@onekeyfe/hd-core 1.2.0-alpha.67 → 1.2.0-alpha.69

package/__tests__/check-all-firmware-release-protocol-v2.test.ts

@@ -5,6 +5,7 @@ import CheckAllFirmwareRelease, {
 } from '../src/api/CheckAllFirmwareRelease';
 import { DataManager } from '../src/data-manager';
 import { createCoreApi } from '../src/inject';
+import { PROTOCOL_V2_RESOURCE_DEVICE_PATHS } from '../src/protocols/protocol-v2/resources';
 
 import type { CoreApi } from '../src/types/api';
 import type { DeviceStateVersions, IFirmwareReleaseInfo } from '../src/types';
@@ -72,7 +73,74 @@ const release: IFirmwareReleaseInfo = {
   ],
 };
 
+const stableResources = ['images', 'animation', 'wallpaper', 'translations', 'roobert', 'noto'].map(
+  (type, index) => ({
+    type,
+    url: `https://example.com/${type}.okpkg`,
+    size: 0x52a0 + index + 1,
+    fileHash: 'a'.repeat(64),
+    headerHash: index.toString(16).padStart(128, '0'),
+  })
+);
+
+const createFilesystemTypedCall = (missingAll = false) => {
+  const resourceByPath = new Map(
+    stableResources.map(resource => [
+      PROTOCOL_V2_RESOURCE_DEVICE_PATHS[
+        resource.type as keyof typeof PROTOCOL_V2_RESOURCE_DEVICE_PATHS
+      ],
+      resource,
+    ])
+  );
+  return jest.fn((requestType: string, _responseType: string, payload: Record<string, any>) => {
+    if (requestType === 'ResourceInventoryGet') {
+      throw new Error('ResourceInventoryGet is unavailable on released firmware');
+    }
+    if (requestType === 'FilesystemPathInfoQuery') {
+      const resource = resourceByPath.get(payload.path);
+      return {
+        message: {
+          exist: Boolean(resource) && !missingAll,
+          directory: false,
+          size: missingAll ? 0 : resource?.size,
+        },
+      };
+    }
+    if (requestType === 'FilesystemFileRead') {
+      const resource = resourceByPath.get(payload.file.path);
+      if (!resource || missingAll) throw new Error('missing resource');
+      const header = new Uint8Array(0x52a0);
+      const view = new DataView(header.buffer);
+      'OKPP'.split('').forEach((char, index) => {
+        header[index] = char.charCodeAt(0);
+      });
+      'RESC'.split('').forEach((char, index) => {
+        header[0x08 + index] = char.charCodeAt(0);
+      });
+      view.setUint32(0x0c, header.byteLength, true);
+      for (let index = 0; index < resource.headerHash.length / 2; index++) {
+        header[0x240 + index] = Number.parseInt(
+          resource.headerHash.slice(index * 2, index * 2 + 2),
+          16
+        );
+      }
+      const offset = Number(payload.file.offset);
+      const chunkLength = Number(payload.chunk_len);
+      return {
+        message: {
+          data: header.slice(offset, offset + chunkLength),
+        },
+      };
+    }
+    throw new Error(`Unexpected request: ${requestType}`);
+  });
+};
+
 describe('checkAllFirmwareRelease Protocol V2 support', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
   test('builds ordered firmwareUpdateV4 targets from recommended component versions', () => {
     const result = buildProtocolV2FirmwareRelease({
       currentVersions,
@@ -84,7 +152,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
       status: 'required',
       hasUpgrade: true,
       required: true,
-      targetsToUpdate: ['boot', 'app_v1', 'resource'],
+      targetsToUpdate: ['boot', 'app_v1'],
       components: [
         { configKey: 'bootloader', status: 'outdated', updateTarget: 'boot' },
         { configKey: 'applicationP1', status: 'outdated', updateTarget: 'app_v1' },
@@ -95,6 +163,34 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
     });
   });
 
+  test('marks SE03 and SE04 as unsupported in a Neo firmware plan', () => {
+    const neoRelease: IFirmwareReleaseInfo = {
+      ...release,
+      installOrder: ['se01', 'se02', 'se03', 'se04'],
+      components: {
+        se01: { target: 'SE01', url: 'https://example.com/se01.bin', version: [2, 0, 0] },
+        se02: { target: 'SE02', url: 'https://example.com/se02.bin', version: [3, 0, 0] },
+        se03: { target: 'SE03', url: 'https://example.com/se03.bin', version: [2, 0, 0] },
+        se04: { target: 'SE04', url: 'https://example.com/se04.bin', version: [2, 0, 0] },
+      },
+    };
+
+    const result = buildProtocolV2FirmwareRelease({
+      currentVersions,
+      firmwareType: EFirmwareType.Universal,
+      release: neoRelease,
+      deviceType: 'neo',
+    });
+
+    expect(result.targetsToUpdate).toEqual(['se01', 'se02']);
+    expect(result.components).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ configKey: 'se03', status: 'unsupported', updateTarget: null }),
+        expect.objectContaining({ configKey: 'se04', status: 'unsupported', updateTarget: null }),
+      ])
+    );
+  });
+
   test('returns an unavailable plan when no Pro2 release is configured', () => {
     expect(
       buildProtocolV2FirmwareRelease({
@@ -142,6 +238,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
         applicationP1Hash: 'aa'.repeat(32),
         applicationP2Hash: 'bb'.repeat(32),
       },
+      checkFirmwareHash: true,
       remotePayloadHashes: {
         applicationP1: 'aa'.repeat(64),
         applicationP2: 'cc'.repeat(64),
@@ -160,6 +257,37 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
     });
   });
 
+  test('uses version-only comparison for same-version packages by default', () => {
+    const packageSet: IFirmwareReleaseInfo = {
+      ...release,
+      required: false,
+      resourceBundles: undefined,
+      installOrder: ['applicationP1'],
+      components: {
+        applicationP1: {
+          target: 'APPLICATION_P1',
+          version: [1, 0, 0],
+          url: 'https://example.com/application-p1.okpkg',
+          payloadHash: 'cc'.repeat(64),
+        },
+      },
+    };
+
+    expect(
+      buildProtocolV2FirmwareRelease({
+        currentVersions: { ...currentVersions, applicationP1: '1.0.0' },
+        currentVerification: { applicationP1Hash: 'aa'.repeat(32) },
+        firmwareType: EFirmwareType.Universal,
+        release: packageSet,
+      })
+    ).toMatchObject({
+      status: 'valid',
+      hasUpgrade: false,
+      targetsToUpdate: [],
+      components: [{ configKey: 'applicationP1', status: 'valid' }],
+    });
+  });
+
   test('keeps same-version hash-aware components unknown without metadata payloadHash', () => {
     const packageSet: IFirmwareReleaseInfo = {
       ...release,
@@ -180,6 +308,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
       buildProtocolV2FirmwareRelease({
         currentVersions: { ...currentVersions, applicationP1: '1.0.0' },
         currentVerification: { applicationP1Hash: 'aa'.repeat(32) },
+        checkFirmwareHash: true,
         firmwareType: EFirmwareType.Universal,
         release: packageSet,
       })
@@ -215,6 +344,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
     const result = buildProtocolV2FirmwareRelease({
       currentVersions,
       currentVerification: { applicationP1Hash: 'aa'.repeat(32) },
+      checkFirmwareHash: true,
       remotePayloadHashes: { applicationP1: 'cc'.repeat(64) },
       firmwareType: EFirmwareType.Universal,
       release: packageSet,
@@ -223,7 +353,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
     expect(result.targetsToUpdate).toEqual(['app_v1', 'app_v2']);
   });
 
-  test('uses the existing method on Protocol V2 and keeps its public API name', async () => {
+  test('does not read vol0 resource inventory while Protocol V2 is in Application mode', async () => {
     const method = new CheckAllFirmwareRelease({
       id: 1,
       payload: {
@@ -240,6 +370,7 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
       status: { mode: 'normal' },
       versions: currentVersions,
     });
+    const typedCall = createFilesystemTypedCall(true);
     method.device = {
       isProtocolV2: () => true,
       features: {
@@ -247,32 +378,124 @@ describe('checkAllFirmwareRelease Protocol V2 support', () => {
         firmwareVersion: '1.0.0',
       },
       getDeviceState,
+      getCommands: () => ({ typedCall }),
     } as unknown as CheckAllFirmwareRelease['device'];
     jest.spyOn(DataManager, 'getFirmwareLatestRelease').mockReturnValue(release);
+    jest.spyOn(DataManager, 'getProtocolV2Resources').mockReturnValue(stableResources as any);
 
     await expect(method.run()).resolves.toMatchObject({
       protocol: 'V2',
       deviceType: 'pro2',
       status: 'required',
-      targetsToUpdate: ['boot', 'app_v1', 'resource'],
+      resourceStatus: 'unknown',
+      targetsToUpdate: ['boot', 'app_v1'],
       firmware: {
         status: 'required',
       },
     });
+    expect(typedCall).not.toHaveBeenCalled();
+    expect(getDeviceState).toHaveBeenCalledWith({
+      refreshSections: ['identity', 'versions'],
+    });
     expect(method.getSupportedProtocols()).toEqual(['V1', 'V2']);
   });
 
+  test('requests and compares firmware hashes only when explicitly enabled', async () => {
+    const packageSet: IFirmwareReleaseInfo = {
+      ...release,
+      required: false,
+      resourceBundles: undefined,
+      installOrder: ['applicationP1'],
+      components: {
+        applicationP1: {
+          target: 'APPLICATION_P1',
+          version: [1, 0, 0],
+          url: 'https://example.com/application-p1.okpkg',
+          payloadHash: 'cc'.repeat(64),
+        },
+      },
+    };
+    const method = new CheckAllFirmwareRelease({
+      id: 1,
+      payload: {
+        method: 'checkAllFirmwareRelease',
+        firmwareType: EFirmwareType.Universal,
+        checkFirmwareHash: true,
+      },
+    });
+    method.init();
+    const getDeviceState = jest.fn().mockResolvedValue({
+      identity: { deviceType: 'pro2', firmwareType: EFirmwareType.Universal },
+      status: { mode: 'normal' },
+      versions: { ...currentVersions, applicationP1: '1.0.0' },
+      verification: { applicationP1Hash: 'aa'.repeat(32) },
+    });
+    method.device = {
+      isProtocolV2: () => true,
+      features: { deviceType: 'pro2', firmwareVersion: '1.0.0' },
+      getDeviceState,
+      getCommands: () => ({ typedCall: jest.fn() }),
+    } as unknown as CheckAllFirmwareRelease['device'];
+    jest.spyOn(DataManager, 'getFirmwareLatestRelease').mockReturnValue(packageSet);
+    jest.spyOn(DataManager, 'getProtocolV2Resources').mockReturnValue(undefined);
+
+    await expect(method.run()).resolves.toMatchObject({
+      status: 'outdated',
+      targetsToUpdate: ['app_v1'],
+    });
+    expect(getDeviceState).toHaveBeenCalledWith({
+      refreshSections: ['identity', 'versions', 'verification'],
+    });
+  });
+
+  test.each(['bootloader', 'romloader'] as const)(
+    'uses filesystem inventory in %s mode instead of forcing all resources',
+    async mode => {
+      const method = new CheckAllFirmwareRelease({
+        id: 1,
+        payload: {
+          method: 'checkAllFirmwareRelease',
+          firmwareType: EFirmwareType.Universal,
+        },
+      });
+      method.init();
+      const typedCall = createFilesystemTypedCall();
+      method.device = {
+        isProtocolV2: () => true,
+        features: { deviceType: 'pro2', firmwareVersion: '1.0.0' },
+        getDeviceState: jest.fn().mockResolvedValue({
+          identity: { deviceType: 'pro2', firmwareType: EFirmwareType.Universal },
+          status: { mode },
+          versions: currentVersions,
+        }),
+        getCommands: () => ({ typedCall }),
+      } as unknown as CheckAllFirmwareRelease['device'];
+      jest.spyOn(DataManager, 'getFirmwareLatestRelease').mockReturnValue(release);
+      jest.spyOn(DataManager, 'getProtocolV2Resources').mockReturnValue(stableResources as any);
+
+      await expect(method.run()).resolves.toMatchObject({
+        protocol: 'V2',
+        resourceStatus: 'valid',
+        targetsToUpdate: ['boot', 'app_v1'],
+      });
+      expect(typedCall.mock.calls.some(call => call[0] === 'ResourceInventoryGet')).toBe(false);
+      expect(typedCall.mock.calls.some(call => call[0] === 'FilesystemFileRead')).toBe(true);
+    }
+  );
+
   test('continues forwarding the existing public method', async () => {
     const call = jest.fn().mockResolvedValue({ success: true, payload: {} });
     const api = createCoreApi(call as CoreApi['call']) as CoreApi;
 
     await api.checkAllFirmwareRelease('pro2-connect-id', {
+      checkFirmwareHash: true,
       firmwareType: EFirmwareType.Universal,
       retryCount: 0,
     });
 
     expect(call).toHaveBeenCalledWith({
       connectId: 'pro2-connect-id',
+      checkFirmwareHash: true,
       firmwareType: EFirmwareType.Universal,
       retryCount: 0,
       method: 'checkAllFirmwareRelease',

package/__tests__/connectSettings.test.ts

@@ -1,61 +1,19 @@
-import DataManager from '../src/data-manager/DataManager';
 import { parseConnectSettings } from '../src/data-manager/connectSettings';
 
-import type { RemoteConfigResponse } from '../src/types';
-
-jest.mock('axios', () => ({
-  get: jest.fn(),
-}));
-
 jest.mock('../src/data/config', () => ({
   getSDKVersion: jest.fn(() => '1.0.0'),
   DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
 }));
 
-const mockAxiosGet: jest.Mock = jest.requireMock('axios').get;
-
 describe('parseConnectSettings', () => {
-  const preloadedConfig = {
-    bridge: {},
-    classic: { firmware: [], ble: [] },
-    classic1s: { firmware: [], ble: [] },
-    classicpure: { firmware: [], ble: [] },
-    mini: { firmware: [], ble: [] },
-    touch: { firmware: [], ble: [] },
-    pro: { firmware: [], ble: [] },
-    pro2: { firmware: [], ble: [] },
-  } as unknown as RemoteConfigResponse;
-
-  it('keeps a serializable preloaded config in parsed settings', () => {
-    const settings = parseConnectSettings({
-      firmwareManifestMode: 'sdk-managed',
-      preloadedConfig,
-    });
-
-    expect(settings.firmwareManifestMode).toBe('sdk-managed');
-    expect(settings.preloadedConfig).toBe(preloadedConfig);
-  });
-
-  it('uses the preloaded config before the SDK network client', async () => {
-    const settings = parseConnectSettings({
-      firmwareManifestMode: 'sdk-managed',
-      preloadedConfig,
-    });
-
-    await DataManager.load(settings);
-
-    expect(mockAxiosGet).not.toHaveBeenCalled();
-    expect(DataManager.deviceMap.classic).toEqual({ firmware: [], ble: [] });
-  });
+  it('keeps custom configFetcher in parsed settings', () => {
+    const configFetcher = jest.fn();
 
-  it('fails closed without a preloaded config in external-only mode', async () => {
     const settings = parseConnectSettings({
-      firmwareManifestMode: 'external-only',
+      fetchConfig: true,
+      configFetcher,
     });
 
-    await expect(DataManager.load(settings)).rejects.toThrow(
-      'External firmware config snapshot is required'
-    );
-    expect(mockAxiosGet).not.toHaveBeenCalled();
+    expect(settings.configFetcher).toBe(configFetcher);
   });
 });

package/__tests__/core-initialization.test.ts

@@ -0,0 +1,23 @@
+import { DataManager } from '../src/data-manager';
+import { init } from '../src/core';
+
+import type { ConnectSettings } from '../src/types';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0-test'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0-test/',
+}));
+
+describe('Core initialization', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('does not create a partially initialized core when settings loading fails', async () => {
+    jest.spyOn(DataManager, 'load').mockRejectedValue(new Error('settings load failed'));
+
+    await expect(init({} as ConnectSettings, class TestTransport {})).rejects.toThrow(
+      'settings load failed'
+    );
+  });
+});

package/__tests__/device-connector-protocol.test.ts

@@ -0,0 +1,81 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import DeviceConnector from '../src/device/DeviceConnector';
+
+jest.mock('../src/data-manager/TransportManager', () => ({
+  __esModule: true,
+  default: {
+    load: jest.fn(),
+    getTransport: jest.fn(),
+  },
+}));
+
+jest.mock('../src/data-manager', () => ({
+  DataManager: {
+    getSettings: jest.fn(() => 'desktop-web-ble'),
+    isBleConnect: jest.fn(() => true),
+  },
+}));
+
+jest.mock('../src/device/DevicePool', () => ({
+  DevicePool: {
+    setConnector: jest.fn(),
+  },
+}));
+
+const transportManagerMock: {
+  default: {
+    getTransport: jest.Mock;
+  };
+} = jest.requireMock('../src/data-manager/TransportManager');
+
+describe('DeviceConnector protocol validation', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('reports an explicit transport error when connector initialization ran too early', async () => {
+    transportManagerMock.default.getTransport.mockReturnValue(undefined);
+    const connector = new DeviceConnector();
+
+    await expect(connector.enumerate()).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.TransportNotConfigured,
+    });
+  });
+
+  it('uses the actively probed protocol returned by acquire when the cache was cleared', async () => {
+    const acquire = jest.fn().mockResolvedValue({
+      id: 'pro2-id',
+      path: 'pro2-id',
+      protocolType: 'V2',
+    });
+    transportManagerMock.default.getTransport.mockReturnValue({
+      acquire,
+      getProtocolType: jest.fn(() => undefined),
+    });
+    const connector = new DeviceConnector();
+
+    await expect(connector.acquire('pro2-id', undefined, undefined, 'V2')).resolves.toEqual(
+      expect.objectContaining({ protocolType: 'V2' })
+    );
+    expect(acquire).toHaveBeenCalledWith(
+      expect.objectContaining({ uuid: 'pro2-id', expectedProtocol: 'V2' })
+    );
+  });
+
+  it('still rejects a real mismatch reported by the active protocol probe', async () => {
+    transportManagerMock.default.getTransport.mockReturnValue({
+      acquire: jest.fn().mockResolvedValue({
+        id: 'classic-id',
+        path: 'classic-id',
+        protocolType: 'V1',
+      }),
+      getProtocolType: jest.fn(() => 'V1'),
+    });
+    const connector = new DeviceConnector();
+
+    await expect(connector.acquire('classic-id', undefined, undefined, 'V2')).rejects.toThrow(
+      'Device protocol mismatch: expected V2, detected V1'
+    );
+  });
+});

package/__tests__/device-lifecycle-events.test.ts

@@ -1,3 +1,4 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
 import { TRANSPORT_EVENT } from '@onekeyfe/hd-transport';
 
 import { initConnector, initCore } from '../src/core';
@@ -95,7 +96,7 @@ describe('public device lifecycle events', () => {
     expect(messages.filter(message => message.type === DEVICE.DISCONNECT)).toHaveLength(1);
   });
 
-  test('uses a cached protocol as a fallback-capable acquire hint', async () => {
+  test('uses a verified cached protocol as a strict expected protocol', async () => {
     jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
     const device = Device.fromDescriptor({
       id: 'ble-id',
@@ -103,16 +104,117 @@ describe('public device lifecycle events', () => {
       commType: 'ble',
       protocolType: 'V1',
     } as never);
-    const acquire = jest.fn().mockResolvedValue({ uuid: 'ble-id', protocolType: 'V2' });
+    const acquire = jest.fn().mockResolvedValue({ uuid: 'ble-id', protocolType: 'V1' });
     device.deviceConnector = { acquire } as never;
 
     await device.acquire();
 
-    expect(acquire).toHaveBeenCalledWith('ble-id', undefined, true, undefined, 'V1');
+    expect(acquire).toHaveBeenCalledWith('ble-id', undefined, true, 'V1', undefined);
+    expect(device.getProtocol()).toBe('V1');
+    expect(device.originalDescriptor.protocolType).toBe('V1');
+  });
+
+  test('bypasses a cached protocol only for explicit active detection', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
+    const device = Device.fromDescriptor({
+      id: 'ble-id',
+      path: 'ble-id',
+      commType: 'ble',
+      protocolType: 'V1',
+    } as never);
+    const acquire = jest.fn().mockResolvedValue({ uuid: 'ble-id', protocolType: 'V2' });
+    device.deviceConnector = { acquire } as never;
+
+    await device.acquire(undefined, { forceProtocolDetection: true });
+
+    expect(acquire).toHaveBeenCalledWith('ble-id', undefined, true, undefined, undefined);
     expect(device.getProtocol()).toBe('V2');
     expect(device.originalDescriptor.protocolType).toBe('V2');
   });
 
+  test('does not reuse a stale protocol when active detection returns no protocol', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
+    const device = Device.fromDescriptor({
+      id: 'ble-id',
+      path: 'ble-id',
+      commType: 'ble',
+      protocolType: 'V1',
+    } as never);
+    const acquire = jest.fn().mockResolvedValue({ uuid: 'ble-id' });
+    const release = jest.fn().mockResolvedValue(undefined);
+    device.deviceConnector = { acquire, release } as never;
+    await expect(
+      device.acquire(undefined, {
+        forceProtocolDetection: true,
+        throwOnRunPromiseError: true,
+      })
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.RuntimeError });
+    expect(device.originalDescriptor.protocolType).toBe('V1');
+    expect(device.hasDeviceAcquire()).toBe(false);
+    expect(release).toHaveBeenCalledWith('ble-id', false);
+  });
+
+  test('actively reacquires an already connected device without initializing it', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('webusb' as never);
+    const device = Device.fromDescriptor({
+      id: 'usb-device',
+      path: 'usb-device',
+      session: 'old-session',
+      protocolType: 'V1',
+    } as never);
+    device.mainId = 'old-session';
+    device.commands = { disposed: false } as never;
+    const release = jest.spyOn(device, 'release').mockImplementation(() => {
+      device.mainId = null;
+      device.originalDescriptor.session = null;
+      device.commands.disposed = true;
+      return Promise.resolve();
+    });
+    const acquire = jest.spyOn(device, 'acquire').mockImplementation(() => {
+      device.mainId = 'new-session';
+      device.originalDescriptor.session = 'new-session';
+      device.originalDescriptor.protocolType = 'V2';
+      device.commands.disposed = false;
+      return Promise.resolve();
+    });
+    const initialize = jest.spyOn(device, 'initialize').mockResolvedValue(undefined);
+
+    await device.run(() => Promise.resolve(undefined), {
+      forceProtocolDetection: true,
+      skipInitialize: true,
+    });
+
+    expect(release).toHaveBeenCalled();
+    expect(acquire).toHaveBeenCalledWith(undefined, {
+      forceProtocolDetection: true,
+    });
+    expect(initialize).not.toHaveBeenCalled();
+    expect(device.getProtocol()).toBe('V2');
+  });
+
+  test('keeps the freshly probed React Native BLE session until the call completes', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
+    const device = Device.fromDescriptor({
+      id: 'ble-device',
+      path: 'ble-device',
+      commType: 'ble',
+      protocolType: 'V1',
+    } as never);
+    device.mainId = 'ble-device';
+    device.commands = { disposed: false } as never;
+    (device as unknown as { deviceAcquired: boolean }).deviceAcquired = true;
+    const release = jest.spyOn(device, 'release').mockResolvedValue(undefined);
+    const run = jest.fn().mockResolvedValue(undefined);
+
+    await device.run(run, {
+      forceProtocolDetection: true,
+      skipInitialize: true,
+    });
+
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
   test('keeps an explicit connectProtocol as a strict expected protocol', async () => {
     jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
     const device = Device.fromDescriptor({

package/__tests__/device-pool-state.test.ts

@@ -38,6 +38,28 @@ describe('DevicePool state lifecycle', () => {
     expect(getDeviceState).toHaveBeenNthCalledWith(2, { refreshSections: ['settings'] });
   });
 
+  test('actively re-detects a cached device when protocol detection is forced', async () => {
+    const descriptor = { path: 'cached-path', protocolType: 'V1' } as any;
+    const device = Device.fromDescriptor(descriptor);
+    const acquire = jest.spyOn(device, 'acquire').mockImplementation(() => {
+      device.originalDescriptor.protocolType = 'V2';
+      return Promise.resolve(true);
+    });
+    const initialize = jest.spyOn(device, 'initialize').mockResolvedValue(undefined);
+    const release = jest.spyOn(device, 'release').mockResolvedValue(undefined);
+    DevicePool.devicesCache = { 'cached-id': device };
+
+    const result = await DevicePool.getDevices([descriptor], 'cached-id', {
+      forceProtocolDetection: true,
+    });
+
+    expect(acquire).toHaveBeenCalledWith(undefined, { forceProtocolDetection: true });
+    expect(initialize).toHaveBeenCalledWith({ forceProtocolDetection: true });
+    expect(release).toHaveBeenCalledTimes(1);
+    expect(device.originalDescriptor.protocolType).toBe('V2');
+    expect(result.deviceList).toEqual([device]);
+  });
+
   test('keeps a discovered device when its Protocol V2 label cannot be read', async () => {
     const labelError = new Error('settings unavailable');
     const getDeviceState = jest