Recover from route changes and background relaunches

Silent audio also stops when the audio route disappears and when media
services reset, and neither posts an interruption notification, so nothing
noticed. A day of device logs shows three silent deaths with zero
interruptions while the phone moved in and out of CarPlay. Route changes and
media services resets are now observed and recover through the same ladder.
Recovery runs for a route appearing or disappearing; a category change never
recovers, because playAudio sets the category itself and an alarm takes over
the session that way. Other reasons are logged so a later log can earn them a
recovery.

A process launched into the background by BGAppRefreshTask never runs the
backgrounding transition, so it had no interruption, route or media services
observers and no background alerts armed. Observers are now attached whenever
audio is restarted, and a background recovery arms the alerts, which also
clears any delivered notification the recovery has just made obsolete. The
task scheduler is kicked on recovery so the alerts are re-armed from the
moment runtime returns. Alerts are only armed while backgrounded, since the
task's work lands on the main queue and the app may have been opened in
between.

The runtime gap is measured against a monotonic clock, so a wall clock
correction cannot hide a stall, and a material difference between the two is
reported. A scheduler park that outlives the moment between a task firing and
its action rescheduling it is now reported with its duration.

Author: bjorkert

LoopFollow/Controllers/BackgroundAlertManager.swift

@@ -64,14 +64,14 @@ class BackgroundAlertManager {
     func scheduleBackgroundAlert(force: Bool = false) {
         guard isAlertScheduled, Storage.shared.backgroundRefreshType.value != .none else { return }
 
-        // Throttle execution if not forced: only run once every 10 seconds.
-        if !force {
-            let now = Date()
-            if let lastDate = lastScheduleDate, now.timeIntervalSince(lastDate) < 10 {
-                return
-            }
-            lastScheduleDate = now
+        // Throttle execution if not forced: only run once every 10 seconds. A forced
+        // run stamps the date too, so the next tick doesn't immediately repeat the
+        // remove-and-re-add it just performed.
+        let now = Date()
+        if !force, let lastDate = lastScheduleDate, now.timeIntervalSince(lastDate) < 10 {
+            return
         }
+        lastScheduleDate = now
 
         removeDeliveredNotifications()
 

LoopFollow/Helpers/BackgroundRefreshManager.swift

@@ -3,6 +3,7 @@
 
 import BackgroundTasks
 import Foundation
+import UIKit
 
 class BackgroundRefreshManager {
     static let shared = BackgroundRefreshManager()
@@ -83,6 +84,8 @@ class BackgroundRefreshManager {
             // absence of a follow-up line.
             guard !backgroundTask.isPlaying else {
                 LogManager.shared.log(category: .taskScheduler, message: "audio alive, no action needed")
+                self.armBackgroundAlerts()
+                TaskScheduler.shared.checkTasksNow()
                 complete(true)
                 return
             }
@@ -96,11 +99,29 @@ class BackgroundRefreshManager {
                     category: .taskScheduler,
                     message: success ? "audio restart succeeded" : "audio restart failed"
                 )
+                // Only on success: a failed restart means suspension is imminent, and
+                // dispatching fetches that cannot finish helps nothing.
+                if success {
+                    self.armBackgroundAlerts()
+                    TaskScheduler.shared.checkTasksNow()
+                }
                 complete(success)
             }
         }
     }
 
+    /// Clears any delivered "App inactive" notification and re-arms the 6/12/18 minute
+    /// alerts from this moment. A background task only runs while backgrounded, so the
+    /// alerts belong armed here — and a process launched into the background never ran
+    /// `appMovedToBackground`, so nothing else would have armed them at all.
+    private func armBackgroundAlerts() {
+        // The task fires while backgrounded, but its work lands on the main queue and
+        // the user may have opened the app in between. Arming then would put an "App
+        // inactive" notification on screen while they are looking at the app.
+        guard UIApplication.shared.applicationState == .background else { return }
+        BackgroundAlertManager.shared.startBackgroundAlert()
+    }
+
     /// Requests the routine health check, leaving an existing pending request alone
     /// when it would run at least as soon. Every background transition calls this,
     /// and unconditional resubmission would push the check further out each time.

LoopFollow/Helpers/BackgroundTaskAudio.swift

@@ -65,13 +65,25 @@ class BackgroundTask {
     // MARK: - Methods
 
     func startBackgroundTask() {
-        NotificationCenter.default.removeObserver(self, name: AVAudioSession.interruptionNotification, object: nil)
-        NotificationCenter.default.addObserver(self, selector: #selector(interruptedAudio), name: AVAudioSession.interruptionNotification, object: AVAudioSession.sharedInstance())
+        attachObservers()
         onMain { self.recover(after: 0, reason: "start") }
     }
 
+    /// Idempotent, and called from `restartAudio` too: a process launched into the
+    /// background by `BGAppRefreshTask` never sees a backgrounding transition, so
+    /// without this it would run the keep-alive with nothing watching the session.
+    private func attachObservers() {
+        removeObservers()
+        NotificationCenter.default.addObserver(self, selector: #selector(interruptedAudio), name: AVAudioSession.interruptionNotification, object: AVAudioSession.sharedInstance())
+        // A route disappearing pauses the player without any interruption notification,
+        // and a media services reset invalidates the session and player outright —
+        // neither is observable through `interruptionNotification`.
+        NotificationCenter.default.addObserver(self, selector: #selector(audioRouteChanged), name: AVAudioSession.routeChangeNotification, object: nil)
+        NotificationCenter.default.addObserver(self, selector: #selector(mediaServicesWereReset), name: AVAudioSession.mediaServicesWereResetNotification, object: nil)
+    }
+
     func stopBackgroundTask() {
-        NotificationCenter.default.removeObserver(self, name: AVAudioSession.interruptionNotification, object: nil)
+        removeObservers()
         onMain {
             self.cancelRecovery()
             self.player.stop()
@@ -89,12 +101,80 @@ class BackgroundTask {
     /// audio claim that made them necessary.
     /// - Parameter completion: Called on the main queue with the final state.
     func restartAudio(reason: String, completion: ((Bool) -> Void)? = nil) {
+        attachObservers()
         onMain {
             self.player.stop()
             self.recover(after: 0, reason: reason, completion: completion)
         }
     }
 
+    private func removeObservers() {
+        NotificationCenter.default.removeObserver(self, name: AVAudioSession.interruptionNotification, object: nil)
+        NotificationCenter.default.removeObserver(self, name: AVAudioSession.routeChangeNotification, object: nil)
+        NotificationCenter.default.removeObserver(self, name: AVAudioSession.mediaServicesWereResetNotification, object: nil)
+    }
+
+    // MARK: - Route and media services handling
+
+    @objc private func audioRouteChanged(_ notification: Notification) {
+        guard let userInfo = notification.userInfo,
+              let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
+              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue)
+        else { return }
+
+        let previous = userInfo[AVAudioSessionRouteChangePreviousRouteKey] as? AVAudioSessionRouteDescription
+        let route = "reason=\(describe(reason)) from=\(portTypes(previous)) to=\(portTypes(AVAudioSession.sharedInstance().currentRoute))"
+
+        switch reason {
+        case .oldDeviceUnavailable, .newDeviceAvailable:
+            LogManager.shared.log(category: .general, message: "[LA] Audio route changed, restarting silent audio: \(route)")
+            // Same settle delay as an interruption, for a different reason: CarPlay and
+            // Bluetooth transitions emit a burst of route changes, and each supersedes
+            // the last so the ladder runs once against the settled route.
+            onMain { self.recover(after: self.interruptionSettleDelay, reason: "route change") }
+
+        case .categoryChange:
+            // Never recover here. `playAudio` sets the category itself, so recovering
+            // would retrigger this notification indefinitely, and an alarm takes over
+            // the session by changing category — reactivating with `.mixWithOthers`
+            // mid-alert would strip the alarm's dominance.
+            LogManager.shared.log(category: .general, message: "[LA] Audio route changed, ignoring: \(route)", isDebug: true)
+
+        default:
+            // Logged but not acted on: no evidence yet ties these to a lost claim, and
+            // a log line is how the next one earns a recovery.
+            LogManager.shared.log(category: .general, message: "[LA] Audio route changed, no action: \(route)")
+        }
+    }
+
+    @objc private func mediaServicesWereReset(_: Notification) {
+        LogManager.shared.log(category: .general, message: "[LA] Media services were reset — session and player are invalid, rebuilding")
+        // `playAudio` reconfigures the category, reactivates, and creates a fresh
+        // player, which is the recovery Apple prescribes for a reset.
+        onMain { self.recover(after: self.interruptionSettleDelay, reason: "media services reset") }
+    }
+
+    /// Port types only — `portName` carries the user's accessory name, which must not
+    /// reach a shared log.
+    private func portTypes(_ route: AVAudioSessionRouteDescription?) -> String {
+        guard let route, !route.outputs.isEmpty else { return "none" }
+        return route.outputs.map { $0.portType.rawValue }.joined(separator: "+")
+    }
+
+    private func describe(_ reason: AVAudioSession.RouteChangeReason) -> String {
+        switch reason {
+        case .newDeviceAvailable: "newDeviceAvailable"
+        case .oldDeviceUnavailable: "oldDeviceUnavailable"
+        case .categoryChange: "categoryChange"
+        case .override: "override"
+        case .wakeFromSleep: "wakeFromSleep"
+        case .noSuitableRouteForCategory: "noSuitableRouteForCategory"
+        case .routeConfigurationChange: "routeConfigurationChange"
+        case .unknown: "unknown"
+        @unknown default: "other"
+        }
+    }
+
     // MARK: - Interruption handling
 
     @objc private func interruptedAudio(_ notification: Notification) {

LoopFollow/Task/TaskScheduler.swift

@@ -33,9 +33,20 @@ class TaskScheduler {
     /// process was suspended and is the window the background alerts fire in.
     private var lastFireDate: Date?
 
+    /// Boot-relative counterpart to `lastFireDate`. It includes time asleep and cannot
+    /// be moved by a clock correction, so it measures the gap even when the wall clock
+    /// steps — and the difference between the two says a step happened.
+    private var lastFireUptime: UInt64?
+
     /// Above normal tick jitter, below the 6-minute first background alert.
     private let runtimeGapThreshold: TimeInterval = 120
 
+    /// Queue-confined park tracking. A normal park clears within milliseconds, so a
+    /// survivor at this age is wedged or was suspended mid-park.
+    private var parkedSince: Date?
+    private var parkedReporter: DispatchWorkItem?
+    private let parkedReportDelay: TimeInterval = 5
+
     private init() {}
 
     // MARK: - Public API
@@ -80,6 +91,12 @@ class TaskScheduler {
             return
         }
 
+        if earliestTask.nextRun == .distantFuture {
+            noteTimerParked()
+        } else {
+            clearTimerParked()
+        }
+
         let interval = earliestTask.nextRun.timeIntervalSinceNow
         let safeInterval = max(interval, 0)
 
@@ -117,12 +134,46 @@ class TaskScheduler {
         }
     }
 
+    /// `fireOverdueTasks` parks a task at `.distantFuture` and its action reschedules
+    /// it asynchronously, so every task being parked at once is normal for the
+    /// milliseconds in between. Only a park that outlives that is interesting: it means
+    /// nothing is left to wake the timer. Reported by duration so the routine case
+    /// stays silent.
+    private func noteTimerParked() {
+        guard parkedSince == nil else { return }
+        let since = Date()
+        parkedSince = since
+        let work = DispatchWorkItem { [weak self] in
+            guard let self, self.parkedSince == since else { return }
+            LogManager.shared.log(
+                category: .taskScheduler,
+                message: "Timer still parked after \(Int(Date().timeIntervalSince(since)))s: every task is awaiting its action to reschedule it"
+            )
+        }
+        parkedReporter = work
+        queue.asyncAfter(deadline: .now() + parkedReportDelay, execute: work)
+    }
+
+    private func clearTimerParked() {
+        parkedReporter?.cancel()
+        parkedReporter = nil
+        parkedSince = nil
+    }
+
     /// Records one line per lost-runtime window, so the length of a background stall
     /// is readable directly instead of having to be inferred from timestamp gaps.
     private func noteRuntimeGap(at now: Date) {
-        defer { lastFireDate = now }
-        guard let last = lastFireDate else { return }
-        let gap = now.timeIntervalSince(last)
+        // CLOCK_MONOTONIC keeps counting while the device sleeps, unlike
+        // CLOCK_UPTIME_RAW, so it measures a suspension rather than skipping it.
+        let uptime = clock_gettime_nsec_np(CLOCK_MONOTONIC)
+        defer {
+            lastFireDate = now
+            lastFireUptime = uptime
+        }
+        guard let last = lastFireDate, let lastUptime = lastFireUptime else { return }
+        // Boot time is authoritative: a wall-clock correction must not hide a stall.
+        let gap = Double(uptime &- lastUptime) / 1_000_000_000
+        let wallGap = now.timeIntervalSince(last)
         guard gap >= runtimeGapThreshold else { return }
         // Silent Tune is the only mode whose invariant is continuous runtime, which is
         // what this measures. `.none` is meant to be suspended, and the Bluetooth modes
@@ -133,10 +184,11 @@ class TaskScheduler {
             .filter { gap >= $0.rawValue }
             .map { "\(Int($0.rawValue / 60))" }
         let fired = alerts.isEmpty ? "none" : alerts.joined(separator: "/") + " min"
-        LogManager.shared.log(
-            category: .taskScheduler,
-            message: "Regained runtime after \(Int(gap))s with no scheduler tick; background alerts fired: \(fired)"
-        )
+        var message = "Regained runtime after \(Int(gap))s with no scheduler tick; background alerts fired: \(fired)"
+        if abs(wallGap - gap) >= 5 {
+            message += "; wall clock moved \(Int(wallGap - gap))s relative to boot time"
+        }
+        LogManager.shared.log(category: .taskScheduler, message: message)
     }
 
     private func formatTime(_ date: Date) -> String {