fix: improve Ledger error handling for disconnect, retry, and pagination cp-7.77.0

.gitignore

@@ -185,6 +185,7 @@ github-tools/
 temp/
 /temp/
 .agent/
+.cursor/hooks/state/
 
 # Reassure performance testing
 .reassure/

AGENTS.md

@@ -224,3 +224,16 @@ bash .agents/skills/ab-testing-implementation/scripts/check-ab-testing-complianc
 ```
 
 If no files are staged, the checker automatically falls back to changed working-tree files.
+
+## Learned User Preferences
+
+- Use `jest.mocked(<function>)` instead of casting with `(fn as jest.Mock)` when configuring mocks in tests
+- In component tests, prefer `.toBeOnTheScreen()` over `.toBeTruthy()` on `queryBy*` results; assert mocks were called with expected arguments rather than just `toBeDefined()`
+- When implementing from an attached plan, follow it as specified without editing the plan file; mark todos in_progress in order and complete all before stopping
+- If a plan fails to generate, fix the issue and proceed with implementation rather than stopping
+- After completing feature or bug work, create a new git branch, commit, and push when asked
+- For PR code reviews, provide specific actionable comments on individual code lines rather than vague overviews
+
+## Learned Workspace Facts
+
+- On Android with targetSdk 35 and Android 15 edge-to-edge, use `SafeAreaView` from `react-native-safe-area-context` (not from `react-native`) or apply `marginTop` from insets to prevent headers overlapping the status bar

app/components/Views/LedgerSelectAccount/index.test.tsx

@@ -803,5 +803,71 @@ describe('LedgerSelectAccount', () => {
         expect(queryByText('Network error')).toBeOnTheScreen();
       });
     });
+
+    it('calls ensureDeviceReady before nextPage pagination', async () => {
+      const { getByTestId } = await renderAndWaitForAccounts();
+
+      mockEnsureDeviceReady.mockClear();
+      mockGetLedgerAccountsByOperation.mockClear();
+      mockGetLedgerAccountsByOperation.mockResolvedValue(mockAccounts);
+
+      await act(async () => {
+        fireEvent.press(getByTestId(ACCOUNT_SELECTOR_NEXT_BUTTON));
+      });
+
+      await waitFor(() => {
+        expect(mockEnsureDeviceReady).toHaveBeenCalledWith('test-device-id');
+      });
+    });
+
+    it('calls ensureDeviceReady before prevPage pagination', async () => {
+      const { getByTestId } = await renderAndWaitForAccounts();
+
+      mockEnsureDeviceReady.mockClear();
+      mockGetLedgerAccountsByOperation.mockClear();
+      mockGetLedgerAccountsByOperation.mockResolvedValue(mockAccounts);
+
+      await act(async () => {
+        fireEvent.press(getByTestId(ACCOUNT_SELECTOR_PREVIOUS_BUTTON));
+      });
+
+      await waitFor(() => {
+        expect(mockEnsureDeviceReady).toHaveBeenCalledWith('test-device-id');
+      });
+    });
+
+    it('skips pagination when ensureDeviceReady returns false on nextPage', async () => {
+      const { getByTestId } = await renderAndWaitForAccounts();
+
+      mockEnsureDeviceReady.mockResolvedValue(false);
+      mockGetLedgerAccountsByOperation.mockClear();
+
+      await act(async () => {
+        fireEvent.press(getByTestId(ACCOUNT_SELECTOR_NEXT_BUTTON));
+      });
+
+      await waitFor(() => {
+        expect(mockEnsureDeviceReady).toHaveBeenCalled();
+      });
+
+      expect(mockGetLedgerAccountsByOperation).not.toHaveBeenCalled();
+    });
+
+    it('skips pagination when ensureDeviceReady returns false on prevPage', async () => {
+      const { getByTestId } = await renderAndWaitForAccounts();
+
+      mockEnsureDeviceReady.mockResolvedValue(false);
+      mockGetLedgerAccountsByOperation.mockClear();
+
+      await act(async () => {
+        fireEvent.press(getByTestId(ACCOUNT_SELECTOR_PREVIOUS_BUTTON));
+      });
+
+      await waitFor(() => {
+        expect(mockEnsureDeviceReady).toHaveBeenCalled();
+      });
+
+      expect(mockGetLedgerAccountsByOperation).not.toHaveBeenCalled();
+    });
   });
 });

app/components/Views/LedgerSelectAccount/index.tsx

@@ -222,32 +222,46 @@ const LedgerSelectAccount = () => {
   }, [selectedOption]);
 
   const nextPage = useCallback(async () => {
-    showLoadingModal();
+    let modalShown = false;
     try {
+      const isReady = await ensureDeviceReady(deviceId);
+      if (!isReady) return;
+
+      showLoadingModal();
+      modalShown = true;
       const _accounts = await getLedgerAccountsByOperation(
         PAGINATION_OPERATIONS.GET_NEXT_PAGE,
       );
       setAccounts(_accounts);
     } catch (e) {
       setErrorMsg((e as Error).message);
     } finally {
-      setBlockingModalVisible(false);
+      if (modalShown) {
+        setBlockingModalVisible(false);
+      }
     }
-  }, []);
+  }, [ensureDeviceReady, deviceId]);
 
   const prevPage = useCallback(async () => {
-    showLoadingModal();
+    let modalShown = false;
     try {
+      const isReady = await ensureDeviceReady(deviceId);
+      if (!isReady) return;
+
+      showLoadingModal();
+      modalShown = true;
       const _accounts = await getLedgerAccountsByOperation(
         PAGINATION_OPERATIONS.GET_PREVIOUS_PAGE,
       );
       setAccounts(_accounts);
     } catch (e) {
       setErrorMsg((e as Error).message);
     } finally {
-      setBlockingModalVisible(false);
+      if (modalShown) {
+        setBlockingModalVisible(false);
+      }
     }
-  }, []);
+  }, [ensureDeviceReady, deviceId]);
 
   const updateNewLegacyAccountsLabel = useCallback(async () => {
     if (LEDGER_LEGACY_PATH === (await getHDPath())) {

app/core/HardwareWallet/adapters/LedgerBluetoothAdapter.test.ts

@@ -617,6 +617,82 @@ describe('LedgerBluetoothAdapter', () => {
 
       jest.useRealTimers();
     });
+
+    it('retries when error message contains "disconnected" even with generic Error name', async () => {
+      const genericBleError = new Error('Device disconnected during operation');
+      genericBleError.name = 'Error';
+      jest
+        .mocked(connectLedgerHardware)
+        .mockRejectedValueOnce(genericBleError)
+        .mockResolvedValueOnce('Ethereum');
+      mockGetAddress.mockResolvedValue({ address: '0x1234' });
+
+      const result = await adapter.ensureDeviceReady('device-123');
+
+      expect(result).toBe(true);
+      expect(connectLedgerHardware).toHaveBeenCalledTimes(2);
+    });
+
+    it('retries when error message contains "bluetooth" even with generic Error name', async () => {
+      const genericBleError = new Error('Bluetooth connection failed');
+      genericBleError.name = 'Error';
+      jest
+        .mocked(connectLedgerHardware)
+        .mockRejectedValueOnce(genericBleError)
+        .mockResolvedValueOnce('Ethereum');
+      mockGetAddress.mockResolvedValue({ address: '0x1234' });
+
+      const result = await adapter.ensureDeviceReady('device-123');
+
+      expect(result).toBe(true);
+      expect(connectLedgerHardware).toHaveBeenCalledTimes(2);
+    });
+
+    it('forces BLE cleanup when transport is null but deviceId exists during retry', async () => {
+      const disconnectError = new Error('Disconnected');
+      disconnectError.name = 'DisconnectedDevice';
+      jest
+        .mocked(connectLedgerHardware)
+        .mockRejectedValueOnce(disconnectError)
+        .mockResolvedValueOnce('Ethereum');
+      mockGetAddress.mockResolvedValue({ address: '0x1234' });
+
+      await adapter.ensureDeviceReady('device-123');
+
+      expect(mockedTransportBLE.disconnectDevice).toHaveBeenCalled();
+    });
+
+    it('closes transport when openEthereumAppOnLedger fails', async () => {
+      jest.mocked(connectLedgerHardware).mockResolvedValue('BOLOS');
+      const { openEthereumAppOnLedger } = jest.requireMock(
+        '../../Ledger/Ledger',
+      ) as { openEthereumAppOnLedger: jest.Mock };
+      openEthereumAppOnLedger.mockRejectedValueOnce(
+        new Error('User cancelled'),
+      );
+
+      await adapter.ensureDeviceReady('device-123');
+
+      expect(mockedTransportBLE.disconnectDevice).toHaveBeenCalledWith(
+        'device-123',
+      );
+    });
+
+    it('closes transport when closeRunningAppOnLedger fails', async () => {
+      jest.mocked(connectLedgerHardware).mockResolvedValue('Bitcoin');
+      const { closeRunningAppOnLedger } = jest.requireMock(
+        '../../Ledger/Ledger',
+      ) as { closeRunningAppOnLedger: jest.Mock };
+      closeRunningAppOnLedger.mockRejectedValueOnce(
+        new Error('User cancelled'),
+      );
+
+      await adapter.ensureDeviceReady('device-123');
+
+      expect(mockedTransportBLE.disconnectDevice).toHaveBeenCalledWith(
+        'device-123',
+      );
+    });
   });
 
   describe('reset', () => {

app/core/HardwareWallet/adapters/LedgerBluetoothAdapter.ts

@@ -515,6 +515,7 @@ export class LedgerBluetoothAdapter implements HardwareWalletAdapter {
           '[LedgerBluetoothAdapter] Failed to send open app command:',
           openError,
         );
+        await this.#closeTransport();
       }
     } else {
       try {
@@ -526,6 +527,7 @@ export class LedgerBluetoothAdapter implements HardwareWalletAdapter {
           '[LedgerBluetoothAdapter] Failed to close app:',
           closeError,
         );
+        await this.#closeTransport();
       }
     }
   }
@@ -564,9 +566,10 @@ export class LedgerBluetoothAdapter implements HardwareWalletAdapter {
   async #closeTransport(): Promise<void> {
     const transport = this.#transport;
     const deviceId = this.#deviceId;
-    if (transport) {
-      this.#transport = null;
-      try {
+    this.#transport = null;
+
+    try {
+      if (transport) {
         if (deviceId) {
           // TransportBLE.close() queues a delayed disconnect (5s timeout).
           // Force an immediate BLE disconnection so in-flight signing is
@@ -575,9 +578,14 @@ export class LedgerBluetoothAdapter implements HardwareWalletAdapter {
         } else {
           await transport.close();
         }
-      } catch {
-        // Ignore close errors — device may already be disconnected
+      } else if (deviceId) {
+        // Transport already cleared (e.g. by #handleDisconnect) but device
+        // ID still set — force BLE cleanup so the OS stack doesn't keep a
+        // stale connection that blocks the next TransportBLE.open() call.
+        await TransportBLE.disconnectDevice(deviceId);
       }
+    } catch {
+      // Ignore close errors — device may already be disconnected
     }
   }
 
@@ -666,16 +674,28 @@ export class LedgerBluetoothAdapter implements HardwareWalletAdapter {
   /**
    * Check if error is a transient BLE error that can be retried
    * (disconnects during app switch, pairing failures during reconnect, etc.)
+   *
+   * Checks error name first, then falls back to message-based detection
+   * for BLE errors that use generic Error names after a device power-cycle.
    */
   #isTransientBleError(error: unknown): boolean {
     if (!(error instanceof Error)) return false;
+
     const transientBleErrorNames: readonly string[] = [
       ...DISCONNECT_ERROR_NAMES,
       'PairingFailed',
       'PeerRemovedPairing',
       'BleError',
     ];
-    return transientBleErrorNames.includes(error.name);
+    if (transientBleErrorNames.includes(error.name)) return true;
+
+    const message = error.message?.toLowerCase() ?? '';
+    return (
+      message.includes('disconnected') ||
+      message.includes('connection lost') ||
+      message.includes('gatt') ||
+      message.includes('bluetooth')
+    );
   }
 
   /**

app/core/Ledger/Ledger.test.ts

@@ -527,6 +527,26 @@ describe('Ledger core', () => {
         getLedgerAccountsByOperation(PAGINATION_OPERATIONS.GET_FIRST_PAGE),
       ).rejects.toThrow('Unspecified error when connect Ledger Hardware,');
     });
+
+    it('throws disconnect error for DisconnectedDevice', async () => {
+      const disconnectError = new Error('Disconnected during operation');
+      disconnectError.name = 'DisconnectedDevice';
+      ledgerKeyring.getFirstPage.mockRejectedValueOnce(disconnectError);
+
+      await expect(
+        getLedgerAccountsByOperation(PAGINATION_OPERATIONS.GET_FIRST_PAGE),
+      ).rejects.toThrow('Your device got disconnected');
+    });
+
+    it('throws disconnect error for DisconnectedDeviceDuringOperation', async () => {
+      const disconnectError = new Error('Lost connection');
+      disconnectError.name = 'DisconnectedDeviceDuringOperation';
+      ledgerKeyring.getNextPage.mockRejectedValueOnce(disconnectError);
+
+      await expect(
+        getLedgerAccountsByOperation(PAGINATION_OPERATIONS.GET_NEXT_PAGE),
+      ).rejects.toThrow('Your device got disconnected');
+    });
   });
 
   describe('ledgerSignTypedMessage', () => {

app/core/Ledger/Ledger.ts

@@ -18,7 +18,7 @@ import PAGINATION_OPERATIONS from '../../constants/pagination';
 import { strings } from '../../../locales/i18n';
 import { keyringTypeToName } from '@metamask/accounts-controller';
 import { removeAccountsFromPermissions } from '../Permissions';
-import { isEthAppNotOpenError } from './ledgerErrors';
+import { isEthAppNotOpenError, isDisconnectError } from './ledgerErrors';
 
 /**
  * Perform an operation with the Ledger keyring.
@@ -192,6 +192,9 @@ export const getLedgerAccountsByOperation = async (
     if (isEthAppNotOpenError(e)) {
       throw new Error(strings('ledger.eth_app_not_open_message'));
     }
+    if (isDisconnectError(e)) {
+      throw new Error(strings('ledger.ledger_disconnected'));
+    }
     throw new Error(strings('ledger.unspecified_error_during_connect'));
   }
 };