@rejourneyco/react-native 1.0.8 → 1.0.9

package/ios/Recording/ReplayOrchestrator.swift

@@ -20,15 +20,15 @@ import QuartzCore
 
 @objc(ReplayOrchestrator)
 public final class ReplayOrchestrator: NSObject {
-    
+
     @objc public static let shared = ReplayOrchestrator()
-    
+
     @objc public var apiToken: String?
     @objc public var replayId: String?
     @objc public var replayStartMs: UInt64 = 0
     @objc public var deferredUploadMode = false
     @objc public var frameBundleSize: Int = 5
-    
+
     public var serverEndpoint: String {
         get { TelemetryPipeline.shared.endpoint }
         set {
@@ -37,7 +37,7 @@ public final class ReplayOrchestrator: NSObject {
             DeviceRegistrar.shared.endpoint = newValue
         }
     }
-    
+
     @objc public var snapshotInterval: Double = 1.0
     @objc public var compressionLevel: Double = 0.5
     @objc public var visualCaptureEnabled: Bool = true
@@ -49,30 +49,30 @@ public final class ReplayOrchestrator: NSObject {
     @objc public var hierarchyCaptureEnabled: Bool = true
     @objc public var hierarchyCaptureInterval: Double = 2.0
     @objc public private(set) var currentScreenName: String?
-    
+
     // Remote config from backend (set via setRemoteConfig before session start)
     @objc public private(set) var remoteRejourneyEnabled: Bool = true
     @objc public private(set) var remoteRecordingEnabled: Bool = true
     @objc public private(set) var remoteSampleRate: Int = 100
     @objc public private(set) var remoteMaxRecordingMinutes: Int = 10
-    
+
     private var _netMonitor: NWPathMonitor?
     private var _netReady = false
     private var _live = false
-    
+
     // Network state tracking
     @objc public private(set) var currentNetworkType: String = "unknown"
     @objc public private(set) var currentCellularGeneration: String = "unknown"
     @objc public private(set) var networkIsConstrained: Bool = false
     @objc public private(set) var networkIsExpensive: Bool = false
-    
+
     // App startup tracking - use actual process start time from kernel
     private static var processStartTime: TimeInterval = {
         // Get the actual process start time from the kernel
         var kinfo = kinfo_proc()
         var size = MemoryLayout<kinfo_proc>.stride
         var mib: [Int32] = [CTL_KERN, KERN_PROC, KERN_PROC_PID, getpid()]
-        
+
         if sysctl(&mib, UInt32(mib.count), &kinfo, &size, nil, 0) == 0 {
             let startSec = kinfo.kp_proc.p_starttime.tv_sec
             let startUsec = kinfo.kp_proc.p_starttime.tv_usec
@@ -81,7 +81,7 @@ public final class ReplayOrchestrator: NSObject {
         // Fallback to current time if sysctl fails
         return Date().timeIntervalSince1970
     }()
-    
+
     private var _crashCount = 0
     private var _freezeCount = 0
     private var _errorCount = 0
@@ -97,20 +97,21 @@ public final class ReplayOrchestrator: NSObject {
     private var _hierarchyTimer: Timer?
     private var _lastHierarchyHash: String?
     private var _durationLimitTimer: DispatchWorkItem?
-    
+    private let lifecycleContractVersion = 2
+
     private override init() {
         super.init()
     }
-    
+
     /// Fast session start using existing credentials - skips credential fetch for faster restart
     @objc public func beginReplayFast(apiToken: String, serverEndpoint: String, credential: String, captureSettings: [String: Any]? = nil) {
         let perf = PerformanceSnapshot.capture()
         DiagnosticLog.debugSessionCreate(phase: "ORCHESTRATOR_FAST_INIT", details: "beginReplayFast with existing credential", perf: perf)
-        
+
         self.apiToken = apiToken
         self.serverEndpoint = serverEndpoint
         _applySettings(captureSettings)
-        
+
         // Set credentials AND endpoint directly without network fetch
         TelemetryPipeline.shared.apiToken = apiToken
         TelemetryPipeline.shared.credential = credential
@@ -118,45 +119,45 @@ public final class ReplayOrchestrator: NSObject {
         SegmentDispatcher.shared.apiToken = apiToken
         SegmentDispatcher.shared.credential = credential
         SegmentDispatcher.shared.endpoint = serverEndpoint
-        
+
         // Skip network monitoring, assume network is available since we just came from background
         DispatchQueue.main.async { [weak self] in
             self?._beginRecording(token: apiToken)
         }
     }
-    
+
     @objc public func beginReplay(apiToken: String, serverEndpoint: String, captureSettings: [String: Any]? = nil) {
         let perf = PerformanceSnapshot.capture()
         DiagnosticLog.debugSessionCreate(phase: "ORCHESTRATOR_INIT", details: "beginReplay", perf: perf)
-        
+
         self.apiToken = apiToken
         self.serverEndpoint = serverEndpoint
         _applySettings(captureSettings)
-        
+
         DiagnosticLog.debugSessionCreate(phase: "CREDENTIAL_START", details: "Requesting device credential")
-        
+
         DeviceRegistrar.shared.obtainCredential(apiToken: apiToken) { [weak self] ok, cred in
             guard let self, ok else {
                 DiagnosticLog.debugSessionCreate(phase: "CREDENTIAL_FAIL", details: "Failed")
                 return
             }
-            
+
             TelemetryPipeline.shared.apiToken = apiToken
             TelemetryPipeline.shared.credential = cred
             SegmentDispatcher.shared.apiToken = apiToken
             SegmentDispatcher.shared.credential = cred
-            
+
             self._monitorNetwork(token: apiToken)
         }
     }
-    
+
     @objc public func beginDeferredReplay(apiToken: String, serverEndpoint: String, captureSettings: [String: Any]? = nil) {
         self.apiToken = apiToken
         self.serverEndpoint = serverEndpoint
         deferredUploadMode = true
-        
+
         _applySettings(captureSettings)
-        
+
         DeviceRegistrar.shared.obtainCredential(apiToken: apiToken) { [weak self] ok, cred in
             guard let self, ok else { return }
             TelemetryPipeline.shared.apiToken = apiToken
@@ -164,53 +165,61 @@ public final class ReplayOrchestrator: NSObject {
             SegmentDispatcher.shared.apiToken = apiToken
             SegmentDispatcher.shared.credential = cred
         }
-        
+
         _initSession()
         TelemetryPipeline.shared.activateDeferredMode()
-        
+
         let renderCfg = _computeRender(fps: 1, tier: "standard")
-        
+
         if visualCaptureEnabled {
             VisualCapture.shared.configure(snapshotInterval: renderCfg.interval, jpegQuality: renderCfg.quality)
             VisualCapture.shared.beginCapture(sessionOrigin: replayStartMs)
             VisualCapture.shared.activateDeferredMode()
         }
-        
+
         if interactionCaptureEnabled { InteractionRecorder.shared.activate() }
         if faultTrackingEnabled { FaultTracker.shared.activate() }
-        
+
         _live = true
     }
-    
+
     @objc public func commitDeferredReplay() {
         deferredUploadMode = false
         TelemetryPipeline.shared.commitDeferredData()
         VisualCapture.shared.commitDeferredData()
         TelemetryPipeline.shared.activate()
     }
-    
+
     @objc public func endReplay() {
         endReplay(completion: nil)
     }
-    
+
     @objc public func endReplay(completion: ((Bool, Bool) -> Void)?) {
+        endReplayInternal(reason: "unspecified", completion: completion)
+    }
+
+    @objc public func endReplayWithReason(_ endReason: String, completion: ((Bool, Bool) -> Void)? = nil) {
+        endReplayInternal(reason: endReason, completion: completion)
+    }
+
+    private func endReplayInternal(reason endReason: String, completion: ((Bool, Bool) -> Void)?) {
         guard _live else {
             completion?(false, false)
             return
         }
         _live = false
-        
+
         let sid = replayId ?? ""
         let termMs = UInt64(Date().timeIntervalSince1970 * 1000)
         let elapsed = Int((termMs - replayStartMs) / 1000)
-        
+
         _netMonitor?.cancel()
         _netMonitor = nil
         _hierarchyTimer?.invalidate()
         _hierarchyTimer = nil
         _stopDurationLimitTimer()
         _detachLifecycle()
-        
+
         let metrics: [String: Any] = [
             "crashCount": _crashCount,
             "anrCount": _freezeCount,
@@ -225,52 +234,54 @@ public final class ReplayOrchestrator: NSObject {
             "screenCount": Set(_visitedScreens).count
         ]
         let queueDepthAtFinalize = TelemetryPipeline.shared.getQueueDepth()
-        
-        SegmentDispatcher.shared.evaluateReplayRetention(replayId: sid, metrics: metrics) { [weak self] retain, reason in
+
+        // Do local teardown immediately so lifecycle rollover never depends on network latency.
+        DispatchQueue.main.async {
+            TelemetryPipeline.shared.shutdown()
+            VisualCapture.shared.halt()
+            InteractionRecorder.shared.deactivate()
+            FaultTracker.shared.deactivate()
+            ResponsivenessWatcher.shared.halt()
+        }
+        SegmentDispatcher.shared.shipPending()
+
+        guard !_finalized else {
+            _clearRecovery()
+            completion?(true, true)
+            replayId = nil
+            replayStartMs = 0
+            return
+        }
+        _finalized = true
+
+        SegmentDispatcher.shared.evaluateReplayRetention(replayId: sid, metrics: metrics) { [weak self] _, _ in
             guard let self else { return }
-            
-            // UI operations MUST run on main thread
-            DispatchQueue.main.async {
-                TelemetryPipeline.shared.shutdown()
-                VisualCapture.shared.halt()
-                InteractionRecorder.shared.deactivate()
-                FaultTracker.shared.deactivate()
-                ResponsivenessWatcher.shared.halt()
-            }
-            
-            SegmentDispatcher.shared.shipPending()
-            
-            guard !self._finalized else {
-                self._clearRecovery()
-                completion?(true, true)
-                return
-            }
-            self._finalized = true
-            
             SegmentDispatcher.shared.concludeReplay(
                 replayId: sid,
                 concludedAt: termMs,
                 backgroundDurationMs: self._bgTimeMs,
                 metrics: metrics,
-                currentQueueDepth: queueDepthAtFinalize
+                currentQueueDepth: queueDepthAtFinalize,
+                endReason: endReason,
+                lifecycleVersion: self.lifecycleContractVersion
             ) { [weak self] ok in
                 if ok { self?._clearRecovery() }
                 completion?(true, ok)
             }
         }
-        
+
         replayId = nil
         replayStartMs = 0
     }
-    
+
     @objc public func redactView(_ view: UIView) {
         VisualCapture.shared.registerRedaction(view)
     }
-    
+
     @objc public func unredactView(_ view: UIView) {
         VisualCapture.shared.unregisterRedaction(view)
     }
-    
+
     /// Set remote configuration from backend
     /// Called by JS side before startSession to apply server-side settings
     @objc public func setRemoteConfig(
@@ -283,88 +294,130 @@ public final class ReplayOrchestrator: NSObject {
         self.remoteRecordingEnabled = recordingEnabled
         self.remoteSampleRate = sampleRate
         self.remoteMaxRecordingMinutes = maxRecordingMinutes
-        
+
         // Set isSampledIn for server-side enforcement
         // recordingEnabled=false means either dashboard disabled OR session sampled out by JS
         TelemetryPipeline.shared.isSampledIn = recordingEnabled
-        
+
         // Apply recording settings immediately
         // If recording is disabled, disable visual capture
         if !recordingEnabled {
             visualCaptureEnabled = false
             DiagnosticLog.trace("[ReplayOrchestrator] Visual capture disabled by remote config (recordingEnabled=false)")
         }
-        
+
         // If already recording, restart the duration limit timer with updated config
         if _live {
             _startDurationLimitTimer()
         }
-        
+
         DiagnosticLog.trace("[ReplayOrchestrator] Remote config applied: rejourneyEnabled=\(rejourneyEnabled), recordingEnabled=\(recordingEnabled), sampleRate=\(sampleRate)%, maxRecording=\(maxRecordingMinutes)min, isSampledIn=\(recordingEnabled)")
     }
-    
+
     @objc public func attachAttribute(key: String, value: String) {
         TelemetryPipeline.shared.recordAttribute(key: key, value: value)
     }
-    
+
     @objc public func recordCustomEvent(name: String, payload: String?) {
         TelemetryPipeline.shared.recordCustomEvent(name: name, payload: payload ?? "")
     }
-    
+
     @objc public func associateUser(_ userId: String) {
         TelemetryPipeline.shared.recordUserAssociation(userId)
     }
-    
+
     @objc public func currentReplayId() -> String {
         replayId ?? ""
     }
-    
+
     @objc public func activateGestureRecording() {
     }
-    
+
     @objc public func recoverInterruptedReplay(completion: @escaping (String?) -> Void) {
         guard let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
             completion(nil)
             return
         }
-        
+
         let path = docs.appendingPathComponent("rejourney_recovery.json")
-        
+
         guard let data = try? Data(contentsOf: path),
               let checkpoint = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let recId = checkpoint["replayId"] as? String else {
             completion(nil)
             return
         }
-        
+
         let origStart = checkpoint["startMs"] as? UInt64 ?? 0
         let nowMs = UInt64(Date().timeIntervalSince1970 * 1000)
-        
+
+        DiagnosticLog.notice("[ReplayOrchestrator] Recovering interrupted session: \(recId)")
+
         if let token = checkpoint["apiToken"] as? String {
             SegmentDispatcher.shared.apiToken = token
         }
         if let endpoint = checkpoint["endpoint"] as? String {
             SegmentDispatcher.shared.endpoint = endpoint
         }
-        
-        let crashMetrics: [String: Any] = [
-            "crashCount": 1,
-            "durationSeconds": Int((nowMs - origStart) / 1000)
-        ]
-        let queueDepthAtFinalize = TelemetryPipeline.shared.getQueueDepth()
-        
-        SegmentDispatcher.shared.concludeReplay(
-            replayId: recId,
-            concludedAt: nowMs,
-            backgroundDurationMs: 0,
-            metrics: crashMetrics,
-            currentQueueDepth: queueDepthAtFinalize
-        ) { [weak self] ok in
-            self?._clearRecovery()
-            completion(ok ? recId : nil)
-        }
-    }
-    
+        if let credential = checkpoint["credential"] as? String {
+            SegmentDispatcher.shared.credential = credential
+        }
+        SegmentDispatcher.shared.currentReplayId = recId
+        SegmentDispatcher.shared.activate()
+        TelemetryPipeline.shared.currentReplayId = recId
+        let hasCrashIncident = _hasStoredCrashIncident(for: recId)
+
+        let finalizeRecoveredSession = { [weak self] in
+            let crashMetrics: [String: Any] = [
+                "crashCount": hasCrashIncident ? 1 : 0,
+                "durationSeconds": Int((nowMs - origStart) / 1000)
+            ]
+            let queueDepthAtFinalize = TelemetryPipeline.shared.getQueueDepth()
+
+            SegmentDispatcher.shared.concludeReplay(
+                replayId: recId,
+                concludedAt: nowMs,
+                backgroundDurationMs: 0,
+                metrics: crashMetrics,
+                currentQueueDepth: queueDepthAtFinalize,
+                endReason: "recovery_finalize",
+                lifecycleVersion: self?.lifecycleContractVersion
+            ) { ok in
+                DiagnosticLog.notice("[ReplayOrchestrator] Crash recovery finalize: success=\(ok), sessionId=\(recId)")
+                if ok { self?._clearRecovery() }
+                completion(ok ? recId : nil)
+            }
+        }
+
+        VisualCapture.shared.uploadPendingFrames(sessionId: recId) { uploaded in
+            guard uploaded else {
+                DiagnosticLog.caution("[ReplayOrchestrator] Crash recovery postponed: pending frame upload failed for session \(recId)")
+                completion(nil)
+                return
+            }
+            finalizeRecoveredSession()
+        }
+    }
+
+    private func _hasStoredCrashIncident(for sessionId: String) -> Bool {
+        guard let cacheDir = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else {
+            return false
+        }
+
+        let incidentPath = cacheDir.appendingPathComponent("rj_incidents.json")
+        guard let data = try? Data(contentsOf: incidentPath),
+              let incident = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return false
+        }
+
+        let incidentSessionId = incident["sessionId"] as? String ?? ""
+        let category = (incident["category"] as? String ?? "").lowercased()
+        let crashLikeCategory = category == "signal" || category == "exception" || category == "crash"
+        let identifier = incident["identifier"] as? String ?? ""
+        let detail = incident["detail"] as? String ?? ""
+        return crashLikeCategory && incidentSessionId == sessionId && (!identifier.isEmpty || !detail.isEmpty)
+    }
+
     @objc public func incrementFaultTally() { _crashCount += 1 }
     @objc public func incrementStalledTally() { _freezeCount += 1 }
     @objc public func incrementExceptionTally() { _errorCount += 1 }
@@ -373,20 +426,20 @@ public final class ReplayOrchestrator: NSObject {
     @objc public func incrementGestureTally() { _gestureCount += 1 }
     @objc public func incrementRageTapTally() { _rageCount += 1 }
     @objc public func incrementDeadTapTally() { _deadTapCount += 1 }
-    
+
     @objc public func logScreenView(_ screenId: String) {
         guard !screenId.isEmpty else { return }
         _visitedScreens.append(screenId)
         currentScreenName = screenId
         if hierarchyCaptureEnabled { _captureHierarchy() }
     }
-    
+
     private func _initSession() {
         replayStartMs = UInt64(Date().timeIntervalSince1970 * 1000)
         let uuidPart = UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
         replayId = "session_\(replayStartMs)_\(uuidPart)"
         _finalized = false
-        
+
         _crashCount = 0
         _freezeCount = 0
         _errorCount = 0
@@ -398,28 +451,28 @@ public final class ReplayOrchestrator: NSObject {
         _visitedScreens.removeAll()
         _bgTimeMs = 0
         _bgStartMs = nil
-        
+
         TelemetryPipeline.shared.currentReplayId = replayId
         SegmentDispatcher.shared.currentReplayId = replayId
         StabilityMonitor.shared.currentSessionId = replayId
-        
+
         _attachLifecycle()
         _saveRecovery()
-        
+
         // Record app startup time
         _recordAppStartup()
     }
-    
+
     private func _recordAppStartup() {
         let nowSec = Date().timeIntervalSince1970
         let startupDurationMs = Int64((nowSec - ReplayOrchestrator.processStartTime) * 1000)
-        
+
         // Only record if it's a reasonable startup time (> 0 and < 60 seconds)
         guard startupDurationMs > 0 && startupDurationMs < 60000 else { return }
-        
+
         TelemetryPipeline.shared.recordAppStartup(durationMs: startupDurationMs)
     }
-    
+
     private func _applySettings(_ cfg: [String: Any]?) {
         guard let cfg else { return }
         snapshotInterval = cfg["captureRate"] as? Double ?? 0.33
@@ -432,7 +485,7 @@ public final class ReplayOrchestrator: NSObject {
         wifiRequired = cfg["wifiOnly"] as? Bool ?? false
         frameBundleSize = cfg["screenshotBatchSize"] as? Int ?? 5
     }
-    
+
     private func _monitorNetwork(token: String) {
         _netMonitor = NWPathMonitor()
         _netMonitor?.pathUpdateHandler = { [weak self] path in
@@ -440,10 +493,10 @@ public final class ReplayOrchestrator: NSObject {
         }
         _netMonitor?.start(queue: DispatchQueue.global(qos: .utility))
     }
-    
+
     private func handlePathChange(path: NWPath, token: String) {
         let canProceed: Bool
-        
+
         if path.status != .satisfied {
             canProceed = false
         } else if wifiRequired && !path.isExpensive {
@@ -453,12 +506,12 @@ public final class ReplayOrchestrator: NSObject {
         } else {
             canProceed = true
         }
-        
+
         // Extract network interface type
         let networkType: String
         let isExpensive = path.isExpensive
         let isConstrained = path.isConstrained
-        
+
         if path.status != .satisfied {
             networkType = "none"
         } else if path.usesInterfaceType(.wifi) {
@@ -472,113 +525,121 @@ public final class ReplayOrchestrator: NSObject {
         } else {
             networkType = "other"
         }
-        
+
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
             self._netReady = canProceed
             self.currentNetworkType = networkType
             self.networkIsExpensive = isExpensive
             self.networkIsConstrained = isConstrained
-            
+
             if canProceed && !self._live {
                 self._beginRecording(token: token)
             }
         }
     }
-    
+
     private func _beginRecording(token: String) {
         guard !_live else { return }
         _live = true
-        
+
         self.apiToken = token
         _initSession()
-        
+
         // Reactivate the dispatcher in case it was halted from a previous session
         SegmentDispatcher.shared.activate()
         TelemetryPipeline.shared.activate()
-        
+
         let renderCfg = _computeRender(fps: 1, tier: "standard")
         VisualCapture.shared.configure(snapshotInterval: renderCfg.interval, jpegQuality: renderCfg.quality)
-        
+
         if visualCaptureEnabled { VisualCapture.shared.beginCapture(sessionOrigin: replayStartMs) }
         if interactionCaptureEnabled { InteractionRecorder.shared.activate() }
         if faultTrackingEnabled { FaultTracker.shared.activate() }
         if responsivenessCaptureEnabled { ResponsivenessWatcher.shared.activate() }
         if hierarchyCaptureEnabled { _startHierarchyCapture() }
-        
+
         // Start duration limit timer based on remote config
         _startDurationLimitTimer()
     }
-    
+
     // MARK: - Duration Limit Timer
-    
+
     private func _startDurationLimitTimer() {
         _stopDurationLimitTimer()
-        
+
         let maxMinutes = remoteMaxRecordingMinutes
         guard maxMinutes > 0 else { return }
-        
+
         let maxMs = UInt64(maxMinutes) * 60 * 1000
         let now = UInt64(Date().timeIntervalSince1970 * 1000)
         let elapsed = now - replayStartMs
         let remaining = maxMs > elapsed ? maxMs - elapsed : 0
-        
+
         guard remaining > 0 else {
             DiagnosticLog.trace("[ReplayOrchestrator] Duration limit already exceeded, stopping session")
-            endReplay()
+            endReplayWithReason("duration_limit")
             return
         }
-        
+
         let workItem = DispatchWorkItem { [weak self] in
             guard let self, self._live else { return }
             DiagnosticLog.trace("[ReplayOrchestrator] Recording duration limit reached (\(maxMinutes)min), stopping session")
-            self.endReplay()
+            self.endReplayWithReason("duration_limit")
         }
         _durationLimitTimer = workItem
         DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(Int(remaining)), execute: workItem)
-        
+
         DiagnosticLog.trace("[ReplayOrchestrator] Duration limit timer set: \(remaining / 1000)s remaining (max \(maxMinutes)min)")
     }
-    
+
     private func _stopDurationLimitTimer() {
         _durationLimitTimer?.cancel()
         _durationLimitTimer = nil
     }
-    
+
     private func _saveRecovery() {
         guard let sid = replayId, let token = apiToken else { return }
-        let checkpoint: [String: Any] = ["replayId": sid, "apiToken": token, "startMs": replayStartMs, "endpoint": serverEndpoint]
+        var checkpoint: [String: Any] = ["replayId": sid, "apiToken": token, "startMs": replayStartMs, "endpoint": serverEndpoint]
+        if let cred = SegmentDispatcher.shared.credential {
+            checkpoint["credential"] = cred
+        }
         guard let data = try? JSONSerialization.data(withJSONObject: checkpoint),
               let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return }
         try? data.write(to: docs.appendingPathComponent("rejourney_recovery.json"))
     }
-    
+
     private func _clearRecovery() {
         guard let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return }
         try? FileManager.default.removeItem(at: docs.appendingPathComponent("rejourney_recovery.json"))
     }
-    
+
     private func _attachLifecycle() {
         NotificationCenter.default.addObserver(self, selector: #selector(_onBackground), name: UIApplication.didEnterBackgroundNotification, object: nil)
         NotificationCenter.default.addObserver(self, selector: #selector(_onForeground), name: UIApplication.willEnterForegroundNotification, object: nil)
     }
-    
+
     private func _detachLifecycle() {
         NotificationCenter.default.removeObserver(self, name: UIApplication.didEnterBackgroundNotification, object: nil)
         NotificationCenter.default.removeObserver(self, name: UIApplication.willEnterForegroundNotification, object: nil)
     }
-    
+
     @objc private func _onBackground() {
         _bgStartMs = UInt64(Date().timeIntervalSince1970 * 1000)
+        ResponsivenessWatcher.shared.halt()
     }
-    
+
     @objc private func _onForeground() {
         guard let start = _bgStartMs else { return }
         let now = UInt64(Date().timeIntervalSince1970 * 1000)
         _bgTimeMs += (now - start)
         _bgStartMs = nil
+
+        if responsivenessCaptureEnabled {
+            ResponsivenessWatcher.shared.activate()
+        }
     }
-    
+
     private func _startHierarchyCapture() {
         _hierarchyTimer?.invalidate()
         // Industry standard: Use default run loop mode (NOT .common)
@@ -586,38 +647,38 @@ public final class ReplayOrchestrator: NSObject {
         _hierarchyTimer = Timer.scheduledTimer(withTimeInterval: hierarchyCaptureInterval, repeats: true) { [weak self] _ in
             self?._captureHierarchy()
         }
-        
+
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
             self?._captureHierarchy()
         }
     }
-    
+
     private func _captureHierarchy() {
         guard _live, let sid = replayId else { return }
         if !Thread.isMainThread {
             DispatchQueue.main.async { [weak self] in self?._captureHierarchy() }
             return
         }
-        
+
         // Throttle hierarchy capture when map is visible and animating —
         // hierarchy scanning traverses the full view tree including the
         // map's deep Metal/GL subviews, adding main-thread pressure.
         if SpecialCases.shared.mapVisible && !SpecialCases.shared.mapIdle {
             return
         }
-        
+
         guard let hierarchy = ViewHierarchyScanner.shared.captureHierarchy() else { return }
-        
+
         let hash = _hierarchyHash(hierarchy)
         if hash == _lastHierarchyHash { return }
         _lastHierarchyHash = hash
-        
+
         guard let json = try? JSONSerialization.data(withJSONObject: hierarchy) else { return }
         let ts = UInt64(Date().timeIntervalSince1970 * 1000)
-        
+
         SegmentDispatcher.shared.transmitHierarchy(replayId: sid, hierarchyPayload: json, timestampMs: ts, completion: nil)
     }
-    
+
     private func _hierarchyHash(_ h: [String: Any]) -> String {
         let screen = currentScreenName ?? "unknown"
         var childCount = 0