diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index a91175782..210c20cb6 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)
@@ -175,7 +185,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,
@@ -204,26 +214,80 @@ 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) {
-          element.tap()
-          return Response(ok: true, data: DataPayload(message: "tapped"))
+          let timing = measureGesture {
+            withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+              element.tap()
+            }
+          }
+          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 {
-        tapAt(app: activeApp, x: x, y: y)
-        return Response(ok: true, data: DataPayload(message: "tapped"))
+        let touchFrame = resolvedTouchVisualizationFrame(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,
+            referenceHeight: touchFrame.referenceHeight
+          )
+        )
       }
       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 {
-        try mouseClickAt(app: activeApp, x: x, y: y, button: command.button ?? "primary")
-        return Response(ok: true, data: DataPayload(message: "clicked"))
+        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))
       }
@@ -234,32 +298,95 @@ 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)
+        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"))
+        return Response(
+          ok: true,
+          data: DataPayload(
+            message: "tap series",
+            gestureStartUptimeMs: timing.gestureStartUptimeMs,
+            gestureEndUptimeMs: timing.gestureEndUptimeMs,
+            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)
+      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"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "tap series",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
+          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)
+      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,
+          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)
-      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-        dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      let dragFrame = resolvedDragVisualizationFrame(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+      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"))
+      return Response(
+        ok: true,
+        data: DataPayload(
+          message: "dragged",
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs,
+          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"))
@@ -271,17 +398,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"))
@@ -304,10 +440,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"))
@@ -358,30 +506,15 @@ extension RunnerTests {
       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 {
@@ -399,17 +532,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 7c6ad4a1d..5563f5ae7 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -1,6 +1,27 @@
 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
+  }
+
+  struct GestureReferenceFrame {
+    let referenceWidth: Double
+    let referenceHeight: Double
+  }
+
   // MARK: - Navigation Gestures
 
   func tapNavigationBack(app: XCUIApplication) -> Bool {
@@ -209,6 +230,58 @@ 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 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 b60afc3ae..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,19 +76,46 @@ 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,
     found: Bool? = nil,
     items: [String]? = nil,
     nodes: [SnapshotNode]? = nil,
-    truncated: Bool? = 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,
+    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/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/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
new file mode 100644
index 000000000..984bbdb91
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -0,0 +1,571 @@
+import AppKit
+import AVFoundation
+import Foundation
+import QuartzCore
+
+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
+let trailOpacityKeyTimes: [NSNumber] = [0.0, 0.08, 0.62, 1.0]
+
+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()
+  }
+  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.")
+  }
+}
+
+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
+  let flippedY = max(0, Double(renderSize.height) - scaledY)
+  return CGPoint(x: scaledX, y: flippedY)
+}
+
+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),
+    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 = makeAnimationGroup(
+    animations: [opacity, scale],
+    duration: minimumTapVisibility,
+    beginTime: AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  )
+  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),
+    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 = makeAnimationGroup(
+    animations: [opacity, scale],
+    duration: duration,
+    beginTime: AVCoreAnimationBeginTimeAtZero + (event.tMs / 1000.0)
+  )
+  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
+}
+
+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,
+  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 + style.tail)
+  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 = style.color
+  pathLayer.lineWidth = style.lineWidth
+  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 = style.trailOpacityValues
+  strokeOpacity.keyTimes = trailOpacityKeyTimes
+
+  let strokeGroup = makeAnimationGroup(
+    animations: [stroke, strokeOpacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
+  strokeGroup.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+  pathLayer.add(strokeGroup, forKey: "stroke")
+
+  let dotLayer = makeTouchDotLayer(center: startPoint, renderSize: renderSize)
+  dotLayer.backgroundColor = style.color
+  dotLayer.borderColor = style.borderColor
+  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 = style.dotOpacityValues
+  opacity.keyTimes = trailOpacityKeyTimes
+
+  let group = makeAnimationGroup(
+    animations: [position, opacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
+  group.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+  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,
+  renderSize: CGSize,
+  beginTime: CFTimeInterval,
+  duration: CFTimeInterval
+) {
+  let dotLayer = makeTouchDotLayer(center: start, renderSize: renderSize)
+  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 = makeAnimationGroup(
+    animations: [position, opacity],
+    duration: duration,
+    beginTime: beginTime
+  )
+  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,
+    renderSize: renderSize,
+    beginTime: beginTime,
+    duration: duration
+  )
+  addPinchDot(
+    overlayLayer: overlayLayer,
+    start: startRight,
+    end: endRight,
+    renderSize: renderSize,
+    beginTime: beginTime,
+    duration: duration
+  )
+}
+
+func makeTouchDotLayer(center: CGPoint, renderSize: CGSize) -> CALayer {
+  let dotRadius = resolvedTouchDotRadius(renderSize: renderSize)
+  let layer = CALayer()
+  layer.bounds = CGRect(x: 0, y: 0, width: dotRadius * 2, height: dotRadius * 2)
+  layer.position = center
+  layer.cornerRadius = dotRadius
+  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 resolvedTouchDotRadius(renderSize: CGSize) -> CGFloat {
+  let minDimension = min(renderSize.width, renderSize.height)
+  return max(18, min(40, minDimension * 0.035))
+}
+
+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 = makeAnimationGroup(
+    animations: [opacity],
+    duration: visibleDuration,
+    beginTime: beginTime
+  )
+  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..6c17823dd
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-trim.swift
@@ -0,0 +1,140 @@
+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()
+  }
+  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.")
+  }
+}
+
+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/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 10770ddec..ac951a32d 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,
             };
           }
 
@@ -346,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
new file mode 100644
index 000000000..bb829f8be
--- /dev/null
+++ b/src/daemon/__tests__/recording-gestures.test.ts
@@ -0,0 +1,246 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { SessionState } from '../types.ts';
+import {
+  augmentScrollVisualizationResult,
+  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 = augmentScrollVisualizationResult(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 = augmentScrollVisualizationResult(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 = augmentScrollVisualizationResult(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('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 = {
+    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('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();
+
+  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('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();
+
+  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__/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/__tests__/request-router-android-modal.test.ts b/src/daemon/__tests__/request-router-android-modal.test.ts
new file mode 100644
index 000000000..98c56fe21
--- /dev/null
+++ b/src/daemon/__tests__/request-router-android-modal.test.ts
@@ -0,0 +1,105 @@
+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']);
+  assert.equal(snapshotCalls, 2);
+});
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/__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/android-system-dialog.ts b/src/daemon/android-system-dialog.ts
new file mode 100644
index 000000000..145ecad7d
--- /dev/null
+++ b/src/daemon/android-system-dialog.ts
@@ -0,0 +1,205 @@
+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 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<AndroidBlockingDialogRecoveryResult> {
+  const {
+    session,
+    snapshotAndroidUi = snapshotAndroid,
+    reopenAndroidApp = openAndroidApp,
+    readAndroidAppState = getAndroidAppState,
+    execCommand = runCmd,
+  } = params;
+
+  if (session.device.platform !== 'android' || !session.recording) {
+    return 'absent';
+  }
+
+  try {
+    const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+    const closeAppButton = findCloseAppButton(nodes);
+    if (!closeAppButton?.rect) {
+      return 'absent';
+    }
+
+    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 'failed';
+    }
+
+    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 'failed';
+    }
+
+    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 'failed';
+      }
+    }
+
+    emitDiagnostic({
+      level: 'warn',
+      phase: 'android_blocking_dialog_recovered',
+      data: {
+        session: session.name,
+        deviceId: session.device.id,
+        appBundleId: session.appBundleId,
+        x,
+        y,
+      },
+    });
+    return 'recovered';
+  } 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 'failed';
+  }
+}
+
+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 {
+  if (!containsBlockingDialog(nodes)) {
+    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) {
+    const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+    if (!containsBlockingDialog(nodes)) {
+      return true;
+    }
+    await sleep(ANDROID_MODAL_POLL_MS);
+  }
+  const nodes = await readAndroidSnapshotNodes(session, snapshotAndroidUi);
+  return !containsBlockingDialog(nodes);
+}
+
+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 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 37fb9bfb0..863d79f66 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,
@@ -60,7 +77,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 +122,222 @@ 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 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 coordinates on Android recording caches physical screen size across interactions', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-direct-press-frame-cache';
+  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);
+
+  let screenSizeReads = 0;
+  const readAndroidScreenSize = async () => {
+    screenSizeReads += 1;
+    return { width: 1344, height: 2992 };
+  };
+
+  await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['300', '2300'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    dispatch: async () => ({ x: 300, y: 2300 }),
+    readAndroidScreenSize,
+  });
+
+  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 () => {
+  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, 570);
+});
+
 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..592d3aa9f 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -4,9 +4,11 @@ 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';
+import { getRecordingOverlaySupportWarning } from '../../../recording/overlay.ts';
 
 type RecordTraceDeps = NonNullable<Parameters<typeof handleRecordTraceCommands>[0]['deps']>;
 type RunnerCall = {
@@ -18,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'));
@@ -68,7 +72,8 @@ async function runRecordCommand(params: {
   deps: RecordTraceDeps;
   logPath?: string;
   cwd?: string;
-  flags?: { fps?: number };
+  flags?: { fps?: number; hideTouches?: boolean };
+  clientArtifactPaths?: Record<string, string>;
 }) {
   return handleRecordTraceCommands({
     req: {
@@ -77,7 +82,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,
@@ -103,6 +116,9 @@ function makeRunnerRecordingDeps(
       logPath: options?.logPath,
       traceLogPath: options?.traceLogPath,
     });
+    if (command.command === 'recordStart') {
+      return { recorderStartUptimeMs: 12_345, targetAppReadyUptimeMs: 15_678 };
+    }
     return {};
   };
   return {
@@ -114,6 +130,27 @@ function makeRunnerRecordingDeps(
       throw new Error('runCmdBackground should not be used for runner-backed recording');
     },
     runIosRunnerCommand,
+    waitForStableFile: async () => {},
+    isPlayableVideo: async () => true,
+    writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
+    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 }) => deriveRecordingTelemetryPath(videoPath),
+    trimRecordingStart: async () => {},
+    overlayRecordingTouches: async () => {},
+    ...overrides,
   };
 }
 
@@ -144,6 +181,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 +189,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 +226,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, deriveRecordingTelemetryPath(finalOut));
+  assert.deepEqual(
+    responseStop?.data?.artifacts?.map((artifact) => artifact.field),
+    ['outPath', 'telemetryPath'],
+  );
+  assert.equal(responseStop?.data?.artifacts?.[1]?.path, deriveRecordingTelemetryPath(finalOut));
   assert.equal(sessionStore.get(sessionName)?.recording, undefined);
 });
 
@@ -214,7 +263,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,
@@ -231,6 +279,41 @@ 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 = makeRunnerRecordingDeps(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,
+    deriveRecordingTelemetryPath(finalOut),
+  );
+  assert.equal(responseStop?.data?.telemetryPath, deriveRecordingTelemetryPath(finalOut));
+});
+
 test('record start resolves relative output path from request cwd', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-cwd';
@@ -310,6 +393,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 }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -335,6 +423,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 }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -361,6 +454,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 }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -395,8 +493,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 }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -413,6 +516,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 +543,11 @@ test('record start does not stop recording owned by another session during desyn
         }
         return {};
       },
+      waitForStableFile: async () => {},
+      isPlayableVideo: async () => true,
+      writeRecordingTelemetry: ({ videoPath }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -456,6 +567,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 +589,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 }) => deriveRecordingTelemetryPath(videoPath),
+      trimRecordingStart: async () => {},
+      overlayRecordingTouches: async () => {},
     },
   });
 
@@ -484,6 +603,56 @@ 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 deriveRecordingTelemetryPath(videoPath);
+      },
+      overlayRecordingTouches: async ({ videoPath, telemetryPath }) => {
+        lifecycleCalls.push(`overlay:${videoPath}:${telemetryPath}`);
+      },
+    }),
+  });
+
+  assert.equal(response?.ok, true);
+  const expectedLifecycleCalls = [
+    'trim:/tmp/device.mp4:3250',
+    'telemetry:/tmp/device.mp4:1',
+  ];
+  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 () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
@@ -509,6 +678,7 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
       runCmdBackground: (cmd, args) => {
         assert.equal(cmd, 'xcrun');
         assert.deepEqual(args.slice(0, 4), ['simctl', 'io', 'sim-1', 'recordVideo']);
+        assert.equal(args[4], path.resolve('./sim.mp4'));
         started = true;
         return {
           child: {
@@ -520,8 +690,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 +711,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,63 +723,538 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
   assert.equal(stopped, true);
 });
 
-test('record keeps android pull + cleanup flow', async () => {
+test('record stop keeps iOS simulator video when overlay export fails', async () => {
   const sessionStore = makeSessionStore();
-  const sessionName = 'android';
+  const sessionName = 'ios-sim-overlay-warning';
   sessionStore.set(
     sessionName,
     makeSession(sessionName, {
-      platform: 'android',
-      id: 'emulator-5554',
-      name: 'Android',
-      kind: 'emulator',
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
       booted: true,
     }),
   );
 
-  const adbCalls: Array<string[]> = [];
   await runRecordCommand({
     sessionStore,
     sessionName,
-    positionals: ['start', './android.mp4'],
+    positionals: ['start', './sim-warning.mp4'],
     deps: {
-      runCmd: async (_cmd, args) => {
-        adbCalls.push(args);
-        return { stdout: '', stderr: '', exitCode: 0 };
+      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');
       },
-      runCmdBackground: (cmd, args) => {
-        assert.equal(cmd, 'adb');
-        assert.deepEqual(args.slice(0, 4), ['-s', 'emulator-5554', 'shell', 'screenrecord']);
+    },
+  });
+
+  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,
+    overlaySupportWarning ?? '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';
+  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 should not be used for Android');
+        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';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const adbCalls: Array<string[]> = [];
   await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    deps: makeRecordDeps({
+      runCmd: async (_cmd, args) => {
+        adbCalls.push(args);
+        if (
+          /^-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 \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+  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 }> = [];
+  const responseStop = 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 \/sdcard\/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');
+      overlayRecordingTouches: async ({ videoPath, telemetryPath }) => {
+        overlayCalls.push({ videoPath, telemetryPath });
       },
-      runIosRunnerCommand: async () => {
-        throw new Error('runner should not be used for Android');
+    }),
+  });
+
+  assert.ok(adbCalls.some((args) => args.join(' ') === '-s emulator-5554 shell kill -2 4321'));
+  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 () => {
+  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,
+    overlaySupportWarning ?? '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';
+  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(adbCalls.length, 2);
-  assert.match(adbCalls[0]?.join(' '), /pull/);
-  assert.match(adbCalls[1]?.join(' '), /shell rm -f/);
+  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 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';
+  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 \/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 \/sdcard\/agent-device-recording-\d+\.mp4$/.test(
+            args.join(' '),
+          )
+        ) {
+          return { stdout: '1024\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+  });
+
+  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 \/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 \/sdcard\/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);
+});
+
+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/__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-touch.ts b/src/daemon/handlers/interaction-touch.ts
new file mode 100644
index 000000000..d0c2b7415
--- /dev/null
+++ b/src/daemon/handlers/interaction-touch.ts
@@ -0,0 +1,728 @@
+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';
+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' || command === 'click') {
+    const commandLabel = command === 'click' ? 'click' : '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 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({
+        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 ?? {}),
+        ...resultButtonTag,
+      };
+      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: `${commandLabel} 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,
+          ...resultButtonTag,
+        },
+      });
+      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: `${commandLabel} 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,
+        ...resultButtonTag,
+      },
+    });
+    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/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..18e6a7aff
--- /dev/null
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -0,0 +1,444 @@
+import fs from 'node:fs';
+import { emitDiagnostic } from '../../utils/diagnostics.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';
+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;
+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 parseAndroidRemotePid(stdout: string): string | undefined {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^\d+$/.test(line))
+    .at(-1);
+}
+
+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 >= ANDROID_REMOTE_FILE_STABLE_POLLS) {
+        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> {
+  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;
+    }
+
+    // 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 false;
+}
+
+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 = 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);
+      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;
+            }
+          })(),
+          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_RETRY_DELAY_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';
+}
+
+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';
+
+  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) {
+      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,
+      },
+    });
+
+    if (await waitForAndroidRecordingReady(deps, device.id, remotePath, remotePid)) {
+      return {
+        platform: 'android',
+        remotePath,
+        remotePid,
+        ...recordingBase,
+        startedAt: Date.now(),
+      };
+    }
+
+    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 {
+    ok: false,
+    error: {
+      code: 'COMMAND_FAILED',
+      message: lastStartError,
+    },
+  };
+}
+
+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,
+    },
+  });
+  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(),
+    },
+  });
+  let stopError: string | undefined;
+  if (stopResult.exitCode !== 0) {
+    if (await isAndroidProcessRunning(deps, device.id, recording.remotePid)) {
+      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))) {
+      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);
+    const copyError = await copyAndroidRecordingWithValidation({
+      deps,
+      deviceId: device.id,
+      remotePath: recording.remotePath,
+      outPath: recording.outPath,
+    });
+    if (copyError) {
+      await cleanupRemoteRecording();
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: copyError,
+        },
+      };
+    }
+
+    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)}`;
+        }
+      }
+    }
+  }
+
+  await cleanupRemoteRecording();
+
+  if (stopError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: stopError,
+      },
+    };
+  }
+
+  if (cleanupError) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: cleanupError,
+      },
+    };
+  }
+
+  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
new file mode 100644
index 000000000..5307b3f0d
--- /dev/null
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -0,0 +1,416 @@
+import { SessionStore } from '../session-store.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 '../../recording/overlay.ts';
+import { formatRecordTraceError } from '../record-trace-errors.ts';
+import type { RecordTraceDeps, RecordingBase } from './record-trace-recording.ts';
+
+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 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;
+  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) {
+    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;
+}
+
+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
new file mode 100644
index 000000000..7b4032abb
--- /dev/null
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -0,0 +1,463 @@
+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 { runCmd, runCmdBackground } from '../../utils/exec.ts';
+import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
+import {
+  deriveRecordingTelemetryPath,
+  persistRecordingTelemetry,
+  writeRecordingTelemetry,
+} from '../recording-telemetry.ts';
+import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
+import {
+  getRecordingOverlaySupportWarning,
+  overlayRecordingTouches,
+  trimRecordingStart,
+} from '../../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';
+import {
+  normalizeAppBundleId,
+  startIosDeviceRecording,
+  startMacOsRecording,
+  stopMacOsRecording,
+  stopIosDeviceRecording,
+  warmIosSimulatorRunner,
+} from './record-trace-ios.ts';
+
+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_SETTLE_POLLS = 2;
+
+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 type RecordingBase = {
+  outPath: string;
+  clientOutPath?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+};
+
+export function buildRecordTraceDeps(overrides?: Partial<RecordTraceDeps>): RecordTraceDeps {
+  return {
+    runCmd,
+    runCmdBackground,
+    runIosRunnerCommand,
+    waitForStableFile,
+    isPlayableVideo,
+    writeRecordingTelemetry,
+    trimRecordingStart,
+    overlayRecordingTouches,
+    ...overrides,
+  };
+}
+
+function buildRecordingBase(req: DaemonRequest, outPath: string): RecordingBase {
+  return {
+    outPath,
+    clientOutPath: req.meta?.clientArtifactPaths?.outPath,
+    startedAt: Date.now(),
+    showTouches: req.flags?.hideTouches !== true,
+    gestureEvents: [],
+  };
+}
+
+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) {
+        return Date.now();
+      }
+    } catch {
+      // Wait for the recorder to create the output file.
+    }
+
+    if (attempt + 1 >= LOCAL_RECORDING_READY_SETTLE_POLLS) {
+      return Date.now();
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, LOCAL_RECORDING_READY_POLL_MS));
+  }
+
+  return Date.now();
+}
+
+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 === '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,
+      activeSession,
+      device,
+      logPath,
+      deps,
+    });
+    const { child, wait } = deps.runCmdBackground(
+      'xcrun',
+      buildSimctlArgsForDevice(device, ['io', device.id, 'recordVideo', resolvedOut]),
+      {
+        allowFailure: true,
+      },
+    );
+    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,
+      gestureClockOriginAtMs:
+        gestureClockOriginUptimeMs === undefined ? undefined : gestureClockOriginAtMs,
+      gestureClockOriginUptimeMs,
+    };
+  } 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 stopNonRunnerRecording(params: {
+  deps: RecordTraceDeps;
+  device: SessionState['device'];
+  recording: Extract<NonNullable<SessionState['recording']>, { platform: 'ios' | 'android' }>;
+}): 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: ${formatRecordTraceExecFailure(stopResult, 'simctl recordVideo')}`,
+      },
+    };
+  }
+
+  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: 'iOS recording',
+        });
+      } catch (error) {
+        recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+      }
+    }
+  }
+
+  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;
+  const invalidatedReason = recording.invalidatedReason;
+  activeSession.recording = undefined;
+
+  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;
+  }
+
+  if (invalidatedReason) {
+    return {
+      ok: false,
+      error: {
+        code: 'COMMAND_FAILED',
+        message: invalidatedReason,
+      },
+    };
+  }
+
+  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: 'telemetryPath',
+      path: recording.telemetryPath,
+      localPath: deriveClientTelemetryPath(recording),
+      fileName: path.basename(recording.telemetryPath),
+    });
+  }
+
+  return {
+    ok: true,
+    data: {
+      recording: 'stopped',
+      outPath: recording.outPath,
+      telemetryPath: recording.telemetryPath,
+      artifacts,
+      showTouches: recording.showTouches,
+      overlayWarning: recording.overlayWarning,
+    },
+  };
+}
+
+function deriveClientTelemetryPath(
+  recording: NonNullable<SessionState['recording']>,
+): string | undefined {
+  if (!recording.clientOutPath) {
+    return undefined;
+  }
+  return deriveRecordingTelemetryPath(recording.clientOutPath);
+}
+
+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..a07648f08 100644
--- a/src/daemon/handlers/session-replay-script.ts
+++ b/src/daemon/handlers/session-replay-script.ts
@@ -3,6 +3,7 @@ import { AppError } from '../../utils/errors.ts';
 import { appendOpenActionScriptArgs, parseReplayOpenFlags } from '../session-open-script.ts';
 import type { SessionAction, SessionState } from '../types.ts';
 import {
+  appendRecordActionScriptArgs,
   appendRuntimeHintFlags,
   appendScriptSeriesFlags,
   formatScriptArgQuoteIfNeeded,
@@ -158,6 +159,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 +276,10 @@ function formatReplayActionLine(action: SessionAction): string {
     appendRuntimeHintFlags(parts, action.flags);
     return parts.join(' ');
   }
+  if (action.command === 'record') {
+    appendRecordActionScriptArgs(parts, action);
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatScriptArg(positional));
   }
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-gestures.ts b/src/daemon/recording-gestures.ts
new file mode 100644
index 000000000..ddf3f148d
--- /dev/null
+++ b/src/daemon/recording-gestures.ts
@@ -0,0 +1,542 @@
+import type { RecordingGestureEvent, SessionState } from './types.ts';
+import type { SnapshotState } from '../utils/snapshot.ts';
+import {
+  resolveGestureDurationMs,
+  resolveGestureOffsetMs,
+  resolveTapVisualizationOffsetMs,
+} 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;
+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 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),
+    reportedDurationMs,
+    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,
+    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),
+    },
+  });
+}
+
+// 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[],
+  result: Record<string, unknown> | void,
+): Record<string, unknown> | void {
+  if (command !== 'scroll') return result;
+
+  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 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,
+    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,
+  };
+}
+
+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 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>,
+  tMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  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;
+  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 coordinates = readCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x, y } = coordinates;
+  return [makeTapEvent(tMs, x, y, referenceFrame)];
+}
+
+function buildLongPressEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  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)];
+}
+
+function buildSwipeEvents(
+  positionals: string[],
+  result: Record<string, unknown>,
+  tMs: number,
+  gestureDurationMs: number,
+  referenceFrame?: ReferenceFrame,
+): RecordingGestureEvent[] {
+  const coordinates = readTravelCoordinates(result, positionals);
+  if (!coordinates) return [];
+  const { x1, y1, x2, y2 } = coordinates;
+
+  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';
+  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 coordinates = readTravelCoordinates(result, positionals);
+  const contentDirection =
+    readDirection(result.contentDirection) ?? readDirection(result.direction);
+  if (!coordinates || !contentDirection) {
+    return [];
+  }
+  const { x1, y1, x2, y2 } = coordinates;
+
+  const durationMs = resolveDurationMs(gestureDurationMs, [], 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 coordinates = readCoordinates(result, positionals, 1);
+  const scale = readNumber(result.scale) ?? readNumber(positionals[0]);
+  if (!coordinates || scale === undefined || scale <= 0) return [];
+  const { x, y } = coordinates;
+  return [
+    {
+      kind: 'pinch',
+      tMs,
+      x,
+      y,
+      ...referenceFrame,
+      scale,
+      durationMs: resolveDurationMs(gestureDurationMs, [], 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 resolveEventReferenceFrame(
+  snapshot: SnapshotState | undefined,
+  result: Record<string, unknown>,
+): ReferenceFrame | undefined {
+  const referenceWidth = readNumber(result.referenceWidth);
+  const referenceHeight = readNumber(result.referenceHeight);
+  if (
+    referenceWidth !== undefined &&
+    referenceWidth > 0 &&
+    referenceHeight !== undefined &&
+    referenceHeight > 0
+  ) {
+    return { referenceWidth, referenceHeight };
+  }
+
+  return getSnapshotReferenceFrame(snapshot);
+}
+
+function readDirection(value: unknown): 'up' | 'down' | 'left' | 'right' | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim().toLowerCase();
+  switch (normalized) {
+    case 'up':
+    case 'down':
+    case 'left':
+    case 'right':
+      return normalized 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 scrollPoints(
+  contentDirection: 'up' | 'down' | 'left' | 'right',
+  referenceFrame: ReferenceFrame,
+  travelFraction: 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);
+  const travelY = Math.round((referenceFrame.referenceHeight * travelFraction) / 2);
+
+  switch (contentDirection) {
+    case 'up':
+      return {
+        start: { x: midX, y: midY - travelY },
+        end: { x: midX, y: midY + travelY },
+      };
+    case 'down':
+      return {
+        start: { x: midX, y: midY + travelY },
+        end: { x: midX, y: midY - travelY },
+      };
+    case 'left':
+      return {
+        start: { x: midX - travelX, y: midY },
+        end: { x: midX + travelX, y: midY },
+      };
+    case 'right':
+      return {
+        start: { x: midX + travelX, y: midY },
+        end: { x: midX - travelX, y: midY },
+      };
+  }
+}
+
+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));
+}
+
+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-telemetry.ts b/src/daemon/recording-telemetry.ts
new file mode 100644
index 000000000..bdb983421
--- /dev/null
+++ b/src/daemon/recording-telemetry.ts
@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RecordingGestureEvent } from './types.ts';
+
+type RecordingTelemetryEnvelope = {
+  version: 1;
+  generatedAt: string;
+  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`);
+}
+
+export function trimRecordingTelemetryEvents(
+  events: RecordingGestureEvent[],
+  trimStartMs: number,
+): RecordingGestureEvent[] {
+  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, 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/recording-timing.ts b/src/daemon/recording-timing.ts
new file mode 100644
index 000000000..d1bc6b486
--- /dev/null
+++ b/src/daemon/recording-timing.ts
@@ -0,0 +1,76 @@
+type GestureTimingSource = {
+  recordingStartedAt: number;
+  gestureClockOriginAtMs?: number;
+  gestureClockOriginUptimeMs?: number;
+  runnerStartedAtUptimeMs?: number;
+  gestureStartUptimeMs?: number;
+  gestureEndUptimeMs?: number;
+  fallbackStartedAtMs: number;
+  fallbackFinishedAtMs: number;
+};
+
+type GestureDurationSource = {
+  gestureStartUptimeMs?: number;
+  gestureEndUptimeMs?: number;
+  reportedDurationMs?: number;
+  fallbackStartedAtMs: number;
+  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);
+}
+
+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);
+}
+
+export function resolveTapVisualizationOffsetMs(source: TapVisualizationOffsetSource): number {
+  const durationMs = Math.max(0, source.gestureDurationMs);
+  if (durationMs < 600) {
+    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/daemon/request-router.ts b/src/daemon/request-router.ts
index d843a2ce3..9862a0bbc 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,
@@ -27,6 +33,14 @@ import {
 } from '../utils/diagnostics.ts';
 import { resolveLeaseScope } from './lease-context.ts';
 import type { LeaseRegistry } from './lease-registry.ts';
+import {
+  augmentScrollVisualizationResult,
+  recordTouchVisualizationEvent,
+} from './recording-gestures.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';
 
 const selectorValidationExemptCommands = new Set([
   'session_list',
@@ -194,6 +208,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;
@@ -205,6 +247,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(
@@ -212,6 +258,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);
@@ -258,9 +308,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 &&
@@ -336,6 +402,25 @@ export function createRequestHandler(
             });
           }
 
+          if (session.device.platform === 'android' && session.recording && command !== 'record') {
+            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 ?? [];
           const outFlag = lockedReq.flags?.out;
           const resolvedPositionals =
@@ -354,14 +439,34 @@ export function createRequestHandler(
             command === 'screenshot' && resolvedOut
               ? { ...(lockedReq.flags ?? {}), out: resolvedOut }
               : (lockedReq.flags ?? {});
-          const data = await dispatch(session.device, command, resolvedPositionals, resolvedOut, {
+          const actionStartedAt = Date.now();
+          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();
+          const visualizationData = augmentScrollVisualizationResult(
+            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/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-store.ts b/src/daemon/session-store.ts
index 9147001c4..ef0ac4aba 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -6,6 +6,7 @@ import { inferFillText } from './action-utils.ts';
 import { resolveUserPath } from '../utils/path-resolution.ts';
 import { appendOpenActionScriptArgs } from './session-open-script.ts';
 import {
+  appendRecordActionScriptArgs,
   appendRuntimeHintFlags,
   appendScriptSeriesFlags,
   formatScriptArgQuoteIfNeeded,
@@ -235,6 +236,8 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     relaunch,
     saveScript,
     noRecord,
+    fps,
+    hideTouches,
     count,
     intervalMs,
     holdMs,
@@ -263,6 +266,8 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     relaunch,
     saveScript,
     noRecord,
+    fps,
+    hideTouches,
     count,
     intervalMs,
     holdMs,
@@ -364,6 +369,10 @@ function formatActionLine(action: SessionAction): string {
     appendRuntimeHintFlags(parts, action.flags);
     return parts.join(' ');
   }
+  if (action.command === 'record') {
+    appendRecordActionScriptArgs(parts, action);
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatScriptArg(positional));
   }
diff --git a/src/daemon/touch-reference-frame.ts b/src/daemon/touch-reference-frame.ts
new file mode 100644
index 000000000..c64a4e00f
--- /dev/null
+++ b/src/daemon/touch-reference-frame.ts
@@ -0,0 +1,61 @@
+import type { Rect, SnapshotNode, SnapshotState } from '../utils/snapshot.ts';
+
+export type TouchReferenceFrame = {
+  referenceWidth: number;
+  referenceHeight: number;
+};
+
+const snapshotReferenceFrameCache = new WeakMap<SnapshotState, TouchReferenceFrame>();
+
+export function getSnapshotReferenceFrame(
+  snapshot: SnapshotState | undefined,
+): TouchReferenceFrame | undefined {
+  if (!snapshot) return undefined;
+  const cached = snapshotReferenceFrameCache.get(snapshot);
+  if (cached) return cached;
+
+  const inferred = inferTouchReferenceFrame(snapshot.nodes ?? []);
+  if (!inferred) return undefined;
+  snapshotReferenceFrameCache.set(snapshot, inferred);
+  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 09dd7597c..4b506e14f 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -69,6 +69,61 @@ 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;
+  overlayWarning?: string;
+  startedAt: number;
+  showTouches: boolean;
+  gestureEvents: RecordingGestureEvent[];
+  touchReferenceFrame?: {
+    referenceWidth: number;
+    referenceHeight: number;
+  };
+  gestureClockOriginAtMs?: number;
+  gestureClockOriginUptimeMs?: number;
+  runnerSessionId?: string;
+  invalidatedReason?: string;
+};
+
 export type SessionState = {
   name: string;
   device: DeviceInfo;
@@ -84,20 +139,27 @@ 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>;
-      }
-    | {
-        platform: 'ios-device-runner' | 'macos-runner';
-        outPath: string;
-        clientOutPath?: string;
         remotePath?: string;
-      };
+      })
+    | (SessionRecordingBase & {
+        platform: 'android';
+        remotePath: string;
+        remotePid: string;
+      })
+    | (SessionRecordingBase & {
+        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?: {
     platform: Platform;
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__/recording-scripts.test.ts b/src/platforms/ios/__tests__/recording-scripts.test.ts
new file mode 100644
index 000000000..16a7dd710
--- /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',
+);
+const recordingTestSupportDir = path.resolve(__dirname, '../../../../test/integration/support');
+
+async function assertSwiftScriptTypechecks(scriptPath: string): Promise<void> {
+  const result = await runCmd('xcrun', ['swiftc', '-typecheck', scriptPath], {
+    allowFailure: true,
+  });
+  assert.equal(result.exitCode, 0, `${path.basename(scriptPath)} 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(path.join(recordingScriptsDir, '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(path.join(recordingScriptsDir, '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(path.join(recordingTestSupportDir, '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/__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..c8c313524 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,
@@ -44,6 +45,7 @@ export type RunnerCommand = {
     | 'pinch'
     | 'recordStart'
     | 'recordStop'
+    | 'uptime'
     | 'shutdown';
   appBundleId?: string;
   text?: string;
@@ -163,6 +165,7 @@ export {
 } from './runner-xctestrun.ts';
 
 export {
+  getRunnerSessionSnapshot,
   stopIosRunnerSession,
   abortAllIosRunnerSessions,
   stopAllIosRunnerSessions,
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/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..e18fac1ef 100644
--- a/src/platforms/ios/runner-xctestrun.ts
+++ b/src/platforms/ios/runner-xctestrun.ts
@@ -63,7 +63,7 @@ export const IOS_RUNNER_CONTAINER_BUNDLE_IDS: string[] = resolveRunnerContainerB
 
 type EnsureXctestrunDeps = {
   findProjectRoot: () => string;
-  findXctestrun: (root: string) => string | null;
+  findXctestrun: (root: string, device?: DeviceInfo) => string | null;
   xctestrunReferencesProjectRoot: (xctestrunPath: string, projectRoot: string) => boolean;
   resolveExistingXctestrunProductPaths: (xctestrunPath: string) => string[] | null;
   repairRunnerProductsIfNeeded: (
@@ -108,7 +108,7 @@ export async function ensureXctestrun(
     const existing = evaluateExistingXctestrun({
       derived,
       projectRoot,
-      findXctestrun: deps.findXctestrun,
+      findXctestrun: (root) => deps.findXctestrun(root, device),
       xctestrunReferencesProjectRoot: deps.xctestrunReferencesProjectRoot,
       resolveExistingXctestrunProductPaths: deps.resolveExistingXctestrunProductPaths,
     });
@@ -158,7 +158,7 @@ export async function ensureXctestrun(
 
     await deps.buildRunnerXctestrun(device, projectPath, derived, options);
 
-    const built = deps.findXctestrun(derived);
+    const built = deps.findXctestrun(derived, device);
     if (!built) {
       throw new AppError('COMMAND_FAILED', 'Failed to locate .xctestrun after build');
     }
@@ -209,9 +209,14 @@ export function shouldDeleteRunnerDerivedRootEntry(entryName: string): boolean {
   return RUNNER_ROOT_TRANSIENT_ENTRY_NAMES.has(entryName);
 }
 
-function findXctestrun(root: string): string | null {
+type XctestrunCandidate = {
+  path: string;
+  mtimeMs: number;
+};
+
+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,10 +238,85 @@ function findXctestrun(root: string): string | null {
     }
   }
   if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  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;
 }
 
+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;
+    }
+  }
+
+  if (platformHints.disallowed.some((hint) => normalizedPath.includes(hint))) {
+    score -= 2_500;
+  }
+
+  return score;
+}
+
+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', 'macos'],
+      };
+    }
+    return {
+      preferred: ['appletvos'],
+      disallowed: ['appletvsimulator', 'iphoneos', 'iphonesimulator', 'macos'],
+    };
+  }
+
+  if (device.kind === 'simulator') {
+    return {
+      preferred: ['iphonesimulator'],
+      disallowed: ['iphoneos', 'appletvos', 'appletvsimulator', 'macos'],
+    };
+  }
+
+  return {
+    preferred: ['iphoneos'],
+    disallowed: ['iphonesimulator', 'appletvos', 'appletvsimulator', 'macos'],
+  };
+}
+
 export function xctestrunReferencesProjectRoot(
   xctestrunPath: string,
   projectRoot: string,
diff --git a/src/recording/overlay.ts b/src/recording/overlay.ts
new file mode 100644
index 000000000..d10354cd1
--- /dev/null
+++ b/src/recording/overlay.ts
@@ -0,0 +1,142 @@
+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}`, {
+    hint: 'Ensure ios-runner/AgentDeviceRunner/RecordingScripts is present in this checkout or bundled with the package.',
+    scriptName,
+    searchedPaths: scriptCandidates,
+  });
+}
+
+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;
+}
+
+function getTrimScriptPath(): string {
+  trimScriptPath ??= resolveScriptPath('recording-trim.swift');
+  return trimScriptPath;
+}
+
+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: getTrimScriptPath(),
+    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: getOverlayScriptPath(),
+    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/__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/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/interactors.ts b/src/utils/interactors.ts
index 9a2ed5146..0418f6034 100644
--- a/src/utils/interactors.ts
+++ b/src/utils/interactors.ts
@@ -48,14 +48,20 @@ 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>;
-  scroll(direction: string, amount?: number): Promise<void>;
+  fill(x: number, y: number, text: string): Promise<Record<string, unknown> | 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>;
@@ -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,17 +246,18 @@ function iosRunnerOverrides(
           { command: 'type', text, clearFirst: true, appBundleId: ctx.appBundleId },
           runnerOpts,
         );
+        return tapResult;
       },
       scroll: async (direction, _amount) => {
         if (!['up', 'down', 'left', 'right'].includes(direction)) {
           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
new file mode 100644
index 000000000..996f1bf83
--- /dev/null
+++ b/src/utils/video.ts
@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { AppError } from './errors.ts';
+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> {
+  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;
+  }
+}
+
+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));
+  }
+}
+
+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));
+        }
+
+        // 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;
+        }
+        offset += atomSize;
+      }
+      return atoms;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return [];
+  }
+}
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/support/recording-inspect.swift b/test/integration/support/recording-inspect.swift
new file mode 100644
index 000000000..58658cec2
--- /dev/null
+++ b/test/integration/support/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/test/integration/test-helpers.ts b/test/integration/test-helpers.ts
index 155fe0fe8..ccc5e08c3 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,73 @@ 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('test/integration/support/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 813deceaf..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
@@ -486,7 +490,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.