@telnyx/react-voice-commons-sdk 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 # CHANGELOG.md
 
-## Unreleased
+## [1.2.0] (2026-10-28)
+
+### Enhancement
+
+- Expose call-quality metrics through `Call.qualityMetrics$`, `currentQualityMetrics`, and the exported metrics and quality-level types.
+- Add automatic active-call recovery through the Voice SDK, including signaling-health monitoring, ICE restart, RTP verification, and reconnect/reattach fallback.
+- Add `iceServers` to credential and token configurations so applications can provide custom STUN/TURN servers; omitted values use the Voice SDK's Telnyx production defaults.
+- Identify Commons signaling as `webrtc-react-native-commons` with the Commons package version while retaining per-client identity isolation and the existing User-Agent format.
+
+### Dependencies
+
+- Require `react-native-webrtc ^155.0.1` (WebRTC M155), matching the Voice SDK's media dependency. Applications must target iOS 14 or newer; the Android minimum remains API 24.
+- Require `@telnyx/react-native-voice-sdk ^1.2.0` when publishing so Commons uses the matching signaling security, call recovery, metrics, and ICE-server behavior while staying within the compatible 1.x line.
+- Remove the unused direct `expo` dependency. Commons does not require Expo,
+  so this avoids installing Expo SDK 53 alongside an application's Expo SDK.
+
+### Security
+
+- Use the Voice SDK's platform-default TLS certificate and hostname validation. On iOS, signaling uses `URLSessionWebSocketTask`; Android retains React Native's OkHttp-backed WebSocket.
+
+### Bug Fixing
+
+- Handle BYE and missed-call pushes that arrive before the incoming WebRTC call exists, dismiss the matching CallKit call, clear pending push state, and show the missed-call notification without treating the original UUID as a collision.
+- Serialize CallKit registration completion with missed-call invalidation so a delayed completion cannot restore an already-ended incoming call; PushKit completion remains exactly once.
+- Keep the active CallKit UUID claimed until WebRTC answering finishes, share concurrent answer work, and reject a second call while another call owns the answering/active slot.
+- Prevent duplicate incoming and reattached-call listeners when the same client-ready callback fires more than once during connection or reconnection.
+
+## [1.1.1] (2026-09-11)
+
+### Bug Fixing
+
+- Improve iOS CallKit audio reliability by routing activation and connected-call verification through a single idempotent recovery path.
+- Recover connected calls when CallKit owns an active play-and-record audio session but the WebRTC audio device remains disabled.
+- Prevent duplicate CallKit setup from disabling WebRTC audio after a call is already active, and harden failure handling when audio recovery does not succeed.
+
+### Dependencies
+
+- Continues to require `@telnyx/react-native-voice-sdk >= 1.1.0`; no new base Voice SDK release is required.
 
 ## [1.1.0] (2026-08-07)
 

package/TelnyxVoiceCommons.podspec

@@ -9,7 +9,7 @@ Pod::Spec.new do |s|
   s.description    = package['description']
   s.homepage       = package['homepage']
   s.license        = package['license']
-  s.platforms      = { :ios => '13.0' }
+  s.platforms      = { :ios => '14.0' }
   s.swift_version  = '5.4'
   s.author         = package['author']
   s.source         = { :git => package['repository']['url'], :tag => "#{s.version}" }
@@ -22,11 +22,11 @@ Pod::Spec.new do |s|
   s.dependency 'React-Core'
   
   # WebRTC Framework dependency
-  s.dependency 'JitsiWebRTC', '~> 124.0.0'
+  s.dependency 'JitsiWebRTC', '~> 155.0.0'
 
   # iOS Frameworks
   s.frameworks = 'CallKit', 'PushKit', 'AVFoundation'
 
   # Compiler flags for Swift
   s.compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1'
-end
+end

package/ios/CallKitBridge.m

@@ -60,4 +60,11 @@ RCT_EXTERN_METHOD(updateCall:(NSString *)callUUID
 RCT_EXTERN_METHOD(getActiveCalls:(RCTPromiseResolveBlock)resolve 
                   rejecter:(RCTPromiseRejectBlock)reject)
 
+#if DEBUG
+RCT_EXTERN_METHOD(simulateAudioSetupRace:(NSString *)callUUID
+                  delayMilliseconds:(nonnull NSNumber *)delayMilliseconds
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+#endif
+
 @end

package/ios/CallKitBridge.swift

@@ -156,7 +156,11 @@ import React
                 "handle": handle,
                 "uuid": uuid.uuidString,
                 "direction": "outgoing",
-                "source": "react_native",
+                // VSDK-771 AFK review: align internal source tag with the
+                // new prefixed convention so grep-based family completeness
+                // (webrtc-react-native / webrtc-react-native-commons) is
+                // clean across the SDK. Not consumed by the wire contract.
+                "source": "webrtc-react-native",
             ]
 
             callController.request(transaction) { error in
@@ -197,7 +201,9 @@ import React
                 "handle": handle,
                 "uuid": uuid.uuidString,
                 "direction": "incoming",
-                "source": "react_native",
+                // VSDK-771 AFK review: align internal source tag with the
+                // new prefixed convention. See outgoing branch above.
+                "source": "webrtc-react-native",
                 "isCallKitRegistered": false,
             ]
 
@@ -440,29 +446,31 @@ import React
                 NSLog("TelnyxVoice: reportCallConnected - fulfilling deferred CXAnswerCallAction")
                 pendingAction.fulfill()
             } else {
-                // Fallback: ensure audio is enabled for non-push or already-fulfilled cases
-                let rtcAudioSession = RTCAudioSession.sharedInstance()
-                rtcAudioSession.lockForConfiguration()
-                let webRTCConfig = RTCAudioSessionConfiguration.webRTC()
-                webRTCConfig.categoryOptions = [.duckOthers, .allowBluetooth]
-                do {
-                    try rtcAudioSession.setConfiguration(webRTCConfig)
-                } catch {
-                    NSLog("TelnyxVoice: reportCallConnected - setConfiguration error: \(error)")
-                }
-                do {
-                    try rtcAudioSession.setActive(true)
-                } catch {
-                    NSLog("TelnyxVoice: reportCallConnected - setActive error: \(error)")
-                }
-                rtcAudioSession.isAudioEnabled = true
-                rtcAudioSession.unlockForConfiguration()
-                rtcAudioSession.audioSessionDidActivate(AVAudioSession.sharedInstance())
+                manager.verifyAudioAfterConnection(for: uuid)
             }
 
             resolve(["success": true])
         }
 
+        #if DEBUG
+            @objc func simulateAudioSetupRace(
+                _ callUUID: String,
+                delayMilliseconds: NSNumber,
+                resolver resolve: @escaping RCTPromiseResolveBlock,
+                rejecter reject: @escaping RCTPromiseRejectBlock
+            ) {
+                guard let uuid = UUID(uuidString: callUUID) else {
+                    reject("INVALID_UUID", "Invalid UUID format", nil)
+                    return
+                }
+                getCallKitManager().simulateAudioSetupRace(
+                    for: uuid,
+                    delay: delayMilliseconds.doubleValue / 1_000
+                )
+                resolve(["scheduled": true, "delayMilliseconds": delayMilliseconds])
+            }
+        #endif
+
         @objc func reportCallEnded(
             _ callUUID: String, reason: NSNumber,
             resolver resolve: @escaping RCTPromiseResolveBlock,
@@ -739,11 +747,29 @@ import React
         public var callKitProvider: CXProvider?
         public var callKitController: CXCallController?
         private let stateLock = NSRecursiveLock()
+        // Keep terminal missed-call invalidation atomic with registration side effects so a
+        // delayed CallKit completion cannot restore an already-ended incoming call.
+        private let incomingRegistrationQueue = DispatchQueue(
+            label: "com.telnyx.react-voice-commons.incoming-registration")
         public lazy var activeCalls = LockedDictionary<UUID, [String: Any]>(lock: stateLock)
         public lazy var pendingAnswerActions = LockedDictionary<UUID, CXAnswerCallAction>(
             lock: stateLock)
         public lazy var pendingHeldActions = LockedDictionary<UUID, CXSetHeldCallAction>(
             lock: stateLock)
+        private var audioLifecycleGeneration = 0
+
+        private func advanceAudioLifecycleGeneration() -> Int {
+            stateLock.lock()
+            defer { stateLock.unlock() }
+            audioLifecycleGeneration += 1
+            return audioLifecycleGeneration
+        }
+
+        private func currentAudioLifecycleGeneration() -> Int {
+            stateLock.lock()
+            defer { stateLock.unlock() }
+            return audioLifecycleGeneration
+        }
 
         fileprivate func markCallKitRegistered(_ callUUID: UUID) {
             guard var callData = activeCalls[callUUID] else {
@@ -766,6 +792,35 @@ import React
             return true
         }
 
+        @discardableResult
+        fileprivate func performIncomingRegistrationIfOwned(
+            _ callUUID: UUID,
+            token: String,
+            effects: () -> Void
+        ) -> Bool {
+            return incomingRegistrationQueue.sync {
+                guard let callData = activeCalls[callUUID],
+                    callData["incomingRegistrationToken"] as? String == token
+                else {
+                    return false
+                }
+
+                effects()
+                return true
+            }
+        }
+
+        fileprivate func invalidateIncomingRegistration(_ callUUID: UUID) {
+            incomingRegistrationQueue.sync {
+                guard var callData = activeCalls[callUUID] else {
+                    return
+                }
+
+                callData.removeValue(forKey: "incomingRegistrationToken")
+                activeCalls[callUUID] = callData
+            }
+        }
+
         private override init() {
             super.init()
             // Only setup if explicitly requested via setup() method
@@ -825,10 +880,6 @@ import React
         }
 
         private func setupCallKit() {
-            // ALWAYS configure WebRTC audio, even if provider already exists
-            RTCAudioSession.sharedInstance().useManualAudio = true
-            RTCAudioSession.sharedInstance().isAudioEnabled = false
-
             // Guard against duplicate provider creation (async setupAutomatically can overwrite
             // the provider created by setupSynchronously for VoIP push)
             guard callKitProvider == nil else {
@@ -836,9 +887,84 @@ import React
                 return
             }
 
+            // Set the initial state only when installing the provider. Re-running setup after
+            // CallKit activation must never disable a live WebRTC audio device.
+            RTCAudioSession.sharedInstance().useManualAudio = true
+            RTCAudioSession.sharedInstance().isAudioEnabled = false
+
             _ = installCallKitProvider()
         }
 
+        fileprivate func activateWebRTCAudio(
+            _ audioSession: AVAudioSession = AVAudioSession.sharedInstance(),
+            reason: String
+        ) {
+            let rtcAudioSession = RTCAudioSession.sharedInstance()
+            rtcAudioSession.lockForConfiguration()
+            let wasAudioEnabled = rtcAudioSession.isAudioEnabled
+            NSLog("TelnyxVoice: activating WebRTC audio (\(reason)); enabled=\(wasAudioEnabled)")
+            let webRTCConfig = RTCAudioSessionConfiguration.webRTC()
+            webRTCConfig.categoryOptions = [.duckOthers, .allowBluetooth]
+            do {
+                try rtcAudioSession.setConfiguration(webRTCConfig)
+            } catch {
+                NSLog("TelnyxVoice: activateWebRTCAudio configuration (\(reason)) error: \(error)")
+            }
+
+            var activationSucceeded = false
+            do {
+                try rtcAudioSession.setActive(true)
+                activationSucceeded = true
+            } catch {
+                NSLog("TelnyxVoice: activateWebRTCAudio activation (\(reason)) error: \(error)")
+            }
+            if activationSucceeded {
+                rtcAudioSession.isAudioEnabled = true
+            } else if !wasAudioEnabled {
+                rtcAudioSession.isAudioEnabled = false
+            }
+            rtcAudioSession.unlockForConfiguration()
+            if activationSucceeded && !wasAudioEnabled {
+                rtcAudioSession.audioSessionDidActivate(audioSession)
+            }
+        }
+
+        fileprivate func verifyAudioAfterConnection(for callUUID: UUID) {
+            // didActivate is asynchronous after CXAnswerCallAction.fulfill(). Verify shortly
+            // afterwards so either callback ordering converges on the same idempotent state.
+            let verificationGeneration = currentAudioLifecycleGeneration()
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.75) { [weak self] in
+                guard let self,
+                    self.currentAudioLifecycleGeneration() == verificationGeneration,
+                    self.activeCalls[callUUID] != nil
+                else { return }
+                let rtcAudioSession = RTCAudioSession.sharedInstance()
+                rtcAudioSession.lockForConfiguration()
+                let isAudioEnabled = rtcAudioSession.isAudioEnabled
+                rtcAudioSession.unlockForConfiguration()
+                if isAudioEnabled {
+                    NSLog("TelnyxVoice: audio verification passed for \(callUUID)")
+                } else if AVAudioSession.sharedInstance().category != .playAndRecord {
+                    NSLog("TelnyxVoice: audio verification skipped for inactive CallKit session \(callUUID)")
+                } else {
+                    NSLog("TelnyxVoice: audio verification recovering disabled audio for \(callUUID)")
+                    self.activateWebRTCAudio(reason: "connected-call verification")
+                }
+            }
+        }
+
+        #if DEBUG
+            fileprivate func simulateAudioSetupRace(for callUUID: UUID, delay: TimeInterval) {
+                NSLog("TelnyxVoice: [VSUP-226] scheduling late audio reset in \(delay)s")
+                DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
+                    let rtcAudioSession = RTCAudioSession.sharedInstance()
+                    rtcAudioSession.isAudioEnabled = false
+                    NSLog("TelnyxVoice: [VSUP-226] injected late setup reset; enabled=false")
+                    self?.verifyAudioAfterConnection(for: callUUID)
+                }
+            }
+        #endif
+
         private func installCallKitProvider() -> CXProvider {
             // Use the localizedName from the app's bundle display name or fallback
             let appName =
@@ -977,7 +1103,36 @@ import React
             }
 
             if let activeCall = activeCalls[callUUID] {
-                guard activeCall["source"] as? String == "missed_call_push" else {
+                let activeSource = activeCall["source"] as? String
+
+                // A missed-call push normally reuses the original incoming
+                // push's call_id. End that still-ringing CallKit call and show
+                // the notification instead of treating it as a UUID collision.
+                if activeSource == "push_notification" || activeSource == "terminated_app_push"
+                    || activeSource == "push"
+                {
+                    NSLog(
+                        "TelnyxVoice: Missed call matched active incoming push UUID: \(callUUID)"
+                    )
+                    // Stop the original report callback from persisting or emitting
+                    // this call while the missed-call watchdog report is pending.
+                    invalidateIncomingRegistration(callUUID)
+                    // This is a second PushKit delivery, so report it to CallKit
+                    // with a fresh UUID before ending the original ringing call.
+                    reportAndEndWatchdogCall(
+                        callUUID: UUID(),
+                        callerName: callerName,
+                        callerNumber: callerNumber,
+                        payload: payload,
+                        source: "missed_call_matched_watchdog",
+                        endedReason: .remoteEnded
+                    ) {
+                        finishMissedCall()
+                    }
+                    return true
+                }
+
+                guard activeSource == "missed_call_push" else {
                     NSLog("TelnyxVoice: Suppressing missed call notification because UUID belongs to an active call: \(callUUID)")
                     markMissedCallProcessed(id: missedCallId)
                     reportAndEndWatchdogCall(
@@ -1404,6 +1559,7 @@ import React
                 "CallKitDidPerformEndCallAction", callUUID: action.callUUID,
                 callData: callData)
 
+            _ = advanceAudioLifecycleGeneration()
             activeCalls.removeValue(forKey: action.callUUID)
             pendingAnswerActions.removeValue(forKey: action.callUUID)?.fail()
             pendingHeldActions.removeValue(forKey: action.callUUID)?.fail()
@@ -1442,31 +1598,8 @@ import React
 
         public func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
             NSLog("TelnyxVoice: Audio session activated by CallKit")
-
-            let rtcAudioSession = RTCAudioSession.sharedInstance()
-
-            // Step 1: Configure (matches native iOS SDK setupCorrectAudioConfiguration)
-            rtcAudioSession.lockForConfiguration()
-            let webRTCConfig = RTCAudioSessionConfiguration.webRTC()
-            webRTCConfig.categoryOptions = [.duckOthers, .allowBluetooth]
-            do {
-                try rtcAudioSession.setConfiguration(webRTCConfig)
-            } catch {
-                NSLog("TelnyxVoice: didActivateAudioSession - setConfiguration error: \(error)")
-            }
-            rtcAudioSession.unlockForConfiguration()
-
-            // Step 2: Activate (matches native iOS SDK setAudioSessionActive)
-            rtcAudioSession.lockForConfiguration()
-            do {
-                try rtcAudioSession.setActive(true)
-            } catch {
-                NSLog("TelnyxVoice: didActivateAudioSession - setActive error: \(error)")
-            }
-            rtcAudioSession.isAudioEnabled = true
-            rtcAudioSession.unlockForConfiguration()
-
-            rtcAudioSession.audioSessionDidActivate(audioSession)
+            _ = advanceAudioLifecycleGeneration()
+            activateWebRTCAudio(audioSession, reason: "CallKit didActivate")
 
             // Emit audio session activated event to React Native
             CallKitBridge.shared?.emitAudioSessionEvent(
@@ -1480,6 +1613,7 @@ import React
 
         public func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
             NSLog("TelnyxVoice: Audio session deactivated by CallKit")
+            _ = advanceAudioLifecycleGeneration()
 
             let rtcAudioSession = RTCAudioSession.sharedInstance()
 
@@ -1657,6 +1791,7 @@ import React
 
             // Store call data manually and report to CallKit
             let isAppRunning = CallKitBridge.shared != nil
+            let registrationToken = UUID().uuidString
             callKitManager.activeCalls[callUUID] = [
                 "caller": callerName,
                 "handle": callerNumber,
@@ -1665,6 +1800,7 @@ import React
                 "direction": "incoming",
                 "source": isAppRunning ? "push_notification" : "terminated_app_push",
                 "isCallKitRegistered": false,
+                "incomingRegistrationToken": registrationToken,
             ]
 
             // Report to CallKit immediately
@@ -1676,56 +1812,68 @@ import React
             callUpdate.supportsHolding = true
 
             callKitProvider.reportNewIncomingCall(with: callUUID, update: callUpdate) { error in
-                if let error = error {
-                    let nsError = error as NSError
-                    let reason =
-                        nsError.domain == CXErrorDomainIncomingCall && nsError.code == 3
-                        ? "filteredByDoNotDisturb" : "registrationRejected"
-                    NSLog(
-                        "[TelnyxVoipPushHandler] CallKit incoming registration rejected: domain=\(nsError.domain), code=\(nsError.code), reason=\(reason)"
-                    )
-                    callKitManager.activeCalls.removeValue(forKey: callUUID)
-                    callKitManager.clearPendingPushData(for: callUUID.uuidString)
-                } else {
-                    NSLog(
-                        "[TelnyxVoipPushHandler] ✅ CallKit call reported successfully via unified path"
-                    )
-
-                    callKitManager.markCallKitRegistered(callUUID)
-                    self.storePendingVoipPush(payload.dictionaryPayload)
+                defer { completion() }
 
-                    // CRITICAL: Store the CallKit UUID for the React Native CallKitCoordinator
-                    // This allows the coordinator to find the existing CallKit call instead of creating a duplicate
-                    UserDefaults.standard.set(callUUID.uuidString, forKey: "@pending_callkit_uuid")
-                    UserDefaults.standard.synchronize()
-                    NSLog(
-                        "[TelnyxVoipPushHandler] ✅ Stored CallKit UUID for React Native coordinator: \(callUUID.uuidString)"
-                    )
-
-                    // Try to emit push received event if CallKit bridge is available
-                    if let callKitBridge = CallKitBridge.shared {
-                        let source = isAppRunning ? "push_notification" : "terminated_app_push"
-                        callKitBridge.emitCallEvent(
-                            "CallKitDidReceivePush", callUUID: callUUID,
-                            callData: [
-                                "caller": callerName,
-                                "handle": callerNumber,
-                                "payload": payload.dictionaryPayload,
-                                "uuid": callUUID.uuidString,
-                                "direction": "incoming",
-                                "source": source,
-                            ])
+                let handled = callKitManager.performIncomingRegistrationIfOwned(
+                    callUUID, token: registrationToken
+                ) {
+                    if let error = error {
+                        let nsError = error as NSError
+                        let reason =
+                            nsError.domain == CXErrorDomainIncomingCall && nsError.code == 3
+                            ? "filteredByDoNotDisturb" : "registrationRejected"
                         NSLog(
-                            "[TelnyxVoipPushHandler] ✅ Emitted CallKitDidReceivePush event to React Native"
+                            "[TelnyxVoipPushHandler] CallKit incoming registration rejected: domain=\(nsError.domain), code=\(nsError.code), reason=\(reason)"
                         )
+                        callKitManager.activeCalls.removeValue(forKey: callUUID)
+                        callKitManager.clearPendingPushData(for: callUUID.uuidString)
                     } else {
                         NSLog(
-                            "[TelnyxVoipPushHandler] ⚠️ React Native bridge not ready - event will be emitted when bridge becomes available"
+                            "[TelnyxVoipPushHandler] ✅ CallKit call reported successfully via unified path"
                         )
+
+                        callKitManager.markCallKitRegistered(callUUID)
+                        self.storePendingVoipPush(payload.dictionaryPayload)
+
+                        // CRITICAL: Store the CallKit UUID for the React Native CallKitCoordinator
+                        // This allows the coordinator to find the existing CallKit call instead of creating a duplicate
+                        UserDefaults.standard.set(
+                            callUUID.uuidString, forKey: "@pending_callkit_uuid")
+                        UserDefaults.standard.synchronize()
+                        NSLog(
+                            "[TelnyxVoipPushHandler] ✅ Stored CallKit UUID for React Native coordinator: \(callUUID.uuidString)"
+                        )
+
+                        // Try to emit push received event if CallKit bridge is available
+                        if let callKitBridge = CallKitBridge.shared {
+                            let source =
+                                isAppRunning ? "push_notification" : "terminated_app_push"
+                            callKitBridge.emitCallEvent(
+                                "CallKitDidReceivePush", callUUID: callUUID,
+                                callData: [
+                                    "caller": callerName,
+                                    "handle": callerNumber,
+                                    "payload": payload.dictionaryPayload,
+                                    "uuid": callUUID.uuidString,
+                                    "direction": "incoming",
+                                    "source": source,
+                                ])
+                            NSLog(
+                                "[TelnyxVoipPushHandler] ✅ Emitted CallKitDidReceivePush event to React Native"
+                            )
+                        } else {
+                            NSLog(
+                                "[TelnyxVoipPushHandler] ⚠️ React Native bridge not ready - event will be emitted when bridge becomes available"
+                            )
+                        }
                     }
                 }
 
-                completion()
+                if !handled {
+                    NSLog(
+                        "[TelnyxVoipPushHandler] Ignoring stale incoming registration completion for ended call: \(callUUID.uuidString)"
+                    )
+                }
             }
         }
 

package/lib/callkit/callkit-coordinator.d.ts

@@ -1,5 +1,12 @@
 import { Call } from '@telnyx/react-native-voice-sdk';
 import type { TelnyxVoipClient } from '../telnyx-voip-client';
+export type RemoteCallEndedReason = {
+  cause?: string;
+  causeCode?: number;
+  sipCode?: number;
+  sipReason?: string;
+  sipCallId?: string;
+};
 /**
  * CallKit Coordinator - Manages the proper CallKit-first flow for iOS
  *
@@ -11,6 +18,8 @@ declare class CallKitCoordinator {
   private static instance;
   private callMap;
   private processingCalls;
+  private activeOrAnsweringCallUUID;
+  private claimActiveCall;
   private endedCalls;
   private connectedCalls;
   private isCallFromPush;
@@ -80,6 +89,11 @@ declare class CallKitCoordinator {
    * before calling this method.
    */
   handleCallKitPushReceived(callKitUUID: string, event?: any): Promise<boolean>;
+  /** End a still-pending PushKit CallKit call after a remote hangup. */
+  handlePendingPushCallRemoteEnded(
+    callKitUUID: string,
+    reason?: RemoteCallEndedReason
+  ): Promise<boolean>;
   /**
    * Handle push notification answer - when user answers from CallKit but we don't have a WebRTC call yet
    * This is the iOS equivalent of the Android FCM handler
@@ -130,6 +144,7 @@ declare class CallKitCoordinator {
   private getSDKClient;
   private normalizeUUID;
   private actionKey;
+  private releaseActiveCall;
   private selectCall;
   private isSelectedCall;
   private recordPendingSwapAction;
@@ -152,6 +167,10 @@ declare class CallKitCoordinator {
    * This helps prevent premature flag resets during CallKit operations
    */
   hasProcessingCalls(): boolean;
+  /** @internal Exposed for deterministic single-active-call regression tests. */
+  claimActiveCallForTesting(callKitUUID: string): boolean;
+  /** @internal Exposed for deterministic single-active-call regression tests. */
+  releaseActiveCallForTesting(callKitUUID: string): void;
   /**
    * Check if there's currently a call from push notification being processed
    * This helps prevent disconnection during push call handling