feat: add authenticated iOS background presence beacon (#73330)

* feat: add iOS background presence beacon

Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com>

* fix: keep iOS background reconnects ahead of beacon throttle

* build: refresh gateway protocol swift models

* fix: emit swift protocol string enums

---------

Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com>

apps/ios/Sources/Model/NodeAppModel.swift

@@ -200,6 +200,8 @@ final class NodeAppModel {
     private(set) var activeGatewayConnectConfig: GatewayConnectConfig?
 
     private static let watchExecApprovalBridgeStateKey = "watch.execApproval.bridge.state.v1"
+    private static let backgroundAliveLastSuccessAtMsKey = "gateway.backgroundAlive.lastSuccessAtMs"
+    private static let backgroundAliveLastTriggerKey = "gateway.backgroundAlive.lastTrigger"
 
     var cameraHUDText: String?
     var cameraHUDKind: CameraHUDKind?
@@ -3142,32 +3144,39 @@ extension NodeAppModel {
             return handled
         }
 
-        let result = await self.reconnectGatewaySessionsForSilentPushIfNeeded(wakeId: wakeId)
+        let result = await self.performBackgroundAliveBeaconIfNeeded(
+            wakeId: wakeId,
+            trigger: .silentPush)
         let outcomeMessage =
             "Silent push outcome wakeId=\(wakeId) "
                 + "applied=\(result.applied) "
+                + "handled=\(result.handled) "
                 + "reason=\(result.reason) "
                 + "durationMs=\(result.durationMs)"
         self.pushWakeLogger.info("\(outcomeMessage, privacy: .public)")
-        return result.applied
+        return result.handled
     }
 
     func handleBackgroundRefreshWake(trigger: String = "bg_app_refresh") async -> Bool {
         let wakeId = Self.makePushWakeAttemptID()
+        let normalizedTrigger = BackgroundAliveBeacon.normalizeTrigger(trigger)
         let receivedMessage =
             "Background refresh wake received wakeId=\(wakeId) "
-                + "trigger=\(trigger) "
+                + "trigger=\(normalizedTrigger.rawValue) "
                 + "backgrounded=\(self.isBackgrounded) "
                 + "autoReconnect=\(self.gatewayAutoReconnectEnabled)"
         self.pushWakeLogger.info("\(receivedMessage, privacy: .public)")
-        let result = await self.reconnectGatewaySessionsForSilentPushIfNeeded(wakeId: wakeId)
+        let result = await self.performBackgroundAliveBeaconIfNeeded(
+            wakeId: wakeId,
+            trigger: normalizedTrigger)
         let outcomeMessage =
             "Background refresh wake outcome wakeId=\(wakeId) "
                 + "applied=\(result.applied) "
+                + "handled=\(result.handled) "
                 + "reason=\(result.reason) "
                 + "durationMs=\(result.durationMs)"
         self.pushWakeLogger.info("\(outcomeMessage, privacy: .public)")
-        return result.applied
+        return result.handled
     }
 
     func handleSignificantLocationWakeIfNeeded() async {
@@ -3196,10 +3205,13 @@ extension NodeAppModel {
                 + "backgrounded=\(self.isBackgrounded) "
                 + "autoReconnect=\(self.gatewayAutoReconnectEnabled)"
         self.locationWakeLogger.info("\(beginMessage, privacy: .public)")
-        let result = await self.reconnectGatewaySessionsForSilentPushIfNeeded(wakeId: wakeId)
+        let result = await self.performBackgroundAliveBeaconIfNeeded(
+            wakeId: wakeId,
+            trigger: .significantLocation)
         let triggerMessage =
             "Location wake trigger wakeId=\(wakeId) "
                 + "applied=\(result.applied) "
+                + "handled=\(result.handled) "
                 + "reason=\(result.reason) "
                 + "durationMs=\(result.durationMs)"
         self.locationWakeLogger.info("\(triggerMessage, privacy: .public)")
@@ -3621,8 +3633,9 @@ extension NodeAppModel {
         return gatewayError.message.lowercased().contains("allow-always is unavailable")
     }
 
-    private struct SilentPushWakeAttemptResult {
+    private struct BackgroundAliveWakeAttemptResult {
         var applied: Bool
+        var handled: Bool
         var reason: String
         var durationMs: Int
     }
@@ -3797,43 +3810,100 @@ extension NodeAppModel {
         return await self.waitForOperatorConnection(timeoutMs: timeoutMs, pollMs: 250)
     }
 
-    private func reconnectGatewaySessionsForSilentPushIfNeeded(
-        wakeId: String) async -> SilentPushWakeAttemptResult
+    private func performBackgroundAliveBeaconIfNeeded(
+        wakeId: String,
+        trigger: BackgroundAliveBeacon.Trigger) async -> BackgroundAliveWakeAttemptResult
     {
         let startedAt = Date()
-        let makeResult: (Bool, String) -> SilentPushWakeAttemptResult = { applied, reason in
+        let makeResult: (Bool, Bool, String) -> BackgroundAliveWakeAttemptResult = { applied, handled, reason in
             let durationMs = Int(Date().timeIntervalSince(startedAt) * 1000)
-            return SilentPushWakeAttemptResult(
+            return BackgroundAliveWakeAttemptResult(
                 applied: applied,
+                handled: handled,
                 reason: reason,
                 durationMs: max(0, durationMs))
         }
 
         guard self.isBackgrounded else {
             self.pushWakeLogger.info("Wake no-op wakeId=\(wakeId, privacy: .public): app not backgrounded")
-            return makeResult(false, "not_backgrounded")
+            return makeResult(false, false, "not_backgrounded")
         }
         guard self.gatewayAutoReconnectEnabled else {
             self.pushWakeLogger.info("Wake no-op wakeId=\(wakeId, privacy: .public): auto reconnect disabled")
-            return makeResult(false, "auto_reconnect_disabled")
+            return makeResult(false, false, "auto_reconnect_disabled")
         }
-        guard let cfg = self.activeGatewayConnectConfig else {
-            self.pushWakeLogger.info("Wake no-op wakeId=\(wakeId, privacy: .public): no active gateway config")
-            return makeResult(false, "no_active_gateway_config")
+        let now = Date()
+        let gatewayConnected = await self.isGatewayConnected()
+
+        var appliedReconnect = false
+        if !gatewayConnected {
+            guard let cfg = self.activeGatewayConnectConfig else {
+                self.pushWakeLogger.info("Wake no-op wakeId=\(wakeId, privacy: .public): no active gateway config")
+                return makeResult(false, false, "no_active_gateway_config")
+            }
+            self.pushWakeLogger.info(
+                "Wake reconnect begin wakeId=\(wakeId, privacy: .public) stableID=\(cfg.stableID, privacy: .public)")
+            self.grantBackgroundReconnectLease(seconds: 30, reason: "wake_\(wakeId)")
+            await self.operatorGateway.disconnect()
+            await self.nodeGateway.disconnect()
+            self.operatorConnected = false
+            self.gatewayConnected = false
+            self.gatewayStatusText = "Reconnecting…"
+            self.talkMode.updateGatewayConnected(false)
+            self.applyGatewayConnectConfig(cfg)
+            appliedReconnect = true
+            self.pushWakeLogger.info("Wake reconnect trigger applied wakeId=\(wakeId, privacy: .public)")
+
+            let connected = await self.waitForGatewayConnection(timeoutMs: 12000, pollMs: 250)
+            guard connected else {
+                return makeResult(appliedReconnect, false, "connect_timeout")
+            }
+        } else if BackgroundAliveBeacon.shouldSkipRecentSuccess(
+            isGatewayConnected: true,
+            now: now,
+            lastSuccessAtMs: UserDefaults.standard.object(forKey: Self.backgroundAliveLastSuccessAtMsKey) as? Double)
+        {
+            return makeResult(false, true, "recent_success")
         }
 
-        self.pushWakeLogger.info(
-            "Wake reconnect begin wakeId=\(wakeId, privacy: .public) stableID=\(cfg.stableID, privacy: .public)")
-        self.grantBackgroundReconnectLease(seconds: 30, reason: "wake_\(wakeId)")
-        await self.operatorGateway.disconnect()
-        await self.nodeGateway.disconnect()
-        self.operatorConnected = false
-        self.gatewayConnected = false
-        self.gatewayStatusText = "Reconnecting…"
-        self.talkMode.updateGatewayConnected(false)
-        self.applyGatewayConnectConfig(cfg)
-        self.pushWakeLogger.info("Wake reconnect trigger applied wakeId=\(wakeId, privacy: .public)")
-        return makeResult(true, "reconnect_triggered")
+        let beacon = await self.publishBackgroundAliveBeacon(trigger: trigger)
+        if beacon.handled {
+            let successAtMs = Date().timeIntervalSince1970 * 1000
+            UserDefaults.standard.set(successAtMs, forKey: Self.backgroundAliveLastSuccessAtMsKey)
+            UserDefaults.standard.set(trigger.rawValue, forKey: Self.backgroundAliveLastTriggerKey)
+            return makeResult(appliedReconnect, true, beacon.reason)
+        }
+        return makeResult(appliedReconnect, false, beacon.reason)
+    }
+
+    private func publishBackgroundAliveBeacon(
+        trigger: BackgroundAliveBeacon.Trigger) async -> (handled: Bool, reason: String)
+    {
+        do {
+            let pushTransport = await self.pushRegistrationManager.usesRelayTransport ? "relay" : "direct"
+            let displayName = NodeDisplayName.resolve(
+                existing: UserDefaults.standard.string(forKey: "node.displayName"),
+                deviceName: UIDevice.current.name,
+                interfaceIdiom: UIDevice.current.userInterfaceIdiom)
+            let payload = BackgroundAliveBeacon.makePayload(
+                trigger: trigger,
+                displayName: displayName,
+                pushTransport: pushTransport)
+            let paramsJSON = try BackgroundAliveBeacon.makeNodeEventRequestPayloadJSON(payload: payload)
+            let response = try await self.nodeGateway.request(
+                method: "node.event",
+                paramsJSON: paramsJSON,
+                timeoutSeconds: 8)
+            guard let decoded = BackgroundAliveBeacon.decodeResponse(response) else {
+                return (false, "invalid_response")
+            }
+            if decoded.handled == true {
+                return (true, decoded.reason ?? "beacon_persisted")
+            }
+            return (false, decoded.reason ?? "unsupported")
+        } catch {
+            return (false, "beacon_failed")
+        }
     }
 }
 

apps/ios/Sources/Push/BackgroundAliveBeacon.swift

@@ -0,0 +1,92 @@
+import Foundation
+import UIKit
+
+enum BackgroundAliveBeacon {
+    static let eventName = "node.presence.alive"
+    static let minSuccessIntervalSeconds: TimeInterval = 10 * 60
+
+    enum Trigger: String, CaseIterable, Codable {
+        case background
+        case silentPush = "silent_push"
+        case bgAppRefresh = "bg_app_refresh"
+        case significantLocation = "significant_location"
+        case manual
+        case connect
+    }
+
+    struct Payload: Encodable {
+        var trigger: String
+        var sentAtMs: Int64
+        var displayName: String
+        var version: String
+        var platform: String
+        var deviceFamily: String
+        var modelIdentifier: String
+        var pushTransport: String?
+    }
+
+    struct NodeEventRequestPayload: Codable {
+        var event: String = BackgroundAliveBeacon.eventName
+        var payloadJSON: String
+    }
+
+    struct NodeEventResponsePayload: Decodable {
+        var ok: Bool?
+        var event: String?
+        var handled: Bool?
+        var reason: String?
+    }
+
+    static func normalizeTrigger(_ raw: String) -> Trigger {
+        let normalized = raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return Trigger(rawValue: normalized) ?? .background
+    }
+
+    static func shouldSkipRecentSuccess(
+        isGatewayConnected: Bool,
+        now: Date,
+        lastSuccessAtMs: Double?,
+        minInterval: TimeInterval = Self.minSuccessIntervalSeconds) -> Bool
+    {
+        guard isGatewayConnected else { return false }
+        guard let lastSuccessAtMs, lastSuccessAtMs > 0 else { return false }
+        let elapsed = now.timeIntervalSince1970 - (lastSuccessAtMs / 1000.0)
+        return elapsed >= 0 && elapsed < minInterval
+    }
+
+    @MainActor
+    static func makePayload(trigger: Trigger, displayName: String, pushTransport: String?) -> Payload {
+        Payload(
+            trigger: trigger.rawValue,
+            sentAtMs: Int64(Date().timeIntervalSince1970 * 1000),
+            displayName: displayName,
+            version: DeviceInfoHelper.appVersion(),
+            platform: DeviceInfoHelper.platformString(),
+            deviceFamily: DeviceInfoHelper.deviceFamily(),
+            modelIdentifier: DeviceInfoHelper.modelIdentifier(),
+            pushTransport: pushTransport)
+    }
+
+    static func makeNodeEventRequestPayloadJSON(
+        payload: Payload,
+        encoder: JSONEncoder = JSONEncoder()) throws -> String
+    {
+        let payloadData = try encoder.encode(payload)
+        guard let payloadJSON = String(data: payloadData, encoding: .utf8) else {
+            throw EncodingError.invalidValue(payload, EncodingError.Context(
+                codingPath: [],
+                debugDescription: "Failed to encode background alive payload as UTF-8"))
+        }
+        let requestData = try encoder.encode(NodeEventRequestPayload(payloadJSON: payloadJSON))
+        guard let requestJSON = String(data: requestData, encoding: .utf8) else {
+            throw EncodingError.invalidValue(payload, EncodingError.Context(
+                codingPath: [],
+                debugDescription: "Failed to encode node.event payload as UTF-8"))
+        }
+        return requestJSON
+    }
+
+    static func decodeResponse(_ data: Data) -> NodeEventResponsePayload? {
+        try? JSONDecoder().decode(NodeEventResponsePayload.self, from: data)
+    }
+}

apps/ios/SwiftSources.input.xcfilelist

@@ -42,6 +42,7 @@ Sources/Onboarding/OnboardingWizardView.swift
 Sources/Onboarding/QRScannerView.swift
 Sources/OpenClawApp.swift
 Sources/Push/ExecApprovalNotificationBridge.swift
+Sources/Push/BackgroundAliveBeacon.swift
 Sources/Push/PushBuildConfig.swift
 Sources/Push/PushRegistrationManager.swift
 Sources/Push/PushRelayClient.swift

apps/ios/Tests/BackgroundAliveBeaconTests.swift

@@ -0,0 +1,74 @@
+import Foundation
+import Testing
+@testable import OpenClaw
+
+struct BackgroundAliveBeaconTests {
+    @Test func `normalize trigger accepts closed reasons`() {
+        #expect(BackgroundAliveBeacon.normalizeTrigger("silent_push") == .silentPush)
+        #expect(BackgroundAliveBeacon.normalizeTrigger(" bg_app_refresh ") == .bgAppRefresh)
+        #expect(BackgroundAliveBeacon.normalizeTrigger("SIGNIFICANT_LOCATION") == .significantLocation)
+    }
+
+    @Test func `normalize trigger falls back to background`() {
+        #expect(BackgroundAliveBeacon.normalizeTrigger("watch_prompt_action") == .background)
+        #expect(BackgroundAliveBeacon.normalizeTrigger("") == .background)
+    }
+
+    @Test func `recent success throttle uses milliseconds`() {
+        let now = Date(timeIntervalSince1970: 1000)
+
+        #expect(BackgroundAliveBeacon.shouldSkipRecentSuccess(
+            isGatewayConnected: true,
+            now: now,
+            lastSuccessAtMs: 999_500,
+            minInterval: 10))
+        #expect(!BackgroundAliveBeacon.shouldSkipRecentSuccess(
+            isGatewayConnected: true,
+            now: now,
+            lastSuccessAtMs: 980_000,
+            minInterval: 10))
+    }
+
+    @Test func `recent success throttle does not suppress disconnected wakes`() {
+        let now = Date(timeIntervalSince1970: 1000)
+
+        #expect(!BackgroundAliveBeacon.shouldSkipRecentSuccess(
+            isGatewayConnected: false,
+            now: now,
+            lastSuccessAtMs: 999_500,
+            minInterval: 10))
+    }
+
+    @Test func `make node event payload wraps presence payload JSON`() throws {
+        let payload = BackgroundAliveBeacon.Payload(
+            trigger: BackgroundAliveBeacon.Trigger.silentPush.rawValue,
+            sentAtMs: 123,
+            displayName: "Peter's iPhone",
+            version: "2026.4.28",
+            platform: "iOS 18.4.0",
+            deviceFamily: "iPhone",
+            modelIdentifier: "iPhone17,1",
+            pushTransport: "relay")
+        let requestJSON = try BackgroundAliveBeacon.makeNodeEventRequestPayloadJSON(payload: payload)
+        let requestData = try #require(requestJSON.data(using: .utf8))
+        let request = try JSONDecoder().decode(
+            BackgroundAliveBeacon.NodeEventRequestPayload.self,
+            from: requestData)
+
+        #expect(request.event == "node.presence.alive")
+        let payloadData = try #require(request.payloadJSON.data(using: .utf8))
+        let decodedPayload = try #require(JSONSerialization.jsonObject(with: payloadData) as? [String: Any])
+        let sentAtMs = try #require(decodedPayload["sentAtMs"] as? Int)
+        #expect(decodedPayload["trigger"] as? String == "silent_push")
+        #expect(sentAtMs == 123)
+        #expect(decodedPayload["pushTransport"] as? String == "relay")
+    }
+
+    @Test func `old gateway ack does not count as handled`() throws {
+        let data = try #require(#"{"ok":true}"#.data(using: .utf8))
+        let response = try #require(BackgroundAliveBeacon.decodeResponse(data))
+
+        #expect(response.ok == true)
+        #expect(response.handled == nil)
+    }
+}