@onekeyfe/hd-transport-react-native 1.2.0-alpha.98 → 1.2.0

package/src/index.ts

@@ -1,7 +1,6 @@
 import { PermissionsAndroid, Platform } from 'react-native';
 import { Buffer } from 'buffer';
 import {
-  BleATTErrorCode,
   BleError,
   BleErrorCode,
   BleManager as BlePlxManager,
@@ -29,7 +28,6 @@ import {
   HardwareErrorCode,
   createDeferred,
   isOnekeyBluetoothDevice,
-  isPro2FindMyAdvertisementName,
 } from '@onekeyfe/hd-shared';
 
 import { getConnectedDeviceIds, onDeviceBondState, pairDevice } from './BleManager';
@@ -49,17 +47,30 @@ import {
   getInfosForServiceUuid,
   isSameBleUuid,
 } from './constants';
+import {
+  isBleStaleBondHardwareError,
+  isNativeBleStaleBondError,
+  toBleStaleBondHardwareError,
+} from './bleStaleBond';
 import { isHeaderChunk } from './utils/validateNotify';
 import BleTransport from './BleTransport';
 import timer from './utils/timer';
 import { bleLogger, setBleLogger } from './logger';
-import { createTransportCallLog } from './transportLog';
 
 import type { Deferred } from '@onekeyfe/hd-shared';
 import type { Characteristic, Device, Subscription } from 'react-native-ble-plx';
 import type EventEmitter from 'events';
 import type { BleAcquireInput, TransportOptions } from './types';
 
+type FirmwareInstallBleAcquireInput = BleAcquireInput & {
+  /**
+   * Reuse the already-verified protocol after an expected firmware-install
+   * disconnect. The install loader accepts status requests but may not answer
+   * the generic protocol probe used by a normal acquire.
+   */
+  skipProtocolProbe?: boolean;
+};
+
 const { check, ProtocolV1, parseConfigure } = transport;
 
 const Log = bleLogger;
@@ -140,7 +151,7 @@ export const getFirmwareUploadWriteRetryType = (
 
 const resolveFirmwareUploadRetryDelay = (attempt: number, baseDelayMs = 200, maxDelayMs = 1200) =>
   Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-const PROTOCOL_PROBE_TIMEOUT_MS = 1000;
+const PROTOCOL_PROBE_TIMEOUT_MS = 3000;
 const PROTOCOL_V2_PROBE_TIMEOUT_MS = 10_000;
 /**
  * Per-packet write budget. iOS only resolves writeWithoutResponse once CoreBluetooth
@@ -151,6 +162,7 @@ const PROTOCOL_V2_PROBE_TIMEOUT_MS = 10_000;
  * A healthy packet completes in milliseconds, so this only fires on a dead link.
  */
 export const BLE_WRITE_PACKET_TIMEOUT_MS = 10_000;
+export const BLE_NATIVE_TEARDOWN_TIMEOUT_MS = 3_000;
 const WEDGED_WRITE_MESSAGE = 'BLE write timeout after';
 const isWedgedWriteError = (error: unknown): boolean =>
   (error as { errorCode?: unknown })?.errorCode === HardwareErrorCode.BleWriteCharacteristicError &&
@@ -204,10 +216,6 @@ export function getProtocolV2BleTuning() {
   return { ...protocolV2BleTuning };
 }
 
-function inferProtocolHintFromDeviceName(name?: string | null): ProtocolType | undefined {
-  return /\bpro\s*2\b/i.test(name ?? '') ? 'V2' : undefined;
-}
-
 function getDeviceDisplayName(device?: Device | null) {
   return device?.name || device?.localName || null;
 }
@@ -259,10 +267,17 @@ export const PROTOCOL_REPROBE_FALLBACK_ATTEMPTS = 3;
 /** BLE setup timeouts since the last successful setup before the manager is recreated. */
 export const BLE_CONNECT_TIMEOUT_MANAGER_RESET_THRESHOLD = 2;
 const CONNECT_TIMEOUT_MESSAGE = 'BLE connect timeout after';
+export const BLE_SETUP_WEDGED_MESSAGE = 'BLE setup wedged repeatedly';
 const isConnectTimeoutError = (error: unknown): boolean =>
   (error as { errorCode?: unknown })?.errorCode === HardwareErrorCode.BleConnectedError &&
   typeof (error as { message?: unknown })?.message === 'string' &&
   (error as { message: string }).message.startsWith(CONNECT_TIMEOUT_MESSAGE);
+const isWedgedBleSetupError = (error: unknown): boolean =>
+  (error as { errorCode?: unknown })?.errorCode === HardwareErrorCode.PollingTimeout &&
+  typeof (error as { message?: unknown })?.message === 'string' &&
+  (error as { message: string }).message.startsWith(BLE_SETUP_WEDGED_MESSAGE);
+const shouldRethrowBleSetupError = (error: unknown): boolean =>
+  isConnectTimeoutError(error) || isWedgedBleSetupError(error);
 const isNativeOperationTimeoutError = (error: unknown): boolean =>
   (error as { errorCode?: unknown })?.errorCode === BleErrorCode.OperationTimedOut;
 
@@ -305,15 +320,10 @@ const resolveNegotiatedMtu = (device: Device) => requestNegotiatedMtu(device, 'c
 
 type IOBleErrorRemap = Error | BleError | null | undefined;
 
-function remapError(error: IOBleErrorRemap) {
+function remapError(error: IOBleErrorRemap, mapProtocolV2StaleBond: boolean) {
   if (error instanceof BleError) {
-    if (
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-expect-error
-      error.iosErrorCode === BleATTErrorCode.UnlikelyError ||
-      error.reason === 'Peer removed pairing information'
-    ) {
-      throw ERRORS.TypedError(HardwareErrorCode.BlePeerRemovedPairingInformation);
+    if (mapProtocolV2StaleBond && isNativeBleStaleBondError(error)) {
+      throw toBleStaleBondHardwareError(error);
     }
 
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
@@ -382,9 +392,22 @@ export default class ReactNativeBleTransport {
   /** Protocol this device actually answered on, kept across reconnects of one session. */
   private sessionProtocols: Map<string, ProtocolType> = new Map();
 
+  /** Endpoints that answered a V2 probe in this transport lifetime. Survives disconnect. */
+  private confirmedProtocolV2 = new Set<string>();
+
   /** Consecutive detections that failed while trusting sessionProtocols. */
   private protocolReprobeFailures: Map<string, number> = new Map();
 
+  /**
+   * Native encryption/pairing failures seen before Protocol V2 probe starts.
+   * Pro2/Neo GATT connect can succeed on a stale iOS bond; the CCCD write then
+   * fails with ATT 5/15. Remember it so detectProtocol fails immediately.
+   */
+  private staleBondErrors: Map<string, Error> = new Map();
+
+  /** Strict or previously confirmed V2 target while acquire installs notifications. */
+  private acquiringProtocolV2 = new Set<string>();
+
   private protocolV2Assemblers: Map<string, ProtocolV2FrameAssembler> = new Map();
 
   private protocolV2FrameQueues: Map<string, Uint8Array[]> = new Map();
@@ -424,6 +447,9 @@ export default class ReactNativeBleTransport {
 
   private nextMonitorToken = 1;
 
+  /** Serializes transport lifecycle changes for the same physical device. */
+  private lifecycleOperations: Map<string, Promise<void>> = new Map();
+
   constructor(options: TransportOptions) {
     this.scanTimeout = options.scanTimeout ?? DEVICE_SCAN_TIMEOUT_MS;
   }
@@ -715,17 +741,15 @@ export default class ReactNativeBleTransport {
           // iOS may report a service-only advertisement before the named scan response.
           // Do not cache that incomplete advertisement as an unknown device.
           const isUnnamedIOSPeripheral = Platform.OS === 'ios' && !displayName?.trim();
-          const isFindMyPeripheral =
-            isPro2FindMyAdvertisementName(device?.name) ||
-            isPro2FindMyAdvertisementName(device?.localName);
           const isOneKey =
             !isUnnamedIOSPeripheral &&
-            !isFindMyPeripheral &&
             isOnekeyBluetoothDevice({
               id: device?.id,
               name: device?.name,
               localName: device?.localName,
-              serviceUuids: device?.serviceUUIDs,
+              // The native scan is already restricted to the OneKey communication service,
+              // but ble-plx permits the returned advertisement field to be null.
+              serviceUuids: device?.serviceUUIDs ?? getBluetoothServiceUuids(),
             });
           if (isOneKey) {
             addDevice(device as unknown as Device);
@@ -747,12 +771,7 @@ export default class ReactNativeBleTransport {
               'localName' in device && typeof device.localName === 'string'
                 ? device.localName
                 : null;
-            const isFindMyPeripheral =
-              isPro2FindMyAdvertisementName(device.name) ||
-              isPro2FindMyAdvertisementName(localName);
-
             if (
-              !isFindMyPeripheral &&
               isOnekeyBluetoothDevice({
                 id: device.id,
                 name: device.name,
@@ -770,10 +789,7 @@ export default class ReactNativeBleTransport {
       const addDevice = (device: Device) => {
         if (deviceList.every(d => d.id !== device.id)) {
           const displayName = getDeviceDisplayName(device) ?? 'Unknown BLE Device';
-          const protocolHint = inferProtocolHintFromDeviceName(displayName);
-          if (protocolHint) {
-            this.deviceProtocolHints.set(device.id, protocolHint);
-          }
+
           deviceList.push({
             ...device,
             name: displayName,
@@ -783,7 +799,6 @@ export default class ReactNativeBleTransport {
             deviceId: device.id,
             name: displayName,
             serviceUUIDs: device.serviceUUIDs,
-            protocolHint,
           });
         }
       };
@@ -868,32 +883,83 @@ export default class ReactNativeBleTransport {
     return transport;
   }
 
-  async acquire(input: BleAcquireInput) {
-    const { uuid, forceCleanRunPromise, expectedProtocol } = input;
+  async acquire(input: FirmwareInstallBleAcquireInput) {
+    const { uuid } = input;
 
     if (!uuid) {
       throw ERRORS.TypedError(HardwareErrorCode.BleRequiredUUID);
     }
 
+    return this.runLifecycleOperation(uuid, () => this.acquireUnlocked(input));
+  }
+
+  private async acquireUnlocked(input: FirmwareInstallBleAcquireInput) {
+    const { uuid, forceCleanRunPromise, expectedProtocol, skipProtocolProbe } = input;
+    const shouldMapProtocolV2StaleBond = expectedProtocol
+      ? expectedProtocol === 'V2'
+      : this.confirmedProtocolV2.has(uuid);
+
     const cachedTransport = transportCache[uuid];
+    if (skipProtocolProbe && !cachedTransport && this.blePlxManager) {
+      Log?.debug(
+        '[ReactNativeBleTransport] refresh uncached BLE connection for firmware install:',
+        uuid
+      );
+      const manager = this.blePlxManager;
+      await this.runNativeTeardown(uuid, manager, async () => {
+        await this.runBestEffortNativeOperation(
+          'firmware install reconnect: cancel uncached device connection',
+          () => manager.cancelDeviceConnection(uuid)
+        );
+      });
+    }
     if (cachedTransport) {
-      const cachedProtocol = this.deviceProtocol.get(uuid);
-      const isCachedDeviceConnected = await cachedTransport.device.isConnected().catch(() => false);
-      if (
-        isCachedDeviceConnected &&
-        cachedProtocol &&
-        (!expectedProtocol || cachedProtocol === expectedProtocol)
-      ) {
-        Log?.debug('[ReactNativeBleTransport] reuse cached BLE transport:', uuid, cachedProtocol);
-        return { uuid, protocolType: cachedProtocol };
-      }
+      if (skipProtocolProbe) {
+        Log?.debug(
+          '[ReactNativeBleTransport] refresh cached BLE connection for firmware install:',
+          uuid
+        );
+        const manager = this.blePlxManager;
+        await this.releaseUnlocked(uuid, true);
+        await this.runNativeTeardown(uuid, manager, async () => {
+          const operations: Promise<unknown>[] = [];
+          if (manager) {
+            operations.push(
+              this.runBestEffortNativeOperation(
+                'firmware install reconnect: cancel device connection',
+                () => manager.cancelDeviceConnection(uuid)
+              )
+            );
+          }
+          operations.push(
+            this.runBestEffortNativeOperation(
+              'firmware install reconnect: device cancel connection',
+              () => cachedTransport.device.cancelConnection()
+            )
+          );
+          await Promise.all(operations);
+        });
+      } else {
+        const cachedProtocol = this.deviceProtocol.get(uuid);
+        const isCachedDeviceConnected = await cachedTransport.device
+          .isConnected()
+          .catch(() => false);
+        if (
+          isCachedDeviceConnected &&
+          cachedProtocol &&
+          (!expectedProtocol || cachedProtocol === expectedProtocol)
+        ) {
+          Log?.debug('[ReactNativeBleTransport] reuse cached BLE transport:', uuid, cachedProtocol);
+          return { uuid, protocolType: cachedProtocol };
+        }
 
-      /**
-       * If the transport is not reusable due to a protocol mismatch or stale
-       * connection, clean it up before creating a new transport instance.
-       */
-      Log?.debug('transport not reusable, will release: ', uuid);
-      await this.release(uuid, true);
+        /**
+         * If the transport is not reusable due to a protocol mismatch or stale
+         * connection, clean it up before creating a new transport instance.
+         */
+        Log?.debug('transport not reusable, will release: ', uuid);
+        await this.releaseUnlocked(uuid, true);
+      }
     }
 
     let device: Device | null = null;
@@ -943,7 +1009,7 @@ export default class ReactNativeBleTransport {
         );
       } catch (e) {
         Log?.debug('try to connect to device has error: ', e);
-        if (isConnectTimeoutError(e)) {
+        if (shouldRethrowBleSetupError(e)) {
           throw e;
         }
         if (
@@ -958,7 +1024,7 @@ export default class ReactNativeBleTransport {
           Log?.debug('device already connected');
           throw ERRORS.TypedError(HardwareErrorCode.BleAlreadyConnected);
         } else {
-          remapError(e);
+          remapError(e, shouldMapProtocolV2StaleBond);
         }
       }
     }
@@ -977,7 +1043,7 @@ export default class ReactNativeBleTransport {
         );
       } catch (e) {
         Log?.debug('not connected, try to connect to device has error: ', e);
-        if (isConnectTimeoutError(e)) {
+        if (shouldRethrowBleSetupError(e)) {
           throw e;
         }
         if (
@@ -1002,7 +1068,7 @@ export default class ReactNativeBleTransport {
             }
           }
         } else {
-          remapError(e);
+          remapError(e, shouldMapProtocolV2StaleBond);
         }
       }
     }
@@ -1014,22 +1080,56 @@ export default class ReactNativeBleTransport {
 
     const protocolHint = expectedProtocol
       ? undefined
-      : input.protocolHint ??
-        this.deviceProtocolHints.get(uuid) ??
-        inferProtocolHintFromDeviceName(getDeviceDisplayName(acquiredDevice));
+      : input.protocolHint ?? this.deviceProtocolHints.get(uuid);
 
     // release transport before new transport instance
-    await this.release(uuid, true);
+    await this.releaseUnlocked(uuid, true);
     if (protocolHint) {
       this.deviceProtocolHints.set(uuid, protocolHint);
     }
 
-    await this.installTransportForAcquire(uuid, acquiredDevice, {
-      writeCharacteristic,
-      notifyCharacteristic,
-    });
+    if (shouldMapProtocolV2StaleBond) {
+      this.acquiringProtocolV2.add(uuid);
+    }
 
     try {
+      await this.installTransportForAcquire(uuid, acquiredDevice, {
+        writeCharacteristic,
+        notifyCharacteristic,
+      });
+
+      if (skipProtocolProbe) {
+        if (!expectedProtocol) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.RuntimeError,
+            'skipProtocolProbe requires an expected BLE protocol'
+          );
+        }
+        const hasConfirmedProtocol =
+          this.sessionProtocols.get(uuid) === expectedProtocol ||
+          (expectedProtocol === 'V2' && this.confirmedProtocolV2.has(uuid));
+        if (!hasConfirmedProtocol) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.RuntimeError,
+            'skipProtocolProbe requires a previously confirmed protocol for this BLE endpoint'
+          );
+        }
+        this.deviceProtocol.set(uuid, expectedProtocol);
+        this.sessionProtocols.set(uuid, expectedProtocol);
+        this.protocolReprobeFailures.delete(uuid);
+        Log?.debug('[ReactNativeBleTransport] protocol selected without probe', {
+          deviceId: uuid,
+          protocol: expectedProtocol,
+          source: 'firmware-install-reconnect',
+        });
+        const currentTransport = transportCache[uuid];
+        if (!currentTransport) {
+          throw ERRORS.TypedError(HardwareErrorCode.TransportNotFound);
+        }
+        this.attachDisconnectSubscription(currentTransport, currentTransport.device, uuid);
+        return { uuid, protocolType: expectedProtocol };
+      }
+
       const protocolType = await this.detectProtocol(
         uuid,
         expectedProtocol,
@@ -1045,8 +1145,14 @@ export default class ReactNativeBleTransport {
       this.attachDisconnectSubscription(currentTransport, currentTransport.device, uuid);
       return { uuid, protocolType };
     } catch (error) {
-      await this.release(uuid, true);
+      if (isBleStaleBondHardwareError(error)) {
+        await this.disconnectUnlocked(uuid);
+      } else {
+        await this.releaseUnlocked(uuid, true);
+      }
       throw error;
+    } finally {
+      this.acquiringProtocolV2.delete(uuid);
     }
   }
 
@@ -1074,17 +1180,21 @@ export default class ReactNativeBleTransport {
           Log?.debug('monitor error ignored for stale transport: ', uuid, notifyTransactionId);
           return;
         }
+        if (
+          (this.getActiveProtocol(uuid) === 'V2' || this.acquiringProtocolV2.has(uuid)) &&
+          isNativeBleStaleBondError(error)
+        ) {
+          this.rememberStaleBondError(uuid, toBleStaleBondHardwareError(error));
+          return;
+        }
         if (this.getActiveProtocol(uuid) === 'V2') {
           let errorCode:
-            | typeof HardwareErrorCode.BleDeviceBondError
             | typeof HardwareErrorCode.BleCharacteristicNotifyError
             | typeof HardwareErrorCode.BleCharacteristicNotifyChangeFailure
             | typeof HardwareErrorCode.BleTimeoutError =
             HardwareErrorCode.BleCharacteristicNotifyError;
           if (error.reason?.includes('The connection has timed out unexpectedly')) {
             errorCode = HardwareErrorCode.BleTimeoutError;
-          } else if (error.reason?.includes('Encryption is insufficient')) {
-            errorCode = HardwareErrorCode.BleDeviceBondError;
           } else if (
             error.reason?.includes('Cannot write client characteristic config descriptor') ||
             error.reason?.includes('Cannot find client characteristic config descriptor') ||
@@ -1099,16 +1209,12 @@ export default class ReactNativeBleTransport {
         }
         if (this.runPromise && this.runPromiseDeviceId === uuid) {
           let ERROR:
-            | typeof HardwareErrorCode.BleDeviceBondError
             | typeof HardwareErrorCode.BleCharacteristicNotifyError
             | typeof HardwareErrorCode.BleTimeoutError =
             HardwareErrorCode.BleCharacteristicNotifyError;
           if (error.reason?.includes('The connection has timed out unexpectedly')) {
             ERROR = HardwareErrorCode.BleTimeoutError;
           }
-          if (error.reason?.includes('Encryption is insufficient')) {
-            ERROR = HardwareErrorCode.BleDeviceBondError;
-          }
           if (
             error.reason?.includes('Cannot write client characteristic config descriptor') ||
             error.reason?.includes('Cannot find client characteristic config descriptor') || // pro firmware 2.3.0 upgrade
@@ -1190,12 +1296,17 @@ export default class ReactNativeBleTransport {
   }
 
   async release(uuid: string, onclose = false) {
+    return this.runLifecycleOperation(uuid, () => this.releaseUnlocked(uuid, onclose));
+  }
+
+  private async releaseUnlocked(uuid: string, onclose = false) {
     await this.protocolV2Links.invalidateLink(uuid, 'React Native BLE transport released');
     return this.releaseNative(uuid, onclose);
   }
 
   private async releaseNative(uuid: string, onclose = false) {
     const transport = transportCache[uuid];
+    const manager = this.blePlxManager;
     if (this.runPromise && this.runPromiseDeviceId === uuid) {
       const error = ERRORS.TypedError(HardwareErrorCode.BleForceCleanRunPromise);
       this.runPromise.reject(error);
@@ -1212,8 +1323,6 @@ export default class ReactNativeBleTransport {
       return Promise.resolve(true);
     }
 
-    await this.restoreAndroidConnectionPriority(uuid, transport);
-
     if (transport) {
       if (this.monitorTokens.get(uuid) === transport.monitorToken) {
         this.monitorTokens.delete(uuid);
@@ -1231,37 +1340,58 @@ export default class ReactNativeBleTransport {
       );
       transport.notifySubscription?.remove();
       transport.notifySubscription = undefined;
-
-      if (transport.notifyTransactionId) {
-        try {
-          await this.blePlxManager?.cancelTransaction(transport.notifyTransactionId);
-        } catch (e) {
-          Log?.debug('release: cancel notify transaction error (ignored): ', e?.message || e);
-        }
+      if (transportCache[uuid] === transport) {
+        delete transportCache[uuid];
       }
-
-      delete transportCache[uuid];
     }
 
     this.protocolV2HighVolumeLogSignatures.delete(uuid);
 
     this.deviceProtocol.delete(uuid);
     this.probingProtocols.delete(uuid);
-    // Preserve a name-derived hint across disconnects so reconnect can probe V2 first.
+    this.staleBondErrors.delete(uuid);
+    this.acquiringProtocolV2.delete(uuid);
+    // Confirmed protocol and caller hints stay in deviceProtocol / protocolHint.
     this.protocolV2Assemblers.get(uuid)?.reset();
     this.protocolV2Assemblers.delete(uuid);
     this.resetProtocolV2Frames(uuid);
 
-    try {
-      await this.blePlxManager?.cancelTransaction(uuid);
-    } catch (e) {
-      Log?.debug('release: cancel transaction error (ignored): ', e?.message || e);
-    }
+    await this.runNativeTeardown(uuid, manager, async () => {
+      const operations: Promise<unknown>[] = [
+        this.runBestEffortNativeOperation('release: restore connection priority', () =>
+          this.restoreAndroidConnectionPriority(uuid, transport)
+        ),
+      ];
+      if (transport?.notifyTransactionId && manager) {
+        operations.push(
+          this.runBestEffortNativeOperation('release: cancel notify transaction', () =>
+            manager.cancelTransaction(transport.notifyTransactionId as string)
+          )
+        );
+      }
+      if (manager) {
+        operations.push(
+          this.runBestEffortNativeOperation('release: cancel transaction', () =>
+            manager.cancelTransaction(uuid)
+          )
+        );
+      }
+      await Promise.all(operations);
+    });
 
     return Promise.resolve(true);
   }
 
   async post(session: string, name: string, data: Record<string, unknown>) {
+    if (this.getProtocolType(session) === 'V2') {
+      await this.protocolV2Links.sendFlowControl(
+        session,
+        () => this.createProtocolV2Adapter(session),
+        name,
+        data
+      );
+      return;
+    }
     await this.call(session, name, data);
   }
 
@@ -1286,8 +1416,6 @@ export default class ReactNativeBleTransport {
         `Device protocol has not been detected for ${uuid}`
       );
     }
-    Log?.debug('transport call', createTransportCallLog(name, protocol, data));
-
     if (protocol === 'V2') {
       return this.callProtocolV2(uuid, name, data, options);
     }
@@ -1554,8 +1682,13 @@ export default class ReactNativeBleTransport {
   }
 
   async disconnect(session: string) {
+    return this.runLifecycleOperation(session, () => this.disconnectUnlocked(session));
+  }
+
+  private async disconnectUnlocked(session: string) {
     await this.protocolV2Links.invalidateLink(session, 'React Native BLE transport disconnected');
     const transport = transportCache[session];
+    const manager = this.blePlxManager;
     const monitorToken = transport?.monitorToken ?? this.monitorTokens.get(session);
 
     // Clean up disconnect subscription first to prevent onDisconnected callback
@@ -1584,37 +1717,13 @@ export default class ReactNativeBleTransport {
       }
     }
 
-    // cancel the ble transaction
-    if (session) {
-      try {
-        await this.blePlxManager?.cancelTransaction(session);
-      } catch (e) {
-        Log?.debug('resetSession: cancel transaction error (ignored): ', e?.message || e);
-      }
-    }
-
-    // disconnect the device via the device object
-    if (transport?.device) {
-      try {
-        await transport.device.cancelConnection();
-      } catch (e) {
-        Log?.debug('resetSession: device.cancelConnection error (ignored): ', e?.message || e);
-      }
-    }
-
-    // disconnect the device via the ble manager
-    try {
-      await this.blePlxManager?.cancelDeviceConnection(session);
-    } catch (e) {
-      Log?.debug('resetSession: manager.cancelDeviceConnection error (ignored): ', e?.message || e);
-    }
-
     // clear the transport cache
-    if (transportCache[session]) {
+    if (!transport || transportCache[session] === transport) {
       delete transportCache[session];
     }
     this.deviceProtocol.delete(session);
     this.probingProtocols.delete(session);
+    this.staleBondErrors.delete(session);
     this.deviceProtocolHints.delete(session);
     this.sessionProtocols.delete(session);
     this.protocolReprobeFailures.delete(session);
@@ -1630,10 +1739,97 @@ export default class ReactNativeBleTransport {
     if (monitorToken !== undefined && this.monitorTokens.get(session) === monitorToken) {
       this.monitorTokens.delete(session);
     }
+
+    await this.runNativeTeardown(session, manager, async () => {
+      const operations: Promise<unknown>[] = [];
+      if (manager) {
+        operations.push(
+          this.runBestEffortNativeOperation('disconnect: cancel transaction', () =>
+            manager.cancelTransaction(session)
+          )
+        );
+        operations.push(
+          this.runBestEffortNativeOperation('disconnect: cancel device connection', () =>
+            manager.cancelDeviceConnection(session)
+          )
+        );
+      }
+      if (transport?.device) {
+        operations.push(
+          this.runBestEffortNativeOperation('disconnect: device cancel connection', () =>
+            transport.device.cancelConnection()
+          )
+        );
+      }
+      await Promise.all(operations);
+    });
+
     // eslint-disable-next-line no-promise-executor-return
     await new Promise<void>(resolve => setTimeout(() => resolve(), 100));
   }
 
+  private async runNativeTeardown(
+    uuid: string,
+    manager: BlePlxManager | undefined,
+    teardown: () => Promise<void>
+  ) {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    const pending = Promise.resolve()
+      .then(teardown)
+      .catch(error => {
+        Log?.debug('BLE native teardown error (ignored): ', error?.message || error);
+      });
+    try {
+      await Promise.race([
+        pending,
+        new Promise<void>(resolve => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            resolve();
+          }, BLE_NATIVE_TEARDOWN_TIMEOUT_MS);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+
+    if (timedOut) {
+      Log?.error('[ReactNativeBleTransport] BLE native teardown timed out:', uuid);
+      if (this.blePlxManager === manager) {
+        this.resetPlxManager();
+      }
+    }
+  }
+
+  private runBestEffortNativeOperation(label: string, operation: () => Promise<unknown>) {
+    return Promise.resolve()
+      .then(operation)
+      .catch(error => {
+        Log?.debug(`${label} error (ignored): `, error?.message || error);
+      });
+  }
+
+  private async runLifecycleOperation<T>(uuid: string, operation: () => Promise<T>): Promise<T> {
+    const previousOperation = this.lifecycleOperations.get(uuid) ?? Promise.resolve();
+    let completeOperation!: () => void;
+    const operationGate = new Promise<void>(resolve => {
+      completeOperation = resolve;
+    });
+    const operationTail = previousOperation.catch(() => undefined).then(() => operationGate);
+    this.lifecycleOperations.set(uuid, operationTail);
+
+    await previousOperation.catch(() => undefined);
+    try {
+      return await operation();
+    } finally {
+      completeOperation();
+      if (this.lifecycleOperations.get(uuid) === operationTail) {
+        this.lifecycleOperations.delete(uuid);
+      }
+    }
+  }
+
   cancel() {
     Log?.debug('transport-react-native transport cancel');
     if (this.runPromise) {
@@ -1669,7 +1865,13 @@ export default class ReactNativeBleTransport {
       return result;
     } catch (error) {
       if (timedOut || isNativeOperationTimeoutError(error)) {
-        this.abandonStalledConnection(uuid, timedOut ? 'connect-backstop' : 'connect-native');
+        const resetManager = this.abandonStalledConnection(
+          uuid,
+          timedOut ? 'connect-backstop' : 'connect-native'
+        );
+        if (resetManager) {
+          throw this.createWedgedBleSetupError();
+        }
       }
       throw error;
     } finally {
@@ -1705,7 +1907,13 @@ export default class ReactNativeBleTransport {
       return result;
     } catch (error) {
       if (timedOut || isNativeOperationTimeoutError(error)) {
-        this.abandonStalledConnection(uuid, timedOut ? 'gatt-backstop' : 'gatt-native');
+        const resetManager = this.abandonStalledConnection(
+          uuid,
+          timedOut ? 'gatt-backstop' : 'gatt-native'
+        );
+        if (resetManager) {
+          throw this.createWedgedBleSetupError();
+        }
       }
       throw error;
     } finally {
@@ -1717,11 +1925,12 @@ export default class ReactNativeBleTransport {
    * Give up on a BLE setup operation the native layer did not settle. The abandoned
    * operation still owns native connection/GATT state that can poison the next attempt,
    * so it is cleared here without awaiting the same queue that stopped responding.
+   * Returns true when the manager itself was reset so the caller can stop Core retries.
    */
   private abandonStalledConnection(
     uuid: string,
     stage: 'connect-backstop' | 'connect-native' | 'gatt-backstop' | 'gatt-native'
-  ) {
+  ): boolean {
     const timeouts = (this.connectionSetupTimeoutCounts.get(uuid) ?? 0) + 1;
     this.connectionSetupTimeoutCounts.set(uuid, timeouts);
     Log?.error('[ReactNativeBleTransport] BLE setup timed out:', uuid, {
@@ -1738,6 +1947,8 @@ export default class ReactNativeBleTransport {
     }
     this.deviceProtocol.delete(uuid);
     this.probingProtocols.delete(uuid);
+    this.staleBondErrors.delete(uuid);
+    this.acquiringProtocolV2.delete(uuid);
     this.protocolV2Assemblers.delete(uuid);
     this.resetProtocolV2Frames(uuid);
 
@@ -1747,7 +1958,15 @@ export default class ReactNativeBleTransport {
       Log?.error('[ReactNativeBleTransport] BLE setup wedged repeatedly, resetting BLE manager');
       this.resetPlxManager();
       this.connectionSetupTimeoutCounts.delete(uuid);
+      return true;
     }
+    return false;
+  }
+
+  private createWedgedBleSetupError() {
+    // PollingTimeout is not retried by connectDeviceForBle and already maps
+    // to the App "connection failed" help text.
+    return ERRORS.TypedError(HardwareErrorCode.PollingTimeout, BLE_SETUP_WEDGED_MESSAGE);
   }
 
   private getCachedTransport(uuid: string) {
@@ -1826,6 +2045,8 @@ export default class ReactNativeBleTransport {
     }
     this.deviceProtocol.delete(uuid);
     this.probingProtocols.delete(uuid);
+    this.staleBondErrors.delete(uuid);
+    this.acquiringProtocolV2.delete(uuid);
     this.protocolV2Assemblers.delete(uuid);
     this.resetProtocolV2Frames(uuid);
 
@@ -1842,13 +2063,45 @@ export default class ReactNativeBleTransport {
   private resetPlxManager() {
     const manager = this.blePlxManager;
     this.blePlxManager = undefined;
-    // Every cached transport belongs to the destroyed manager's peripherals.
-    Object.keys(transportCache).forEach(key => {
-      delete transportCache[key];
+    const reason = 'React Native BLE manager reset';
+    // Destroying the shared manager invalidates every peripheral it owns. Notify
+    // each cached session before clearing generations so Core cannot retain a
+    // silently stale connection for an unrelated device.
+    Object.entries(transportCache).forEach(([uuid, cachedTransport]) => {
+      try {
+        cachedTransport.disconnectSubscription?.remove();
+      } catch (error) {
+        Log?.debug('BLE manager reset disconnect subscription removal failed:', error);
+      }
+      cachedTransport.disconnectSubscription = undefined;
+      try {
+        cachedTransport.notifySubscription?.remove();
+      } catch (error) {
+        Log?.debug('BLE manager reset notify subscription removal failed:', error);
+      }
+      cachedTransport.notifySubscription = undefined;
+      this.rejectProtocolV2Frames(uuid, new Error(reason));
+      try {
+        this.emitDeviceDisconnect(
+          uuid,
+          cachedTransport.device?.name,
+          cachedTransport.monitorToken ?? this.monitorTokens.get(uuid)
+        );
+      } catch (error) {
+        Log?.debug('BLE manager reset disconnect event failed:', error);
+      }
+      delete transportCache[uuid];
+    });
+    this.protocolV2Links.invalidateAllLinks(reason).catch(error => {
+      Log?.debug('[ReactNativeBleTransport] BLE manager link invalidation failed:', error);
     });
     this.deviceProtocol.clear();
     this.probingProtocols.clear();
+    this.staleBondErrors.clear();
+    this.acquiringProtocolV2.clear();
     this.sessionProtocols.clear();
+    // Keep transport-lifetime V2 proof so the same endpoint can finish a no-probe
+    // firmware reconnect after the native BLE manager is recreated.
     this.protocolReprobeFailures.clear();
     this.writeTimeoutCounts.clear();
     this.connectionSetupTimeoutCounts.clear();
@@ -1862,6 +2115,8 @@ export default class ReactNativeBleTransport {
   }
 
   private createProtocolMismatchError(expected: ProtocolType) {
+    // A protocol probe miss alone does not prove that the OS bond is stale.
+    // Native authentication/encryption failures are mapped separately.
     return ERRORS.TypedError(
       HardwareErrorCode.RuntimeError,
       `Device protocol mismatch: expected ${expected}, but device did not respond to expected protocol`
@@ -1895,34 +2150,35 @@ export default class ReactNativeBleTransport {
     protocolHint?: ProtocolType,
     rebuildTransport?: () => Promise<void>
   ): Promise<ProtocolType> {
-    if (Platform.OS === 'ios' && expectedProtocol) {
-      this.deviceProtocol.set(uuid, expectedProtocol);
+    // A declared V1 is taken at face value on every platform, as iOS has done
+    // since protocol probing arrived: the caller reads the protocol off its own
+    // device record, so the probe re-asks a question that is already answered
+    // and costs a round trip on every acquire. Expected V2 must still Ping so
+    // USB-priority `link disabled` surfaces here instead of as a later unmapped
+    // RuntimeError. sessionProtocols is deliberately NOT stamped here: that map
+    // records protocols the device actually answered on (it gates the
+    // trustSessionProtocol narrowing in forced detection), and this branch has
+    // received no response. skipProtocolProbe does not need it either — its only
+    // caller is the V2 firmware-install reconnect.
+    if (expectedProtocol === 'V1') {
+      this.deviceProtocol.set(uuid, 'V1');
       Log?.debug('[ReactNativeBleTransport] protocol selected', {
         deviceId: uuid,
-        protocol: expectedProtocol,
+        protocol: 'V1',
         source: 'expected',
       });
-      return expectedProtocol;
+      return 'V1';
     }
 
-    if (expectedProtocol === 'V1') {
-      if (await this.probeProtocolV1(uuid)) {
-        this.deviceProtocol.set(uuid, 'V1');
-        this.sessionProtocols.set(uuid, 'V1');
-        Log?.debug('[ReactNativeBleTransport] protocol detected', {
-          deviceId: uuid,
-          protocol: 'V1',
-          source: 'expected',
-        });
-        return 'V1';
-      }
-      throw this.createProtocolMismatchError(expectedProtocol);
+    if (expectedProtocol === 'V2' || this.acquiringProtocolV2.has(uuid)) {
+      this.throwIfStaleBondError(uuid);
     }
 
     if (expectedProtocol === 'V2') {
       if (await this.probeProtocolV2(uuid)) {
         this.deviceProtocol.set(uuid, 'V2');
         this.sessionProtocols.set(uuid, 'V2');
+        this.confirmedProtocolV2.add(uuid);
         Log?.debug('[ReactNativeBleTransport] protocol detected', {
           deviceId: uuid,
           protocol: 'V2',
@@ -1965,6 +2221,9 @@ export default class ReactNativeBleTransport {
       if (detected) {
         this.deviceProtocol.set(uuid, protocol);
         this.sessionProtocols.set(uuid, protocol);
+        if (protocol === 'V2') {
+          this.confirmedProtocolV2.add(uuid);
+        }
         this.protocolReprobeFailures.delete(uuid);
         Log?.debug('[ReactNativeBleTransport] protocol detected', {
           deviceId: uuid,
@@ -2071,6 +2330,7 @@ export default class ReactNativeBleTransport {
 
     this.probingProtocols.set(uuid, 'V2');
     this.protocolV2Assemblers.get(uuid)?.reset();
+    this.throwIfStaleBondError(uuid);
     const detected = await probeProtocolV2Helper({
       call: (name: string, data: Record<string, unknown>, options?: TransportCallOptions) =>
         this.callProtocolV2(uuid, name, data, options),
@@ -2081,6 +2341,7 @@ export default class ReactNativeBleTransport {
         this.protocolV2Assemblers.get(uuid)?.reset();
         this.resetProtocolV2Frames(uuid);
       },
+      shouldRethrow: isBleStaleBondHardwareError,
     });
     if (!detected) {
       this.clearProbeProtocol(uuid, 'V2');
@@ -2149,6 +2410,21 @@ export default class ReactNativeBleTransport {
     }
   }
 
+  private rememberStaleBondError(uuid: string, error: Error) {
+    this.staleBondErrors.set(uuid, error);
+    this.rejectProtocolV2Frames(uuid, error);
+    if (this.runPromise && this.runPromiseDeviceId === uuid) {
+      this.runPromise.reject(error);
+    }
+  }
+
+  private throwIfStaleBondError(uuid: string) {
+    const error = this.staleBondErrors.get(uuid);
+    if (error) {
+      throw error;
+    }
+  }
+
   private async readProtocolV2Frame(uuid: string) {
     const queuedFrame = this.getProtocolV2FrameQueue(uuid).shift();
     if (queuedFrame) {
@@ -2207,6 +2483,11 @@ export default class ReactNativeBleTransport {
         assertCurrentGeneration();
         return;
       } catch (error) {
+        if (isNativeBleStaleBondError(error) || isBleStaleBondHardwareError(error)) {
+          const bondError = toBleStaleBondHardwareError(error);
+          this.rememberStaleBondError(uuid, bondError);
+          throw bondError;
+        }
         if (
           getFirmwareUploadWriteRetryType(error) !== 'congested' ||
           attempt >= FIRMWARE_UPLOAD_WRITE_MAX_RETRIES
@@ -2443,6 +2724,7 @@ export default class ReactNativeBleTransport {
         return rxFrame;
       },
       reset: (reason: string) => {
+        if (this.monitorTokens.get(uuid) !== generation) return;
         this.protocolV2Assemblers.get(uuid)?.reset();
         this.rejectProtocolV2Frames(uuid, new Error(reason));
       },