From 5b7ccf7e5d839402739d71a07f9f923bf0fbbaff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 21 Mar 2026 17:48:21 +0100
Subject: [PATCH 01/11] feat: add gesture telemetry recording overlays

---
 .../RecordingScripts/recording-overlay.swift  | 546 ++++++++++++++
 .../RecordingScripts/recording-trim.swift     | 137 ++++
 .../__tests__/recording-gestures.test.ts      | 187 +++++
 src/daemon/__tests__/session-store.test.ts    |  24 +
 .../handlers/__tests__/interaction.test.ts    | 121 +++-
 .../handlers/__tests__/record-trace.test.ts   | 297 +++++++-
 .../__tests__/session-replay-script.test.ts   |  24 +-
 src/daemon/handlers/__tests__/session.test.ts |   3 +
 src/daemon/handlers/interaction.ts            | 572 ++++++++++++++-
 src/daemon/handlers/record-trace-android.ts   | 456 ++++++++++++
 src/daemon/handlers/record-trace-recording.ts | 665 ++++++++++++++++++
 src/daemon/handlers/record-trace.ts           | 422 +----------
 src/daemon/handlers/session-replay-script.ts  |  38 +
 src/daemon/recording-gestures.ts              | 539 ++++++++++++++
 src/daemon/recording-telemetry.ts             |  56 ++
 src/daemon/recording-timing.ts                |  37 +
 src/daemon/request-router.ts                  |  21 +
 src/daemon/session-store.ts                   |  20 +
 src/daemon/types.ts                           |  69 +-
 src/platforms/ios/recording-overlay.ts        | 125 ++++
 src/utils/__tests__/args.test.ts              |  16 +
 src/utils/command-schema.ts                   |  12 +-
 src/utils/video.ts                            |  83 +++
 23 files changed, 3974 insertions(+), 496 deletions(-)
 create mode 100644 ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
 create mode 100644 ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
 create mode 100644 src/daemon/__tests__/recording-gestures.test.ts
 create mode 100644 src/daemon/handlers/record-trace-android.ts
 create mode 100644 src/daemon/handlers/record-trace-recording.ts
 create mode 100644 src/daemon/recording-gestures.ts
 create mode 100644 src/daemon/recording-telemetry.ts
 create mode 100644 src/daemon/recording-timing.ts
 create mode 100644 src/platforms/ios/recording-overlay.ts
 create mode 100644 src/utils/video.ts

diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
new file mode 100644
index 000000000..698ecd07f
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -0,0 +1,546 @@
+import AppKit
+import AVFoundation
+import Foundation
+import QuartzCore
+
+let touchDotRadius: CGFloat = 30
+let touchDotColor = NSColor(calibratedRed: 0.20, green: 0.63, blue: 0.98, alpha: 0.48).cgColor
+let touchDotBorderColor = NSColor(calibratedRed: 0.94, green: 0.98, blue: 1.0, alpha: 0.68).cgColor
+let minimumTapVisibility: CFTimeInterval = 0.45
+let minimumSwipeVisibility: CFTimeInterval = 0.5
+let minimumPinchVisibility: CFTimeInterval = 0.5
+let swipeVisibilityTail: CFTimeInterval = 0.16
+
+struct GestureEnvelope: Decodable {
+  let events: [GestureEvent]
+}
+
+struct GestureEvent: Decodable {
+  let kind: String
+  let tMs: Double
+  let x: Double
+  let y: Double
+  let x2: Double?
+  let y2: Double?
+  let referenceWidth: Double?
+  let referenceHeight: Double?
+  let durationMs: Double?
+  let scale: Double?
+  let contentDirection: String?
+  let edge: String?
+}
+
+enum OverlayError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case missingVideoTrack
+  case exportFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .exportFailed(let message):
+      return message
+    }
+  }
+}
+
+do {
+  try run()
+} catch {
+  fputs("recording-overlay: \(error)\n", stderr)
+  exit(1)
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let parsedArgs = try parseArguments(arguments)
+  let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
+  let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
+  let eventsURL = URL(fileURLWithPath: parsedArgs.eventsPath)
+
+  if FileManager.default.fileExists(atPath: outputURL.path) {
+    try FileManager.default.removeItem(at: outputURL)
+  }
+
+  let payload = try Data(contentsOf: eventsURL)
+  let envelope = try JSONDecoder().decode(GestureEnvelope.self, from: payload)
+
+  if envelope.events.isEmpty {
+    try FileManager.default.copyItem(at: inputURL, to: outputURL)
+    return
+  }
+
+  let asset = AVURLAsset(url: inputURL)
+  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
+    throw OverlayError.missingVideoTrack
+  }
+
+  let composition = AVMutableComposition()
+  guard let compositionVideoTrack = composition.addMutableTrack(
+    withMediaType: .video,
+    preferredTrackID: kCMPersistentTrackID_Invalid
+  ) else {
+    throw OverlayError.exportFailed("Failed to create composition video track.")
+  }
+
+  let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
+  try compositionVideoTrack.insertTimeRange(fullRange, of: sourceVideoTrack, at: .zero)
+
+  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
+     let compositionAudioTrack = composition.addMutableTrack(
+       withMediaType: .audio,
+       preferredTrackID: kCMPersistentTrackID_Invalid
+     ) {
+    try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
+  }
+
+  let renderSize = resolvedRenderSize(for: sourceVideoTrack)
+  let videoComposition = AVMutableVideoComposition()
+  videoComposition.renderSize = renderSize
+  videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
+
+  let instruction = AVMutableVideoCompositionInstruction()
+  instruction.timeRange = fullRange
+  let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
+  layerInstruction.setTransform(sourceVideoTrack.preferredTransform, at: .zero)
+  instruction.layerInstructions = [layerInstruction]
+  videoComposition.instructions = [instruction]
+
+  let parentLayer = CALayer()
+  parentLayer.frame = CGRect(origin: .zero, size: renderSize)
+  parentLayer.masksToBounds = true
+
+  let videoLayer = CALayer()
+  videoLayer.frame = parentLayer.frame
+  parentLayer.addSublayer(videoLayer)
+
+  let overlayLayer = CALayer()
+  overlayLayer.frame = parentLayer.frame
+  parentLayer.addSublayer(overlayLayer)
+
+  for event in envelope.events {
+    switch event.kind {
+    case "tap":
+      addTapLayer(event: event, renderSize: renderSize, to: overlayLayer)
+    case "longpress":
+      addLongPressLayer(event: event, renderSize: renderSize, to: overlayLayer)
+    case "swipe":
+      addSwipeLayers(event: event, renderSize: renderSize, to: overlayLayer)
+    case "scroll":
+      addScrollLayers(event: event, renderSize: renderSize, to: overlayLayer)
+    case "back-swipe":
+      addBackSwipeLayers(event: event, renderSize: renderSize, to: overlayLayer)
+    case "pinch":
+      addPinchLayers(event: event, renderSize: renderSize, to: overlayLayer)
+    default:
+      continue
+    }
+  }
+
+  videoComposition.animationTool = AVVideoCompositionCoreAnimationTool(
+    postProcessingAsVideoLayer: videoLayer,
+    in: parentLayer
+  )
+
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+    throw OverlayError.exportFailed("Failed to create export session.")
+  }
+
+  exporter.outputURL = outputURL
+  exporter.outputFileType = .mp4
+  exporter.videoComposition = videoComposition
+  exporter.shouldOptimizeForNetworkUse = true
+
+  let semaphore = DispatchSemaphore(value: 0)
+  exporter.exportAsynchronously {
+    semaphore.signal()
+  }
+  _ = semaphore.wait(timeout: .now() + 120)
+
+  if exporter.status != .completed {
+    throw OverlayError.exportFailed(exporter.error?.localizedDescription ?? "Touch overlay export failed.")
+  }
+}
+
+func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, eventsPath: String) {
+  var inputPath: String?
+  var outputPath: String?
+  var eventsPath: String?
+  var index = 0
+
+  while index < arguments.count {
+    let argument = arguments[index]
+    let nextIndex = index + 1
+    switch argument {
+    case "--input":
+      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--input requires a value") }
+      inputPath = arguments[nextIndex]
+      index += 2
+    case "--output":
+      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--output requires a value") }
+      outputPath = arguments[nextIndex]
+      index += 2
+    case "--events":
+      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--events requires a value") }
+      eventsPath = arguments[nextIndex]
+      index += 2
+    default:
+      throw OverlayError.invalidArgs("Unknown argument: \(argument)")
+    }
+  }
+
+  guard let inputPath, let outputPath, let eventsPath else {
+    throw OverlayError.invalidArgs("Usage: recording-overlay.swift --input <video> --output <video> --events <json>")
+  }
+  return (inputPath, outputPath, eventsPath)
+}
+
+func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
+  let transformed = track.naturalSize.applying(track.preferredTransform)
+  return CGSize(width: abs(transformed.width), height: abs(transformed.height))
+}
+
+func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
+  let minFrameDuration = track.minFrameDuration
+  if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
+    return minFrameDuration
+  }
+
+  let nominalFrameRate = track.nominalFrameRate
+  if nominalFrameRate > 0 {
+    let timescale = Int32(max(1, round(nominalFrameRate)))
+    return CMTime(value: 1, timescale: timescale)
+  }
+
+  return CMTime(value: 1, timescale: 60)
+}
+
+func overlayPoint(event: GestureEvent, x: Double, y: Double, renderSize: CGSize) -> CGPoint {
+  let scaleX = scaledAxis(renderSize: renderSize.width, referenceSize: event.referenceWidth)
+  let scaleY = scaledAxis(renderSize: renderSize.height, referenceSize: event.referenceHeight)
+  let scaledX = x * scaleX
+  let scaledY = y * scaleY
+  return CGPoint(x: scaledX, y: renderSize.height - scaledY)
+}
+
+func scaledAxis(renderSize: CGFloat, referenceSize: Double?) -> Double {
+  guard let referenceSize, referenceSize > 0 else { return 1.0 }
+  return Double(renderSize) / referenceSize
+}
+
+func addTapLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  let layer = makeTouchDotLayer(center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize))
+  overlayLayer.addSublayer(layer)
+
+  let opacity = CAKeyframeAnimation(keyPath: "opacity")
+  opacity.values = [0.0, 0.98, 0.98, 0.0]
+  opacity.keyTimes = [0.0, 0.08, 0.8, 1.0]
+
+  let scale = CAKeyframeAnimation(keyPath: "transform.scale")
+  scale.values = [0.84, 1.0, 1.0]
+  scale.keyTimes = [0.0, 0.22, 1.0]
+
+  let group = CAAnimationGroup()
+  group.animations = [opacity, scale]
+  group.duration = minimumTapVisibility
+  group.beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  layer.add(group, forKey: "tap")
+}
+
+func addLongPressLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  let duration = max(0.75, (event.durationMs ?? 800) / 1000.0)
+  let layer = makeTouchDotLayer(center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize))
+  overlayLayer.addSublayer(layer)
+
+  let opacity = CAKeyframeAnimation(keyPath: "opacity")
+  opacity.values = [0.0, 0.98, 0.98, 0.0]
+  opacity.keyTimes = [0.0, 0.08, 0.92, 1.0]
+
+  let scale = CAKeyframeAnimation(keyPath: "transform.scale")
+  scale.values = [0.84, 1.0, 1.0]
+  scale.keyTimes = [0.0, 0.15, 1.0]
+
+  let group = CAAnimationGroup()
+  group.animations = [opacity, scale]
+  group.duration = duration
+  group.beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  layer.add(group, forKey: "longpress")
+}
+
+func addSwipeLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  addTrailLayers(event: event, renderSize: renderSize, to: overlayLayer, style: .swipe)
+}
+
+func addScrollLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  addTrailLayers(event: event, renderSize: renderSize, to: overlayLayer, style: .scroll)
+}
+
+func addBackSwipeLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  addTrailLayers(event: event, renderSize: renderSize, to: overlayLayer, style: .backSwipe)
+}
+
+enum TrailStyle: Equatable {
+  case swipe
+  case scroll
+  case backSwipe
+}
+
+func addTrailLayers(
+  event: GestureEvent,
+  renderSize: CGSize,
+  to overlayLayer: CALayer,
+  style: TrailStyle
+) {
+  guard let x2 = event.x2, let y2 = event.y2 else { return }
+  let startPoint = overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize)
+  let endPoint = overlayPoint(event: event, x: x2, y: y2, renderSize: renderSize)
+  let duration = max(0.1, (event.durationMs ?? 250) / 1000.0)
+  let visibleDuration = max(minimumSwipeVisibility, duration + trailTail(style: style))
+  let beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+
+  let pathLayer = CAShapeLayer()
+  pathLayer.frame = overlayLayer.bounds
+  pathLayer.strokeEnd = 1.0
+  pathLayer.path = {
+    let path = CGMutablePath()
+    path.move(to: startPoint)
+    path.addLine(to: endPoint)
+    return path
+  }()
+  pathLayer.strokeColor = trailColor(style: style)
+  pathLayer.lineWidth = trailLineWidth(style: style)
+  pathLayer.lineCap = .round
+  pathLayer.fillColor = nil
+  pathLayer.opacity = 0
+  overlayLayer.addSublayer(pathLayer)
+
+  let stroke = CABasicAnimation(keyPath: "strokeEnd")
+  stroke.fromValue = 0.0
+  stroke.toValue = 1.0
+
+  let strokeOpacity = CAKeyframeAnimation(keyPath: "opacity")
+  strokeOpacity.values = trailOpacityValues(style: style)
+  strokeOpacity.keyTimes = trailOpacityKeyTimes()
+
+  let strokeGroup = CAAnimationGroup()
+  strokeGroup.animations = [stroke, strokeOpacity]
+  strokeGroup.duration = visibleDuration
+  strokeGroup.beginTime = beginTime
+  strokeGroup.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+  strokeGroup.fillMode = .both
+  strokeGroup.isRemovedOnCompletion = false
+  pathLayer.add(strokeGroup, forKey: "stroke")
+
+  let dotLayer = makeTouchDotLayer(center: startPoint)
+  dotLayer.backgroundColor = trailColor(style: style)
+  dotLayer.borderColor = trailBorderColor(style: style)
+  dotLayer.position = endPoint
+  overlayLayer.addSublayer(dotLayer)
+
+  let position = CABasicAnimation(keyPath: "position")
+  position.fromValue = NSValue(point: startPoint)
+  position.toValue = NSValue(point: endPoint)
+  position.duration = duration
+
+  let opacity = CAKeyframeAnimation(keyPath: "opacity")
+  opacity.values = dotOpacityValues(style: style)
+  opacity.keyTimes = trailOpacityKeyTimes()
+
+  let group = CAAnimationGroup()
+  group.animations = [position, opacity]
+  group.duration = visibleDuration
+  group.beginTime = beginTime
+  group.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  dotLayer.add(group, forKey: "swipe-dot")
+
+  if style == .backSwipe {
+    addBackSwipeEdgeHint(
+      event: event,
+      renderSize: renderSize,
+      beginTime: beginTime,
+      visibleDuration: visibleDuration,
+      to: overlayLayer
+    )
+  }
+}
+
+func addPinchDot(
+  overlayLayer: CALayer,
+  start: CGPoint,
+  end: CGPoint,
+  beginTime: CFTimeInterval,
+  duration: CFTimeInterval
+) {
+  let dotLayer = makeTouchDotLayer(center: start)
+  overlayLayer.addSublayer(dotLayer)
+
+  let position = CABasicAnimation(keyPath: "position")
+  position.fromValue = NSValue(point: start)
+  position.toValue = NSValue(point: end)
+  position.duration = duration
+
+  let opacity = CAKeyframeAnimation(keyPath: "opacity")
+  opacity.values = [0.0, 1.0, 1.0, 0.0]
+  opacity.keyTimes = [0.0, 0.1, 0.82, 1.0]
+
+  let group = CAAnimationGroup()
+  group.animations = [position, opacity]
+  group.duration = duration
+  group.beginTime = beginTime
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  dotLayer.add(group, forKey: "pinch")
+}
+
+func addPinchLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
+  let duration = max(minimumPinchVisibility, (event.durationMs ?? 280) / 1000.0)
+  let beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  let startOffset: CGFloat = 28
+  let scale = max(0.2, min(event.scale ?? 1.0, 3.0))
+  let endOffset = scale >= 1.0 ? startOffset * CGFloat(min(scale, 2.0)) : startOffset * CGFloat(max(scale, 0.5))
+  let startLeft = overlayPoint(event: event, x: event.x - Double(startOffset), y: event.y, renderSize: renderSize)
+  let startRight = overlayPoint(event: event, x: event.x + Double(startOffset), y: event.y, renderSize: renderSize)
+  let endLeft = overlayPoint(event: event, x: event.x - Double(endOffset), y: event.y, renderSize: renderSize)
+  let endRight = overlayPoint(event: event, x: event.x + Double(endOffset), y: event.y, renderSize: renderSize)
+
+  addPinchDot(
+    overlayLayer: overlayLayer,
+    start: startLeft,
+    end: endLeft,
+    beginTime: beginTime,
+    duration: duration
+  )
+  addPinchDot(
+    overlayLayer: overlayLayer,
+    start: startRight,
+    end: endRight,
+    beginTime: beginTime,
+    duration: duration
+  )
+}
+
+func makeTouchDotLayer(center: CGPoint) -> CALayer {
+  let layer = CALayer()
+  layer.bounds = CGRect(x: 0, y: 0, width: touchDotRadius * 2, height: touchDotRadius * 2)
+  layer.position = center
+  layer.cornerRadius = touchDotRadius
+  layer.backgroundColor = touchDotColor
+  layer.borderWidth = 2
+  layer.borderColor = touchDotBorderColor
+  layer.shadowColor = NSColor(calibratedRed: 0.08, green: 0.20, blue: 0.36, alpha: 1.0).cgColor
+  layer.shadowOpacity = 0.18
+  layer.shadowRadius = 4
+  layer.opacity = 0
+  return layer
+}
+
+func trailTail(style: TrailStyle) -> CFTimeInterval {
+  switch style {
+  case .swipe:
+    return swipeVisibilityTail
+  case .scroll:
+    return 0.08
+  case .backSwipe:
+    return 0.12
+  }
+}
+
+func trailLineWidth(style: TrailStyle) -> CGFloat {
+  switch style {
+  case .swipe:
+    return 4
+  case .scroll:
+    return 5
+  case .backSwipe:
+    return 6
+  }
+}
+
+func trailColor(style: TrailStyle) -> CGColor {
+  switch style {
+  case .swipe:
+    return touchDotColor
+  case .scroll:
+    return NSColor(calibratedRed: 0.16, green: 0.74, blue: 0.88, alpha: 0.34).cgColor
+  case .backSwipe:
+    return NSColor(calibratedRed: 0.24, green: 0.69, blue: 1.0, alpha: 0.55).cgColor
+  }
+}
+
+func trailBorderColor(style: TrailStyle) -> CGColor {
+  switch style {
+  case .swipe:
+    return touchDotBorderColor
+  case .scroll:
+    return NSColor(calibratedRed: 0.92, green: 1.0, blue: 1.0, alpha: 0.48).cgColor
+  case .backSwipe:
+    return NSColor(calibratedRed: 0.94, green: 0.98, blue: 1.0, alpha: 0.8).cgColor
+  }
+}
+
+func trailOpacityValues(style: TrailStyle) -> [NSNumber] {
+  switch style {
+  case .swipe:
+    return [0.0, 0.9, 0.35, 0.0]
+  case .scroll:
+    return [0.0, 0.5, 0.18, 0.0]
+  case .backSwipe:
+    return [0.0, 1.0, 0.45, 0.0]
+  }
+}
+
+func dotOpacityValues(style: TrailStyle) -> [NSNumber] {
+  switch style {
+  case .swipe:
+    return [0.0, 1.0, 0.92, 0.0]
+  case .scroll:
+    return [0.0, 0.72, 0.4, 0.0]
+  case .backSwipe:
+    return [0.0, 1.0, 0.9, 0.0]
+  }
+}
+
+func trailOpacityKeyTimes() -> [NSNumber] {
+  return [0.0, 0.08, 0.62, 1.0]
+}
+
+func addBackSwipeEdgeHint(
+  event: GestureEvent,
+  renderSize: CGSize,
+  beginTime: CFTimeInterval,
+  visibleDuration: CFTimeInterval,
+  to overlayLayer: CALayer
+) {
+  let edge = (event.edge ?? "left").lowercased()
+  let hintLayer = CALayer()
+  let width: CGFloat = 10
+  let height: CGFloat = min(renderSize.height * 0.3, 320)
+  let y = (renderSize.height - height) / 2
+  let x: CGFloat = edge == "right" ? renderSize.width - width : 0
+  hintLayer.frame = CGRect(x: x, y: y, width: width, height: height)
+  hintLayer.backgroundColor = NSColor(calibratedRed: 0.24, green: 0.69, blue: 1.0, alpha: 0.22).cgColor
+  hintLayer.cornerRadius = width / 2
+  hintLayer.opacity = 0
+  overlayLayer.addSublayer(hintLayer)
+
+  let opacity = CAKeyframeAnimation(keyPath: "opacity")
+  opacity.values = [0.0, 0.9, 0.0]
+  opacity.keyTimes = [0.0, 0.2, 1.0]
+
+  let group = CAAnimationGroup()
+  group.animations = [opacity]
+  group.duration = visibleDuration
+  group.beginTime = beginTime
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  hintLayer.add(group, forKey: "back-swipe-edge")
+}
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
new file mode 100644
index 000000000..16c1ab45e
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
@@ -0,0 +1,137 @@
+import AVFoundation
+import Foundation
+
+enum TrimError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case invalidTrimRange
+  case missingVideoTrack
+  case exportFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .invalidTrimRange:
+      return "Trim start must be before the end of the recording."
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .exportFailed(let message):
+      return message
+    }
+  }
+}
+
+do {
+  try run()
+} catch {
+  fputs("recording-trim: \(error)\n", stderr)
+  exit(1)
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let parsedArgs = try parseArguments(arguments)
+  let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
+  let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
+
+  if FileManager.default.fileExists(atPath: outputURL.path) {
+    try FileManager.default.removeItem(at: outputURL)
+  }
+
+  let asset = AVURLAsset(url: inputURL)
+  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
+    throw TrimError.missingVideoTrack
+  }
+
+  let trimStart = CMTime(seconds: parsedArgs.trimStartMs / 1000.0, preferredTimescale: 600)
+  guard CMTimeCompare(trimStart, asset.duration) < 0 else {
+    throw TrimError.invalidTrimRange
+  }
+
+  let trimmedDuration = CMTimeSubtract(asset.duration, trimStart)
+  guard CMTimeCompare(trimmedDuration, .zero) > 0 else {
+    throw TrimError.invalidTrimRange
+  }
+
+  let composition = AVMutableComposition()
+  let trimmedRange = CMTimeRange(start: trimStart, duration: trimmedDuration)
+
+  guard let compositionVideoTrack = composition.addMutableTrack(
+    withMediaType: .video,
+    preferredTrackID: kCMPersistentTrackID_Invalid
+  ) else {
+    throw TrimError.exportFailed("Failed to create composition video track.")
+  }
+  try compositionVideoTrack.insertTimeRange(trimmedRange, of: sourceVideoTrack, at: .zero)
+  compositionVideoTrack.preferredTransform = sourceVideoTrack.preferredTransform
+
+  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
+     let compositionAudioTrack = composition.addMutableTrack(
+       withMediaType: .audio,
+       preferredTrackID: kCMPersistentTrackID_Invalid
+     ) {
+    try? compositionAudioTrack.insertTimeRange(trimmedRange, of: sourceAudioTrack, at: .zero)
+  }
+
+  let presetName = AVAssetExportSession.exportPresets(compatibleWith: composition)
+    .contains(AVAssetExportPresetPassthrough)
+    ? AVAssetExportPresetPassthrough
+    : AVAssetExportPresetHighestQuality
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
+    throw TrimError.exportFailed("Failed to create export session.")
+  }
+
+  exporter.outputURL = outputURL
+  exporter.outputFileType = .mp4
+  exporter.shouldOptimizeForNetworkUse = true
+
+  let semaphore = DispatchSemaphore(value: 0)
+  exporter.exportAsynchronously {
+    semaphore.signal()
+  }
+  _ = semaphore.wait(timeout: .now() + 120)
+
+  if exporter.status != .completed {
+    throw TrimError.exportFailed(exporter.error?.localizedDescription ?? "Trim export failed.")
+  }
+}
+
+func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, trimStartMs: Double) {
+  var inputPath: String?
+  var outputPath: String?
+  var trimStartMs: Double?
+  var index = 0
+
+  while index < arguments.count {
+    let argument = arguments[index]
+    let nextIndex = index + 1
+    switch argument {
+    case "--input":
+      guard nextIndex < arguments.count else { throw TrimError.invalidArgs("--input requires a value") }
+      inputPath = arguments[nextIndex]
+      index += 2
+    case "--output":
+      guard nextIndex < arguments.count else { throw TrimError.invalidArgs("--output requires a value") }
+      outputPath = arguments[nextIndex]
+      index += 2
+    case "--trim-start-ms":
+      guard nextIndex < arguments.count else {
+        throw TrimError.invalidArgs("--trim-start-ms requires a value")
+      }
+      guard let parsed = Double(arguments[nextIndex]), parsed >= 0 else {
+        throw TrimError.invalidArgs("--trim-start-ms must be a non-negative number")
+      }
+      trimStartMs = parsed
+      index += 2
+    default:
+      throw TrimError.invalidArgs("Unknown argument: \(argument)")
+    }
+  }
+
+  guard let inputPath, let outputPath, let trimStartMs else {
+    throw TrimError.invalidArgs(
+      "Usage: recording-trim.swift --input <video> --output <video> --trim-start-ms <ms>"
+    )
+  }
+  return (inputPath, outputPath, trimStartMs)
+}
diff --git a/src/daemon/__tests__/recording-gestures.test.ts b/src/daemon/__tests__/recording-gestures.test.ts
new file mode 100644
index 000000000..c2701336d
--- /dev/null
+++ b/src/daemon/__tests__/recording-gestures.test.ts
@@ -0,0 +1,187 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { SessionState } from '../types.ts';
+import {
+  augmentTouchVisualizationResult,
+  recordTouchVisualizationEvent,
+} from '../recording-gestures.ts';
+import { attachRefs } from '../../utils/snapshot.ts';
+
+function makeSession(): SessionState {
+  return {
+    name: 'default',
+    device: {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    },
+    createdAt: Date.now(),
+    actions: [],
+    snapshot: {
+      nodes: attachRefs([
+        {
+          index: 0,
+          type: 'Application',
+          rect: { x: 0, y: 0, width: 402, height: 874 },
+        },
+      ]),
+      createdAt: Date.now(),
+      backend: 'xctest',
+    },
+    recording: {
+      platform: 'ios',
+      outPath: '/tmp/demo.mp4',
+      startedAt: 1_000,
+      showTouches: true,
+      gestureEvents: [],
+      child: { kill: () => {} } as any,
+      wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+    },
+  };
+}
+
+test('scroll records a semantic scroll gesture for visualization telemetry', () => {
+  const session = makeSession();
+  const result = augmentTouchVisualizationResult(session, 'scroll', ['down'], {
+    direction: 'down',
+  });
+
+  recordTouchVisualizationEvent(session, 'scroll', ['down'], result, {}, 1_500, 1_920);
+
+  assert.equal(session.recording?.gestureEvents.length, 1);
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'scroll');
+  if (!event || event.kind !== 'scroll') return;
+
+  assert.equal(event.tMs, 500);
+  assert.equal(event.referenceWidth, 402);
+  assert.equal(event.referenceHeight, 874);
+  assert.equal(event.x, 201);
+  assert.equal(event.y, 612);
+  assert.equal(event.x2, 201);
+  assert.equal(event.y2, 262);
+  assert.equal(event.durationMs, 250);
+  assert.equal(event.contentDirection, 'down');
+});
+
+test('scroll amount scales swipe travel for visualization', () => {
+  const session = makeSession();
+  const result = augmentTouchVisualizationResult(session, 'scroll', ['right', '0.6'], {
+    direction: 'right',
+    amount: 0.6,
+  });
+
+  recordTouchVisualizationEvent(session, 'scroll', ['right', '0.6'], result, {}, 1_500);
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'scroll');
+  if (!event || event.kind !== 'scroll') return;
+
+  assert.equal(event.x, 322);
+  assert.equal(event.x2, 80);
+  assert.equal(event.y, 437);
+  assert.equal(event.y2, 437);
+  assert.equal(event.amount, 0.6);
+});
+
+test('scroll augmentation falls back to normalized geometry without a snapshot', () => {
+  const session = makeSession();
+  session.snapshot = undefined;
+
+  const augmented = augmentTouchVisualizationResult(session, 'scroll', ['down'], {
+    direction: 'down',
+  });
+
+  assert.ok(augmented);
+  assert.equal((augmented as Record<string, unknown>).referenceWidth, 1000);
+  assert.equal((augmented as Record<string, unknown>).referenceHeight, 1000);
+});
+
+test('gesture recording prefers native runner timing when available', () => {
+  const session = makeSession();
+  session.recording = {
+    platform: 'ios-device-runner',
+    outPath: '/tmp/demo.mp4',
+    remotePath: 'tmp/demo.mp4',
+    startedAt: 1_000,
+    showTouches: true,
+    gestureEvents: [],
+    runnerStartedAtUptimeMs: 5_000,
+  };
+
+  recordTouchVisualizationEvent(
+    session,
+    'press',
+    ['201', '437'],
+    { x: 201, y: 437, gestureStartUptimeMs: 5_180 },
+    {},
+    9_999,
+  );
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'tap');
+  assert.equal(event?.tMs, 180);
+});
+
+test('swipe visualization prefers native gesture duration when available', () => {
+  const session = makeSession();
+
+  recordTouchVisualizationEvent(
+    session,
+    'swipe',
+    ['10', '20', '110', '220', '300'],
+    {
+      x1: 10,
+      y1: 20,
+      x2: 110,
+      y2: 220,
+      durationMs: 300,
+      gestureStartUptimeMs: 5_000,
+      gestureEndUptimeMs: 5_780,
+    },
+    {},
+    2_000,
+    2_300,
+  );
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'swipe');
+  if (!event || event.kind !== 'swipe') return;
+
+  assert.equal(event.durationMs, 780);
+});
+
+test('telemetry is still captured when touch overlays are hidden', () => {
+  const session = makeSession();
+  if (session.recording) {
+    session.recording.showTouches = false;
+  }
+
+  recordTouchVisualizationEvent(session, 'press', ['100', '200'], { x: 100, y: 200 }, {}, 1_500);
+
+  assert.equal(session.recording?.gestureEvents.length, 1);
+  assert.equal(session.recording?.gestureEvents[0]?.kind, 'tap');
+});
+
+test('edge swipe is classified as a back-swipe telemetry event', () => {
+  const session = makeSession();
+
+  recordTouchVisualizationEvent(
+    session,
+    'swipe',
+    ['10', '400', '180', '400', '320'],
+    { x1: 10, y1: 400, x2: 180, y2: 400, durationMs: 320 },
+    {},
+    1_500,
+    1_900,
+  );
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'back-swipe');
+  if (!event || event.kind !== 'back-swipe') return;
+
+  assert.equal(event.edge, 'left');
+  assert.equal(event.durationMs, 320);
+});
diff --git a/src/daemon/__tests__/session-store.test.ts b/src/daemon/__tests__/session-store.test.ts
index e34a6ba69..8b7c806a7 100644
--- a/src/daemon/__tests__/session-store.test.ts
+++ b/src/daemon/__tests__/session-store.test.ts
@@ -154,6 +154,30 @@ test('writeSessionLog persists open --relaunch in script output', () => {
   assert.match(script, /open "Settings" --relaunch/);
 });
 
+test('writeSessionLog persists record --hide-touches flags in script output', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-record-'));
+  const store = new SessionStore(root);
+  const session = makeSession('default');
+  store.recordAction(session, {
+    command: 'open',
+    positionals: ['Settings'],
+    flags: { platform: 'ios', saveScript: true },
+    result: {},
+  });
+  store.recordAction(session, {
+    command: 'record',
+    positionals: ['start', './capture.mp4'],
+    flags: { platform: 'ios', fps: 30, hideTouches: true },
+    result: { action: 'start', showTouches: false },
+  });
+
+  store.writeSessionLog(session);
+  const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
+  assert.ok(scriptFile);
+  const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
+  assert.match(script, /record start "\.\/capture\.mp4" --fps 30 --hide-touches/);
+});
+
 test('writeSessionLog persists inline open runtime hints in script output', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-open-runtime-'));
   const store = new SessionStore(root);
diff --git a/src/daemon/handlers/__tests__/interaction.test.ts b/src/daemon/handlers/__tests__/interaction.test.ts
index 37fb9bfb0..fad34adb1 100644
--- a/src/daemon/handlers/__tests__/interaction.test.ts
+++ b/src/daemon/handlers/__tests__/interaction.test.ts
@@ -60,7 +60,8 @@ test('unsupportedRefSnapshotFlags returns empty when no ref-unsupported flags ar
 test('press coordinates dispatches press and records as press', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';
-  sessionStore.set(sessionName, makeSession(sessionName));
+  const storedSession = makeSession(sessionName);
+  sessionStore.set(sessionName, storedSession);
 
   const dispatchCalls: Array<{
     command: string;
@@ -104,6 +105,124 @@ test('press coordinates dispatches press and records as press', async () => {
   assert.deepEqual(session?.actions[0]?.positionals, ['100', '200']);
 });
 
+test('press coordinates appends touch-visualization events while recording', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  const session = makeSession(sessionName);
+  session.snapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        type: 'XCUIElementTypeApplication',
+        rect: { x: 0, y: 0, width: 402, height: 874 },
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'xctest',
+  };
+  session.recording = {
+    platform: 'ios',
+    outPath: '/tmp/demo.mp4',
+    startedAt: Date.now() - 1_000,
+    showTouches: true,
+    gestureEvents: [],
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  };
+  sessionStore.set(sessionName, session);
+
+  const response = await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['100', '200'],
+      flags: { count: 2, intervalMs: 150, doubleTap: true },
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch: async () => ({ ok: true }),
+  });
+
+  assert.equal(response?.ok, true);
+  const recorded = sessionStore.get(sessionName)?.recording;
+  assert.ok(recorded);
+  assert.equal(recorded?.gestureEvents.length, 4);
+  assert.equal(recorded?.gestureEvents[0]?.kind, 'tap');
+  assert.equal(recorded?.gestureEvents[0]?.x, 100);
+  assert.equal(recorded?.gestureEvents[0]?.y, 200);
+  assert.equal(recorded?.gestureEvents[0]?.referenceWidth, 402);
+  assert.equal(recorded?.gestureEvents[0]?.referenceHeight, 874);
+});
+
+test('press @ref preserves native timing in recorded result and touch visualization', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  const session = makeSession(sessionName);
+  session.snapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        type: 'XCUIElementTypeButton',
+        label: 'Continue',
+        identifier: 'auth_continue',
+        rect: { x: 10, y: 20, width: 100, height: 40 },
+        enabled: true,
+        hittable: true,
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'xctest',
+  };
+  session.recording = {
+    platform: 'ios',
+    outPath: '/tmp/demo.mp4',
+    startedAt: 1_000,
+    showTouches: true,
+    gestureEvents: [],
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  };
+  sessionStore.set(sessionName, session);
+
+  const originalNow = Date.now;
+  let now = 1_500;
+  Date.now = () => now;
+
+  try {
+    const response = await handleInteractionCommands({
+      req: {
+        token: 't',
+        session: sessionName,
+        command: 'press',
+        positionals: ['@e1'],
+        flags: {},
+      },
+      sessionName,
+      sessionStore,
+      contextFromFlags,
+      dispatch: async () => {
+        now = 1_650;
+        return {
+          gestureStartUptimeMs: 5_100,
+          gestureEndUptimeMs: 5_180,
+        };
+      },
+    });
+
+    assert.equal(response?.ok, true);
+  } finally {
+    Date.now = originalNow;
+  }
+
+  const stored = sessionStore.get(sessionName);
+  const result = (stored?.actions[0]?.result ?? {}) as Record<string, unknown>;
+  assert.equal(result.gestureStartUptimeMs, 5_100);
+  assert.equal(result.gestureEndUptimeMs, 5_180);
+  assert.equal(stored?.recording?.gestureEvents[0]?.tMs, 500);
+});
+
 test('press @ref resolves snapshot node and records press action', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index e79a75f12..bae1c9f5a 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -68,7 +68,7 @@ async function runRecordCommand(params: {
   deps: RecordTraceDeps;
   logPath?: string;
   cwd?: string;
-  flags?: { fps?: number };
+  flags?: { fps?: number; hideTouches?: boolean };
 }) {
   return handleRecordTraceCommands({
     req: {
@@ -103,6 +103,9 @@ function makeRunnerRecordingDeps(
       logPath: options?.logPath,
       traceLogPath: options?.traceLogPath,
     });
+    if (command.command === 'recordStart') {
+      return { recorderStartUptimeMs: 12_345, targetAppReadyUptimeMs: 15_678 };
+    }
     return {};
   };
   return {
@@ -114,6 +117,27 @@ function makeRunnerRecordingDeps(
       throw new Error('runCmdBackground should not be used for runner-backed recording');
     },
     runIosRunnerCommand,
+    waitForStableFile: async () => {},
+    isPlayableVideo: async () => true,
+    writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+    trimRecordingStart: async () => {},
+    overlayRecordingTouches: async () => {},
+  };
+}
+
+function makeRecordDeps(overrides: Partial<RecordTraceDeps> = {}): RecordTraceDeps {
+  return {
+    runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
+    runCmdBackground: () => {
+      throw new Error('runCmdBackground should not be used in this test');
+    },
+    runIosRunnerCommand: async () => ({}),
+    waitForStableFile: async () => {},
+    isPlayableVideo: async () => true,
+    writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+    trimRecordingStart: async () => {},
+    overlayRecordingTouches: async () => {},
+    ...overrides,
   };
 }
 
@@ -144,6 +168,7 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
   assert.equal(runnerCalls[0]?.appBundleId, 'com.atebits.Tweetie2');
   assert.equal(runnerCalls[0]?.logPath, '/tmp/daemon.log');
   assert.equal(runnerCalls[0]?.traceLogPath, undefined);
+  assert.equal(responseStart?.data?.showTouches, true);
   const startedRecording = sessionStore.get(sessionName)?.recording;
   assert.equal(startedRecording?.platform, 'ios-device-runner');
   const stagedRemotePath =
@@ -151,6 +176,11 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
       ? startedRecording.remotePath
       : undefined;
   assert.match(stagedRemotePath ?? '', /^tmp\/agent-device-recording-\d+\.mp4$/);
+  if (startedRecording?.platform === 'ios-device-runner') {
+    assert.equal(startedRecording.runnerStartedAtUptimeMs, 12_345);
+    assert.equal(startedRecording.targetAppReadyUptimeMs, 15_678);
+    assert.equal(startedRecording.showTouches, true);
+  }
 
   const responseStop = await runRecordCommand({
     sessionStore,
@@ -183,6 +213,11 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
     '--domain-identifier',
     IOS_RUNNER_CONTAINER_BUNDLE_IDS[0] ?? '',
   ]);
+  assert.equal(responseStop?.data?.telemetryPath, `${finalOut}.gesture-telemetry.json`);
+  assert.deepEqual(
+    responseStop?.data?.artifacts?.map((artifact) => artifact.field),
+    ['outPath', 'gestureTelemetry'],
+  );
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
@@ -310,6 +345,11 @@ test('record start rejects invalid fps value', async () => {
       runIosRunnerCommand: async () => {
         throw new Error('runIosRunnerCommand should not be used for invalid args');
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -335,6 +375,11 @@ test('record start on iOS device requires active app session context', async ()
       runIosRunnerCommand: async () => {
         throw new Error('runIosRunnerCommand should not be used without active app context');
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -361,6 +406,11 @@ test('record start returns structured error when iOS runner start fails', async
       runIosRunnerCommand: async () => {
         throw new Error('runner disconnected');
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -395,8 +445,13 @@ test('record start recovers from stale iOS runner recording state', async () =>
             throw new Error('recording already in progress');
           }
         }
-        return {};
+        return { recorderStartUptimeMs: 11_000, targetAppReadyUptimeMs: 12_000 };
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -413,6 +468,9 @@ test('record start does not stop recording owned by another session during desyn
     platform: 'ios-device-runner',
     outPath: '/tmp/owner.mp4',
     remotePath: 'tmp/owner.mp4',
+    startedAt: Date.now(),
+    showTouches: false,
+    gestureEvents: [],
   };
   sessionStore.set(ownerSessionName, ownerSession);
 
@@ -437,6 +495,11 @@ test('record start does not stop recording owned by another session during desyn
         }
         return {};
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -456,6 +519,9 @@ test('record stop clears iOS runner recording state when runner stop fails', asy
       platform: 'ios-device-runner',
       outPath: '/tmp/device.mp4',
       remotePath: 'tmp/device.mp4',
+      startedAt: Date.now(),
+      showTouches: false,
+      gestureEvents: [],
     },
   });
 
@@ -475,6 +541,11 @@ test('record stop clears iOS runner recording state when runner stop fails', asy
       runIosRunnerCommand: async () => {
         throw new Error('runner disconnected');
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -484,6 +555,50 @@ test('record stop clears iOS runner recording state when runner stop fails', asy
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
+test('record stop trims iOS device recordings from target app readiness before overlays', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-trim';
+  sessionStore.set(sessionName, {
+    ...makeIosDeviceSession(sessionName, 'com.atebits.Tweetie2'),
+    recording: {
+      platform: 'ios-device-runner',
+      outPath: '/tmp/device.mp4',
+      remotePath: 'tmp/device.mp4',
+      startedAt: Date.now(),
+      runnerStartedAtUptimeMs: 10_000,
+      targetAppReadyUptimeMs: 13_250,
+      showTouches: true,
+      gestureEvents: [{ kind: 'tap', tMs: 3_600, x: 50, y: 80 }],
+    },
+  });
+
+  const lifecycleCalls: string[] = [];
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps: makeRecordDeps({
+      trimRecordingStart: async ({ videoPath, trimStartMs }) => {
+        lifecycleCalls.push(`trim:${videoPath}:${trimStartMs}`);
+      },
+      writeRecordingTelemetry: ({ videoPath, events }) => {
+        lifecycleCalls.push(`telemetry:${videoPath}:${events.length}`);
+        return `${videoPath}.gesture-telemetry.json`;
+      },
+      overlayRecordingTouches: async ({ videoPath, telemetryPath }) => {
+        lifecycleCalls.push(`overlay:${videoPath}:${telemetryPath}`);
+      },
+    }),
+  });
+
+  assert.equal(response?.ok, true);
+  assert.deepEqual(lifecycleCalls, [
+    'trim:/tmp/device.mp4:3250',
+    'telemetry:/tmp/device.mp4:1',
+    'overlay:/tmp/device.mp4:/tmp/device.mp4.gesture-telemetry.json',
+  ]);
+});
+
 test('record uses simctl recordVideo for iOS simulators', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
@@ -508,7 +623,7 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
       runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
       runCmdBackground: (cmd, args) => {
         assert.equal(cmd, 'xcrun');
-        assert.deepEqual(args.slice(0, 4), ['simctl', 'io', 'sim-1', 'recordVideo']);
+        assert.deepEqual(args.slice(0, 5), ['simctl', 'io', 'sim-1', 'recordVideo', '-f']);
         started = true;
         return {
           child: {
@@ -520,8 +635,12 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
         };
       },
       runIosRunnerCommand: async () => {
-        throw new Error('runner should not be used for iOS simulators');
+        return {};
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -537,9 +656,11 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
       runCmdBackground: () => {
         throw new Error('runCmdBackground should not be called on stop for simulator');
       },
-      runIosRunnerCommand: async () => {
-        throw new Error('runner should not be used for iOS simulators');
-      },
+      runIosRunnerCommand: async () => ({}),
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -547,16 +668,16 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
   assert.equal(stopped, true);
 });
 
-test('record keeps android pull + cleanup flow', async () => {
+test('record start/stop overlays Android gestures by default on devices', async () => {
   const sessionStore = makeSessionStore();
-  const sessionName = 'android';
+  const sessionName = 'android-overlay';
   sessionStore.set(
     sessionName,
     makeSession(sessionName, {
       platform: 'android',
       id: 'emulator-5554',
       name: 'Android',
-      kind: 'emulator',
+      kind: 'device',
       booted: true,
     }),
   );
@@ -566,44 +687,156 @@ test('record keeps android pull + cleanup flow', async () => {
     sessionStore,
     sessionName,
     positionals: ['start', './android.mp4'],
-    deps: {
+    deps: makeRecordDeps({
       runCmd: async (_cmd, args) => {
         adbCalls.push(args);
+        if (
+          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '4321\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      runCmdBackground: (cmd, args) => {
-        assert.equal(cmd, 'adb');
-        assert.deepEqual(args.slice(0, 4), ['-s', 'emulator-5554', 'shell', 'screenrecord']);
-        return {
-          child: { kill: () => {} } as any,
-          wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
-        };
-      },
-      runIosRunnerCommand: async () => {
-        throw new Error('runner should not be used for Android');
-      },
-    },
+    }),
   });
+  const startedRecording = sessionStore.get(sessionName)?.recording;
+  assert.equal(startedRecording?.platform, 'android');
+  startedRecording?.gestureEvents.push({ kind: 'tap', tMs: 120, x: 90, y: 180 });
 
+  const overlayCalls: Array<{ videoPath: string; telemetryPath: string }> = [];
   await runRecordCommand({
     sessionStore,
     sessionName,
     positionals: ['stop'],
-    deps: {
+    deps: makeRecordDeps({
       runCmd: async (_cmd, args) => {
         adbCalls.push(args);
+        if (args.join(' ') === '-s emulator-5554 shell ps -o pid= -p 4321') {
+          return { stdout: '', stderr: '', exitCode: 1 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '2048\n', stderr: '', exitCode: 0 };
+        }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      runCmdBackground: () => {
-        throw new Error('runCmdBackground should not be called on stop for Android');
-      },
-      runIosRunnerCommand: async () => {
-        throw new Error('runner should not be used for Android');
+      overlayRecordingTouches: async ({ videoPath, telemetryPath }) => {
+        overlayCalls.push({ videoPath, telemetryPath });
       },
+    }),
+  });
+
+  assert.ok(adbCalls.some((args) => args.join(' ') === '-s emulator-5554 shell kill -2 4321'));
+  assert.deepEqual(overlayCalls, [
+    {
+      videoPath: path.resolve('./android.mp4'),
+      telemetryPath: `${path.resolve('./android.mp4')}.gesture-telemetry.json`,
     },
+  ]);
+});
+
+test('record start leaves overlays disabled with --hide-touches', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-hide-touches';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    flags: { hideTouches: true },
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        if (
+          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '9999\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
   });
 
-  assert.equal(adbCalls.length, 2);
-  assert.match(adbCalls[0]?.join(' '), /pull/);
-  assert.match(adbCalls[1]?.join(' '), /shell rm -f/);
+  assert.equal(response?.ok, true);
+  assert.equal(response?.data?.showTouches, false);
+  assert.equal(sessionStore.get(sessionName)?.recording?.showTouches, false);
+});
+
+test('record start accepts Android screenrecord before the remote file begins growing', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-running-without-file-growth';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  let psChecks = 0;
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        if (
+          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '5555\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '0\n', stderr: '', exitCode: 0 };
+        }
+        if (command === '-s emulator-5554 shell ps -o pid= -p 5555') {
+          psChecks += 1;
+          return { stdout: '5555\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  assert.equal(response?.ok, true);
+  assert.equal(psChecks >= 2, true);
 });
diff --git a/src/daemon/handlers/__tests__/session-replay-script.test.ts b/src/daemon/handlers/__tests__/session-replay-script.test.ts
index 07e2a4e41..6a278f33c 100644
--- a/src/daemon/handlers/__tests__/session-replay-script.test.ts
+++ b/src/daemon/handlers/__tests__/session-replay-script.test.ts
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { writeReplayScript } from '../session-replay-script.ts';
+import { parseReplayScript, writeReplayScript } from '../session-replay-script.ts';
 import type { SessionAction, SessionState } from '../../types.ts';
 
 function makeSession(): SessionState {
@@ -47,3 +47,25 @@ test('writeReplayScript preserves inline open runtime hints', () => {
     /open "Demo" --relaunch --platform android --metro-host 10\.0\.0\.10 --metro-port 8081 --launch-url myapp:\/\/dev/,
   );
 });
+
+test('record replay script round-trips fps and hide-touches flags', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-script-record-'));
+  const replayPath = path.join(root, 'flow.ad');
+  const actions: SessionAction[] = [
+    {
+      ts: Date.now(),
+      command: 'record',
+      positionals: ['start', './capture.mp4'],
+      flags: { fps: 24, hideTouches: true },
+    },
+  ];
+
+  writeReplayScript(replayPath, actions, makeSession());
+  const script = fs.readFileSync(replayPath, 'utf8');
+  assert.match(script, /record start "\.\/capture\.mp4" --fps 24 --hide-touches/);
+
+  const parsed = parseReplayScript(script);
+  assert.deepEqual(parsed[0]?.positionals, ['start', './capture.mp4']);
+  assert.equal(parsed[0]?.flags.fps, 24);
+  assert.equal(parsed[0]?.flags.hideTouches, true);
+});
diff --git a/src/daemon/handlers/__tests__/session.test.ts b/src/daemon/handlers/__tests__/session.test.ts
index 1b027e330..8c6e91b56 100644
--- a/src/daemon/handlers/__tests__/session.test.ts
+++ b/src/daemon/handlers/__tests__/session.test.ts
@@ -2711,6 +2711,9 @@ test('close on iOS session with recording stops runner session before delete', a
       platform: 'ios-device-runner',
       outPath: '/tmp/device-recording.mp4',
       remotePath: 'tmp/device-recording.mp4',
+      startedAt: Date.now(),
+      showTouches: false,
+      gestureEvents: [],
     },
   });
 
diff --git a/src/daemon/handlers/interaction.ts b/src/daemon/handlers/interaction.ts
index c595d12a6..988f7be22 100644
--- a/src/daemon/handlers/interaction.ts
+++ b/src/daemon/handlers/interaction.ts
@@ -1,37 +1,543 @@
-import { dispatchCommand } from '../../core/dispatch.ts';
-import type { DaemonResponse } from '../types.ts';
-import { handleFillCommand } from './interaction-fill.ts';
-import { handleGetCommand } from './interaction-get.ts';
-import type { InteractionHandlerParams } from './interaction-common.ts';
-import { handleIsCommand } from './interaction-is.ts';
-import { handlePressCommand } from './interaction-press.ts';
-import { handleScrollIntoViewCommand } from './interaction-scroll.ts';
-
-export { unsupportedRefSnapshotFlags } from './interaction-flags.ts';
-
-export async function handleInteractionCommands(
-  params: Omit<InteractionHandlerParams, 'dispatch'> & {
-    dispatch?: typeof dispatchCommand;
-  },
-): Promise<DaemonResponse | null> {
-  const handlerParams: InteractionHandlerParams = {
-    ...params,
-    dispatch: params.dispatch ?? dispatchCommand,
-  };
+import { dispatchCommand, type CommandFlags } from '../../core/dispatch.ts';
+import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import {
+  attachRefs,
+  centerOfRect,
+  findNodeByRef,
+  normalizeRef,
+  type RawSnapshotNode,
+  type Rect,
+  type SnapshotNode,
+} from '../../utils/snapshot.ts';
+import type { DaemonCommandContext } from '../context.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
+import { SessionStore } from '../session-store.ts';
+import { evaluateIsPredicate, isSupportedPredicate } from '../is-predicates.ts';
+import {
+  extractNodeText,
+  findNodeByLabel,
+  pruneGroupNodes,
+  resolveRefLabel,
+} from '../snapshot-processing.ts';
+import {
+  buildSelectorChainForNode,
+  findSelectorChainMatch,
+  formatSelectorFailure,
+  parseSelectorChain,
+  resolveSelectorChain,
+  splitIsSelectorArgs,
+} from '../selectors.ts';
+import { withDiagnosticTimer } from '../../utils/diagnostics.ts';
+import { buildScrollIntoViewPlan, resolveViewportRect } from '../scroll-planner.ts';
+import { getAndroidScreenSize } from '../../platforms/android/index.ts';
+import { handleTouchInteractionCommands } from './interaction-touch.ts';
+
+type ContextFromFlags = (
+  flags: CommandFlags | undefined,
+  appBundleId?: string,
+  traceLogPath?: string,
+) => DaemonCommandContext;
+
+export async function handleInteractionCommands(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  sessionStore: SessionStore;
+  contextFromFlags: ContextFromFlags;
+  dispatch?: typeof dispatchCommand;
+  readAndroidScreenSize?: typeof getAndroidScreenSize;
+}): Promise<DaemonResponse | null> {
+  const { req, sessionName, sessionStore, contextFromFlags } = params;
+  const dispatch = params.dispatch ?? dispatchCommand;
+  const readAndroidScreenSize = params.readAndroidScreenSize ?? getAndroidScreenSize;
+  const command = req.command;
+
+  const touchResponse = await handleTouchInteractionCommands({
+    req,
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch,
+    readAndroidScreenSize,
+    captureSnapshotForSession,
+    resolveRefTarget,
+    refSnapshotFlagGuardResponse,
+  });
+  if (touchResponse) {
+    return touchResponse;
+  }
+
+  if (command === 'get') {
+    const sub = req.positionals?.[0];
+    if (sub !== 'text' && sub !== 'attrs') {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: 'get only supports text or attrs' },
+      };
+    }
+    const session = sessionStore.get(sessionName);
+    if (!session) {
+      return {
+        ok: false,
+        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+      };
+    }
+    if (!isCommandSupportedOnDevice('get', session.device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'get is not supported on this device' },
+      };
+    }
+    const refInput = req.positionals?.[1] ?? '';
+    if (refInput.startsWith('@')) {
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('get', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
+      const labelCandidate =
+        req.positionals.length > 2 ? req.positionals.slice(2).join(' ').trim() : '';
+      const resolvedRefTarget = resolveRefTarget({
+        session,
+        refInput,
+        fallbackLabel: labelCandidate,
+        requireRect: false,
+        invalidRefMessage: 'get text requires a ref like @e2',
+        notFoundMessage: `Ref ${refInput} not found`,
+      });
+      if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
+      const { ref, node } = resolvedRefTarget.target;
+      const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+        action: 'get',
+      });
+      if (sub === 'attrs') {
+        sessionStore.recordAction(session, {
+          command,
+          positionals: req.positionals ?? [],
+          flags: req.flags ?? {},
+          result: { ref, selectorChain },
+        });
+        return { ok: true, data: { ref, node } };
+      }
+      const text = extractNodeText(node);
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: { ref, text, refLabel: text || undefined, selectorChain },
+      });
+      return { ok: true, data: { ref, text, node } };
+    }
+
+    const selectorExpression = req.positionals.slice(1).join(' ').trim();
+    if (!selectorExpression) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: 'get requires @ref or selector expression' },
+      };
+    }
+    const chain = parseSelectorChain(selectorExpression);
+    const snapshot = await captureSnapshotForSession(
+      session,
+      req.flags,
+      sessionStore,
+      contextFromFlags,
+      { interactiveOnly: false },
+      dispatch,
+    );
+    const resolved = await withDiagnosticTimer(
+      'selector_resolve',
+      () =>
+        resolveSelectorChain(snapshot.nodes, chain, {
+          platform: session.device.platform,
+          requireRect: false,
+          requireUnique: true,
+          disambiguateAmbiguous: sub === 'text',
+        }),
+      { command },
+    );
+    if (!resolved) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: formatSelectorFailure(chain, [], { unique: true }),
+        },
+      };
+    }
+    const node = resolved.node;
+    const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+      action: 'get',
+    });
+    if (sub === 'attrs') {
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: { selector: resolved.selector.raw, selectorChain },
+      });
+      return { ok: true, data: { selector: resolved.selector.raw, node } };
+    }
+    const text = extractNodeText(node);
+    sessionStore.recordAction(session, {
+      command,
+      positionals: req.positionals ?? [],
+      flags: req.flags ?? {},
+      result: {
+        text,
+        refLabel: text || undefined,
+        selector: resolved.selector.raw,
+        selectorChain,
+      },
+    });
+    return { ok: true, data: { selector: resolved.selector.raw, text, node } };
+  }
 
-  switch (params.req.command) {
-    case 'click':
-    case 'press':
-      return await handlePressCommand(handlerParams);
-    case 'fill':
-      return await handleFillCommand(handlerParams);
-    case 'get':
-      return await handleGetCommand(handlerParams);
-    case 'is':
-      return await handleIsCommand(handlerParams);
-    case 'scrollintoview':
-      return await handleScrollIntoViewCommand(handlerParams);
-    default:
+  if (command === 'is') {
+    const predicate = (req.positionals?.[0] ?? '').toLowerCase();
+    if (!isSupportedPredicate(predicate)) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'is requires predicate: visible|hidden|exists|editable|selected|text',
+        },
+      };
+    }
+    const session = sessionStore.get(sessionName);
+    if (!session) {
+      return {
+        ok: false,
+        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+      };
+    }
+    if (!isCommandSupportedOnDevice('is', session.device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'is is not supported on this device' },
+      };
+    }
+    const { split } = splitIsSelectorArgs(req.positionals);
+    if (!split) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'is requires a selector expression',
+        },
+      };
+    }
+    const expectedText = split.rest.join(' ').trim();
+    if (predicate === 'text' && !expectedText) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'is text requires expected text value',
+        },
+      };
+    }
+    if (predicate !== 'text' && split.rest.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: `is ${predicate} does not accept trailing values`,
+        },
+      };
+    }
+    const chain = parseSelectorChain(split.selectorExpression);
+    const snapshot = await captureSnapshotForSession(
+      session,
+      req.flags,
+      sessionStore,
+      contextFromFlags,
+      { interactiveOnly: false },
+      dispatch,
+    );
+    if (predicate === 'exists') {
+      const matched = findSelectorChainMatch(snapshot.nodes, chain, {
+        platform: session.device.platform,
+      });
+      if (!matched) {
+        return {
+          ok: false,
+          error: {
+            code: 'COMMAND_FAILED',
+            message: formatSelectorFailure(chain, [], { unique: false }),
+          },
+        };
+      }
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: {
+          predicate,
+          selector: matched.selector.raw,
+          selectorChain: chain.selectors.map((entry) => entry.raw),
+          pass: true,
+          matches: matched.matches,
+        },
+      });
+      return {
+        ok: true,
+        data: { predicate, pass: true, selector: matched.selector.raw, matches: matched.matches },
+      };
+    }
+
+    const resolved = await withDiagnosticTimer(
+      'selector_resolve',
+      () =>
+        resolveSelectorChain(snapshot.nodes, chain, {
+          platform: session.device.platform,
+          requireUnique: true,
+        }),
+      { command: 'is', predicate },
+    );
+    if (!resolved) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: formatSelectorFailure(chain, [], { unique: true }),
+        },
+      };
+    }
+    const result = evaluateIsPredicate({
+      predicate,
+      node: resolved.node,
+      expectedText,
+      platform: session.device.platform,
+    });
+    if (!result.pass) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `is ${predicate} failed for selector ${resolved.selector.raw}: ${result.details}`,
+        },
+      };
+    }
+    sessionStore.recordAction(session, {
+      command,
+      positionals: req.positionals ?? [],
+      flags: req.flags ?? {},
+      result: {
+        predicate,
+        selector: resolved.selector.raw,
+        selectorChain: chain.selectors.map((entry) => entry.raw),
+        pass: true,
+        text: predicate === 'text' ? result.actualText : undefined,
+      },
+    });
+    return { ok: true, data: { predicate, pass: true, selector: resolved.selector.raw } };
+  }
+
+  if (command === 'scrollintoview') {
+    const session = sessionStore.get(sessionName);
+    if (!session) {
+      return {
+        ok: false,
+        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+      };
+    }
+    if (!isCommandSupportedOnDevice('scrollintoview', session.device)) {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'scrollintoview is not supported on this device',
+        },
+      };
+    }
+    const targetInput = req.positionals?.[0] ?? '';
+    if (!targetInput.startsWith('@')) {
       return null;
+    }
+    const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('scrollintoview', req.flags);
+    if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
+    const fallbackLabel =
+      req.positionals && req.positionals.length > 1
+        ? req.positionals.slice(1).join(' ').trim()
+        : '';
+    const resolvedRefTarget = resolveRefTarget({
+      session,
+      refInput: targetInput,
+      fallbackLabel,
+      requireRect: true,
+      invalidRefMessage: 'scrollintoview requires a ref like @e2',
+      notFoundMessage: `Ref ${targetInput} not found or has no bounds`,
+    });
+    if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
+    const { ref, node, snapshotNodes } = resolvedRefTarget.target;
+    if (!node.rect) {
+      return {
+        ok: false,
+        error: { code: 'COMMAND_FAILED', message: `Ref ${targetInput} not found or has no bounds` },
+      };
+    }
+    const viewportRect = resolveViewportRect(snapshotNodes, node.rect);
+    if (!viewportRect) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `scrollintoview could not infer viewport for ${targetInput}`,
+        },
+      };
+    }
+    const plan = buildScrollIntoViewPlan(node.rect, viewportRect);
+    const refLabel = resolveRefLabel(node, snapshotNodes);
+    const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+      action: 'get',
+    });
+    if (!plan) {
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: { ref, attempts: 0, alreadyVisible: true, refLabel, selectorChain },
+      });
+      return { ok: true, data: { ref, attempts: 0, alreadyVisible: true } };
+    }
+    const data = await dispatch(
+      session.device,
+      'swipe',
+      [String(plan.x), String(plan.startY), String(plan.x), String(plan.endY), '16'],
+      req.flags?.out,
+      {
+        ...contextFromFlags(req.flags, session.appBundleId, session.trace?.outPath),
+        count: plan.count,
+        pauseMs: 0,
+        pattern: 'one-way',
+      },
+    );
+    sessionStore.recordAction(session, {
+      command,
+      positionals: req.positionals ?? [],
+      flags: req.flags ?? {},
+      result: {
+        ...(data ?? {}),
+        ref,
+        attempts: plan.count,
+        direction: plan.direction,
+        refLabel,
+        selectorChain,
+      },
+    });
+    return {
+      ok: true,
+      data: {
+        ...(data ?? {}),
+        ref,
+        attempts: plan.count,
+        direction: plan.direction,
+      },
+    };
+  }
+
+  return null;
+}
+
+async function captureSnapshotForSession(
+  session: SessionState,
+  flags: CommandFlags | undefined,
+  sessionStore: SessionStore,
+  contextFromFlags: ContextFromFlags,
+  options: { interactiveOnly: boolean },
+  dispatch: typeof dispatchCommand = dispatchCommand,
+) {
+  const data = (await dispatch(session.device, 'snapshot', [], flags?.out, {
+    ...contextFromFlags(
+      {
+        ...(flags ?? {}),
+        snapshotInteractiveOnly: options.interactiveOnly,
+        snapshotCompact: options.interactiveOnly,
+      },
+      session.appBundleId,
+      session.trace?.outPath,
+    ),
+  })) as {
+    nodes?: RawSnapshotNode[];
+    truncated?: boolean;
+    backend?: 'xctest' | 'android';
+  };
+  const rawNodes = data?.nodes ?? [];
+  const nodes = attachRefs(flags?.snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
+  session.snapshot = {
+    nodes,
+    truncated: data?.truncated,
+    createdAt: Date.now(),
+    backend: data?.backend,
+  };
+  sessionStore.set(session.name, session);
+  return session.snapshot;
+}
+
+const REF_UNSUPPORTED_FLAG_MAP: ReadonlyArray<[keyof CommandFlags, string]> = [
+  ['snapshotDepth', '--depth'],
+  ['snapshotScope', '--scope'],
+  ['snapshotRaw', '--raw'],
+];
+
+function refSnapshotFlagGuardResponse(
+  command: 'press' | 'fill' | 'get' | 'scrollintoview',
+  flags: CommandFlags | undefined,
+): DaemonResponse | null {
+  const unsupported = unsupportedRefSnapshotFlags(flags);
+  if (unsupported.length === 0) return null;
+  return {
+    ok: false,
+    error: {
+      code: 'INVALID_ARGS',
+      message: `${command} @ref does not support ${unsupported.join(', ')}.`,
+    },
+  };
+}
+
+export function unsupportedRefSnapshotFlags(flags: CommandFlags | undefined): string[] {
+  if (!flags) return [];
+  const unsupported: string[] = [];
+  for (const [key, label] of REF_UNSUPPORTED_FLAG_MAP) {
+    if (flags[key] !== undefined) unsupported.push(label);
+  }
+  return unsupported;
+}
+
+function resolveRefTarget(params: {
+  session: SessionState;
+  refInput: string;
+  fallbackLabel: string;
+  requireRect: boolean;
+  invalidRefMessage: string;
+  notFoundMessage: string;
+}):
+  | { ok: true; target: { ref: string; node: SnapshotNode; snapshotNodes: SnapshotNode[] } }
+  | { ok: false; response: DaemonResponse } {
+  const { session, refInput, fallbackLabel, requireRect, invalidRefMessage, notFoundMessage } =
+    params;
+  if (!session.snapshot) {
+    return {
+      ok: false,
+      response: {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' },
+      },
+    };
+  }
+  const ref = normalizeRef(refInput);
+  if (!ref) {
+    return {
+      ok: false,
+      response: { ok: false, error: { code: 'INVALID_ARGS', message: invalidRefMessage } },
+    };
+  }
+  let node = findNodeByRef(session.snapshot.nodes, ref);
+  if ((!node || (requireRect && !node.rect)) && fallbackLabel.length > 0) {
+    node = findNodeByLabel(session.snapshot.nodes, fallbackLabel);
+  }
+  if (!node || (requireRect && !node.rect)) {
+    return {
+      ok: false,
+      response: { ok: false, error: { code: 'COMMAND_FAILED', message: notFoundMessage } },
+    };
   }
+  return { ok: true, target: { ref, node, snapshotNodes: session.snapshot.nodes } };
 }
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
new file mode 100644
index 000000000..33aab241c
--- /dev/null
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -0,0 +1,456 @@
+import fs from 'node:fs';
+import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import type { DaemonResponse, SessionState } from '../types.ts';
+import type { RecordTraceDeps } from './record-trace-recording.ts';
+
+const ANDROID_REMOTE_FILE_POLL_MS = 250;
+const ANDROID_REMOTE_FILE_ATTEMPTS = 20;
+const ANDROID_LOCAL_VIDEO_ATTEMPTS = 6;
+const ANDROID_LOCAL_VIDEO_POLL_MS = 500;
+const ANDROID_PROCESS_EXIT_POLL_MS = 250;
+const ANDROID_PROCESS_EXIT_ATTEMPTS = 40;
+const ANDROID_RECORDING_READY_ATTEMPTS = 8;
+const ANDROID_RECORDING_READY_MIN_RUNNING_POLLS = 2;
+
+type AndroidDevice = SessionState['device'];
+type AndroidRecording = Extract<NonNullable<SessionState['recording']>, { platform: 'android' }>;
+type AndroidRecordingBase = Pick<
+  AndroidRecording,
+  'outPath' | 'clientOutPath' | 'telemetryPath' | 'startedAt' | 'showTouches' | 'gestureEvents'
+>;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function failedExecMessage(
+  result: { stdout: string; stderr: string; exitCode: number },
+  command: string,
+): string {
+  return (
+    result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.exitCode}`
+  );
+}
+
+function parseAndroidRemotePid(stdout: string): string | undefined {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^\d+$/.test(line))
+    .at(-1);
+}
+
+function inspectMp4TopLevelAtoms(filePath: string): string[] {
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const size = fs.fstatSync(fd).size;
+      let offset = 0;
+      const atoms: string[] = [];
+      while (offset + 8 <= size && atoms.length < 12) {
+        const header = Buffer.alloc(8);
+        const bytesRead = fs.readSync(fd, header, 0, 8, offset);
+        if (bytesRead < 8) {
+          break;
+        }
+
+        let atomSize = header.readUInt32BE(0);
+        const atomType = header.toString('latin1', 4, 8);
+        atoms.push(atomType);
+
+        if (atomSize === 1) {
+          const extended = Buffer.alloc(8);
+          const extendedRead = fs.readSync(fd, extended, 0, 8, offset + 8);
+          if (extendedRead < 8) {
+            break;
+          }
+          atomSize = Number(extended.readBigUInt64BE(0));
+        }
+
+        if (!Number.isFinite(atomSize) || atomSize <= 0) {
+          break;
+        }
+        offset += atomSize;
+      }
+      return atoms;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return [];
+  }
+}
+
+async function isAndroidProcessRunning(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  pid: string,
+): Promise<boolean> {
+  const result = await deps.runCmd(
+    'adb',
+    ['-s', deviceId, 'shell', 'ps', '-o', 'pid=', '-p', pid],
+    {
+      allowFailure: true,
+    },
+  );
+  if (result.exitCode !== 0) {
+    return false;
+  }
+  return result.stdout
+    .split(/\s+/)
+    .map((value) => value.trim())
+    .includes(pid);
+}
+
+async function waitForAndroidProcessExit(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  pid: string,
+): Promise<boolean> {
+  for (let attempt = 0; attempt < ANDROID_PROCESS_EXIT_ATTEMPTS; attempt += 1) {
+    if (!(await isAndroidProcessRunning(deps, deviceId, pid))) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, ANDROID_PROCESS_EXIT_POLL_MS));
+  }
+  return !(await isAndroidProcessRunning(deps, deviceId, pid));
+}
+
+async function waitForAndroidRemoteFileStability(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  remotePath: string,
+): Promise<void> {
+  let previousSize: string | undefined;
+  let stableCount = 0;
+
+  for (let attempt = 0; attempt < ANDROID_REMOTE_FILE_ATTEMPTS; attempt += 1) {
+    const statResult = await deps.runCmd(
+      'adb',
+      ['-s', deviceId, 'shell', 'stat', '-c', '%s', remotePath],
+      { allowFailure: true },
+    );
+    const currentSize = statResult.exitCode === 0 ? statResult.stdout.trim() : '';
+    if (currentSize.length > 0 && currentSize === previousSize) {
+      stableCount += 1;
+      if (stableCount >= 2) {
+        return;
+      }
+    } else {
+      stableCount = 0;
+    }
+    previousSize = currentSize;
+    await new Promise((resolve) => setTimeout(resolve, ANDROID_REMOTE_FILE_POLL_MS));
+  }
+}
+
+async function waitForAndroidRecordingReady(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  remotePath: string,
+  remotePid: string,
+): Promise<boolean> {
+  let runningPolls = 0;
+
+  for (let attempt = 0; attempt < ANDROID_RECORDING_READY_ATTEMPTS; attempt += 1) {
+    const statResult = await deps.runCmd(
+      'adb',
+      ['-s', deviceId, 'shell', 'stat', '-c', '%s', remotePath],
+      { allowFailure: true },
+    );
+    const currentSize = statResult.exitCode === 0 ? Number(statResult.stdout.trim()) : NaN;
+    if (Number.isFinite(currentSize) && currentSize > 0) {
+      return true;
+    }
+
+    if (!(await isAndroidProcessRunning(deps, deviceId, remotePid))) {
+      return false;
+    }
+
+    runningPolls += 1;
+    if (runningPolls >= ANDROID_RECORDING_READY_MIN_RUNNING_POLLS) {
+      return true;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, ANDROID_REMOTE_FILE_POLL_MS));
+  }
+
+  return runningPolls >= ANDROID_RECORDING_READY_MIN_RUNNING_POLLS;
+}
+
+async function copyAndroidRecordingWithValidation(params: {
+  deps: RecordTraceDeps;
+  deviceId: string;
+  remotePath: string;
+  outPath: string;
+}): Promise<string | undefined> {
+  const { deps, deviceId, remotePath, outPath } = params;
+  let lastCopyError: string | undefined;
+
+  for (let attempt = 0; attempt < ANDROID_LOCAL_VIDEO_ATTEMPTS; attempt += 1) {
+    try {
+      fs.rmSync(outPath, { force: true });
+    } catch {
+      // Ignore stale local file cleanup issues and let adb pull report the real failure.
+    }
+
+    const pullResult = await deps.runCmd('adb', ['-s', deviceId, 'pull', remotePath, outPath], {
+      allowFailure: true,
+    });
+    if (pullResult.exitCode !== 0) {
+      lastCopyError = failedExecMessage(pullResult, 'adb pull');
+    } else {
+      await deps.waitForStableFile(outPath, {
+        pollMs: ANDROID_REMOTE_FILE_POLL_MS,
+        attempts: ANDROID_REMOTE_FILE_ATTEMPTS,
+      });
+      const playable = await deps.isPlayableVideo(outPath);
+      const atoms = inspectMp4TopLevelAtoms(outPath);
+      emitDiagnostic({
+        level: 'debug',
+        phase: 'record_stop_android_pull_validation',
+        data: {
+          deviceId,
+          remotePath,
+          outPath,
+          attempt: attempt + 1,
+          fileSize: (() => {
+            try {
+              return fs.statSync(outPath).size;
+            } catch {
+              return 0;
+            }
+          })(),
+          atoms,
+          playable,
+        },
+      });
+      if (playable) {
+        return undefined;
+      }
+
+      emitDiagnostic({
+        level: 'warn',
+        phase: 'record_stop_android_invalid_video_retry',
+        data: {
+          deviceId,
+          remotePath,
+          outPath,
+          attempt: attempt + 1,
+        },
+      });
+    }
+
+    if (attempt < ANDROID_LOCAL_VIDEO_ATTEMPTS - 1) {
+      await new Promise((resolve) => setTimeout(resolve, ANDROID_LOCAL_VIDEO_POLL_MS));
+    }
+  }
+
+  if (lastCopyError) {
+    return `failed to copy recording from device: ${lastCopyError}`;
+  }
+  return 'failed to copy recording from device: pulled file is not a playable MP4';
+}
+
+export async function startAndroidRecording(params: {
+  deps: RecordTraceDeps;
+  device: AndroidDevice;
+  recordingBase: AndroidRecordingBase;
+}): Promise<DaemonResponse | AndroidRecording> {
+  const { deps, device, recordingBase } = params;
+
+  const remotePath = `/data/local/tmp/agent-device-recording-${Date.now()}.mp4`;
+  const startResult = await deps.runCmd(
+    'adb',
+    ['-s', device.id, 'shell', `screenrecord ${remotePath} >/dev/null 2>&1 & echo $!`],
+    {
+      allowFailure: true,
+    },
+  );
+  if (startResult.exitCode !== 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to start recording: ${failedExecMessage(startResult, 'adb shell screenrecord')}`,
+      },
+    };
+  }
+
+  const remotePid = parseAndroidRemotePid(startResult.stdout);
+  if (!remotePid) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: 'failed to start recording: adb did not return a valid Android screenrecord pid',
+      },
+    };
+  }
+
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'record_start_android_started',
+    data: {
+      deviceId: device.id,
+      remotePath,
+      remotePid,
+    },
+  });
+
+  if (!(await waitForAndroidRecordingReady(deps, device.id, remotePath, remotePid))) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: 'failed to start recording: Android screenrecord did not begin producing frames',
+      },
+    };
+  }
+
+  return {
+    platform: 'android',
+    remotePath,
+    remotePid,
+    ...recordingBase,
+  };
+}
+
+export async function stopAndroidRecording(params: {
+  deps: RecordTraceDeps;
+  device: AndroidDevice;
+  recording: AndroidRecording;
+}): Promise<DaemonResponse | null> {
+  const { deps, device, recording } = params;
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'record_stop_android_enter',
+    data: {
+      deviceId: device.id,
+      remotePath: recording.remotePath,
+      remotePid: recording.remotePid,
+    },
+  });
+  let stopError: string | undefined;
+  let copyError: string | undefined;
+  let cleanupError: string | undefined;
+  let overlayError: string | undefined;
+
+  const stopResult = await deps.runCmd(
+    'adb',
+    ['-s', device.id, 'shell', 'kill', '-2', recording.remotePid],
+    {
+      allowFailure: true,
+    },
+  );
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'record_stop_android_signal',
+    data: {
+      deviceId: device.id,
+      remotePath: recording.remotePath,
+      remotePid: recording.remotePid,
+      exitCode: stopResult.exitCode,
+      stdout: stopResult.stdout.trim(),
+      stderr: stopResult.stderr.trim(),
+    },
+  });
+  if (stopResult.exitCode !== 0) {
+    if (await isAndroidProcessRunning(deps, device.id, recording.remotePid)) {
+      stopError = `failed to stop recording: ${failedExecMessage(stopResult, 'adb shell kill')}`;
+    }
+  } else if (!(await waitForAndroidProcessExit(deps, device.id, recording.remotePid))) {
+    stopError = `failed to stop recording: Android screenrecord pid ${recording.remotePid} did not exit`;
+  }
+
+  if (!stopError) {
+    await waitForAndroidRemoteFileStability(deps, device.id, recording.remotePath);
+    copyError = await copyAndroidRecordingWithValidation({
+      deps,
+      deviceId: device.id,
+      remotePath: recording.remotePath,
+      outPath: recording.outPath,
+    });
+    if (!copyError) {
+      recording.telemetryPath = deps.writeRecordingTelemetry({
+        videoPath: recording.outPath,
+        events: recording.gestureEvents,
+      });
+    }
+    if (!copyError && recording.showTouches && recording.telemetryPath) {
+      try {
+        await deps.overlayRecordingTouches({
+          videoPath: recording.outPath,
+          telemetryPath: recording.telemetryPath,
+          targetLabel: 'Android recording',
+        });
+      } catch (error) {
+        overlayError = `failed to overlay recording touches: ${errorMessage(error)}`;
+      }
+    }
+
+    const rmResult = await deps.runCmd(
+      'adb',
+      ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath],
+      {
+        allowFailure: true,
+      },
+    );
+    emitDiagnostic({
+      level: 'debug',
+      phase: 'record_stop_android_cleanup',
+      data: {
+        deviceId: device.id,
+        remotePath: recording.remotePath,
+        exitCode: rmResult.exitCode,
+        stdout: rmResult.stdout.trim(),
+        stderr: rmResult.stderr.trim(),
+      },
+    });
+    if (rmResult.exitCode !== 0) {
+      cleanupError = `failed to clean up remote recording: ${failedExecMessage(rmResult, 'adb shell rm')}`;
+    }
+  }
+
+  if (stopError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: stopError,
+      },
+    };
+  }
+
+  if (copyError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: copyError,
+      },
+    };
+  }
+
+  if (overlayError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: overlayError,
+      },
+    };
+  }
+
+  if (cleanupError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: cleanupError,
+      },
+    };
+  }
+
+  return null;
+}
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
new file mode 100644
index 000000000..f61bcb269
--- /dev/null
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -0,0 +1,665 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveTargetDevice, type CommandFlags } from '../../core/dispatch.ts';
+import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { ensureDeviceReady } from '../device-ready.ts';
+import { SessionStore } from '../session-store.ts';
+import type {
+  DaemonArtifact,
+  DaemonRequest,
+  DaemonResponse,
+  RecordingGestureEvent,
+  SessionState,
+} from '../types.ts';
+import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import { runCmd, runCmdBackground } from '../../utils/exec.ts';
+import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
+import { trimRecordingTelemetryEvents, writeRecordingTelemetry } from '../recording-telemetry.ts';
+import {
+  IOS_RUNNER_CONTAINER_BUNDLE_IDS,
+  runIosRunnerCommand,
+} from '../../platforms/ios/runner-client.ts';
+import {
+  overlayRecordingTouches,
+  trimRecordingStart,
+} from '../../platforms/ios/recording-overlay.ts';
+import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
+import { startAndroidRecording, stopAndroidRecording } from './record-trace-android.ts';
+
+const IOS_DEVICE_RECORD_MIN_FPS = 1;
+const IOS_DEVICE_RECORD_MAX_FPS = 120;
+
+export type RecordTraceDeps = {
+  runCmd: typeof runCmd;
+  runCmdBackground: typeof runCmdBackground;
+  runIosRunnerCommand: typeof runIosRunnerCommand;
+  waitForStableFile: typeof waitForStableFile;
+  isPlayableVideo: typeof isPlayableVideo;
+  writeRecordingTelemetry: typeof writeRecordingTelemetry;
+  trimRecordingStart: typeof trimRecordingStart;
+  overlayRecordingTouches: typeof overlayRecordingTouches;
+};
+
+export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): RecordTraceDeps {
+  return {
+    runCmd,
+    runCmdBackground,
+    runIosRunnerCommand,
+    waitForStableFile,
+    isPlayableVideo,
+    writeRecordingTelemetry,
+    trimRecordingStart,
+    overlayRecordingTouches,
+    ...overrides,
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function failedExecMessage(
+  result: { stdout: string; stderr: string; exitCode: number },
+  command: string,
+): string {
+  return (
+    result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.exitCode}`
+  );
+}
+
+function isRunnerRecordingAlreadyInProgressError(error: unknown): boolean {
+  return errorMessage(error).toLowerCase().includes('recording already in progress');
+}
+
+function normalizeAppBundleId(session: SessionState): string | undefined {
+  const trimmed = session.appBundleId?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+
+function findOtherActiveIosRunnerRecording(
+  sessionStore: SessionStore,
+  deviceId: string,
+  currentSessionName: string,
+): SessionState | undefined {
+  return sessionStore
+    .toArray()
+    .find(
+      (session) =>
+        session.name !== currentSessionName &&
+        session.device.platform === 'ios' &&
+        session.device.kind === 'device' &&
+        session.device.id === deviceId &&
+        session.recording?.platform === 'ios-device-runner',
+    );
+}
+
+function getRunnerOptions(req: DaemonRequest, logPath: string | undefined, session: SessionState) {
+  return {
+    verbose: req.flags?.verbose,
+    logPath,
+    traceLogPath: session.trace?.outPath,
+  };
+}
+
+async function warmIosSimulatorRunner(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+}): Promise<DaemonResponse | null> {
+  const { req, activeSession, device, logPath, deps } = params;
+  const appBundleId = normalizeAppBundleId(activeSession);
+  if (!appBundleId) return null;
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      {
+        command: 'snapshot',
+        appBundleId,
+        interactiveOnly: true,
+        compact: true,
+        depth: 1,
+      },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+    return null;
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to prepare iOS simulator recording: ${errorMessage(error)}`,
+      },
+    };
+  }
+}
+
+function buildRecordingBase(
+  req: DaemonRequest,
+  outPath: string,
+): {
+  outPath: string;
+  clientOutPath?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+} {
+  return {
+    outPath,
+    clientOutPath: req.meta?.clientArtifactPaths?.outPath,
+    startedAt: Date.now(),
+    showTouches: req.flags?.hideTouches !== true,
+    gestureEvents: [],
+  };
+}
+
+function resolveIosRecordingTrimStartMs(
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>,
+): number {
+  if (
+    typeof recording.runnerStartedAtUptimeMs !== 'number' ||
+    typeof recording.targetAppReadyUptimeMs !== 'number'
+  ) {
+    return 0;
+  }
+  return Math.max(0, recording.targetAppReadyUptimeMs - recording.runnerStartedAtUptimeMs);
+}
+
+function persistRecordingTelemetry(params: {
+  deps: RecordTraceDeps;
+  recording: NonNullable<SessionState['recording']>;
+  trimStartMs?: number;
+}): string {
+  const { deps, recording, trimStartMs = 0 } = params;
+  const events = trimRecordingTelemetryEvents(recording.gestureEvents, trimStartMs);
+  const telemetryPath = deps.writeRecordingTelemetry({
+    videoPath: recording.outPath,
+    events,
+  });
+  recording.telemetryPath = telemetryPath;
+  return telemetryPath;
+}
+
+async function startIosDeviceRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  sessionStore: SessionStore;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  fpsFlag: number | undefined;
+  recordingBase: ReturnType<typeof buildRecordingBase>;
+  appBundleId: string;
+}): Promise<DaemonResponse | NonNullable<SessionState['recording']>> {
+  const {
+    req,
+    activeSession,
+    sessionStore,
+    device,
+    logPath,
+    deps,
+    fpsFlag,
+    recordingBase,
+    appBundleId,
+  } = params;
+  const recordingFileName = `agent-device-recording-${Date.now()}.mp4`;
+  const remotePath = `tmp/${recordingFileName}`;
+  const runnerOptions = getRunnerOptions(req, logPath, activeSession);
+  let runnerStartedAtUptimeMs: number | undefined;
+  let targetAppReadyUptimeMs: number | undefined;
+  const startRunnerRecording = async () =>
+    deps.runIosRunnerCommand(
+      device,
+      {
+        command: 'recordStart',
+        outPath: recordingFileName,
+        fps: fpsFlag,
+        appBundleId,
+      },
+      runnerOptions,
+    );
+
+  try {
+    const startResult = await startRunnerRecording();
+    runnerStartedAtUptimeMs =
+      typeof startResult.recorderStartUptimeMs === 'number'
+        ? startResult.recorderStartUptimeMs
+        : undefined;
+    targetAppReadyUptimeMs =
+      typeof startResult.targetAppReadyUptimeMs === 'number'
+        ? startResult.targetAppReadyUptimeMs
+        : undefined;
+  } catch (error) {
+    if (!isRunnerRecordingAlreadyInProgressError(error)) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: ${errorMessage(error)}`,
+        },
+      };
+    }
+
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_start_runner_desynced',
+      data: {
+        platform: device.platform,
+        kind: device.kind,
+        deviceId: device.id,
+        session: activeSession.name,
+        error: errorMessage(error),
+      },
+    });
+
+    const otherRecordingSession = findOtherActiveIosRunnerRecording(
+      sessionStore,
+      device.id,
+      activeSession.name,
+    );
+    if (otherRecordingSession) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: recording already in progress in session '${otherRecordingSession.name}'`,
+        },
+      };
+    }
+
+    try {
+      await deps.runIosRunnerCommand(device, { command: 'recordStop', appBundleId }, runnerOptions);
+    } catch {
+      // best effort: stop stale runner recording and retry start
+    }
+
+    try {
+      const startResult = await startRunnerRecording();
+      runnerStartedAtUptimeMs =
+        typeof startResult.recorderStartUptimeMs === 'number'
+          ? startResult.recorderStartUptimeMs
+          : undefined;
+      targetAppReadyUptimeMs =
+        typeof startResult.targetAppReadyUptimeMs === 'number'
+          ? startResult.targetAppReadyUptimeMs
+          : undefined;
+    } catch (retryError) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: ${errorMessage(retryError)}`,
+        },
+      };
+    }
+  }
+
+  return {
+    platform: 'ios-device-runner',
+    remotePath,
+    runnerStartedAtUptimeMs,
+    targetAppReadyUptimeMs,
+    ...recordingBase,
+  };
+}
+
+async function startRecording(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  sessionStore: SessionStore;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+}): Promise<DaemonResponse> {
+  const { req, sessionName, sessionStore, activeSession, device, logPath, deps } = params;
+
+  if (activeSession.recording) {
+    return {
+      ok: false,
+      error: { code: 'INVALID_ARGS', message: 'recording already in progress' },
+    };
+  }
+
+  const fpsFlag = req.flags?.fps;
+  if (
+    fpsFlag !== undefined &&
+    (!Number.isInteger(fpsFlag) ||
+      fpsFlag < IOS_DEVICE_RECORD_MIN_FPS ||
+      fpsFlag > IOS_DEVICE_RECORD_MAX_FPS)
+  ) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_ARGS',
+        message: `fps must be an integer between ${IOS_DEVICE_RECORD_MIN_FPS} and ${IOS_DEVICE_RECORD_MAX_FPS}`,
+      },
+    };
+  }
+
+  if (!isCommandSupportedOnDevice('record', device)) {
+    return {
+      ok: false,
+      error: {
+        code: 'UNSUPPORTED_OPERATION',
+        message: 'record is not supported on this device',
+      },
+    };
+  }
+
+  const outPath = req.positionals?.[1] ?? `./recording-${Date.now()}.mp4`;
+  const resolvedOut = SessionStore.expandHome(outPath, req.meta?.cwd);
+  const recordingBase = buildRecordingBase(req, resolvedOut);
+  fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+  fs.rmSync(resolvedOut, { force: true });
+
+  let recording: NonNullable<SessionState['recording']> | DaemonResponse;
+  if (device.platform === 'ios' && device.kind === 'device') {
+    const appBundleId = normalizeAppBundleId(activeSession);
+    if (!appBundleId) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message:
+            'record on physical iOS devices requires an active app session; run open <app> first',
+        },
+      };
+    }
+    recording = await startIosDeviceRecording({
+      req,
+      activeSession,
+      sessionStore,
+      device,
+      logPath,
+      deps,
+      fpsFlag,
+      recordingBase,
+      appBundleId,
+    });
+  } else if (device.platform === 'ios') {
+    const warmRunnerError = await warmIosSimulatorRunner({
+      req,
+      activeSession,
+      device,
+      logPath,
+      deps,
+    });
+    if (warmRunnerError) {
+      return warmRunnerError;
+    }
+    const { child, wait } = deps.runCmdBackground(
+      'xcrun',
+      buildSimctlArgsForDevice(device, ['io', device.id, 'recordVideo', '-f', resolvedOut]),
+      {
+        allowFailure: true,
+      },
+    );
+    recording = { platform: 'ios', child, wait, ...recordingBase };
+  } else {
+    recording = await startAndroidRecording({ deps, device, recordingBase });
+  }
+
+  if ('ok' in recording) {
+    return recording;
+  }
+
+  activeSession.recording = recording;
+  sessionStore.set(sessionName, activeSession);
+  sessionStore.recordAction(activeSession, {
+    command: req.command,
+    positionals: req.positionals ?? [],
+    flags: (req.flags ?? {}) as CommandFlags,
+    result: { action: 'start', showTouches: recording.showTouches },
+  });
+
+  return {
+    ok: true,
+    data: {
+      recording: 'started',
+      outPath: recording.clientOutPath ?? outPath,
+      showTouches: recording.showTouches,
+    },
+  };
+}
+
+async function stopIosDeviceRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>;
+}): Promise<DaemonResponse | null> {
+  const { req, activeSession, device, logPath, deps, recording } = params;
+  const appBundleId = normalizeAppBundleId(activeSession);
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      { command: 'recordStop', appBundleId },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+  } catch (error) {
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_stop_runner_failed',
+      data: {
+        platform: device.platform,
+        kind: device.kind,
+        deviceId: device.id,
+        session: activeSession.name,
+        error: errorMessage(error),
+      },
+    });
+    // best effort: clear runner-backed recording state even if runner stop fails
+  }
+
+  let copyResult = { stdout: '', stderr: '', exitCode: 1 };
+  for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
+    copyResult = await deps.runCmd(
+      'xcrun',
+      [
+        'devicectl',
+        'device',
+        'copy',
+        'from',
+        '--device',
+        device.id,
+        '--source',
+        recording.remotePath,
+        '--destination',
+        recording.outPath,
+        '--domain-type',
+        'appDataContainer',
+        '--domain-identifier',
+        bundleId,
+      ],
+      { allowFailure: true },
+    );
+    if (copyResult.exitCode === 0) {
+      break;
+    }
+  }
+
+  if (copyResult.exitCode !== 0) {
+    const copyError =
+      copyResult.stderr.trim() ||
+      copyResult.stdout.trim() ||
+      `devicectl exited with code ${copyResult.exitCode}`;
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to copy recording from device: ${copyError}`,
+      },
+    };
+  }
+
+  const trimStartMs = resolveIosRecordingTrimStartMs(recording);
+  if (trimStartMs > 0) {
+    await deps.trimRecordingStart({
+      videoPath: recording.outPath,
+      trimStartMs,
+    });
+  }
+
+  const telemetryPath = persistRecordingTelemetry({ deps, recording, trimStartMs });
+
+  if (recording.showTouches) {
+    await deps.overlayRecordingTouches({
+      videoPath: recording.outPath,
+      telemetryPath,
+      targetLabel: 'iOS recording',
+    });
+  }
+
+  return null;
+}
+
+async function stopNonRunnerRecording(params: {
+  deps: RecordTraceDeps;
+  device: SessionState['device'];
+  recording: Exclude<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>;
+}): Promise<DaemonResponse | null> {
+  const { deps, device, recording } = params;
+  if (recording.platform === 'android') {
+    return await stopAndroidRecording({ deps, device, recording });
+  }
+
+  recording.child.kill('SIGINT');
+
+  const stopResult = await recording.wait;
+  if (stopResult.exitCode !== 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to stop recording: ${failedExecMessage(stopResult, 'simctl recordVideo')}`,
+      },
+    };
+  }
+
+  const telemetryPath = persistRecordingTelemetry({ deps, recording });
+
+  if (recording.showTouches) {
+    await deps.overlayRecordingTouches({
+      videoPath: recording.outPath,
+      telemetryPath,
+      targetLabel: 'iOS recording',
+    });
+  }
+
+  return null;
+}
+
+async function stopRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+}): Promise<DaemonResponse> {
+  const { req, activeSession, device, logPath, deps } = params;
+
+  if (!activeSession.recording) {
+    return { ok: false, error: { code: 'INVALID_ARGS', message: 'no active recording' } };
+  }
+
+  const recording = activeSession.recording;
+  activeSession.recording = undefined;
+
+  const stopError =
+    recording.platform === 'ios-device-runner'
+      ? await stopIosDeviceRecording({ req, activeSession, device, logPath, deps, recording })
+      : await stopNonRunnerRecording({ deps, device, recording });
+  if (stopError) {
+    return stopError;
+  }
+
+  return buildRecordStopResponse(recording);
+}
+
+function buildRecordStopResponse(
+  recording: NonNullable<SessionState['recording']>,
+): DaemonResponse {
+  const artifacts: DaemonArtifact[] = [
+    {
+      field: 'outPath',
+      path: recording.outPath,
+      localPath: recording.clientOutPath,
+      fileName: path.basename(recording.clientOutPath ?? recording.outPath),
+    },
+  ];
+  if (recording.telemetryPath) {
+    artifacts.push({
+      field: 'gestureTelemetry',
+      path: recording.telemetryPath,
+      fileName: path.basename(recording.telemetryPath),
+    });
+  }
+
+  return {
+    ok: true,
+    data: {
+      recording: 'stopped',
+      outPath: recording.outPath,
+      telemetryPath: recording.telemetryPath,
+      artifacts,
+      showTouches: recording.showTouches,
+    },
+  };
+}
+
+export async function handleRecordCommand(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  sessionStore: SessionStore;
+  logPath?: string;
+  deps?: Partial<RecordTraceDeps>;
+}): Promise<DaemonResponse> {
+  const { req, sessionName, sessionStore, logPath } = params;
+  const deps = buildRecordTraceDeps(params.deps);
+  const session = sessionStore.get(sessionName);
+  const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
+  if (!session) {
+    await ensureDeviceReady(device);
+  }
+
+  const activeSession =
+    session ??
+    ({
+      name: sessionName,
+      device,
+      createdAt: Date.now(),
+      actions: [],
+    } satisfies SessionState);
+
+  const action = (req.positionals?.[0] ?? '').toLowerCase();
+  if (!['start', 'stop'].includes(action)) {
+    return { ok: false, error: { code: 'INVALID_ARGS', message: 'record requires start|stop' } };
+  }
+
+  if (action === 'start') {
+    return startRecording({ req, sessionName, sessionStore, activeSession, device, logPath, deps });
+  }
+
+  const response = await stopRecording({ req, activeSession, device, logPath, deps });
+  if (!response.ok) {
+    return response;
+  }
+
+  sessionStore.recordAction(activeSession, {
+    command: req.command,
+    positionals: req.positionals ?? [],
+    flags: (req.flags ?? {}) as CommandFlags,
+    result: {
+      action: 'stop',
+      outPath: response.data?.outPath,
+      showTouches: response.data?.showTouches,
+    },
+  });
+  return response;
+}
diff --git a/src/daemon/handlers/record-trace.ts b/src/daemon/handlers/record-trace.ts
index eb010e4e1..e6c614c4a 100644
--- a/src/daemon/handlers/record-trace.ts
+++ b/src/daemon/handlers/record-trace.ts
@@ -1,434 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { runCmd, runCmdBackground } from '../../utils/exec.ts';
-import { resolveTargetDevice, type CommandFlags } from '../../core/dispatch.ts';
-import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
-import {
-  runIosRunnerCommand,
-  IOS_RUNNER_CONTAINER_BUNDLE_IDS,
-} from '../../platforms/ios/runner-client.ts';
-import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
-import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
+import type { CommandFlags } from '../../core/dispatch.ts';
+import type { DaemonRequest, DaemonResponse } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
-import { emitDiagnostic } from '../../utils/diagnostics.ts';
-import type { DaemonArtifact } from '../types.ts';
-
-const IOS_DEVICE_RECORD_MIN_FPS = 1;
-const IOS_DEVICE_RECORD_MAX_FPS = 120;
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function isRunnerRecordingAlreadyInProgressError(error: unknown): boolean {
-  return errorMessage(error).toLowerCase().includes('recording already in progress');
-}
-
-function normalizeAppBundleId(session: SessionState): string | undefined {
-  const trimmed = session.appBundleId?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : undefined;
-}
-
-function findOtherRunnerRecording(
-  sessionStore: SessionStore,
-  deviceId: string,
-  currentSessionName: string,
-): SessionState | undefined {
-  return sessionStore
-    .toArray()
-    .find(
-      (session) =>
-        session.name !== currentSessionName &&
-        session.device.id === deviceId &&
-        (session.recording?.platform === 'ios-device-runner' ||
-          session.recording?.platform === 'macos-runner'),
-    );
-}
-
-function getRunnerOptions(req: DaemonRequest, logPath: string | undefined, session: SessionState) {
-  return {
-    verbose: req.flags?.verbose,
-    logPath,
-    traceLogPath: session.trace?.outPath,
-  };
-}
-
-async function startRunnerRecordingSession(params: {
-  deps: NonNullable<Parameters<typeof handleRecordTraceCommands>[0]['deps']>;
-  device: SessionState['device'];
-  sessionStore: SessionStore;
-  session: SessionState;
-  req: DaemonRequest;
-  logPath: string | undefined;
-  fps?: number;
-  appBundleId: string;
-  runnerOutPath: string;
-  recording: Extract<
-    NonNullable<SessionState['recording']>,
-    { platform: 'ios-device-runner' | 'macos-runner' }
-  >;
-}): Promise<DaemonResponse | { recording: NonNullable<SessionState['recording']> }> {
-  const { deps, device, sessionStore, session, req, logPath, fps, appBundleId, runnerOutPath } =
-    params;
-  const runnerOptions = getRunnerOptions(req, logPath, session);
-  const startRunnerRecording = async () => {
-    await deps.runIosRunnerCommand(
-      device,
-      {
-        command: 'recordStart',
-        outPath: runnerOutPath,
-        fps,
-        appBundleId,
-      },
-      runnerOptions,
-    );
-  };
-
-  try {
-    await startRunnerRecording();
-  } catch (error) {
-    if (isRunnerRecordingAlreadyInProgressError(error)) {
-      emitDiagnostic({
-        level: 'warn',
-        phase: 'record_start_runner_desynced',
-        data: {
-          platform: device.platform,
-          kind: device.kind,
-          deviceId: device.id,
-          session: session.name,
-          error: errorMessage(error),
-        },
-      });
-      const otherRecordingSession = findOtherRunnerRecording(sessionStore, device.id, session.name);
-      if (otherRecordingSession) {
-        return {
-          ok: false,
-          error: {
-            code: 'COMMAND_FAILED',
-            message: `failed to start recording: recording already in progress in session '${otherRecordingSession.name}'`,
-          },
-        };
-      }
-      try {
-        await deps.runIosRunnerCommand(
-          device,
-          { command: 'recordStop', appBundleId },
-          runnerOptions,
-        );
-      } catch {
-        // best effort: stop stale runner recording and retry start
-      }
-      try {
-        await startRunnerRecording();
-      } catch (retryError) {
-        return {
-          ok: false,
-          error: {
-            code: 'COMMAND_FAILED',
-            message: `failed to start recording: ${errorMessage(retryError)}`,
-          },
-        };
-      }
-    } else {
-      return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: `failed to start recording: ${errorMessage(error)}`,
-        },
-      };
-    }
-  }
-
-  return { recording: params.recording };
-}
+import { handleRecordCommand, type RecordTraceDeps } from './record-trace-recording.ts';
 
 export async function handleRecordTraceCommands(params: {
   req: DaemonRequest;
   sessionName: string;
   sessionStore: SessionStore;
   logPath?: string;
-  deps?: {
-    runCmd: typeof runCmd;
-    runCmdBackground: typeof runCmdBackground;
-    runIosRunnerCommand: typeof runIosRunnerCommand;
-  };
+  deps?: Partial<RecordTraceDeps>;
 }): Promise<DaemonResponse | null> {
   const { req, sessionName, sessionStore, logPath } = params;
-  const deps = params.deps ?? { runCmd, runCmdBackground, runIosRunnerCommand };
   const command = req.command;
 
   if (command === 'record') {
-    const action = (req.positionals?.[0] ?? '').toLowerCase();
-    if (!['start', 'stop'].includes(action)) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'record requires start|stop' } };
-    }
-    const session = sessionStore.get(sessionName);
-    const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
-    if (!session) {
-      await ensureDeviceReady(device);
-    }
-    const activeSession =
-      session ??
-      ({
-        name: sessionName,
-        device,
-        createdAt: Date.now(),
-        actions: [],
-      } satisfies SessionState);
-
-    if (action === 'start') {
-      if (activeSession.recording) {
-        return {
-          ok: false,
-          error: { code: 'INVALID_ARGS', message: 'recording already in progress' },
-        };
-      }
-      const fpsFlag = req.flags?.fps;
-      if (
-        fpsFlag !== undefined &&
-        (!Number.isInteger(fpsFlag) ||
-          fpsFlag < IOS_DEVICE_RECORD_MIN_FPS ||
-          fpsFlag > IOS_DEVICE_RECORD_MAX_FPS)
-      ) {
-        return {
-          ok: false,
-          error: {
-            code: 'INVALID_ARGS',
-            message: `fps must be an integer between ${IOS_DEVICE_RECORD_MIN_FPS} and ${IOS_DEVICE_RECORD_MAX_FPS}`,
-          },
-        };
-      }
-      const outPath = req.positionals?.[1] ?? `./recording-${Date.now()}.mp4`;
-      if (!isCommandSupportedOnDevice('record', device)) {
-        return {
-          ok: false,
-          error: {
-            code: 'UNSUPPORTED_OPERATION',
-            message: 'record is not supported on this device',
-          },
-        };
-      }
-      const runnerAppBundleId =
-        (device.platform === 'ios' && device.kind === 'device') || device.platform === 'macos'
-          ? normalizeAppBundleId(activeSession)
-          : undefined;
-      if (
-        !runnerAppBundleId &&
-        ((device.platform === 'ios' && device.kind === 'device') || device.platform === 'macos')
-      ) {
-        return {
-          ok: false,
-          error: {
-            code: 'INVALID_ARGS',
-            message:
-              device.platform === 'macos'
-                ? 'record on macOS requires an active app session; run open <app> first'
-                : 'record on physical iOS devices requires an active app session; run open <app> first',
-          },
-        };
-      }
-      const ensuredRunnerAppBundleId = runnerAppBundleId as string;
-      const resolvedOut = SessionStore.expandHome(outPath, req.meta?.cwd);
-      const clientOutPath = req.meta?.clientArtifactPaths?.outPath;
-      fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
-      if (device.platform === 'ios' && device.kind === 'device') {
-        const appBundleId = ensuredRunnerAppBundleId;
-        const recordingFileName = `agent-device-recording-${Date.now()}.mp4`;
-        const remotePath = `tmp/${recordingFileName}`;
-        const started = await startRunnerRecordingSession({
-          deps,
-          device,
-          sessionStore,
-          session: activeSession,
-          req,
-          logPath,
-          fps: fpsFlag,
-          appBundleId,
-          runnerOutPath: recordingFileName,
-          recording: {
-            platform: 'ios-device-runner',
-            outPath: resolvedOut,
-            clientOutPath,
-            remotePath,
-          },
-        });
-        if ('ok' in started) {
-          return started;
-        }
-        activeSession.recording = started.recording;
-      } else if (device.platform === 'macos') {
-        const appBundleId = ensuredRunnerAppBundleId;
-        const started = await startRunnerRecordingSession({
-          deps,
-          device,
-          sessionStore,
-          session: activeSession,
-          req,
-          logPath,
-          fps: fpsFlag,
-          appBundleId,
-          runnerOutPath: resolvedOut,
-          recording: {
-            platform: 'macos-runner',
-            outPath: resolvedOut,
-            clientOutPath,
-          },
-        });
-        if ('ok' in started) {
-          return started;
-        }
-        activeSession.recording = started.recording;
-      } else if (device.platform === 'ios') {
-        const { child, wait } = deps.runCmdBackground(
-          'xcrun',
-          buildSimctlArgsForDevice(device, ['io', device.id, 'recordVideo', resolvedOut]),
-          {
-            allowFailure: true,
-          },
-        );
-        activeSession.recording = {
-          platform: 'ios',
-          outPath: resolvedOut,
-          clientOutPath,
-          child,
-          wait,
-        };
-      } else {
-        const remotePath = `/sdcard/agent-device-recording-${Date.now()}.mp4`;
-        const { child, wait } = deps.runCmdBackground(
-          'adb',
-          ['-s', device.id, 'shell', 'screenrecord', remotePath],
-          {
-            allowFailure: true,
-          },
-        );
-        activeSession.recording = {
-          platform: 'android',
-          outPath: resolvedOut,
-          clientOutPath,
-          remotePath,
-          child,
-          wait,
-        };
-      }
-      sessionStore.set(sessionName, activeSession);
-      sessionStore.recordAction(activeSession, {
-        command,
-        positionals: req.positionals ?? [],
-        flags: (req.flags ?? {}) as CommandFlags,
-        result: { action: 'start' },
-      });
-      return { ok: true, data: { recording: 'started', outPath: clientOutPath ?? outPath } };
-    }
-
-    if (!activeSession.recording) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'no active recording' } };
-    }
-    const recording = activeSession.recording;
-    if (recording.platform === 'ios-device-runner' || recording.platform === 'macos-runner') {
-      const appBundleId = normalizeAppBundleId(activeSession);
-      try {
-        await deps.runIosRunnerCommand(
-          device,
-          { command: 'recordStop', appBundleId },
-          getRunnerOptions(req, logPath, activeSession),
-        );
-      } catch (error) {
-        emitDiagnostic({
-          level: 'warn',
-          phase: 'record_stop_runner_failed',
-          data: {
-            platform: device.platform,
-            kind: device.kind,
-            deviceId: device.id,
-            session: activeSession.name,
-            error: errorMessage(error),
-          },
-        });
-        // best effort: clear runner-backed recording state even if runner stop fails
-      }
-      activeSession.recording = undefined;
-      if (recording.platform === 'ios-device-runner') {
-        let copyResult = { stdout: '', stderr: '', exitCode: 1 };
-        for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
-          copyResult = await deps.runCmd(
-            'xcrun',
-            [
-              'devicectl',
-              'device',
-              'copy',
-              'from',
-              '--device',
-              device.id,
-              '--source',
-              recording.remotePath as string,
-              '--destination',
-              recording.outPath,
-              '--domain-type',
-              'appDataContainer',
-              '--domain-identifier',
-              bundleId,
-            ],
-            { allowFailure: true },
-          );
-          if (copyResult.exitCode === 0) {
-            break;
-          }
-        }
-        if (copyResult.exitCode !== 0) {
-          const copyError =
-            copyResult.stderr.trim() ||
-            copyResult.stdout.trim() ||
-            `devicectl exited with code ${copyResult.exitCode}`;
-          return {
-            ok: false,
-            error: {
-              code: 'COMMAND_FAILED',
-              message: `failed to copy recording from device: ${copyError}`,
-            },
-          };
-        }
-      }
-    } else if ('child' in recording) {
-      recording.child.kill('SIGINT');
-      try {
-        await recording.wait;
-      } catch {
-        // ignore
-      }
-      if (recording.platform === 'android' && recording.remotePath) {
-        try {
-          await deps.runCmd(
-            'adb',
-            ['-s', device.id, 'pull', recording.remotePath, recording.outPath],
-            { allowFailure: true },
-          );
-          await deps.runCmd('adb', ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath], {
-            allowFailure: true,
-          });
-        } catch {
-          // ignore
-        }
-      }
-      activeSession.recording = undefined;
-    }
-    sessionStore.recordAction(activeSession, {
-      command,
-      positionals: req.positionals ?? [],
-      flags: (req.flags ?? {}) as CommandFlags,
-      result: { action: 'stop', outPath: recording.outPath },
-    });
-    const artifacts: DaemonArtifact[] = [
-      {
-        field: 'outPath',
-        path: recording.outPath,
-        localPath: recording.clientOutPath,
-        fileName: path.basename(recording.clientOutPath ?? recording.outPath),
-      },
-    ];
-    return { ok: true, data: { recording: 'stopped', outPath: recording.outPath, artifacts } };
+    return handleRecordCommand({ req, sessionName, sessionStore, logPath, deps: params.deps });
   }
 
   if (command === 'trace') {
diff --git a/src/daemon/handlers/session-replay-script.ts b/src/daemon/handlers/session-replay-script.ts
index a307b3365..5836816a9 100644
--- a/src/daemon/handlers/session-replay-script.ts
+++ b/src/daemon/handlers/session-replay-script.ts
@@ -158,6 +158,28 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     return action;
   }
 
+  if (command === 'record') {
+    const positionals: string[] = [];
+    for (let index = 0; index < args.length; index += 1) {
+      const token = args[index];
+      if (token === '--hide-touches') {
+        action.flags.hideTouches = true;
+        continue;
+      }
+      if (token === '--fps' && index + 1 < args.length) {
+        const parsedFps = Number(args[index + 1]);
+        if (Number.isFinite(parsedFps)) {
+          action.flags.fps = Math.floor(parsedFps);
+        }
+        index += 1;
+        continue;
+      }
+      positionals.push(token);
+    }
+    action.positionals = positionals;
+    return action;
+  }
+
   action.positionals = args;
   return action;
 }
@@ -253,6 +275,22 @@ function formatReplayActionLine(action: SessionAction): string {
     appendRuntimeHintFlags(parts, action.flags);
     return parts.join(' ');
   }
+  if (action.command === 'record') {
+    const [subcommand, ...rest] = action.positionals ?? [];
+    if (subcommand) {
+      parts.push(formatScriptArgQuoteIfNeeded(subcommand));
+    }
+    for (const positional of rest) {
+      parts.push(formatScriptArg(positional));
+    }
+    if (typeof action.flags?.fps === 'number') {
+      parts.push('--fps', String(action.flags.fps));
+    }
+    if (action.flags?.hideTouches) {
+      parts.push('--hide-touches');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatScriptArg(positional));
   }
diff --git a/src/daemon/recording-gestures.ts b/src/daemon/recording-gestures.ts
new file mode 100644
index 000000000..8b4de91f3
--- /dev/null
+++ b/src/daemon/recording-gestures.ts
@@ -0,0 +1,539 @@
+import type { RecordingGestureEvent, SessionState } from './types.ts';
+import type { Rect, SnapshotNode, SnapshotState } from '../utils/snapshot.ts';
+import { resolveGestureDurationMs, resolveGestureOffsetMs } from './recording-timing.ts';
+import { emitDiagnostic } from '../utils/diagnostics.ts';
+
+const DEFAULT_TAP_GAP_MS = 90;
+const DEFAULT_SWIPE_DURATION_MS = 250;
+const DEFAULT_PINCH_DURATION_MS = 280;
+const DEFAULT_SCROLL_FRACTION = 0.4;
+const MIN_SCROLL_FRACTION = 0.2;
+const MAX_SCROLL_FRACTION = 0.7;
+const DEFAULT_SCROLL_REFERENCE_FRAME: ReferenceFrame = {
+  referenceWidth: 1000,
+  referenceHeight: 1000,
+};
+
+export function recordTouchVisualizationEvent(
+  session: SessionState,
+  command: string,
+  positionals: string[],
+  result: Record<string, unknown> | void,
+  fallback: Record<string, unknown> = {},
+  startedAtMs = Date.now(),
+  finishedAtMs = Date.now(),
+): void {
+  const recording = session.recording;
+  if (!recording) return;
+
+  const merged = { ...fallback, ...(result ?? {}) };
+  const reportedDurationMs =
+    readNumber(merged.effectiveDurationMs) ?? readNumber(merged.durationMs);
+  const tMs = resolveGestureOffsetMs({
+    recordingStartedAt: recording.startedAt,
+    runnerStartedAtUptimeMs:
+      recording.platform === 'ios-device-runner' ? recording.runnerStartedAtUptimeMs : undefined,
+    gestureStartUptimeMs: readNumber(merged.gestureStartUptimeMs),
+    fallbackStartedAtMs: startedAtMs,
+  });
+  const gestureDurationMs = resolveGestureDurationMs({
+    gestureStartUptimeMs: readNumber(merged.gestureStartUptimeMs),
+    gestureEndUptimeMs: readNumber(merged.gestureEndUptimeMs),
+    reportedDurationMs,
+    fallbackStartedAtMs: startedAtMs,
+    fallbackFinishedAtMs: finishedAtMs,
+  });
+  const referenceFrame = resolveEventReferenceFrame(session.snapshot, merged);
+  const events = buildGestureEvents(
+    command,
+    positionals,
+    merged,
+    tMs,
+    gestureDurationMs,
+    referenceFrame,
+  );
+  if (events.length === 0) return;
+  recording.gestureEvents.push(...events);
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'record_touch_visualization_event',
+    data: {
+      session: session.name,
+      command,
+      count: events.length,
+      tMs,
+      gestureDurationMs,
+      kinds: events.map((event) => event.kind),
+    },
+  });
+}
+
+export function augmentTouchVisualizationResult(
+  session: SessionState,
+  command: string,
+  positionals: string[],
+  result: Record<string, unknown> | void,
+): Record<string, unknown> | void {
+  if (command !== 'scroll') return result;
+
+  const referenceFrame = getReferenceFrame(session.snapshot);
+  const merged = { ...(result ?? {}) };
+  const contentDirection = readDirection(merged.direction) ?? readDirection(positionals[0]);
+  if (!contentDirection) return result;
+
+  const amountValue = readNumber(merged.amount) ?? readNumber(positionals[1]);
+  const travelFraction = resolveScrollTravelFraction(amountValue);
+  const fallbackReferenceFrame = referenceFrame ?? DEFAULT_SCROLL_REFERENCE_FRAME;
+  const start = scrollStartPoint(contentDirection, fallbackReferenceFrame, travelFraction);
+  const end = scrollEndPoint(contentDirection, fallbackReferenceFrame, travelFraction);
+
+  return {
+    ...merged,
+    x1: start.x,
+    y1: start.y,
+    x2: end.x,
+    y2: end.y,
+    contentDirection,
+    amount: amountValue,
+    referenceWidth: fallbackReferenceFrame.referenceWidth,
+    referenceHeight: fallbackReferenceFrame.referenceHeight,
+    durationMs: DEFAULT_SWIPE_DURATION_MS,
+  };
+}
+
+type ReferenceFrame = {
+  referenceWidth: number;
+  referenceHeight: number;
+};
+
+type SnapshotReferenceFrameState = SnapshotState & {
+  referenceWidth?: number;
+  referenceHeight?: number;
+};
+
+function buildGestureEvents(
+  command: string,
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  switch (command) {
+    case 'click':
+    case 'press':
+      return buildPressEvents(positionals, result, tMs, referenceFrame);
+    case 'fill':
+    case 'focus':
+      return buildFocusEvents(positionals, result, tMs, referenceFrame);
+    case 'longpress':
+      return buildLongPressEvents(positionals, result, tMs, gestureDurationMs, referenceFrame);
+    case 'scroll':
+      return buildScrollEvents(positionals, result, tMs, gestureDurationMs, referenceFrame);
+    case 'swipe':
+      return buildSwipeEvents(positionals, result, tMs, gestureDurationMs, referenceFrame);
+    case 'pinch':
+      return buildPinchEvents(positionals, result, tMs, gestureDurationMs, referenceFrame);
+    default:
+      return [];
+  }
+}
+
+function buildPressEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x = readNumber(result.x) ?? readNumber(positionals[0]);
+  const y = readNumber(result.y) ?? readNumber(positionals[1]);
+  if (x === undefined || y === undefined) return [];
+
+  const count = clampInt(readNumber(result.count), 1) ?? 1;
+  const intervalMs = clampInt(readNumber(result.intervalMs), 0) ?? 0;
+  const doubleTap = result.doubleTap === true;
+  const holdMs = clampInt(readNumber(result.holdMs), 1);
+  const events: RecordingGestureEvent[] = [];
+
+  for (let index = 0; index < count; index += 1) {
+    const baseTime = tMs + index * intervalMs;
+    if (holdMs !== undefined && holdMs > 0) {
+      events.push(makeLongPressEvent(baseTime, x, y, holdMs, referenceFrame));
+      continue;
+    }
+    events.push(makeTapEvent(baseTime, x, y, referenceFrame));
+    if (doubleTap) {
+      events.push(makeTapEvent(baseTime + DEFAULT_TAP_GAP_MS, x, y, referenceFrame));
+    }
+  }
+  return events;
+}
+
+function buildFocusEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x = readNumber(result.x) ?? readNumber(positionals[0]);
+  const y = readNumber(result.y) ?? readNumber(positionals[1]);
+  if (x === undefined || y === undefined) return [];
+  return [makeTapEvent(tMs, x, y, referenceFrame)];
+}
+
+function buildLongPressEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x = readNumber(result.x) ?? readNumber(positionals[0]);
+  const y = readNumber(result.y) ?? readNumber(positionals[1]);
+  if (x === undefined || y === undefined) return [];
+  const durationMs =
+    clampInt(gestureDurationMs, 1) ??
+    clampInt(readNumber(result.durationMs), 1) ??
+    clampInt(readNumber(positionals[2]), 1) ??
+    800;
+  return [makeLongPressEvent(tMs, x, y, durationMs, referenceFrame)];
+}
+
+function buildSwipeEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x1 = readNumber(result.x1) ?? readNumber(positionals[0]);
+  const y1 = readNumber(result.y1) ?? readNumber(positionals[1]);
+  const x2 = readNumber(result.x2) ?? readNumber(positionals[2]);
+  const y2 = readNumber(result.y2) ?? readNumber(positionals[3]);
+  if (x1 === undefined || y1 === undefined || x2 === undefined || y2 === undefined) return [];
+
+  const durationMs =
+    clampInt(gestureDurationMs, 1) ??
+    clampInt(readNumber(result.effectiveDurationMs), 1) ??
+    clampInt(readNumber(result.durationMs), 1) ??
+    clampInt(readNumber(positionals[4]), 1) ??
+    DEFAULT_SWIPE_DURATION_MS;
+  const count = clampInt(readNumber(result.count), 1) ?? 1;
+  const pauseMs = clampInt(readNumber(result.pauseMs), 0) ?? 0;
+  const pattern = result.pattern === 'ping-pong' ? 'ping-pong' : 'one-way';
+  const events: RecordingGestureEvent[] = [];
+
+  for (let index = 0; index < count; index += 1) {
+    const reverse = pattern === 'ping-pong' && index % 2 === 1;
+    const startX = reverse ? x2 : x1;
+    const startY = reverse ? y2 : y1;
+    const endX = reverse ? x1 : x2;
+    const endY = reverse ? y1 : y2;
+    const startTime = tMs + index * (durationMs + pauseMs);
+    const kind = classifySwipeKind(startX, startY, endX, endY, referenceFrame);
+    if (kind === 'back-swipe') {
+      events.push({
+        kind: 'back-swipe',
+        tMs: startTime,
+        x: startX,
+        y: startY,
+        x2: endX,
+        y2: endY,
+        ...referenceFrame,
+        durationMs,
+        edge: resolveBackSwipeEdge(startX, endX, referenceFrame),
+      });
+      continue;
+    }
+    events.push({
+      kind: 'swipe',
+      tMs: startTime,
+      x: startX,
+      y: startY,
+      x2: endX,
+      y2: endY,
+      ...referenceFrame,
+      durationMs,
+    });
+  }
+
+  return events;
+}
+
+function buildScrollEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x1 = readNumber(result.x1) ?? readNumber(positionals[0]);
+  const y1 = readNumber(result.y1) ?? readNumber(positionals[1]);
+  const x2 = readNumber(result.x2) ?? readNumber(positionals[2]);
+  const y2 = readNumber(result.y2) ?? readNumber(positionals[3]);
+  const contentDirection =
+    readDirection(result.contentDirection) ?? readDirection(result.direction);
+  if (
+    x1 === undefined ||
+    y1 === undefined ||
+    x2 === undefined ||
+    y2 === undefined ||
+    !contentDirection
+  ) {
+    return [];
+  }
+
+  const durationMs = clampInt(gestureDurationMs, 1) ?? DEFAULT_SWIPE_DURATION_MS;
+  const amount = readNumber(result.amount) ?? readNumber(positionals[1]);
+  return [
+    {
+      kind: 'scroll',
+      tMs,
+      x: x1,
+      y: y1,
+      x2,
+      y2,
+      ...referenceFrame,
+      durationMs,
+      contentDirection,
+      ...(amount !== undefined ? { amount } : {}),
+    },
+  ];
+}
+
+function buildPinchEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const x = readNumber(result.x) ?? readNumber(positionals[1]);
+  const y = readNumber(result.y) ?? readNumber(positionals[2]);
+  const scale = readNumber(result.scale) ?? readNumber(positionals[0]);
+  if (x === undefined || y === undefined || scale === undefined || scale <= 0) return [];
+  return [
+    {
+      kind: 'pinch',
+      tMs,
+      x,
+      y,
+      ...referenceFrame,
+      scale,
+      durationMs: clampInt(gestureDurationMs, 1) ?? DEFAULT_PINCH_DURATION_MS,
+    },
+  ];
+}
+
+function makeTapEvent(
+  tMs: number,
+  x: number,
+  y: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent {
+  return { kind: 'tap', tMs, x, y, ...referenceFrame };
+}
+
+function makeLongPressEvent(
+  tMs: number,
+  x: number,
+  y: number,
+  durationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent {
+  return { kind: 'longpress', tMs, x, y, ...referenceFrame, durationMs };
+}
+
+function classifySwipeKind(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  referenceFrame?: ReferenceFrame,
+): 'swipe' | 'back-swipe' {
+  if (!referenceFrame) return 'swipe';
+  const horizontalDistance = Math.abs(x2 - x1);
+  const verticalDistance = Math.abs(y2 - y1);
+  if (horizontalDistance <= verticalDistance * 1.25) return 'swipe';
+
+  const edgeInset = referenceFrame.referenceWidth * 0.08;
+  if (x1 <= edgeInset && x2 > x1) return 'back-swipe';
+  if (x1 >= referenceFrame.referenceWidth - edgeInset && x2 < x1) return 'back-swipe';
+  return 'swipe';
+}
+
+function resolveBackSwipeEdge(
+  startX: number,
+  endX: number,
+  referenceFrame?: ReferenceFrame,
+): 'left' | 'right' {
+  if (referenceFrame) {
+    const edgeInset = referenceFrame.referenceWidth * 0.08;
+    if (startX <= edgeInset) return 'left';
+    if (startX >= referenceFrame.referenceWidth - edgeInset) return 'right';
+  }
+  return endX >= startX ? 'left' : 'right';
+}
+
+function inferReferenceFrame(nodes: SnapshotNode[]): ReferenceFrame | undefined {
+  const viewportRect = inferViewportRect(nodes);
+  if (!viewportRect) return undefined;
+  return {
+    referenceWidth: viewportRect.width,
+    referenceHeight: viewportRect.height,
+  };
+}
+
+function getReferenceFrame(snapshot: SnapshotState | undefined): ReferenceFrame | undefined {
+  if (!snapshot) return undefined;
+  const cachedSnapshot = snapshot as SnapshotReferenceFrameState;
+  if (
+    typeof cachedSnapshot.referenceWidth === 'number' &&
+    cachedSnapshot.referenceWidth > 0 &&
+    typeof cachedSnapshot.referenceHeight === 'number' &&
+    cachedSnapshot.referenceHeight > 0
+  ) {
+    return {
+      referenceWidth: cachedSnapshot.referenceWidth,
+      referenceHeight: cachedSnapshot.referenceHeight,
+    };
+  }
+  const inferred = inferReferenceFrame(snapshot.nodes ?? []);
+  if (!inferred) return undefined;
+  cachedSnapshot.referenceWidth = inferred.referenceWidth;
+  cachedSnapshot.referenceHeight = inferred.referenceHeight;
+  return inferred;
+}
+
+function resolveEventReferenceFrame(
+  snapshot: SnapshotState | undefined,
+  result: Record<string, unknown>,
+): ReferenceFrame | undefined {
+  const snapshotReferenceFrame = getReferenceFrame(snapshot);
+  if (snapshotReferenceFrame) return snapshotReferenceFrame;
+
+  const referenceWidth = readNumber(result.referenceWidth);
+  const referenceHeight = readNumber(result.referenceHeight);
+  if (
+    referenceWidth !== undefined &&
+    referenceWidth > 0 &&
+    referenceHeight !== undefined &&
+    referenceHeight > 0
+  ) {
+    return { referenceWidth, referenceHeight };
+  }
+
+  return undefined;
+}
+
+function readDirection(value: unknown): 'up' | 'down' | 'left' | 'right' | undefined {
+  if (typeof value !== 'string') return undefined;
+  switch (value.trim().toLowerCase()) {
+    case 'up':
+    case 'down':
+    case 'left':
+    case 'right':
+      return value.trim().toLowerCase() as 'up' | 'down' | 'left' | 'right';
+    default:
+      return undefined;
+  }
+}
+
+function resolveScrollTravelFraction(amount: number | undefined): number {
+  if (amount === undefined) return DEFAULT_SCROLL_FRACTION;
+  if (!Number.isFinite(amount) || amount <= 0) return DEFAULT_SCROLL_FRACTION;
+  if (amount <= 1) {
+    return clampNumber(amount, MIN_SCROLL_FRACTION, MAX_SCROLL_FRACTION);
+  }
+  return clampNumber(amount / 100, MIN_SCROLL_FRACTION, MAX_SCROLL_FRACTION);
+}
+
+function scrollStartPoint(
+  contentDirection: 'up' | 'down' | 'left' | 'right',
+  referenceFrame: ReferenceFrame,
+  travelFraction: number,
+): { x: number; y: number } {
+  const midX = Math.round(referenceFrame.referenceWidth / 2);
+  const midY = Math.round(referenceFrame.referenceHeight / 2);
+  const travelX = Math.round((referenceFrame.referenceWidth * travelFraction) / 2);
+  const travelY = Math.round((referenceFrame.referenceHeight * travelFraction) / 2);
+
+  switch (contentDirection) {
+    case 'up':
+      return { x: midX, y: midY - travelY };
+    case 'down':
+      return { x: midX, y: midY + travelY };
+    case 'left':
+      return { x: midX - travelX, y: midY };
+    case 'right':
+      return { x: midX + travelX, y: midY };
+  }
+}
+
+function scrollEndPoint(
+  contentDirection: 'up' | 'down' | 'left' | 'right',
+  referenceFrame: ReferenceFrame,
+  travelFraction: number,
+): { x: number; y: number } {
+  const midX = Math.round(referenceFrame.referenceWidth / 2);
+  const midY = Math.round(referenceFrame.referenceHeight / 2);
+  const travelX = Math.round((referenceFrame.referenceWidth * travelFraction) / 2);
+  const travelY = Math.round((referenceFrame.referenceHeight * travelFraction) / 2);
+
+  switch (contentDirection) {
+    case 'up':
+      return { x: midX, y: midY + travelY };
+    case 'down':
+      return { x: midX, y: midY - travelY };
+    case 'left':
+      return { x: midX + travelX, y: midY };
+    case 'right':
+      return { x: midX - travelX, y: midY };
+  }
+}
+
+function inferViewportRect(nodes: SnapshotNode[]): Rect | undefined {
+  const candidate = nodes
+    .filter((node) => isViewportNode(node.type) && isValidRect(node.rect))
+    .map((node) => node.rect)
+    .sort(
+      (left, right) =>
+        (right?.width ?? 0) * (right?.height ?? 0) - (left?.width ?? 0) * (left?.height ?? 0),
+    )[0];
+  if (candidate) return candidate;
+
+  const rects = nodes.map((node) => node.rect).filter(isValidRect);
+  if (rects.length === 0) return undefined;
+
+  const width = Math.max(...rects.map((rect) => rect.x + rect.width));
+  const height = Math.max(...rects.map((rect) => rect.y + rect.height));
+  if (width <= 0 || height <= 0) return undefined;
+  return { x: 0, y: 0, width, height };
+}
+
+function isViewportNode(type: string | undefined): boolean {
+  if (!type) return false;
+  const normalized = type.toLowerCase();
+  return normalized.includes('application') || normalized.includes('window');
+}
+
+function isValidRect(rect: Rect | undefined): rect is Rect {
+  return !!rect && rect.width > 0 && rect.height > 0;
+}
+
+function readNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string' || value.trim().length === 0) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function clampInt(value: number | undefined, min: number): number | undefined {
+  if (value === undefined) return undefined;
+  const normalized = Math.floor(value);
+  return normalized >= min ? normalized : undefined;
+}
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
diff --git a/src/daemon/recording-telemetry.ts b/src/daemon/recording-telemetry.ts
new file mode 100644
index 000000000..59d730f08
--- /dev/null
+++ b/src/daemon/recording-telemetry.ts
@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RecordingGestureEvent } from './types.ts';
+
+type RecordingTelemetryEnvelope = {
+  version: 1;
+  generatedAt: string;
+  events: RecordingGestureEvent[];
+};
+
+export function deriveRecordingTelemetryPath(videoPath: string): string {
+  const parsed = path.parse(videoPath);
+  return path.join(parsed.dir, `${parsed.name}.gesture-telemetry.json`);
+}
+
+export function trimRecordingTelemetryEvents(
+  events: RecordingGestureEvent[],
+  trimStartMs: number,
+): RecordingGestureEvent[] {
+  const normalizedEvents =
+    trimStartMs > 0
+      ? events.flatMap((event) => {
+          const adjustedStartMs = event.tMs - trimStartMs;
+          const durationMs = 'durationMs' in event ? event.durationMs : undefined;
+          const adjustedEndMs =
+            typeof durationMs === 'number' ? adjustedStartMs + durationMs : adjustedStartMs;
+
+          if (adjustedEndMs <= 0) {
+            return [];
+          }
+
+          return [
+            {
+              ...event,
+              tMs: Math.max(0, adjustedStartMs),
+            },
+          ];
+        })
+      : events.map((event) => ({ ...event }));
+
+  return normalizedEvents.sort((left, right) => left.tMs - right.tMs);
+}
+
+export function writeRecordingTelemetry(params: {
+  videoPath: string;
+  events: RecordingGestureEvent[];
+}): string {
+  const telemetryPath = deriveRecordingTelemetryPath(params.videoPath);
+  const payload: RecordingTelemetryEnvelope = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    events: trimRecordingTelemetryEvents(params.events, 0),
+  };
+  fs.writeFileSync(telemetryPath, JSON.stringify(payload, null, 2));
+  return telemetryPath;
+}
diff --git a/src/daemon/recording-timing.ts b/src/daemon/recording-timing.ts
new file mode 100644
index 000000000..71225a2ab
--- /dev/null
+++ b/src/daemon/recording-timing.ts
@@ -0,0 +1,37 @@
+type GestureTimingSource = {
+  recordingStartedAt: number;
+  runnerStartedAtUptimeMs?: number;
+  gestureStartUptimeMs?: number;
+  fallbackStartedAtMs: number;
+};
+
+type GestureDurationSource = {
+  gestureStartUptimeMs?: number;
+  gestureEndUptimeMs?: number;
+  reportedDurationMs?: number;
+  fallbackStartedAtMs: number;
+  fallbackFinishedAtMs: number;
+};
+
+export function resolveGestureOffsetMs(source: GestureTimingSource): number {
+  if (
+    typeof source.runnerStartedAtUptimeMs === 'number' &&
+    typeof source.gestureStartUptimeMs === 'number'
+  ) {
+    return Math.max(0, source.gestureStartUptimeMs - source.runnerStartedAtUptimeMs);
+  }
+  return Math.max(0, source.fallbackStartedAtMs - source.recordingStartedAt);
+}
+
+export function resolveGestureDurationMs(source: GestureDurationSource): number {
+  if (
+    typeof source.gestureStartUptimeMs === 'number' &&
+    typeof source.gestureEndUptimeMs === 'number'
+  ) {
+    return Math.max(0, source.gestureEndUptimeMs - source.gestureStartUptimeMs);
+  }
+  if (typeof source.reportedDurationMs === 'number') {
+    return Math.max(0, source.reportedDurationMs);
+  }
+  return Math.max(0, source.fallbackFinishedAtMs - source.fallbackStartedAtMs);
+}
diff --git a/src/daemon/request-router.ts b/src/daemon/request-router.ts
index d843a2ce3..1eefe3aea 100644
--- a/src/daemon/request-router.ts
+++ b/src/daemon/request-router.ts
@@ -27,6 +27,10 @@ import {
 } from '../utils/diagnostics.ts';
 import { resolveLeaseScope } from './lease-context.ts';
 import type { LeaseRegistry } from './lease-registry.ts';
+import {
+  augmentTouchVisualizationResult,
+  recordTouchVisualizationEvent,
+} from './recording-gestures.ts';
 
 const selectorValidationExemptCommands = new Set([
   'session_list',
@@ -354,6 +358,7 @@ export function createRequestHandler(
             command === 'screenshot' && resolvedOut
               ? { ...(lockedReq.flags ?? {}), out: resolvedOut }
               : (lockedReq.flags ?? {});
+          const actionStartedAt = Date.now();
           const data = await dispatch(session.device, command, resolvedPositionals, resolvedOut, {
             ...contextFromFlags(
               logPath,
@@ -362,6 +367,22 @@ export function createRequestHandler(
               session.trace?.outPath,
             ),
           });
+          const actionFinishedAt = Date.now();
+          const visualizationData = augmentTouchVisualizationResult(
+            session,
+            command,
+            resolvedPositionals,
+            data as Record<string, unknown> | void,
+          );
+          recordTouchVisualizationEvent(
+            session,
+            command,
+            resolvedPositionals,
+            visualizationData as Record<string, unknown> | void,
+            (lockedReq.flags ?? {}) as Record<string, unknown>,
+            actionStartedAt,
+            actionFinishedAt,
+          );
           sessionStore.recordAction(session, {
             command,
             positionals: recordedPositionals,
diff --git a/src/daemon/session-store.ts b/src/daemon/session-store.ts
index 9147001c4..de116aced 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -235,6 +235,8 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     relaunch,
     saveScript,
     noRecord,
+    fps,
+    hideTouches,
     count,
     intervalMs,
     holdMs,
@@ -263,6 +265,8 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     relaunch,
     saveScript,
     noRecord,
+    fps,
+    hideTouches,
     count,
     intervalMs,
     holdMs,
@@ -364,6 +368,22 @@ function formatActionLine(action: SessionAction): string {
     appendRuntimeHintFlags(parts, action.flags);
     return parts.join(' ');
   }
+  if (action.command === 'record') {
+    const [subcommand, ...rest] = action.positionals ?? [];
+    if (subcommand) {
+      parts.push(formatScriptArgQuoteIfNeeded(subcommand));
+    }
+    for (const positional of rest) {
+      parts.push(formatScriptArg(positional));
+    }
+    if (typeof action.flags?.fps === 'number') {
+      parts.push('--fps', String(action.flags.fps));
+    }
+    if (action.flags?.hideTouches) {
+      parts.push('--hide-touches');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatScriptArg(positional));
   }
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 09dd7597c..8b58ac160 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -69,6 +69,52 @@ export type DaemonResponse =
       };
     };
 
+type RecordingTelemetryBase = {
+  tMs: number;
+  x: number;
+  y: number;
+  referenceWidth?: number;
+  referenceHeight?: number;
+};
+
+type RecordingTelemetryTravel = RecordingTelemetryBase & {
+  x2: number;
+  y2: number;
+  durationMs: number;
+};
+
+export type RecordingGestureEvent =
+  | (RecordingTelemetryBase & {
+      kind: 'tap' | 'longpress';
+      durationMs?: number;
+    })
+  | (RecordingTelemetryTravel & {
+      kind: 'swipe';
+    })
+  | (RecordingTelemetryTravel & {
+      kind: 'scroll';
+      contentDirection: 'up' | 'down' | 'left' | 'right';
+      amount?: number;
+    })
+  | (RecordingTelemetryTravel & {
+      kind: 'back-swipe';
+      edge: 'left' | 'right';
+    })
+  | (RecordingTelemetryBase & {
+      kind: 'pinch';
+      scale: number;
+      durationMs: number;
+    });
+
+type SessionRecordingBase = {
+  outPath: string;
+  clientOutPath?: string;
+  telemetryPath?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+};
+
 export type SessionState = {
   name: string;
   device: DeviceInfo;
@@ -84,20 +130,23 @@ export type SessionState = {
   saveScriptPath?: string;
   actions: SessionAction[];
   recording?:
-    | {
-        platform: 'ios' | 'android';
-        outPath: string;
-        clientOutPath?: string;
-        remotePath?: string;
+    | (SessionRecordingBase & {
+        platform: 'ios';
         child: ReturnType<typeof import('node:child_process').spawn>;
         wait: Promise<ExecResult>;
-      }
-    | {
+        remotePath?: string;
+      })
+    | (SessionRecordingBase & {
+        platform: 'android';
+        remotePath: string;
+        remotePid: string;
+      })
+    | (SessionRecordingBase & {
         platform: 'ios-device-runner' | 'macos-runner';
-        outPath: string;
-        clientOutPath?: string;
         remotePath?: string;
-      };
+        runnerStartedAtUptimeMs?: number;
+        targetAppReadyUptimeMs?: number;
+      });
   /** Session-scoped app log stream; logs written to outPath for agent to grep */
   appLog?: {
     platform: Platform;
diff --git a/src/platforms/ios/recording-overlay.ts b/src/platforms/ios/recording-overlay.ts
new file mode 100644
index 000000000..e3ea0ec15
--- /dev/null
+++ b/src/platforms/ios/recording-overlay.ts
@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCmd } from '../../utils/exec.ts';
+import { AppError } from '../../utils/errors.ts';
+import { waitForPlayableVideo, waitForStableFile } from '../../utils/video.ts';
+
+function resolveScriptPath(scriptName: string): string {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const scriptCandidates = [
+    fileURLToPath(new URL(`./${scriptName}`, import.meta.url)),
+    path.resolve(moduleDir, `../../../ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`),
+    path.resolve(
+      moduleDir,
+      `../../../../ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`,
+    ),
+    path.resolve(process.cwd(), `ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`),
+  ];
+
+  for (const candidate of scriptCandidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new AppError('COMMAND_FAILED', `Missing recording helper script: ${scriptName}`, {
+    scriptName,
+    searchedPaths: scriptCandidates,
+  });
+}
+
+const overlayScriptPath = resolveScriptPath('recording-overlay.swift');
+const trimScriptPath = resolveScriptPath('recording-trim.swift');
+
+async function exportProcessedVideo(params: {
+  videoPath: string;
+  scriptPath: string;
+  scriptArgs: string[];
+  commandDescription: string;
+}): Promise<void> {
+  const { videoPath, scriptPath, scriptArgs, commandDescription } = params;
+  await waitForStableFile(videoPath);
+  await waitForPlayableVideo(videoPath);
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-record-overlay-'));
+  const inputPath = path.join(tempDir, `input${path.extname(videoPath) || '.mp4'}`);
+  const outputPath = path.join(tempDir, path.basename(videoPath));
+  const homePath = path.join(tempDir, 'home');
+  const moduleCachePath = path.join(tempDir, 'module-cache');
+
+  fs.copyFileSync(videoPath, inputPath);
+  fs.mkdirSync(homePath, { recursive: true });
+  fs.mkdirSync(moduleCachePath, { recursive: true });
+  try {
+    await runCmd(
+      'xcrun',
+      ['swift', scriptPath, '--input', inputPath, '--output', outputPath, ...scriptArgs],
+      {
+        timeoutMs: 120_000,
+        env: {
+          ...process.env,
+          HOME: homePath,
+          CLANG_MODULE_CACHE_PATH: moduleCachePath,
+        },
+      },
+    );
+    await waitForPlayableVideo(outputPath);
+    fs.copyFileSync(outputPath, videoPath);
+  } catch (error) {
+    const cause =
+      error instanceof AppError
+        ? error
+        : new AppError(
+            'COMMAND_FAILED',
+            String(error),
+            undefined,
+            error instanceof Error ? error : undefined,
+          );
+    throw new AppError(
+      'COMMAND_FAILED',
+      commandDescription,
+      {
+        videoPath,
+        script: scriptPath,
+        stderr: cause.details?.stderr,
+        stdout: cause.details?.stdout,
+        exitCode: cause.details?.exitCode,
+        processExitError: cause.details?.processExitError,
+      },
+      cause,
+    );
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function trimRecordingStart(params: {
+  videoPath: string;
+  trimStartMs: number;
+}): Promise<void> {
+  const { videoPath, trimStartMs } = params;
+  if (!(trimStartMs > 0)) return;
+
+  await exportProcessedVideo({
+    videoPath,
+    scriptPath: trimScriptPath,
+    scriptArgs: ['--trim-start-ms', String(trimStartMs)],
+    commandDescription: 'Failed to trim the start of the iOS recording',
+  });
+}
+
+export async function overlayRecordingTouches(params: {
+  videoPath: string;
+  telemetryPath: string;
+  targetLabel?: string;
+}): Promise<void> {
+  const { videoPath, telemetryPath, targetLabel = 'recording' } = params;
+  await exportProcessedVideo({
+    videoPath,
+    scriptPath: overlayScriptPath,
+    scriptArgs: ['--events', telemetryPath],
+    commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
+  });
+}
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index 3595a683d..ddc3861d8 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -415,6 +415,15 @@ test('parseArgs recognizes record --fps flag', () => {
   assert.equal(parsed.flags.fps, 30);
 });
 
+test('parseArgs recognizes record --hide-touches flag', () => {
+  const parsed = parseArgs(['record', 'start', './capture.mp4', '--hide-touches'], {
+    strictFlags: true,
+  });
+  assert.equal(parsed.command, 'record');
+  assert.deepEqual(parsed.positionals, ['start', './capture.mp4']);
+  assert.equal(parsed.flags.hideTouches, true);
+});
+
 test('parseArgs rejects invalid record --fps range', () => {
   assert.throws(
     () => parseArgs(['record', 'start', './capture.mp4', '--fps', '0'], { strictFlags: true }),
@@ -720,6 +729,13 @@ test('command usage shows command and global flags separately', () => {
   assert.match(help, /--platform ios\|macos\|android\|apple/);
 });
 
+test('command usage shows record touch-overlay opt-out flag', () => {
+  const help = usageForCommand('record');
+  if (help === null) throw new Error('Expected command help text');
+  assert.match(help, /record start \[path\] \[--fps <n>\] \[--hide-touches\] \| record stop/);
+  assert.match(help, /--hide-touches/);
+});
+
 test('command usage keeps detailed descriptions', () => {
   const help = usageForCommand('metro');
   if (help === null) throw new Error('Expected command help text');
diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
index 635c399ee..87b618fdb 100644
--- a/src/utils/command-schema.ts
+++ b/src/utils/command-schema.ts
@@ -56,6 +56,7 @@ export type CliFlags = {
   appsFilter?: 'user-installed' | 'all';
   count?: number;
   fps?: number;
+  hideTouches?: boolean;
   intervalMs?: number;
   holdMs?: number;
   jitterPx?: number;
@@ -508,6 +509,13 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageLabel: '--fps <n>',
     usageDescription: 'Record: target frames per second (iOS physical device runner)',
   },
+  {
+    key: 'hideTouches',
+    names: ['--hide-touches'],
+    type: 'boolean',
+    usageLabel: '--hide-touches',
+    usageDescription: 'Record: disable touch overlays in the final video',
+  },
   {
     key: 'intervalMs',
     names: ['--interval-ms'],
@@ -1064,12 +1072,12 @@ const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     allowedFlags: [],
   },
   record: {
-    usageOverride: 'record start [path] [--fps <n>] | record stop',
+    usageOverride: 'record start [path] [--fps <n>] [--hide-touches] | record stop',
     listUsageOverride: 'record start [path] | record stop',
     helpDescription: 'Start/stop screen recording',
     summary: 'Start or stop screen recording',
     positionalArgs: ['start|stop', 'path?'],
-    allowedFlags: ['fps'],
+    allowedFlags: ['fps', 'hideTouches'],
   },
   trace: {
     usageOverride: 'trace start [path] | trace stop [path]',
diff --git a/src/utils/video.ts b/src/utils/video.ts
new file mode 100644
index 000000000..9c7272fc8
--- /dev/null
+++ b/src/utils/video.ts
@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import { runCmd } from './exec.ts';
+
+const VIDEO_VALIDATION_SCRIPT = `
+import Foundation
+import AVFoundation
+
+let url = URL(fileURLWithPath: CommandLine.arguments[1])
+let asset = AVURLAsset(url: url)
+let semaphore = DispatchSemaphore(value: 0)
+var exitCode: Int32 = 1
+
+Task {
+  defer { semaphore.signal() }
+  do {
+    let playable = try await asset.load(.isPlayable)
+    let duration = try await asset.load(.duration)
+    if playable && duration.isValid && !duration.isIndefinite && CMTimeGetSeconds(duration) > 0 {
+      exitCode = 0
+    }
+  } catch {
+    exitCode = 1
+  }
+}
+
+semaphore.wait()
+exit(exitCode)
+`.trim();
+
+export async function waitForStableFile(
+  filePath: string,
+  options: { pollMs?: number; attempts?: number } = {},
+): Promise<void> {
+  const pollMs = options.pollMs ?? 150;
+  const attempts = options.attempts ?? 12;
+  let previousSize: number | undefined;
+  let stableCount = 0;
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    let currentSize = 0;
+    try {
+      currentSize = fs.statSync(filePath).size;
+    } catch {
+      currentSize = 0;
+    }
+
+    if (currentSize > 0 && currentSize === previousSize) {
+      stableCount += 1;
+      if (stableCount >= 2) {
+        return;
+      }
+    } else {
+      stableCount = 0;
+    }
+
+    previousSize = currentSize;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+export async function isPlayableVideo(filePath: string): Promise<boolean> {
+  const result = await runCmd('swift', ['-', filePath], {
+    stdin: VIDEO_VALIDATION_SCRIPT,
+    allowFailure: true,
+    timeoutMs: 10_000,
+  });
+  return result.exitCode === 0;
+}
+
+export async function waitForPlayableVideo(
+  filePath: string,
+  options: { pollMs?: number; attempts?: number } = {},
+): Promise<void> {
+  const pollMs = options.pollMs ?? 150;
+  const attempts = options.attempts ?? 12;
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (await isPlayableVideo(filePath)) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}

From 594b1af9193d87afdbee7c1df6fe5c5e3d316cf4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 21 Mar 2026 18:09:00 +0100
Subject: [PATCH 02/11] fix: stabilize recording validation and telemetry
 artifacts

---
 .../RunnerTests+CommandExecution.swift        |  2 +-
 .../RunnerTests+ScreenRecorder.swift          | 10 ++--
 .../RunnerTests.swift                         |  1 +
 .../handlers/__tests__/record-trace.test.ts   | 47 +++++++++++++++++--
 src/daemon/handlers/record-trace-recording.ts | 12 ++++-
 src/utils/video.ts                            |  9 ++++
 website/docs/docs/commands.md                 |  2 +-
 website/docs/docs/introduction.md             |  2 +-
 8 files changed, 72 insertions(+), 13 deletions(-)

diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index a91175782..4eb77377f 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -175,7 +175,7 @@ extension RunnerTests {
       }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
-        let fpsLabel = command.fps.map(String.init) ?? "max"
+        let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
         NSLog(
           "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
           requestedOutPath,
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
index 6e0b4780f..9c9db51f3 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
@@ -7,13 +7,11 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
-    private let uncappedFrameInterval: TimeInterval = 0.001
-    private var uncappedTimestampTimescale: Int32 {
-      Int32(max(1, Int((1.0 / uncappedFrameInterval).rounded())))
+    private var effectiveFps: Int32 {
+      max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
     private var frameInterval: TimeInterval {
-      guard let fps else { return uncappedFrameInterval }
-      return 1.0 / Double(fps)
+      1.0 / Double(effectiveFps)
     }
     private let queue = DispatchQueue(label: "agent-device.runner.recorder")
     private let lock = NSLock()
@@ -206,7 +204,7 @@ extension RunnerTests {
         recordingStartUptime = nowUptime
       }
       let elapsed = max(0, nowUptime - (recordingStartUptime ?? nowUptime))
-      let timescale = fps ?? uncappedTimestampTimescale
+      let timescale = effectiveFps
       var timestampValue = Int64((elapsed * Double(timescale)).rounded(.down))
       if timestampValue <= lastTimestampValue {
         timestampValue = lastTimestampValue + 1
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index cf1049736..df3c983be 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -29,6 +29,7 @@ final class RunnerTests: XCTestCase {
   }
 
   static let springboardBundleId = "com.apple.springboard"
+  static let defaultRecordingFps: Int32 = 15
   var listener: NWListener?
   var doneExpectation: XCTestExpectation?
   let app = XCUIApplication()
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index bae1c9f5a..706628bd6 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -69,6 +69,7 @@ async function runRecordCommand(params: {
   logPath?: string;
   cwd?: string;
   flags?: { fps?: number; hideTouches?: boolean };
+  clientArtifactPaths?: Record<string, string>;
 }) {
   return handleRecordTraceCommands({
     req: {
@@ -77,7 +78,15 @@ async function runRecordCommand(params: {
       command: 'record',
       positionals: params.positionals,
       flags: params.flags ?? {},
-      meta: params.cwd ? { cwd: params.cwd } : undefined,
+      meta:
+        params.cwd || params.clientArtifactPaths
+          ? {
+              ...(params.cwd ? { cwd: params.cwd } : {}),
+              ...(params.clientArtifactPaths
+                ? { clientArtifactPaths: params.clientArtifactPaths }
+                : {}),
+            }
+          : undefined,
     },
     sessionName: params.sessionName,
     sessionStore: params.sessionStore,
@@ -216,8 +225,9 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
   assert.equal(responseStop?.data?.telemetryPath, `${finalOut}.gesture-telemetry.json`);
   assert.deepEqual(
     responseStop?.data?.artifacts?.map((artifact) => artifact.field),
-    ['outPath', 'gestureTelemetry'],
+    ['outPath', 'telemetryPath'],
   );
+  assert.equal(responseStop?.data?.artifacts?.[1]?.path, `${finalOut}.gesture-telemetry.json`);
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
@@ -249,7 +259,6 @@ test('record start/stop uses runner on macOS desktop sessions', async () => {
     traceLogPath: undefined,
   });
   assert.equal(sessionStore.get(sessionName)?.recording?.platform, 'macos-runner');
-
   const responseStop = await runRecordCommand({
     sessionStore,
     sessionName,
@@ -266,6 +275,38 @@ test('record start/stop uses runner on macOS desktop sessions', async () => {
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
+test('record stop derives telemetry artifact local path from client outPath', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-remote-artifacts';
+  const session = makeIosDeviceSession(sessionName, 'com.atebits.Tweetie2');
+  sessionStore.set(sessionName, session);
+
+  const runnerCalls: RunnerCall[] = [];
+  const runCmdCalls: Array<{ cmd: string; args: string[] }> = [];
+  const deps = makeIosDeviceRunnerDeps(runnerCalls, runCmdCalls);
+  const finalOut = path.join(os.tmpdir(), `agent-device-test-record-${Date.now()}.mp4`);
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', finalOut],
+    deps,
+    clientArtifactPaths: { outPath: finalOut },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps,
+  });
+
+  assert.equal(responseStop?.ok, true);
+  assert.equal(responseStop?.data?.artifacts?.[1]?.field, 'telemetryPath');
+  assert.equal(responseStop?.data?.artifacts?.[1]?.localPath, `${finalOut}.gesture-telemetry.json`);
+  assert.equal(responseStop?.data?.telemetryPath, `${finalOut}.gesture-telemetry.json`);
+});
+
 test('record start resolves relative output path from request cwd', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-cwd';
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index f61bcb269..60a517eee 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -595,8 +595,9 @@ function buildRecordStopResponse(
   ];
   if (recording.telemetryPath) {
     artifacts.push({
-      field: 'gestureTelemetry',
+      field: 'telemetryPath',
       path: recording.telemetryPath,
+      localPath: deriveClientTelemetryPath(recording),
       fileName: path.basename(recording.telemetryPath),
     });
   }
@@ -613,6 +614,15 @@ function buildRecordStopResponse(
   };
 }
 
+function deriveClientTelemetryPath(
+  recording: NonNullable<SessionState['recording']>,
+): string | undefined {
+  if (!recording.clientOutPath) {
+    return undefined;
+  }
+  return `${recording.clientOutPath}.gesture-telemetry.json`;
+}
+
 export async function handleRecordCommand(params: {
   req: DaemonRequest;
   sessionName: string;
diff --git a/src/utils/video.ts b/src/utils/video.ts
index 9c7272fc8..c7e776811 100644
--- a/src/utils/video.ts
+++ b/src/utils/video.ts
@@ -64,6 +64,15 @@ export async function isPlayableVideo(filePath: string): Promise<boolean> {
     allowFailure: true,
     timeoutMs: 10_000,
   });
+  if (
+    result.exitCode !== 0 &&
+    typeof result.stderr === 'string' &&
+    /\b(swift: command not found|avfoundation\b|no such module|unable to find utility|xcrun: error)\b/i.test(
+      result.stderr,
+    )
+  ) {
+    return true;
+  }
   return result.exitCode === 0;
 }
 
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 813deceaf..b316a890f 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -486,7 +486,7 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical iOS device capture is runner-based and built from repeated `XCUIScreen.main.screenshot()` frames (no native video stream/audio capture).
 - Physical iOS device recording requires an active app session context (`open <app>` first).
 - Physical iOS device capture is best-effort: dropped frames are expected and true 60 FPS is not guaranteed even with `--fps 60`.
-- Physical-device capture defaults to uncapped (max available) FPS.
+- Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
 
 ## Tracing
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index fc39758a8..677b96dac 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -29,7 +29,7 @@ For exploratory QA and bug-hunting workflows, see `skills/dogfood/SKILL.md` in t
   - Simulators use native `simctl io ... recordVideo`.
   - Physical devices use runner screenshot capture (`XCUIScreen.main.screenshot()` frames) stitched into MP4, so FPS is best-effort (not guaranteed 60 even with `--fps 60`).
   - Physical-device recording requires an active app session context (`open <app>` first).
-  - Physical-device recording defaults to uncapped (max available) FPS and supports `--fps` caps.
+  - Physical-device recording defaults to 15 FPS and supports `--fps` caps.
 - Android supports the same core interaction set, plus `push` notification simulation, `clipboard read/write`, and `keyboard status|get|dismiss` via adb shell commands.
 - App-event triggers are available on iOS and Android through app-defined deep-link hooks (`trigger-app-event`), using active session context or explicit device selectors.
 

From 5122ac08621d9c89449fdfa1d4740eeba2509a24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 21 Mar 2026 18:59:27 +0100
Subject: [PATCH 03/11] fix: tighten recording telemetry helpers

---
 .../handlers/__tests__/record-trace.test.ts   | 149 ++++++++++--
 src/daemon/handlers/record-trace-android.ts   | 224 +++++++++---------
 src/daemon/handlers/record-trace-recording.ts |  87 +++----
 src/daemon/handlers/session-replay-script.ts  |  15 +-
 src/daemon/record-trace-errors.ts             |  12 +
 src/daemon/recording-telemetry.ts             |  75 ++++--
 src/daemon/session-record-script.ts           |  18 ++
 src/daemon/session-store.ts                   |  15 +-
 src/platforms/ios/recording-overlay.ts        |  19 +-
 src/utils/__tests__/video.test.ts             |  45 ++++
 src/utils/video.ts                            |  95 ++++++--
 11 files changed, 494 insertions(+), 260 deletions(-)
 create mode 100644 src/daemon/record-trace-errors.ts
 create mode 100644 src/daemon/session-record-script.ts
 create mode 100644 src/utils/__tests__/video.test.ts

diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index 706628bd6..49ff43f84 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { handleRecordTraceCommands } from '../record-trace.ts';
+import { deriveRecordingTelemetryPath } from '../../recording-telemetry.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { SessionState } from '../../types.ts';
 import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../../platforms/ios/runner-client.ts';
@@ -128,7 +129,7 @@ function makeRunnerRecordingDeps(
     runIosRunnerCommand,
     waitForStableFile: async () => {},
     isPlayableVideo: async () => true,
-    writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+    writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
     trimRecordingStart: async () => {},
     overlayRecordingTouches: async () => {},
   };
@@ -143,7 +144,7 @@ function makeRecordDeps(overrides: Partial<RecordTraceDeps> = {}): RecordTraceDe
     runIosRunnerCommand: async () => ({}),
     waitForStableFile: async () => {},
     isPlayableVideo: async () => true,
-    writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+    writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
     trimRecordingStart: async () => {},
     overlayRecordingTouches: async () => {},
     ...overrides,
@@ -222,12 +223,12 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
     '--domain-identifier',
     IOS_RUNNER_CONTAINER_BUNDLE_IDS[0] ?? '',
   ]);
-  assert.equal(responseStop?.data?.telemetryPath, `${finalOut}.gesture-telemetry.json`);
+  assert.equal(responseStop?.data?.telemetryPath, deriveRecordingTelemetryPath(finalOut));
   assert.deepEqual(
     responseStop?.data?.artifacts?.map((artifact) => artifact.field),
     ['outPath', 'telemetryPath'],
   );
-  assert.equal(responseStop?.data?.artifacts?.[1]?.path, `${finalOut}.gesture-telemetry.json`);
+  assert.equal(responseStop?.data?.artifacts?.[1]?.path, deriveRecordingTelemetryPath(finalOut));
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
@@ -303,8 +304,11 @@ test('record stop derives telemetry artifact local path from client outPath', as
 
   assert.equal(responseStop?.ok, true);
   assert.equal(responseStop?.data?.artifacts?.[1]?.field, 'telemetryPath');
-  assert.equal(responseStop?.data?.artifacts?.[1]?.localPath, `${finalOut}.gesture-telemetry.json`);
-  assert.equal(responseStop?.data?.telemetryPath, `${finalOut}.gesture-telemetry.json`);
+  assert.equal(
+    responseStop?.data?.artifacts?.[1]?.localPath,
+    deriveRecordingTelemetryPath(finalOut),
+  );
+  assert.equal(responseStop?.data?.telemetryPath, deriveRecordingTelemetryPath(finalOut));
 });
 
 test('record start resolves relative output path from request cwd', async () => {
@@ -388,7 +392,7 @@ test('record start rejects invalid fps value', async () => {
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -418,7 +422,7 @@ test('record start on iOS device requires active app session context', async ()
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -449,7 +453,7 @@ test('record start returns structured error when iOS runner start fails', async
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -490,7 +494,7 @@ test('record start recovers from stale iOS runner recording state', async () =>
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -538,7 +542,7 @@ test('record start does not stop recording owned by another session during desyn
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -584,7 +588,7 @@ test('record stop clears iOS runner recording state when runner stop fails', asy
       },
       waitForStableFile: async () => {},
       isPlayableVideo: async () => true,
-      writeRecordingTelemetry: ({ videoPath }) => `${videoPath}.gesture-telemetry.json`,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
       trimRecordingStart: async () => {},
       overlayRecordingTouches: async () => {},
     },
@@ -624,7 +628,7 @@ test('record stop trims iOS device recordings from target app readiness before o
       },
       writeRecordingTelemetry: ({ videoPath, events }) => {
         lifecycleCalls.push(`telemetry:${videoPath}:${events.length}`);
-        return `${videoPath}.gesture-telemetry.json`;
+        return deriveRecordingTelemetryPath(videoPath);
       },
       overlayRecordingTouches: async ({ videoPath, telemetryPath }) => {
         lifecycleCalls.push(`overlay:${videoPath}:${telemetryPath}`);
@@ -636,7 +640,7 @@ test('record stop trims iOS device recordings from target app readiness before o
   assert.deepEqual(lifecycleCalls, [
     'trim:/tmp/device.mp4:3250',
     'telemetry:/tmp/device.mp4:1',
-    'overlay:/tmp/device.mp4:/tmp/device.mp4.gesture-telemetry.json',
+    `overlay:/tmp/device.mp4:${deriveRecordingTelemetryPath('/tmp/device.mp4')}`,
   ]);
 });
 
@@ -664,7 +668,8 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
       runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
       runCmdBackground: (cmd, args) => {
         assert.equal(cmd, 'xcrun');
-        assert.deepEqual(args.slice(0, 5), ['simctl', 'io', 'sim-1', 'recordVideo', '-f']);
+        assert.deepEqual(args.slice(0, 4), ['simctl', 'io', 'sim-1', 'recordVideo']);
+        assert.equal(args[4], path.resolve('./sim.mp4'));
         started = true;
         return {
           child: {
@@ -709,6 +714,48 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
   assert.equal(stopped, true);
 });
 
+test('record start does not fail when iOS simulator runner warm-up fails', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-warm-failure';
+  const session = makeSession(sessionName, {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'Simulator',
+    kind: 'simulator',
+    booted: true,
+  });
+  session.appBundleId = 'com.apple.Preferences';
+  sessionStore.set(sessionName, session);
+
+  let started = false;
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim.mp4'],
+    deps: {
+      runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
+      runCmdBackground: () => {
+        started = true;
+        return {
+          child: { kill: () => {} } as any,
+          wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+        };
+      },
+      runIosRunnerCommand: async () => {
+        throw new Error('runner warm-up unavailable');
+      },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
+    },
+  });
+
+  assert.equal(response?.ok, true);
+  assert.equal(started, true);
+});
+
 test('record start/stop overlays Android gestures by default on devices', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-overlay';
@@ -732,14 +779,14 @@ test('record start/stop overlays Android gestures by default on devices', async
       runCmd: async (_cmd, args) => {
         adbCalls.push(args);
         if (
-          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
             args.join(' '),
           )
         ) {
           return { stdout: '4321\n', stderr: '', exitCode: 0 };
         }
         if (
-          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
             args.join(' '),
           )
         ) {
@@ -765,7 +812,7 @@ test('record start/stop overlays Android gestures by default on devices', async
           return { stdout: '', stderr: '', exitCode: 1 };
         }
         if (
-          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
             args.join(' '),
           )
         ) {
@@ -783,7 +830,7 @@ test('record start/stop overlays Android gestures by default on devices', async
   assert.deepEqual(overlayCalls, [
     {
       videoPath: path.resolve('./android.mp4'),
-      telemetryPath: `${path.resolve('./android.mp4')}.gesture-telemetry.json`,
+      telemetryPath: deriveRecordingTelemetryPath(path.resolve('./android.mp4')),
     },
   ]);
 });
@@ -810,14 +857,14 @@ test('record start leaves overlays disabled with --hide-touches', async () => {
     deps: makeRecordDeps({
       runCmd: async (_cmd, args) => {
         if (
-          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
             args.join(' '),
           )
         ) {
           return { stdout: '9999\n', stderr: '', exitCode: 0 };
         }
         if (
-          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
             args.join(' '),
           )
         ) {
@@ -856,14 +903,14 @@ test('record start accepts Android screenrecord before the remote file begins gr
       runCmd: async (_cmd, args) => {
         const command = args.join(' ');
         if (
-          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
             command,
           )
         ) {
           return { stdout: '5555\n', stderr: '', exitCode: 0 };
         }
         if (
-          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
             command,
           )
         ) {
@@ -881,3 +928,59 @@ test('record start accepts Android screenrecord before the remote file begins gr
   assert.equal(response?.ok, true);
   assert.equal(psChecks >= 2, true);
 });
+
+test('record start falls back to /data/local/tmp when /sdcard is unavailable on Android', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-fallback-path';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        if (
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            command,
+          )
+        ) {
+          return { stdout: 'permission denied\n', stderr: '', exitCode: 1 };
+        }
+        if (
+          /^-s emulator-5554 shell screenrecord \/data\/local\/tmp\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '7777\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  assert.equal(response?.ok, true);
+  const recording = sessionStore.get(sessionName)?.recording;
+  assert.equal(recording?.platform, 'android');
+  assert.match(
+    recording?.remotePath ?? '',
+    /^\/data\/local\/tmp\/agent-device-recording-\d+\.mp4$/,
+  );
+});
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 33aab241c..58835abea 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -1,12 +1,14 @@
 import fs from 'node:fs';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import type { DaemonResponse, SessionState } from '../types.ts';
+import { persistRecordingTelemetry } from '../recording-telemetry.ts';
+import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import type { RecordTraceDeps } from './record-trace-recording.ts';
 
 const ANDROID_REMOTE_FILE_POLL_MS = 250;
 const ANDROID_REMOTE_FILE_ATTEMPTS = 20;
-const ANDROID_LOCAL_VIDEO_ATTEMPTS = 6;
-const ANDROID_LOCAL_VIDEO_POLL_MS = 500;
+const ANDROID_LOCAL_VIDEO_ATTEMPTS = 2;
+const ANDROID_LOCAL_VIDEO_RETRY_DELAY_MS = 750;
 const ANDROID_PROCESS_EXIT_POLL_MS = 250;
 const ANDROID_PROCESS_EXIT_ATTEMPTS = 40;
 const ANDROID_RECORDING_READY_ATTEMPTS = 8;
@@ -19,19 +21,6 @@ type AndroidRecordingBase = Pick<
   'outPath' | 'clientOutPath' | 'telemetryPath' | 'startedAt' | 'showTouches' | 'gestureEvents'
 >;
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function failedExecMessage(
-  result: { stdout: string; stderr: string; exitCode: number },
-  command: string,
-): string {
-  return (
-    result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.exitCode}`
-  );
-}
-
 function parseAndroidRemotePid(stdout: string): string | undefined {
   return stdout
     .split(/\r?\n/)
@@ -40,47 +29,6 @@ function parseAndroidRemotePid(stdout: string): string | undefined {
     .at(-1);
 }
 
-function inspectMp4TopLevelAtoms(filePath: string): string[] {
-  try {
-    const fd = fs.openSync(filePath, 'r');
-    try {
-      const size = fs.fstatSync(fd).size;
-      let offset = 0;
-      const atoms: string[] = [];
-      while (offset + 8 <= size && atoms.length < 12) {
-        const header = Buffer.alloc(8);
-        const bytesRead = fs.readSync(fd, header, 0, 8, offset);
-        if (bytesRead < 8) {
-          break;
-        }
-
-        let atomSize = header.readUInt32BE(0);
-        const atomType = header.toString('latin1', 4, 8);
-        atoms.push(atomType);
-
-        if (atomSize === 1) {
-          const extended = Buffer.alloc(8);
-          const extendedRead = fs.readSync(fd, extended, 0, 8, offset + 8);
-          if (extendedRead < 8) {
-            break;
-          }
-          atomSize = Number(extended.readBigUInt64BE(0));
-        }
-
-        if (!Number.isFinite(atomSize) || atomSize <= 0) {
-          break;
-        }
-        offset += atomSize;
-      }
-      return atoms;
-    } finally {
-      fs.closeSync(fd);
-    }
-  } catch {
-    return [];
-  }
-}
-
 async function isAndroidProcessRunning(
   deps: RecordTraceDeps,
   deviceId: string,
@@ -150,8 +98,6 @@ async function waitForAndroidRecordingReady(
   remotePath: string,
   remotePid: string,
 ): Promise<boolean> {
-  let runningPolls = 0;
-
   for (let attempt = 0; attempt < ANDROID_RECORDING_READY_ATTEMPTS; attempt += 1) {
     const statResult = await deps.runCmd(
       'adb',
@@ -167,15 +113,17 @@ async function waitForAndroidRecordingReady(
       return false;
     }
 
-    runningPolls += 1;
-    if (runningPolls >= ANDROID_RECORDING_READY_MIN_RUNNING_POLLS) {
+    // Some Android builds keep the output file at zero bytes briefly after screenrecord starts.
+    // Once the process stays alive for a couple of polls, treat recording as ready and let stop
+    // validation handle final container/playability checks.
+    if (attempt + 1 >= ANDROID_RECORDING_READY_MIN_RUNNING_POLLS) {
       return true;
     }
 
     await new Promise((resolve) => setTimeout(resolve, ANDROID_REMOTE_FILE_POLL_MS));
   }
 
-  return runningPolls >= ANDROID_RECORDING_READY_MIN_RUNNING_POLLS;
+  return false;
 }
 
 async function copyAndroidRecordingWithValidation(params: {
@@ -198,14 +146,13 @@ async function copyAndroidRecordingWithValidation(params: {
       allowFailure: true,
     });
     if (pullResult.exitCode !== 0) {
-      lastCopyError = failedExecMessage(pullResult, 'adb pull');
+      lastCopyError = formatRecordTraceExecFailure(pullResult, 'adb pull');
     } else {
       await deps.waitForStableFile(outPath, {
         pollMs: ANDROID_REMOTE_FILE_POLL_MS,
         attempts: ANDROID_REMOTE_FILE_ATTEMPTS,
       });
       const playable = await deps.isPlayableVideo(outPath);
-      const atoms = inspectMp4TopLevelAtoms(outPath);
       emitDiagnostic({
         level: 'debug',
         phase: 'record_stop_android_pull_validation',
@@ -221,7 +168,6 @@ async function copyAndroidRecordingWithValidation(params: {
               return 0;
             }
           })(),
-          atoms,
           playable,
         },
       });
@@ -242,7 +188,7 @@ async function copyAndroidRecordingWithValidation(params: {
     }
 
     if (attempt < ANDROID_LOCAL_VIDEO_ATTEMPTS - 1) {
-      await new Promise((resolve) => setTimeout(resolve, ANDROID_LOCAL_VIDEO_POLL_MS));
+      await new Promise((resolve) => setTimeout(resolve, ANDROID_LOCAL_VIDEO_RETRY_DELAY_MS));
     }
   }
 
@@ -252,67 +198,107 @@ async function copyAndroidRecordingWithValidation(params: {
   return 'failed to copy recording from device: pulled file is not a playable MP4';
 }
 
+function androidRemoteRecordingPaths(timestamp: number): string[] {
+  const fileName = `agent-device-recording-${timestamp}.mp4`;
+  return [`/sdcard/${fileName}`, `/data/local/tmp/${fileName}`];
+}
+
+async function cleanupAndroidRemoteRecording(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  remotePath: string,
+): Promise<void> {
+  await deps.runCmd('adb', ['-s', deviceId, 'shell', 'rm', '-f', remotePath], {
+    allowFailure: true,
+  });
+}
+
+async function forceStopAndroidProcess(
+  deps: RecordTraceDeps,
+  deviceId: string,
+  pid: string,
+): Promise<boolean> {
+  const forceResult = await deps.runCmd('adb', ['-s', deviceId, 'shell', 'kill', '-9', pid], {
+    allowFailure: true,
+  });
+  emitDiagnostic({
+    level: 'warn',
+    phase: 'record_stop_android_force_signal',
+    data: {
+      deviceId,
+      remotePid: pid,
+      exitCode: forceResult.exitCode,
+      stdout: forceResult.stdout.trim(),
+      stderr: forceResult.stderr.trim(),
+    },
+  });
+  if (forceResult.exitCode !== 0 && (await isAndroidProcessRunning(deps, deviceId, pid))) {
+    return false;
+  }
+  return await waitForAndroidProcessExit(deps, deviceId, pid);
+}
+
 export async function startAndroidRecording(params: {
   deps: RecordTraceDeps;
   device: AndroidDevice;
   recordingBase: AndroidRecordingBase;
 }): Promise<DaemonResponse | AndroidRecording> {
   const { deps, device, recordingBase } = params;
+  let lastStartError =
+    'failed to start recording: Android screenrecord did not begin producing frames';
 
-  const remotePath = `/data/local/tmp/agent-device-recording-${Date.now()}.mp4`;
-  const startResult = await deps.runCmd(
-    'adb',
-    ['-s', device.id, 'shell', `screenrecord ${remotePath} >/dev/null 2>&1 & echo $!`],
-    {
-      allowFailure: true,
-    },
-  );
-  if (startResult.exitCode !== 0) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: `failed to start recording: ${failedExecMessage(startResult, 'adb shell screenrecord')}`,
+  for (const remotePath of androidRemoteRecordingPaths(Date.now())) {
+    const startResult = await deps.runCmd(
+      'adb',
+      ['-s', device.id, 'shell', `screenrecord ${remotePath} >/dev/null 2>&1 & echo $!`],
+      {
+        allowFailure: true,
       },
-    };
-  }
+    );
+    if (startResult.exitCode !== 0) {
+      lastStartError = `failed to start recording: ${formatRecordTraceExecFailure(startResult, 'adb shell screenrecord')}`;
+      continue;
+    }
 
-  const remotePid = parseAndroidRemotePid(startResult.stdout);
-  if (!remotePid) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: 'failed to start recording: adb did not return a valid Android screenrecord pid',
+    const remotePid = parseAndroidRemotePid(startResult.stdout);
+    if (!remotePid) {
+      lastStartError =
+        'failed to start recording: adb did not return a valid Android screenrecord pid';
+      await cleanupAndroidRemoteRecording(deps, device.id, remotePath);
+      continue;
+    }
+
+    emitDiagnostic({
+      level: 'debug',
+      phase: 'record_start_android_started',
+      data: {
+        deviceId: device.id,
+        remotePath,
+        remotePid,
       },
-    };
-  }
+    });
 
-  emitDiagnostic({
-    level: 'debug',
-    phase: 'record_start_android_started',
-    data: {
-      deviceId: device.id,
-      remotePath,
-      remotePid,
-    },
-  });
+    if (await waitForAndroidRecordingReady(deps, device.id, remotePath, remotePid)) {
+      return {
+        platform: 'android',
+        remotePath,
+        remotePid,
+        ...recordingBase,
+      };
+    }
 
-  if (!(await waitForAndroidRecordingReady(deps, device.id, remotePath, remotePid))) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: 'failed to start recording: Android screenrecord did not begin producing frames',
-      },
-    };
+    lastStartError =
+      'failed to start recording: Android screenrecord did not begin producing frames';
+    await forceStopAndroidProcess(deps, device.id, remotePid);
+    await cleanupAndroidRemoteRecording(deps, device.id, remotePath);
   }
 
   return {
-    platform: 'android',
-    remotePath,
-    remotePid,
-    ...recordingBase,
+    ok: false,
+    error: {
+      code: 'COMMAND_FAILED',
+      message: lastStartError,
+    },
   };
 }
 
@@ -357,10 +343,12 @@ export async function stopAndroidRecording(params: {
   });
   if (stopResult.exitCode !== 0) {
     if (await isAndroidProcessRunning(deps, device.id, recording.remotePid)) {
-      stopError = `failed to stop recording: ${failedExecMessage(stopResult, 'adb shell kill')}`;
+      stopError = `failed to stop recording: ${formatRecordTraceExecFailure(stopResult, 'adb shell kill')}`;
     }
   } else if (!(await waitForAndroidProcessExit(deps, device.id, recording.remotePid))) {
-    stopError = `failed to stop recording: Android screenrecord pid ${recording.remotePid} did not exit`;
+    if (!(await forceStopAndroidProcess(deps, device.id, recording.remotePid))) {
+      stopError = `failed to stop recording: Android screenrecord pid ${recording.remotePid} did not exit`;
+    }
   }
 
   if (!stopError) {
@@ -372,9 +360,9 @@ export async function stopAndroidRecording(params: {
       outPath: recording.outPath,
     });
     if (!copyError) {
-      recording.telemetryPath = deps.writeRecordingTelemetry({
-        videoPath: recording.outPath,
-        events: recording.gestureEvents,
+      persistRecordingTelemetry({
+        recording,
+        writeTelemetry: deps.writeRecordingTelemetry,
       });
     }
     if (!copyError && recording.showTouches && recording.telemetryPath) {
@@ -385,7 +373,7 @@ export async function stopAndroidRecording(params: {
           targetLabel: 'Android recording',
         });
       } catch (error) {
-        overlayError = `failed to overlay recording touches: ${errorMessage(error)}`;
+        overlayError = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
       }
     }
 
@@ -408,7 +396,7 @@ export async function stopAndroidRecording(params: {
       },
     });
     if (rmResult.exitCode !== 0) {
-      cleanupError = `failed to clean up remote recording: ${failedExecMessage(rmResult, 'adb shell rm')}`;
+      cleanupError = `failed to clean up remote recording: ${formatRecordTraceExecFailure(rmResult, 'adb shell rm')}`;
     }
   }
 
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 60a517eee..6a0900e58 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -14,7 +14,11 @@ import type {
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { runCmd, runCmdBackground } from '../../utils/exec.ts';
 import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
-import { trimRecordingTelemetryEvents, writeRecordingTelemetry } from '../recording-telemetry.ts';
+import {
+  deriveRecordingTelemetryPath,
+  persistRecordingTelemetry,
+  writeRecordingTelemetry,
+} from '../recording-telemetry.ts';
 import {
   IOS_RUNNER_CONTAINER_BUNDLE_IDS,
   runIosRunnerCommand,
@@ -24,6 +28,7 @@ import {
   trimRecordingStart,
 } from '../../platforms/ios/recording-overlay.ts';
 import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
+import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import { startAndroidRecording, stopAndroidRecording } from './record-trace-android.ts';
 
 const IOS_DEVICE_RECORD_MIN_FPS = 1;
@@ -54,21 +59,8 @@ export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): Reco
   };
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function failedExecMessage(
-  result: { stdout: string; stderr: string; exitCode: number },
-  command: string,
-): string {
-  return (
-    result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.exitCode}`
-  );
-}
-
 function isRunnerRecordingAlreadyInProgressError(error: unknown): boolean {
-  return errorMessage(error).toLowerCase().includes('recording already in progress');
+  return formatRecordTraceError(error).toLowerCase().includes('recording already in progress');
 }
 
 function normalizeAppBundleId(session: SessionState): string | undefined {
@@ -107,10 +99,10 @@ async function warmIosSimulatorRunner(params: {
   device: SessionState['device'];
   logPath?: string;
   deps: RecordTraceDeps;
-}): Promise<DaemonResponse | null> {
+}): Promise<void> {
   const { req, activeSession, device, logPath, deps } = params;
   const appBundleId = normalizeAppBundleId(activeSession);
-  if (!appBundleId) return null;
+  if (!appBundleId) return;
 
   try {
     await deps.runIosRunnerCommand(
@@ -124,15 +116,17 @@ async function warmIosSimulatorRunner(params: {
       },
       getRunnerOptions(req, logPath, activeSession),
     );
-    return null;
   } catch (error) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: `failed to prepare iOS simulator recording: ${errorMessage(error)}`,
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_start_simulator_runner_warm_failed',
+      data: {
+        deviceId: device.id,
+        session: activeSession.name,
+        appBundleId,
+        error: formatRecordTraceError(error),
       },
-    };
+    });
   }
 }
 
@@ -167,21 +161,6 @@ function resolveIosRecordingTrimStartMs(
   return Math.max(0, recording.targetAppReadyUptimeMs - recording.runnerStartedAtUptimeMs);
 }
 
-function persistRecordingTelemetry(params: {
-  deps: RecordTraceDeps;
-  recording: NonNullable<SessionState['recording']>;
-  trimStartMs?: number;
-}): string {
-  const { deps, recording, trimStartMs = 0 } = params;
-  const events = trimRecordingTelemetryEvents(recording.gestureEvents, trimStartMs);
-  const telemetryPath = deps.writeRecordingTelemetry({
-    videoPath: recording.outPath,
-    events,
-  });
-  recording.telemetryPath = telemetryPath;
-  return telemetryPath;
-}
-
 async function startIosDeviceRecording(params: {
   req: DaemonRequest;
   activeSession: SessionState;
@@ -237,7 +216,7 @@ async function startIosDeviceRecording(params: {
         ok: false,
         error: {
           code: 'COMMAND_FAILED',
-          message: `failed to start recording: ${errorMessage(error)}`,
+          message: `failed to start recording: ${formatRecordTraceError(error)}`,
         },
       };
     }
@@ -250,7 +229,7 @@ async function startIosDeviceRecording(params: {
         kind: device.kind,
         deviceId: device.id,
         session: activeSession.name,
-        error: errorMessage(error),
+        error: formatRecordTraceError(error),
       },
     });
 
@@ -290,7 +269,7 @@ async function startIosDeviceRecording(params: {
         ok: false,
         error: {
           code: 'COMMAND_FAILED',
-          message: `failed to start recording: ${errorMessage(retryError)}`,
+          message: `failed to start recording: ${formatRecordTraceError(retryError)}`,
         },
       };
     }
@@ -380,19 +359,16 @@ async function startRecording(params: {
       appBundleId,
     });
   } else if (device.platform === 'ios') {
-    const warmRunnerError = await warmIosSimulatorRunner({
+    await warmIosSimulatorRunner({
       req,
       activeSession,
       device,
       logPath,
       deps,
     });
-    if (warmRunnerError) {
-      return warmRunnerError;
-    }
     const { child, wait } = deps.runCmdBackground(
       'xcrun',
-      buildSimctlArgsForDevice(device, ['io', device.id, 'recordVideo', '-f', resolvedOut]),
+      buildSimctlArgsForDevice(device, ['io', device.id, 'recordVideo', resolvedOut]),
       {
         allowFailure: true,
       },
@@ -451,7 +427,7 @@ async function stopIosDeviceRecording(params: {
         kind: device.kind,
         deviceId: device.id,
         session: activeSession.name,
-        error: errorMessage(error),
+        error: formatRecordTraceError(error),
       },
     });
     // best effort: clear runner-backed recording state even if runner stop fails
@@ -506,7 +482,11 @@ async function stopIosDeviceRecording(params: {
     });
   }
 
-  const telemetryPath = persistRecordingTelemetry({ deps, recording, trimStartMs });
+  const telemetryPath = persistRecordingTelemetry({
+    recording,
+    trimStartMs,
+    writeTelemetry: deps.writeRecordingTelemetry,
+  });
 
   if (recording.showTouches) {
     await deps.overlayRecordingTouches({
@@ -537,12 +517,15 @@ async function stopNonRunnerRecording(params: {
       ok: false,
       error: {
         code: 'COMMAND_FAILED',
-        message: `failed to stop recording: ${failedExecMessage(stopResult, 'simctl recordVideo')}`,
+        message: `failed to stop recording: ${formatRecordTraceExecFailure(stopResult, 'simctl recordVideo')}`,
       },
     };
   }
 
-  const telemetryPath = persistRecordingTelemetry({ deps, recording });
+  const telemetryPath = persistRecordingTelemetry({
+    recording,
+    writeTelemetry: deps.writeRecordingTelemetry,
+  });
 
   if (recording.showTouches) {
     await deps.overlayRecordingTouches({
@@ -620,7 +603,7 @@ function deriveClientTelemetryPath(
   if (!recording.clientOutPath) {
     return undefined;
   }
-  return `${recording.clientOutPath}.gesture-telemetry.json`;
+  return deriveRecordingTelemetryPath(recording.clientOutPath);
 }
 
 export async function handleRecordCommand(params: {
diff --git a/src/daemon/handlers/session-replay-script.ts b/src/daemon/handlers/session-replay-script.ts
index 5836816a9..f73f673e8 100644
--- a/src/daemon/handlers/session-replay-script.ts
+++ b/src/daemon/handlers/session-replay-script.ts
@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { AppError } from '../../utils/errors.ts';
 import { appendOpenActionScriptArgs, parseReplayOpenFlags } from '../session-open-script.ts';
+import { appendRecordActionScriptArgs } from '../session-record-script.ts';
 import type { SessionAction, SessionState } from '../types.ts';
 import {
   appendRuntimeHintFlags,
@@ -276,19 +277,7 @@ function formatReplayActionLine(action: SessionAction): string {
     return parts.join(' ');
   }
   if (action.command === 'record') {
-    const [subcommand, ...rest] = action.positionals ?? [];
-    if (subcommand) {
-      parts.push(formatScriptArgQuoteIfNeeded(subcommand));
-    }
-    for (const positional of rest) {
-      parts.push(formatScriptArg(positional));
-    }
-    if (typeof action.flags?.fps === 'number') {
-      parts.push('--fps', String(action.flags.fps));
-    }
-    if (action.flags?.hideTouches) {
-      parts.push('--hide-touches');
-    }
+    appendRecordActionScriptArgs(parts, action);
     return parts.join(' ');
   }
   for (const positional of action.positionals ?? []) {
diff --git a/src/daemon/record-trace-errors.ts b/src/daemon/record-trace-errors.ts
new file mode 100644
index 000000000..4cc0509c5
--- /dev/null
+++ b/src/daemon/record-trace-errors.ts
@@ -0,0 +1,12 @@
+export function formatRecordTraceError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function formatRecordTraceExecFailure(
+  result: { stdout: string; stderr: string; exitCode: number },
+  command: string,
+): string {
+  return (
+    result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.exitCode}`
+  );
+}
diff --git a/src/daemon/recording-telemetry.ts b/src/daemon/recording-telemetry.ts
index 59d730f08..bdb983421 100644
--- a/src/daemon/recording-telemetry.ts
+++ b/src/daemon/recording-telemetry.ts
@@ -8,6 +8,12 @@ type RecordingTelemetryEnvelope = {
   events: RecordingGestureEvent[];
 };
 
+type RecordingTelemetryState = {
+  outPath: string;
+  gestureEvents: RecordingGestureEvent[];
+  telemetryPath?: string;
+};
+
 export function deriveRecordingTelemetryPath(videoPath: string): string {
   const parsed = path.parse(videoPath);
   return path.join(parsed.dir, `${parsed.name}.gesture-telemetry.json`);
@@ -17,40 +23,63 @@ export function trimRecordingTelemetryEvents(
   events: RecordingGestureEvent[],
   trimStartMs: number,
 ): RecordingGestureEvent[] {
-  const normalizedEvents =
-    trimStartMs > 0
-      ? events.flatMap((event) => {
-          const adjustedStartMs = event.tMs - trimStartMs;
-          const durationMs = 'durationMs' in event ? event.durationMs : undefined;
-          const adjustedEndMs =
-            typeof durationMs === 'number' ? adjustedStartMs + durationMs : adjustedStartMs;
-
-          if (adjustedEndMs <= 0) {
-            return [];
-          }
-
-          return [
-            {
-              ...event,
-              tMs: Math.max(0, adjustedStartMs),
-            },
-          ];
-        })
-      : events.map((event) => ({ ...event }));
-
-  return normalizedEvents.sort((left, right) => left.tMs - right.tMs);
+  if (!(trimStartMs > 0)) {
+    return normalizeRecordingTelemetryEvents(events);
+  }
+
+  return normalizeRecordingTelemetryEvents(
+    events.flatMap((event) => {
+      const adjustedStartMs = event.tMs - trimStartMs;
+      const durationMs = 'durationMs' in event ? event.durationMs : undefined;
+      const adjustedEndMs =
+        typeof durationMs === 'number' ? adjustedStartMs + durationMs : adjustedStartMs;
+
+      if (adjustedEndMs <= 0) {
+        return [];
+      }
+
+      return [
+        {
+          ...event,
+          tMs: Math.max(0, adjustedStartMs),
+        },
+      ];
+    }),
+  );
+}
+
+export function normalizeRecordingTelemetryEvents(
+  events: RecordingGestureEvent[],
+): RecordingGestureEvent[] {
+  return [...events].sort((left, right) => left.tMs - right.tMs);
 }
 
 export function writeRecordingTelemetry(params: {
   videoPath: string;
   events: RecordingGestureEvent[];
+  trimStartMs?: number;
 }): string {
   const telemetryPath = deriveRecordingTelemetryPath(params.videoPath);
   const payload: RecordingTelemetryEnvelope = {
     version: 1,
     generatedAt: new Date().toISOString(),
-    events: trimRecordingTelemetryEvents(params.events, 0),
+    events: trimRecordingTelemetryEvents(params.events, params.trimStartMs ?? 0),
   };
   fs.writeFileSync(telemetryPath, JSON.stringify(payload, null, 2));
   return telemetryPath;
 }
+
+export function persistRecordingTelemetry(params: {
+  recording: RecordingTelemetryState;
+  trimStartMs?: number;
+  writeTelemetry?: typeof writeRecordingTelemetry;
+}): string {
+  const { recording, trimStartMs, writeTelemetry = writeRecordingTelemetry } = params;
+  const telemetryPath = writeTelemetry({
+    videoPath: recording.outPath,
+    events: recording.gestureEvents,
+    trimStartMs,
+  });
+  recording.telemetryPath = telemetryPath;
+  return telemetryPath;
+}
diff --git a/src/daemon/session-record-script.ts b/src/daemon/session-record-script.ts
new file mode 100644
index 000000000..02c3757c1
--- /dev/null
+++ b/src/daemon/session-record-script.ts
@@ -0,0 +1,18 @@
+import type { SessionAction } from './types.ts';
+import { formatScriptArg, formatScriptArgQuoteIfNeeded } from './script-utils.ts';
+
+export function appendRecordActionScriptArgs(parts: string[], action: SessionAction): void {
+  const [subcommand, ...rest] = action.positionals ?? [];
+  if (subcommand) {
+    parts.push(formatScriptArgQuoteIfNeeded(subcommand));
+  }
+  for (const positional of rest) {
+    parts.push(formatScriptArg(positional));
+  }
+  if (typeof action.flags?.fps === 'number') {
+    parts.push('--fps', String(action.flags.fps));
+  }
+  if (action.flags?.hideTouches) {
+    parts.push('--hide-touches');
+  }
+}
diff --git a/src/daemon/session-store.ts b/src/daemon/session-store.ts
index de116aced..b92b84d66 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -5,6 +5,7 @@ import type { SessionAction, SessionRuntimeHints, SessionState } from './types.t
 import { inferFillText } from './action-utils.ts';
 import { resolveUserPath } from '../utils/path-resolution.ts';
 import { appendOpenActionScriptArgs } from './session-open-script.ts';
+import { appendRecordActionScriptArgs } from './session-record-script.ts';
 import {
   appendRuntimeHintFlags,
   appendScriptSeriesFlags,
@@ -369,19 +370,7 @@ function formatActionLine(action: SessionAction): string {
     return parts.join(' ');
   }
   if (action.command === 'record') {
-    const [subcommand, ...rest] = action.positionals ?? [];
-    if (subcommand) {
-      parts.push(formatScriptArgQuoteIfNeeded(subcommand));
-    }
-    for (const positional of rest) {
-      parts.push(formatScriptArg(positional));
-    }
-    if (typeof action.flags?.fps === 'number') {
-      parts.push('--fps', String(action.flags.fps));
-    }
-    if (action.flags?.hideTouches) {
-      parts.push('--hide-touches');
-    }
+    appendRecordActionScriptArgs(parts, action);
     return parts.join(' ');
   }
   for (const positional of action.positionals ?? []) {
diff --git a/src/platforms/ios/recording-overlay.ts b/src/platforms/ios/recording-overlay.ts
index e3ea0ec15..03c90e15a 100644
--- a/src/platforms/ios/recording-overlay.ts
+++ b/src/platforms/ios/recording-overlay.ts
@@ -25,13 +25,24 @@ function resolveScriptPath(scriptName: string): string {
   }
 
   throw new AppError('COMMAND_FAILED', `Missing recording helper script: ${scriptName}`, {
+    hint: 'Ensure ios-runner/AgentDeviceRunner/RecordingScripts is present in this checkout or bundled with the package.',
     scriptName,
     searchedPaths: scriptCandidates,
   });
 }
 
-const overlayScriptPath = resolveScriptPath('recording-overlay.swift');
-const trimScriptPath = resolveScriptPath('recording-trim.swift');
+let overlayScriptPath: string | undefined;
+let trimScriptPath: string | undefined;
+
+function getOverlayScriptPath(): string {
+  overlayScriptPath ??= resolveScriptPath('recording-overlay.swift');
+  return overlayScriptPath;
+}
+
+function getTrimScriptPath(): string {
+  trimScriptPath ??= resolveScriptPath('recording-trim.swift');
+  return trimScriptPath;
+}
 
 async function exportProcessedVideo(params: {
   videoPath: string;
@@ -104,7 +115,7 @@ export async function trimRecordingStart(params: {
 
   await exportProcessedVideo({
     videoPath,
-    scriptPath: trimScriptPath,
+    scriptPath: getTrimScriptPath(),
     scriptArgs: ['--trim-start-ms', String(trimStartMs)],
     commandDescription: 'Failed to trim the start of the iOS recording',
   });
@@ -118,7 +129,7 @@ export async function overlayRecordingTouches(params: {
   const { videoPath, telemetryPath, targetLabel = 'recording' } = params;
   await exportProcessedVideo({
     videoPath,
-    scriptPath: overlayScriptPath,
+    scriptPath: getOverlayScriptPath(),
     scriptArgs: ['--events', telemetryPath],
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
   });
diff --git a/src/utils/__tests__/video.test.ts b/src/utils/__tests__/video.test.ts
new file mode 100644
index 000000000..4382f5606
--- /dev/null
+++ b/src/utils/__tests__/video.test.ts
@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isPlayableVideo } from '../video.ts';
+
+function makeAtom(type: string, payload = Buffer.alloc(0)): Buffer {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(8 + payload.length, 0);
+  header.write(type, 4, 4, 'ascii');
+  return Buffer.concat([header, payload]);
+}
+
+test('isPlayableVideo falls back to MP4 container validation when swift is unavailable', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-video-fallback-'));
+  const videoPath = path.join(tmpDir, 'sample.mp4');
+  await fs.writeFile(videoPath, Buffer.concat([makeAtom('ftyp'), makeAtom('moov')]));
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = '';
+
+  try {
+    assert.equal(await isPlayableVideo(videoPath), true);
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('isPlayableVideo fallback rejects files without playable MP4 atoms', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-video-invalid-'));
+  const videoPath = path.join(tmpDir, 'sample.mp4');
+  await fs.writeFile(videoPath, Buffer.concat([makeAtom('ftyp'), makeAtom('mdat')]));
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = '';
+
+  try {
+    assert.equal(await isPlayableVideo(videoPath), false);
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
diff --git a/src/utils/video.ts b/src/utils/video.ts
index c7e776811..2a2a716ba 100644
--- a/src/utils/video.ts
+++ b/src/utils/video.ts
@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { AppError } from './errors.ts';
 import { runCmd } from './exec.ts';
 
 const VIDEO_VALIDATION_SCRIPT = `
@@ -59,21 +60,25 @@ export async function waitForStableFile(
 }
 
 export async function isPlayableVideo(filePath: string): Promise<boolean> {
-  const result = await runCmd('swift', ['-', filePath], {
-    stdin: VIDEO_VALIDATION_SCRIPT,
-    allowFailure: true,
-    timeoutMs: 10_000,
-  });
-  if (
-    result.exitCode !== 0 &&
-    typeof result.stderr === 'string' &&
-    /\b(swift: command not found|avfoundation\b|no such module|unable to find utility|xcrun: error)\b/i.test(
-      result.stderr,
-    )
-  ) {
-    return true;
+  try {
+    const result = await runCmd('swift', ['-', filePath], {
+      stdin: VIDEO_VALIDATION_SCRIPT,
+      allowFailure: true,
+      timeoutMs: 10_000,
+    });
+    if (result.exitCode === 0) {
+      return true;
+    }
+    if (isSwiftVideoValidatorUnavailable(result.stderr, result.stdout)) {
+      return hasLikelyPlayableVideoContainer(filePath);
+    }
+    return false;
+  } catch (error) {
+    if (error instanceof AppError && error.code === 'TOOL_MISSING') {
+      return hasLikelyPlayableVideoContainer(filePath);
+    }
+    throw error;
   }
-  return result.exitCode === 0;
 }
 
 export async function waitForPlayableVideo(
@@ -90,3 +95,65 @@ export async function waitForPlayableVideo(
     await new Promise((resolve) => setTimeout(resolve, pollMs));
   }
 }
+
+function isSwiftVideoValidatorUnavailable(stderr: string, stdout: string): boolean {
+  const combined = `${stderr}\n${stdout}`;
+  return /\b(no such module ['"]AVFoundation['"]|unable to find utility ["']swift["']|xcrun: error: unable to find utility ["']swift["'])\b/i.test(
+    combined,
+  );
+}
+
+function hasLikelyPlayableVideoContainer(filePath: string): boolean {
+  try {
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile() || stats.size <= 0) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  const atoms = inspectTopLevelAtoms(filePath);
+  return atoms.includes('ftyp') && atoms.includes('moov');
+}
+
+function inspectTopLevelAtoms(filePath: string): string[] {
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const size = fs.fstatSync(fd).size;
+      let offset = 0;
+      const atoms: string[] = [];
+      while (offset + 8 <= size && atoms.length < 16) {
+        const header = Buffer.alloc(8);
+        const bytesRead = fs.readSync(fd, header, 0, 8, offset);
+        if (bytesRead < 8) {
+          break;
+        }
+
+        let atomSize = header.readUInt32BE(0);
+        const atomType = header.toString('latin1', 4, 8);
+        atoms.push(atomType);
+
+        if (atomSize === 1) {
+          const extended = Buffer.alloc(8);
+          const extendedRead = fs.readSync(fd, extended, 0, 8, offset + 8);
+          if (extendedRead < 8) {
+            break;
+          }
+          atomSize = Number(extended.readBigUInt64BE(0));
+        }
+
+        if (!Number.isFinite(atomSize) || atomSize <= 0) {
+          break;
+        }
+        offset += atomSize;
+      }
+      return atoms;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return [];
+  }
+}

From 2192503447078c909e34d7f3d5d7a95aaee198cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 21 Mar 2026 19:05:15 +0100
Subject: [PATCH 04/11] fix: clean up android recording stop fallback

---
 .../handlers/__tests__/record-trace.test.ts   | 81 +++++++++++++++++++
 src/daemon/handlers/record-trace-android.ts   | 46 ++++++-----
 2 files changed, 105 insertions(+), 22 deletions(-)

diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index 49ff43f84..b92ac6283 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -835,6 +835,87 @@ test('record start/stop overlays Android gestures by default on devices', async
   ]);
 });
 
+test('record stop force-kills Android screenrecord when SIGINT fails but process is still running', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-force-stop';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        if (
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '4321\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  const adbCalls: string[] = [];
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        adbCalls.push(command);
+        if (command === '-s emulator-5554 shell kill -2 4321') {
+          return { stdout: '', stderr: 'operation not permitted', exitCode: 1 };
+        }
+        if (command === '-s emulator-5554 shell ps -o pid= -p 4321') {
+          return {
+            stdout: adbCalls.includes('-s emulator-5554 shell kill -9 4321') ? '' : '4321\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '2048\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  assert.equal(response?.ok, true);
+  assert.ok(adbCalls.includes('-s emulator-5554 shell kill -2 4321'));
+  assert.ok(adbCalls.includes('-s emulator-5554 shell kill -9 4321'));
+  assert.ok(
+    adbCalls.some((command) =>
+      /^-s emulator-5554 shell rm -f \/sdcard\/agent-device-recording-\d+\.mp4$/.test(command),
+    ),
+  );
+});
+
 test('record start leaves overlays disabled with --hide-touches', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-hide-touches';
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 58835abea..337e00220 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -343,7 +343,9 @@ export async function stopAndroidRecording(params: {
   });
   if (stopResult.exitCode !== 0) {
     if (await isAndroidProcessRunning(deps, device.id, recording.remotePid)) {
-      stopError = `failed to stop recording: ${formatRecordTraceExecFailure(stopResult, 'adb shell kill')}`;
+      if (!(await forceStopAndroidProcess(deps, device.id, recording.remotePid))) {
+        stopError = `failed to stop recording: ${formatRecordTraceExecFailure(stopResult, 'adb shell kill')}`;
+      }
     }
   } else if (!(await waitForAndroidProcessExit(deps, device.id, recording.remotePid))) {
     if (!(await forceStopAndroidProcess(deps, device.id, recording.remotePid))) {
@@ -376,28 +378,28 @@ export async function stopAndroidRecording(params: {
         overlayError = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
       }
     }
+  }
 
-    const rmResult = await deps.runCmd(
-      'adb',
-      ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath],
-      {
-        allowFailure: true,
-      },
-    );
-    emitDiagnostic({
-      level: 'debug',
-      phase: 'record_stop_android_cleanup',
-      data: {
-        deviceId: device.id,
-        remotePath: recording.remotePath,
-        exitCode: rmResult.exitCode,
-        stdout: rmResult.stdout.trim(),
-        stderr: rmResult.stderr.trim(),
-      },
-    });
-    if (rmResult.exitCode !== 0) {
-      cleanupError = `failed to clean up remote recording: ${formatRecordTraceExecFailure(rmResult, 'adb shell rm')}`;
-    }
+  const rmResult = await deps.runCmd(
+    'adb',
+    ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath],
+    {
+      allowFailure: true,
+    },
+  );
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'record_stop_android_cleanup',
+    data: {
+      deviceId: device.id,
+      remotePath: recording.remotePath,
+      exitCode: rmResult.exitCode,
+      stdout: rmResult.stdout.trim(),
+      stderr: rmResult.stderr.trim(),
+    },
+  });
+  if (rmResult.exitCode !== 0 && !stopError) {
+    cleanupError = `failed to clean up remote recording: ${formatRecordTraceExecFailure(rmResult, 'adb shell rm')}`;
   }
 
   if (stopError) {

From d47769707b30523e4c6ddbb840333825d49f4e11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 21 Mar 2026 19:17:08 +0100
Subject: [PATCH 05/11] refactor: split ios recording handlers

---
 src/daemon/handlers/record-trace-ios.ts       | 324 ++++++++++++++++++
 src/daemon/handlers/record-trace-recording.ts | 318 +----------------
 2 files changed, 332 insertions(+), 310 deletions(-)
 create mode 100644 src/daemon/handlers/record-trace-ios.ts

diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
new file mode 100644
index 000000000..3bc4d50ce
--- /dev/null
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -0,0 +1,324 @@
+import { SessionStore } from '../session-store.ts';
+import type {
+  DaemonRequest,
+  DaemonResponse,
+  RecordingGestureEvent,
+  SessionState,
+} from '../types.ts';
+import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import { persistRecordingTelemetry } from '../recording-telemetry.ts';
+import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../platforms/ios/runner-client.ts';
+import { formatRecordTraceError } from '../record-trace-errors.ts';
+import type { RecordTraceDeps } from './record-trace-recording.ts';
+
+type RecordingBase = {
+  outPath: string;
+  clientOutPath?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+};
+
+export function normalizeAppBundleId(session: SessionState): string | undefined {
+  const trimmed = session.appBundleId?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+
+function isRunnerRecordingAlreadyInProgressError(error: unknown): boolean {
+  return formatRecordTraceError(error).toLowerCase().includes('recording already in progress');
+}
+
+function findOtherActiveIosRunnerRecording(
+  sessionStore: SessionStore,
+  deviceId: string,
+  currentSessionName: string,
+): SessionState | undefined {
+  return sessionStore
+    .toArray()
+    .find(
+      (session) =>
+        session.name !== currentSessionName &&
+        session.device.platform === 'ios' &&
+        session.device.kind === 'device' &&
+        session.device.id === deviceId &&
+        session.recording?.platform === 'ios-device-runner',
+    );
+}
+
+function getRunnerOptions(req: DaemonRequest, logPath: string | undefined, session: SessionState) {
+  return {
+    verbose: req.flags?.verbose,
+    logPath,
+    traceLogPath: session.trace?.outPath,
+  };
+}
+
+function resolveIosRecordingTrimStartMs(
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>,
+): number {
+  if (
+    typeof recording.runnerStartedAtUptimeMs !== 'number' ||
+    typeof recording.targetAppReadyUptimeMs !== 'number'
+  ) {
+    return 0;
+  }
+  return Math.max(0, recording.targetAppReadyUptimeMs - recording.runnerStartedAtUptimeMs);
+}
+
+export async function warmIosSimulatorRunner(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+}): Promise<void> {
+  const { req, activeSession, device, logPath, deps } = params;
+  const appBundleId = normalizeAppBundleId(activeSession);
+  if (!appBundleId) return;
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      {
+        command: 'snapshot',
+        appBundleId,
+        interactiveOnly: true,
+        compact: true,
+        depth: 1,
+      },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+  } catch (error) {
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_start_simulator_runner_warm_failed',
+      data: {
+        deviceId: device.id,
+        session: activeSession.name,
+        appBundleId,
+        error: formatRecordTraceError(error),
+      },
+    });
+  }
+}
+
+export async function startIosDeviceRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  sessionStore: SessionStore;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  fpsFlag: number | undefined;
+  recordingBase: RecordingBase;
+  appBundleId: string;
+}): Promise<DaemonResponse | NonNullable<SessionState['recording']>> {
+  const {
+    req,
+    activeSession,
+    sessionStore,
+    device,
+    logPath,
+    deps,
+    fpsFlag,
+    recordingBase,
+    appBundleId,
+  } = params;
+  const recordingFileName = `agent-device-recording-${Date.now()}.mp4`;
+  const remotePath = `tmp/${recordingFileName}`;
+  const runnerOptions = getRunnerOptions(req, logPath, activeSession);
+  let runnerStartedAtUptimeMs: number | undefined;
+  let targetAppReadyUptimeMs: number | undefined;
+  const startRunnerRecording = async () =>
+    deps.runIosRunnerCommand(
+      device,
+      {
+        command: 'recordStart',
+        outPath: recordingFileName,
+        fps: fpsFlag,
+        appBundleId,
+      },
+      runnerOptions,
+    );
+
+  try {
+    const startResult = await startRunnerRecording();
+    runnerStartedAtUptimeMs =
+      typeof startResult.recorderStartUptimeMs === 'number'
+        ? startResult.recorderStartUptimeMs
+        : undefined;
+    targetAppReadyUptimeMs =
+      typeof startResult.targetAppReadyUptimeMs === 'number'
+        ? startResult.targetAppReadyUptimeMs
+        : undefined;
+  } catch (error) {
+    if (!isRunnerRecordingAlreadyInProgressError(error)) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: ${formatRecordTraceError(error)}`,
+        },
+      };
+    }
+
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_start_runner_desynced',
+      data: {
+        platform: device.platform,
+        kind: device.kind,
+        deviceId: device.id,
+        session: activeSession.name,
+        error: formatRecordTraceError(error),
+      },
+    });
+
+    const otherRecordingSession = findOtherActiveIosRunnerRecording(
+      sessionStore,
+      device.id,
+      activeSession.name,
+    );
+    if (otherRecordingSession) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: recording already in progress in session '${otherRecordingSession.name}'`,
+        },
+      };
+    }
+
+    try {
+      await deps.runIosRunnerCommand(device, { command: 'recordStop', appBundleId }, runnerOptions);
+    } catch {
+      // best effort: stop stale runner recording and retry start
+    }
+
+    try {
+      const startResult = await startRunnerRecording();
+      runnerStartedAtUptimeMs =
+        typeof startResult.recorderStartUptimeMs === 'number'
+          ? startResult.recorderStartUptimeMs
+          : undefined;
+      targetAppReadyUptimeMs =
+        typeof startResult.targetAppReadyUptimeMs === 'number'
+          ? startResult.targetAppReadyUptimeMs
+          : undefined;
+    } catch (retryError) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `failed to start recording: ${formatRecordTraceError(retryError)}`,
+        },
+      };
+    }
+  }
+
+  return {
+    platform: 'ios-device-runner',
+    remotePath,
+    runnerStartedAtUptimeMs,
+    targetAppReadyUptimeMs,
+    ...recordingBase,
+  };
+}
+
+export async function stopIosDeviceRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>;
+}): Promise<DaemonResponse | null> {
+  const { req, activeSession, device, logPath, deps, recording } = params;
+  const appBundleId = normalizeAppBundleId(activeSession);
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      { command: 'recordStop', appBundleId },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+  } catch (error) {
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_stop_runner_failed',
+      data: {
+        platform: device.platform,
+        kind: device.kind,
+        deviceId: device.id,
+        session: activeSession.name,
+        error: formatRecordTraceError(error),
+      },
+    });
+    // best effort: clear runner-backed recording state even if runner stop fails
+  }
+
+  let copyResult = { stdout: '', stderr: '', exitCode: 1 };
+  for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
+    copyResult = await deps.runCmd(
+      'xcrun',
+      [
+        'devicectl',
+        'device',
+        'copy',
+        'from',
+        '--device',
+        device.id,
+        '--source',
+        recording.remotePath,
+        '--destination',
+        recording.outPath,
+        '--domain-type',
+        'appDataContainer',
+        '--domain-identifier',
+        bundleId,
+      ],
+      { allowFailure: true },
+    );
+    if (copyResult.exitCode === 0) {
+      break;
+    }
+  }
+
+  if (copyResult.exitCode !== 0) {
+    const copyError =
+      copyResult.stderr.trim() ||
+      copyResult.stdout.trim() ||
+      `devicectl exited with code ${copyResult.exitCode}`;
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to copy recording from device: ${copyError}`,
+      },
+    };
+  }
+
+  const trimStartMs = resolveIosRecordingTrimStartMs(recording);
+  if (trimStartMs > 0) {
+    await deps.trimRecordingStart({
+      videoPath: recording.outPath,
+      trimStartMs,
+    });
+  }
+
+  const telemetryPath = persistRecordingTelemetry({
+    recording,
+    trimStartMs,
+    writeTelemetry: deps.writeRecordingTelemetry,
+  });
+
+  if (recording.showTouches) {
+    await deps.overlayRecordingTouches({
+      videoPath: recording.outPath,
+      telemetryPath,
+      targetLabel: 'iOS recording',
+    });
+  }
+
+  return null;
+}
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 6a0900e58..c54c41054 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -11,7 +11,6 @@ import type {
   RecordingGestureEvent,
   SessionState,
 } from '../types.ts';
-import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { runCmd, runCmdBackground } from '../../utils/exec.ts';
 import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
 import {
@@ -19,17 +18,20 @@ import {
   persistRecordingTelemetry,
   writeRecordingTelemetry,
 } from '../recording-telemetry.ts';
-import {
-  IOS_RUNNER_CONTAINER_BUNDLE_IDS,
-  runIosRunnerCommand,
-} from '../../platforms/ios/runner-client.ts';
+import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
 import {
   overlayRecordingTouches,
   trimRecordingStart,
 } from '../../platforms/ios/recording-overlay.ts';
 import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
-import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
+import { formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import { startAndroidRecording, stopAndroidRecording } from './record-trace-android.ts';
+import {
+  normalizeAppBundleId,
+  startIosDeviceRecording,
+  stopIosDeviceRecording,
+  warmIosSimulatorRunner,
+} from './record-trace-ios.ts';
 
 const IOS_DEVICE_RECORD_MIN_FPS = 1;
 const IOS_DEVICE_RECORD_MAX_FPS = 120;
@@ -59,77 +61,6 @@ export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): Reco
   };
 }
 
-function isRunnerRecordingAlreadyInProgressError(error: unknown): boolean {
-  return formatRecordTraceError(error).toLowerCase().includes('recording already in progress');
-}
-
-function normalizeAppBundleId(session: SessionState): string | undefined {
-  const trimmed = session.appBundleId?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : undefined;
-}
-
-function findOtherActiveIosRunnerRecording(
-  sessionStore: SessionStore,
-  deviceId: string,
-  currentSessionName: string,
-): SessionState | undefined {
-  return sessionStore
-    .toArray()
-    .find(
-      (session) =>
-        session.name !== currentSessionName &&
-        session.device.platform === 'ios' &&
-        session.device.kind === 'device' &&
-        session.device.id === deviceId &&
-        session.recording?.platform === 'ios-device-runner',
-    );
-}
-
-function getRunnerOptions(req: DaemonRequest, logPath: string | undefined, session: SessionState) {
-  return {
-    verbose: req.flags?.verbose,
-    logPath,
-    traceLogPath: session.trace?.outPath,
-  };
-}
-
-async function warmIosSimulatorRunner(params: {
-  req: DaemonRequest;
-  activeSession: SessionState;
-  device: SessionState['device'];
-  logPath?: string;
-  deps: RecordTraceDeps;
-}): Promise<void> {
-  const { req, activeSession, device, logPath, deps } = params;
-  const appBundleId = normalizeAppBundleId(activeSession);
-  if (!appBundleId) return;
-
-  try {
-    await deps.runIosRunnerCommand(
-      device,
-      {
-        command: 'snapshot',
-        appBundleId,
-        interactiveOnly: true,
-        compact: true,
-        depth: 1,
-      },
-      getRunnerOptions(req, logPath, activeSession),
-    );
-  } catch (error) {
-    emitDiagnostic({
-      level: 'warn',
-      phase: 'record_start_simulator_runner_warm_failed',
-      data: {
-        deviceId: device.id,
-        session: activeSession.name,
-        appBundleId,
-        error: formatRecordTraceError(error),
-      },
-    });
-  }
-}
-
 function buildRecordingBase(
   req: DaemonRequest,
   outPath: string,
@@ -149,141 +80,6 @@ function buildRecordingBase(
   };
 }
 
-function resolveIosRecordingTrimStartMs(
-  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>,
-): number {
-  if (
-    typeof recording.runnerStartedAtUptimeMs !== 'number' ||
-    typeof recording.targetAppReadyUptimeMs !== 'number'
-  ) {
-    return 0;
-  }
-  return Math.max(0, recording.targetAppReadyUptimeMs - recording.runnerStartedAtUptimeMs);
-}
-
-async function startIosDeviceRecording(params: {
-  req: DaemonRequest;
-  activeSession: SessionState;
-  sessionStore: SessionStore;
-  device: SessionState['device'];
-  logPath?: string;
-  deps: RecordTraceDeps;
-  fpsFlag: number | undefined;
-  recordingBase: ReturnType<typeof buildRecordingBase>;
-  appBundleId: string;
-}): Promise<DaemonResponse | NonNullable<SessionState['recording']>> {
-  const {
-    req,
-    activeSession,
-    sessionStore,
-    device,
-    logPath,
-    deps,
-    fpsFlag,
-    recordingBase,
-    appBundleId,
-  } = params;
-  const recordingFileName = `agent-device-recording-${Date.now()}.mp4`;
-  const remotePath = `tmp/${recordingFileName}`;
-  const runnerOptions = getRunnerOptions(req, logPath, activeSession);
-  let runnerStartedAtUptimeMs: number | undefined;
-  let targetAppReadyUptimeMs: number | undefined;
-  const startRunnerRecording = async () =>
-    deps.runIosRunnerCommand(
-      device,
-      {
-        command: 'recordStart',
-        outPath: recordingFileName,
-        fps: fpsFlag,
-        appBundleId,
-      },
-      runnerOptions,
-    );
-
-  try {
-    const startResult = await startRunnerRecording();
-    runnerStartedAtUptimeMs =
-      typeof startResult.recorderStartUptimeMs === 'number'
-        ? startResult.recorderStartUptimeMs
-        : undefined;
-    targetAppReadyUptimeMs =
-      typeof startResult.targetAppReadyUptimeMs === 'number'
-        ? startResult.targetAppReadyUptimeMs
-        : undefined;
-  } catch (error) {
-    if (!isRunnerRecordingAlreadyInProgressError(error)) {
-      return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: `failed to start recording: ${formatRecordTraceError(error)}`,
-        },
-      };
-    }
-
-    emitDiagnostic({
-      level: 'warn',
-      phase: 'record_start_runner_desynced',
-      data: {
-        platform: device.platform,
-        kind: device.kind,
-        deviceId: device.id,
-        session: activeSession.name,
-        error: formatRecordTraceError(error),
-      },
-    });
-
-    const otherRecordingSession = findOtherActiveIosRunnerRecording(
-      sessionStore,
-      device.id,
-      activeSession.name,
-    );
-    if (otherRecordingSession) {
-      return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: `failed to start recording: recording already in progress in session '${otherRecordingSession.name}'`,
-        },
-      };
-    }
-
-    try {
-      await deps.runIosRunnerCommand(device, { command: 'recordStop', appBundleId }, runnerOptions);
-    } catch {
-      // best effort: stop stale runner recording and retry start
-    }
-
-    try {
-      const startResult = await startRunnerRecording();
-      runnerStartedAtUptimeMs =
-        typeof startResult.recorderStartUptimeMs === 'number'
-          ? startResult.recorderStartUptimeMs
-          : undefined;
-      targetAppReadyUptimeMs =
-        typeof startResult.targetAppReadyUptimeMs === 'number'
-          ? startResult.targetAppReadyUptimeMs
-          : undefined;
-    } catch (retryError) {
-      return {
-        ok: false,
-        error: {
-          code: 'COMMAND_FAILED',
-          message: `failed to start recording: ${formatRecordTraceError(retryError)}`,
-        },
-      };
-    }
-  }
-
-  return {
-    platform: 'ios-device-runner',
-    remotePath,
-    runnerStartedAtUptimeMs,
-    targetAppReadyUptimeMs,
-    ...recordingBase,
-  };
-}
-
 async function startRecording(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -401,104 +197,6 @@ async function startRecording(params: {
   };
 }
 
-async function stopIosDeviceRecording(params: {
-  req: DaemonRequest;
-  activeSession: SessionState;
-  device: SessionState['device'];
-  logPath?: string;
-  deps: RecordTraceDeps;
-  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>;
-}): Promise<DaemonResponse | null> {
-  const { req, activeSession, device, logPath, deps, recording } = params;
-  const appBundleId = normalizeAppBundleId(activeSession);
-
-  try {
-    await deps.runIosRunnerCommand(
-      device,
-      { command: 'recordStop', appBundleId },
-      getRunnerOptions(req, logPath, activeSession),
-    );
-  } catch (error) {
-    emitDiagnostic({
-      level: 'warn',
-      phase: 'record_stop_runner_failed',
-      data: {
-        platform: device.platform,
-        kind: device.kind,
-        deviceId: device.id,
-        session: activeSession.name,
-        error: formatRecordTraceError(error),
-      },
-    });
-    // best effort: clear runner-backed recording state even if runner stop fails
-  }
-
-  let copyResult = { stdout: '', stderr: '', exitCode: 1 };
-  for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
-    copyResult = await deps.runCmd(
-      'xcrun',
-      [
-        'devicectl',
-        'device',
-        'copy',
-        'from',
-        '--device',
-        device.id,
-        '--source',
-        recording.remotePath,
-        '--destination',
-        recording.outPath,
-        '--domain-type',
-        'appDataContainer',
-        '--domain-identifier',
-        bundleId,
-      ],
-      { allowFailure: true },
-    );
-    if (copyResult.exitCode === 0) {
-      break;
-    }
-  }
-
-  if (copyResult.exitCode !== 0) {
-    const copyError =
-      copyResult.stderr.trim() ||
-      copyResult.stdout.trim() ||
-      `devicectl exited with code ${copyResult.exitCode}`;
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: `failed to copy recording from device: ${copyError}`,
-      },
-    };
-  }
-
-  const trimStartMs = resolveIosRecordingTrimStartMs(recording);
-  if (trimStartMs > 0) {
-    await deps.trimRecordingStart({
-      videoPath: recording.outPath,
-      trimStartMs,
-    });
-  }
-
-  const telemetryPath = persistRecordingTelemetry({
-    recording,
-    trimStartMs,
-    writeTelemetry: deps.writeRecordingTelemetry,
-  });
-
-  if (recording.showTouches) {
-    await deps.overlayRecordingTouches({
-      videoPath: recording.outPath,
-      telemetryPath,
-      targetLabel: 'iOS recording',
-    });
-  }
-
-  return null;
-}
-
 async function stopNonRunnerRecording(params: {
   deps: RecordTraceDeps;
   device: SessionState['device'];

From 1aab9175de388d650f885bcd9595d1a8a43d2bda Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sun, 22 Mar 2026 09:53:42 +0100
Subject: [PATCH 06/11] fix: tighten runner-backed touch telemetry

---
 .../RunnerTests+CommandExecution.swift        |  85 +++-
 .../RunnerTests+Interaction.swift             |  60 +++
 .../RunnerTests+Models.swift                  |  20 +-
 src/core/dispatch.ts                          |  19 +-
 .../__tests__/recording-gestures.test.ts      |  23 +
 .../request-router-android-modal.test.ts      | 104 ++++
 .../request-router-recording-health.test.ts   |  72 +++
 src/daemon/android-system-dialog.ts           | 213 +++++++++
 .../handlers/__tests__/interaction.test.ts    | 128 +++++
 .../handlers/__tests__/record-trace.test.ts   |  37 ++
 src/daemon/handlers/record-trace-android.ts   |   1 +
 src/daemon/handlers/record-trace-recording.ts |  44 +-
 src/daemon/recording-gestures.ts              |   6 +-
 src/daemon/request-router.ts                  | 107 ++++-
 src/daemon/types.ts                           |   2 +
 src/platforms/android/index.ts                |   1 +
 src/platforms/android/input-actions.ts        |   2 +-
 .../ios/__tests__/runner-xctestrun.test.ts    |  94 ++++
 src/platforms/ios/runner-client.ts            |   2 +
 src/platforms/ios/runner-session.ts           |  44 ++
 src/platforms/ios/runner-xctestrun.ts         | 443 ++++++------------
 src/utils/interactors.ts                      |  31 +-
 22 files changed, 1199 insertions(+), 339 deletions(-)
 create mode 100644 src/daemon/__tests__/request-router-android-modal.test.ts
 create mode 100644 src/daemon/__tests__/request-router-recording-health.test.ts
 create mode 100644 src/daemon/android-system-dialog.ts
 create mode 100644 src/platforms/ios/__tests__/runner-xctestrun.test.ts

diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 4eb77377f..bcc3e959a 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -207,14 +207,28 @@ extension RunnerTests {
     case .tap:
       if let text = command.text {
         if let element = findElement(app: activeApp, text: text) {
-          element.tap()
+          withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+            element.tap()
+          }
           return Response(ok: true, data: DataPayload(message: "tapped"))
         }
         return Response(ok: false, error: ErrorPayload(message: "element not found"))
       }
       if let x = command.x, let y = command.y {
-        tapAt(app: activeApp, x: x, y: y)
-        return Response(ok: true, data: DataPayload(message: "tapped"))
+        let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          tapAt(app: activeApp, x: x, y: y)
+        }
+        return Response(
+          ok: true,
+          data: DataPayload(
+            message: "tapped",
+            x: touchFrame.x,
+            y: touchFrame.y,
+            referenceWidth: touchFrame.referenceWidth,
+            referenceHeight: touchFrame.referenceHeight
+          )
+        )
       }
       return Response(ok: false, error: ErrorPayload(message: "tap requires text or x/y"))
     case .mouseClick:
@@ -234,32 +248,79 @@ extension RunnerTests {
       let count = max(Int(command.count ?? 1), 1)
       let intervalMs = max(command.intervalMs ?? 0, 0)
       let doubleTap = command.doubleTap ?? false
+      let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
       if doubleTap {
-        runSeries(count: count, pauseMs: intervalMs) { _ in
-          doubleTapAt(app: activeApp, x: x, y: y)
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          runSeries(count: count, pauseMs: intervalMs) { _ in
+            doubleTapAt(app: activeApp, x: x, y: y)
+          }
         }
-        return Response(ok: true, data: DataPayload(message: "tap series"))
+        return Response(
+          ok: true,
+          data: DataPayload(
+            message: "tap series",
+            x: touchFrame.x,
+            y: touchFrame.y,
+            referenceWidth: touchFrame.referenceWidth,
+            referenceHeight: touchFrame.referenceHeight
+          )
+        )
       }
-      runSeries(count: count, pauseMs: intervalMs) { _ in
-        tapAt(app: activeApp, x: x, y: y)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        runSeries(count: count, pauseMs: intervalMs) { _ in
+          tapAt(app: activeApp, x: x, y: y)
+        }
       }
-      return Response(ok: true, data: DataPayload(message: "tap series"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "tap series",
+          x: touchFrame.x,
+          y: touchFrame.y,
+          referenceWidth: touchFrame.referenceWidth,
+          referenceHeight: touchFrame.referenceHeight
+        )
+      )
     case .longPress:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "longPress requires x and y"))
       }
       let duration = (command.durationMs ?? 800) / 1000.0
-      longPressAt(app: activeApp, x: x, y: y, duration: duration)
-      return Response(ok: true, data: DataPayload(message: "long pressed"))
+      let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        longPressAt(app: activeApp, x: x, y: y, duration: duration)
+      }
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "long pressed",
+          x: touchFrame.x,
+          y: touchFrame.y,
+          referenceWidth: touchFrame.referenceWidth,
+          referenceHeight: touchFrame.referenceHeight
+        )
+      )
     case .drag:
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      let dragFrame = resolvedDragVisualizationFrame(app: activeApp, x: x, y: y, x2: x2, y2: y2)
       withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
         dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
       }
-      return Response(ok: true, data: DataPayload(message: "dragged"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "dragged",
+          x: dragFrame.x,
+          y: dragFrame.y,
+          x2: dragFrame.x2,
+          y2: dragFrame.y2,
+          referenceWidth: dragFrame.referenceWidth,
+          referenceHeight: dragFrame.referenceHeight
+        )
+      )
     case .dragSeries:
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
         return Response(ok: false, error: ErrorPayload(message: "dragSeries requires x, y, x2, and y2"))
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index 7c6ad4a1d..7f13ac522 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -1,6 +1,22 @@
 import XCTest
 
 extension RunnerTests {
+  struct TouchVisualizationFrame {
+    let x: Double
+    let y: Double
+    let referenceWidth: Double
+    let referenceHeight: Double
+  }
+
+  struct DragVisualizationFrame {
+    let x: Double
+    let y: Double
+    let x2: Double
+    let y2: Double
+    let referenceWidth: Double
+    let referenceHeight: Double
+  }
+
   // MARK: - Navigation Gestures
 
   func tapNavigationBack(app: XCUIApplication) -> Bool {
@@ -209,6 +225,50 @@ extension RunnerTests {
     start.press(forDuration: holdDuration, thenDragTo: end)
   }
 
+  func resolvedTouchVisualizationFrame(app: XCUIApplication, x: Double, y: Double) -> TouchVisualizationFrame {
+    let appFrame = app.frame
+    let referenceFrame = resolvedTouchReferenceFrame(app: app, appFrame: appFrame)
+    let originX = appFrame.isEmpty ? referenceFrame.minX : appFrame.minX
+    let originY = appFrame.isEmpty ? referenceFrame.minY : appFrame.minY
+    return TouchVisualizationFrame(
+      x: originX + x,
+      y: originY + y,
+      referenceWidth: referenceFrame.width,
+      referenceHeight: referenceFrame.height
+    )
+  }
+
+  func resolvedDragVisualizationFrame(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double
+  ) -> DragVisualizationFrame {
+    let start = resolvedTouchVisualizationFrame(app: app, x: x, y: y)
+    let end = resolvedTouchVisualizationFrame(app: app, x: x2, y: y2)
+    return DragVisualizationFrame(
+      x: start.x,
+      y: start.y,
+      x2: end.x,
+      y2: end.y,
+      referenceWidth: start.referenceWidth,
+      referenceHeight: start.referenceHeight
+    )
+  }
+
+  private func resolvedTouchReferenceFrame(app: XCUIApplication, appFrame: CGRect) -> CGRect {
+    let window = app.windows.firstMatch
+    let windowFrame = window.frame
+    if window.exists && !windowFrame.isEmpty {
+      return windowFrame
+    }
+    if !appFrame.isEmpty {
+      return appFrame
+    }
+    return CGRect(x: 0, y: 0, width: 0, height: 0)
+  }
+
   func runSeries(count: Int, pauseMs: Double, operation: (Int) -> Void) {
     let total = max(count, 1)
     let pause = max(pauseMs, 0)
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index b60afc3ae..5c06cde06 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -75,19 +75,37 @@ struct DataPayload: Codable {
   let items: [String]?
   let nodes: [SnapshotNode]?
   let truncated: Bool?
+  let x: Double?
+  let y: Double?
+  let x2: Double?
+  let y2: Double?
+  let referenceWidth: Double?
+  let referenceHeight: Double?
 
   init(
     message: String? = nil,
     found: Bool? = nil,
     items: [String]? = nil,
     nodes: [SnapshotNode]? = nil,
-    truncated: Bool? = nil
+    truncated: Bool? = nil,
+    x: Double? = nil,
+    y: Double? = nil,
+    x2: Double? = nil,
+    y2: Double? = nil,
+    referenceWidth: Double? = nil,
+    referenceHeight: Double? = nil
   ) {
     self.message = message
     self.found = found
     self.items = items
     self.nodes = nodes
     self.truncated = truncated
+    self.x = x
+    self.y = y
+    self.x2 = x2
+    self.y2 = y2
+    self.referenceWidth = referenceWidth
+    self.referenceHeight = referenceHeight
   }
 }
 
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 10770ddec..9911abfe5 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -190,7 +190,7 @@ export async function dispatchCommand(
           }
 
           if (shouldUseIosTapSeries(device, count, holdMs, jitterPx)) {
-            await runIosRunnerCommand(
+            const runnerResult = await runIosRunnerCommand(
               device,
               {
                 command: 'tapSeries',
@@ -217,22 +217,28 @@ export async function dispatchCommand(
               jitterPx,
               doubleTap,
               timingMode: 'runner-series',
+              ...runnerResult,
             };
           }
 
+          let interactionResult: Record<string, unknown> | undefined;
           await runRepeatedSeries(count, intervalMs, async (index) => {
             const [dx, dy] = computeDeterministicJitter(index, jitterPx);
             const targetX = x + dx;
             const targetY = y + dy;
             if (doubleTap) {
-              await interactor.doubleTap(targetX, targetY);
+              interactionResult ??= (await interactor.doubleTap(targetX, targetY)) ?? undefined;
               return;
             }
-            if (holdMs > 0) await interactor.longPress(targetX, targetY, holdMs);
-            else await interactor.tap(targetX, targetY);
+            if (holdMs > 0) {
+              interactionResult ??=
+                (await interactor.longPress(targetX, targetY, holdMs)) ?? undefined;
+            } else {
+              interactionResult ??= (await interactor.tap(targetX, targetY)) ?? undefined;
+            }
           });
 
-          return { x, y, count, intervalMs, holdMs, jitterPx, doubleTap };
+          return { x, y, count, intervalMs, holdMs, jitterPx, doubleTap, ...interactionResult };
         }
         case 'swipe': {
           const x1 = Number(positionals[0]);
@@ -255,7 +261,7 @@ export async function dispatchCommand(
           }
 
           if (shouldUseIosDragSeries(device, count)) {
-            await runIosRunnerCommand(
+            const runnerResult = await runIosRunnerCommand(
               device,
               {
                 command: 'dragSeries',
@@ -287,6 +293,7 @@ export async function dispatchCommand(
               count,
               pauseMs,
               pattern,
+              ...runnerResult,
             };
           }
 
diff --git a/src/daemon/__tests__/recording-gestures.test.ts b/src/daemon/__tests__/recording-gestures.test.ts
index c2701336d..3eaa87c8e 100644
--- a/src/daemon/__tests__/recording-gestures.test.ts
+++ b/src/daemon/__tests__/recording-gestures.test.ts
@@ -165,6 +165,29 @@ test('telemetry is still captured when touch overlays are hidden', () => {
   assert.equal(session.recording?.gestureEvents[0]?.kind, 'tap');
 });
 
+test('explicit event reference frame overrides stale snapshot geometry', () => {
+  const session = makeSession();
+
+  recordTouchVisualizationEvent(
+    session,
+    'press',
+    ['300', '2300'],
+    {
+      x: 300,
+      y: 2300,
+      referenceWidth: 1344,
+      referenceHeight: 2992,
+    },
+    {},
+    1_500,
+  );
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'tap');
+  assert.equal(event?.referenceWidth, 1344);
+  assert.equal(event?.referenceHeight, 2992);
+});
+
 test('edge swipe is classified as a back-swipe telemetry event', () => {
   const session = makeSession();
 
diff --git a/src/daemon/__tests__/request-router-android-modal.test.ts b/src/daemon/__tests__/request-router-android-modal.test.ts
new file mode 100644
index 000000000..0d87cfb75
--- /dev/null
+++ b/src/daemon/__tests__/request-router-android-modal.test.ts
@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequestHandler } from '../request-router.ts';
+import { SessionStore } from '../session-store.ts';
+import type { SessionState } from '../types.ts';
+import { LeaseRegistry } from '../lease-registry.ts';
+
+function makeStore(): SessionStore {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-router-android-modal-'));
+  return new SessionStore(path.join(tempRoot, 'sessions'));
+}
+
+function makeAndroidSession(name: string): SessionState {
+  return {
+    name,
+    createdAt: Date.now(),
+    appBundleId: 'com.android.settings',
+    actions: [],
+    device: {
+      platform: 'android',
+      target: 'mobile',
+      id: 'emulator-5554',
+      name: 'Pixel 9 Pro XL',
+      kind: 'emulator',
+      booted: true,
+    },
+    recording: {
+      platform: 'android',
+      outPath: '/tmp/demo.mp4',
+      remotePath: '/sdcard/demo.mp4',
+      remotePid: '4242',
+      startedAt: Date.now() - 1_000,
+      showTouches: true,
+      gestureEvents: [],
+    },
+  };
+}
+
+test('generic Android gesture commands dismiss blocking system dialogs during recording', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set('default', makeAndroidSession('default'));
+  const dispatchCalls: string[][] = [];
+  const execCalls: string[][] = [];
+  const reopenedApps: string[] = [];
+  let snapshotCalls = 0;
+
+  const handler = createRequestHandler({
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    token: 'test-token',
+    sessionStore,
+    leaseRegistry: new LeaseRegistry(),
+    trackDownloadableArtifact: () => 'artifact-id',
+    dispatchCommand: async (_device, command, positionals) => {
+      dispatchCalls.push([command, ...positionals]);
+      return {};
+    },
+    snapshotAndroidUi: async () => {
+      snapshotCalls += 1;
+      if (snapshotCalls === 1) {
+        return {
+          nodes: [
+            {
+              index: 0,
+              type: 'android.widget.TextView',
+              label: 'Process system is not responding',
+              rect: { x: 50, y: 400, width: 500, height: 80 },
+            },
+            {
+              index: 1,
+              type: 'android.widget.Button',
+              label: 'Close app',
+              rect: { x: 100, y: 600, width: 220, height: 80 },
+            },
+          ],
+        };
+      }
+      return { nodes: [] };
+    },
+    reopenAndroidApp: async (_device, app) => {
+      reopenedApps.push(app);
+    },
+    readAndroidAppState: async () => ({ package: 'com.android.settings' }),
+    execCommand: async (_cmd, args) => {
+      execCalls.push(args);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    },
+  });
+
+  const response = await handler({
+    token: 'test-token',
+    session: 'default',
+    command: 'scroll',
+    positionals: ['down', '0.55'],
+    meta: { requestId: 'req-android-modal' },
+  });
+
+  assert.equal(response.ok, true);
+  assert.deepEqual(dispatchCalls, [['scroll', 'down', '0.55']]);
+  assert.deepEqual(execCalls, [['-s', 'emulator-5554', 'shell', 'input', 'tap', '210', '640']]);
+  assert.deepEqual(reopenedApps, ['com.android.settings']);
+});
diff --git a/src/daemon/__tests__/request-router-recording-health.test.ts b/src/daemon/__tests__/request-router-recording-health.test.ts
new file mode 100644
index 000000000..72ae52a85
--- /dev/null
+++ b/src/daemon/__tests__/request-router-recording-health.test.ts
@@ -0,0 +1,72 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequestHandler } from '../request-router.ts';
+import { SessionStore } from '../session-store.ts';
+import type { SessionState } from '../types.ts';
+import { LeaseRegistry } from '../lease-registry.ts';
+
+function makeStore(): SessionStore {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-router-recording-health-'));
+  return new SessionStore(path.join(tempRoot, 'sessions'));
+}
+
+test('router blocks non-record commands when recording was invalidated', async () => {
+  const sessionStore = makeStore();
+  const session: SessionState = {
+    name: 'default',
+    createdAt: Date.now(),
+    actions: [],
+    appBundleId: 'com.apple.Preferences',
+    device: {
+      platform: 'ios',
+      target: 'mobile',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    },
+    recording: {
+      platform: 'ios',
+      outPath: '/tmp/demo.mp4',
+      startedAt: Date.now() - 1_000,
+      showTouches: true,
+      gestureEvents: [],
+      invalidatedReason: 'iOS runner session restarted during recording',
+      child: { kill: () => {} } as any,
+      wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+    },
+  };
+  sessionStore.set('default', session);
+
+  let dispatched = false;
+  const handler = createRequestHandler({
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    token: 'test-token',
+    sessionStore,
+    leaseRegistry: new LeaseRegistry(),
+    trackDownloadableArtifact: () => 'artifact-id',
+    dispatchCommand: async () => {
+      dispatched = true;
+      return {};
+    },
+  });
+
+  const response = await handler({
+    token: 'test-token',
+    session: 'default',
+    command: 'scroll',
+    positionals: ['down'],
+    meta: { requestId: 'req-invalidated-recording' },
+  });
+
+  assert.equal(response.ok, false);
+  if (response.ok) {
+    return;
+  }
+  assert.equal(response.error.code, 'COMMAND_FAILED');
+  assert.equal(response.error.message, 'iOS runner session restarted during recording');
+  assert.equal(dispatched, false);
+});
diff --git a/src/daemon/android-system-dialog.ts b/src/daemon/android-system-dialog.ts
new file mode 100644
index 000000000..03bc794c3
--- /dev/null
+++ b/src/daemon/android-system-dialog.ts
@@ -0,0 +1,213 @@
+import { openAndroidApp, snapshotAndroid, getAndroidAppState } from '../platforms/android/index.ts';
+import { adbArgs } from '../platforms/android/adb.ts';
+import { runCmd } from '../utils/exec.ts';
+import { emitDiagnostic } from '../utils/diagnostics.ts';
+import { centerOfRect, attachRefs, type SnapshotNode } from '../utils/snapshot.ts';
+import { pruneGroupNodes } from './snapshot-processing.ts';
+import type { SessionState } from './types.ts';
+
+const ANDROID_BLOCKING_MODAL_PATTERN = /\bis(?:n't| not)\s+responding\b/i;
+const ANDROID_CLOSE_APP_PATTERN = /^close app$/i;
+const ANDROID_MODAL_POLL_MS = 500;
+const ANDROID_MODAL_POLL_ATTEMPTS = 12;
+
+export async function maybeRecoverAndroidBlockingSystemDialog(params: {
+  session: SessionState;
+  snapshotAndroidUi?: typeof snapshotAndroid;
+  reopenAndroidApp?: typeof openAndroidApp;
+  readAndroidAppState?: typeof getAndroidAppState;
+  execCommand?: typeof runCmd;
+}): Promise<boolean> {
+  const {
+    session,
+    snapshotAndroidUi = snapshotAndroid,
+    reopenAndroidApp = openAndroidApp,
+    readAndroidAppState = getAndroidAppState,
+    execCommand = runCmd,
+  } = params;
+
+  if (session.device.platform !== 'android' || !session.recording) {
+    return false;
+  }
+
+  try {
+    const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+    const closeAppButton = findCloseAppButton(nodes);
+    if (!closeAppButton?.rect) {
+      return false;
+    }
+
+    const { x, y } = centerOfRect(closeAppButton.rect);
+    const tapResult = await execCommand(
+      'adb',
+      adbArgs(session.device, [
+        'shell',
+        'input',
+        'tap',
+        String(Math.round(x)),
+        String(Math.round(y)),
+      ]),
+      { allowFailure: true },
+    );
+    if (tapResult.exitCode !== 0) {
+      emitDiagnostic({
+        level: 'warn',
+        phase: 'android_blocking_dialog_tap_failed',
+        data: {
+          session: session.name,
+          deviceId: session.device.id,
+          exitCode: tapResult.exitCode,
+          stdout: tapResult.stdout.trim(),
+          stderr: tapResult.stderr.trim(),
+        },
+      });
+      return false;
+    }
+
+    const dismissed = await waitForBlockingDialogToDismiss(session, snapshotAndroidUi);
+    if (!dismissed) {
+      emitDiagnostic({
+        level: 'warn',
+        phase: 'android_blocking_dialog_still_present',
+        data: {
+          session: session.name,
+          deviceId: session.device.id,
+        },
+      });
+      return false;
+    }
+
+    if (session.appBundleId) {
+      await reopenAndroidApp(session.device, session.appBundleId);
+      const focused = await waitForFocusedAndroidApp(
+        session,
+        session.appBundleId,
+        readAndroidAppState,
+      );
+      if (!focused) {
+        emitDiagnostic({
+          level: 'warn',
+          phase: 'android_blocking_dialog_relaunch_unfocused',
+          data: {
+            session: session.name,
+            deviceId: session.device.id,
+            appBundleId: session.appBundleId,
+          },
+        });
+        return false;
+      }
+    }
+
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'android_blocking_dialog_recovered',
+      data: {
+        session: session.name,
+        deviceId: session.device.id,
+        appBundleId: session.appBundleId,
+        x,
+        y,
+      },
+    });
+    return true;
+  } catch (error) {
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'android_blocking_dialog_recovery_failed',
+      data: {
+        session: session.name,
+        deviceId: session.device.id,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    return false;
+  }
+}
+
+export async function hasAndroidBlockingSystemDialog(params: {
+  session: SessionState;
+  snapshotAndroidUi?: typeof snapshotAndroid;
+}): Promise<boolean> {
+  const { session, snapshotAndroidUi = snapshotAndroid } = params;
+  if (session.device.platform !== 'android') {
+    return false;
+  }
+  const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+  return nodes.some((node) => {
+    const text = readNodeText(node);
+    return text.length > 0 && ANDROID_BLOCKING_MODAL_PATTERN.test(text);
+  });
+}
+
+async function readAndroidSnapshotNodes(
+  session: SessionState,
+  snapshotAndroidUi: typeof snapshotAndroid,
+): Promise<SnapshotNode[]> {
+  const rawSnapshot = await snapshotAndroidUi(session.device, {
+    interactiveOnly: false,
+    compact: false,
+  });
+  return attachRefs(pruneGroupNodes(rawSnapshot.nodes));
+}
+
+function findCloseAppButton(nodes: SnapshotNode[]): SnapshotNode | undefined {
+  const hasBlockingDialog = nodes.some((node) => {
+    const text = readNodeText(node);
+    return text.length > 0 && ANDROID_BLOCKING_MODAL_PATTERN.test(text);
+  });
+  if (!hasBlockingDialog) {
+    return undefined;
+  }
+  return nodes.find((node) => {
+    const text = readNodeText(node);
+    return text.length > 0 && ANDROID_CLOSE_APP_PATTERN.test(text) && node.rect;
+  });
+}
+
+async function waitForBlockingDialogToDismiss(
+  session: SessionState,
+  snapshotAndroidUi: typeof snapshotAndroid,
+): Promise<boolean> {
+  for (let attempt = 0; attempt < ANDROID_MODAL_POLL_ATTEMPTS; attempt += 1) {
+    if (!(await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }))) {
+      return true;
+    }
+    await sleep(ANDROID_MODAL_POLL_MS);
+  }
+  return !(await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }));
+}
+
+async function waitForFocusedAndroidApp(
+  session: SessionState,
+  appBundleId: string,
+  readAndroidAppState: typeof getAndroidAppState,
+): Promise<boolean> {
+  for (let attempt = 0; attempt < ANDROID_MODAL_POLL_ATTEMPTS; attempt += 1) {
+    const state = await readAndroidAppState(session.device);
+    if (state.package === appBundleId) {
+      return true;
+    }
+    await sleep(ANDROID_MODAL_POLL_MS);
+  }
+  const state = await readAndroidAppState(session.device);
+  return state.package === appBundleId;
+}
+
+function readNodeText(node: {
+  label?: string;
+  value?: string | number | boolean | null;
+  identifier?: string;
+}): string {
+  const parts = [node.label, node.identifier];
+  if (typeof node.value === 'string' && node.value.trim().length > 0) {
+    parts.push(node.value);
+  }
+  return parts
+    .filter((part): part is string => typeof part === 'string' && part.trim().length > 0)
+    .join(' ')
+    .trim();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
diff --git a/src/daemon/handlers/__tests__/interaction.test.ts b/src/daemon/handlers/__tests__/interaction.test.ts
index fad34adb1..de3ea2303 100644
--- a/src/daemon/handlers/__tests__/interaction.test.ts
+++ b/src/daemon/handlers/__tests__/interaction.test.ts
@@ -30,6 +30,23 @@ function makeSession(name: string): SessionState {
   };
 }
 
+function makeAndroidSession(name: string): SessionState {
+  return {
+    name,
+    device: {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel 9 Pro XL',
+      kind: 'emulator',
+      target: 'mobile',
+      booted: true,
+    },
+    createdAt: Date.now(),
+    appBundleId: 'com.android.settings',
+    actions: [],
+  };
+}
+
 const contextFromFlags = (flags: CommandFlags | undefined) => ({
   count: flags?.count,
   intervalMs: flags?.intervalMs,
@@ -156,6 +173,117 @@ test('press coordinates appends touch-visualization events while recording', asy
   assert.equal(recorded?.gestureEvents[0]?.referenceHeight, 874);
 });
 
+test('press coordinates dismisses blocking Android dialog during recording and relaunches app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  const session = makeAndroidSession(sessionName);
+  session.recording = {
+    platform: 'android',
+    outPath: '/tmp/demo.mp4',
+    remotePath: '/sdcard/demo.mp4',
+    remotePid: '1234',
+    startedAt: Date.now() - 1_000,
+    showTouches: true,
+    gestureEvents: [],
+  };
+  sessionStore.set(sessionName, session);
+
+  const dispatchCalls: string[][] = [];
+  const execCalls: string[][] = [];
+  const reopenedApps: string[] = [];
+  let snapshotCalls = 0;
+
+  const response = await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['100', '200'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch: async (_device, command, positionals) => {
+      dispatchCalls.push([command, ...positionals]);
+      return { ok: true };
+    },
+    snapshotAndroidUi: async () => {
+      snapshotCalls += 1;
+      if (snapshotCalls === 1) {
+        return {
+          nodes: [
+            {
+              index: 0,
+              type: 'android.widget.TextView',
+              label: "System UI isn't responding",
+              rect: { x: 40, y: 500, width: 500, height: 80 },
+            },
+            {
+              index: 1,
+              type: 'android.widget.Button',
+              label: 'Close app',
+              rect: { x: 60, y: 700, width: 220, height: 80 },
+            },
+          ],
+        };
+      }
+      return { nodes: [] };
+    },
+    reopenAndroidApp: async (_device, app) => {
+      reopenedApps.push(app);
+    },
+    readAndroidAppState: async () => ({ package: 'com.android.settings' }),
+    execCommand: async (_cmd, args) => {
+      execCalls.push(args);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    },
+  });
+
+  assert.equal(response?.ok, true);
+  assert.deepEqual(dispatchCalls, [['press', '100', '200']]);
+  assert.deepEqual(execCalls, [['-s', 'emulator-5554', 'shell', 'input', 'tap', '170', '740']]);
+  assert.deepEqual(reopenedApps, ['com.android.settings']);
+});
+
+test('press coordinates on Android recording uses physical screen size when no snapshot exists', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-direct-press-frame';
+  const session = makeAndroidSession(sessionName);
+  session.recording = {
+    platform: 'android',
+    outPath: '/tmp/demo.mp4',
+    remotePath: '/sdcard/demo.mp4',
+    remotePid: '1234',
+    startedAt: Date.now() - 1_000,
+    showTouches: true,
+    gestureEvents: [],
+  };
+  session.snapshot = undefined;
+  sessionStore.set(sessionName, session);
+
+  const response = await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['300', '2300'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch: async () => ({ x: 300, y: 2300 }),
+    readAndroidScreenSize: async () => ({ width: 1344, height: 2992 }),
+  });
+
+  assert.equal(response?.ok, true);
+  const event = sessionStore.get(sessionName)?.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'tap');
+  assert.equal(event?.referenceWidth, 1344);
+  assert.equal(event?.referenceHeight, 2992);
+});
+
 test('press @ref preserves native timing in recorded result and touch visualization', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index b92ac6283..f91df5c9b 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -916,6 +916,43 @@ test('record stop force-kills Android screenrecord when SIGINT fails but process
   );
 });
 
+test('record stop reports invalidated recording after cleanup', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-invalidated-recording';
+  const session = makeSession(sessionName, {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  });
+  session.recording = {
+    platform: 'ios',
+    outPath: path.resolve('./invalidated.mp4'),
+    startedAt: Date.now() - 1_000,
+    showTouches: true,
+    gestureEvents: [],
+    invalidatedReason: 'iOS runner session exited during recording',
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  };
+  sessionStore.set(sessionName, session);
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps: makeRecordDeps(),
+  });
+
+  assert.equal(response?.ok, false);
+  if (response?.ok === false) {
+    assert.equal(response.error.code, 'COMMAND_FAILED');
+    assert.equal(response.error.message, 'iOS runner session exited during recording');
+  }
+  assert.equal(sessionStore.get(sessionName)?.recording, undefined);
+});
+
 test('record start leaves overlays disabled with --hide-touches', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-hide-touches';
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 337e00220..30d3d25a9 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -284,6 +284,7 @@ export async function startAndroidRecording(params: {
         remotePath,
         remotePid,
         ...recordingBase,
+        startedAt: Date.now(),
       };
     }
 
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index c54c41054..f9a846e61 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -35,6 +35,9 @@ import {
 
 const IOS_DEVICE_RECORD_MIN_FPS = 1;
 const IOS_DEVICE_RECORD_MAX_FPS = 120;
+const LOCAL_RECORDING_READY_POLL_MS = 250;
+const LOCAL_RECORDING_READY_ATTEMPTS = 24;
+const LOCAL_RECORDING_READY_MIN_POLLS = 2;
 
 export type RecordTraceDeps = {
   runCmd: typeof runCmd;
@@ -80,6 +83,27 @@ function buildRecordingBase(
   };
 }
 
+async function waitForLocalRecordingReady(outPath: string): Promise<number | undefined> {
+  for (let attempt = 0; attempt < LOCAL_RECORDING_READY_ATTEMPTS; attempt += 1) {
+    try {
+      const stat = fs.statSync(outPath);
+      if (stat.size > 0) {
+        return Date.now();
+      }
+    } catch {
+      // Wait for the recorder to create the output file.
+    }
+
+    if (attempt + 1 >= LOCAL_RECORDING_READY_MIN_POLLS) {
+      return Date.now();
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, LOCAL_RECORDING_READY_POLL_MS));
+  }
+
+  return undefined;
+}
+
 async function startRecording(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -169,7 +193,14 @@ async function startRecording(params: {
         allowFailure: true,
       },
     );
-    recording = { platform: 'ios', child, wait, ...recordingBase };
+    const readyAt = await waitForLocalRecordingReady(resolvedOut);
+    recording = {
+      platform: 'ios',
+      child,
+      wait,
+      ...recordingBase,
+      startedAt: readyAt ?? recordingBase.startedAt,
+    };
   } else {
     recording = await startAndroidRecording({ deps, device, recordingBase });
   }
@@ -250,6 +281,7 @@ async function stopRecording(params: {
   }
 
   const recording = activeSession.recording;
+  const invalidatedReason = recording.invalidatedReason;
   activeSession.recording = undefined;
 
   const stopError =
@@ -260,6 +292,16 @@ async function stopRecording(params: {
     return stopError;
   }
 
+  if (invalidatedReason) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: invalidatedReason,
+      },
+    };
+  }
+
   return buildRecordStopResponse(recording);
 }
 
diff --git a/src/daemon/recording-gestures.ts b/src/daemon/recording-gestures.ts
index 8b4de91f3..aea881c14 100644
--- a/src/daemon/recording-gestures.ts
+++ b/src/daemon/recording-gestures.ts
@@ -409,9 +409,6 @@ function resolveEventReferenceFrame(
   snapshot: SnapshotState | undefined,
   result: Record<string, unknown>,
 ): ReferenceFrame | undefined {
-  const snapshotReferenceFrame = getReferenceFrame(snapshot);
-  if (snapshotReferenceFrame) return snapshotReferenceFrame;
-
   const referenceWidth = readNumber(result.referenceWidth);
   const referenceHeight = readNumber(result.referenceHeight);
   if (
@@ -423,6 +420,9 @@ function resolveEventReferenceFrame(
     return { referenceWidth, referenceHeight };
   }
 
+  const snapshotReferenceFrame = getReferenceFrame(snapshot);
+  if (snapshotReferenceFrame) return snapshotReferenceFrame;
+
   return undefined;
 }
 
diff --git a/src/daemon/request-router.ts b/src/daemon/request-router.ts
index 1eefe3aea..665a427c6 100644
--- a/src/daemon/request-router.ts
+++ b/src/daemon/request-router.ts
@@ -3,7 +3,13 @@ import type { CommandFlags } from '../core/dispatch.ts';
 import { dispatchCommand } from '../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../core/capabilities.ts';
 import { AppError, normalizeError } from '../utils/errors.ts';
-import type { DaemonArtifact, DaemonRequest, DaemonResponse, DaemonResponseData } from './types.ts';
+import type {
+  DaemonArtifact,
+  DaemonRequest,
+  DaemonResponse,
+  DaemonResponseData,
+  SessionState,
+} from './types.ts';
 import { SessionStore } from './session-store.ts';
 import {
   contextFromFlags as contextFromFlagsWithLog,
@@ -31,6 +37,13 @@ import {
   augmentTouchVisualizationResult,
   recordTouchVisualizationEvent,
 } from './recording-gestures.ts';
+import {
+  hasAndroidBlockingSystemDialog,
+  maybeRecoverAndroidBlockingSystemDialog,
+} from './android-system-dialog.ts';
+import { snapshotAndroid, openAndroidApp, getAndroidAppState } from '../platforms/android/index.ts';
+import { getRunnerSessionSnapshot } from '../platforms/ios/runner-client.ts';
+import { runCmd } from '../utils/exec.ts';
 
 const selectorValidationExemptCommands = new Set([
   'session_list',
@@ -198,6 +211,34 @@ function collectPendingArtifacts(req: DaemonRequest, data: DaemonResponseData):
   );
 }
 
+function refreshRecordingHealth(session: SessionState): void {
+  const recording = session.recording;
+  if (!recording || session.device.platform !== 'ios') {
+    return;
+  }
+
+  const snapshot = getRunnerSessionSnapshot(session.device.id);
+  if (!recording.runnerSessionId) {
+    if (snapshot?.alive) {
+      recording.runnerSessionId = snapshot.sessionId;
+    }
+    return;
+  }
+
+  if (!snapshot?.alive) {
+    recording.invalidatedReason ??= 'iOS runner session exited during recording';
+    return;
+  }
+
+  if (snapshot.sessionId !== recording.runnerSessionId) {
+    recording.invalidatedReason ??= 'iOS runner session restarted during recording';
+  }
+}
+
+function shouldBlockForInvalidRecording(command: string): boolean {
+  return command !== 'record' && command !== 'close';
+}
+
 export type RequestRouterDeps = {
   logPath: string;
   token: string;
@@ -209,6 +250,10 @@ export type RequestRouterDeps = {
     fileName?: string;
   }) => string;
   dispatchCommand?: typeof dispatchCommand;
+  snapshotAndroidUi?: typeof snapshotAndroid;
+  reopenAndroidApp?: typeof openAndroidApp;
+  readAndroidAppState?: typeof getAndroidAppState;
+  execCommand?: typeof runCmd;
 };
 
 export function createRequestHandler(
@@ -216,6 +261,10 @@ export function createRequestHandler(
 ): (req: DaemonRequest) => Promise<DaemonResponse> {
   const { logPath, token, sessionStore, leaseRegistry, trackDownloadableArtifact } = deps;
   const dispatch = deps.dispatchCommand ?? dispatchCommand;
+  const snapshotAndroidUi = deps.snapshotAndroidUi ?? snapshotAndroid;
+  const reopenAndroidApp = deps.reopenAndroidApp ?? openAndroidApp;
+  const readAndroidAppState = deps.readAndroidAppState ?? getAndroidAppState;
+  const execCommand = deps.execCommand ?? runCmd;
 
   async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     const normalizedReq = normalizeAliasedCommands(req);
@@ -262,9 +311,25 @@ export function createRequestHandler(
           }
           const sessionName = resolveEffectiveSessionName(scopedReq, sessionStore);
           const existingSession = sessionStore.get(sessionName);
+          if (existingSession) {
+            refreshRecordingHealth(existingSession);
+            sessionStore.set(sessionName, existingSession);
+          }
           const lockedReq = applyRequestLockPolicy(scopedReq, existingSession);
           const finalize = (response: DaemonResponse): DaemonResponse =>
             finalizeDaemonResponse(lockedReq, response, trackDownloadableArtifact);
+          if (
+            existingSession?.recording?.invalidatedReason &&
+            shouldBlockForInvalidRecording(command)
+          ) {
+            return finalize({
+              ok: false,
+              error: {
+                code: 'COMMAND_FAILED',
+                message: existingSession.recording.invalidatedReason,
+              },
+            });
+          }
           if (
             existingSession &&
             !lockedReq.meta?.lockPolicy &&
@@ -319,6 +384,10 @@ export function createRequestHandler(
             sessionStore,
             contextFromFlags: (flags, appBundleId, traceLogPath) =>
               contextFromFlags(logPath, flags, appBundleId, traceLogPath),
+            snapshotAndroidUi,
+            reopenAndroidApp,
+            readAndroidAppState,
+            execCommand,
           });
           if (interactionResponse) return finalize(interactionResponse);
 
@@ -340,6 +409,16 @@ export function createRequestHandler(
             });
           }
 
+          if (session.device.platform === 'android' && session.recording && command !== 'record') {
+            await maybeRecoverAndroidBlockingSystemDialog({
+              session,
+              snapshotAndroidUi,
+              reopenAndroidApp,
+              readAndroidAppState,
+              execCommand,
+            });
+          }
+
           const positionals = lockedReq.positionals ?? [];
           const outFlag = lockedReq.flags?.out;
           const resolvedPositionals =
@@ -359,15 +438,39 @@ export function createRequestHandler(
               ? { ...(lockedReq.flags ?? {}), out: resolvedOut }
               : (lockedReq.flags ?? {});
           const actionStartedAt = Date.now();
-          const data = await dispatch(session.device, command, resolvedPositionals, resolvedOut, {
+          const dispatchContext = {
             ...contextFromFlags(
               logPath,
               lockedReq.flags,
               session.appBundleId,
               session.trace?.outPath,
             ),
+          };
+          const data = await dispatch(session.device, command, resolvedPositionals, resolvedOut, {
+            ...dispatchContext,
           });
           const actionFinishedAt = Date.now();
+          await maybeRecoverAndroidBlockingSystemDialog({
+            session,
+            snapshotAndroidUi,
+            reopenAndroidApp,
+            readAndroidAppState,
+            execCommand,
+          });
+          if (
+            command !== 'record' &&
+            session.device.platform === 'android' &&
+            session.recording &&
+            (await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }))
+          ) {
+            return finalize({
+              ok: false,
+              error: {
+                code: 'COMMAND_FAILED',
+                message: 'Android system dialog blocked the recording session',
+              },
+            });
+          }
           const visualizationData = augmentTouchVisualizationResult(
             session,
             command,
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 8b58ac160..d6295e756 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -113,6 +113,8 @@ type SessionRecordingBase = {
   startedAt: number;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
+  runnerSessionId?: string;
+  invalidatedReason?: string;
 };
 
 export type SessionState = {
diff --git a/src/platforms/android/index.ts b/src/platforms/android/index.ts
index 601bac8a4..6968a58a4 100644
--- a/src/platforms/android/index.ts
+++ b/src/platforms/android/index.ts
@@ -28,6 +28,7 @@ export {
   fillAndroid,
   scrollAndroid,
   scrollIntoViewAndroid,
+  getAndroidScreenSize,
 } from './input-actions.ts';
 
 export {
diff --git a/src/platforms/android/input-actions.ts b/src/platforms/android/input-actions.ts
index 1febddce3..82c327a17 100644
--- a/src/platforms/android/input-actions.ts
+++ b/src/platforms/android/input-actions.ts
@@ -217,7 +217,7 @@ export async function scrollIntoViewAndroid(device: DeviceInfo, text: string): P
   );
 }
 
-async function getAndroidScreenSize(
+export async function getAndroidScreenSize(
   device: DeviceInfo,
 ): Promise<{ width: number; height: number }> {
   const result = await runCmd('adb', adbArgs(device, ['shell', 'wm', 'size']));
diff --git a/src/platforms/ios/__tests__/runner-xctestrun.test.ts b/src/platforms/ios/__tests__/runner-xctestrun.test.ts
new file mode 100644
index 000000000..0bee65588
--- /dev/null
+++ b/src/platforms/ios/__tests__/runner-xctestrun.test.ts
@@ -0,0 +1,94 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { DeviceInfo } from '../../../utils/device.ts';
+import { findXctestrun, scoreXctestrunCandidate } from '../runner-xctestrun.ts';
+
+const iosSimulator: DeviceInfo = {
+  platform: 'ios',
+  id: 'sim-1',
+  name: 'iPhone Simulator',
+  kind: 'simulator',
+  booted: true,
+};
+
+const iosDevice: DeviceInfo = {
+  platform: 'ios',
+  id: 'device-1',
+  name: 'iPhone',
+  kind: 'device',
+  booted: true,
+};
+
+test('findXctestrun prefers simulator xctestrun over newer macos candidate', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'runner-xctestrun-'));
+  try {
+    const simulatorPath = path.join(
+      root,
+      'Build',
+      'Products',
+      'AgentDeviceRunner_AgentDeviceRunner_iphonesimulator26.2-arm64-x86_64.xctestrun',
+    );
+    const macosPath = path.join(
+      root,
+      'macos',
+      'Build',
+      'Products',
+      'AgentDeviceRunner.env.session-123.xctestrun',
+    );
+    fs.mkdirSync(path.dirname(simulatorPath), { recursive: true });
+    fs.mkdirSync(path.dirname(macosPath), { recursive: true });
+    fs.writeFileSync(simulatorPath, 'sim');
+    fs.writeFileSync(macosPath, 'mac');
+    const now = new Date();
+    fs.utimesSync(simulatorPath, now, now);
+    fs.utimesSync(macosPath, new Date(now.getTime() + 5_000), new Date(now.getTime() + 5_000));
+
+    assert.equal(findXctestrun(root, iosSimulator), simulatorPath);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('findXctestrun prefers base xctestrun over newer env xctestrun for matching platform', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'runner-xctestrun-'));
+  try {
+    const basePath = path.join(
+      root,
+      'Build',
+      'Products',
+      'AgentDeviceRunner_AgentDeviceRunner_iphoneos26.2-arm64.xctestrun',
+    );
+    const envPath = path.join(
+      root,
+      'Build',
+      'Products',
+      'AgentDeviceRunner.env.session-456.xctestrun',
+    );
+    fs.mkdirSync(path.dirname(basePath), { recursive: true });
+    fs.writeFileSync(basePath, 'base');
+    fs.writeFileSync(envPath, 'env');
+    const now = new Date();
+    fs.utimesSync(basePath, now, now);
+    fs.utimesSync(envPath, new Date(now.getTime() + 5_000), new Date(now.getTime() + 5_000));
+
+    assert.equal(findXctestrun(root, iosDevice), basePath);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('scoreXctestrunCandidate penalizes macos and env xctestrun files for simulator runs', () => {
+  const simulatorScore = scoreXctestrunCandidate(
+    '/tmp/derived/Build/Products/AgentDeviceRunner_AgentDeviceRunner_iphonesimulator26.2-arm64.xctestrun',
+    iosSimulator,
+  );
+  const macosEnvScore = scoreXctestrunCandidate(
+    '/tmp/derived/macos/Build/Products/AgentDeviceRunner.env.session-123.xctestrun',
+    iosSimulator,
+  );
+
+  assert.ok(simulatorScore > macosEnvScore);
+});
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 4e2de7dcd..0735e6e5b 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -17,6 +17,7 @@ import {
 import {
   type RunnerSession,
   ensureRunnerSession,
+  getRunnerSessionSnapshot,
   stopRunnerSession,
   stopIosRunnerSession,
   validateRunnerDevice,
@@ -163,6 +164,7 @@ export {
 } from './runner-xctestrun.ts';
 
 export {
+  getRunnerSessionSnapshot,
   stopIosRunnerSession,
   abortAllIosRunnerSessions,
   stopAllIosRunnerSessions,
diff --git a/src/platforms/ios/runner-session.ts b/src/platforms/ios/runner-session.ts
index cc3acfd2e..0c3017142 100644
--- a/src/platforms/ios/runner-session.ts
+++ b/src/platforms/ios/runner-session.ts
@@ -20,6 +20,7 @@ import {
 } from './runner-transport.ts';
 import {
   ensureXctestrun,
+  IOS_RUNNER_CONTAINER_BUNDLE_IDS,
   prepareXctestrunWithEnv,
   resolveRunnerDestination,
   resolveRunnerMaxConcurrentDestinationsFlag,
@@ -28,6 +29,7 @@ import {
 import type { RunnerCommand } from './runner-client.ts';
 
 export type RunnerSession = {
+  sessionId: string;
   device: DeviceInfo;
   deviceId: string;
   port: number;
@@ -61,6 +63,7 @@ export async function ensureRunnerSession(
     }
 
     await ensureBootedIfNeeded(device);
+    await cleanupStaleSimulatorRunnerBundles(device);
     const xctestrun = await ensureXctestrun(device, options);
     const port = await getFreePort();
     const { xctestrunPath, jsonPath } = await prepareXctestrunWithEnv(
@@ -103,6 +106,7 @@ export async function ensureRunnerSession(
     });
 
     const session: RunnerSession = {
+      sessionId: `${device.id}:${port}:${Date.now()}`,
       device,
       deviceId: device.id,
       port,
@@ -117,6 +121,46 @@ export async function ensureRunnerSession(
   });
 }
 
+async function cleanupStaleSimulatorRunnerBundles(device: DeviceInfo): Promise<void> {
+  if (device.kind !== 'simulator') {
+    return;
+  }
+
+  for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
+    const result = await runCmd(
+      'xcrun',
+      buildSimctlArgsForDevice(device, ['uninstall', device.id, bundleId]),
+      {
+        allowFailure: true,
+      },
+    );
+    if (result.exitCode !== 0) {
+      const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+      if (
+        !output.includes('not installed') &&
+        !output.includes('found nothing') &&
+        !output.includes('no such file') &&
+        !output.includes('invalid device') &&
+        !output.includes('could not find')
+      ) {
+        // Best-effort cleanup only; xcodebuild may still be able to install.
+        continue;
+      }
+    }
+  }
+}
+
+export function getRunnerSessionSnapshot(
+  deviceId: string,
+): { sessionId: string; alive: boolean } | null {
+  const session = runnerSessions.get(deviceId);
+  if (!session) return null;
+  return {
+    sessionId: session.sessionId,
+    alive: isRunnerProcessAlive(session.child.pid),
+  };
+}
+
 export async function stopRunnerSession(session: RunnerSession): Promise<void> {
   await withRunnerSessionLock(session.deviceId, async () => {
     await stopRunnerSessionInternal(session.deviceId, session);
diff --git a/src/platforms/ios/runner-xctestrun.ts b/src/platforms/ios/runner-xctestrun.ts
index a9859e4df..4c0389201 100644
--- a/src/platforms/ios/runner-xctestrun.ts
+++ b/src/platforms/ios/runner-xctestrun.ts
@@ -7,15 +7,8 @@ import { runCmd, runCmdStreaming, type ExecBackgroundResult } from '../../utils/
 import { isEnvTruthy } from '../../utils/retry.ts';
 import { resolveApplePlatformName, type DeviceInfo } from '../../utils/device.ts';
 import { withKeyedLock } from '../../utils/keyed-lock.ts';
-import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { resolveSigningFailureHint } from './runner-errors.ts';
 import { logChunk } from './runner-transport.ts';
-import {
-  repairMacOsRunnerProductsIfNeeded,
-  isExpectedRunnerRepairFailure,
-} from './runner-macos-products.ts';
-import { resolveExistingXctestrunProductPaths } from './runner-xctestrun-products.ts';
-export { xctestrunReferencesExistingProducts } from './runner-xctestrun-products.ts';
 
 const DEFAULT_IOS_RUNNER_APP_BUNDLE_ID = 'com.callstack.agentdevice.runner';
 
@@ -61,90 +54,24 @@ export const IOS_RUNNER_CONTAINER_BUNDLE_IDS: string[] = resolveRunnerContainerB
   process.env,
 );
 
-type EnsureXctestrunDeps = {
-  findProjectRoot: () => string;
-  findXctestrun: (root: string) => string | null;
-  xctestrunReferencesProjectRoot: (xctestrunPath: string, projectRoot: string) => boolean;
-  resolveExistingXctestrunProductPaths: (xctestrunPath: string) => string[] | null;
-  repairRunnerProductsIfNeeded: (
-    device: DeviceInfo,
-    productPaths: string[],
-    xctestrunPath: string,
-  ) => Promise<void>;
-  assertSafeDerivedCleanup: (derivedPath: string) => void;
-  cleanRunnerDerivedArtifacts: (derivedPath: string) => void;
-  buildRunnerXctestrun: (
-    device: DeviceInfo,
-    projectPath: string,
-    derived: string,
-    options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
-  ) => Promise<void>;
-};
-
-const defaultEnsureXctestrunDeps: EnsureXctestrunDeps = {
-  findProjectRoot,
-  findXctestrun,
-  xctestrunReferencesProjectRoot,
-  resolveExistingXctestrunProductPaths,
-  repairRunnerProductsIfNeeded: repairMacOsRunnerProductsIfNeeded,
-  assertSafeDerivedCleanup,
-  cleanRunnerDerivedArtifacts,
-  buildRunnerXctestrun,
-};
-
 export async function ensureXctestrun(
   device: DeviceInfo,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
-  deps: EnsureXctestrunDeps = defaultEnsureXctestrunDeps,
 ): Promise<string> {
-  const derived = resolveRunnerDerivedPath(device);
-  const projectRoot = deps.findProjectRoot();
+  const derived = resolveRunnerDerivedPath(device.kind);
   return await withKeyedLock(runnerXctestrunBuildLocks, derived, async () => {
     if (shouldCleanDerived()) {
-      emitRunnerXctestrunDecision('clean', 'forced_clean', { derived });
-      deps.assertSafeDerivedCleanup(derived);
-      deps.cleanRunnerDerivedArtifacts(derived);
-    }
-    const existing = evaluateExistingXctestrun({
-      derived,
-      projectRoot,
-      findXctestrun: deps.findXctestrun,
-      xctestrunReferencesProjectRoot: deps.xctestrunReferencesProjectRoot,
-      resolveExistingXctestrunProductPaths: deps.resolveExistingXctestrunProductPaths,
-    });
-    if (existing.reason !== 'reuse_ready') {
-      emitRunnerXctestrunDecision('rebuild', existing.reason, {
-        derived,
-        xctestrunPath: existing.xctestrunPath,
-      });
-    }
-    if (existing.reason === 'reuse_ready') {
+      assertSafeDerivedCleanup(derived);
       try {
-        await deps.repairRunnerProductsIfNeeded(
-          device,
-          existing.productPaths,
-          existing.xctestrunPath,
-        );
-        emitRunnerXctestrunDecision('reuse', 'reuse_ready', {
-          derived,
-          xctestrunPath: existing.xctestrunPath,
-        });
-        return existing.xctestrunPath;
-      } catch (error) {
-        if (!isExpectedRunnerRepairFailure(error)) {
-          throw error;
-        }
-        emitRunnerXctestrunDecision('rebuild', 'repair_failed', {
-          derived,
-          xctestrunPath: existing.xctestrunPath,
-        });
-        // Fall through and rebuild from a clean derived state.
+        fs.rmSync(derived, { recursive: true, force: true });
+      } catch {
+        // ignore
       }
     }
-    if (existing.xctestrunPath) {
-      deps.assertSafeDerivedCleanup(derived);
-      deps.cleanRunnerDerivedArtifacts(derived);
-    }
+    const existing = findXctestrun(derived, device);
+    if (existing) return existing;
+
+    const projectRoot = findProjectRoot();
     const projectPath = path.join(
       projectRoot,
       'ios-runner',
@@ -156,62 +83,78 @@ export async function ensureXctestrun(
       throw new AppError('COMMAND_FAILED', 'iOS runner project not found', { projectPath });
     }
 
-    await deps.buildRunnerXctestrun(device, projectPath, derived, options);
+    const runnerBundleBuildSettings = resolveRunnerBundleBuildSettings(process.env);
+    const signingBuildSettings = resolveRunnerSigningBuildSettings(
+      process.env,
+      device.kind === 'device',
+    );
+    const provisioningArgs = device.kind === 'device' ? ['-allowProvisioningUpdates'] : [];
+    const performanceBuildSettings = resolveRunnerPerformanceBuildSettings();
+    try {
+      await runCmdStreaming(
+        'xcodebuild',
+        [
+          'build-for-testing',
+          '-project',
+          projectPath,
+          '-scheme',
+          'AgentDeviceRunner',
+          '-parallel-testing-enabled',
+          'NO',
+          resolveRunnerMaxConcurrentDestinationsFlag(device),
+          '1',
+          '-destination',
+          resolveRunnerBuildDestination(device),
+          '-derivedDataPath',
+          derived,
+          ...performanceBuildSettings,
+          ...runnerBundleBuildSettings,
+          ...provisioningArgs,
+          ...signingBuildSettings,
+        ],
+        {
+          detached: true,
+          onSpawn: (child) => {
+            runnerPrepProcesses.add(child);
+            child.on('close', () => {
+              runnerPrepProcesses.delete(child);
+            });
+          },
+          onStdoutChunk: (chunk) => {
+            logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
+          },
+          onStderrChunk: (chunk) => {
+            logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
+          },
+        },
+      );
+    } catch (err) {
+      const appErr = err instanceof AppError ? err : new AppError('COMMAND_FAILED', String(err));
+      const hint = resolveSigningFailureHint(appErr);
+      throw new AppError('COMMAND_FAILED', 'xcodebuild build-for-testing failed', {
+        error: appErr.message,
+        details: appErr.details,
+        logPath: options.logPath,
+        hint,
+      });
+    }
 
-    const built = deps.findXctestrun(derived);
+    const built = findXctestrun(derived, device);
     if (!built) {
       throw new AppError('COMMAND_FAILED', 'Failed to locate .xctestrun after build');
     }
-    const builtProductPaths = deps.resolveExistingXctestrunProductPaths(built);
-    if (!builtProductPaths) {
-      throw new AppError('COMMAND_FAILED', 'Runner build is missing expected products', {
-        xctestrunPath: built,
-      });
-    }
-    await deps.repairRunnerProductsIfNeeded(device, builtProductPaths, built);
-    emitRunnerXctestrunDecision('build', 'built_new', {
-      derived,
-      xctestrunPath: built,
-    });
     return built;
   });
 }
 
-function cleanRunnerDerivedArtifacts(derived: string): void {
-  try {
-    if (!fs.existsSync(derived)) return;
-    if (path.basename(derived) !== 'derived') {
-      fs.rmSync(derived, { recursive: true, force: true });
-      return;
-    }
-    for (const entry of fs.readdirSync(derived, { withFileTypes: true })) {
-      if (!shouldDeleteRunnerDerivedRootEntry(entry.name)) continue;
-      fs.rmSync(path.join(derived, entry.name), { recursive: true, force: true });
-    }
-  } catch {
-    // ignore
-  }
-}
-
-const RUNNER_ROOT_TRANSIENT_ENTRY_NAMES = new Set([
-  'Build',
-  'BuildCache.noindex',
-  'Index.noindex',
-  'Logs',
-  'ModuleCache.noindex',
-  'SDKStatCaches.noindex',
-  'SourcePackages',
-  'TextBasedInstallAPI',
-  'info.plist',
-]);
-
-export function shouldDeleteRunnerDerivedRootEntry(entryName: string): boolean {
-  return RUNNER_ROOT_TRANSIENT_ENTRY_NAMES.has(entryName);
-}
+type XctestrunCandidate = {
+  path: string;
+  mtimeMs: number;
+};
 
-function findXctestrun(root: string): string | null {
+export function findXctestrun(root: string, device: DeviceInfo): string | null {
   if (!fs.existsSync(root)) return null;
-  const candidates: { path: string; mtimeMs: number }[] = [];
+  const candidates: XctestrunCandidate[] = [];
   const stack: string[] = [root];
   while (stack.length > 0) {
     const current = stack.pop() as string;
@@ -233,31 +176,76 @@ function findXctestrun(root: string): string | null {
     }
   }
   if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  candidates.sort(
+    (a, b) =>
+      compareXctestrunCandidates(b.path, a.path, device) ||
+      b.mtimeMs - a.mtimeMs ||
+      a.path.localeCompare(b.path),
+  );
   return candidates[0]?.path ?? null;
 }
 
-export function xctestrunReferencesProjectRoot(
-  xctestrunPath: string,
-  projectRoot: string,
-): boolean {
-  try {
-    const contents = fs.readFileSync(xctestrunPath, 'utf8');
-    const candidateRoots = new Set<string>([projectRoot]);
-    try {
-      candidateRoots.add(fs.realpathSync(projectRoot));
-    } catch {
-      // ignore
+function compareXctestrunCandidates(left: string, right: string, device: DeviceInfo): number {
+  return scoreXctestrunCandidate(left, device) - scoreXctestrunCandidate(right, device);
+}
+
+export function scoreXctestrunCandidate(candidatePath: string, device: DeviceInfo): number {
+  let score = 0;
+  const normalizedPath = candidatePath.toLowerCase();
+  const fileName = path.basename(normalizedPath);
+
+  if (fileName.startsWith('agentdevicerunner.env.')) {
+    score -= 1_000;
+  }
+
+  if (normalizedPath.includes(`${path.sep}macos${path.sep}`)) {
+    score -= 5_000;
+  }
+
+  const platformHints = resolveRunnerXctestrunHints(device);
+  if (platformHints.preferred.length > 0) {
+    if (platformHints.preferred.some((hint) => normalizedPath.includes(hint))) {
+      score += 2_000;
+    } else {
+      score -= 500;
     }
-    for (const root of candidateRoots) {
-      if (contents.includes(root)) {
-        return true;
-      }
+  }
+
+  if (platformHints.disallowed.some((hint) => normalizedPath.includes(hint))) {
+    score -= 2_500;
+  }
+
+  return score;
+}
+
+function resolveRunnerXctestrunHints(device: DeviceInfo): {
+  preferred: string[];
+  disallowed: string[];
+} {
+  if (device.target === 'tv') {
+    if (device.kind === 'simulator') {
+      return {
+        preferred: ['appletvsimulator'],
+        disallowed: ['appletvos', 'iphoneos', 'iphonesimulator'],
+      };
     }
-    return false;
-  } catch {
-    return false;
+    return {
+      preferred: ['appletvos'],
+      disallowed: ['appletvsimulator', 'iphoneos', 'iphonesimulator'],
+    };
+  }
+
+  if (device.kind === 'simulator') {
+    return {
+      preferred: ['iphonesimulator'],
+      disallowed: ['iphoneos', 'appletvos', 'appletvsimulator'],
+    };
   }
+
+  return {
+    preferred: ['iphoneos'],
+    disallowed: ['iphonesimulator', 'appletvos', 'appletvsimulator'],
+  };
 }
 
 function findProjectRoot(): string {
@@ -355,89 +343,19 @@ export async function prepareXctestrunWithEnv(
   return { xctestrunPath: tmpXctestrunPath, jsonPath: tmpJsonPath };
 }
 
-async function buildRunnerXctestrun(
-  device: DeviceInfo,
-  projectPath: string,
-  derived: string,
-  options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
-): Promise<void> {
-  const runnerBundleBuildSettings = resolveRunnerBundleBuildSettings(process.env);
-  const signingBuildSettings = resolveRunnerSigningBuildSettings(
-    process.env,
-    device.kind === 'device',
-    device.platform,
-  );
-  const provisioningArgs = device.kind === 'device' ? ['-allowProvisioningUpdates'] : [];
-  const performanceBuildSettings = resolveRunnerPerformanceBuildSettings();
-  try {
-    await runCmdStreaming(
-      'xcodebuild',
-      [
-        'build-for-testing',
-        '-project',
-        projectPath,
-        '-scheme',
-        'AgentDeviceRunner',
-        '-parallel-testing-enabled',
-        'NO',
-        resolveRunnerMaxConcurrentDestinationsFlag(device),
-        '1',
-        '-destination',
-        resolveRunnerBuildDestination(device),
-        '-derivedDataPath',
-        derived,
-        ...performanceBuildSettings,
-        ...runnerBundleBuildSettings,
-        ...provisioningArgs,
-        ...signingBuildSettings,
-      ],
-      {
-        detached: true,
-        onSpawn: (child) => {
-          runnerPrepProcesses.add(child);
-          child.on('close', () => {
-            runnerPrepProcesses.delete(child);
-          });
-        },
-        onStdoutChunk: (chunk) => {
-          logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
-        },
-        onStderrChunk: (chunk) => {
-          logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
-        },
-      },
-    );
-  } catch (err) {
-    const appErr = err instanceof AppError ? err : new AppError('COMMAND_FAILED', String(err));
-    const hint = resolveSigningFailureHint(appErr);
-    throw new AppError('COMMAND_FAILED', 'xcodebuild build-for-testing failed', {
-      error: appErr.message,
-      details: appErr.details,
-      logPath: options.logPath,
-      hint,
-    });
-  }
-}
-
-function resolveRunnerDerivedPath(device: DeviceInfo): string {
+function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
   const override = process.env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH?.trim();
   if (override) {
     return path.resolve(override);
   }
-  if (device.platform === 'macos') {
-    return path.join(RUNNER_DERIVED_ROOT, 'derived', 'macos');
-  }
-  if (device.kind === 'simulator') {
+  if (kind === 'simulator') {
     return path.join(RUNNER_DERIVED_ROOT, 'derived');
   }
-  return path.join(RUNNER_DERIVED_ROOT, 'derived', device.kind);
+  return path.join(RUNNER_DERIVED_ROOT, 'derived', kind);
 }
 
 export function resolveRunnerDestination(device: DeviceInfo): string {
   const platformName = resolveRunnerPlatformName(device);
-  if (platformName === 'macOS') {
-    return `platform=macOS,arch=${resolveMacRunnerArch()}`;
-  }
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
@@ -446,36 +364,23 @@ export function resolveRunnerDestination(device: DeviceInfo): string {
 
 export function resolveRunnerBuildDestination(device: DeviceInfo): string {
   const platformName = resolveRunnerPlatformName(device);
-  if (platformName === 'macOS') {
-    return `platform=macOS,arch=${resolveMacRunnerArch()}`;
-  }
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
   return `generic/platform=${platformName}`;
 }
 
-function resolveRunnerPlatformName(device: DeviceInfo): 'iOS' | 'tvOS' | 'macOS' {
-  if (device.platform !== 'ios' && device.platform !== 'macos') {
+function resolveRunnerPlatformName(device: DeviceInfo): 'iOS' | 'tvOS' {
+  if (device.platform !== 'ios') {
     throw new AppError(
       'UNSUPPORTED_PLATFORM',
       `Unsupported platform for iOS runner: ${device.platform}`,
     );
   }
-  if (device.platform === 'macos') {
-    return 'macOS';
-  }
   return resolveApplePlatformName(device.target);
 }
 
-function resolveMacRunnerArch(): 'arm64' | 'x86_64' {
-  return process.arch === 'arm64' ? 'arm64' : 'x86_64';
-}
-
 export function resolveRunnerMaxConcurrentDestinationsFlag(device: DeviceInfo): string {
-  if (device.platform === 'macos') {
-    return '-maximum-concurrent-test-device-destinations';
-  }
   return device.kind === 'device'
     ? '-maximum-concurrent-test-device-destinations'
     : '-maximum-concurrent-test-simulator-destinations';
@@ -484,16 +389,7 @@ export function resolveRunnerMaxConcurrentDestinationsFlag(device: DeviceInfo):
 export function resolveRunnerSigningBuildSettings(
   env: NodeJS.ProcessEnv = process.env,
   forDevice = false,
-  platform: DeviceInfo['platform'] = 'ios',
 ): string[] {
-  if (platform === 'macos') {
-    return [
-      'CODE_SIGNING_ALLOWED=NO',
-      'CODE_SIGNING_REQUIRED=NO',
-      'CODE_SIGN_IDENTITY=',
-      'DEVELOPMENT_TEAM=',
-    ];
-  }
   if (!forDevice) {
     return [];
   }
@@ -520,8 +416,8 @@ export function resolveRunnerBundleBuildSettings(env: NodeJS.ProcessEnv = proces
   ];
 }
 
-export function resolveRunnerPerformanceBuildSettings(): string[] {
-  return ['COMPILER_INDEX_STORE_ENABLE=NO', 'ENABLE_CODE_COVERAGE=NO'];
+function resolveRunnerPerformanceBuildSettings(): string[] {
+  return ['COMPILER_INDEX_STORE_ENABLE=NO'];
 }
 
 function shouldCleanDerived(): boolean {
@@ -552,58 +448,3 @@ export function assertSafeDerivedCleanup(
 function isCleanupOverrideAllowed(env: NodeJS.ProcessEnv = process.env): boolean {
   return isEnvTruthy(env.AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN);
 }
-
-type ExistingXctestrunState =
-  | {
-      reason: 'missing_xctestrun';
-      xctestrunPath: null;
-    }
-  | {
-      reason: 'project_root_mismatch' | 'missing_products' | 'reuse_ready';
-      xctestrunPath: string;
-      productPaths: string[];
-    };
-
-function evaluateExistingXctestrun(options: {
-  derived: string;
-  projectRoot: string;
-  findXctestrun: (root: string) => string | null;
-  xctestrunReferencesProjectRoot: (xctestrunPath: string, projectRoot: string) => boolean;
-  resolveExistingXctestrunProductPaths: (xctestrunPath: string) => string[] | null;
-}): ExistingXctestrunState {
-  const xctestrunPath = options.findXctestrun(options.derived);
-  if (!xctestrunPath) {
-    return { reason: 'missing_xctestrun', xctestrunPath: null };
-  }
-  const productPaths = options.resolveExistingXctestrunProductPaths(xctestrunPath);
-  if (!productPaths) {
-    return { reason: 'missing_products', xctestrunPath, productPaths: [] };
-  }
-  if (!options.xctestrunReferencesProjectRoot(xctestrunPath, options.projectRoot)) {
-    return { reason: 'project_root_mismatch', xctestrunPath, productPaths };
-  }
-  return { reason: 'reuse_ready', xctestrunPath, productPaths };
-}
-
-function emitRunnerXctestrunDecision(
-  action: 'clean' | 'reuse' | 'rebuild' | 'build',
-  reason:
-    | 'forced_clean'
-    | 'missing_xctestrun'
-    | 'project_root_mismatch'
-    | 'missing_products'
-    | 'repair_failed'
-    | 'reuse_ready'
-    | 'built_new',
-  data: Record<string, unknown>,
-): void {
-  emitDiagnostic({
-    level: action === 'rebuild' ? 'warn' : 'info',
-    phase: 'runner_xctestrun_cache',
-    data: {
-      action,
-      reason,
-      ...data,
-    },
-  });
-}
diff --git a/src/utils/interactors.ts b/src/utils/interactors.ts
index 9a2ed5146..ee16fb617 100644
--- a/src/utils/interactors.ts
+++ b/src/utils/interactors.ts
@@ -48,13 +48,19 @@ type Interactor = {
   ): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
-  tap(x: number, y: number): Promise<void>;
-  doubleTap(x: number, y: number): Promise<void>;
-  swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
-  longPress(x: number, y: number, durationMs?: number): Promise<void>;
-  focus(x: number, y: number): Promise<void>;
+  tap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  swipe(
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number,
+    durationMs?: number,
+  ): Promise<Record<string, unknown> | void>;
+  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
+  focus(x: number, y: number): Promise<Record<string, unknown> | void>;
   type(text: string): Promise<void>;
-  fill(x: number, y: number, text: string): Promise<void>;
+  fill(x: number, y: number, text: string): Promise<Record<string, unknown> | void>;
   scroll(direction: string, amount?: number): Promise<void>;
   scrollIntoView(text: string): Promise<{ attempts?: number } | void>;
   screenshot(outPath: string, appBundleId?: string): Promise<void>;
@@ -180,14 +186,14 @@ function iosRunnerOverrides(
     runnerOpts,
     overrides: {
       tap: async (x, y) => {
-        await runIosRunnerCommand(
+        return await runIosRunnerCommand(
           device,
           { command: 'tap', x, y, appBundleId: ctx.appBundleId },
           runnerOpts,
         );
       },
       doubleTap: async (x, y) => {
-        await runIosRunnerCommand(
+        return await runIosRunnerCommand(
           device,
           {
             command: 'tapSeries',
@@ -202,21 +208,21 @@ function iosRunnerOverrides(
         );
       },
       swipe: async (x1, y1, x2, y2, durationMs) => {
-        await runIosRunnerCommand(
+        return await runIosRunnerCommand(
           device,
           { command: 'drag', x: x1, y: y1, x2, y2, durationMs, appBundleId: ctx.appBundleId },
           runnerOpts,
         );
       },
       longPress: async (x, y, durationMs) => {
-        await runIosRunnerCommand(
+        return await runIosRunnerCommand(
           device,
           { command: 'longPress', x, y, durationMs, appBundleId: ctx.appBundleId },
           runnerOpts,
         );
       },
       focus: async (x, y) => {
-        await runIosRunnerCommand(
+        return await runIosRunnerCommand(
           device,
           { command: 'tap', x, y, appBundleId: ctx.appBundleId },
           runnerOpts,
@@ -230,7 +236,7 @@ function iosRunnerOverrides(
         );
       },
       fill: async (x, y, text) => {
-        await runIosRunnerCommand(
+        const tapResult = await runIosRunnerCommand(
           device,
           { command: 'tap', x, y, appBundleId: ctx.appBundleId },
           runnerOpts,
@@ -240,6 +246,7 @@ function iosRunnerOverrides(
           { command: 'type', text, clearFirst: true, appBundleId: ctx.appBundleId },
           runnerOpts,
         );
+        return tapResult;
       },
       scroll: async (direction, _amount) => {
         if (!['up', 'down', 'left', 'right'].includes(direction)) {

From bccf61106385c0743017f176115fe279396f4384 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sun, 22 Mar 2026 18:53:25 +0100
Subject: [PATCH 07/11] refactor: simplify touch recording recovery

---
 .../request-router-android-modal.test.ts      |  1 +
 src/daemon/android-system-dialog.ts           | 54 +++++------
 .../handlers/__tests__/interaction.test.ts    | 95 ++++++++-----------
 src/daemon/recording-gestures.ts              | 73 ++------------
 src/daemon/request-router.ts                  | 41 +++-----
 src/daemon/touch-reference-frame.ts           | 75 +++++++++++++++
 src/daemon/types.ts                           |  4 +
 7 files changed, 161 insertions(+), 182 deletions(-)
 create mode 100644 src/daemon/touch-reference-frame.ts

diff --git a/src/daemon/__tests__/request-router-android-modal.test.ts b/src/daemon/__tests__/request-router-android-modal.test.ts
index 0d87cfb75..98c56fe21 100644
--- a/src/daemon/__tests__/request-router-android-modal.test.ts
+++ b/src/daemon/__tests__/request-router-android-modal.test.ts
@@ -101,4 +101,5 @@ test('generic Android gesture commands dismiss blocking system dialogs during re
   assert.deepEqual(dispatchCalls, [['scroll', 'down', '0.55']]);
   assert.deepEqual(execCalls, [['-s', 'emulator-5554', 'shell', 'input', 'tap', '210', '640']]);
   assert.deepEqual(reopenedApps, ['com.android.settings']);
+  assert.equal(snapshotCalls, 2);
 });
diff --git a/src/daemon/android-system-dialog.ts b/src/daemon/android-system-dialog.ts
index 03bc794c3..145ecad7d 100644
--- a/src/daemon/android-system-dialog.ts
+++ b/src/daemon/android-system-dialog.ts
@@ -11,13 +11,15 @@ const ANDROID_CLOSE_APP_PATTERN = /^close app$/i;
 const ANDROID_MODAL_POLL_MS = 500;
 const ANDROID_MODAL_POLL_ATTEMPTS = 12;
 
-export async function maybeRecoverAndroidBlockingSystemDialog(params: {
+export type AndroidBlockingDialogRecoveryResult = 'absent' | 'recovered' | 'failed';
+
+export async function recoverAndroidBlockingSystemDialog(params: {
   session: SessionState;
   snapshotAndroidUi?: typeof snapshotAndroid;
   reopenAndroidApp?: typeof openAndroidApp;
   readAndroidAppState?: typeof getAndroidAppState;
   execCommand?: typeof runCmd;
-}): Promise<boolean> {
+}): Promise<AndroidBlockingDialogRecoveryResult> {
   const {
     session,
     snapshotAndroidUi = snapshotAndroid,
@@ -27,14 +29,14 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
   } = params;
 
   if (session.device.platform !== 'android' || !session.recording) {
-    return false;
+    return 'absent';
   }
 
   try {
     const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
     const closeAppButton = findCloseAppButton(nodes);
     if (!closeAppButton?.rect) {
-      return false;
+      return 'absent';
     }
 
     const { x, y } = centerOfRect(closeAppButton.rect);
@@ -61,7 +63,7 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
           stderr: tapResult.stderr.trim(),
         },
       });
-      return false;
+      return 'failed';
     }
 
     const dismissed = await waitForBlockingDialogToDismiss(session, snapshotAndroidUi);
@@ -74,7 +76,7 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
           deviceId: session.device.id,
         },
       });
-      return false;
+      return 'failed';
     }
 
     if (session.appBundleId) {
@@ -94,7 +96,7 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
             appBundleId: session.appBundleId,
           },
         });
-        return false;
+        return 'failed';
       }
     }
 
@@ -109,7 +111,7 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
         y,
       },
     });
-    return true;
+    return 'recovered';
   } catch (error) {
     emitDiagnostic({
       level: 'warn',
@@ -120,23 +122,8 @@ export async function maybeRecoverAndroidBlockingSystemDialog(params: {
         error: error instanceof Error ? error.message : String(error),
       },
     });
-    return false;
-  }
-}
-
-export async function hasAndroidBlockingSystemDialog(params: {
-  session: SessionState;
-  snapshotAndroidUi?: typeof snapshotAndroid;
-}): Promise<boolean> {
-  const { session, snapshotAndroidUi = snapshotAndroid } = params;
-  if (session.device.platform !== 'android') {
-    return false;
+    return 'failed';
   }
-  const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
-  return nodes.some((node) => {
-    const text = readNodeText(node);
-    return text.length > 0 && ANDROID_BLOCKING_MODAL_PATTERN.test(text);
-  });
 }
 
 async function readAndroidSnapshotNodes(
@@ -151,11 +138,7 @@ async function readAndroidSnapshotNodes(
 }
 
 function findCloseAppButton(nodes: SnapshotNode[]): SnapshotNode | undefined {
-  const hasBlockingDialog = nodes.some((node) => {
-    const text = readNodeText(node);
-    return text.length > 0 && ANDROID_BLOCKING_MODAL_PATTERN.test(text);
-  });
-  if (!hasBlockingDialog) {
+  if (!containsBlockingDialog(nodes)) {
     return undefined;
   }
   return nodes.find((node) => {
@@ -169,12 +152,14 @@ async function waitForBlockingDialogToDismiss(
   snapshotAndroidUi: typeof snapshotAndroid,
 ): Promise<boolean> {
   for (let attempt = 0; attempt < ANDROID_MODAL_POLL_ATTEMPTS; attempt += 1) {
-    if (!(await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }))) {
+    const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+    if (!containsBlockingDialog(nodes)) {
       return true;
     }
     await sleep(ANDROID_MODAL_POLL_MS);
   }
-  return !(await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }));
+  const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+  return !containsBlockingDialog(nodes);
 }
 
 async function waitForFocusedAndroidApp(
@@ -208,6 +193,13 @@ function readNodeText(node: {
     .trim();
 }
 
+function containsBlockingDialog(nodes: SnapshotNode[]): boolean {
+  return nodes.some((node) => {
+    const text = readNodeText(node);
+    return text.length > 0 && ANDROID_BLOCKING_MODAL_PATTERN.test(text);
+  });
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
diff --git a/src/daemon/handlers/__tests__/interaction.test.ts b/src/daemon/handlers/__tests__/interaction.test.ts
index de3ea2303..8d22e8f0a 100644
--- a/src/daemon/handlers/__tests__/interaction.test.ts
+++ b/src/daemon/handlers/__tests__/interaction.test.ts
@@ -173,9 +173,9 @@ test('press coordinates appends touch-visualization events while recording', asy
   assert.equal(recorded?.gestureEvents[0]?.referenceHeight, 874);
 });
 
-test('press coordinates dismisses blocking Android dialog during recording and relaunches app', async () => {
+test('press coordinates on Android recording uses physical screen size when no snapshot exists', async () => {
   const sessionStore = makeSessionStore();
-  const sessionName = 'default';
+  const sessionName = 'android-direct-press-frame';
   const session = makeAndroidSession(sessionName);
   session.recording = {
     platform: 'android',
@@ -186,69 +186,34 @@ test('press coordinates dismisses blocking Android dialog during recording and r
     showTouches: true,
     gestureEvents: [],
   };
+  session.snapshot = undefined;
   sessionStore.set(sessionName, session);
 
-  const dispatchCalls: string[][] = [];
-  const execCalls: string[][] = [];
-  const reopenedApps: string[] = [];
-  let snapshotCalls = 0;
-
   const response = await handleInteractionCommands({
     req: {
       token: 't',
       session: sessionName,
       command: 'press',
-      positionals: ['100', '200'],
+      positionals: ['300', '2300'],
       flags: {},
     },
     sessionName,
     sessionStore,
     contextFromFlags,
-    dispatch: async (_device, command, positionals) => {
-      dispatchCalls.push([command, ...positionals]);
-      return { ok: true };
-    },
-    snapshotAndroidUi: async () => {
-      snapshotCalls += 1;
-      if (snapshotCalls === 1) {
-        return {
-          nodes: [
-            {
-              index: 0,
-              type: 'android.widget.TextView',
-              label: "System UI isn't responding",
-              rect: { x: 40, y: 500, width: 500, height: 80 },
-            },
-            {
-              index: 1,
-              type: 'android.widget.Button',
-              label: 'Close app',
-              rect: { x: 60, y: 700, width: 220, height: 80 },
-            },
-          ],
-        };
-      }
-      return { nodes: [] };
-    },
-    reopenAndroidApp: async (_device, app) => {
-      reopenedApps.push(app);
-    },
-    readAndroidAppState: async () => ({ package: 'com.android.settings' }),
-    execCommand: async (_cmd, args) => {
-      execCalls.push(args);
-      return { stdout: '', stderr: '', exitCode: 0 };
-    },
+    dispatch: async () => ({ x: 300, y: 2300 }),
+    readAndroidScreenSize: async () => ({ width: 1344, height: 2992 }),
   });
 
   assert.equal(response?.ok, true);
-  assert.deepEqual(dispatchCalls, [['press', '100', '200']]);
-  assert.deepEqual(execCalls, [['-s', 'emulator-5554', 'shell', 'input', 'tap', '170', '740']]);
-  assert.deepEqual(reopenedApps, ['com.android.settings']);
+  const event = sessionStore.get(sessionName)?.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'tap');
+  assert.equal(event?.referenceWidth, 1344);
+  assert.equal(event?.referenceHeight, 2992);
 });
 
-test('press coordinates on Android recording uses physical screen size when no snapshot exists', async () => {
+test('press coordinates on Android recording caches physical screen size across interactions', async () => {
   const sessionStore = makeSessionStore();
-  const sessionName = 'android-direct-press-frame';
+  const sessionName = 'android-direct-press-frame-cache';
   const session = makeAndroidSession(sessionName);
   session.recording = {
     platform: 'android',
@@ -262,7 +227,13 @@ test('press coordinates on Android recording uses physical screen size when no s
   session.snapshot = undefined;
   sessionStore.set(sessionName, session);
 
-  const response = await handleInteractionCommands({
+  let screenSizeReads = 0;
+  const readAndroidScreenSize = async () => {
+    screenSizeReads += 1;
+    return { width: 1344, height: 2992 };
+  };
+
+  await handleInteractionCommands({
     req: {
       token: 't',
       session: sessionName,
@@ -274,14 +245,30 @@ test('press coordinates on Android recording uses physical screen size when no s
     sessionStore,
     contextFromFlags,
     dispatch: async () => ({ x: 300, y: 2300 }),
-    readAndroidScreenSize: async () => ({ width: 1344, height: 2992 }),
+    readAndroidScreenSize,
   });
 
-  assert.equal(response?.ok, true);
-  const event = sessionStore.get(sessionName)?.recording?.gestureEvents[0];
-  assert.equal(event?.kind, 'tap');
-  assert.equal(event?.referenceWidth, 1344);
-  assert.equal(event?.referenceHeight, 2992);
+  await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['320', '2200'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch: async () => ({ x: 320, y: 2200 }),
+    readAndroidScreenSize,
+  });
+
+  assert.equal(screenSizeReads, 1);
+  const recording = sessionStore.get(sessionName)?.recording;
+  assert.deepEqual(recording?.touchReferenceFrame, {
+    referenceWidth: 1344,
+    referenceHeight: 2992,
+  });
 });
 
 test('press @ref preserves native timing in recorded result and touch visualization', async () => {
diff --git a/src/daemon/recording-gestures.ts b/src/daemon/recording-gestures.ts
index aea881c14..f60a43318 100644
--- a/src/daemon/recording-gestures.ts
+++ b/src/daemon/recording-gestures.ts
@@ -1,7 +1,11 @@
 import type { RecordingGestureEvent, SessionState } from './types.ts';
-import type { Rect, SnapshotNode, SnapshotState } from '../utils/snapshot.ts';
+import type { SnapshotState } from '../utils/snapshot.ts';
 import { resolveGestureDurationMs, resolveGestureOffsetMs } from './recording-timing.ts';
 import { emitDiagnostic } from '../utils/diagnostics.ts';
+import {
+  getSnapshotReferenceFrame,
+  type TouchReferenceFrame as ReferenceFrame,
+} from './touch-reference-frame.ts';
 
 const DEFAULT_TAP_GAP_MS = 90;
 const DEFAULT_SWIPE_DURATION_MS = 250;
@@ -101,16 +105,6 @@ export function augmentTouchVisualizationResult(
   };
 }
 
-type ReferenceFrame = {
-  referenceWidth: number;
-  referenceHeight: number;
-};
-
-type SnapshotReferenceFrameState = SnapshotState & {
-  referenceWidth?: number;
-  referenceHeight?: number;
-};
-
 function buildGestureEvents(
   command: string,
   positionals: string[],
@@ -375,34 +369,8 @@ function resolveBackSwipeEdge(
   return endX >= startX ? 'left' : 'right';
 }
 
-function inferReferenceFrame(nodes: SnapshotNode[]): ReferenceFrame | undefined {
-  const viewportRect = inferViewportRect(nodes);
-  if (!viewportRect) return undefined;
-  return {
-    referenceWidth: viewportRect.width,
-    referenceHeight: viewportRect.height,
-  };
-}
-
 function getReferenceFrame(snapshot: SnapshotState | undefined): ReferenceFrame | undefined {
-  if (!snapshot) return undefined;
-  const cachedSnapshot = snapshot as SnapshotReferenceFrameState;
-  if (
-    typeof cachedSnapshot.referenceWidth === 'number' &&
-    cachedSnapshot.referenceWidth > 0 &&
-    typeof cachedSnapshot.referenceHeight === 'number' &&
-    cachedSnapshot.referenceHeight > 0
-  ) {
-    return {
-      referenceWidth: cachedSnapshot.referenceWidth,
-      referenceHeight: cachedSnapshot.referenceHeight,
-    };
-  }
-  const inferred = inferReferenceFrame(snapshot.nodes ?? []);
-  if (!inferred) return undefined;
-  cachedSnapshot.referenceWidth = inferred.referenceWidth;
-  cachedSnapshot.referenceHeight = inferred.referenceHeight;
-  return inferred;
+  return getSnapshotReferenceFrame(snapshot);
 }
 
 function resolveEventReferenceFrame(
@@ -492,35 +460,6 @@ function scrollEndPoint(
   }
 }
 
-function inferViewportRect(nodes: SnapshotNode[]): Rect | undefined {
-  const candidate = nodes
-    .filter((node) => isViewportNode(node.type) && isValidRect(node.rect))
-    .map((node) => node.rect)
-    .sort(
-      (left, right) =>
-        (right?.width ?? 0) * (right?.height ?? 0) - (left?.width ?? 0) * (left?.height ?? 0),
-    )[0];
-  if (candidate) return candidate;
-
-  const rects = nodes.map((node) => node.rect).filter(isValidRect);
-  if (rects.length === 0) return undefined;
-
-  const width = Math.max(...rects.map((rect) => rect.x + rect.width));
-  const height = Math.max(...rects.map((rect) => rect.y + rect.height));
-  if (width <= 0 || height <= 0) return undefined;
-  return { x: 0, y: 0, width, height };
-}
-
-function isViewportNode(type: string | undefined): boolean {
-  if (!type) return false;
-  const normalized = type.toLowerCase();
-  return normalized.includes('application') || normalized.includes('window');
-}
-
-function isValidRect(rect: Rect | undefined): rect is Rect {
-  return !!rect && rect.width > 0 && rect.height > 0;
-}
-
 function readNumber(value: unknown): number | undefined {
   if (typeof value === 'number' && Number.isFinite(value)) return value;
   if (typeof value !== 'string' || value.trim().length === 0) return undefined;
diff --git a/src/daemon/request-router.ts b/src/daemon/request-router.ts
index 665a427c6..42735cf91 100644
--- a/src/daemon/request-router.ts
+++ b/src/daemon/request-router.ts
@@ -37,10 +37,7 @@ import {
   augmentTouchVisualizationResult,
   recordTouchVisualizationEvent,
 } from './recording-gestures.ts';
-import {
-  hasAndroidBlockingSystemDialog,
-  maybeRecoverAndroidBlockingSystemDialog,
-} from './android-system-dialog.ts';
+import { recoverAndroidBlockingSystemDialog } from './android-system-dialog.ts';
 import { snapshotAndroid, openAndroidApp, getAndroidAppState } from '../platforms/android/index.ts';
 import { getRunnerSessionSnapshot } from '../platforms/ios/runner-client.ts';
 import { runCmd } from '../utils/exec.ts';
@@ -384,10 +381,6 @@ export function createRequestHandler(
             sessionStore,
             contextFromFlags: (flags, appBundleId, traceLogPath) =>
               contextFromFlags(logPath, flags, appBundleId, traceLogPath),
-            snapshotAndroidUi,
-            reopenAndroidApp,
-            readAndroidAppState,
-            execCommand,
           });
           if (interactionResponse) return finalize(interactionResponse);
 
@@ -410,13 +403,22 @@ export function createRequestHandler(
           }
 
           if (session.device.platform === 'android' && session.recording && command !== 'record') {
-            await maybeRecoverAndroidBlockingSystemDialog({
+            const androidRecoveryResult = await recoverAndroidBlockingSystemDialog({
               session,
               snapshotAndroidUi,
               reopenAndroidApp,
               readAndroidAppState,
               execCommand,
             });
+            if (androidRecoveryResult === 'failed') {
+              return finalize({
+                ok: false,
+                error: {
+                  code: 'COMMAND_FAILED',
+                  message: 'Android system dialog blocked the recording session',
+                },
+              });
+            }
           }
 
           const positionals = lockedReq.positionals ?? [];
@@ -450,27 +452,6 @@ export function createRequestHandler(
             ...dispatchContext,
           });
           const actionFinishedAt = Date.now();
-          await maybeRecoverAndroidBlockingSystemDialog({
-            session,
-            snapshotAndroidUi,
-            reopenAndroidApp,
-            readAndroidAppState,
-            execCommand,
-          });
-          if (
-            command !== 'record' &&
-            session.device.platform === 'android' &&
-            session.recording &&
-            (await hasAndroidBlockingSystemDialog({ session, snapshotAndroidUi }))
-          ) {
-            return finalize({
-              ok: false,
-              error: {
-                code: 'COMMAND_FAILED',
-                message: 'Android system dialog blocked the recording session',
-              },
-            });
-          }
           const visualizationData = augmentTouchVisualizationResult(
             session,
             command,
diff --git a/src/daemon/touch-reference-frame.ts b/src/daemon/touch-reference-frame.ts
new file mode 100644
index 000000000..157ced16a
--- /dev/null
+++ b/src/daemon/touch-reference-frame.ts
@@ -0,0 +1,75 @@
+import type { Rect, SnapshotNode, SnapshotState } from '../utils/snapshot.ts';
+
+export type TouchReferenceFrame = {
+  referenceWidth: number;
+  referenceHeight: number;
+};
+
+type SnapshotReferenceFrameState = SnapshotState & {
+  referenceWidth?: number;
+  referenceHeight?: number;
+};
+
+export function getSnapshotReferenceFrame(
+  snapshot: SnapshotState | undefined,
+): TouchReferenceFrame | undefined {
+  if (!snapshot) return undefined;
+  const cachedSnapshot = snapshot as SnapshotReferenceFrameState;
+  if (
+    typeof cachedSnapshot.referenceWidth === 'number' &&
+    cachedSnapshot.referenceWidth > 0 &&
+    typeof cachedSnapshot.referenceHeight === 'number' &&
+    cachedSnapshot.referenceHeight > 0
+  ) {
+    return {
+      referenceWidth: cachedSnapshot.referenceWidth,
+      referenceHeight: cachedSnapshot.referenceHeight,
+    };
+  }
+
+  const inferred = inferTouchReferenceFrame(snapshot.nodes ?? []);
+  if (!inferred) return undefined;
+  cachedSnapshot.referenceWidth = inferred.referenceWidth;
+  cachedSnapshot.referenceHeight = inferred.referenceHeight;
+  return inferred;
+}
+
+export function inferTouchReferenceFrame(
+  nodes: Array<Pick<SnapshotNode, 'type' | 'rect'>>,
+): TouchReferenceFrame | undefined {
+  const viewportRect = inferViewportRect(nodes);
+  if (!viewportRect) return undefined;
+  return {
+    referenceWidth: viewportRect.width,
+    referenceHeight: viewportRect.height,
+  };
+}
+
+function inferViewportRect(nodes: Array<Pick<SnapshotNode, 'type' | 'rect'>>): Rect | undefined {
+  const candidate = nodes
+    .filter((node) => isViewportNode(node.type) && isValidRect(node.rect))
+    .map((node) => node.rect)
+    .sort(
+      (left, right) =>
+        (right?.width ?? 0) * (right?.height ?? 0) - (left?.width ?? 0) * (left?.height ?? 0),
+    )[0];
+  if (candidate) return candidate;
+
+  const rects = nodes.map((node) => node.rect).filter(isValidRect);
+  if (rects.length === 0) return undefined;
+
+  const width = Math.max(...rects.map((rect) => rect.x + rect.width));
+  const height = Math.max(...rects.map((rect) => rect.y + rect.height));
+  if (width <= 0 || height <= 0) return undefined;
+  return { x: 0, y: 0, width, height };
+}
+
+function isViewportNode(type: string | undefined): boolean {
+  if (!type) return false;
+  const normalized = type.toLowerCase();
+  return normalized.includes('application') || normalized.includes('window');
+}
+
+function isValidRect(rect: Rect | undefined): rect is Rect {
+  return !!rect && rect.width > 0 && rect.height > 0;
+}
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index d6295e756..9e16c07d0 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -113,6 +113,10 @@ type SessionRecordingBase = {
   startedAt: number;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
+  touchReferenceFrame?: {
+    referenceWidth: number;
+    referenceHeight: number;
+  };
   runnerSessionId?: string;
   invalidatedReason?: string;
 };

From 94f1773c463cc48e4319832c63f20a23b3d8989b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 23 Mar 2026 13:50:06 +0100
Subject: [PATCH 08/11] feat: add gesture telemetry recording overlays

---
 .../RunnerTests+CommandExecution.swift        | 166 +++++++----
 .../RunnerTests+Interaction.swift             |  13 +
 .../RunnerTests+Models.swift                  |  12 +-
 .../RecordingScripts/recording-inspect.swift  | 255 ++++++++++++++++
 .../RecordingScripts/recording-overlay.swift  |  38 ++-
 .../RecordingScripts/recording-trim.swift     |   5 +-
 .../references/video-recording.md             |  10 +-
 src/core/dispatch.ts                          |   4 +-
 .../__tests__/recording-gestures.test.ts      |  44 ++-
 src/daemon/__tests__/recording-timing.test.ts |  52 ++++
 .../handlers/__tests__/interaction.test.ts    |   2 +-
 .../handlers/__tests__/record-trace.test.ts   | 137 +++++++++
 src/daemon/handlers/record-trace-android.ts   | 121 ++++----
 src/daemon/handlers/record-trace-ios.ts       |  37 ++-
 src/daemon/handlers/record-trace-recording.ts |  93 ++++--
 src/daemon/recording-gestures.ts              | 232 +++++++++------
 src/daemon/recording-timing.ts                |  36 +++
 src/daemon/request-router.ts                  |   4 +-
 src/daemon/touch-reference-frame.ts           |  22 +-
 src/daemon/types.ts                           |   3 +
 .../ios/__tests__/recording-scripts.test.ts   |  52 ++++
 src/platforms/ios/recording-overlay.ts        |   9 +
 src/platforms/ios/runner-client.ts            |   1 +
 src/platforms/ios/runner-errors.ts            |   3 +-
 src/utils/interactors.ts                      |   6 +-
 src/utils/video.ts                            |   2 +
 test/integration/recording-overlay.test.ts    | 272 ++++++++++++++++++
 test/integration/test-helpers.ts              | 111 ++++++-
 website/docs/docs/commands.md                 |   4 +
 29 files changed, 1445 insertions(+), 301 deletions(-)
 create mode 100644 ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift
 create mode 100644 src/daemon/__tests__/recording-timing.test.ts
 create mode 100644 src/platforms/ios/__tests__/recording-scripts.test.ts
 create mode 100644 test/integration/recording-overlay.test.ts

diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index bcc3e959a..421be390f 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -3,6 +3,16 @@ import XCTest
 extension RunnerTests {
   // MARK: - Main Thread Dispatch
 
+  private func currentUptimeMs() -> Double {
+    ProcessInfo.processInfo.systemUptime * 1000
+  }
+
+  private func measureGesture(_ action: () -> Void) -> (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double) {
+    let gestureStartUptimeMs = currentUptimeMs()
+    action()
+    return (gestureStartUptimeMs, currentUptimeMs())
+  }
+
   func execute(command: Command) throws -> Response {
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
@@ -204,25 +214,43 @@ extension RunnerTests {
         activeRecording = nil
         return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
       }
+    case .uptime:
+      return Response(
+        ok: true,
+        data: DataPayload(currentUptimeMs: currentUptimeMs())
+      )
     case .tap:
       if let text = command.text {
         if let element = findElement(app: activeApp, text: text) {
-          withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-            element.tap()
+          let timing = measureGesture {
+            withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+              element.tap()
+            }
           }
-          return Response(ok: true, data: DataPayload(message: "tapped"))
+          return Response(
+            ok: true,
+            data: DataPayload(
+              message: "tapped",
+              gestureStartUptimeMs: timing.gestureStartUptimeMs,
+              gestureEndUptimeMs: timing.gestureEndUptimeMs
+            )
+          )
         }
         return Response(ok: false, error: ErrorPayload(message: "element not found"))
       }
       if let x = command.x, let y = command.y {
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
-        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-          tapAt(app: activeApp, x: x, y: y)
+        let timing = measureGesture {
+          withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+            tapAt(app: activeApp, x: x, y: y)
+          }
         }
         return Response(
           ok: true,
           data: DataPayload(
             message: "tapped",
+            gestureStartUptimeMs: timing.gestureStartUptimeMs,
+            gestureEndUptimeMs: timing.gestureEndUptimeMs,
             x: touchFrame.x,
             y: touchFrame.y,
             referenceWidth: touchFrame.referenceWidth,
@@ -231,16 +259,6 @@ extension RunnerTests {
         )
       }
       return Response(ok: false, error: ErrorPayload(message: "tap requires text 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"))
-      }
-      do {
-        try mouseClickAt(app: activeApp, x: x, y: y, button: command.button ?? "primary")
-        return Response(ok: true, data: DataPayload(message: "clicked"))
-      } catch {
-        return Response(ok: false, error: ErrorPayload(message: error.localizedDescription))
-      }
     case .tapSeries:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "tapSeries requires x and y"))
@@ -250,15 +268,19 @@ extension RunnerTests {
       let doubleTap = command.doubleTap ?? false
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
       if doubleTap {
-        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-          runSeries(count: count, pauseMs: intervalMs) { _ in
-            doubleTapAt(app: activeApp, x: x, y: y)
+        let timing = measureGesture {
+          withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+            runSeries(count: count, pauseMs: intervalMs) { _ in
+              doubleTapAt(app: activeApp, x: x, y: y)
+            }
           }
         }
         return Response(
           ok: true,
           data: DataPayload(
             message: "tap series",
+            gestureStartUptimeMs: timing.gestureStartUptimeMs,
+            gestureEndUptimeMs: timing.gestureEndUptimeMs,
             x: touchFrame.x,
             y: touchFrame.y,
             referenceWidth: touchFrame.referenceWidth,
@@ -266,15 +288,19 @@ extension RunnerTests {
           )
         )
       }
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        runSeries(count: count, pauseMs: intervalMs) { _ in
-          tapAt(app: activeApp, x: x, y: y)
+      let timing = measureGesture {
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          runSeries(count: count, pauseMs: intervalMs) { _ in
+            tapAt(app: activeApp, x: x, y: y)
+          }
         }
       }
       return Response(
         ok: true,
         data: DataPayload(
           message: "tap series",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
           x: touchFrame.x,
           y: touchFrame.y,
           referenceWidth: touchFrame.referenceWidth,
@@ -287,13 +313,17 @@ extension RunnerTests {
       }
       let duration = (command.durationMs ?? 800) / 1000.0
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        longPressAt(app: activeApp, x: x, y: y, duration: duration)
+      let timing = measureGesture {
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          longPressAt(app: activeApp, x: x, y: y, duration: duration)
+        }
       }
       return Response(
         ok: true,
         data: DataPayload(
           message: "long pressed",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
           x: touchFrame.x,
           y: touchFrame.y,
           referenceWidth: touchFrame.referenceWidth,
@@ -306,13 +336,17 @@ extension RunnerTests {
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
       let dragFrame = resolvedDragVisualizationFrame(app: activeApp, x: x, y: y, x2: x2, y2: y2)
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      let timing = measureGesture {
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+        }
       }
       return Response(
         ok: true,
         data: DataPayload(
           message: "dragged",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
           x: dragFrame.x,
           y: dragFrame.y,
           x2: dragFrame.x2,
@@ -332,17 +366,26 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "dragSeries pattern must be one-way or ping-pong"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        runSeries(count: count, pauseMs: pauseMs) { idx in
-          let reverse = pattern == "ping-pong" && (idx % 2 == 1)
-          if reverse {
-            dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
-          } else {
-            dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      let timing = measureGesture {
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          runSeries(count: count, pauseMs: pauseMs) { idx in
+            let reverse = pattern == "ping-pong" && (idx % 2 == 1)
+            if reverse {
+              dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
+            } else {
+              dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+            }
           }
         }
       }
-      return Response(ok: true, data: DataPayload(message: "drag series"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "drag series",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs
+        )
+      )
     case .type:
       guard let text = command.text else {
         return Response(ok: false, error: ErrorPayload(message: "type requires text"))
@@ -365,10 +408,22 @@ extension RunnerTests {
       guard let direction = command.direction else {
         return Response(ok: false, error: ErrorPayload(message: "swipe requires direction"))
       }
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        swipe(app: activeApp, direction: direction)
+      let referenceFrame = resolvedGestureReferenceFrame(app: activeApp)
+      let timing = measureGesture {
+        withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+          swipe(app: activeApp, direction: direction)
+        }
       }
-      return Response(ok: true, data: DataPayload(message: "swiped"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "swiped",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
+          referenceWidth: referenceFrame.referenceWidth,
+          referenceHeight: referenceFrame.referenceHeight
+        )
+      )
     case .findText:
       guard let text = command.text else {
         return Response(ok: false, error: ErrorPayload(message: "findText requires text"))
@@ -399,7 +454,7 @@ extension RunnerTests {
         Thread.sleep(forTimeInterval: 0.5)
       }
       let screenshot = XCUIScreen.main.screenshot()
-      guard let pngData = runnerPngData(for: screenshot.image) else {
+      guard let pngData = screenshot.image.pngData() else {
         return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
       }
       let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
@@ -409,40 +464,21 @@ extension RunnerTests {
       } catch {
         return Response(ok: false, error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)"))
       }
-#if os(macOS)
-      return Response(ok: true, data: DataPayload(message: filePath))
-#else
       // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
       return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
-#endif
     case .back:
       if tapNavigationBack(app: activeApp) {
         return Response(ok: true, data: DataPayload(message: "back"))
       }
-#if os(macOS)
-      return Response(ok: false, error: ErrorPayload(message: "back button is not available on macOS"))
-#else
       performBackGesture(app: activeApp)
       return Response(ok: true, data: DataPayload(message: "back"))
-#endif
     case .home:
-#if os(macOS)
-      return Response(ok: false, error: ErrorPayload(message: "home is not supported on macOS"))
-#else
       pressHomeButton()
       return Response(ok: true, data: DataPayload(message: "home"))
-#endif
     case .appSwitcher:
-#if os(macOS)
-      return Response(ok: false, error: ErrorPayload(message: "appSwitcher is not supported on macOS"))
-#else
       performAppSwitcherGesture(app: activeApp)
       return Response(ok: true, data: DataPayload(message: "appSwitcher"))
-#endif
     case .alert:
-#if os(macOS)
-      return Response(ok: false, error: ErrorPayload(message: "alert is not supported on macOS"))
-#else
       let action = (command.action ?? "get").lowercased()
       let alert = activeApp.alerts.firstMatch
       if !alert.exists {
@@ -460,17 +496,21 @@ extension RunnerTests {
       }
       let buttonLabels = alert.buttons.allElementsBoundByIndex.map { $0.label }
       return Response(ok: true, data: DataPayload(message: alert.label, items: buttonLabels))
-#endif
     case .pinch:
-#if os(macOS)
-      return Response(ok: false, error: ErrorPayload(message: "pinch is not supported on macOS"))
-#else
       guard let scale = command.scale, scale > 0 else {
         return Response(ok: false, error: ErrorPayload(message: "pinch requires scale > 0"))
       }
-      pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
-      return Response(ok: true, data: DataPayload(message: "pinched"))
-#endif
+      let timing = measureGesture {
+        pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
+      }
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "pinched",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs
+        )
+      )
     }
   }
 }
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index 7f13ac522..5563f5ae7 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -17,6 +17,11 @@ extension RunnerTests {
     let referenceHeight: Double
   }
 
+  struct GestureReferenceFrame {
+    let referenceWidth: Double
+    let referenceHeight: Double
+  }
+
   // MARK: - Navigation Gestures
 
   func tapNavigationBack(app: XCUIApplication) -> Bool {
@@ -269,6 +274,14 @@ extension RunnerTests {
     return CGRect(x: 0, y: 0, width: 0, height: 0)
   }
 
+  func resolvedGestureReferenceFrame(app: XCUIApplication) -> GestureReferenceFrame {
+    let frame = resolvedTouchReferenceFrame(app: app, appFrame: app.frame)
+    return GestureReferenceFrame(
+      referenceWidth: frame.width,
+      referenceHeight: frame.height
+    )
+  }
+
   func runSeries(count: Int, pauseMs: Double, operation: (Int) -> Void) {
     let total = max(count, 1)
     let pause = max(pauseMs, 0)
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 5c06cde06..036812e31 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -19,6 +19,7 @@ enum CommandType: String, Codable {
   case pinch
   case recordStart
   case recordStop
+  case uptime
   case shutdown
 }
 
@@ -75,12 +76,15 @@ struct DataPayload: Codable {
   let items: [String]?
   let nodes: [SnapshotNode]?
   let truncated: Bool?
+  let gestureStartUptimeMs: Double?
+  let gestureEndUptimeMs: Double?
   let x: Double?
   let y: Double?
   let x2: Double?
   let y2: Double?
   let referenceWidth: Double?
   let referenceHeight: Double?
+  let currentUptimeMs: Double?
 
   init(
     message: String? = nil,
@@ -88,24 +92,30 @@ struct DataPayload: Codable {
     items: [String]? = nil,
     nodes: [SnapshotNode]? = nil,
     truncated: Bool? = nil,
+    gestureStartUptimeMs: Double? = nil,
+    gestureEndUptimeMs: Double? = nil,
     x: Double? = nil,
     y: Double? = nil,
     x2: Double? = nil,
     y2: Double? = nil,
     referenceWidth: Double? = nil,
-    referenceHeight: Double? = nil
+    referenceHeight: Double? = nil,
+    currentUptimeMs: Double? = nil
   ) {
     self.message = message
     self.found = found
     self.items = items
     self.nodes = nodes
     self.truncated = truncated
+    self.gestureStartUptimeMs = gestureStartUptimeMs
+    self.gestureEndUptimeMs = gestureEndUptimeMs
     self.x = x
     self.y = y
     self.x2 = x2
     self.y2 = y2
     self.referenceWidth = referenceWidth
     self.referenceHeight = referenceHeight
+    self.currentUptimeMs = currentUptimeMs
   }
 }
 
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift
new file mode 100644
index 000000000..58658cec2
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift
@@ -0,0 +1,255 @@
+import AppKit
+import AVFoundation
+import Foundation
+
+struct GestureEnvelope: Decodable {
+  let events: [GestureEvent]
+}
+
+struct GestureEvent: Decodable {
+  let kind: String
+  let tMs: Double
+  let x: Double
+  let y: Double
+  let x2: Double?
+  let y2: Double?
+  let referenceWidth: Double?
+  let referenceHeight: Double?
+  let durationMs: Double?
+  let scale: Double?
+}
+
+struct InspectionManifest: Encodable {
+  struct Item: Encodable {
+    let index: Int
+    let kind: String
+    let sourceTimeMs: Double
+    let sampleTimeMs: Double
+    let expectedX: Double
+    let expectedY: Double
+    let fullFramePath: String
+    let cropPath: String
+  }
+
+  let generatedAt: String
+  let inputPath: String
+  let items: [Item]
+}
+
+enum InspectError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case missingVideoTrack
+  case frameExtractionFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .frameExtractionFailed(let message):
+      return message
+    }
+  }
+}
+
+do {
+  try run()
+} catch {
+  fputs("recording-inspect: \(error)\n", stderr)
+  exit(1)
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let parsed = try parseArguments(arguments)
+  let inputURL = URL(fileURLWithPath: parsed.inputPath)
+  let eventsURL = URL(fileURLWithPath: parsed.eventsPath)
+  let outputDirURL = URL(fileURLWithPath: parsed.outputDir, isDirectory: true)
+
+  try FileManager.default.createDirectory(at: outputDirURL, withIntermediateDirectories: true)
+
+  let envelope = try JSONDecoder().decode(GestureEnvelope.self, from: Data(contentsOf: eventsURL))
+  let asset = AVURLAsset(url: inputURL)
+  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
+    throw InspectError.missingVideoTrack
+  }
+
+  let renderSize = resolvedRenderSize(for: sourceVideoTrack)
+  let durationMs = max(0, asset.duration.seconds * 1000.0)
+  let generator = AVAssetImageGenerator(asset: asset)
+  generator.appliesPreferredTrackTransform = true
+  generator.requestedTimeToleranceBefore = .zero
+  generator.requestedTimeToleranceAfter = .zero
+
+  var manifestItems: [InspectionManifest.Item] = []
+  for (index, event) in envelope.events.enumerated() {
+    let sampleTimeMs = clampedSampleTimeMs(
+      recommendedSampleTimeMs(for: event),
+      durationMs: durationMs
+    )
+    let sampleTime = CMTime(seconds: sampleTimeMs / 1000.0, preferredTimescale: 600)
+    let cgImage: CGImage
+    do {
+      cgImage = try generator.copyCGImage(at: sampleTime, actualTime: nil)
+    } catch {
+      throw InspectError.frameExtractionFailed(
+        "Failed to extract frame for event \(index + 1) at \(sampleTimeMs)ms: \(error)"
+      )
+    }
+
+    let expectedPoint = overlayPoint(
+      event: event,
+      renderSize: renderSize,
+      sampleTimeMs: sampleTimeMs
+    )
+    let fullFrameURL = outputDirURL.appendingPathComponent(
+      fileName(prefix: index + 1, kind: event.kind, suffix: "frame")
+    )
+    let cropURL = outputDirURL.appendingPathComponent(
+      fileName(prefix: index + 1, kind: event.kind, suffix: "crop")
+    )
+
+    try writePNG(cgImage: cgImage, to: fullFrameURL)
+    let cropped = cropImage(cgImage, centeredAt: expectedPoint, size: CGSize(width: 280, height: 280))
+    try writePNG(cgImage: cropped, to: cropURL)
+
+    manifestItems.append(
+      .init(
+        index: index + 1,
+        kind: event.kind,
+        sourceTimeMs: event.tMs,
+        sampleTimeMs: sampleTimeMs,
+        expectedX: expectedPoint.x,
+        expectedY: expectedPoint.y,
+        fullFramePath: fullFrameURL.path,
+        cropPath: cropURL.path
+      )
+    )
+  }
+
+  let manifest = InspectionManifest(
+    generatedAt: ISO8601DateFormatter().string(from: Date()),
+    inputPath: inputURL.path,
+    items: manifestItems
+  )
+  let manifestURL = outputDirURL.appendingPathComponent("manifest.json")
+  let encoder = JSONEncoder()
+  encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+  try encoder.encode(manifest).write(to: manifestURL)
+  print(manifestURL.path)
+}
+
+func clampedSampleTimeMs(_ sampleTimeMs: Double, durationMs: Double) -> Double {
+  guard durationMs > 0 else { return max(0, sampleTimeMs) }
+  return min(max(0, sampleTimeMs), max(0, durationMs - 50))
+}
+
+func parseArguments(_ arguments: [String]) throws -> (inputPath: String, eventsPath: String, outputDir: String) {
+  var inputPath: String?
+  var eventsPath: String?
+  var outputDir: String?
+  var index = 0
+
+  while index < arguments.count {
+    let argument = arguments[index]
+    let nextIndex = index + 1
+    switch argument {
+    case "--input":
+      guard nextIndex < arguments.count else { throw InspectError.invalidArgs("--input requires a value") }
+      inputPath = arguments[nextIndex]
+      index += 2
+    case "--events":
+      guard nextIndex < arguments.count else { throw InspectError.invalidArgs("--events requires a value") }
+      eventsPath = arguments[nextIndex]
+      index += 2
+    case "--output-dir":
+      guard nextIndex < arguments.count else { throw InspectError.invalidArgs("--output-dir requires a value") }
+      outputDir = arguments[nextIndex]
+      index += 2
+    default:
+      throw InspectError.invalidArgs("Unknown argument: \(argument)")
+    }
+  }
+
+  guard let inputPath, let eventsPath, let outputDir else {
+    throw InspectError.invalidArgs(
+      "Usage: recording-inspect.swift --input <video> --events <json> --output-dir <dir>"
+    )
+  }
+  return (inputPath, eventsPath, outputDir)
+}
+
+func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
+  let transformed = track.naturalSize.applying(track.preferredTransform)
+  return CGSize(width: abs(transformed.width), height: abs(transformed.height))
+}
+
+func recommendedSampleTimeMs(for event: GestureEvent) -> Double {
+  switch event.kind {
+  case "tap":
+    return event.tMs + 180
+  case "longpress":
+    let duration = max(event.durationMs ?? 800, 350)
+    return event.tMs + min(duration * 0.35, 280)
+  case "swipe", "scroll", "back-swipe", "pinch":
+    let duration = max(event.durationMs ?? 250, 180)
+    return event.tMs + min(max(duration * 0.5, 120), 320)
+  default:
+    return event.tMs + 180
+  }
+}
+
+func overlayPoint(event: GestureEvent, renderSize: CGSize, sampleTimeMs: Double) -> CGPoint {
+  let sampleX: Double
+  let sampleY: Double
+  if let x2 = event.x2, let y2 = event.y2, let durationMs = event.durationMs, durationMs > 0 {
+    let elapsedMs = max(0, min(sampleTimeMs - event.tMs, durationMs))
+    let progress = min(1.0, elapsedMs / durationMs)
+    let easedProgress = progress * progress * (3 - 2 * progress)
+    let inspectedProgress =
+      event.kind == "back-swipe" ? min(easedProgress, 0.25) : easedProgress
+    sampleX = event.x + (x2 - event.x) * inspectedProgress
+    sampleY = event.y + (y2 - event.y) * inspectedProgress
+  } else {
+    sampleX = event.x
+    sampleY = event.y
+  }
+  let scaleX = scaledAxis(renderSize: renderSize.width, referenceSize: event.referenceWidth)
+  let scaleY = scaledAxis(renderSize: renderSize.height, referenceSize: event.referenceHeight)
+  let scaledX = sampleX * scaleX
+  let scaledY = sampleY * scaleY
+  return CGPoint(x: scaledX, y: scaledY)
+}
+
+func scaledAxis(renderSize: CGFloat, referenceSize: Double?) -> Double {
+  guard let referenceSize, referenceSize > 0 else { return 1.0 }
+  return Double(renderSize) / referenceSize
+}
+
+func fileName(prefix: Int, kind: String, suffix: String) -> String {
+  String(format: "%02d-%@-%@.png", prefix, sanitize(kind), suffix)
+}
+
+func sanitize(_ value: String) -> String {
+  value.replacingOccurrences(of: "[^A-Za-z0-9_-]", with: "-", options: .regularExpression)
+}
+
+func writePNG(cgImage: CGImage, to url: URL) throws {
+  let rep = NSBitmapImageRep(cgImage: cgImage)
+  guard let data = rep.representation(using: .png, properties: [:]) else {
+    throw InspectError.frameExtractionFailed("Failed to encode PNG for \(url.lastPathComponent)")
+  }
+  try data.write(to: url)
+}
+
+func cropImage(_ image: CGImage, centeredAt point: CGPoint, size: CGSize) -> CGImage {
+  let width = CGFloat(image.width)
+  let height = CGFloat(image.height)
+  let cropWidth = min(size.width, width)
+  let cropHeight = min(size.height, height)
+  let originX = min(max(0, point.x - cropWidth / 2), max(0, width - cropWidth))
+  let originY = min(max(0, point.y - cropHeight / 2), max(0, height - cropHeight))
+  let rect = CGRect(x: originX, y: originY, width: cropWidth, height: cropHeight).integral
+  return image.cropping(to: rect) ?? image
+}
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
index 698ecd07f..e7c087417 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -3,7 +3,6 @@ import AVFoundation
 import Foundation
 import QuartzCore
 
-let touchDotRadius: CGFloat = 30
 let touchDotColor = NSColor(calibratedRed: 0.20, green: 0.63, blue: 0.98, alpha: 0.48).cgColor
 let touchDotBorderColor = NSColor(calibratedRed: 0.94, green: 0.98, blue: 1.0, alpha: 0.68).cgColor
 let minimumTapVisibility: CFTimeInterval = 0.45
@@ -158,7 +157,10 @@ func run() throws {
   exporter.exportAsynchronously {
     semaphore.signal()
   }
-  _ = semaphore.wait(timeout: .now() + 120)
+  if semaphore.wait(timeout: .now() + 120) == .timedOut {
+    exporter.cancelExport()
+    throw OverlayError.exportFailed("Touch overlay export timed out.")
+  }
 
   if exporter.status != .completed {
     throw OverlayError.exportFailed(exporter.error?.localizedDescription ?? "Touch overlay export failed.")
@@ -223,7 +225,8 @@ func overlayPoint(event: GestureEvent, x: Double, y: Double, renderSize: CGSize)
   let scaleY = scaledAxis(renderSize: renderSize.height, referenceSize: event.referenceHeight)
   let scaledX = x * scaleX
   let scaledY = y * scaleY
-  return CGPoint(x: scaledX, y: renderSize.height - scaledY)
+  let flippedY = max(0, Double(renderSize.height) - scaledY)
+  return CGPoint(x: scaledX, y: flippedY)
 }
 
 func scaledAxis(renderSize: CGFloat, referenceSize: Double?) -> Double {
@@ -232,7 +235,10 @@ func scaledAxis(renderSize: CGFloat, referenceSize: Double?) -> Double {
 }
 
 func addTapLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
-  let layer = makeTouchDotLayer(center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize))
+  let layer = makeTouchDotLayer(
+    center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize),
+    renderSize: renderSize
+  )
   overlayLayer.addSublayer(layer)
 
   let opacity = CAKeyframeAnimation(keyPath: "opacity")
@@ -254,7 +260,10 @@ func addTapLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALay
 
 func addLongPressLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALayer) {
   let duration = max(0.75, (event.durationMs ?? 800) / 1000.0)
-  let layer = makeTouchDotLayer(center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize))
+  let layer = makeTouchDotLayer(
+    center: overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize),
+    renderSize: renderSize
+  )
   overlayLayer.addSublayer(layer)
 
   let opacity = CAKeyframeAnimation(keyPath: "opacity")
@@ -338,7 +347,7 @@ func addTrailLayers(
   strokeGroup.isRemovedOnCompletion = false
   pathLayer.add(strokeGroup, forKey: "stroke")
 
-  let dotLayer = makeTouchDotLayer(center: startPoint)
+  let dotLayer = makeTouchDotLayer(center: startPoint, renderSize: renderSize)
   dotLayer.backgroundColor = trailColor(style: style)
   dotLayer.borderColor = trailBorderColor(style: style)
   dotLayer.position = endPoint
@@ -377,10 +386,11 @@ func addPinchDot(
   overlayLayer: CALayer,
   start: CGPoint,
   end: CGPoint,
+  renderSize: CGSize,
   beginTime: CFTimeInterval,
   duration: CFTimeInterval
 ) {
-  let dotLayer = makeTouchDotLayer(center: start)
+  let dotLayer = makeTouchDotLayer(center: start, renderSize: renderSize)
   overlayLayer.addSublayer(dotLayer)
 
   let position = CABasicAnimation(keyPath: "position")
@@ -416,6 +426,7 @@ func addPinchLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CA
     overlayLayer: overlayLayer,
     start: startLeft,
     end: endLeft,
+    renderSize: renderSize,
     beginTime: beginTime,
     duration: duration
   )
@@ -423,16 +434,18 @@ func addPinchLayers(event: GestureEvent, renderSize: CGSize, to overlayLayer: CA
     overlayLayer: overlayLayer,
     start: startRight,
     end: endRight,
+    renderSize: renderSize,
     beginTime: beginTime,
     duration: duration
   )
 }
 
-func makeTouchDotLayer(center: CGPoint) -> CALayer {
+func makeTouchDotLayer(center: CGPoint, renderSize: CGSize) -> CALayer {
+  let dotRadius = resolvedTouchDotRadius(renderSize: renderSize)
   let layer = CALayer()
-  layer.bounds = CGRect(x: 0, y: 0, width: touchDotRadius * 2, height: touchDotRadius * 2)
+  layer.bounds = CGRect(x: 0, y: 0, width: dotRadius * 2, height: dotRadius * 2)
   layer.position = center
-  layer.cornerRadius = touchDotRadius
+  layer.cornerRadius = dotRadius
   layer.backgroundColor = touchDotColor
   layer.borderWidth = 2
   layer.borderColor = touchDotBorderColor
@@ -443,6 +456,11 @@ func makeTouchDotLayer(center: CGPoint) -> CALayer {
   return layer
 }
 
+func resolvedTouchDotRadius(renderSize: CGSize) -> CGFloat {
+  let minDimension = min(renderSize.width, renderSize.height)
+  return max(18, min(40, minDimension * 0.035))
+}
+
 func trailTail(style: TrailStyle) -> CFTimeInterval {
   switch style {
   case .swipe:
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
index 16c1ab45e..6c17823dd 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
@@ -89,7 +89,10 @@ func run() throws {
   exporter.exportAsynchronously {
     semaphore.signal()
   }
-  _ = semaphore.wait(timeout: .now() + 120)
+  if semaphore.wait(timeout: .now() + 120) == .timedOut {
+    exporter.cancelExport()
+    throw TrimError.exportFailed("Trim export timed out.")
+  }
 
   if exporter.status != .completed {
     throw TrimError.exportFailed(exporter.error?.localizedDescription ?? "Trim export failed.")
diff --git a/skills/agent-device/references/video-recording.md b/skills/agent-device/references/video-recording.md
index a590ad056..62db920a1 100644
--- a/skills/agent-device/references/video-recording.md
+++ b/skills/agent-device/references/video-recording.md
@@ -20,7 +20,15 @@ agent-device close
 agent-device record stop
 ```
 
-`record` is iOS simulator-only.
+`record` supports iOS simulators, physical iOS devices, and Android.
+
+Recording outputs:
+- a video artifact
+- a gesture-telemetry sidecar JSON next to the video
+
+Touch overlay support:
+- macOS host: telemetry can be burned into the video as visible touch overlays
+- non-macOS host: recording still succeeds, but the video stays raw and `record stop` returns an `overlayWarning`
 
 ## Android Emulator/Device
 
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 9911abfe5..ac951a32d 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -353,8 +353,8 @@ export async function dispatchCommand(
           const direction = positionals[0];
           const amount = positionals[1] ? Number(positionals[1]) : undefined;
           if (!direction) throw new AppError('INVALID_ARGS', 'scroll requires direction');
-          await interactor.scroll(direction, amount);
-          return { direction, amount };
+          const interactionResult = await interactor.scroll(direction, amount);
+          return { direction, amount, ...interactionResult };
         }
         case 'scrollintoview': {
           const text = positionals.join(' ').trim();
diff --git a/src/daemon/__tests__/recording-gestures.test.ts b/src/daemon/__tests__/recording-gestures.test.ts
index 3eaa87c8e..bb829f8be 100644
--- a/src/daemon/__tests__/recording-gestures.test.ts
+++ b/src/daemon/__tests__/recording-gestures.test.ts
@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import type { SessionState } from '../types.ts';
 import {
-  augmentTouchVisualizationResult,
+  augmentScrollVisualizationResult,
   recordTouchVisualizationEvent,
 } from '../recording-gestures.ts';
 import { attachRefs } from '../../utils/snapshot.ts';
@@ -44,7 +44,7 @@ function makeSession(): SessionState {
 
 test('scroll records a semantic scroll gesture for visualization telemetry', () => {
   const session = makeSession();
-  const result = augmentTouchVisualizationResult(session, 'scroll', ['down'], {
+  const result = augmentScrollVisualizationResult(session, 'scroll', ['down'], {
     direction: 'down',
   });
 
@@ -68,7 +68,7 @@ test('scroll records a semantic scroll gesture for visualization telemetry', ()
 
 test('scroll amount scales swipe travel for visualization', () => {
   const session = makeSession();
-  const result = augmentTouchVisualizationResult(session, 'scroll', ['right', '0.6'], {
+  const result = augmentScrollVisualizationResult(session, 'scroll', ['right', '0.6'], {
     direction: 'right',
     amount: 0.6,
   });
@@ -90,7 +90,7 @@ test('scroll augmentation falls back to normalized geometry without a snapshot',
   const session = makeSession();
   session.snapshot = undefined;
 
-  const augmented = augmentTouchVisualizationResult(session, 'scroll', ['down'], {
+  const augmented = augmentScrollVisualizationResult(session, 'scroll', ['down'], {
     direction: 'down',
   });
 
@@ -99,6 +99,24 @@ test('scroll augmentation falls back to normalized geometry without a snapshot',
   assert.equal((augmented as Record<string, unknown>).referenceHeight, 1000);
 });
 
+test('scroll augmentation preserves explicit reference frame from platform result', () => {
+  const session = makeSession();
+  session.snapshot = undefined;
+
+  const augmented = augmentScrollVisualizationResult(session, 'scroll', ['down', '0.45'], {
+    direction: 'down',
+    referenceWidth: 402,
+    referenceHeight: 874,
+  }) as Record<string, unknown>;
+
+  assert.equal(augmented.referenceWidth, 402);
+  assert.equal(augmented.referenceHeight, 874);
+  assert.equal(augmented.x1, 201);
+  assert.equal(augmented.y1, 634);
+  assert.equal(augmented.x2, 201);
+  assert.equal(augmented.y2, 240);
+});
+
 test('gesture recording prefers native runner timing when available', () => {
   const session = makeSession();
   session.recording = {
@@ -125,6 +143,24 @@ test('gesture recording prefers native runner timing when available', () => {
   assert.equal(event?.tMs, 180);
 });
 
+test('ios tap visualization anchors near completion when command execution stalls', () => {
+  const session = makeSession();
+
+  recordTouchVisualizationEvent(
+    session,
+    'click',
+    [],
+    { x: 201, y: 319 },
+    {},
+    1_500,
+    3_700,
+  );
+
+  const event = session.recording?.gestureEvents[0];
+  assert.equal(event?.kind, 'tap');
+  assert.equal(event?.tMs, 2_440);
+});
+
 test('swipe visualization prefers native gesture duration when available', () => {
   const session = makeSession();
 
diff --git a/src/daemon/__tests__/recording-timing.test.ts b/src/daemon/__tests__/recording-timing.test.ts
new file mode 100644
index 000000000..f2f88f66d
--- /dev/null
+++ b/src/daemon/__tests__/recording-timing.test.ts
@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveGestureOffsetMs } from '../recording-timing.ts';
+
+test('resolveGestureOffsetMs uses runner uptime anchor when available', () => {
+  const offset = resolveGestureOffsetMs({
+    recordingStartedAt: 1_000,
+    runnerStartedAtUptimeMs: 10_000,
+    gestureStartUptimeMs: 10_240,
+    gestureEndUptimeMs: 10_300,
+    fallbackStartedAtMs: 1_200,
+    fallbackFinishedAtMs: 1_400,
+  });
+
+  assert.equal(offset, 240);
+});
+
+test('resolveGestureOffsetMs uses gesture clock origin when available', () => {
+  const offset = resolveGestureOffsetMs({
+    recordingStartedAt: 1_000,
+    gestureClockOriginAtMs: 1_120,
+    gestureClockOriginUptimeMs: 20_000,
+    gestureStartUptimeMs: 20_240,
+    gestureEndUptimeMs: 20_300,
+    fallbackStartedAtMs: 1_500,
+    fallbackFinishedAtMs: 1_900,
+  });
+
+  assert.equal(offset, 360);
+});
+
+test('resolveGestureOffsetMs derives simulator offset from gesture end uptime', () => {
+  const offset = resolveGestureOffsetMs({
+    recordingStartedAt: 1_000,
+    gestureStartUptimeMs: 5_000,
+    gestureEndUptimeMs: 5_150,
+    fallbackStartedAtMs: 1_100,
+    fallbackFinishedAtMs: 1_800,
+  });
+
+  assert.equal(offset, 650);
+});
+
+test('resolveGestureOffsetMs falls back to command start when no uptime data exists', () => {
+  const offset = resolveGestureOffsetMs({
+    recordingStartedAt: 1_000,
+    fallbackStartedAtMs: 1_240,
+    fallbackFinishedAtMs: 1_500,
+  });
+
+  assert.equal(offset, 240);
+});
diff --git a/src/daemon/handlers/__tests__/interaction.test.ts b/src/daemon/handlers/__tests__/interaction.test.ts
index 8d22e8f0a..863d79f66 100644
--- a/src/daemon/handlers/__tests__/interaction.test.ts
+++ b/src/daemon/handlers/__tests__/interaction.test.ts
@@ -335,7 +335,7 @@ test('press @ref preserves native timing in recorded result and touch visualizat
   const result = (stored?.actions[0]?.result ?? {}) as Record<string, unknown>;
   assert.equal(result.gestureStartUptimeMs, 5_100);
   assert.equal(result.gestureEndUptimeMs, 5_180);
-  assert.equal(stored?.recording?.gestureEvents[0]?.tMs, 500);
+  assert.equal(stored?.recording?.gestureEvents[0]?.tMs, 570);
 });
 
 test('press @ref resolves snapshot node and records press action', async () => {
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index f91df5c9b..da1d12cdb 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -714,6 +714,68 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
   assert.equal(stopped, true);
 });
 
+test('record stop keeps iOS simulator video when overlay export fails', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-overlay-warning';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-warning.mp4'],
+    deps: {
+      runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
+      runCmdBackground: () => ({
+        child: { kill: () => {} } as any,
+        wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+      }),
+      runIosRunnerCommand: async () => ({}),
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {
+        throw new Error('swift export failed');
+      },
+    },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps: {
+      runCmd: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
+      runCmdBackground: () => {
+        throw new Error('runCmdBackground should not be called on stop for simulator');
+      },
+      runIosRunnerCommand: async () => ({}),
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {
+        throw new Error('swift export failed');
+      },
+    },
+  });
+
+  assert.equal(responseStop?.ok, true);
+  assert.equal(
+    responseStop?.data?.overlayWarning,
+    'failed to overlay recording touches: swift export failed',
+  );
+});
+
 test('record start does not fail when iOS simulator runner warm-up fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim-warm-failure';
@@ -835,6 +897,81 @@ test('record start/stop overlays Android gestures by default on devices', async
   ]);
 });
 
+test('record stop keeps Android video when overlay export fails', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-overlay-warning';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android-warning.mp4'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        if (
+          /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '4321\n', stderr: '', exitCode: 0 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  const startedRecording = sessionStore.get(sessionName)?.recording;
+  startedRecording?.gestureEvents.push({ kind: 'tap', tMs: 120, x: 90, y: 180 });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        const command = args.join(' ');
+        if (command === '-s emulator-5554 shell ps -o pid= -p 4321') {
+          return { stdout: '', stderr: '', exitCode: 1 };
+        }
+        if (
+          /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            command,
+          )
+        ) {
+          return { stdout: '2048\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      overlayRecordingTouches: async () => {
+        throw new Error('android overlay export failed');
+      },
+    }),
+  });
+
+  assert.equal(responseStop?.ok, true);
+  assert.equal(
+    responseStop?.data?.overlayWarning,
+    'failed to overlay recording touches: android overlay export failed',
+  );
+});
+
 test('record stop force-kills Android screenrecord when SIGINT fails but process is still running', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-force-stop';
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 30d3d25a9..792787016 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
+import { getRecordingOverlaySupportWarning } from '../../platforms/ios/recording-overlay.ts';
 import type { DaemonResponse, SessionState } from '../types.ts';
 import { persistRecordingTelemetry } from '../recording-telemetry.ts';
 import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
@@ -7,6 +8,7 @@ import type { RecordTraceDeps } from './record-trace-recording.ts';
 
 const ANDROID_REMOTE_FILE_POLL_MS = 250;
 const ANDROID_REMOTE_FILE_ATTEMPTS = 20;
+const ANDROID_REMOTE_FILE_STABLE_POLLS = 4;
 const ANDROID_LOCAL_VIDEO_ATTEMPTS = 2;
 const ANDROID_LOCAL_VIDEO_RETRY_DELAY_MS = 750;
 const ANDROID_PROCESS_EXIT_POLL_MS = 250;
@@ -81,7 +83,7 @@ async function waitForAndroidRemoteFileStability(
     const currentSize = statResult.exitCode === 0 ? statResult.stdout.trim() : '';
     if (currentSize.length > 0 && currentSize === previousSize) {
       stableCount += 1;
-      if (stableCount >= 2) {
+      if (stableCount >= ANDROID_REMOTE_FILE_STABLE_POLLS) {
         return;
       }
     } else {
@@ -318,11 +320,6 @@ export async function stopAndroidRecording(params: {
       remotePid: recording.remotePid,
     },
   });
-  let stopError: string | undefined;
-  let copyError: string | undefined;
-  let cleanupError: string | undefined;
-  let overlayError: string | undefined;
-
   const stopResult = await deps.runCmd(
     'adb',
     ['-s', device.id, 'shell', 'kill', '-2', recording.remotePid],
@@ -342,6 +339,7 @@ export async function stopAndroidRecording(params: {
       stderr: stopResult.stderr.trim(),
     },
   });
+  let stopError: string | undefined;
   if (stopResult.exitCode !== 0) {
     if (await isAndroidProcessRunning(deps, device.id, recording.remotePid)) {
       if (!(await forceStopAndroidProcess(deps, device.id, recording.remotePid))) {
@@ -353,55 +351,50 @@ export async function stopAndroidRecording(params: {
       stopError = `failed to stop recording: Android screenrecord pid ${recording.remotePid} did not exit`;
     }
   }
+  let cleanupError: string | undefined;
 
   if (!stopError) {
     await waitForAndroidRemoteFileStability(deps, device.id, recording.remotePath);
-    copyError = await copyAndroidRecordingWithValidation({
+    const copyError = await copyAndroidRecordingWithValidation({
       deps,
       deviceId: device.id,
       remotePath: recording.remotePath,
       outPath: recording.outPath,
     });
-    if (!copyError) {
-      persistRecordingTelemetry({
-        recording,
-        writeTelemetry: deps.writeRecordingTelemetry,
-      });
+    if (copyError) {
+      await cleanupRemoteRecording();
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: copyError,
+        },
+      };
     }
-    if (!copyError && recording.showTouches && recording.telemetryPath) {
-      try {
-        await deps.overlayRecordingTouches({
-          videoPath: recording.outPath,
-          telemetryPath: recording.telemetryPath,
-          targetLabel: 'Android recording',
-        });
-      } catch (error) {
-        overlayError = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+
+    persistRecordingTelemetry({
+      recording,
+      writeTelemetry: deps.writeRecordingTelemetry,
+    });
+    if (recording.showTouches && recording.telemetryPath) {
+      const overlaySupportWarning = getRecordingOverlaySupportWarning();
+      if (overlaySupportWarning) {
+        recording.overlayWarning = overlaySupportWarning;
+      } else {
+        try {
+          await deps.overlayRecordingTouches({
+            videoPath: recording.outPath,
+            telemetryPath: recording.telemetryPath,
+            targetLabel: 'Android recording',
+          });
+        } catch (error) {
+          recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+        }
       }
     }
   }
 
-  const rmResult = await deps.runCmd(
-    'adb',
-    ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath],
-    {
-      allowFailure: true,
-    },
-  );
-  emitDiagnostic({
-    level: 'debug',
-    phase: 'record_stop_android_cleanup',
-    data: {
-      deviceId: device.id,
-      remotePath: recording.remotePath,
-      exitCode: rmResult.exitCode,
-      stdout: rmResult.stdout.trim(),
-      stderr: rmResult.stderr.trim(),
-    },
-  });
-  if (rmResult.exitCode !== 0 && !stopError) {
-    cleanupError = `failed to clean up remote recording: ${formatRecordTraceExecFailure(rmResult, 'adb shell rm')}`;
-  }
+  await cleanupRemoteRecording();
 
   if (stopError) {
     return {
@@ -413,26 +406,6 @@ export async function stopAndroidRecording(params: {
     };
   }
 
-  if (copyError) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: copyError,
-      },
-    };
-  }
-
-  if (overlayError) {
-    return {
-      ok: false,
-      error: {
-        code: 'COMMAND_FAILED',
-        message: overlayError,
-      },
-    };
-  }
-
   if (cleanupError) {
     return {
       ok: false,
@@ -444,4 +417,28 @@ export async function stopAndroidRecording(params: {
   }
 
   return null;
+
+  async function cleanupRemoteRecording(): Promise<void> {
+    const rmResult = await deps.runCmd(
+      'adb',
+      ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath],
+      {
+        allowFailure: true,
+      },
+    );
+    emitDiagnostic({
+      level: 'debug',
+      phase: 'record_stop_android_cleanup',
+      data: {
+        deviceId: device.id,
+        remotePath: recording.remotePath,
+        exitCode: rmResult.exitCode,
+        stdout: rmResult.stdout.trim(),
+        stderr: rmResult.stderr.trim(),
+      },
+    });
+    if (rmResult.exitCode !== 0 && !stopError) {
+      cleanupError = `failed to clean up remote recording: ${formatRecordTraceExecFailure(rmResult, 'adb shell rm')}`;
+    }
+  }
 }
diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
index 3bc4d50ce..f9253e959 100644
--- a/src/daemon/handlers/record-trace-ios.ts
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -1,23 +1,11 @@
 import { SessionStore } from '../session-store.ts';
-import type {
-  DaemonRequest,
-  DaemonResponse,
-  RecordingGestureEvent,
-  SessionState,
-} from '../types.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { persistRecordingTelemetry } from '../recording-telemetry.ts';
 import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../platforms/ios/runner-client.ts';
+import { getRecordingOverlaySupportWarning } from '../../platforms/ios/recording-overlay.ts';
 import { formatRecordTraceError } from '../record-trace-errors.ts';
-import type { RecordTraceDeps } from './record-trace-recording.ts';
-
-type RecordingBase = {
-  outPath: string;
-  clientOutPath?: string;
-  startedAt: number;
-  showTouches: boolean;
-  gestureEvents: RecordingGestureEvent[];
-};
+import type { RecordTraceDeps, RecordingBase } from './record-trace-recording.ts';
 
 export function normalizeAppBundleId(session: SessionState): string | undefined {
   const trimmed = session.appBundleId?.trim();
@@ -313,11 +301,20 @@ export async function stopIosDeviceRecording(params: {
   });
 
   if (recording.showTouches) {
-    await deps.overlayRecordingTouches({
-      videoPath: recording.outPath,
-      telemetryPath,
-      targetLabel: 'iOS recording',
-    });
+    const overlaySupportWarning = getRecordingOverlaySupportWarning();
+    if (overlaySupportWarning) {
+      recording.overlayWarning = overlaySupportWarning;
+    } else {
+      try {
+        await deps.overlayRecordingTouches({
+          videoPath: recording.outPath,
+          telemetryPath,
+          targetLabel: 'iOS recording',
+        });
+      } catch (error) {
+        recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+      }
+    }
   }
 
   return null;
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index f9a846e61..2318ff111 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -20,6 +20,7 @@ import {
 } from '../recording-telemetry.ts';
 import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
 import {
+  getRecordingOverlaySupportWarning,
   overlayRecordingTouches,
   trimRecordingStart,
 } from '../../platforms/ios/recording-overlay.ts';
@@ -36,8 +37,7 @@ import {
 const IOS_DEVICE_RECORD_MIN_FPS = 1;
 const IOS_DEVICE_RECORD_MAX_FPS = 120;
 const LOCAL_RECORDING_READY_POLL_MS = 250;
-const LOCAL_RECORDING_READY_ATTEMPTS = 24;
-const LOCAL_RECORDING_READY_MIN_POLLS = 2;
+const LOCAL_RECORDING_READY_SETTLE_POLLS = 2;
 
 export type RecordTraceDeps = {
   runCmd: typeof runCmd;
@@ -50,6 +50,14 @@ export type RecordTraceDeps = {
   overlayRecordingTouches: typeof overlayRecordingTouches;
 };
 
+export type RecordingBase = {
+  outPath: string;
+  clientOutPath?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+};
+
 export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): RecordTraceDeps {
   return {
     runCmd,
@@ -64,16 +72,7 @@ export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): Reco
   };
 }
 
-function buildRecordingBase(
-  req: DaemonRequest,
-  outPath: string,
-): {
-  outPath: string;
-  clientOutPath?: string;
-  startedAt: number;
-  showTouches: boolean;
-  gestureEvents: RecordingGestureEvent[];
-} {
+function buildRecordingBase(req: DaemonRequest, outPath: string): RecordingBase {
   return {
     outPath,
     clientOutPath: req.meta?.clientArtifactPaths?.outPath,
@@ -83,8 +82,11 @@ function buildRecordingBase(
   };
 }
 
-async function waitForLocalRecordingReady(outPath: string): Promise<number | undefined> {
-  for (let attempt = 0; attempt < LOCAL_RECORDING_READY_ATTEMPTS; attempt += 1) {
+async function waitForLocalRecordingSettleWindow(outPath: string): Promise<number> {
+  // simctl recordVideo can take a beat to open its output even though recording has already
+  // started. This is a short settle window, not a strict readiness guarantee. We prefer a
+  // close recorder anchor over blocking start indefinitely waiting for non-zero bytes.
+  for (let attempt = 0; attempt < LOCAL_RECORDING_READY_SETTLE_POLLS; attempt += 1) {
     try {
       const stat = fs.statSync(outPath);
       if (stat.size > 0) {
@@ -94,14 +96,14 @@ async function waitForLocalRecordingReady(outPath: string): Promise<number | und
       // Wait for the recorder to create the output file.
     }
 
-    if (attempt + 1 >= LOCAL_RECORDING_READY_MIN_POLLS) {
+    if (attempt + 1 >= LOCAL_RECORDING_READY_SETTLE_POLLS) {
       return Date.now();
     }
 
     await new Promise((resolve) => setTimeout(resolve, LOCAL_RECORDING_READY_POLL_MS));
   }
 
-  return undefined;
+  return Date.now();
 }
 
 async function startRecording(params: {
@@ -193,13 +195,41 @@ async function startRecording(params: {
         allowFailure: true,
       },
     );
-    const readyAt = await waitForLocalRecordingReady(resolvedOut);
+    const readyAt = await waitForLocalRecordingSettleWindow(resolvedOut);
+    let gestureClockOriginAtMs: number | undefined;
+    let gestureClockOriginUptimeMs: number | undefined;
+    try {
+      const uptimeRequestStartedAtMs = Date.now();
+      const uptimeResult = await deps.runIosRunnerCommand(
+        device,
+        {
+          command: 'uptime',
+          appBundleId: normalizeAppBundleId(activeSession),
+        },
+        {
+          verbose: req.flags?.verbose,
+          logPath,
+          traceLogPath: activeSession.trace?.outPath,
+        },
+      );
+      const uptimeRequestFinishedAtMs = Date.now();
+      gestureClockOriginAtMs = Math.round(
+        (uptimeRequestStartedAtMs + uptimeRequestFinishedAtMs) / 2,
+      );
+      gestureClockOriginUptimeMs =
+        typeof uptimeResult.currentUptimeMs === 'number' ? uptimeResult.currentUptimeMs : undefined;
+    } catch {
+      // Best effort only; wall-clock fallback remains available.
+    }
     recording = {
       platform: 'ios',
       child,
       wait,
       ...recordingBase,
-      startedAt: readyAt ?? recordingBase.startedAt,
+      startedAt: readyAt,
+      gestureClockOriginAtMs:
+        gestureClockOriginUptimeMs === undefined ? undefined : gestureClockOriginAtMs,
+      gestureClockOriginUptimeMs,
     };
   } else {
     recording = await startAndroidRecording({ deps, device, recordingBase });
@@ -257,11 +287,20 @@ async function stopNonRunnerRecording(params: {
   });
 
   if (recording.showTouches) {
-    await deps.overlayRecordingTouches({
-      videoPath: recording.outPath,
-      telemetryPath,
-      targetLabel: 'iOS recording',
-    });
+    const overlaySupportWarning = getRecordingOverlaySupportWarning();
+    if (overlaySupportWarning) {
+      recording.overlayWarning = overlaySupportWarning;
+    } else {
+      try {
+        await deps.overlayRecordingTouches({
+          videoPath: recording.outPath,
+          telemetryPath,
+          targetLabel: 'iOS recording',
+        });
+      } catch (error) {
+        recording.overlayWarning = `failed to overlay recording touches: ${formatOverlayError(error)}`;
+      }
+    }
   }
 
   return null;
@@ -333,6 +372,7 @@ function buildRecordStopResponse(
       telemetryPath: recording.telemetryPath,
       artifacts,
       showTouches: recording.showTouches,
+      overlayWarning: recording.overlayWarning,
     },
   };
 }
@@ -346,6 +386,13 @@ function deriveClientTelemetryPath(
   return deriveRecordingTelemetryPath(recording.clientOutPath);
 }
 
+function formatOverlayError(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+  return String(error);
+}
+
 export async function handleRecordCommand(params: {
   req: DaemonRequest;
   sessionName: string;
diff --git a/src/daemon/recording-gestures.ts b/src/daemon/recording-gestures.ts
index f60a43318..1356c0449 100644
--- a/src/daemon/recording-gestures.ts
+++ b/src/daemon/recording-gestures.ts
@@ -1,6 +1,10 @@
 import type { RecordingGestureEvent, SessionState } from './types.ts';
 import type { SnapshotState } from '../utils/snapshot.ts';
-import { resolveGestureDurationMs, resolveGestureOffsetMs } from './recording-timing.ts';
+import {
+  resolveGestureDurationMs,
+  resolveGestureOffsetMs,
+  resolveTapVisualizationOffsetMs,
+} from './recording-timing.ts';
 import { emitDiagnostic } from '../utils/diagnostics.ts';
 import {
   getSnapshotReferenceFrame,
@@ -33,13 +37,17 @@ export function recordTouchVisualizationEvent(
   const merged = { ...fallback, ...(result ?? {}) };
   const reportedDurationMs =
     readNumber(merged.effectiveDurationMs) ?? readNumber(merged.durationMs);
-  const tMs = resolveGestureOffsetMs({
+  const timingSource = {
     recordingStartedAt: recording.startedAt,
+    gestureClockOriginAtMs: recording.gestureClockOriginAtMs,
+    gestureClockOriginUptimeMs: recording.gestureClockOriginUptimeMs,
     runnerStartedAtUptimeMs:
       recording.platform === 'ios-device-runner' ? recording.runnerStartedAtUptimeMs : undefined,
     gestureStartUptimeMs: readNumber(merged.gestureStartUptimeMs),
+    gestureEndUptimeMs: readNumber(merged.gestureEndUptimeMs),
     fallbackStartedAtMs: startedAtMs,
-  });
+    fallbackFinishedAtMs: finishedAtMs,
+  };
   const gestureDurationMs = resolveGestureDurationMs({
     gestureStartUptimeMs: readNumber(merged.gestureStartUptimeMs),
     gestureEndUptimeMs: readNumber(merged.gestureEndUptimeMs),
@@ -47,6 +55,12 @@ export function recordTouchVisualizationEvent(
     fallbackStartedAtMs: startedAtMs,
     fallbackFinishedAtMs: finishedAtMs,
   });
+  const tMs =
+    session.device.platform === 'ios' &&
+    readNumber(merged.gestureStartUptimeMs) === undefined &&
+    shouldAnchorTapVisualizationNearCompletion(command, merged)
+      ? resolveTapVisualizationOffsetMs({ ...timingSource, gestureDurationMs })
+      : resolveGestureOffsetMs(timingSource);
   const referenceFrame = resolveEventReferenceFrame(session.snapshot, merged);
   const events = buildGestureEvents(
     command,
@@ -72,7 +86,9 @@ export function recordTouchVisualizationEvent(
   });
 }
 
-export function augmentTouchVisualizationResult(
+// Scroll commands do not carry a concrete gesture path from the platform layer, so we
+// synthesize one here before recording telemetry.
+export function augmentScrollVisualizationResult(
   session: SessionState,
   command: string,
   positionals: string[],
@@ -80,16 +96,26 @@ export function augmentTouchVisualizationResult(
 ): Record<string, unknown> | void {
   if (command !== 'scroll') return result;
 
-  const referenceFrame = getReferenceFrame(session.snapshot);
+  const referenceFrame = getSnapshotReferenceFrame(session.snapshot);
   const merged = { ...(result ?? {}) };
   const contentDirection = readDirection(merged.direction) ?? readDirection(positionals[0]);
   if (!contentDirection) return result;
 
   const amountValue = readNumber(merged.amount) ?? readNumber(positionals[1]);
   const travelFraction = resolveScrollTravelFraction(amountValue);
-  const fallbackReferenceFrame = referenceFrame ?? DEFAULT_SCROLL_REFERENCE_FRAME;
-  const start = scrollStartPoint(contentDirection, fallbackReferenceFrame, travelFraction);
-  const end = scrollEndPoint(contentDirection, fallbackReferenceFrame, travelFraction);
+  const explicitReferenceWidth = readNumber(merged.referenceWidth);
+  const explicitReferenceHeight = readNumber(merged.referenceHeight);
+  const fallbackReferenceFrame =
+    explicitReferenceWidth !== undefined &&
+    explicitReferenceWidth > 0 &&
+    explicitReferenceHeight !== undefined &&
+    explicitReferenceHeight > 0
+      ? {
+          referenceWidth: explicitReferenceWidth,
+          referenceHeight: explicitReferenceHeight,
+        }
+      : (referenceFrame ?? DEFAULT_SCROLL_REFERENCE_FRAME);
+  const { start, end } = scrollPoints(contentDirection, fallbackReferenceFrame, travelFraction);
 
   return {
     ...merged,
@@ -133,6 +159,26 @@ function buildGestureEvents(
   }
 }
 
+function shouldAnchorTapVisualizationNearCompletion(
+  command: string,
+  result: Record<string, unknown>,
+): boolean {
+  switch (command) {
+    case 'click':
+    case 'fill':
+    case 'focus':
+      return true;
+    case 'press': {
+      const count = clampInt(readNumber(result.count), 1) ?? 1;
+      const doubleTap = result.doubleTap === true;
+      const holdMs = clampInt(readNumber(result.holdMs), 1);
+      return count === 1 && !doubleTap && holdMs === undefined;
+    }
+    default:
+      return false;
+  }
+}
+
 function buildPressEvents(
   positionals: string[],
   result: Record<string, unknown>,
@@ -169,9 +215,9 @@ function buildFocusEvents(
   tMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x = readNumber(result.x) ?? readNumber(positionals[0]);
-  const y = readNumber(result.y) ?? readNumber(positionals[1]);
-  if (x === undefined || y === undefined) return [];
+  const coordinates = readCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x, y } = coordinates;
   return [makeTapEvent(tMs, x, y, referenceFrame)];
 }
 
@@ -182,14 +228,14 @@ function buildLongPressEvents(
   gestureDurationMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x = readNumber(result.x) ?? readNumber(positionals[0]);
-  const y = readNumber(result.y) ?? readNumber(positionals[1]);
-  if (x === undefined || y === undefined) return [];
-  const durationMs =
-    clampInt(gestureDurationMs, 1) ??
-    clampInt(readNumber(result.durationMs), 1) ??
-    clampInt(readNumber(positionals[2]), 1) ??
-    800;
+  const coordinates = readCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x, y } = coordinates;
+  const durationMs = resolveDurationMs(
+    gestureDurationMs,
+    [readNumber(result.durationMs), readNumber(positionals[2])],
+    800,
+  );
   return [makeLongPressEvent(tMs, x, y, durationMs, referenceFrame)];
 }
 
@@ -200,18 +246,19 @@ function buildSwipeEvents(
   gestureDurationMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x1 = readNumber(result.x1) ?? readNumber(positionals[0]);
-  const y1 = readNumber(result.y1) ?? readNumber(positionals[1]);
-  const x2 = readNumber(result.x2) ?? readNumber(positionals[2]);
-  const y2 = readNumber(result.y2) ?? readNumber(positionals[3]);
-  if (x1 === undefined || y1 === undefined || x2 === undefined || y2 === undefined) return [];
+  const coordinates = readTravelCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x1, y1, x2, y2 } = coordinates;
 
-  const durationMs =
-    clampInt(gestureDurationMs, 1) ??
-    clampInt(readNumber(result.effectiveDurationMs), 1) ??
-    clampInt(readNumber(result.durationMs), 1) ??
-    clampInt(readNumber(positionals[4]), 1) ??
-    DEFAULT_SWIPE_DURATION_MS;
+  const durationMs = resolveDurationMs(
+    gestureDurationMs,
+    [
+      readNumber(result.effectiveDurationMs),
+      readNumber(result.durationMs),
+      readNumber(positionals[4]),
+    ],
+    DEFAULT_SWIPE_DURATION_MS,
+  );
   const count = clampInt(readNumber(result.count), 1) ?? 1;
   const pauseMs = clampInt(readNumber(result.pauseMs), 0) ?? 0;
   const pattern = result.pattern === 'ping-pong' ? 'ping-pong' : 'one-way';
@@ -261,23 +308,15 @@ function buildScrollEvents(
   gestureDurationMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x1 = readNumber(result.x1) ?? readNumber(positionals[0]);
-  const y1 = readNumber(result.y1) ?? readNumber(positionals[1]);
-  const x2 = readNumber(result.x2) ?? readNumber(positionals[2]);
-  const y2 = readNumber(result.y2) ?? readNumber(positionals[3]);
+  const coordinates = readTravelCoordinates(result, positionals);
   const contentDirection =
     readDirection(result.contentDirection) ?? readDirection(result.direction);
-  if (
-    x1 === undefined ||
-    y1 === undefined ||
-    x2 === undefined ||
-    y2 === undefined ||
-    !contentDirection
-  ) {
+  if (!coordinates || !contentDirection) {
     return [];
   }
+  const { x1, y1, x2, y2 } = coordinates;
 
-  const durationMs = clampInt(gestureDurationMs, 1) ?? DEFAULT_SWIPE_DURATION_MS;
+  const durationMs = resolveDurationMs(gestureDurationMs, [], DEFAULT_SWIPE_DURATION_MS);
   const amount = readNumber(result.amount) ?? readNumber(positionals[1]);
   return [
     {
@@ -302,10 +341,10 @@ function buildPinchEvents(
   gestureDurationMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x = readNumber(result.x) ?? readNumber(positionals[1]);
-  const y = readNumber(result.y) ?? readNumber(positionals[2]);
+  const coordinates = readCoordinates(result, positionals, 1);
   const scale = readNumber(result.scale) ?? readNumber(positionals[0]);
-  if (x === undefined || y === undefined || scale === undefined || scale <= 0) return [];
+  if (!coordinates || scale === undefined || scale <= 0) return [];
+  const { x, y } = coordinates;
   return [
     {
       kind: 'pinch',
@@ -314,7 +353,7 @@ function buildPinchEvents(
       y,
       ...referenceFrame,
       scale,
-      durationMs: clampInt(gestureDurationMs, 1) ?? DEFAULT_PINCH_DURATION_MS,
+      durationMs: resolveDurationMs(gestureDurationMs, [], DEFAULT_PINCH_DURATION_MS),
     },
   ];
 }
@@ -369,10 +408,6 @@ function resolveBackSwipeEdge(
   return endX >= startX ? 'left' : 'right';
 }
 
-function getReferenceFrame(snapshot: SnapshotState | undefined): ReferenceFrame | undefined {
-  return getSnapshotReferenceFrame(snapshot);
-}
-
 function resolveEventReferenceFrame(
   snapshot: SnapshotState | undefined,
   result: Record<string, unknown>,
@@ -388,20 +423,18 @@ function resolveEventReferenceFrame(
     return { referenceWidth, referenceHeight };
   }
 
-  const snapshotReferenceFrame = getReferenceFrame(snapshot);
-  if (snapshotReferenceFrame) return snapshotReferenceFrame;
-
-  return undefined;
+  return getSnapshotReferenceFrame(snapshot);
 }
 
 function readDirection(value: unknown): 'up' | 'down' | 'left' | 'right' | undefined {
   if (typeof value !== 'string') return undefined;
-  switch (value.trim().toLowerCase()) {
+  const normalized = value.trim().toLowerCase();
+  switch (normalized) {
     case 'up':
     case 'down':
     case 'left':
     case 'right':
-      return value.trim().toLowerCase() as 'up' | 'down' | 'left' | 'right';
+      return normalized as 'up' | 'down' | 'left' | 'right';
     default:
       return undefined;
   }
@@ -416,33 +449,11 @@ function resolveScrollTravelFraction(amount: number | undefined): number {
   return clampNumber(amount / 100, MIN_SCROLL_FRACTION, MAX_SCROLL_FRACTION);
 }
 
-function scrollStartPoint(
-  contentDirection: 'up' | 'down' | 'left' | 'right',
-  referenceFrame: ReferenceFrame,
-  travelFraction: number,
-): { x: number; y: number } {
-  const midX = Math.round(referenceFrame.referenceWidth / 2);
-  const midY = Math.round(referenceFrame.referenceHeight / 2);
-  const travelX = Math.round((referenceFrame.referenceWidth * travelFraction) / 2);
-  const travelY = Math.round((referenceFrame.referenceHeight * travelFraction) / 2);
-
-  switch (contentDirection) {
-    case 'up':
-      return { x: midX, y: midY - travelY };
-    case 'down':
-      return { x: midX, y: midY + travelY };
-    case 'left':
-      return { x: midX - travelX, y: midY };
-    case 'right':
-      return { x: midX + travelX, y: midY };
-  }
-}
-
-function scrollEndPoint(
+function scrollPoints(
   contentDirection: 'up' | 'down' | 'left' | 'right',
   referenceFrame: ReferenceFrame,
   travelFraction: number,
-): { x: number; y: number } {
+): { start: { x: number; y: number }; end: { x: number; y: number } } {
   const midX = Math.round(referenceFrame.referenceWidth / 2);
   const midY = Math.round(referenceFrame.referenceHeight / 2);
   const travelX = Math.round((referenceFrame.referenceWidth * travelFraction) / 2);
@@ -450,13 +461,25 @@ function scrollEndPoint(
 
   switch (contentDirection) {
     case 'up':
-      return { x: midX, y: midY + travelY };
+      return {
+        start: { x: midX, y: midY - travelY },
+        end: { x: midX, y: midY + travelY },
+      };
     case 'down':
-      return { x: midX, y: midY - travelY };
+      return {
+        start: { x: midX, y: midY + travelY },
+        end: { x: midX, y: midY - travelY },
+      };
     case 'left':
-      return { x: midX + travelX, y: midY };
+      return {
+        start: { x: midX - travelX, y: midY },
+        end: { x: midX + travelX, y: midY },
+      };
     case 'right':
-      return { x: midX - travelX, y: midY };
+      return {
+        start: { x: midX + travelX, y: midY },
+        end: { x: midX - travelX, y: midY },
+      };
   }
 }
 
@@ -476,3 +499,44 @@ function clampInt(value: number | undefined, min: number): number | undefined {
 function clampNumber(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value));
 }
+
+function readCoordinates(
+  result: Record<string, unknown>,
+  positionals: string[],
+  positionalOffset = 0,
+): { x: number; y: number } | undefined {
+  const x = readNumber(result.x) ?? readNumber(positionals[positionalOffset]);
+  const y = readNumber(result.y) ?? readNumber(positionals[positionalOffset + 1]);
+  if (x === undefined || y === undefined) {
+    return undefined;
+  }
+  return { x, y };
+}
+
+function readTravelCoordinates(
+  result: Record<string, unknown>,
+  positionals: string[],
+): { x1: number; y1: number; x2: number; y2: number } | undefined {
+  const x1 = readNumber(result.x1) ?? readNumber(positionals[0]);
+  const y1 = readNumber(result.y1) ?? readNumber(positionals[1]);
+  const x2 = readNumber(result.x2) ?? readNumber(positionals[2]);
+  const y2 = readNumber(result.y2) ?? readNumber(positionals[3]);
+  if (x1 === undefined || y1 === undefined || x2 === undefined || y2 === undefined) {
+    return undefined;
+  }
+  return { x1, y1, x2, y2 };
+}
+
+function resolveDurationMs(
+  gestureDurationMs: number,
+  candidates: Array<number | undefined>,
+  fallbackDurationMs: number,
+): number {
+  return (
+    clampInt(gestureDurationMs, 1) ??
+    candidates
+      .map((candidate) => clampInt(candidate, 1))
+      .find((candidate) => candidate !== undefined) ??
+    fallbackDurationMs
+  );
+}
diff --git a/src/daemon/recording-timing.ts b/src/daemon/recording-timing.ts
index 71225a2ab..a2c11a62d 100644
--- a/src/daemon/recording-timing.ts
+++ b/src/daemon/recording-timing.ts
@@ -1,8 +1,12 @@
 type GestureTimingSource = {
   recordingStartedAt: number;
+  gestureClockOriginAtMs?: number;
+  gestureClockOriginUptimeMs?: number;
   runnerStartedAtUptimeMs?: number;
   gestureStartUptimeMs?: number;
+  gestureEndUptimeMs?: number;
   fallbackStartedAtMs: number;
+  fallbackFinishedAtMs: number;
 };
 
 type GestureDurationSource = {
@@ -13,13 +17,35 @@ type GestureDurationSource = {
   fallbackFinishedAtMs: number;
 };
 
+type TapVisualizationOffsetSource = GestureTimingSource & {
+  gestureDurationMs: number;
+};
+
 export function resolveGestureOffsetMs(source: GestureTimingSource): number {
+  if (
+    typeof source.gestureClockOriginAtMs === 'number' &&
+    typeof source.gestureClockOriginUptimeMs === 'number' &&
+    typeof source.gestureStartUptimeMs === 'number'
+  ) {
+    const wallClockAtGestureStart =
+      source.gestureClockOriginAtMs +
+      (source.gestureStartUptimeMs - source.gestureClockOriginUptimeMs);
+    return Math.max(0, wallClockAtGestureStart - source.recordingStartedAt);
+  }
   if (
     typeof source.runnerStartedAtUptimeMs === 'number' &&
     typeof source.gestureStartUptimeMs === 'number'
   ) {
     return Math.max(0, source.gestureStartUptimeMs - source.runnerStartedAtUptimeMs);
   }
+  if (
+    typeof source.gestureStartUptimeMs === 'number' &&
+    typeof source.gestureEndUptimeMs === 'number'
+  ) {
+    const wallClockAtGestureStart =
+      source.fallbackFinishedAtMs - (source.gestureEndUptimeMs - source.gestureStartUptimeMs);
+    return Math.max(0, wallClockAtGestureStart - source.recordingStartedAt);
+  }
   return Math.max(0, source.fallbackStartedAtMs - source.recordingStartedAt);
 }
 
@@ -35,3 +61,13 @@ export function resolveGestureDurationMs(source: GestureDurationSource): number
   }
   return Math.max(0, source.fallbackFinishedAtMs - source.fallbackStartedAtMs);
 }
+
+export function resolveTapVisualizationOffsetMs(source: TapVisualizationOffsetSource): number {
+  const durationMs = Math.max(0, source.gestureDurationMs);
+  if (durationMs < 600) {
+    return resolveGestureOffsetMs(source);
+  }
+
+  const leadMs = Math.min(Math.max(durationMs * 0.15, 120), 260);
+  return Math.max(0, source.fallbackFinishedAtMs - leadMs - source.recordingStartedAt);
+}
diff --git a/src/daemon/request-router.ts b/src/daemon/request-router.ts
index 42735cf91..9862a0bbc 100644
--- a/src/daemon/request-router.ts
+++ b/src/daemon/request-router.ts
@@ -34,7 +34,7 @@ import {
 import { resolveLeaseScope } from './lease-context.ts';
 import type { LeaseRegistry } from './lease-registry.ts';
 import {
-  augmentTouchVisualizationResult,
+  augmentScrollVisualizationResult,
   recordTouchVisualizationEvent,
 } from './recording-gestures.ts';
 import { recoverAndroidBlockingSystemDialog } from './android-system-dialog.ts';
@@ -452,7 +452,7 @@ export function createRequestHandler(
             ...dispatchContext,
           });
           const actionFinishedAt = Date.now();
-          const visualizationData = augmentTouchVisualizationResult(
+          const visualizationData = augmentScrollVisualizationResult(
             session,
             command,
             resolvedPositionals,
diff --git a/src/daemon/touch-reference-frame.ts b/src/daemon/touch-reference-frame.ts
index 157ced16a..c64a4e00f 100644
--- a/src/daemon/touch-reference-frame.ts
+++ b/src/daemon/touch-reference-frame.ts
@@ -5,32 +5,18 @@ export type TouchReferenceFrame = {
   referenceHeight: number;
 };
 
-type SnapshotReferenceFrameState = SnapshotState & {
-  referenceWidth?: number;
-  referenceHeight?: number;
-};
+const snapshotReferenceFrameCache = new WeakMap<SnapshotState, TouchReferenceFrame>();
 
 export function getSnapshotReferenceFrame(
   snapshot: SnapshotState | undefined,
 ): TouchReferenceFrame | undefined {
   if (!snapshot) return undefined;
-  const cachedSnapshot = snapshot as SnapshotReferenceFrameState;
-  if (
-    typeof cachedSnapshot.referenceWidth === 'number' &&
-    cachedSnapshot.referenceWidth > 0 &&
-    typeof cachedSnapshot.referenceHeight === 'number' &&
-    cachedSnapshot.referenceHeight > 0
-  ) {
-    return {
-      referenceWidth: cachedSnapshot.referenceWidth,
-      referenceHeight: cachedSnapshot.referenceHeight,
-    };
-  }
+  const cached = snapshotReferenceFrameCache.get(snapshot);
+  if (cached) return cached;
 
   const inferred = inferTouchReferenceFrame(snapshot.nodes ?? []);
   if (!inferred) return undefined;
-  cachedSnapshot.referenceWidth = inferred.referenceWidth;
-  cachedSnapshot.referenceHeight = inferred.referenceHeight;
+  snapshotReferenceFrameCache.set(snapshot, inferred);
   return inferred;
 }
 
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 9e16c07d0..0f33b8e40 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -110,6 +110,7 @@ type SessionRecordingBase = {
   outPath: string;
   clientOutPath?: string;
   telemetryPath?: string;
+  overlayWarning?: string;
   startedAt: number;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
@@ -117,6 +118,8 @@ type SessionRecordingBase = {
     referenceWidth: number;
     referenceHeight: number;
   };
+  gestureClockOriginAtMs?: number;
+  gestureClockOriginUptimeMs?: number;
   runnerSessionId?: string;
   invalidatedReason?: string;
 };
diff --git a/src/platforms/ios/__tests__/recording-scripts.test.ts b/src/platforms/ios/__tests__/recording-scripts.test.ts
new file mode 100644
index 000000000..722b0da4b
--- /dev/null
+++ b/src/platforms/ios/__tests__/recording-scripts.test.ts
@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCmd } from '../../../utils/exec.ts';
+import { getRecordingOverlaySupportWarning } from '../recording-overlay.ts';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const recordingScriptsDir = path.resolve(
+  __dirname,
+  '../../../../ios-runner/AgentDeviceRunner/RecordingScripts',
+);
+
+async function assertSwiftScriptTypechecks(scriptName: string): Promise<void> {
+  const scriptPath = path.join(recordingScriptsDir, scriptName);
+  const result = await runCmd('xcrun', ['swiftc', '-typecheck', scriptPath], {
+    allowFailure: true,
+  });
+  assert.equal(result.exitCode, 0, `${scriptName} should typecheck`);
+}
+
+test('recording overlay Swift script typechecks', async (t) => {
+  if (process.platform !== 'darwin') {
+    t.skip('Swift recording scripts are only validated on macOS');
+  }
+
+  await assertSwiftScriptTypechecks('recording-overlay.swift');
+});
+
+test('recording trim Swift script typechecks', async (t) => {
+  if (process.platform !== 'darwin') {
+    t.skip('Swift recording scripts are only validated on macOS');
+  }
+
+  await assertSwiftScriptTypechecks('recording-trim.swift');
+});
+
+test('recording inspect Swift script typechecks', async (t) => {
+  if (process.platform !== 'darwin') {
+    t.skip('Swift recording scripts are only validated on macOS');
+  }
+
+  await assertSwiftScriptTypechecks('recording-inspect.swift');
+});
+
+test('recording overlays are explicitly unsupported on non-macOS hosts', () => {
+  assert.equal(
+    getRecordingOverlaySupportWarning('linux'),
+    'touch overlay burn-in is only available on macOS hosts; returning raw video plus gesture telemetry',
+  );
+  assert.equal(getRecordingOverlaySupportWarning('darwin'), undefined);
+});
diff --git a/src/platforms/ios/recording-overlay.ts b/src/platforms/ios/recording-overlay.ts
index 03c90e15a..fdb76c5ab 100644
--- a/src/platforms/ios/recording-overlay.ts
+++ b/src/platforms/ios/recording-overlay.ts
@@ -34,6 +34,15 @@ function resolveScriptPath(scriptName: string): string {
 let overlayScriptPath: string | undefined;
 let trimScriptPath: string | undefined;
 
+export function getRecordingOverlaySupportWarning(
+  hostPlatform: NodeJS.Platform = process.platform,
+): string | undefined {
+  if (hostPlatform === 'darwin') {
+    return undefined;
+  }
+  return 'touch overlay burn-in is only available on macOS hosts; returning raw video plus gesture telemetry';
+}
+
 function getOverlayScriptPath(): string {
   overlayScriptPath ??= resolveScriptPath('recording-overlay.swift');
   return overlayScriptPath;
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 0735e6e5b..c8c313524 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -45,6 +45,7 @@ export type RunnerCommand = {
     | 'pinch'
     | 'recordStart'
     | 'recordStop'
+    | 'uptime'
     | 'shutdown';
   appBundleId?: string;
   text?: string;
diff --git a/src/platforms/ios/runner-errors.ts b/src/platforms/ios/runner-errors.ts
index ef7cd88d1..5d1bc4bd8 100644
--- a/src/platforms/ios/runner-errors.ts
+++ b/src/platforms/ios/runner-errors.ts
@@ -112,7 +112,8 @@ export function isReadOnlyRunnerCommand(command: RunnerCommand['command']): bool
     command === 'snapshot' ||
     command === 'screenshot' ||
     command === 'findText' ||
-    command === 'alert'
+    command === 'alert' ||
+    command === 'uptime'
   );
 }
 
diff --git a/src/utils/interactors.ts b/src/utils/interactors.ts
index ee16fb617..0418f6034 100644
--- a/src/utils/interactors.ts
+++ b/src/utils/interactors.ts
@@ -61,7 +61,7 @@ type Interactor = {
   focus(x: number, y: number): Promise<Record<string, unknown> | void>;
   type(text: string): Promise<void>;
   fill(x: number, y: number, text: string): Promise<Record<string, unknown> | void>;
-  scroll(direction: string, amount?: number): Promise<void>;
+  scroll(direction: string, amount?: number): Promise<Record<string, unknown> | void>;
   scrollIntoView(text: string): Promise<{ attempts?: number } | void>;
   screenshot(outPath: string, appBundleId?: string): Promise<void>;
   back(): Promise<void>;
@@ -253,11 +253,11 @@ function iosRunnerOverrides(
           throw new AppError('INVALID_ARGS', `Unknown direction: ${direction}`);
         }
         const inverted = invertScrollDirection(direction as 'up' | 'down' | 'left' | 'right');
-        await runIosRunnerCommand(
+        return (await runIosRunnerCommand(
           device,
           { command: 'swipe', direction: inverted, appBundleId: ctx.appBundleId },
           runnerOpts,
-        );
+        )) as Record<string, unknown>;
       },
       scrollIntoView: async (text) => {
         // Check once, then scroll in bursts to avoid slow find->swipe->find cadence on heavy screens.
diff --git a/src/utils/video.ts b/src/utils/video.ts
index 2a2a716ba..996f1bf83 100644
--- a/src/utils/video.ts
+++ b/src/utils/video.ts
@@ -144,6 +144,8 @@ function inspectTopLevelAtoms(filePath: string): string[] {
           atomSize = Number(extended.readBigUInt64BE(0));
         }
 
+        // A top-level MP4 atom size of 0 extends to EOF. We stop here because there is no
+        // next sibling atom to inspect, and advancing by 0 would loop forever.
         if (!Number.isFinite(atomSize) || atomSize <= 0) {
           break;
         }
diff --git a/test/integration/recording-overlay.test.ts b/test/integration/recording-overlay.test.ts
new file mode 100644
index 000000000..2cc1bb509
--- /dev/null
+++ b/test/integration/recording-overlay.test.ts
@@ -0,0 +1,272 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import {
+  analyzeOverlayCrop,
+  createIntegrationTestContext,
+  runCliJson,
+  runRecordingInspect,
+  type RecordingInspectionManifest,
+} from './test-helpers.ts';
+
+const recordingE2EEnabled = isTruthy(process.env.AGENT_DEVICE_RECORDING_E2E);
+
+test('recording tap overlay on iOS simulator', { skip: shouldSkipIosRecordingE2E() }, () => {
+  const integration = createRecordingIntegrationContext('ios', 'recording tap overlay');
+  const outPath = path.join(integration.artifactDir(), 'ios-tap.mp4');
+  const session = ['--session', 'recording-ios-tap'];
+
+  integration.runStep('open settings', [
+    'open',
+    'com.apple.Preferences',
+    '--platform',
+    'ios',
+    '--relaunch',
+    '--json',
+    ...session,
+  ]);
+  integration.runStep('record start', ['record', 'start', outPath, '--json', ...session]);
+  integration.runStep('tap general', [
+    'click',
+    'role=cell',
+    'label=General',
+    '--json',
+    ...session,
+  ]);
+  const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+
+  assertRecordingArtifacts(stop, outPath);
+  const manifest = inspectRecording(
+    outPath,
+    stop.json?.data?.telemetryPath,
+    integration.artifactDir(),
+    'ios-tap',
+  );
+  assertOverlayForKind(manifest, 'tap', { minPixelCount: 180, maxCenterDistance: 80 });
+});
+
+test('recording scroll overlay on iOS simulator', { skip: shouldSkipIosRecordingE2E() }, () => {
+  const integration = createRecordingIntegrationContext('ios', 'recording scroll overlay');
+  const outPath = path.join(integration.artifactDir(), 'ios-scroll.mp4');
+  const session = ['--session', 'recording-ios-scroll'];
+
+  integration.runStep('open settings', [
+    'open',
+    'com.apple.Preferences',
+    '--platform',
+    'ios',
+    '--relaunch',
+    '--json',
+    ...session,
+  ]);
+  integration.runStep('record start', ['record', 'start', outPath, '--json', ...session]);
+  integration.runStep('scroll down', ['scroll', 'down', '0.45', '--json', ...session]);
+  const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+
+  assertRecordingArtifacts(stop, outPath);
+  const manifest = inspectRecording(
+    outPath,
+    stop.json?.data?.telemetryPath,
+    integration.artifactDir(),
+    'ios-scroll',
+  );
+  assertOverlayForKind(manifest, 'scroll', { minPixelCount: 5 });
+});
+
+test('recording back-swipe overlay on iOS simulator', { skip: shouldSkipIosRecordingE2E() }, () => {
+  const integration = createRecordingIntegrationContext('ios', 'recording back swipe overlay');
+  const outPath = path.join(integration.artifactDir(), 'ios-back-swipe.mp4');
+  const session = ['--session', 'recording-ios-back-swipe'];
+
+  integration.runStep('open settings', [
+    'open',
+    'com.apple.Preferences',
+    '--platform',
+    'ios',
+    '--relaunch',
+    '--json',
+    ...session,
+  ]);
+  integration.runStep('record start', ['record', 'start', outPath, '--json', ...session]);
+  integration.runStep('open general', [
+    'press',
+    '201',
+    '319',
+    '--json',
+    ...session,
+  ]);
+  integration.runStep('edge swipe', [
+    'swipe',
+    '10',
+    '400',
+    '250',
+    '400',
+    '250',
+    '--json',
+    ...session,
+  ]);
+  const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+
+  assertRecordingArtifacts(stop, outPath);
+  const manifest = inspectRecording(
+    outPath,
+    stop.json?.data?.telemetryPath,
+    integration.artifactDir(),
+    'ios-back-swipe',
+  );
+  assertOverlayForKind(manifest, 'back-swipe', { minPixelCount: 80 });
+});
+
+test('recording tap overlay on Android emulator', { skip: shouldSkipAndroidRecordingE2E() }, () => {
+  const integration = createRecordingIntegrationContext('android', 'recording tap overlay');
+  const outPath = path.join(integration.artifactDir(), 'android-tap.mp4');
+  const session = ['--session', 'recording-android-tap'];
+
+  integration.runStep('open settings', [
+    'open',
+    'settings',
+    '--platform',
+    'android',
+    '--relaunch',
+    '--json',
+    ...session,
+  ]);
+  integration.runStep('record start', ['record', 'start', outPath, '--json', ...session]);
+  integration.runStep('tap apps', ['press', '672', '1362', '--json', ...session]);
+  integration.runStep('scroll down', ['scroll', 'down', '0.2', '--json', ...session]);
+  integration.runStep('settle', ['wait', '1200', '--json', ...session]);
+  const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+
+  assertRecordingArtifacts(stop, outPath);
+  const manifest = inspectRecording(
+    outPath,
+    stop.json?.data?.telemetryPath,
+    integration.artifactDir(),
+    'android-tap',
+  );
+  assertOverlayForKind(manifest, 'tap', { minPixelCount: 180, maxCenterDistance: 80 });
+});
+
+test(
+  'recording scroll overlay on Android emulator',
+  { skip: shouldSkipAndroidRecordingE2E() },
+  () => {
+    const integration = createRecordingIntegrationContext('android', 'recording scroll overlay');
+    const outPath = path.join(integration.artifactDir(), 'android-scroll.mp4');
+    const session = ['--session', 'recording-android-scroll'];
+
+    integration.runStep('open settings', [
+      'open',
+      'settings',
+      '--platform',
+      'android',
+      '--relaunch',
+      '--json',
+      ...session,
+    ]);
+    integration.runStep('record start', ['record', 'start', outPath, '--json', ...session]);
+    integration.runStep('scroll down', ['scroll', 'down', '0.45', '--json', ...session]);
+    integration.runStep('settle', ['wait', '1200', '--json', ...session]);
+    const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+
+    assertRecordingArtifacts(stop, outPath);
+    const manifest = inspectRecording(
+      outPath,
+      stop.json?.data?.telemetryPath,
+      integration.artifactDir(),
+      'android-scroll',
+    );
+    assertOverlayForKind(manifest, 'scroll', { minPixelCount: 5 });
+  },
+);
+
+function createRecordingIntegrationContext(platform: 'ios' | 'android', testName: string) {
+  const runId = new Date().toISOString().replaceAll(':', '-');
+  const stateDir = path.resolve('test/artifacts', platform, sanitize(testName), runId, 'state');
+  return createIntegrationTestContext({
+    platform,
+    testName,
+    extraEnv: { ...process.env, AGENT_DEVICE_STATE_DIR: stateDir },
+  });
+}
+
+function assertRecordingArtifacts(result: ReturnType<typeof runCliJson>, outPath: string): void {
+  assert.equal(result.status, 0, JSON.stringify(result.json ?? result.stderr));
+  assert.equal(result.json?.success, true);
+  assert.equal(typeof result.json?.data?.telemetryPath, 'string');
+  assert.ok(existsSync(outPath), `expected recording at ${outPath}`);
+  assert.ok(
+    existsSync(String(result.json?.data?.telemetryPath)),
+    `expected telemetry sidecar at ${String(result.json?.data?.telemetryPath)}`,
+  );
+  assert.equal(
+    result.json?.data?.artifacts?.some(
+      (artifact: { field?: string }) => artifact.field === 'telemetryPath',
+    ),
+    true,
+    'expected telemetryPath artifact in record stop response',
+  );
+}
+
+function inspectRecording(
+  outPath: string,
+  telemetryPath: string,
+  artifactDir: string,
+  prefix: string,
+): RecordingInspectionManifest {
+  return runRecordingInspect({
+    videoPath: outPath,
+    telemetryPath,
+    outputDir: path.join(artifactDir, `${prefix}-inspect`),
+  });
+}
+
+function assertOverlayForKind(
+  manifest: RecordingInspectionManifest,
+  kind: string,
+  options: { minPixelCount: number; maxCenterDistance?: number },
+): void {
+  const item = manifest.items.find((candidate) => candidate.kind === kind);
+  assert.ok(item, `expected manifest item for ${kind}`);
+  const analysis = analyzeOverlayCrop(item.cropPath);
+  assert.ok(
+    analysis.matchingPixelCount >= options.minPixelCount,
+    `expected at least ${options.minPixelCount} overlay-colored pixels in ${item.cropPath}, saw ${analysis.matchingPixelCount}`,
+  );
+  if (options.maxCenterDistance === undefined) {
+    return;
+  }
+  const centerX = analysis.width / 2;
+  const centerY = analysis.height / 2;
+  const distance = Math.hypot(analysis.centroidX - centerX, analysis.centroidY - centerY);
+  assert.ok(
+    distance <= options.maxCenterDistance,
+    `expected overlay centroid near crop center for ${item.cropPath}, distance=${distance.toFixed(2)}`,
+  );
+}
+
+function shouldSkipIosRecordingE2E(): string | false {
+  if (!recordingE2EEnabled)
+    return 'set AGENT_DEVICE_RECORDING_E2E=1 to run live recording overlay tests';
+  if (process.platform !== 'darwin') return 'iOS recording overlay E2E runs only on macOS';
+  return false;
+}
+
+function shouldSkipAndroidRecordingE2E(): string | false {
+  if (!recordingE2EEnabled)
+    return 'set AGENT_DEVICE_RECORDING_E2E=1 to run live recording overlay tests';
+  return false;
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
+}
+
+function sanitize(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-');
+}
diff --git a/test/integration/test-helpers.ts b/test/integration/test-helpers.ts
index 155fe0fe8..908a3b023 100644
--- a/test/integration/test-helpers.ts
+++ b/test/integration/test-helpers.ts
@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { PNG } from 'pngjs';
 import { runCmdSync } from '../../src/utils/exec.ts';
 
 export type CliJsonResult = {
@@ -31,17 +32,44 @@ type LastSnapshotState = {
 type IntegrationTestContextOptions = {
   platform: IntegrationPlatform;
   testName: string;
+  extraEnv?: NodeJS.ProcessEnv;
 };
 
 type AssertResultOptions = {
   detail?: string;
 };
 
-export function runCliJson(args: string[]): CliJsonResult {
+export type RecordingInspectionManifest = {
+  generatedAt: string;
+  inputPath: string;
+  items: Array<{
+    index: number;
+    kind: string;
+    sourceTimeMs: number;
+    sampleTimeMs: number;
+    expectedX: number;
+    expectedY: number;
+    fullFramePath: string;
+    cropPath: string;
+  }>;
+};
+
+export type OverlayCropAnalysis = {
+  matchingPixelCount: number;
+  centroidX: number;
+  centroidY: number;
+  width: number;
+  height: number;
+};
+
+export function runCliJson(args: string[], options?: { env?: NodeJS.ProcessEnv }): CliJsonResult {
   const result = runCmdSync(
     process.execPath,
     ['--experimental-strip-types', 'src/bin.ts', ...args],
-    { allowFailure: true },
+    {
+      allowFailure: true,
+      env: options?.env,
+    },
   );
   let json: any;
   try {
@@ -74,13 +102,13 @@ export function formatResultDebug(step: string, args: string[], result: CliJsonR
 }
 
 export function createIntegrationTestContext(options: IntegrationTestContextOptions) {
-  const { platform, testName } = options;
+  const { platform, testName, extraEnv } = options;
   const stepHistory: StepRecord[] = [];
   let lastSnapshot: LastSnapshotState | null = null;
   let artifactDir: string | null = null;
 
   function runStep(step: string, args: string[], expectedStatus = 0): CliJsonResult {
-    const result = runCliJson(args);
+    const result = runCliJson(args, { env: extraEnv });
     const errorCode =
       typeof result.json?.error?.code === 'string' ? (result.json.error.code as string) : undefined;
     const errorMessage =
@@ -249,9 +277,82 @@ export function createIntegrationTestContext(options: IntegrationTestContextOpti
   return {
     runStep,
     assertResult,
+    artifactDir: ensureArtifactDir,
+  };
+}
+
+export function runRecordingInspect(params: {
+  videoPath: string;
+  telemetryPath: string;
+  outputDir: string;
+}): RecordingInspectionManifest {
+  mkdirSync(params.outputDir, { recursive: true });
+  const scriptPath = path.resolve(
+    'ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift',
+  );
+  const result = runCmdSync(
+    'xcrun',
+    [
+      'swift',
+      scriptPath,
+      '--input',
+      params.videoPath,
+      '--events',
+      params.telemetryPath,
+      '--output-dir',
+      params.outputDir,
+    ],
+    { allowFailure: true },
+  );
+  assert.equal(result.exitCode, 0, result.stderr || result.stdout || 'recording inspect failed');
+  const manifestPath = path.join(params.outputDir, 'manifest.json');
+  return JSON.parse(readFileSync(manifestPath, 'utf8')) as RecordingInspectionManifest;
+}
+
+export function analyzeOverlayCrop(cropPath: string): OverlayCropAnalysis {
+  const png = PNG.sync.read(readFileSync(cropPath));
+  let matchingPixelCount = 0;
+  let sumX = 0;
+  let sumY = 0;
+  for (let y = 0; y < png.height; y += 1) {
+    for (let x = 0; x < png.width; x += 1) {
+      const offset = (png.width * y + x) * 4;
+      const r = png.data[offset] ?? 0;
+      const g = png.data[offset + 1] ?? 0;
+      const b = png.data[offset + 2] ?? 0;
+      const a = png.data[offset + 3] ?? 0;
+      if (!isOverlayBlue(r, g, b, a)) continue;
+      matchingPixelCount += 1;
+      sumX += x;
+      sumY += y;
+    }
+  }
+
+  return {
+    matchingPixelCount,
+    centroidX: matchingPixelCount > 0 ? sumX / matchingPixelCount : png.width / 2,
+    centroidY: matchingPixelCount > 0 ? sumY / matchingPixelCount : png.height / 2,
+    width: png.width,
+    height: png.height,
   };
 }
 
+function isOverlayBlue(r: number, g: number, b: number, a: number): boolean {
+  if (a <= 0) {
+    return false;
+  }
+  const maxChannel = Math.max(r, g, b);
+  const minChannel = Math.min(r, g, b);
+  return (
+    b >= 180 &&
+    g >= 160 &&
+    r <= 235 &&
+    b >= g &&
+    b - r >= 25 &&
+    maxChannel - minChannel >= 12
+  );
+}
+
 function sanitizeSegment(input: string): string {
   return input
     .trim()
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index b316a890f..0a2ac13c8 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -440,6 +440,10 @@ agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
 agent-device record stop                # Stop active recording
 ```
 
+- Recordings always produce a video artifact. When touch visualization is enabled, they also produce a gesture telemetry sidecar that can be used for post-processing or inspection.
+- Burned-in touch overlays are exported only on macOS hosts, because the overlay pipeline depends on Swift + AVFoundation helpers.
+- On Linux or other non-macOS hosts, `record stop` still succeeds and returns the raw video plus telemetry sidecar, and includes `overlayWarning` when burn-in overlays were skipped.
+
 **Session app logs (token-efficient debugging):** Logging is off by default in normal flows. Enable it on demand for debugging. Logs are written to a file so agents can grep instead of loading full output into context.
 
 ```bash

From 88ad09dd7e8e42d859ad3d32160175e8a7478466 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 23 Mar 2026 15:02:13 +0100
Subject: [PATCH 09/11] refactor: split touch interaction recording flow

---
 .../RecordingScripts/recording-overlay.swift  | 237 +++---
 src/daemon/handlers/interaction-touch.ts      | 695 ++++++++++++++++++
 src/daemon/handlers/record-trace-android.ts   |   2 +-
 src/daemon/handlers/record-trace-ios.ts       |   2 +-
 src/daemon/handlers/record-trace-recording.ts |  13 +-
 src/daemon/recording-gestures.ts              |   6 +-
 src/daemon/recording-timing.ts                |   3 +
 .../ios/__tests__/recording-scripts.test.ts   |   2 +-
 .../overlay.ts}                               |  11 +-
 9 files changed, 833 insertions(+), 138 deletions(-)
 create mode 100644 src/daemon/handlers/interaction-touch.ts
 rename src/{platforms/ios/recording-overlay.ts => recording/overlay.ts} (93%)

diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
index e7c087417..984bbdb91 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -9,6 +9,7 @@ let minimumTapVisibility: CFTimeInterval = 0.45
 let minimumSwipeVisibility: CFTimeInterval = 0.5
 let minimumPinchVisibility: CFTimeInterval = 0.5
 let swipeVisibilityTail: CFTimeInterval = 0.16
+let trailOpacityKeyTimes: [NSNumber] = [0.0, 0.08, 0.62, 1.0]
 
 struct GestureEnvelope: Decodable {
   let events: [GestureEvent]
@@ -249,12 +250,11 @@ func addTapLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer: CALay
   scale.values = [0.84, 1.0, 1.0]
   scale.keyTimes = [0.0, 0.22, 1.0]
 
-  let group = CAAnimationGroup()
-  group.animations = [opacity, scale]
-  group.duration = minimumTapVisibility
-  group.beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
-  group.fillMode = .both
-  group.isRemovedOnCompletion = false
+  let group = makeAnimationGroup(
+    animations: [opacity, scale],
+    duration: minimumTapVisibility,
+    beginTime: AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  )
   layer.add(group, forKey: "tap")
 }
 
@@ -274,12 +274,11 @@ func addLongPressLayer(event: GestureEvent, renderSize: CGSize, to overlayLayer:
   scale.values = [0.84, 1.0, 1.0]
   scale.keyTimes = [0.0, 0.15, 1.0]
 
-  let group = CAAnimationGroup()
-  group.animations = [opacity, scale]
-  group.duration = duration
-  group.beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
-  group.fillMode = .both
-  group.isRemovedOnCompletion = false
+  let group = makeAnimationGroup(
+    animations: [opacity, scale],
+    duration: duration,
+    beginTime: AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  )
   layer.add(group, forKey: "longpress")
 }
 
@@ -301,6 +300,88 @@ enum TrailStyle: Equatable {
   case backSwipe
 }
 
+extension TrailStyle {
+  var tail: CFTimeInterval {
+    switch self {
+    case .swipe:
+      return swipeVisibilityTail
+    case .scroll:
+      return 0.08
+    case .backSwipe:
+      return 0.12
+    }
+  }
+
+  var lineWidth: CGFloat {
+    switch self {
+    case .swipe:
+      return 4
+    case .scroll:
+      return 5
+    case .backSwipe:
+      return 6
+    }
+  }
+
+  var color: CGColor {
+    switch self {
+    case .swipe:
+      return touchDotColor
+    case .scroll:
+      return NSColor(calibratedRed: 0.16, green: 0.74, blue: 0.88, alpha: 0.34).cgColor
+    case .backSwipe:
+      return NSColor(calibratedRed: 0.24, green: 0.69, blue: 1.0, alpha: 0.55).cgColor
+    }
+  }
+
+  var borderColor: CGColor {
+    switch self {
+    case .swipe:
+      return touchDotBorderColor
+    case .scroll:
+      return NSColor(calibratedRed: 0.92, green: 1.0, blue: 1.0, alpha: 0.48).cgColor
+    case .backSwipe:
+      return NSColor(calibratedRed: 0.94, green: 0.98, blue: 1.0, alpha: 0.8).cgColor
+    }
+  }
+
+  var trailOpacityValues: [NSNumber] {
+    switch self {
+    case .swipe:
+      return [0.0, 0.9, 0.35, 0.0]
+    case .scroll:
+      return [0.0, 0.5, 0.18, 0.0]
+    case .backSwipe:
+      return [0.0, 1.0, 0.45, 0.0]
+    }
+  }
+
+  var dotOpacityValues: [NSNumber] {
+    switch self {
+    case .swipe:
+      return [0.0, 1.0, 0.92, 0.0]
+    case .scroll:
+      return [0.0, 0.72, 0.4, 0.0]
+    case .backSwipe:
+      return [0.0, 1.0, 0.9, 0.0]
+    }
+  }
+}
+
+func makeAnimationGroup(
+  animations: [CAAnimation],
+  duration: CFTimeInterval,
+  beginTime: CFTimeInterval
+) -> CAAnimationGroup {
+  let group = CAAnimationGroup()
+  group.animations = animations
+  group.duration = duration
+  group.beginTime = beginTime
+  group.fillMode = .both
+  group.isRemovedOnCompletion = false
+  return group
+}
+
 func addTrailLayers(
   event: GestureEvent,
   renderSize: CGSize,
@@ -311,7 +392,7 @@ func addTrailLayers(
   let startPoint = overlayPoint(event: event, x: event.x, y: event.y, renderSize: renderSize)
   let endPoint = overlayPoint(event: event, x: x2, y: y2, renderSize: renderSize)
   let duration = max(0.1, (event.durationMs ?? 250) / 1000.0)
-  let visibleDuration = max(minimumSwipeVisibility, duration + trailTail(style: style))
+  let visibleDuration = max(minimumSwipeVisibility, duration + style.tail)
   let beginTime = AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
 
   let pathLayer = CAShapeLayer()
@@ -323,8 +404,8 @@ func addTrailLayers(
     path.addLine(to: endPoint)
     return path
   }()
-  pathLayer.strokeColor = trailColor(style: style)
-  pathLayer.lineWidth = trailLineWidth(style: style)
+  pathLayer.strokeColor = style.color
+  pathLayer.lineWidth = style.lineWidth
   pathLayer.lineCap = .round
   pathLayer.fillColor = nil
   pathLayer.opacity = 0
@@ -335,21 +416,20 @@ func addTrailLayers(
   stroke.toValue = 1.0
 
   let strokeOpacity = CAKeyframeAnimation(keyPath: "opacity")
-  strokeOpacity.values = trailOpacityValues(style: style)
-  strokeOpacity.keyTimes = trailOpacityKeyTimes()
+  strokeOpacity.values = style.trailOpacityValues
+  strokeOpacity.keyTimes = trailOpacityKeyTimes
 
-  let strokeGroup = CAAnimationGroup()
-  strokeGroup.animations = [stroke, strokeOpacity]
-  strokeGroup.duration = visibleDuration
-  strokeGroup.beginTime = beginTime
+  let strokeGroup = makeAnimationGroup(
+    animations: [stroke, strokeOpacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
   strokeGroup.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
-  strokeGroup.fillMode = .both
-  strokeGroup.isRemovedOnCompletion = false
   pathLayer.add(strokeGroup, forKey: "stroke")
 
   let dotLayer = makeTouchDotLayer(center: startPoint, renderSize: renderSize)
-  dotLayer.backgroundColor = trailColor(style: style)
-  dotLayer.borderColor = trailBorderColor(style: style)
+  dotLayer.backgroundColor = style.color
+  dotLayer.borderColor = style.borderColor
   dotLayer.position = endPoint
   overlayLayer.addSublayer(dotLayer)
 
@@ -359,16 +439,15 @@ func addTrailLayers(
   position.duration = duration
 
   let opacity = CAKeyframeAnimation(keyPath: "opacity")
-  opacity.values = dotOpacityValues(style: style)
-  opacity.keyTimes = trailOpacityKeyTimes()
+  opacity.values = style.dotOpacityValues
+  opacity.keyTimes = trailOpacityKeyTimes
 
-  let group = CAAnimationGroup()
-  group.animations = [position, opacity]
-  group.duration = visibleDuration
-  group.beginTime = beginTime
+  let group = makeAnimationGroup(
+    animations: [position, opacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
   group.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
-  group.fillMode = .both
-  group.isRemovedOnCompletion = false
   dotLayer.add(group, forKey: "swipe-dot")
 
   if style == .backSwipe {
@@ -402,12 +481,11 @@ func addPinchDot(
   opacity.values = [0.0, 1.0, 1.0, 0.0]
   opacity.keyTimes = [0.0, 0.1, 0.82, 1.0]
 
-  let group = CAAnimationGroup()
-  group.animations = [position, opacity]
-  group.duration = duration
-  group.beginTime = beginTime
-  group.fillMode = .both
-  group.isRemovedOnCompletion = false
+  let group = makeAnimationGroup(
+    animations: [position, opacity],
+    duration: duration,
+    beginTime: beginTime
+  )
   dotLayer.add(group, forKey: "pinch")
 }
 
@@ -461,76 +539,6 @@ func resolvedTouchDotRadius(renderSize: CGSize) -> CGFloat {
   return max(18, min(40, minDimension * 0.035))
 }
 
-func trailTail(style: TrailStyle) -> CFTimeInterval {
-  switch style {
-  case .swipe:
-    return swipeVisibilityTail
-  case .scroll:
-    return 0.08
-  case .backSwipe:
-    return 0.12
-  }
-}
-
-func trailLineWidth(style: TrailStyle) -> CGFloat {
-  switch style {
-  case .swipe:
-    return 4
-  case .scroll:
-    return 5
-  case .backSwipe:
-    return 6
-  }
-}
-
-func trailColor(style: TrailStyle) -> CGColor {
-  switch style {
-  case .swipe:
-    return touchDotColor
-  case .scroll:
-    return NSColor(calibratedRed: 0.16, green: 0.74, blue: 0.88, alpha: 0.34).cgColor
-  case .backSwipe:
-    return NSColor(calibratedRed: 0.24, green: 0.69, blue: 1.0, alpha: 0.55).cgColor
-  }
-}
-
-func trailBorderColor(style: TrailStyle) -> CGColor {
-  switch style {
-  case .swipe:
-    return touchDotBorderColor
-  case .scroll:
-    return NSColor(calibratedRed: 0.92, green: 1.0, blue: 1.0, alpha: 0.48).cgColor
-  case .backSwipe:
-    return NSColor(calibratedRed: 0.94, green: 0.98, blue: 1.0, alpha: 0.8).cgColor
-  }
-}
-
-func trailOpacityValues(style: TrailStyle) -> [NSNumber] {
-  switch style {
-  case .swipe:
-    return [0.0, 0.9, 0.35, 0.0]
-  case .scroll:
-    return [0.0, 0.5, 0.18, 0.0]
-  case .backSwipe:
-    return [0.0, 1.0, 0.45, 0.0]
-  }
-}
-
-func dotOpacityValues(style: TrailStyle) -> [NSNumber] {
-  switch style {
-  case .swipe:
-    return [0.0, 1.0, 0.92, 0.0]
-  case .scroll:
-    return [0.0, 0.72, 0.4, 0.0]
-  case .backSwipe:
-    return [0.0, 1.0, 0.9, 0.0]
-  }
-}
-
-func trailOpacityKeyTimes() -> [NSNumber] {
-  return [0.0, 0.08, 0.62, 1.0]
-}
-
 func addBackSwipeEdgeHint(
   event: GestureEvent,
   renderSize: CGSize,
@@ -554,11 +562,10 @@ func addBackSwipeEdgeHint(
   opacity.values = [0.0, 0.9, 0.0]
   opacity.keyTimes = [0.0, 0.2, 1.0]
 
-  let group = CAAnimationGroup()
-  group.animations = [opacity]
-  group.duration = visibleDuration
-  group.beginTime = beginTime
-  group.fillMode = .both
-  group.isRemovedOnCompletion = false
+  let group = makeAnimationGroup(
+    animations: [opacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
   hintLayer.add(group, forKey: "back-swipe-edge")
 }
diff --git a/src/daemon/handlers/interaction-touch.ts b/src/daemon/handlers/interaction-touch.ts
new file mode 100644
index 000000000..c7d901e28
--- /dev/null
+++ b/src/daemon/handlers/interaction-touch.ts
@@ -0,0 +1,695 @@
+import { dispatchCommand, type CommandFlags } from '../../core/dispatch.ts';
+import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { centerOfRect, findNodeByRef, type Rect, type SnapshotNode } from '../../utils/snapshot.ts';
+import type { DaemonCommandContext } from '../context.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
+import { SessionStore } from '../session-store.ts';
+import { findNodeByLabel, isFillableType, resolveRefLabel } from '../snapshot-processing.ts';
+import {
+  buildSelectorChainForNode,
+  formatSelectorFailure,
+  parseSelectorChain,
+  resolveSelectorChain,
+  splitSelectorFromArgs,
+} from '../selectors.ts';
+import { withDiagnosticTimer } from '../../utils/diagnostics.ts';
+import { recordTouchVisualizationEvent } from '../recording-gestures.ts';
+import { getAndroidScreenSize } from '../../platforms/android/index.ts';
+import { getSnapshotReferenceFrame } from '../touch-reference-frame.ts';
+
+type ContextFromFlags = (
+  flags: CommandFlags | undefined,
+  appBundleId?: string,
+  traceLogPath?: string,
+) => DaemonCommandContext;
+
+type CaptureSnapshotForSession = (
+  session: SessionState,
+  flags: CommandFlags | undefined,
+  sessionStore: SessionStore,
+  contextFromFlags: ContextFromFlags,
+  options: { interactiveOnly: boolean },
+  dispatch?: typeof dispatchCommand,
+) => Promise<{
+  nodes: SnapshotNode[];
+  truncated?: boolean;
+  createdAt: number;
+  backend?: 'xctest' | 'android';
+}>;
+
+type ResolveRefTarget =
+  | ((params: {
+      session: SessionState;
+      refInput: string;
+      fallbackLabel: string;
+      requireRect: boolean;
+      invalidRefMessage: string;
+      notFoundMessage: string;
+    }) =>
+      | { ok: true; target: { ref: string; node: SnapshotNode; snapshotNodes: SnapshotNode[] } }
+      | { ok: false; response: DaemonResponse })
+  | undefined;
+
+type RefSnapshotFlagGuardResponse = (
+  command: 'press' | 'fill' | 'get' | 'scrollintoview',
+  flags: CommandFlags | undefined,
+) => DaemonResponse | null;
+
+export async function handleTouchInteractionCommands(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  sessionStore: SessionStore;
+  contextFromFlags: ContextFromFlags;
+  dispatch?: typeof dispatchCommand;
+  readAndroidScreenSize?: typeof getAndroidScreenSize;
+  captureSnapshotForSession: CaptureSnapshotForSession;
+  resolveRefTarget: NonNullable<ResolveRefTarget>;
+  refSnapshotFlagGuardResponse: RefSnapshotFlagGuardResponse;
+}): Promise<DaemonResponse | null> {
+  const {
+    req,
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    captureSnapshotForSession,
+    resolveRefTarget,
+    refSnapshotFlagGuardResponse,
+  } = params;
+  const dispatch = params.dispatch ?? dispatchCommand;
+  const readAndroidScreenSize = params.readAndroidScreenSize ?? getAndroidScreenSize;
+  const command = req.command;
+
+  if (command === 'press') {
+    const session = sessionStore.get(sessionName);
+    if (!session) {
+      return {
+        ok: false,
+        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+      };
+    }
+    if (!isCommandSupportedOnDevice('press', session.device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'press is not supported on this device' },
+      };
+    }
+    const directCoordinates = parseCoordinateTarget(req.positionals ?? []);
+    if (directCoordinates) {
+      const interaction = await dispatchInteractionCommand({
+        session,
+        flags: req.flags,
+        contextFromFlags,
+        dispatch,
+        command: 'press',
+        positionals: [String(directCoordinates.x), String(directCoordinates.y)],
+        outPath: req.flags?.out,
+      });
+      const visualizationFrame = await resolveDirectTouchReferenceFrame({
+        session,
+        flags: req.flags,
+        sessionStore,
+        contextFromFlags,
+        captureSnapshotForSession,
+        dispatch,
+        readAndroidScreenSize,
+      });
+      const visualizationResult = {
+        ...(interaction.data ?? { x: directCoordinates.x, y: directCoordinates.y }),
+        ...(visualizationFrame ?? {}),
+      };
+      return finalizeTouchInteraction({
+        session,
+        sessionStore,
+        command,
+        positionals: req.positionals ?? [String(directCoordinates.x), String(directCoordinates.y)],
+        flags: req.flags,
+        result: visualizationResult,
+        responseData: visualizationResult,
+        actionStartedAt: interaction.actionStartedAt,
+        actionFinishedAt: interaction.actionFinishedAt,
+      });
+    }
+
+    const selectorAction = 'click';
+    const refInput = req.positionals?.[0] ?? '';
+    if (refInput.startsWith('@')) {
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('press', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
+      const fallbackLabel =
+        req.positionals.length > 1 ? req.positionals.slice(1).join(' ').trim() : '';
+      const resolvedRefTarget = resolveRefTarget({
+        session,
+        refInput,
+        fallbackLabel,
+        requireRect: true,
+        invalidRefMessage: `${command} requires a ref like @e2`,
+        notFoundMessage: `Ref ${refInput} not found or has no bounds`,
+      });
+      if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
+      const { ref } = resolvedRefTarget.target;
+      let node = resolvedRefTarget.target.node;
+      let snapshotNodes = resolvedRefTarget.target.snapshotNodes;
+      let pressPoint = resolveRectCenter(node.rect);
+      if (!pressPoint) {
+        const refreshed = await captureSnapshotForSession(
+          session,
+          req.flags,
+          sessionStore,
+          contextFromFlags,
+          { interactiveOnly: true },
+          dispatch,
+        );
+        const refNode = findNodeByRef(refreshed.nodes, ref);
+        const fallbackNode =
+          fallbackLabel.length > 0 ? findNodeByLabel(refreshed.nodes, fallbackLabel) : null;
+        const fallbackNodePoint = resolveRectCenter(fallbackNode?.rect);
+        const refNodePoint = resolveRectCenter(refNode?.rect);
+        const refreshedNode = refNodePoint
+          ? refNode
+          : fallbackNodePoint
+            ? fallbackNode
+            : (refNode ?? fallbackNode);
+        const refreshedPoint = resolveRectCenter(refreshedNode?.rect);
+        if (refreshedNode && refreshedPoint) {
+          node = refreshedNode;
+          snapshotNodes = refreshed.nodes;
+          pressPoint = refreshedPoint;
+        }
+      }
+      if (!pressPoint) {
+        return {
+          ok: false,
+          error: {
+            code: 'COMMAND_FAILED',
+            message: `Ref ${refInput} not found or has invalid bounds`,
+          },
+        };
+      }
+      const refLabel = resolveRefLabel(node, snapshotNodes);
+      const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+        action: selectorAction,
+      });
+      const { x, y } = pressPoint;
+      const interaction = await dispatchInteractionCommand({
+        session,
+        flags: req.flags,
+        contextFromFlags,
+        dispatch,
+        command: 'press',
+        positionals: [String(x), String(y)],
+        outPath: req.flags?.out,
+      });
+      const resultPayload = buildTouchVisualizationResult({
+        data: interaction.data,
+        fallbackX: x,
+        fallbackY: y,
+        referenceFrame: readSnapshotNodesReferenceFrame(snapshotNodes),
+        extra: {
+          ref,
+          refLabel,
+          selectorChain,
+        },
+      });
+      return finalizeTouchInteraction({
+        session,
+        sessionStore,
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags,
+        result: resultPayload,
+        responseData: resultPayload,
+        actionStartedAt: interaction.actionStartedAt,
+        actionFinishedAt: interaction.actionFinishedAt,
+      });
+    }
+
+    const selectorExpression = (req.positionals ?? []).join(' ').trim();
+    if (!selectorExpression) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: `${command} requires @ref, selector expression, or x y coordinates`,
+        },
+      };
+    }
+    const chain = parseSelectorChain(selectorExpression);
+    const snapshot = await captureSnapshotForSession(
+      session,
+      req.flags,
+      sessionStore,
+      contextFromFlags,
+      { interactiveOnly: true },
+      dispatch,
+    );
+    const resolved = await withDiagnosticTimer(
+      'selector_resolve',
+      () =>
+        resolveSelectorChain(snapshot.nodes, chain, {
+          platform: session.device.platform,
+          requireRect: true,
+          requireUnique: true,
+          disambiguateAmbiguous: true,
+        }),
+      { command },
+    );
+    if (!resolved || !resolved.node.rect) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: formatSelectorFailure(chain, resolved?.diagnostics ?? [], { unique: true }),
+        },
+      };
+    }
+    const pressPoint = resolveRectCenter(resolved.node.rect);
+    if (!pressPoint) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `Selector ${resolved.selector.raw} resolved to invalid bounds`,
+        },
+      };
+    }
+    const { x, y } = pressPoint;
+    const interaction = await dispatchInteractionCommand({
+      session,
+      flags: req.flags,
+      contextFromFlags,
+      dispatch,
+      command: 'press',
+      positionals: [String(x), String(y)],
+      outPath: req.flags?.out,
+    });
+    const selectorChain = buildSelectorChainForNode(resolved.node, session.device.platform, {
+      action: selectorAction,
+    });
+    const refLabel = resolveRefLabel(resolved.node, snapshot.nodes);
+    const resultPayload = buildTouchVisualizationResult({
+      data: interaction.data,
+      fallbackX: x,
+      fallbackY: y,
+      referenceFrame: readSnapshotNodesReferenceFrame(snapshot.nodes),
+      extra: {
+        selector: resolved.selector.raw,
+        selectorChain,
+        refLabel,
+      },
+    });
+    return finalizeTouchInteraction({
+      session,
+      sessionStore,
+      command,
+      positionals: req.positionals ?? [],
+      flags: req.flags,
+      result: resultPayload,
+      responseData: resultPayload,
+      actionStartedAt: interaction.actionStartedAt,
+      actionFinishedAt: interaction.actionFinishedAt,
+    });
+  }
+
+  if (command === 'fill') {
+    const session = sessionStore.get(sessionName);
+    if (session && !isCommandSupportedOnDevice('fill', session.device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'fill is not supported on this device' },
+      };
+    }
+    if (req.positionals?.[0]?.startsWith('@')) {
+      if (!session) {
+        return {
+          ok: false,
+          error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+        };
+      }
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('fill', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
+      const labelCandidate = req.positionals.length >= 3 ? req.positionals[1] : '';
+      const text =
+        req.positionals.length >= 3
+          ? req.positionals.slice(2).join(' ')
+          : req.positionals.slice(1).join(' ');
+      if (!text) {
+        return {
+          ok: false,
+          error: { code: 'INVALID_ARGS', message: 'fill requires text after ref' },
+        };
+      }
+
+      const resolvedRefTarget = resolveRefTarget({
+        session,
+        refInput: req.positionals[0],
+        fallbackLabel: labelCandidate,
+        requireRect: true,
+        invalidRefMessage: 'fill requires a ref like @e2',
+        notFoundMessage: `Ref ${req.positionals[0]} not found or has no bounds`,
+      });
+      if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
+      const { ref, node, snapshotNodes } = resolvedRefTarget.target;
+      if (!node.rect) {
+        return {
+          ok: false,
+          error: {
+            code: 'COMMAND_FAILED',
+            message: `Ref ${req.positionals[0]} not found or has no bounds`,
+          },
+        };
+      }
+      const nodeType = node.type ?? '';
+      const fillWarning =
+        nodeType && !isFillableType(nodeType, session.device.platform)
+          ? `fill target ${req.positionals[0]} resolved to "${nodeType}", attempting fill anyway.`
+          : undefined;
+      const refLabel = resolveRefLabel(node, snapshotNodes);
+      const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+        action: 'fill',
+      });
+      const { x, y } = centerOfRect(node.rect);
+      const interaction = await dispatchInteractionCommand({
+        session,
+        flags: req.flags,
+        contextFromFlags,
+        dispatch,
+        command: 'fill',
+        positionals: [String(x), String(y), text],
+        outPath: req.flags?.out,
+      });
+      const resultPayload: Record<string, unknown> = {
+        ...(interaction.data ?? { ref, x, y }),
+      };
+      if (fillWarning) {
+        resultPayload.warning = fillWarning;
+      }
+      return finalizeTouchInteraction({
+        session,
+        sessionStore,
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags,
+        result: {
+          ...resultPayload,
+          refLabel,
+          selectorChain,
+        },
+        responseData: resultPayload,
+        actionStartedAt: interaction.actionStartedAt,
+        actionFinishedAt: interaction.actionFinishedAt,
+      });
+    }
+    if (!session) {
+      return {
+        ok: false,
+        error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
+      };
+    }
+    const selectorArgs = splitSelectorFromArgs(req.positionals ?? [], {
+      preferTrailingValue: true,
+    });
+    if (selectorArgs) {
+      if (selectorArgs.rest.length === 0) {
+        return {
+          ok: false,
+          error: { code: 'INVALID_ARGS', message: 'fill requires text after selector' },
+        };
+      }
+      const text = selectorArgs.rest.join(' ').trim();
+      if (!text) {
+        return {
+          ok: false,
+          error: { code: 'INVALID_ARGS', message: 'fill requires text after selector' },
+        };
+      }
+      const chain = parseSelectorChain(selectorArgs.selectorExpression);
+      const snapshot = await captureSnapshotForSession(
+        session,
+        req.flags,
+        sessionStore,
+        contextFromFlags,
+        { interactiveOnly: true },
+        dispatch,
+      );
+      const resolved = await withDiagnosticTimer(
+        'selector_resolve',
+        () =>
+          resolveSelectorChain(snapshot.nodes, chain, {
+            platform: session.device.platform,
+            requireRect: true,
+            requireUnique: true,
+            disambiguateAmbiguous: true,
+          }),
+        { command },
+      );
+      if (!resolved || !resolved.node.rect) {
+        return {
+          ok: false,
+          error: {
+            code: 'COMMAND_FAILED',
+            message: formatSelectorFailure(chain, resolved?.diagnostics ?? [], { unique: true }),
+          },
+        };
+      }
+      const node = resolved.node;
+      const nodeType = node.type ?? '';
+      const fillWarning =
+        nodeType && !isFillableType(nodeType, session.device.platform)
+          ? `fill target ${resolved.selector.raw} resolved to "${nodeType}", attempting fill anyway.`
+          : undefined;
+      const { x, y } = centerOfRect(resolved.node.rect);
+      const interaction = await dispatchInteractionCommand({
+        session,
+        flags: req.flags,
+        contextFromFlags,
+        dispatch,
+        command: 'fill',
+        positionals: [String(x), String(y), text],
+        outPath: req.flags?.out,
+      });
+      const selectorChain = buildSelectorChainForNode(node, session.device.platform, {
+        action: 'fill',
+      });
+      const resultPayload = buildTouchVisualizationResult({
+        data: interaction.data,
+        fallbackX: x,
+        fallbackY: y,
+        referenceFrame: readSnapshotNodesReferenceFrame(snapshot.nodes),
+        extra: {
+          text,
+          selector: resolved.selector.raw,
+          selectorChain,
+          refLabel: resolveRefLabel(node, snapshot.nodes),
+        },
+      });
+      if (fillWarning) {
+        resultPayload.warning = fillWarning;
+      }
+      return finalizeTouchInteraction({
+        session,
+        sessionStore,
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags,
+        result: resultPayload,
+        responseData: resultPayload,
+        actionStartedAt: interaction.actionStartedAt,
+        actionFinishedAt: interaction.actionFinishedAt,
+      });
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_ARGS',
+        message: 'fill requires x y text, @ref text, or selector text',
+      },
+    };
+  }
+
+  return null;
+}
+
+function parseCoordinateTarget(positionals: string[]): { x: number; y: number } | null {
+  if (positionals.length < 2) return null;
+  const x = Number(positionals[0]);
+  const y = Number(positionals[1]);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { x, y };
+}
+
+async function resolveDirectTouchReferenceFrame(params: {
+  session: SessionState;
+  flags: CommandFlags | undefined;
+  sessionStore: SessionStore;
+  contextFromFlags: ContextFromFlags;
+  captureSnapshotForSession: CaptureSnapshotForSession;
+  dispatch: typeof dispatchCommand;
+  readAndroidScreenSize: typeof getAndroidScreenSize;
+}): Promise<{ referenceWidth: number; referenceHeight: number } | undefined> {
+  const {
+    session,
+    flags,
+    sessionStore,
+    contextFromFlags,
+    captureSnapshotForSession,
+    dispatch,
+    readAndroidScreenSize,
+  } = params;
+  if (session.recording?.touchReferenceFrame) {
+    return session.recording.touchReferenceFrame;
+  }
+
+  if (session.device.platform === 'android') {
+    const size = await readAndroidScreenSize(session.device);
+    const referenceFrame = {
+      referenceWidth: size.width,
+      referenceHeight: size.height,
+    };
+    if (session.recording) {
+      session.recording.touchReferenceFrame = referenceFrame;
+    }
+    return referenceFrame;
+  }
+
+  const snapshotFrame = getSnapshotReferenceFrame(session.snapshot);
+  if (snapshotFrame) {
+    if (session.recording) {
+      session.recording.touchReferenceFrame = snapshotFrame;
+    }
+    return snapshotFrame;
+  }
+
+  if (!session.recording) {
+    return undefined;
+  }
+
+  const snapshot = await captureSnapshotForSession(
+    session,
+    flags,
+    sessionStore,
+    contextFromFlags,
+    { interactiveOnly: true },
+    dispatch,
+  );
+  const referenceFrame = getSnapshotReferenceFrame(snapshot);
+  if (referenceFrame && session.recording) {
+    session.recording.touchReferenceFrame = referenceFrame;
+  }
+  return referenceFrame;
+}
+
+function readSnapshotNodesReferenceFrame(
+  nodes: SnapshotNode[],
+): { referenceWidth: number; referenceHeight: number } | undefined {
+  return getSnapshotReferenceFrame({
+    nodes,
+    createdAt: 0,
+  });
+}
+
+function buildTouchVisualizationResult(params: {
+  data: Record<string, unknown> | undefined;
+  fallbackX: number;
+  fallbackY: number;
+  referenceFrame?: { referenceWidth: number; referenceHeight: number };
+  extra?: Record<string, unknown>;
+}): Record<string, unknown> {
+  const { data, fallbackX, fallbackY, referenceFrame, extra } = params;
+  return {
+    x: fallbackX,
+    y: fallbackY,
+    ...(referenceFrame ?? {}),
+    ...(extra ?? {}),
+    ...(data ?? {}),
+  };
+}
+
+async function dispatchInteractionCommand(params: {
+  session: SessionState;
+  flags: CommandFlags | undefined;
+  contextFromFlags: ContextFromFlags;
+  dispatch: typeof dispatchCommand;
+  command: string;
+  positionals: string[];
+  outPath: string | undefined;
+}): Promise<{
+  data: Record<string, unknown> | undefined;
+  actionStartedAt: number;
+  actionFinishedAt: number;
+}> {
+  const { session, flags, contextFromFlags, dispatch, command, positionals, outPath } = params;
+  const actionStartedAt = Date.now();
+  const dispatchContext = {
+    ...contextFromFlags(flags, session.appBundleId, session.trace?.outPath),
+  };
+  const rawData = await dispatch(session.device, command, positionals, outPath, dispatchContext);
+  const actionFinishedAt = Date.now();
+  const data = rawData && typeof rawData === 'object' ? rawData : undefined;
+  return { data, actionStartedAt, actionFinishedAt };
+}
+
+function finalizeTouchInteraction(params: {
+  session: SessionState;
+  sessionStore: SessionStore;
+  command: string;
+  positionals: string[];
+  flags: CommandFlags | undefined;
+  result: Record<string, unknown>;
+  responseData: Record<string, unknown>;
+  actionStartedAt: number;
+  actionFinishedAt: number;
+}): DaemonResponse {
+  const {
+    session,
+    sessionStore,
+    command,
+    positionals,
+    flags,
+    result,
+    responseData,
+    actionStartedAt,
+    actionFinishedAt,
+  } = params;
+  sessionStore.recordAction(session, {
+    command,
+    positionals,
+    flags: flags ?? {},
+    result,
+  });
+  recordTouchVisualizationEvent(
+    session,
+    command,
+    positionals,
+    result,
+    (flags ?? {}) as Record<string, unknown>,
+    actionStartedAt,
+    actionFinishedAt,
+  );
+  return { ok: true, data: responseData };
+}
+
+function resolveRectCenter(rect: Rect | undefined): { x: number; y: number } | null {
+  const normalized = normalizeRect(rect);
+  if (!normalized) return null;
+  const center = centerOfRect(normalized);
+  if (!Number.isFinite(center.x) || !Number.isFinite(center.y)) return null;
+  return center;
+}
+
+function normalizeRect(rect: Rect | undefined): Rect | null {
+  if (!rect) return null;
+  const x = Number(rect.x);
+  const y = Number(rect.y);
+  const width = Number(rect.width);
+  const height = Number(rect.height);
+  if (
+    !Number.isFinite(x) ||
+    !Number.isFinite(y) ||
+    !Number.isFinite(width) ||
+    !Number.isFinite(height)
+  ) {
+    return null;
+  }
+  if (width < 0 || height < 0) return null;
+  return { x, y, width, height };
+}
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 792787016..18e6a7aff 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
-import { getRecordingOverlaySupportWarning } from '../../platforms/ios/recording-overlay.ts';
+import { getRecordingOverlaySupportWarning } from '../../recording/overlay.ts';
 import type { DaemonResponse, SessionState } from '../types.ts';
 import { persistRecordingTelemetry } from '../recording-telemetry.ts';
 import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
index f9253e959..d703e5ecb 100644
--- a/src/daemon/handlers/record-trace-ios.ts
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -3,7 +3,7 @@ import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { persistRecordingTelemetry } from '../recording-telemetry.ts';
 import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../platforms/ios/runner-client.ts';
-import { getRecordingOverlaySupportWarning } from '../../platforms/ios/recording-overlay.ts';
+import { getRecordingOverlaySupportWarning } from '../../recording/overlay.ts';
 import { formatRecordTraceError } from '../record-trace-errors.ts';
 import type { RecordTraceDeps, RecordingBase } from './record-trace-recording.ts';
 
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 2318ff111..9b3509759 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -23,9 +23,9 @@ import {
   getRecordingOverlaySupportWarning,
   overlayRecordingTouches,
   trimRecordingStart,
-} from '../../platforms/ios/recording-overlay.ts';
+} from '../../recording/overlay.ts';
 import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
-import { formatRecordTraceExecFailure } from '../record-trace-errors.ts';
+import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import { startAndroidRecording, stopAndroidRecording } from './record-trace-android.ts';
 import {
   normalizeAppBundleId,
@@ -298,7 +298,7 @@ async function stopNonRunnerRecording(params: {
           targetLabel: 'iOS recording',
         });
       } catch (error) {
-        recording.overlayWarning = `failed to overlay recording touches: ${formatOverlayError(error)}`;
+        recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
       }
     }
   }
@@ -386,13 +386,6 @@ function deriveClientTelemetryPath(
   return deriveRecordingTelemetryPath(recording.clientOutPath);
 }
 
-function formatOverlayError(error: unknown): string {
-  if (error instanceof Error && error.message.trim().length > 0) {
-    return error.message;
-  }
-  return String(error);
-}
-
 export async function handleRecordCommand(params: {
   req: DaemonRequest;
   sessionName: string;
diff --git a/src/daemon/recording-gestures.ts b/src/daemon/recording-gestures.ts
index 1356c0449..ddf3f148d 100644
--- a/src/daemon/recording-gestures.ts
+++ b/src/daemon/recording-gestures.ts
@@ -185,9 +185,9 @@ function buildPressEvents(
   tMs: number,
   referenceFrame?: ReferenceFrame,
 ): RecordingGestureEvent[] {
-  const x = readNumber(result.x) ?? readNumber(positionals[0]);
-  const y = readNumber(result.y) ?? readNumber(positionals[1]);
-  if (x === undefined || y === undefined) return [];
+  const coordinates = readCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x, y } = coordinates;
 
   const count = clampInt(readNumber(result.count), 1) ?? 1;
   const intervalMs = clampInt(readNumber(result.intervalMs), 0) ?? 0;
diff --git a/src/daemon/recording-timing.ts b/src/daemon/recording-timing.ts
index a2c11a62d..d1bc6b486 100644
--- a/src/daemon/recording-timing.ts
+++ b/src/daemon/recording-timing.ts
@@ -68,6 +68,9 @@ export function resolveTapVisualizationOffsetMs(source: TapVisualizationOffsetSo
     return resolveGestureOffsetMs(source);
   }
 
+  // Long tap-like commands can spend most of their wall-clock time in selector resolution or
+  // XCTest idle waiting. In that case, show the overlay shortly before completion instead of
+  // anchoring it to the full command runtime.
   const leadMs = Math.min(Math.max(durationMs * 0.15, 120), 260);
   return Math.max(0, source.fallbackFinishedAtMs - leadMs - source.recordingStartedAt);
 }
diff --git a/src/platforms/ios/__tests__/recording-scripts.test.ts b/src/platforms/ios/__tests__/recording-scripts.test.ts
index 722b0da4b..05b96441e 100644
--- a/src/platforms/ios/__tests__/recording-scripts.test.ts
+++ b/src/platforms/ios/__tests__/recording-scripts.test.ts
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runCmd } from '../../../utils/exec.ts';
-import { getRecordingOverlaySupportWarning } from '../recording-overlay.ts';
+import { getRecordingOverlaySupportWarning } from '../../../recording/overlay.ts';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const recordingScriptsDir = path.resolve(
diff --git a/src/platforms/ios/recording-overlay.ts b/src/recording/overlay.ts
similarity index 93%
rename from src/platforms/ios/recording-overlay.ts
rename to src/recording/overlay.ts
index fdb76c5ab..d10354cd1 100644
--- a/src/platforms/ios/recording-overlay.ts
+++ b/src/recording/overlay.ts
@@ -2,19 +2,16 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { runCmd } from '../../utils/exec.ts';
-import { AppError } from '../../utils/errors.ts';
-import { waitForPlayableVideo, waitForStableFile } from '../../utils/video.ts';
+import { runCmd } from '../utils/exec.ts';
+import { AppError } from '../utils/errors.ts';
+import { waitForPlayableVideo, waitForStableFile } from '../utils/video.ts';
 
 function resolveScriptPath(scriptName: string): string {
   const moduleDir = path.dirname(fileURLToPath(import.meta.url));
   const scriptCandidates = [
     fileURLToPath(new URL(`./${scriptName}`, import.meta.url)),
+    path.resolve(moduleDir, `../../ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`),
     path.resolve(moduleDir, `../../../ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`),
-    path.resolve(
-      moduleDir,
-      `../../../../ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`,
-    ),
     path.resolve(process.cwd(), `ios-runner/AgentDeviceRunner/RecordingScripts/${scriptName}`),
   ];
 

From 369b02c1e88c6bdf57075f9a2f1c4f85dae3f47c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 23 Mar 2026 16:46:48 +0100
Subject: [PATCH 10/11] fix: rebase gesture telemetry onto main

---
 .../RunnerTests+CommandExecution.swift        |  38 +-
 .../handlers/__tests__/record-trace.test.ts   |   2 +-
 src/daemon/handlers/interaction-touch.ts      |  39 +-
 src/daemon/handlers/record-trace-ios.ts       |  95 ++++
 src/daemon/handlers/record-trace-recording.ts |  27 +-
 src/daemon/types.ts                           |   8 +-
 src/platforms/ios/runner-xctestrun.ts         | 413 ++++++++++++++----
 7 files changed, 527 insertions(+), 95 deletions(-)

diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 421be390f..210c20cb6 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -259,6 +259,38 @@ extension RunnerTests {
         )
       }
       return Response(ok: false, error: ErrorPayload(message: "tap requires text 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"))
+      }
+      let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
+      do {
+        var clickError: Error?
+        let timing = measureGesture {
+          do {
+            try mouseClickAt(app: activeApp, x: x, y: y, button: command.button ?? "primary")
+          } catch {
+            clickError = error
+          }
+        }
+        if let clickError {
+          throw clickError
+        }
+        return Response(
+          ok: true,
+          data: DataPayload(
+            message: "clicked",
+            gestureStartUptimeMs: timing.gestureStartUptimeMs,
+            gestureEndUptimeMs: timing.gestureEndUptimeMs,
+            x: touchFrame.x,
+            y: touchFrame.y,
+            referenceWidth: touchFrame.referenceWidth,
+            referenceHeight: touchFrame.referenceHeight
+          )
+        )
+      } catch {
+        return Response(ok: false, error: ErrorPayload(message: error.localizedDescription))
+      }
     case .tapSeries:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "tapSeries requires x and y"))
@@ -454,7 +486,7 @@ extension RunnerTests {
         Thread.sleep(forTimeInterval: 0.5)
       }
       let screenshot = XCUIScreen.main.screenshot()
-      guard let pngData = screenshot.image.pngData() else {
+      guard let pngData = runnerPngData(for: screenshot.image) else {
         return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
       }
       let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
@@ -464,8 +496,12 @@ extension RunnerTests {
       } catch {
         return Response(ok: false, error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)"))
       }
+#if os(macOS)
+      return Response(ok: true, data: DataPayload(message: filePath))
+#else
       // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
       return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
+#endif
     case .back:
       if tapNavigationBack(app: activeApp) {
         return Response(ok: true, data: DataPayload(message: "back"))
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index da1d12cdb..5097e9e91 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -284,7 +284,7 @@ test('record stop derives telemetry artifact local path from client outPath', as
 
   const runnerCalls: RunnerCall[] = [];
   const runCmdCalls: Array<{ cmd: string; args: string[] }> = [];
-  const deps = makeIosDeviceRunnerDeps(runnerCalls, runCmdCalls);
+  const deps = makeRunnerRecordingDeps(runnerCalls, runCmdCalls);
   const finalOut = path.join(os.tmpdir(), `agent-device-test-record-${Date.now()}.mp4`);
 
   await runRecordCommand({
diff --git a/src/daemon/handlers/interaction-touch.ts b/src/daemon/handlers/interaction-touch.ts
index c7d901e28..d0c2b7415 100644
--- a/src/daemon/handlers/interaction-touch.ts
+++ b/src/daemon/handlers/interaction-touch.ts
@@ -1,5 +1,10 @@
 import { dispatchCommand, type CommandFlags } from '../../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import {
+  buttonTag,
+  getClickButtonValidationError,
+  resolveClickButton,
+} from '../../core/click-button.ts';
 import { centerOfRect, findNodeByRef, type Rect, type SnapshotNode } from '../../utils/snapshot.ts';
 import type { DaemonCommandContext } from '../context.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
@@ -79,7 +84,8 @@ export async function handleTouchInteractionCommands(params: {
   const readAndroidScreenSize = params.readAndroidScreenSize ?? getAndroidScreenSize;
   const command = req.command;
 
-  if (command === 'press') {
+  if (command === 'press' || command === 'click') {
+    const commandLabel = command === 'click' ? 'click' : 'press';
     const session = sessionStore.get(sessionName);
     if (!session) {
       return {
@@ -93,6 +99,30 @@ export async function handleTouchInteractionCommands(params: {
         error: { code: 'UNSUPPORTED_OPERATION', message: 'press is not supported on this device' },
       };
     }
+    const clickButton = resolveClickButton(req.flags);
+    const resultButtonTag = buttonTag(clickButton);
+    if (clickButton !== 'primary') {
+      const validationError = getClickButtonValidationError({
+        commandLabel,
+        platform: session.device.platform,
+        button: clickButton,
+        count: req.flags?.count,
+        intervalMs: req.flags?.intervalMs,
+        holdMs: req.flags?.holdMs,
+        jitterPx: req.flags?.jitterPx,
+        doubleTap: req.flags?.doubleTap,
+      });
+      if (validationError) {
+        return {
+          ok: false,
+          error: {
+            code: validationError.code,
+            message: validationError.message,
+            details: validationError.details,
+          },
+        };
+      }
+    }
     const directCoordinates = parseCoordinateTarget(req.positionals ?? []);
     if (directCoordinates) {
       const interaction = await dispatchInteractionCommand({
@@ -116,6 +146,7 @@ export async function handleTouchInteractionCommands(params: {
       const visualizationResult = {
         ...(interaction.data ?? { x: directCoordinates.x, y: directCoordinates.y }),
         ...(visualizationFrame ?? {}),
+        ...resultButtonTag,
       };
       return finalizeTouchInteraction({
         session,
@@ -142,7 +173,7 @@ export async function handleTouchInteractionCommands(params: {
         refInput,
         fallbackLabel,
         requireRect: true,
-        invalidRefMessage: `${command} requires a ref like @e2`,
+        invalidRefMessage: `${commandLabel} requires a ref like @e2`,
         notFoundMessage: `Ref ${refInput} not found or has no bounds`,
       });
       if (!resolvedRefTarget.ok) return resolvedRefTarget.response;
@@ -208,6 +239,7 @@ export async function handleTouchInteractionCommands(params: {
           ref,
           refLabel,
           selectorChain,
+          ...resultButtonTag,
         },
       });
       return finalizeTouchInteraction({
@@ -229,7 +261,7 @@ export async function handleTouchInteractionCommands(params: {
         ok: false,
         error: {
           code: 'INVALID_ARGS',
-          message: `${command} requires @ref, selector expression, or x y coordinates`,
+          message: `${commandLabel} requires @ref, selector expression, or x y coordinates`,
         },
       };
     }
@@ -295,6 +327,7 @@ export async function handleTouchInteractionCommands(params: {
         selector: resolved.selector.raw,
         selectorChain,
         refLabel,
+        ...resultButtonTag,
       },
     });
     return finalizeTouchInteraction({
diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
index d703e5ecb..5307b3f0d 100644
--- a/src/daemon/handlers/record-trace-ios.ts
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -213,6 +213,45 @@ export async function startIosDeviceRecording(params: {
   };
 }
 
+export async function startMacOsRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  fpsFlag: number | undefined;
+  recordingBase: RecordingBase;
+  appBundleId: string;
+}): Promise<DaemonResponse | NonNullable<SessionState['recording']>> {
+  const { req, activeSession, device, logPath, deps, fpsFlag, recordingBase, appBundleId } = params;
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      {
+        command: 'recordStart',
+        outPath: recordingBase.outPath,
+        fps: fpsFlag,
+        appBundleId,
+      },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: `failed to start recording: ${formatRecordTraceError(error)}`,
+      },
+    };
+  }
+
+  return {
+    platform: 'macos-runner',
+    ...recordingBase,
+  };
+}
+
 export async function stopIosDeviceRecording(params: {
   req: DaemonRequest;
   activeSession: SessionState;
@@ -319,3 +358,59 @@ export async function stopIosDeviceRecording(params: {
 
   return null;
 }
+
+export async function stopMacOsRecording(params: {
+  req: DaemonRequest;
+  activeSession: SessionState;
+  device: SessionState['device'];
+  logPath?: string;
+  deps: RecordTraceDeps;
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'macos-runner' }>;
+}): Promise<DaemonResponse | null> {
+  const { req, activeSession, device, logPath, deps, recording } = params;
+  const appBundleId = normalizeAppBundleId(activeSession);
+
+  try {
+    await deps.runIosRunnerCommand(
+      device,
+      { command: 'recordStop', appBundleId },
+      getRunnerOptions(req, logPath, activeSession),
+    );
+  } catch (error) {
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'record_stop_runner_failed',
+      data: {
+        platform: device.platform,
+        kind: device.kind,
+        deviceId: device.id,
+        session: activeSession.name,
+        error: formatRecordTraceError(error),
+      },
+    });
+  }
+
+  const telemetryPath = persistRecordingTelemetry({
+    recording,
+    writeTelemetry: deps.writeRecordingTelemetry,
+  });
+
+  if (recording.showTouches) {
+    const overlaySupportWarning = getRecordingOverlaySupportWarning();
+    if (overlaySupportWarning) {
+      recording.overlayWarning = overlaySupportWarning;
+    } else {
+      try {
+        await deps.overlayRecordingTouches({
+          videoPath: recording.outPath,
+          telemetryPath,
+          targetLabel: 'macOS recording',
+        });
+      } catch (error) {
+        recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+      }
+    }
+  }
+
+  return null;
+}
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 9b3509759..7b4032abb 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -30,6 +30,8 @@ import { startAndroidRecording, stopAndroidRecording } from './record-trace-andr
 import {
   normalizeAppBundleId,
   startIosDeviceRecording,
+  startMacOsRecording,
+  stopMacOsRecording,
   stopIosDeviceRecording,
   warmIosSimulatorRunner,
 } from './record-trace-ios.ts';
@@ -180,6 +182,27 @@ async function startRecording(params: {
       recordingBase,
       appBundleId,
     });
+  } else if (device.platform === 'macos') {
+    const appBundleId = normalizeAppBundleId(activeSession);
+    if (!appBundleId) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'record on macOS requires an active app session; run open <app> first',
+        },
+      };
+    }
+    recording = await startMacOsRecording({
+      req,
+      activeSession,
+      device,
+      logPath,
+      deps,
+      fpsFlag,
+      recordingBase,
+      appBundleId,
+    });
   } else if (device.platform === 'ios') {
     await warmIosSimulatorRunner({
       req,
@@ -261,7 +284,7 @@ async function startRecording(params: {
 async function stopNonRunnerRecording(params: {
   deps: RecordTraceDeps;
   device: SessionState['device'];
-  recording: Exclude<NonNullable<SessionState['recording']>, { platform: 'ios-device-runner' }>;
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios' | 'android' }>;
 }): Promise<DaemonResponse | null> {
   const { deps, device, recording } = params;
   if (recording.platform === 'android') {
@@ -326,6 +349,8 @@ async function stopRecording(params: {
   const stopError =
     recording.platform === 'ios-device-runner'
       ? await stopIosDeviceRecording({ req, activeSession, device, logPath, deps, recording })
+      : recording.platform === 'macos-runner'
+        ? await stopMacOsRecording({ req, activeSession, device, logPath, deps, recording })
       : await stopNonRunnerRecording({ deps, device, recording });
   if (stopError) {
     return stopError;
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 0f33b8e40..4b506e14f 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -151,10 +151,14 @@ export type SessionState = {
         remotePid: string;
       })
     | (SessionRecordingBase & {
-        platform: 'ios-device-runner' | 'macos-runner';
-        remotePath?: string;
+        platform: 'ios-device-runner';
+        remotePath: string;
         runnerStartedAtUptimeMs?: number;
         targetAppReadyUptimeMs?: number;
+      })
+    | (SessionRecordingBase & {
+        platform: 'macos-runner';
+        remotePath?: string;
       });
   /** Session-scoped app log stream; logs written to outPath for agent to grep */
   appLog?: {
diff --git a/src/platforms/ios/runner-xctestrun.ts b/src/platforms/ios/runner-xctestrun.ts
index 4c0389201..e18fac1ef 100644
--- a/src/platforms/ios/runner-xctestrun.ts
+++ b/src/platforms/ios/runner-xctestrun.ts
@@ -7,8 +7,15 @@ import { runCmd, runCmdStreaming, type ExecBackgroundResult } from '../../utils/
 import { isEnvTruthy } from '../../utils/retry.ts';
 import { resolveApplePlatformName, type DeviceInfo } from '../../utils/device.ts';
 import { withKeyedLock } from '../../utils/keyed-lock.ts';
+import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import { resolveSigningFailureHint } from './runner-errors.ts';
 import { logChunk } from './runner-transport.ts';
+import {
+  repairMacOsRunnerProductsIfNeeded,
+  isExpectedRunnerRepairFailure,
+} from './runner-macos-products.ts';
+import { resolveExistingXctestrunProductPaths } from './runner-xctestrun-products.ts';
+export { xctestrunReferencesExistingProducts } from './runner-xctestrun-products.ts';
 
 const DEFAULT_IOS_RUNNER_APP_BUNDLE_ID = 'com.callstack.agentdevice.runner';
 
@@ -54,24 +61,90 @@ export const IOS_RUNNER_CONTAINER_BUNDLE_IDS: string[] = resolveRunnerContainerB
   process.env,
 );
 
+type EnsureXctestrunDeps = {
+  findProjectRoot: () => string;
+  findXctestrun: (root: string, device?: DeviceInfo) => string | null;
+  xctestrunReferencesProjectRoot: (xctestrunPath: string, projectRoot: string) => boolean;
+  resolveExistingXctestrunProductPaths: (xctestrunPath: string) => string[] | null;
+  repairRunnerProductsIfNeeded: (
+    device: DeviceInfo,
+    productPaths: string[],
+    xctestrunPath: string,
+  ) => Promise<void>;
+  assertSafeDerivedCleanup: (derivedPath: string) => void;
+  cleanRunnerDerivedArtifacts: (derivedPath: string) => void;
+  buildRunnerXctestrun: (
+    device: DeviceInfo,
+    projectPath: string,
+    derived: string,
+    options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
+  ) => Promise<void>;
+};
+
+const defaultEnsureXctestrunDeps: EnsureXctestrunDeps = {
+  findProjectRoot,
+  findXctestrun,
+  xctestrunReferencesProjectRoot,
+  resolveExistingXctestrunProductPaths,
+  repairRunnerProductsIfNeeded: repairMacOsRunnerProductsIfNeeded,
+  assertSafeDerivedCleanup,
+  cleanRunnerDerivedArtifacts,
+  buildRunnerXctestrun,
+};
+
 export async function ensureXctestrun(
   device: DeviceInfo,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
+  deps: EnsureXctestrunDeps = defaultEnsureXctestrunDeps,
 ): Promise<string> {
-  const derived = resolveRunnerDerivedPath(device.kind);
+  const derived = resolveRunnerDerivedPath(device);
+  const projectRoot = deps.findProjectRoot();
   return await withKeyedLock(runnerXctestrunBuildLocks, derived, async () => {
     if (shouldCleanDerived()) {
-      assertSafeDerivedCleanup(derived);
+      emitRunnerXctestrunDecision('clean', 'forced_clean', { derived });
+      deps.assertSafeDerivedCleanup(derived);
+      deps.cleanRunnerDerivedArtifacts(derived);
+    }
+    const existing = evaluateExistingXctestrun({
+      derived,
+      projectRoot,
+      findXctestrun: (root) => deps.findXctestrun(root, device),
+      xctestrunReferencesProjectRoot: deps.xctestrunReferencesProjectRoot,
+      resolveExistingXctestrunProductPaths: deps.resolveExistingXctestrunProductPaths,
+    });
+    if (existing.reason !== 'reuse_ready') {
+      emitRunnerXctestrunDecision('rebuild', existing.reason, {
+        derived,
+        xctestrunPath: existing.xctestrunPath,
+      });
+    }
+    if (existing.reason === 'reuse_ready') {
       try {
-        fs.rmSync(derived, { recursive: true, force: true });
-      } catch {
-        // ignore
+        await deps.repairRunnerProductsIfNeeded(
+          device,
+          existing.productPaths,
+          existing.xctestrunPath,
+        );
+        emitRunnerXctestrunDecision('reuse', 'reuse_ready', {
+          derived,
+          xctestrunPath: existing.xctestrunPath,
+        });
+        return existing.xctestrunPath;
+      } catch (error) {
+        if (!isExpectedRunnerRepairFailure(error)) {
+          throw error;
+        }
+        emitRunnerXctestrunDecision('rebuild', 'repair_failed', {
+          derived,
+          xctestrunPath: existing.xctestrunPath,
+        });
+        // Fall through and rebuild from a clean derived state.
       }
     }
-    const existing = findXctestrun(derived, device);
-    if (existing) return existing;
-
-    const projectRoot = findProjectRoot();
+    if (existing.xctestrunPath) {
+      deps.assertSafeDerivedCleanup(derived);
+      deps.cleanRunnerDerivedArtifacts(derived);
+    }
     const projectPath = path.join(
       projectRoot,
       'ios-runner',
@@ -83,76 +156,65 @@ export async function ensureXctestrun(
       throw new AppError('COMMAND_FAILED', 'iOS runner project not found', { projectPath });
     }
 
-    const runnerBundleBuildSettings = resolveRunnerBundleBuildSettings(process.env);
-    const signingBuildSettings = resolveRunnerSigningBuildSettings(
-      process.env,
-      device.kind === 'device',
-    );
-    const provisioningArgs = device.kind === 'device' ? ['-allowProvisioningUpdates'] : [];
-    const performanceBuildSettings = resolveRunnerPerformanceBuildSettings();
-    try {
-      await runCmdStreaming(
-        'xcodebuild',
-        [
-          'build-for-testing',
-          '-project',
-          projectPath,
-          '-scheme',
-          'AgentDeviceRunner',
-          '-parallel-testing-enabled',
-          'NO',
-          resolveRunnerMaxConcurrentDestinationsFlag(device),
-          '1',
-          '-destination',
-          resolveRunnerBuildDestination(device),
-          '-derivedDataPath',
-          derived,
-          ...performanceBuildSettings,
-          ...runnerBundleBuildSettings,
-          ...provisioningArgs,
-          ...signingBuildSettings,
-        ],
-        {
-          detached: true,
-          onSpawn: (child) => {
-            runnerPrepProcesses.add(child);
-            child.on('close', () => {
-              runnerPrepProcesses.delete(child);
-            });
-          },
-          onStdoutChunk: (chunk) => {
-            logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
-          },
-          onStderrChunk: (chunk) => {
-            logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
-          },
-        },
-      );
-    } catch (err) {
-      const appErr = err instanceof AppError ? err : new AppError('COMMAND_FAILED', String(err));
-      const hint = resolveSigningFailureHint(appErr);
-      throw new AppError('COMMAND_FAILED', 'xcodebuild build-for-testing failed', {
-        error: appErr.message,
-        details: appErr.details,
-        logPath: options.logPath,
-        hint,
-      });
-    }
+    await deps.buildRunnerXctestrun(device, projectPath, derived, options);
 
-    const built = findXctestrun(derived, device);
+    const built = deps.findXctestrun(derived, device);
     if (!built) {
       throw new AppError('COMMAND_FAILED', 'Failed to locate .xctestrun after build');
     }
+    const builtProductPaths = deps.resolveExistingXctestrunProductPaths(built);
+    if (!builtProductPaths) {
+      throw new AppError('COMMAND_FAILED', 'Runner build is missing expected products', {
+        xctestrunPath: built,
+      });
+    }
+    await deps.repairRunnerProductsIfNeeded(device, builtProductPaths, built);
+    emitRunnerXctestrunDecision('build', 'built_new', {
+      derived,
+      xctestrunPath: built,
+    });
     return built;
   });
 }
 
+function cleanRunnerDerivedArtifacts(derived: string): void {
+  try {
+    if (!fs.existsSync(derived)) return;
+    if (path.basename(derived) !== 'derived') {
+      fs.rmSync(derived, { recursive: true, force: true });
+      return;
+    }
+    for (const entry of fs.readdirSync(derived, { withFileTypes: true })) {
+      if (!shouldDeleteRunnerDerivedRootEntry(entry.name)) continue;
+      fs.rmSync(path.join(derived, entry.name), { recursive: true, force: true });
+    }
+  } catch {
+    // ignore
+  }
+}
+
+const RUNNER_ROOT_TRANSIENT_ENTRY_NAMES = new Set([
+  'Build',
+  'BuildCache.noindex',
+  'Index.noindex',
+  'Logs',
+  'ModuleCache.noindex',
+  'SDKStatCaches.noindex',
+  'SourcePackages',
+  'TextBasedInstallAPI',
+  'info.plist',
+]);
+
+export function shouldDeleteRunnerDerivedRootEntry(entryName: string): boolean {
+  return RUNNER_ROOT_TRANSIENT_ENTRY_NAMES.has(entryName);
+}
+
 type XctestrunCandidate = {
   path: string;
   mtimeMs: number;
 };
 
-export function findXctestrun(root: string, device: DeviceInfo): string | null {
+export function findXctestrun(root: string, device?: DeviceInfo): string | null {
   if (!fs.existsSync(root)) return null;
   const candidates: XctestrunCandidate[] = [];
   const stack: string[] = [root];
@@ -176,19 +238,19 @@ export function findXctestrun(root: string, device: DeviceInfo): string | null {
     }
   }
   if (candidates.length === 0) return null;
-  candidates.sort(
-    (a, b) =>
-      compareXctestrunCandidates(b.path, a.path, device) ||
-      b.mtimeMs - a.mtimeMs ||
-      a.path.localeCompare(b.path),
-  );
+  candidates.sort((a, b) => {
+    if (device) {
+      const scoreDiff =
+        scoreXctestrunCandidate(b.path, device) - scoreXctestrunCandidate(a.path, device);
+      if (scoreDiff !== 0) {
+        return scoreDiff;
+      }
+    }
+    return b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path);
+  });
   return candidates[0]?.path ?? null;
 }
 
-function compareXctestrunCandidates(left: string, right: string, device: DeviceInfo): number {
-  return scoreXctestrunCandidate(left, device) - scoreXctestrunCandidate(right, device);
-}
-
 export function scoreXctestrunCandidate(candidatePath: string, device: DeviceInfo): number {
   let score = 0;
   const normalizedPath = candidatePath.toLowerCase();
@@ -222,32 +284,62 @@ function resolveRunnerXctestrunHints(device: DeviceInfo): {
   preferred: string[];
   disallowed: string[];
 } {
+  if (device.platform === 'macos') {
+    return {
+      preferred: ['macos'],
+      disallowed: ['iphoneos', 'iphonesimulator', 'appletvos', 'appletvsimulator'],
+    };
+  }
+
   if (device.target === 'tv') {
     if (device.kind === 'simulator') {
       return {
         preferred: ['appletvsimulator'],
-        disallowed: ['appletvos', 'iphoneos', 'iphonesimulator'],
+        disallowed: ['appletvos', 'iphoneos', 'iphonesimulator', 'macos'],
       };
     }
     return {
       preferred: ['appletvos'],
-      disallowed: ['appletvsimulator', 'iphoneos', 'iphonesimulator'],
+      disallowed: ['appletvsimulator', 'iphoneos', 'iphonesimulator', 'macos'],
     };
   }
 
   if (device.kind === 'simulator') {
     return {
       preferred: ['iphonesimulator'],
-      disallowed: ['iphoneos', 'appletvos', 'appletvsimulator'],
+      disallowed: ['iphoneos', 'appletvos', 'appletvsimulator', 'macos'],
     };
   }
 
   return {
     preferred: ['iphoneos'],
-    disallowed: ['iphonesimulator', 'appletvos', 'appletvsimulator'],
+    disallowed: ['iphonesimulator', 'appletvos', 'appletvsimulator', 'macos'],
   };
 }
 
+export function xctestrunReferencesProjectRoot(
+  xctestrunPath: string,
+  projectRoot: string,
+): boolean {
+  try {
+    const contents = fs.readFileSync(xctestrunPath, 'utf8');
+    const candidateRoots = new Set<string>([projectRoot]);
+    try {
+      candidateRoots.add(fs.realpathSync(projectRoot));
+    } catch {
+      // ignore
+    }
+    for (const root of candidateRoots) {
+      if (contents.includes(root)) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 function findProjectRoot(): string {
   const start = path.dirname(fileURLToPath(import.meta.url));
   let current = start;
@@ -343,19 +435,89 @@ export async function prepareXctestrunWithEnv(
   return { xctestrunPath: tmpXctestrunPath, jsonPath: tmpJsonPath };
 }
 
-function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
+async function buildRunnerXctestrun(
+  device: DeviceInfo,
+  projectPath: string,
+  derived: string,
+  options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
+): Promise<void> {
+  const runnerBundleBuildSettings = resolveRunnerBundleBuildSettings(process.env);
+  const signingBuildSettings = resolveRunnerSigningBuildSettings(
+    process.env,
+    device.kind === 'device',
+    device.platform,
+  );
+  const provisioningArgs = device.kind === 'device' ? ['-allowProvisioningUpdates'] : [];
+  const performanceBuildSettings = resolveRunnerPerformanceBuildSettings();
+  try {
+    await runCmdStreaming(
+      'xcodebuild',
+      [
+        'build-for-testing',
+        '-project',
+        projectPath,
+        '-scheme',
+        'AgentDeviceRunner',
+        '-parallel-testing-enabled',
+        'NO',
+        resolveRunnerMaxConcurrentDestinationsFlag(device),
+        '1',
+        '-destination',
+        resolveRunnerBuildDestination(device),
+        '-derivedDataPath',
+        derived,
+        ...performanceBuildSettings,
+        ...runnerBundleBuildSettings,
+        ...provisioningArgs,
+        ...signingBuildSettings,
+      ],
+      {
+        detached: true,
+        onSpawn: (child) => {
+          runnerPrepProcesses.add(child);
+          child.on('close', () => {
+            runnerPrepProcesses.delete(child);
+          });
+        },
+        onStdoutChunk: (chunk) => {
+          logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
+        },
+        onStderrChunk: (chunk) => {
+          logChunk(chunk, options.logPath, options.traceLogPath, options.verbose);
+        },
+      },
+    );
+  } catch (err) {
+    const appErr = err instanceof AppError ? err : new AppError('COMMAND_FAILED', String(err));
+    const hint = resolveSigningFailureHint(appErr);
+    throw new AppError('COMMAND_FAILED', 'xcodebuild build-for-testing failed', {
+      error: appErr.message,
+      details: appErr.details,
+      logPath: options.logPath,
+      hint,
+    });
+  }
+}
+
+function resolveRunnerDerivedPath(device: DeviceInfo): string {
   const override = process.env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH?.trim();
   if (override) {
     return path.resolve(override);
   }
-  if (kind === 'simulator') {
+  if (device.platform === 'macos') {
+    return path.join(RUNNER_DERIVED_ROOT, 'derived', 'macos');
+  }
+  if (device.kind === 'simulator') {
     return path.join(RUNNER_DERIVED_ROOT, 'derived');
   }
-  return path.join(RUNNER_DERIVED_ROOT, 'derived', kind);
+  return path.join(RUNNER_DERIVED_ROOT, 'derived', device.kind);
 }
 
 export function resolveRunnerDestination(device: DeviceInfo): string {
   const platformName = resolveRunnerPlatformName(device);
+  if (platformName === 'macOS') {
+    return `platform=macOS,arch=${resolveMacRunnerArch()}`;
+  }
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
@@ -364,23 +526,36 @@ export function resolveRunnerDestination(device: DeviceInfo): string {
 
 export function resolveRunnerBuildDestination(device: DeviceInfo): string {
   const platformName = resolveRunnerPlatformName(device);
+  if (platformName === 'macOS') {
+    return `platform=macOS,arch=${resolveMacRunnerArch()}`;
+  }
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
   return `generic/platform=${platformName}`;
 }
 
-function resolveRunnerPlatformName(device: DeviceInfo): 'iOS' | 'tvOS' {
-  if (device.platform !== 'ios') {
+function resolveRunnerPlatformName(device: DeviceInfo): 'iOS' | 'tvOS' | 'macOS' {
+  if (device.platform !== 'ios' && device.platform !== 'macos') {
     throw new AppError(
       'UNSUPPORTED_PLATFORM',
       `Unsupported platform for iOS runner: ${device.platform}`,
     );
   }
+  if (device.platform === 'macos') {
+    return 'macOS';
+  }
   return resolveApplePlatformName(device.target);
 }
 
+function resolveMacRunnerArch(): 'arm64' | 'x86_64' {
+  return process.arch === 'arm64' ? 'arm64' : 'x86_64';
+}
+
 export function resolveRunnerMaxConcurrentDestinationsFlag(device: DeviceInfo): string {
+  if (device.platform === 'macos') {
+    return '-maximum-concurrent-test-device-destinations';
+  }
   return device.kind === 'device'
     ? '-maximum-concurrent-test-device-destinations'
     : '-maximum-concurrent-test-simulator-destinations';
@@ -389,7 +564,16 @@ export function resolveRunnerMaxConcurrentDestinationsFlag(device: DeviceInfo):
 export function resolveRunnerSigningBuildSettings(
   env: NodeJS.ProcessEnv = process.env,
   forDevice = false,
+  platform: DeviceInfo['platform'] = 'ios',
 ): string[] {
+  if (platform === 'macos') {
+    return [
+      'CODE_SIGNING_ALLOWED=NO',
+      'CODE_SIGNING_REQUIRED=NO',
+      'CODE_SIGN_IDENTITY=',
+      'DEVELOPMENT_TEAM=',
+    ];
+  }
   if (!forDevice) {
     return [];
   }
@@ -416,8 +600,8 @@ export function resolveRunnerBundleBuildSettings(env: NodeJS.ProcessEnv = proces
   ];
 }
 
-function resolveRunnerPerformanceBuildSettings(): string[] {
-  return ['COMPILER_INDEX_STORE_ENABLE=NO'];
+export function resolveRunnerPerformanceBuildSettings(): string[] {
+  return ['COMPILER_INDEX_STORE_ENABLE=NO', 'ENABLE_CODE_COVERAGE=NO'];
 }
 
 function shouldCleanDerived(): boolean {
@@ -448,3 +632,58 @@ export function assertSafeDerivedCleanup(
 function isCleanupOverrideAllowed(env: NodeJS.ProcessEnv = process.env): boolean {
   return isEnvTruthy(env.AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN);
 }
+
+type ExistingXctestrunState =
+  | {
+      reason: 'missing_xctestrun';
+      xctestrunPath: null;
+    }
+  | {
+      reason: 'project_root_mismatch' | 'missing_products' | 'reuse_ready';
+      xctestrunPath: string;
+      productPaths: string[];
+    };
+
+function evaluateExistingXctestrun(options: {
+  derived: string;
+  projectRoot: string;
+  findXctestrun: (root: string) => string | null;
+  xctestrunReferencesProjectRoot: (xctestrunPath: string, projectRoot: string) => boolean;
+  resolveExistingXctestrunProductPaths: (xctestrunPath: string) => string[] | null;
+}): ExistingXctestrunState {
+  const xctestrunPath = options.findXctestrun(options.derived);
+  if (!xctestrunPath) {
+    return { reason: 'missing_xctestrun', xctestrunPath: null };
+  }
+  const productPaths = options.resolveExistingXctestrunProductPaths(xctestrunPath);
+  if (!productPaths) {
+    return { reason: 'missing_products', xctestrunPath, productPaths: [] };
+  }
+  if (!options.xctestrunReferencesProjectRoot(xctestrunPath, options.projectRoot)) {
+    return { reason: 'project_root_mismatch', xctestrunPath, productPaths };
+  }
+  return { reason: 'reuse_ready', xctestrunPath, productPaths };
+}
+
+function emitRunnerXctestrunDecision(
+  action: 'clean' | 'reuse' | 'rebuild' | 'build',
+  reason:
+    | 'forced_clean'
+    | 'missing_xctestrun'
+    | 'project_root_mismatch'
+    | 'missing_products'
+    | 'repair_failed'
+    | 'reuse_ready'
+    | 'built_new',
+  data: Record<string, unknown>,
+): void {
+  emitDiagnostic({
+    level: action === 'rebuild' ? 'warn' : 'info',
+    phase: 'runner_xctestrun_cache',
+    data: {
+      action,
+      reason,
+      ...data,
+    },
+  });
+}

From da63eddc4128fa5c0ec3df4317655ced45152d02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 24 Mar 2026 13:14:05 +0100
Subject: [PATCH 11/11] test: fix recording overlay CI expectations

---
 .../handlers/__tests__/record-trace.test.ts   | 43 +++++++++++++------
 src/daemon/handlers/session-replay-script.ts  |  2 +-
 src/daemon/script-utils.ts                    | 16 +++++++
 src/daemon/session-record-script.ts           | 18 --------
 src/daemon/session-store.ts                   |  2 +-
 .../ios/__tests__/recording-scripts.test.ts   | 12 +++---
 .../support}/recording-inspect.swift          |  0
 test/integration/test-helpers.ts              | 13 +-----
 8 files changed, 57 insertions(+), 49 deletions(-)
 delete mode 100644 src/daemon/session-record-script.ts
 rename {ios-runner/AgentDeviceRunner/RecordingScripts => test/integration/support}/recording-inspect.swift (100%)

diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index 5097e9e91..592d3aa9f 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -8,6 +8,7 @@ import { deriveRecordingTelemetryPath } from '../../recording-telemetry.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { SessionState } from '../../types.ts';
 import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../../platforms/ios/runner-client.ts';
+import { getRecordingOverlaySupportWarning } from '../../../recording/overlay.ts';
 
 type RecordTraceDeps = NonNullable<Parameters<typeof handleRecordTraceCommands>[0]['deps']>;
 type RunnerCall = {
@@ -19,6 +20,8 @@ type RunnerCall = {
   traceLogPath?: string;
 };
 
+const overlaySupportWarning = getRecordingOverlaySupportWarning();
+
 function makeSessionStore(): SessionStore {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-record-trace-'));
   return new SessionStore(path.join(root, 'sessions'));
@@ -637,11 +640,17 @@ test('record stop trims iOS device recordings from target app readiness before o
   });
 
   assert.equal(response?.ok, true);
-  assert.deepEqual(lifecycleCalls, [
+  const expectedLifecycleCalls = [
     'trim:/tmp/device.mp4:3250',
     'telemetry:/tmp/device.mp4:1',
-    `overlay:/tmp/device.mp4:${deriveRecordingTelemetryPath('/tmp/device.mp4')}`,
-  ]);
+  ];
+  if (!overlaySupportWarning) {
+    expectedLifecycleCalls.push(
+      `overlay:/tmp/device.mp4:${deriveRecordingTelemetryPath('/tmp/device.mp4')}`,
+    );
+  }
+  assert.deepEqual(lifecycleCalls, expectedLifecycleCalls);
+  assert.equal(response?.data?.overlayWarning, overlaySupportWarning);
 });
 
 test('record uses simctl recordVideo for iOS simulators', async () => {
@@ -772,7 +781,7 @@ test('record stop keeps iOS simulator video when overlay export fails', async ()
   assert.equal(responseStop?.ok, true);
   assert.equal(
     responseStop?.data?.overlayWarning,
-    'failed to overlay recording touches: swift export failed',
+    overlaySupportWarning ?? 'failed to overlay recording touches: swift export failed',
   );
 });
 
@@ -863,7 +872,7 @@ test('record start/stop overlays Android gestures by default on devices', async
   startedRecording?.gestureEvents.push({ kind: 'tap', tMs: 120, x: 90, y: 180 });
 
   const overlayCalls: Array<{ videoPath: string; telemetryPath: string }> = [];
-  await runRecordCommand({
+  const responseStop = await runRecordCommand({
     sessionStore,
     sessionName,
     positionals: ['stop'],
@@ -889,12 +898,22 @@ test('record start/stop overlays Android gestures by default on devices', async
   });
 
   assert.ok(adbCalls.some((args) => args.join(' ') === '-s emulator-5554 shell kill -2 4321'));
-  assert.deepEqual(overlayCalls, [
-    {
-      videoPath: path.resolve('./android.mp4'),
-      telemetryPath: deriveRecordingTelemetryPath(path.resolve('./android.mp4')),
-    },
-  ]);
+  assert.equal(responseStop?.ok, true);
+  if (!responseStop?.ok) {
+    throw new Error('expected successful Android record stop response');
+  }
+  if (overlaySupportWarning) {
+    assert.deepEqual(overlayCalls, []);
+    assert.equal(responseStop.data?.overlayWarning, overlaySupportWarning);
+  } else {
+    assert.deepEqual(overlayCalls, [
+      {
+        videoPath: path.resolve('./android.mp4'),
+        telemetryPath: deriveRecordingTelemetryPath(path.resolve('./android.mp4')),
+      },
+    ]);
+    assert.equal(responseStop.data?.overlayWarning, undefined);
+  }
 });
 
 test('record stop keeps Android video when overlay export fails', async () => {
@@ -968,7 +987,7 @@ test('record stop keeps Android video when overlay export fails', async () => {
   assert.equal(responseStop?.ok, true);
   assert.equal(
     responseStop?.data?.overlayWarning,
-    'failed to overlay recording touches: android overlay export failed',
+    overlaySupportWarning ?? 'failed to overlay recording touches: android overlay export failed',
   );
 });
 
diff --git a/src/daemon/handlers/session-replay-script.ts b/src/daemon/handlers/session-replay-script.ts
index f73f673e8..a07648f08 100644
--- a/src/daemon/handlers/session-replay-script.ts
+++ b/src/daemon/handlers/session-replay-script.ts
@@ -1,9 +1,9 @@
 import fs from 'node:fs';
 import { AppError } from '../../utils/errors.ts';
 import { appendOpenActionScriptArgs, parseReplayOpenFlags } from '../session-open-script.ts';
-import { appendRecordActionScriptArgs } from '../session-record-script.ts';
 import type { SessionAction, SessionState } from '../types.ts';
 import {
+  appendRecordActionScriptArgs,
   appendRuntimeHintFlags,
   appendScriptSeriesFlags,
   formatScriptArgQuoteIfNeeded,
diff --git a/src/daemon/script-utils.ts b/src/daemon/script-utils.ts
index aef9cf90d..92a747425 100644
--- a/src/daemon/script-utils.ts
+++ b/src/daemon/script-utils.ts
@@ -95,6 +95,22 @@ export function appendRuntimeHintFlags(
   }
 }
 
+export function appendRecordActionScriptArgs(parts: string[], action: SessionAction): void {
+  const [subcommand, ...rest] = action.positionals ?? [];
+  if (subcommand) {
+    parts.push(formatScriptArgQuoteIfNeeded(subcommand));
+  }
+  for (const positional of rest) {
+    parts.push(formatScriptArg(positional));
+  }
+  if (typeof action.flags?.fps === 'number') {
+    parts.push('--fps', String(action.flags.fps));
+  }
+  if (action.flags?.hideTouches) {
+    parts.push('--hide-touches');
+  }
+}
+
 export function parseReplaySeriesFlags(
   command: string,
   args: string[],
diff --git a/src/daemon/session-record-script.ts b/src/daemon/session-record-script.ts
deleted file mode 100644
index 02c3757c1..000000000
--- a/src/daemon/session-record-script.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { SessionAction } from './types.ts';
-import { formatScriptArg, formatScriptArgQuoteIfNeeded } from './script-utils.ts';
-
-export function appendRecordActionScriptArgs(parts: string[], action: SessionAction): void {
-  const [subcommand, ...rest] = action.positionals ?? [];
-  if (subcommand) {
-    parts.push(formatScriptArgQuoteIfNeeded(subcommand));
-  }
-  for (const positional of rest) {
-    parts.push(formatScriptArg(positional));
-  }
-  if (typeof action.flags?.fps === 'number') {
-    parts.push('--fps', String(action.flags.fps));
-  }
-  if (action.flags?.hideTouches) {
-    parts.push('--hide-touches');
-  }
-}
diff --git a/src/daemon/session-store.ts b/src/daemon/session-store.ts
index b92b84d66..ef0ac4aba 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -5,8 +5,8 @@ import type { SessionAction, SessionRuntimeHints, SessionState } from './types.t
 import { inferFillText } from './action-utils.ts';
 import { resolveUserPath } from '../utils/path-resolution.ts';
 import { appendOpenActionScriptArgs } from './session-open-script.ts';
-import { appendRecordActionScriptArgs } from './session-record-script.ts';
 import {
+  appendRecordActionScriptArgs,
   appendRuntimeHintFlags,
   appendScriptSeriesFlags,
   formatScriptArgQuoteIfNeeded,
diff --git a/src/platforms/ios/__tests__/recording-scripts.test.ts b/src/platforms/ios/__tests__/recording-scripts.test.ts
index 05b96441e..16a7dd710 100644
--- a/src/platforms/ios/__tests__/recording-scripts.test.ts
+++ b/src/platforms/ios/__tests__/recording-scripts.test.ts
@@ -10,13 +10,13 @@ const recordingScriptsDir = path.resolve(
   __dirname,
   '../../../../ios-runner/AgentDeviceRunner/RecordingScripts',
 );
+const recordingTestSupportDir = path.resolve(__dirname, '../../../../test/integration/support');
 
-async function assertSwiftScriptTypechecks(scriptName: string): Promise<void> {
-  const scriptPath = path.join(recordingScriptsDir, scriptName);
+async function assertSwiftScriptTypechecks(scriptPath: string): Promise<void> {
   const result = await runCmd('xcrun', ['swiftc', '-typecheck', scriptPath], {
     allowFailure: true,
   });
-  assert.equal(result.exitCode, 0, `${scriptName} should typecheck`);
+  assert.equal(result.exitCode, 0, `${path.basename(scriptPath)} should typecheck`);
 }
 
 test('recording overlay Swift script typechecks', async (t) => {
@@ -24,7 +24,7 @@ test('recording overlay Swift script typechecks', async (t) => {
     t.skip('Swift recording scripts are only validated on macOS');
   }
 
-  await assertSwiftScriptTypechecks('recording-overlay.swift');
+  await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-overlay.swift'));
 });
 
 test('recording trim Swift script typechecks', async (t) => {
@@ -32,7 +32,7 @@ test('recording trim Swift script typechecks', async (t) => {
     t.skip('Swift recording scripts are only validated on macOS');
   }
 
-  await assertSwiftScriptTypechecks('recording-trim.swift');
+  await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-trim.swift'));
 });
 
 test('recording inspect Swift script typechecks', async (t) => {
@@ -40,7 +40,7 @@ test('recording inspect Swift script typechecks', async (t) => {
     t.skip('Swift recording scripts are only validated on macOS');
   }
 
-  await assertSwiftScriptTypechecks('recording-inspect.swift');
+  await assertSwiftScriptTypechecks(path.join(recordingTestSupportDir, 'recording-inspect.swift'));
 });
 
 test('recording overlays are explicitly unsupported on non-macOS hosts', () => {
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift b/test/integration/support/recording-inspect.swift
similarity index 100%
rename from ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift
rename to test/integration/support/recording-inspect.swift
diff --git a/test/integration/test-helpers.ts b/test/integration/test-helpers.ts
index 908a3b023..ccc5e08c3 100644
--- a/test/integration/test-helpers.ts
+++ b/test/integration/test-helpers.ts
@@ -287,9 +287,7 @@ export function runRecordingInspect(params: {
   outputDir: string;
 }): RecordingInspectionManifest {
   mkdirSync(params.outputDir, { recursive: true });
-  const scriptPath = path.resolve(
-    'ios-runner/AgentDeviceRunner/RecordingScripts/recording-inspect.swift',
-  );
+  const scriptPath = path.resolve('test/integration/support/recording-inspect.swift');
   const result = runCmdSync(
     'xcrun',
     [
@@ -343,14 +341,7 @@ function isOverlayBlue(r: number, g: number, b: number, a: number): boolean {
   }
   const maxChannel = Math.max(r, g, b);
   const minChannel = Math.min(r, g, b);
-  return (
-    b >= 180 &&
-    g >= 160 &&
-    r <= 235 &&
-    b >= g &&
-    b - r >= 25 &&
-    maxChannel - minChannel >= 12
-  );
+  return b >= 180 && g >= 160 && r <= 235 && b >= g && b - r >= 25 && maxChannel - minChannel >= 12;
 }
 
 function sanitizeSegment(input: string): string {