Fix Live Activity background renewal; add push-to-start fallback and stuck-widget recovery

[bjorkert]

Why

Live Activities have an 8-hour ceiling, so LoopFollow ends the current LA and starts a fresh one before the deadline. Three things made that fragile:

1. When the renewal deadline passed while the app was in the background, Activity.request() was called anyway. It can only succeed from a foregroundActive scene, so it always failed with visibility, the LA decayed, and the user only got their Live Activity back when they next opened the app.
2. When the renewal path did run, the .dismissed callback for the old activity raced against the storage-flag clears. On the unlucky ordering the old LA's dismissal was classified as a user swipe — dismissedByUser=true — which then blocked the auto-restart entirely. Logs showed this triggering on nearly every app-terminate / restart sequence.
3. iOS sometimes stops invoking the widget extension well before the 8-hour deadline. The LA's shared content state is still correct, but the lock screen freezes because the body is never re-rendered — and nothing noticed.

Four user-provided log files (2026-04-19, 2026-04-19-1, 2026-04-20, 2026-04-20-1) contained direct evidence of the first two failure modes, including multiple Live Activity failed to start: visibility entries and .dismissed: endingForRestart=false, renewBy=0.0 → dismissed by USER lines immediately followed by [LA] ended on app terminate.

Changes to the general LA lifecycle

• Restart classification (endingForRestart flag). Set before any internal activity.end() call — endOnTerminate, handleExpiredToken, forceRestart, and the foreground renewal path. The .dismissed state observer now checks this flag first, so a system-initiated end is never misclassified as a user swipe regardless of which MainActor hop runs first.
• Foreground-race fix. willEnterForegroundNotification fires before the scene reaches foregroundActive, so restarting from there still throws visibility. handleForeground now just sets pendingForegroundRestart = true and the actual end+restart runs from handleDidBecomeActive, where Activity.request() is guaranteed to succeed.
• Cold-start staleness check. startIfNeeded now detects an existing-but-stale LA on launch (laRenewalFailed, in the renewal window, or past staleDate) and ends+restarts it, covering the path where handleForeground never fires because the app was killed while the overlay was showing.
• Background-audio fallback. When the background audio session permanently fails, handleBackgroundAudioFailed forces the renewal overlay immediately so the user sees "Tap to update" instead of silently losing updates.
• Diagnostics. Added structured logs around handleForeground, handleDidBecomeActive, startIfNeeded, handleExpiredToken, and the .dismissed branch so classification decisions are visible in the log stream.

Push-to-start fallback (iOS 17.2+)

The real fix for background renewal is iOS 17.2's push-to-start. LoopFollow is already awake in the background (silent tune / bluetooth session), so when the renewal deadline passes while the app is backgrounded, it can send an APNs event: "start" payload to itself and iOS will spawn a fresh Live Activity without needing a foregroundActive scene.

Mechanics

• LiveActivityManager opens two long-lived streams at init (both behind #available guards, so the targets stay intact on older iOS):
  • Activity<GlucoseLiveActivityAttributes>.pushToStartTokenUpdates (iOS 17.2+) — the device-level push-to-start token is persisted to Storage.shared.laPushToStartToken each time iOS issues one. The token survives app relaunches.
  • Activity<GlucoseLiveActivityAttributes>.activityUpdates (iOS 16.2+) — any new activity not already bound is adopted: the old LA is ended immediately, laRenewBy is reset to a fresh 7.5h deadline, laRenewalFailed is cleared, LALivenessStore is cleared, and the new activity is bound through the same code path as a normal start.
• Restart decisions run through a single attemptLARestart helper so deadline renewal and stuck-widget restart (below) take the same path:
  • Foreground: end old + Activity.request.
  • Background: attemptPushToStartIfEligible builds a fresh snapshot, bumps seq, and POSTs to /3/device/{token} with apns-push-type: liveactivity and event: "start" via APNSClient.sendLiveActivityStart. If the request can't be dispatched (no token, rate-limited), the existing markRenewalFailedFromBackground path runs and schedules the local notification.

The start payload omits an alert block, so the restart is silent — iOS spawns the fresh Live Activity without surfacing a banner to the user.

Rate limiting

Once-per-failed-renewal with exponential backoff stored in laPushToStartBackoff / laLastPushToStartAt:

• Success: backoff set to base (300s) so refresh ticks between the send and activityUpdates adoption don't re-fire.
• 429 (rate limited): backoff doubled, capped at 60 min, then falls back to markRenewalFailed for this cycle.
• 404/410 (token invalid): stored token cleared so the next pushToStartTokenUpdates delivery overwrites it; backoff reset.
• Other failure: backoff bumped to at least base to avoid hammering APNs.

Stuck-widget recovery

The widget body contains a small LALivenessMarker SwiftUI view whose .task(id:) fires on every re-render and writes the rendered seq + timestamp into an app-group UserDefaults via LALivenessStore. The main app already had a shouldRestartBecauseExtensionLooksStuck() helper (behind on seq AND no render for 15+ minutes) but nothing called it.

LALivenessStore was pointing at the bare bundle id (com.<team>.LoopFollow) rather than the App Group suite (group.<base>), so the widget's writes and the app's reads were on different backing stores — lastExtensionSeenAt stayed 0.0 forever and the extensionHasNeverCheckedIn branch short-circuited as "silent" on every fresh LA. Field log LoopFollow 2026-04-21.log shows this exactly: seenSeq=0, lastSeenAt=0.0 across hours of runtime while expectedSeq climbs past 20, each check firing a push-to-start that then gets rate-limited into a markRenewalFailed notification. The fix is one line: use AppGroupID.current() so both processes share the suite.

performRefresh now calls restartIfExtensionLooksStuck(snapshot:) every tick, right after renewIfNeeded. When it fires, the same attemptLARestart helper runs — so a frozen widget triggers a push-to-start on iOS 17.2+ or an overlay + local notification on iOS 16.x, exactly like a deadline-based renewal. Running on every refresh is safe because the push-to-start backoff and laRenewalFailed's first-failure gate naturally dedupe repeat firings.

LALivenessStore is cleared whenever a fresh LA takes over (start-new, renew, force-restart, end, terminate, and now the foreground attemptLARestart path plus adoptPushToStartActivity), so the previous LA's last-seen seq cannot leave the new one looking stuck on its first refresh ticks.

iOS 16 vs iOS 17 behavior after this PR

The minimum deployment target stays at iOS 16. The push-to-start code is all gated by #available(iOS 17.2, *) (for the token observer) or by the presence of a stored token (which can only be populated on iOS 17.2+).

• iOS 16.x — pushToStartTokenUpdates is never observed, laPushToStartToken stays empty, attemptPushToStartIfEligible no-ops and returns false, and the background renewal / stuck-widget paths fall straight through to markRenewalFailedFromBackground + local notification exactly as before. No behavioral change except for the stuck-widget detection, which will now mark renewal failed and notify instead of silently showing a frozen lock screen.
• iOS 16.2+ — activityUpdates is observed and the adoption path works, so out-of-band starts would be picked up if they ever occurred. In practice on 16.2–17.1 nothing else starts LAs for us, so it's a no-op but costs nothing.
• iOS 17.2+ — the full push-to-start fallback is active. Both a passed renewal deadline and a stuck widget extension will restart the LA in place without requiring the user to open the app.