@onekeyfe/hd-transport-electron 1.2.2-alpha.101 → 1.2.2-alpha.103

package/src/noble-ble-handler.ts

@@ -40,6 +40,31 @@ import type { CharacteristicPair, DeviceInfo, Logger, NobleModule } from './type
 // Noble will be dynamically imported to avoid bundling issues
 let noble: NobleModule | null = null;
 let logger: Logger | null = null;
+let disposing = false;
+let nativeReleased = false;
+let disposePromise: Promise<void> | undefined;
+let windowCleanup: Promise<void> | undefined;
+let removeIpcHandlers: (() => void) | undefined;
+const pendingCancellations = new Set<() => void>();
+const nativeConnections = new Set<{ cancel: () => void; settled: Promise<void> }>();
+
+function trackNativeConnection(operation: Promise<unknown>, cancel: () => void): void {
+  const connection = {
+    cancel,
+    settled: operation.then(
+      () => undefined,
+      () => undefined
+    ),
+  };
+  nativeConnections.add(connection);
+  connection.settled = connection.settled.finally(() => nativeConnections.delete(connection));
+}
+
+function assertBleActive(): void {
+  if (disposing) {
+    throw ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down');
+  }
+}
 
 type NobleBleNativeError = Error & {
   nativeErrorCode?: number;
@@ -49,7 +74,8 @@ type NobleBleNativeError = Error & {
 export function createNobleBleConnectionError(error: NobleBleNativeError, messagePrefix = '') {
   const errorMessage = error.message;
   const isInvalidMacOsBond =
-    error.nativeErrorCode === 14 && error.nativeErrorDomain === 'CBErrorDomain';
+    (error.nativeErrorCode === 14 && error.nativeErrorDomain === 'CBErrorDomain') ||
+    (error.nativeErrorCode === 15 && error.nativeErrorDomain === 'CBATTErrorDomain');
   if (isInvalidMacOsBond) {
     const nativeErrorMessage = `${messagePrefix}${errorMessage}`;
     return ERRORS.TypedError(
@@ -116,6 +142,102 @@ let persistentDiscoverListener: ((peripheral: Peripheral) => void) | null = null
 // Device cache and connection state
 const discoveredDevices = new Map<string, Peripheral>();
 const connectedDevices = new Map<string, Peripheral>();
+type PendingDeviceConnection = {
+  peripheral: Peripheral;
+  generation: number;
+  cancel: (error: unknown) => void;
+};
+const connectingDevices = new Map<string, PendingDeviceConnection>();
+let nextConnectionGeneration = 0;
+
+function connectPeripheralWithCancellation(
+  peripheral: Peripheral,
+  deviceId: string,
+  messagePrefix = ''
+): Promise<void> {
+  assertBleActive();
+  return new Promise<void>((resolve, reject) => {
+    const generation = ++nextConnectionGeneration;
+    let settled = false;
+    const settle = (settler: () => void): boolean => {
+      if (settled) return false;
+      settled = true;
+      if (connectingDevices.get(deviceId)?.generation === generation) {
+        connectingDevices.delete(deviceId);
+      }
+      settler();
+      return true;
+    };
+    const pendingConnection: PendingDeviceConnection = {
+      peripheral,
+      generation,
+      cancel: error => {
+        settle(() => reject(error));
+      },
+    };
+    connectingDevices
+      .get(deviceId)
+      ?.cancel(
+        ERRORS.TypedError(
+          HardwareErrorCode.BleDeviceDisconnected,
+          `Device ${deviceId} connect attempt was superseded`
+        )
+      );
+    connectingDevices.set(deviceId, pendingConnection);
+
+    let completeNative!: () => void;
+    trackNativeConnection(
+      new Promise<void>(resolve => {
+        completeNative = resolve;
+      }),
+      () => {
+        if (typeof peripheral.cancelConnect === 'function') peripheral.cancelConnect();
+        else noble?.cancelConnect?.(deviceId);
+      }
+    );
+    const onConnect = (error?: Error | null) => {
+      if (nativeReleased) {
+        completeNative();
+        return;
+      }
+      if (error) {
+        settle(() => reject(createNobleBleConnectionError(error, messagePrefix)));
+        completeNative();
+        return;
+      }
+
+      if (
+        !settle(() => {
+          connectedDevices.set(deviceId, peripheral);
+          resolve();
+        })
+      ) {
+        const activeConnection = connectingDevices.get(deviceId);
+        if (!activeConnection || activeConnection.peripheral !== peripheral) {
+          try {
+            peripheral.removeAllListeners('disconnect');
+            runBleCallbackOperation(callback => peripheral.disconnect(() => callback()), {
+              timeoutMs: BLE_DISCONNECT_CONFIRM_TIMEOUT_MS,
+              timeoutBehavior: 'resolve',
+            })
+              .catch(() => undefined)
+              .finally(completeNative);
+            return;
+          } catch {
+            // Best-effort cleanup for a stale native callback.
+          }
+        }
+      }
+      completeNative();
+    };
+    try {
+      peripheral.connect(onConnect);
+    } catch (error) {
+      completeNative();
+      settle(() => reject(error));
+    }
+  });
+}
 const pairedDevices = new Set<string>(); // Windows BLE device pairing status tracking
 const deviceCharacteristics = new Map<string, CharacteristicPair>();
 const notificationCallbacks = new Map<string, (data: string) => void>();
@@ -320,6 +442,7 @@ function updateBluetoothState(state: string): void {
 
 // Initialize Noble
 async function initializeNoble(): Promise<void> {
+  assertBleActive();
   if (noble) return;
 
   try {
@@ -345,12 +468,14 @@ async function initializeNoble(): Promise<void> {
       }
 
       const timeout = setTimeout(() => {
+        cleanup();
         reject(
           ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Bluetooth initialization timeout')
         );
       }, BLUETOOTH_INIT_TIMEOUT);
 
       const cleanup = () => {
+        pendingCancellations.delete(cancel);
         clearTimeout(timeout);
         if (noble) {
           noble.removeListener('stateChange', onStateChange);
@@ -375,9 +500,17 @@ async function initializeNoble(): Promise<void> {
         }
       };
 
+      const cancel = () => {
+        cleanup();
+        reject(
+          ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down')
+        );
+      };
+      pendingCancellations.add(cancel);
       noble.on('stateChange', onStateChange);
     });
 
+    assertBleActive();
     // Set up device discovery
     if (!persistentDiscoverListener) {
       persistentDiscoverListener = (peripheral: Peripheral) => {
@@ -462,6 +595,7 @@ function armIdleDisconnect(
   reason: 'idle' | 'busy-backstop' = 'idle'
 ): void {
   clearIdleDisconnect(deviceId);
+  if (disposing) return;
   idleDisconnectTimers.set(
     deviceId,
     setTimeout(() => {
@@ -544,6 +678,14 @@ function cleanupDevice(
 
   // 1. Clean up connection state
   if (cleanupConnection) {
+    connectingDevices
+      .get(deviceId)
+      ?.cancel(
+        ERRORS.TypedError(
+          HardwareErrorCode.BleDeviceDisconnected,
+          `Device ${deviceId} disconnected while connecting`
+        )
+      );
     const disconnectEntry = deviceDisconnectListeners.get(deviceId);
     if (disconnectEntry) {
       disconnectEntry.peripheral.removeListener('disconnect', disconnectEntry.listener);
@@ -653,6 +795,7 @@ async function writeCharacteristicWithoutResponse(
   writeCharacteristic: Characteristic,
   buffer: Buffer
 ): Promise<void> {
+  assertBleActive();
   return new Promise((resolve, reject) => {
     writeCharacteristic.write(buffer, true, (error?: Error) => {
       if (error) {
@@ -937,6 +1080,7 @@ async function performTargetedScan(
   targetDeviceId: string,
   timeoutMs: number = NOBLE_BLE_TARGETED_SCAN_TIMEOUT_MS
 ): Promise<Peripheral | null> {
+  assertBleActive();
   if (!noble) {
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Noble not available');
   }
@@ -952,6 +1096,7 @@ async function performTargetedScan(
     const finish = async (peripheral: Peripheral | null, error?: Error) => {
       if (settled) return;
       settled = true;
+      pendingCancellations.delete(cancel);
       if (timeoutId) clearTimeout(timeoutId);
       nobleInstance.removeListener('discover', onDiscover);
       await waitForNobleScanStop(nobleInstance);
@@ -961,6 +1106,7 @@ async function performTargetedScan(
         reject(ERRORS.TypedError(HardwareErrorCode.BleScanError, error.message));
         return;
       }
+      assertBleActive();
       if (peripheral) {
         discoveredDevices.set(peripheral.id, peripheral);
       }
@@ -983,6 +1129,11 @@ async function performTargetedScan(
       finish(null).catch(reject);
     }, timeoutMs);
 
+    const cancel = () => {
+      finish(null, new Error('Noble BLE is shutting down')).catch(reject);
+    };
+    pendingCancellations.add(cancel);
+
     // Add local listener for this scan
     nobleInstance.on('discover', onDiscover);
 
@@ -1008,6 +1159,7 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Noble not available');
   }
 
+  assertBleActive();
   // Capture noble reference for use in closures (TypeScript narrowing)
   const nobleInstance = noble;
 
@@ -1022,12 +1174,15 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
 
   return new Promise((resolve, reject) => {
     const devices: DeviceInfo[] = [];
+    let settled = false;
     let intervalId: ReturnType<typeof setInterval> | undefined;
 
     // Cleanup function: clears timers and waits until Noble confirms scanning
     // has stopped. Resolving enumerate before this callback creates a race with
     // an immediately-following connection attempt.
     const cleanup = async () => {
+      settled = true;
+      pendingCancellations.delete(cancel);
       clearTimeout(timeoutId);
       if (intervalId) clearInterval(intervalId);
       await waitForNobleScanStop(nobleInstance);
@@ -1051,6 +1206,7 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
 
     // Set timeout for scanning — use longer timeout to catch slow-advertising devices like Pro2
     const timeoutId = setTimeout(async () => {
+      if (settled) return;
       // Final collection before resolving — catches devices discovered near the deadline
       checkDevices();
       await cleanup();
@@ -1058,11 +1214,17 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
       resolve(devices);
     }, DEVICE_SCAN_TIMEOUT);
 
+    const cancel = () => {
+      cleanup().then(() => resolve([]), reject);
+    };
+    pendingCancellations.add(cancel);
+
     // Start scanning without a service UUID filter so Pro2 advertisements with
     // short vendor UUIDs can be found. Repeated advertisements are required when
     // the local name arrives in a later scan response; discoveredDevices handles deduplication.
     logger?.info('[NobleBLE] Scanning for OneKey BLE devices');
     nobleInstance.startScanning([], true, async (error?: Error) => {
+      if (settled) return;
       if (error) {
         await cleanup();
         logger?.error('[NobleBLE] Failed to start scanning:', error);
@@ -1080,7 +1242,7 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
 
 // Stop scanning
 async function stopScanning(): Promise<void> {
-  if (!noble) return;
+  if (!noble || nativeReleased) return;
   const nobleInstance = noble;
   await waitForNobleScanStop(nobleInstance);
   logger?.info('[NobleBLE] Scanning stopped');
@@ -1153,13 +1315,17 @@ function getDevice(deviceId: string): DeviceInfo | null {
 async function discoverServicesAndCharacteristics(
   peripheral: Peripheral
 ): Promise<CharacteristicPair> {
+  assertBleActive();
   // Cleanup resources - will be set up and cleaned in try/finally
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
   let onDisconnect: (() => void) | undefined;
 
   const cleanup = () => {
     if (timeoutId) clearTimeout(timeoutId);
-    if (onDisconnect) peripheral.removeListener('disconnect', onDisconnect);
+    if (onDisconnect) {
+      peripheral.removeListener('disconnect', onDisconnect);
+      pendingCancellations.delete(onDisconnect);
+    }
   };
 
   // Racing promises for timeout and disconnect
@@ -1180,6 +1346,7 @@ async function discoverServicesAndCharacteristics(
         )
       );
     };
+    pendingCancellations.add(onDisconnect);
     peripheral.once('disconnect', onDisconnect);
   });
 
@@ -1205,6 +1372,7 @@ async function discoverServicesAndCharacteristics(
       });
     });
 
+    assertBleActive();
     if (!services || services.length === 0) {
       throw ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, 'No OneKey services found');
     }
@@ -1311,17 +1479,8 @@ async function forceReconnectPeripheral(peripheral: Peripheral, deviceId: string
   }
 
   // Step 3: Re-establish connection
-  await new Promise<void>((resolve, reject) => {
-    peripheral.connect(error => {
-      if (error) {
-        reject(createNobleBleConnectionError(error));
-        return;
-      }
-      resolve();
-    });
-  });
+  await connectPeripheralWithCancellation(peripheral, deviceId);
   logger?.info('[NobleBLE] Force reconnect successful');
-  connectedDevices.set(deviceId, peripheral);
 
   // Wait for connection to stabilize
   await wait(500);
@@ -1357,16 +1516,11 @@ async function freshScanAndDiscover(
   discoveredDevices.set(deviceId, freshPeripheral);
 
   // Connect to fresh peripheral
-  await new Promise<void>((resolve, reject) => {
-    freshPeripheral.connect((error: Error | undefined) => {
-      if (error) {
-        reject(createNobleBleConnectionError(error, 'Fresh peripheral connection failed: '));
-      } else {
-        connectedDevices.set(deviceId, freshPeripheral);
-        resolve();
-      }
-    });
-  });
+  await connectPeripheralWithCancellation(
+    freshPeripheral,
+    deviceId,
+    'Fresh peripheral connection failed: '
+  );
 
   // Setup disconnect listener for fresh peripheral
   setupDisconnectListener(freshPeripheral, deviceId, webContents);
@@ -1438,6 +1592,7 @@ async function discoverServicesAndCharacteristicsWithRetry(
       minTimeout: 500,
       maxTimeout: 3000,
       onFailedAttempt: error => {
+        assertBleActive();
         // This runs after each failed attempt
         logger?.error(`[NobleBLE] Service discovery attempt ${error.attemptNumber} failed:`, {
           message: error.message,
@@ -1473,13 +1628,17 @@ async function setupConnectionAndDiscoverServices(
   try {
     await forceReconnectPeripheral(peripheral, deviceId);
   } catch (resetError) {
-    if (isBleStaleBondHardwareError(resetError)) {
+    if (
+      isBleStaleBondHardwareError(resetError) ||
+      (resetError as { errorCode?: unknown })?.errorCode === HardwareErrorCode.BleDeviceDisconnected
+    ) {
       throw resetError;
     }
     // A failed reset must not abort the attempt: discovery on the existing
     // link, then the fresh-scan fallback, still have a chance to recover.
     logger?.error('[NobleBLE] Connection reset before discovery failed, continuing', resetError);
   }
+  assertBleActive();
   setupDisconnectListener(peripheral, deviceId, webContents);
 
   try {
@@ -1522,6 +1681,7 @@ const directConnectCooldownUntil = new Map<string, number>();
  * Ported from the Trezor connector, where it is field-proven.
  */
 async function tryDirectConnectById(deviceId: string): Promise<Peripheral | undefined> {
+  assertBleActive();
   const nobleInstance = noble as
     | (typeof noble & {
         connectAsync?: (id: string) => Promise<Peripheral | undefined>;
@@ -1532,34 +1692,42 @@ async function tryDirectConnectById(deviceId: string): Promise<Peripheral | unde
   const cooldownUntil = directConnectCooldownUntil.get(deviceId) ?? 0;
   if (Date.now() < cooldownUntil) return undefined;
 
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cancel: (() => void) | undefined;
+  let abandoned = false;
   try {
     // The late-orphan guard must attach to THIS pending connect.
     const directPromise = nobleInstance.connectAsync(deviceId);
+    trackNativeConnection(
+      directPromise.then(async late => {
+        if ((!abandoned && !disposing) || nativeReleased) return;
+        const peripheral = late ?? discoveredDevices.get(deviceId);
+        if (peripheral?.state === 'connected' && !connectedDevices.has(deviceId)) {
+          peripheral.removeAllListeners('disconnect');
+          await runBleCallbackOperation(callback => peripheral.disconnect(() => callback()), {
+            timeoutMs: BLE_DISCONNECT_CONFIRM_TIMEOUT_MS,
+            timeoutBehavior: 'resolve',
+          });
+        }
+      }),
+      () => nobleInstance.cancelConnect?.(deviceId)
+    );
     const raced = await Promise.race([
       directPromise,
       new Promise<'timeout'>(resolve => {
-        setTimeout(() => resolve('timeout'), DIRECT_CONNECT_TIMEOUT_MS);
+        cancel = () => {
+          abandoned = true;
+          resolve('timeout');
+        };
+        pendingCancellations.add(cancel);
+        timer = setTimeout(cancel, DIRECT_CONNECT_TIMEOUT_MS);
       }),
     ]);
-    if (raced === 'timeout') {
+    if (raced === 'timeout' || disposing) {
       directConnectCooldownUntil.set(deviceId, Date.now() + DIRECT_CONNECT_COOLDOWN_MS);
       logger?.info('[NobleBLE] Direct connect-by-id timed out, falling back to scan', {
         deviceId,
       });
-      // Promise.race times out the caller only; a late success orphans the link.
-      directPromise
-        .then(late => {
-          const latePeripheral = late ?? discoveredDevices.get(deviceId);
-          if (
-            latePeripheral &&
-            latePeripheral.state === 'connected' &&
-            !connectedDevices.has(deviceId)
-          ) {
-            latePeripheral.removeAllListeners('disconnect');
-            latePeripheral.disconnect(() => undefined);
-          }
-        })
-        .catch(() => undefined);
       return undefined;
     }
     // Backends emit `discover` as a side effect, so the cache may hold it.
@@ -1574,6 +1742,9 @@ async function tryDirectConnectById(deviceId: string): Promise<Peripheral | unde
       error: String(error),
     });
     return undefined;
+  } finally {
+    clearTimeout(timer);
+    if (cancel) pendingCancellations.delete(cancel);
   }
 }
 
@@ -1644,6 +1815,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     }
   }
 
+  assertBleActive();
   // At this point, peripheral is guaranteed to be defined
   if (!peripheral) {
     throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `Device ${deviceId} not found`);
@@ -1666,6 +1838,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     // Re-bind unconditionally (idempotent): on a kept-alive link the disconnect
     // and MTU listeners may still hold the webContents of a soft-restarted
     // renderer, and the reuse fast path below returns before any other setup.
+    assertBleActive();
     setupDisconnectListener(peripheral, deviceId, webContents);
 
     // Check if we already have characteristics for this device
@@ -1716,6 +1889,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
         deviceId,
         webContents
       );
+      assertBleActive();
       deviceCharacteristics.set(deviceId, characteristics);
       logger?.info('[NobleBLE] Device ready for communication:', deviceId);
     } catch (setupError) {
@@ -1727,51 +1901,43 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     return;
   }
 
-  return new Promise((resolve, reject) => {
-    // TypeScript type assertion - peripheral is guaranteed to be defined at this point
-    const connectedPeripheral = peripheral as Peripheral;
-    connectedPeripheral.connect(async (error: Error | undefined) => {
-      if (error) {
-        logger?.error('[NobleBLE] Connection failed:', error);
-        reject(createNobleBleConnectionError(error));
-        return;
-      }
-
-      logger?.info('[NobleBLE] Connected to device:', deviceId);
-      connectedDevices.set(deviceId, connectedPeripheral);
+  const connectedPeripheral = peripheral;
+  await connectPeripheralWithCancellation(connectedPeripheral, deviceId);
+  logger?.info('[NobleBLE] Connected to device:', deviceId);
 
-      // Setup connection and discover services
-      try {
-        const characteristics = await setupConnectionAndDiscoverServices(
-          connectedPeripheral,
-          deviceId,
-          webContents
-        );
-        deviceCharacteristics.set(deviceId, characteristics);
-        logger?.info('[NobleBLE] Device ready for communication:', deviceId);
-        resolve();
-      } catch (setupError) {
-        logger?.error('[NobleBLE] Connection setup failed:', setupError);
-        // Never reject from inside a raw disconnect callback: noble only fires
-        // it on a real 'disconnect' event, so a peripheral that is already
-        // down leaves this promise — and the renderer acquire awaiting it —
-        // pending forever. disconnectDevice always settles (it no-ops on an
-        // unknown peripheral and caps the confirm wait).
-        disconnectDevice(deviceId)
-          .catch(() => undefined)
-          .then(() => reject(setupError));
-      }
-    });
-  });
+  // Setup connection and discover services
+  try {
+    const characteristics = await setupConnectionAndDiscoverServices(
+      connectedPeripheral,
+      deviceId,
+      webContents
+    );
+    assertBleActive();
+    deviceCharacteristics.set(deviceId, characteristics);
+    logger?.info('[NobleBLE] Device ready for communication:', deviceId);
+  } catch (setupError) {
+    logger?.error('[NobleBLE] Connection setup failed:', setupError);
+    await disconnectDevice(deviceId).catch(() => undefined);
+    throw setupError;
+  }
 }
 
 // Disconnect device
 async function disconnectDevice(deviceId: string): Promise<void> {
-  const peripheral = connectedDevices.get(deviceId);
+  if (nativeReleased) return;
+  const pendingConnection = connectingDevices.get(deviceId);
+  const peripheral = connectedDevices.get(deviceId) ?? pendingConnection?.peripheral;
   if (!peripheral) {
     return;
   }
 
+  pendingConnection?.cancel(
+    ERRORS.TypedError(
+      HardwareErrorCode.BleDeviceDisconnected,
+      `Device ${deviceId} connection cancelled`
+    )
+  );
+
   const disconnectEntry = deviceDisconnectListeners.get(deviceId);
   if (disconnectEntry) {
     disconnectEntry.peripheral.removeListener('disconnect', disconnectEntry.listener);
@@ -1799,6 +1965,7 @@ async function disconnectDevice(deviceId: string): Promise<void> {
 
 // Unsubscribe from notifications
 async function unsubscribeNotifications(deviceId: string): Promise<void> {
+  if (nativeReleased) return;
   const peripheral = connectedDevices.get(deviceId);
   const characteristics = deviceCharacteristics.get(deviceId);
 
@@ -1826,7 +1993,7 @@ async function unsubscribeNotifications(deviceId: string): Promise<void> {
     subscribedDevices.delete(deviceId);
   } finally {
     // 🔒 CRITICAL: Always clear operation state (even on error)
-    subscriptionOperations.set(deviceId, 'idle');
+    if (!disposing) subscriptionOperations.set(deviceId, 'idle');
   }
 }
 
@@ -1915,11 +2082,13 @@ async function subscribeNotifications(
       timeoutMs: BLE_CLEANUP_TIMEOUT,
       timeoutBehavior: 'resolve',
     });
+    assertBleActive();
     await runBleCallbackOperation(callback => notifyCharacteristic.subscribe(callback), {
       timeoutMs: NOBLE_BLE_SUBSCRIBE_TIMEOUT_MS,
       timeoutBehavior: 'reject',
     });
 
+    assertBleActive();
     notifyCharacteristic.on('data', (data: Buffer) => {
       // Windows BLE pairing detection: receiving any data means device is paired
       if (!pairedDevices.has(deviceId)) {
@@ -1934,19 +2103,27 @@ async function subscribeNotifications(
   const subscribeStartedAt = Date.now();
   try {
     await rebuildAppSubscription(deviceId, notifyCharacteristic);
+    assertBleActive();
     subscribedDevices.set(deviceId, true);
     logger?.info('[NobleBLE] Notification subscription active', {
       deviceId,
       ms: Date.now() - subscribeStartedAt,
     });
+  } catch (error) {
+    throw createNobleBleConnectionError(
+      error as NobleBleNativeError,
+      'Notification subscription failed: '
+    );
   } finally {
     // 🔒 CRITICAL: Always clear operation state (even on error)
-    subscriptionOperations.set(deviceId, 'idle');
+    if (!disposing) subscriptionOperations.set(deviceId, 'idle');
   }
 }
 
 // Setup IPC handlers
 export function setupNobleBleHandlers(webContents: WebContents): void {
+  if (disposing) return;
+  let windowDestroyed = false;
   try {
     // @ts-ignore – electron-log is only available at runtime
     // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
@@ -1956,11 +2133,24 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
     // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
     const { ipcMain } = require('electron') as { ipcMain: IpcMain };
 
+    const channels = new Set<string>();
+    removeIpcHandlers = () => channels.forEach(channel => ipcMain.removeHandler(channel));
+
     // Electron throws on duplicate channels and setup re-runs on soft restart.
     const handle: IpcMain['handle'] = (channel, listener) => {
+      channels.add(channel);
       ipcMain.removeHandler(channel);
       ipcMain.handle(channel, async (...args) => {
         try {
+          // A replacement renderer must not race the old renderer's shared-state cleanup.
+          if (windowCleanup) await windowCleanup;
+          assertBleActive();
+          if (windowDestroyed) {
+            throw ERRORS.TypedError(
+              HardwareErrorCode.BleDeviceDisconnected,
+              'BLE window destroyed'
+            );
+          }
           return await Promise.resolve(listener(...args));
         } catch (error) {
           return createNobleBleIpcErrorResponse(error);
@@ -2116,16 +2306,24 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
       }
     });
 
-    // Cleanup on app quit
+    // Window cleanup also runs during renderer soft restart; native release belongs to app quit.
     webContents.on('destroyed', () => {
+      windowDestroyed = true;
+      if (disposing) return;
       safeLog(logger, 'info', 'Cleaning up Noble BLE handlers');
-      (async () => {
+      const previousCleanup = windowCleanup;
+      windowCleanup = (async () => {
+        if (previousCleanup) await previousCleanup;
+        if (disposing) return;
         const deviceIds = Array.from(connectedDevices.keys());
         for (const deviceId of deviceIds) {
+          if (disposing) return;
           await unsubscribeNotifications(deviceId).catch(() => undefined);
+          if (disposing) return;
           await disconnectDevice(deviceId).catch(() => undefined);
         }
 
+        if (disposing) return;
         await stopScanning().catch(() => undefined);
         // persistentStateListener is process-lifetime, NOT per-window: this
         // destroy handler also fires on a renderer soft restart, and removing
@@ -2147,3 +2345,77 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
     throw error;
   }
 }
+
+/**
+ * Terminal, bounded cleanup while the Node environment is still alive.
+ * If Noble is shared with another transport, releaseNoble must queue the instance
+ * and call stop() once after every transport has finished its cleanup.
+ */
+export function disposeNobleBleSupport(
+  releaseNoble: (instance: { stop(): void }) => void = instance => instance.stop()
+): Promise<void> {
+  if (disposePromise) return disposePromise;
+  disposing = true;
+  removeIpcHandlers?.();
+  const instance = noble;
+  const deviceIds = new Set([...connectedDevices.keys(), ...connectingDevices.keys()]);
+  const pendingPeripherals = Array.from(connectingDevices.values(), pending => pending.peripheral);
+  for (const cancel of pendingCancellations) cancel();
+  for (const id of idleDisconnectTimers.keys()) clearIdleDisconnect(id);
+  for (const pending of connectingDevices.values()) {
+    pending.cancel(
+      ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down')
+    );
+  }
+  const connections = Array.from(nativeConnections);
+  for (const connection of connections) {
+    try {
+      connection.cancel();
+    } catch (error) {
+      logger?.warn('[NobleBLE] Native connect cancellation failed', error);
+    }
+  }
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  disposePromise = (async () => {
+    try {
+      await Promise.race([
+        Promise.allSettled([
+          windowCleanup,
+          ...connections.map(connection => connection.settled),
+          stopScanning(),
+          ...pendingPeripherals.map(peripheral =>
+            runBleCallbackOperation(callback => peripheral.disconnect(() => callback()), {
+              timeoutMs: BLE_DISCONNECT_CONFIRM_TIMEOUT_MS,
+              timeoutBehavior: 'resolve',
+            })
+          ),
+          ...Array.from(deviceIds, async id => {
+            await unsubscribeNotifications(id).catch(() => undefined);
+            await disconnectDevice(id).catch(() => undefined);
+          }),
+        ]),
+        new Promise<void>(resolve => {
+          timeout = setTimeout(() => {
+            logger?.warn('[NobleBLE] Process dispose timed out; releasing native manager');
+            resolve();
+          }, 3500);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timeout);
+      // Bounded cleanup may finish before a broken native callback; it must stay inert afterwards.
+      nativeReleased = true;
+      cleanupNobleListeners();
+      if (instance && persistentStateListener) {
+        instance.removeListener('stateChange', persistentStateListener);
+        persistentStateListener = null;
+      }
+      for (const id of deviceIds) cleanupDevice(id);
+      discoveredDevices.clear();
+      directConnectCooldownUntil.clear();
+      if (instance) releaseNoble(instance);
+      logger?.info('[NobleBLE] Process dispose completed');
+    }
+  })();
+  return disposePromise;
+}