@onekeyfe/hd-core 1.2.0-alpha.40 → 1.2.0-alpha.41

package/__tests__/protocol-v2.test.ts

@@ -61,7 +61,6 @@ import { createCoreApi } from '../src/inject';
 import { Device, preloadSessionCache } from '../src/device/Device';
 import { deviceWalletSessionStore } from '../src/device/DeviceWalletSessionStore';
 import { DevicePool } from '../src/device/DevicePool';
-import { DEVICE } from '../src/events';
 import { UI_REQUEST } from '../src/events/ui-request';
 import {
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
@@ -79,10 +78,7 @@ import {
   getProtocolV2WalletSession,
   refreshProtocolV2DeviceStatus,
 } from '../src/protocols/protocol-v2/walletSession';
-import {
-  createProtocolV2UnlockContext,
-  runMethodWithUnlockPolicy,
-} from '../src/protocols/protocol-v2/unlockPolicyRunner';
+import { runMethodWithUnlockRetry } from '../src/protocols/protocol-v2/unlockRetry';
 import { BaseMethod } from '../src/api/BaseMethod';
 import {
   buildProtocolV1FeaturesPayload,
@@ -96,6 +92,7 @@ import {
   getMethodVersionRange,
 } from '../src/utils';
 import { getDeviceFirmwareVersion } from '../src/utils/deviceVersionUtils';
+import { openFirmwareByteSource } from '../src/api/firmware/FirmwareArtifactSource';
 import {
   getPassphraseState,
   getPassphraseStateWithRefreshDeviceInfo,
@@ -244,7 +241,7 @@ describe('UploadPortfolio', () => {
     (method as any).device = device;
 
     method.init();
-    await runMethodWithUnlockPolicy(method, device as any);
+    await runMethodWithUnlockRetry(method, device as any);
 
     expect(unlockDevice).not.toHaveBeenCalled();
     expect(typedCall).toHaveBeenNthCalledWith(
@@ -420,16 +417,14 @@ function stubDevice<T extends Record<string, any>>(device: T): T {
     }
     return d.features;
   };
-  d.ensureProtocolV2RuntimeContext ??= (timeoutMs?: number) =>
-    requestProtocolV2ProtocolInfo({
-      commands: d.getCommands?.() ?? d.commands,
-      timeoutMs,
-    });
   d.probeProtocolV2RuntimeState ??= async (
     deviceInfo: ProtocolV2DeviceInfo,
     timeoutMs?: number
   ) => {
-    const protocolInfo = await d.ensureProtocolV2RuntimeContext(timeoutMs);
+    const protocolInfo = await requestProtocolV2ProtocolInfo({
+      commands: d.getCommands(),
+      timeoutMs,
+    });
     const runtimeMode = getProtocolV2RuntimeMode(protocolInfo);
     if (runtimeMode === 'bootloader' || runtimeMode === 'romloader') {
       return d.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
@@ -810,7 +805,7 @@ describe('Protocol V2 feature adapter', () => {
     ).resolves.toEqual({
       passphraseState: 'state-1',
       newSession: 'session-1',
-      unlockedAttachPin: false,
+      unlockedAttachPin: undefined,
       resumed: false,
     });
     expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
@@ -1558,70 +1553,6 @@ describe('Protocol V2 feature adapter', () => {
     expect(device.getInternalState()).toBeUndefined();
   });
 
-  test.each([false, true])(
-    'rejects a different Attach PIN wallet when Pro2 lock failure is %s',
-    async lockFails => {
-      const deviceId = 'attach-mismatch-device';
-      const device = Device.fromDescriptor({ ...descriptor, protocolType: 'V2' } as any);
-      (device as any).features = normalizeProtocolV2Features(
-        { ...descriptor, protocolType: 'V2' } as any,
-        {
-          status: {
-            device_id: deviceId,
-            unlocked: true,
-            passphrase_enabled: true,
-            attach_to_pin_enabled: true,
-            unlocked_by_attach_to_pin: false,
-          },
-        }
-      );
-      device.passphraseState = 'expected-state';
-
-      const typedCall = jest.fn((request: string) => {
-        if (request === 'ProtocolInfoRequest') return { message: { version: 2 } };
-        if (request === 'DeviceSessionAskPin') return { message: { message: 'PIN verified' } };
-        if (request === 'DeviceStatusGet') {
-          return {
-            message: {
-              device_id: deviceId,
-              unlocked: true,
-              passphrase_enabled: true,
-              attach_to_pin_enabled: true,
-              unlocked_by_attach_to_pin: true,
-            },
-          };
-        }
-        if (request === 'DeviceSessionGet') {
-          return {
-            message: {
-              btc_test_address: 'wrong-attach-state',
-              session_id: 'wrong-attach-session',
-            },
-          };
-        }
-        if (request === 'LockDevice') {
-          if (lockFails) throw new Error('Lock unsupported');
-          return { message: { message: 'Device locked' } };
-        }
-        throw new Error(`Unexpected request: ${request}`);
-      });
-      const promptPassphrase = jest.fn().mockResolvedValue({ attachPinOnDevice: true });
-      (device as any).commands = { typedCall, promptPassphrase };
-
-      await expect(
-        getProtocolV2WalletSession(device, { expectedPassphraseState: 'expected-state' })
-      ).rejects.toMatchObject({
-        errorCode: HardwareErrorCode.DeviceCheckUnlockTypeError,
-      });
-
-      expect(promptPassphrase).not.toHaveBeenCalled();
-      expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
-      expect(typedCall).toHaveBeenCalledWith('LockDevice', 'Success', {});
-      expect(typedCall.mock.calls.filter(call => call[0] === 'DeviceSessionGet')).toHaveLength(1);
-      expect(device.getInternalState()).toBeUndefined();
-    }
-  );
-
   test('recovers an expired Attach PIN wallet through the unified wallet selector', async () => {
     const device = Device.fromDescriptor({
       id: 'cache-device-attach-recovery',
@@ -1678,17 +1609,7 @@ describe('Protocol V2 feature adapter', () => {
       }),
       { cancelDeviceOnReject: false }
     );
-    expect(unlockDevice).toHaveBeenCalledWith(
-      DeviceSessionPinType.AttachToPin,
-      expect.objectContaining({
-        emitUiEvent: false,
-        interaction: expect.objectContaining({
-          phase: 'pin',
-          transition: 'start',
-          protocol: 'V2',
-        }),
-      })
-    );
+    expect(unlockDevice).toHaveBeenCalledWith(DeviceSessionPinType.AttachToPin);
     expect(device.getInternalState()).toBe('new-attach-session');
   });
 
@@ -1972,10 +1893,12 @@ describe('Protocol V2 feature adapter', () => {
     expect(getFeatures).not.toHaveBeenCalled();
   });
 
-  test('uses the cached wallet address when the local session is missing', async () => {
+  test('marks an interactive cache miss as a wallet-session recovery', async () => {
     const typedCall = jest
       .fn()
       .mockResolvedValueOnce({ message: { version: 2 } })
+      .mockResolvedValueOnce({ message: { message: 'Passphrase prepared' } })
+      .mockResolvedValueOnce({ message: { unlocked: true, unlocked_attach_pin: false } })
       .mockResolvedValueOnce({
         message: {
           btc_test_address: 'expected-state',
@@ -2003,8 +1926,16 @@ describe('Protocol V2 feature adapter', () => {
     await expect(
       getProtocolV2WalletSession(device, { expectedPassphraseState: 'expected-state' })
     ).resolves.toMatchObject({ passphraseState: 'expected-state' });
-    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
-    expect(promptPassphrase).not.toHaveBeenCalled();
+    expect(promptPassphrase).toHaveBeenCalledWith(
+      {
+        existsAttachPinUser: false,
+        deviceOnly: false,
+        source: 'wallet-session-coordinator',
+        reason: 'session-recovery',
+        expectedPassphraseState: 'expected-state',
+      },
+      { cancelDeviceOnReject: false }
+    );
   });
 
   test('reuses the Pro2 session opened by legacy getPassphraseState on the next App call', async () => {
@@ -2070,6 +2001,7 @@ describe('Protocol V2 feature adapter', () => {
       true
     );
     expect(typedCall.mock.calls).toEqual([
+      ['ProtocolInfoRequest', 'ProtocolInfo', { eventless_wallet_session: true }],
       ['DeviceSessionGet', 'DeviceSession', { session_id: 'session-pro2-app' }],
     ]);
   });
@@ -2337,13 +2269,12 @@ describe('Protocol V2 feature adapter', () => {
     );
 
     expect(device.getInternalState()).toBeUndefined();
-    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
-    expect(typedCall).toHaveBeenCalledWith('DeviceSessionAskPassphrase', 'Success', {
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'DeviceSessionAskPassphrase', 'Success', {
       passphrase: 'host hidden wallet',
       on_device: false,
     });
-    expect(typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
-    expect(typedCall).toHaveBeenCalledWith('DeviceSessionGet', 'DeviceSession', {});
+    expect(typedCall).toHaveBeenNthCalledWith(3, 'DeviceStatusGet', 'DeviceStatus', {});
+    expect(typedCall).toHaveBeenNthCalledWith(4, 'DeviceSessionGet', 'DeviceSession', {});
   });
 
   test('useEmptyPassphrase ignores a stale hidden-wallet state during Protocol V2 safety check', async () => {
@@ -2380,9 +2311,6 @@ describe('Protocol V2 feature adapter', () => {
     expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
       eventless_wallet_session: true,
     });
-    expect(typedCall).toHaveBeenCalledWith('DeviceSessionAskPin', 'Success', {
-      type: DeviceSessionPinType.Main,
-    });
   });
 
   test('marks fallback features as unavailable when DeviceInfo is missing', () => {
@@ -2753,9 +2681,7 @@ describe('Protocol V2 feature adapter', () => {
         timeoutMs: PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
       }
     );
-    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {
-      eventless_wallet_session: true,
-    });
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {});
     expect(typedCall).toHaveBeenNthCalledWith(3, 'DeviceStatusGet', 'DeviceStatus', {});
   });
 
@@ -2793,9 +2719,7 @@ describe('Protocol V2 feature adapter', () => {
       }),
       expect.anything()
     );
-    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {
-      eventless_wallet_session: true,
-    });
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'ProtocolInfoRequest', 'ProtocolInfo', {});
     expect(typedCall).not.toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
     expect(device.features).toMatchObject({
       deviceId: null,
@@ -3061,6 +2985,10 @@ describe('Protocol V2 feature adapter', () => {
           fw: { application: { version: '1.2.4' } },
         },
       })
+      .mockResolvedValueOnce({
+        type: 'ProtocolInfo',
+        message: protocolV2ApplicationInfo,
+      })
       .mockResolvedValueOnce({
         type: 'DeviceStatus',
         message: { init_states: true, unlocked: true },
@@ -3082,7 +3010,7 @@ describe('Protocol V2 feature adapter', () => {
       firmwareVersion: '1.2.4',
       passphraseProtection: null,
     });
-    expect(typedCall).toHaveBeenCalledTimes(5);
+    expect(typedCall).toHaveBeenCalledTimes(6);
     expect(typedCall).toHaveBeenNthCalledWith(
       4,
       'DeviceInfoGet',
@@ -3196,23 +3124,9 @@ describe('Protocol V2 feature adapter', () => {
         status: { init_states: true },
       }
     );
-    const pinOnDevice = jest.fn();
-    device.on(DEVICE.PIN_ON_DEVICE, pinOnDevice);
 
     const features = await device.unlockDevice();
 
-    expect(pinOnDevice).toHaveBeenCalledWith(
-      device,
-      DeviceSessionPinType.Main,
-      expect.objectContaining({
-        source: 'unlock-coordinator',
-        reason: 'device-unlock',
-        deviceOnly: true,
-      })
-    );
-    expect(pinOnDevice.mock.invocationCallOrder[0]).toBeLessThan(
-      typedCall.mock.invocationCallOrder[0]
-    );
     expect(typedCall.mock.calls).toEqual([
       ['DeviceSessionAskPin', 'Success', { type: DeviceSessionPinType.Main }],
       ['DeviceStatusGet', 'DeviceStatus', {}],
@@ -3258,12 +3172,9 @@ describe('Protocol V2 feature adapter', () => {
       throw new Error(`Unexpected request: ${requestType}`);
     });
     (device as any).commands = { typedCall };
-    const pinOnDevice = jest.fn();
-    device.on(DEVICE.PIN_ON_DEVICE, pinOnDevice);
 
-    await device.unlockDevice(DeviceSessionPinType.Main, { emitUiEvent: false });
+    await device.unlockDevice();
 
-    expect(pinOnDevice).not.toHaveBeenCalled();
     expect(typedCall.mock.calls).toEqual([
       ['DeviceSessionAskPin', 'Success', { type: DeviceSessionPinType.Main }],
       ['DeviceStatusGet', 'DeviceStatus', {}],
@@ -3806,7 +3717,7 @@ describe('Protocol V2 firmware update targets', () => {
     });
   });
 
-  test('enters Protocol V2 bootloader before upload', async () => {
+  test('delegates Protocol V2 mode transition to the phase executor', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
       payload: {
@@ -3841,7 +3752,7 @@ describe('Protocol V2 firmware update targets', () => {
 
     await method.run();
 
-    expect((method as any).enterProtocolV2BootloaderMode).toHaveBeenCalledTimes(1);
+    expect((method as any).enterProtocolV2BootloaderMode).not.toHaveBeenCalled();
     expect((method as any).executeProtocolV2Update).toHaveBeenCalledWith({
       fwBinaryMap: [
         {
@@ -4224,9 +4135,9 @@ describe('Protocol V2 firmware update targets', () => {
     const typedCall = jest
       .fn()
       .mockRejectedValue(
-        new DOMException(
-          "Failed to execute 'open' on 'USBDevice': The device was disconnected",
-          'NotFoundError'
+        Object.assign(
+          new Error("Failed to execute 'open' on 'USBDevice': The device was disconnected"),
+          { name: 'NotFoundError' }
         )
       );
 
@@ -4407,6 +4318,77 @@ describe('Protocol V2 firmware update targets', () => {
     expect((method as any).probeProtocolV2NormalMode).toHaveBeenCalledWith(deviceInfo);
   });
 
+  test('rejects a finished target whose payload version conflicts with the plan', () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+        platform: 'desktop',
+        expectedTargetVersions: {
+          app_v1: '2.0.0',
+        },
+      },
+    });
+    method.init();
+    method.postProgressMessage = jest.fn();
+
+    expect(() =>
+      (method as any).assertProtocolV2TargetStatus(
+        [{ target_id: 4, status: 2, payload_version: 0x010000 }],
+        new Set([4])
+      )
+    ).toThrow('expected 131072');
+  });
+
+  test('does not fail a completed multi-app install when final app versions are unobservable', () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+        platform: 'desktop',
+        targetsToUpdate: ['app_v1', 'app_v2'],
+        expectedTargetVersions: {
+          app_v1: '1.0.0',
+          app_v2: '2.0.0',
+        },
+      },
+    });
+    method.init();
+    (method as any).protocolV2LatestFinalFeatures = {
+      major_version: 3,
+      minor_version: 0,
+      patch_version: 0,
+    };
+    (method as any).protocolV2FinalStatusVerified = true;
+
+    expect(() => (method as any).assertExpectedProtocolV2Versions()).not.toThrow();
+  });
+
+  test('rejects unobservable final versions after the status endpoint fallback', () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+        platform: 'desktop',
+        targetsToUpdate: ['app_v1', 'app_v2'],
+        expectedTargetVersions: {
+          app_v1: '1.0.0',
+          app_v2: '2.0.0',
+        },
+      },
+    });
+    method.init();
+    (method as any).protocolV2LatestFinalFeatures = {
+      major_version: 3,
+      minor_version: 0,
+      patch_version: 0,
+    };
+
+    expect(() => (method as any).assertExpectedProtocolV2Versions()).toThrow(
+      'has no observable final version after status fallback'
+    );
+  });
+
   test('polls target status after update ACK and finishes when all targets complete', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
@@ -4483,7 +4465,7 @@ describe('Protocol V2 firmware update targets', () => {
     ).toBe(true);
 
     (method.postProgressMessage as jest.Mock).mockClear();
-    expect(
+    expect(() =>
       (method as any).assertProtocolV2TargetStatus(
         [
           { target_id: 4, status: 'FW_MGMT_UPDATER_TASK_STATUS_FINISHED' },
@@ -4491,8 +4473,8 @@ describe('Protocol V2 firmware update targets', () => {
         ],
         new Set([4, 10])
       )
-    ).toBe(false);
-    expect(method.postProgressMessage).toHaveBeenCalledWith(50, 'installingFirmware');
+    ).toThrow('Protocol V2 install status conflicts with target 4');
+    expect(method.postProgressMessage).not.toHaveBeenCalled();
     expect(method.postProgressMessage).not.toHaveBeenCalledWith(100, 'installingFirmware');
 
     expect(
@@ -4596,10 +4578,14 @@ describe('Protocol V2 firmware update targets', () => {
     const writtenPaths: string[] = [];
     method.postTipMessage = jest.fn();
     method.postProgressMessage = jest.fn();
-    (method as any).protocolV2CommonUpdateProcess = jest.fn().mockImplementation(params => {
+    (method as any).protocolV2SourceUpdateProcess = jest.fn().mockImplementation(params => {
       writtenPaths.push(params.filePath);
-      return Number(params.processedSize ?? 0) + Number(params.payload.byteLength);
+      return Number(params.processedSize ?? 0) + Number(params.source.size);
     });
+    (method as any).enterProtocolV2BootloaderMode = jest.fn().mockResolvedValue(undefined);
+    (method as any).exitProtocolV2BootloaderToNormal = jest.fn().mockResolvedValue(undefined);
+    (method as any).waitForProtocolV2FinalFeatures = jest.fn().mockResolvedValue({});
+    (method as any).completeProtocolV2FinalVerification = jest.fn().mockResolvedValue({});
     (method as any).verifyProtocolV2StagedFile = jest.fn().mockResolvedValue(undefined);
     (method as any).protocolV2StartFirmwareUpdate = jest.fn().mockResolvedValue(undefined);
     (method as any).waitForProtocolV2FirmwareUpdateComplete = jest
@@ -4639,10 +4625,12 @@ describe('Protocol V2 firmware update targets', () => {
       'vol0:/coprocessor.bin',
       1
     );
-    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenCalledTimes(1);
-    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenCalledWith({
+    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenCalledTimes(2);
+    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenNthCalledWith(1, {
+      targets: [{ target_id: 3, path: 'vol0:/bootloader.bin' }],
+    });
+    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenNthCalledWith(2, {
       targets: [
-        { target_id: 3, path: 'vol0:/bootloader.bin' },
         { target_id: 6, path: 'vol0:/coprocessor.bin' },
         { target_id: 7, path: 'vol0:/se01.bin' },
         { target_id: 4, path: 'vol0:/application_p1.bin' },
@@ -4652,7 +4640,7 @@ describe('Protocol V2 firmware update targets', () => {
     expect((method as any).waitForProtocolV2FirmwareUpdateComplete).toHaveBeenCalled();
   });
 
-  test('announces one transfer when syncing resource bundles and staging firmware', async () => {
+  test('announces separate resource and component transfer phases', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
       payload: {
@@ -4662,11 +4650,14 @@ describe('Protocol V2 firmware update targets', () => {
 
     method.postTipMessage = jest.fn();
     method.postProgressMessage = jest.fn();
-    (method as any).protocolV2CommonUpdateProcess = jest
+    (method as any).protocolV2SourceUpdateProcess = jest
       .fn()
       .mockImplementation(params =>
-        Promise.resolve(Number(params.processedSize ?? 0) + Number(params.payload.byteLength))
+        Promise.resolve(Number(params.processedSize ?? 0) + Number(params.source.size))
       );
+    (method as any).enterProtocolV2BootloaderMode = jest.fn().mockResolvedValue(undefined);
+    (method as any).exitProtocolV2BootloaderToNormal = jest.fn().mockResolvedValue(undefined);
+    (method as any).completeProtocolV2FinalVerification = jest.fn().mockResolvedValue({});
     (method as any).verifyProtocolV2StagedFile = jest.fn().mockResolvedValue(undefined);
     (method as any).protocolV2StartFirmwareUpdate = jest.fn().mockResolvedValue(undefined);
     (method as any).waitForProtocolV2FirmwareUpdateComplete = jest
@@ -4686,21 +4677,22 @@ describe('Protocol V2 firmware update targets', () => {
         {
           fileName: 'application_p1.bin',
           binary: new Uint8Array([3]).buffer,
-          targetId: 3,
+          targetId: 4,
         },
       ],
     });
 
-    expect(method.postTipMessage).toHaveBeenCalledTimes(2);
+    expect(method.postTipMessage).toHaveBeenCalledTimes(3);
     expect(method.postTipMessage).toHaveBeenNthCalledWith(1, 'StartTransferData');
-    expect(method.postTipMessage).toHaveBeenNthCalledWith(2, 'ConfirmOnDevice');
-    expect((method as any).protocolV2CommonUpdateProcess).toHaveBeenNthCalledWith(
+    expect(method.postTipMessage).toHaveBeenNthCalledWith(2, 'StartTransferData');
+    expect(method.postTipMessage).toHaveBeenNthCalledWith(3, 'ConfirmOnDevice');
+    expect((method as any).protocolV2SourceUpdateProcess).toHaveBeenNthCalledWith(
       1,
-      expect.objectContaining({ processedSize: 0, totalSize: 3 })
+      expect.objectContaining({ processedSize: 0, totalSize: 2 })
     );
-    expect((method as any).protocolV2CommonUpdateProcess).toHaveBeenNthCalledWith(
+    expect((method as any).protocolV2SourceUpdateProcess).toHaveBeenNthCalledWith(
       2,
-      expect.objectContaining({ processedSize: 2, totalSize: 3 })
+      expect.objectContaining({ processedSize: 0, totalSize: 1 })
     );
   });
 
@@ -4714,7 +4706,8 @@ describe('Protocol V2 firmware update targets', () => {
 
     method.postTipMessage = jest.fn();
     method.postProgressMessage = jest.fn();
-    (method as any).protocolV2CommonUpdateProcess = jest.fn().mockResolvedValue(3);
+    (method as any).protocolV2SourceUpdateProcess = jest.fn().mockResolvedValue(3);
+    (method as any).enterProtocolV2BootloaderMode = jest.fn().mockResolvedValue(undefined);
     (method as any).device = stubDevice({
       getCommands: () => ({
         typedCall: jest.fn().mockResolvedValue({
@@ -4760,11 +4753,14 @@ describe('Protocol V2 firmware update targets', () => {
 
     method.postTipMessage = jest.fn();
     method.postProgressMessage = jest.fn();
-    (method as any).protocolV2CommonUpdateProcess = jest
+    (method as any).protocolV2SourceUpdateProcess = jest
       .fn()
       .mockImplementation(params =>
-        Promise.resolve(Number(params.processedSize ?? 0) + Number(params.payload.byteLength))
+        Promise.resolve(Number(params.processedSize ?? 0) + Number(params.source.size))
       );
+    (method as any).enterProtocolV2BootloaderMode = jest.fn().mockResolvedValue(undefined);
+    (method as any).exitProtocolV2BootloaderToNormal = jest.fn().mockResolvedValue(undefined);
+    (method as any).completeProtocolV2FinalVerification = jest.fn().mockResolvedValue({});
     (method as any).verifyProtocolV2StagedFile = jest.fn().mockResolvedValue(undefined);
     (method as any).protocolV2StartFirmwareUpdate = jest.fn().mockResolvedValue(undefined);
     (method as any).waitForProtocolV2FirmwareUpdateComplete = jest
@@ -5087,6 +5083,58 @@ describe('Protocol V2 firmware update targets', () => {
     getFirmwareLatestReleaseSpy.mockRestore();
   });
 
+  test('rejects prepared RESC bundle paths before opening an artifact source', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const openPreparedSource = jest.fn();
+    (method as any).params = {
+      targetsToUpdate: ['resource'],
+      resourceBundleArtifacts: [
+        {
+          name: 'images',
+          artifact: {
+            artifactRef: `fw:${'a'.repeat(64)}`,
+            size: 1,
+            sha256: 'a'.repeat(64),
+          },
+        },
+      ],
+    };
+    (method as any).openProtocolV2PreparedSource = openPreparedSource;
+    const getFirmwareLatestReleaseSpy = jest
+      .spyOn(DataManager, 'getFirmwareLatestRelease')
+      .mockReturnValue({
+        required: false,
+        version: [1, 0, 0],
+        url: '',
+        resourceBundles: [
+          {
+            name: 'images',
+            url: 'https://example.com/images.okpkg',
+            devicePath: 'vol0:/resource/../images.okpkg',
+          },
+        ],
+        fingerprint: '',
+        changelog: {
+          'zh-CN': '',
+          'en-US': '',
+        },
+      });
+
+    await expect(
+      (method as any).prepareProtocolV2ResourceSources('universal', {
+        deviceType: 'pro2',
+      })
+    ).rejects.toThrow('resourceBundles[].devicePath');
+    expect(openPreparedSource).not.toHaveBeenCalled();
+
+    getFirmwareLatestReleaseSpy.mockRestore();
+  });
+
   test('downloads and validates remote RESC bundles before entering bootloader', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
@@ -5139,7 +5187,9 @@ describe('Protocol V2 firmware update targets', () => {
       order.push('bootloader');
       return Promise.resolve(true);
     });
-    (method as any).executeProtocolV2Update = jest.fn().mockResolvedValue(undefined);
+    const executeProtocolV2UpdateSpy = jest.spyOn(method as any, 'executeProtocolV2Update');
+    (method as any).executeProtocolV2TransferPhase = jest.fn().mockResolvedValue(undefined);
+    (method as any).completeProtocolV2FinalVerification = jest.fn().mockResolvedValue(undefined);
     (method as any).exitProtocolV2BootloaderToNormal = jest.fn().mockResolvedValue(undefined);
     (method as any).waitForProtocolV2FinalFeatures = jest.fn().mockResolvedValue({
       bootloaderVersion: '1.0.0',
@@ -5151,7 +5201,7 @@ describe('Protocol V2 firmware update targets', () => {
     await method.run();
 
     expect(order).toEqual(['download', 'bootloader']);
-    expect((method as any).executeProtocolV2Update).toHaveBeenCalledWith({
+    expect(executeProtocolV2UpdateSpy).toHaveBeenCalledWith({
       bootloaderBinary: null,
       fwBinaryMap: [],
       resourceBundles: [
@@ -5164,6 +5214,7 @@ describe('Protocol V2 firmware update targets', () => {
       ],
     });
 
+    executeProtocolV2UpdateSpy.mockRestore();
     getSysResourceBinarySpy.mockRestore();
     getFirmwareLatestReleaseSpy.mockRestore();
   });
@@ -5175,12 +5226,13 @@ describe('Protocol V2 firmware update targets', () => {
         method: 'firmwareUpdateV4',
       },
     });
+    method.init();
     const getSysResourceBinarySpy = jest
       .spyOn(firmwareBinaryApi, 'getSysResourceBinary')
       .mockResolvedValue({ binary: new Uint8Array([1, 2, 3]).buffer });
 
     await expect(
-      (method as any).prefetchProtocolV2ResourceBundles([
+      (method as any).materializeProtocolV2ResourceBundles([
         {
           name: 'images',
           binary: new ArrayBuffer(0),
@@ -5477,7 +5529,10 @@ describe('Protocol V2 firmware update targets', () => {
 
     method.postTipMessage = jest.fn();
     method.postProgressMessage = jest.fn();
-    (method as any).protocolV2CommonUpdateProcess = jest.fn().mockResolvedValue(3);
+    (method as any).protocolV2SourceUpdateProcess = jest.fn().mockResolvedValue(3);
+    (method as any).enterProtocolV2BootloaderMode = jest.fn().mockResolvedValue(undefined);
+    (method as any).completeProtocolV2FinalVerification = jest.fn().mockResolvedValue({});
+    (method as any).verifyProtocolV2StagedFile = jest.fn().mockResolvedValue(undefined);
     (method as any).protocolV2StartFirmwareUpdate = jest.fn();
     (method as any).waitForProtocolV2FirmwareUpdateComplete = jest.fn();
 
@@ -5493,7 +5548,7 @@ describe('Protocol V2 firmware update targets', () => {
       fwBinaryMap: [],
     });
 
-    expect((method as any).protocolV2CommonUpdateProcess).toHaveBeenCalledTimes(1);
+    expect((method as any).protocolV2SourceUpdateProcess).toHaveBeenCalledTimes(1);
     expect((method as any).protocolV2StartFirmwareUpdate).not.toHaveBeenCalled();
     expect((method as any).waitForProtocolV2FirmwareUpdateComplete).not.toHaveBeenCalled();
   });
@@ -5524,12 +5579,19 @@ describe('Protocol V2 firmware update targets', () => {
     });
     method.postProgressMessage = jest.fn();
 
-    await (method as any).protocolV2CommonUpdateProcess({
-      payload: new Uint8Array(4097).buffer,
-      filePath: 'vol1:firmware.bin',
-      processedSize: 0,
-      totalSize: 4097,
+    const source = await openFirmwareByteSource({
+      binary: new Uint8Array(4097).buffer,
     });
+    try {
+      await (method as any).protocolV2SourceUpdateProcess({
+        source,
+        filePath: 'vol1:firmware.bin',
+        processedSize: 0,
+        totalSize: 4097,
+      });
+    } finally {
+      await source?.close();
+    }
 
     const writePayloads = typedCall.mock.calls.map(call => call[2]);
     expect(writePayloads.map(payload => payload.file.offset)).toEqual([0, 4000]);
@@ -5586,12 +5648,16 @@ describe('Protocol V2 firmware update targets', () => {
     method.postProgressMessage = jest.fn();
 
     try {
-      await (method as any).protocolV2CommonUpdateProcess({
-        payload: new Uint8Array(8001).buffer,
+      const source = await openFirmwareByteSource({
+        binary: new Uint8Array(8001).buffer,
+      });
+      await (method as any).protocolV2SourceUpdateProcess({
+        source,
         filePath: 'vol0:/firmware.bin',
         processedSize: 0,
         totalSize: 8001,
       });
+      await source?.close();
     } finally {
       setTimeoutSpy.mockRestore();
     }
@@ -5626,16 +5692,21 @@ describe('Protocol V2 firmware update targets', () => {
     });
     method.postProgressMessage = jest.fn();
     method.postTipMessage = jest.fn();
+    (method as any).recoverProtocolV2FileTransfer = jest.fn().mockResolvedValue(undefined);
 
+    const source = await openFirmwareByteSource({
+      binary: new Uint8Array(4097).buffer,
+    });
     await expect(
-      (method as any).protocolV2WriteWholeFile({
-        payload: new Uint8Array(4097).buffer,
+      (method as any).protocolV2SourceUpdateProcess({
+        source,
         filePath: 'vol0:/firmware.bin',
         processedSize: 0,
         totalSize: 4097,
       })
     ).rejects.toMatchObject({ errorCode: HardwareErrorCode.EmmcFileWriteFirmwareError });
-    expect(typedCall).toHaveBeenCalledTimes(2);
+    await source?.close();
+    expect(typedCall).toHaveBeenCalledTimes(6);
   });
 
   test('caps native BLE firmware upload chunks below the WebUSB limit', async () => {
@@ -5668,12 +5739,19 @@ describe('Protocol V2 firmware update targets', () => {
     });
     method.postProgressMessage = jest.fn();
 
-    await (method as any).protocolV2CommonUpdateProcess({
-      payload: new Uint8Array(1801).buffer,
-      filePath: 'vol1:ble-firmware.bin',
-      processedSize: 0,
-      totalSize: 1801,
+    const source = await openFirmwareByteSource({
+      binary: new Uint8Array(1801).buffer,
     });
+    try {
+      await (method as any).protocolV2SourceUpdateProcess({
+        source,
+        filePath: 'vol1:ble-firmware.bin',
+        processedSize: 0,
+        totalSize: 1801,
+      });
+    } finally {
+      await source?.close();
+    }
 
     const writePayloads = typedCall.mock.calls.map(call => call[2]);
     expect(writePayloads.map(payload => payload.file.offset)).toEqual([0, 1800]);
@@ -5790,9 +5868,9 @@ describe('Protocol V2 firmware update method', () => {
     const typedCall = jest
       .fn()
       .mockRejectedValue(
-        new DOMException(
-          "Failed to execute 'open' on 'USBDevice': The device was disconnected",
-          'NotFoundError'
+        Object.assign(
+          new Error("Failed to execute 'open' on 'USBDevice': The device was disconnected"),
+          { name: 'NotFoundError' }
         )
       );
 
@@ -5957,6 +6035,21 @@ describe('Protocol V2 firmware update method', () => {
 });
 
 describe('Protocol V2 firmware reconnect identity', () => {
+  test('keeps the host plan identity as the V4 reconnect anchor', () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+        platform: 'native',
+        expectedDeviceId: 'persisted-device-id',
+      },
+    });
+
+    method.init();
+
+    expect((method as any).params.expectedDeviceId).toBe('persisted-device-id');
+  });
+
   test('rejects a different physical serial before firmware transfer resumes', () => {
     expect(() => assertProtocolV2ReconnectIdentity('expected-serial', 'other-serial')).toThrow(
       'identity mismatch'
@@ -6193,230 +6286,311 @@ describe('Protocol V2 protected method execution', () => {
     expect(method.unlockPolicy).toBe('none');
   });
 
-  test('checks fresh status for a wallet business method without a name allowlist', async () => {
+  test('unlocks and retries an opted-in Protocol V2 method once', async () => {
     const calls: string[] = [];
-    const features = { unlocked: true };
     const method = {
-      name: 'confluxSignMessageCIP23',
-      unlockPolicy: 'none',
-      useDevicePassphraseState: true,
-      protocolV2UiInteraction: { reason: 'address-confirmation' },
-      run: jest.fn(() => {
-        calls.push('run');
-        return Promise.resolve({ address: '0x1' });
-      }),
+      name: 'testBusinessMethod',
+      unlockPolicy: 'retry-on-locked',
+      protocolV2UiInteraction: { reason: 'settings-page' },
+      run: jest
+        .fn()
+        .mockImplementationOnce(() => {
+          calls.push('run-1');
+          return Promise.reject(deviceLockedError());
+        })
+        .mockImplementationOnce(() => {
+          calls.push('run-2');
+          return Promise.resolve({ message: 'ok' });
+        }),
     };
     const device = {
-      features,
-      commands: {
-        typedCall: jest.fn(() => {
-          calls.push('status');
-          return Promise.resolve({ message: { unlocked: true } });
-        }),
-      },
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
-        features.unlocked = status.unlocked === true;
-        return features;
+      unlockDevice: jest.fn(() => {
+        calls.push('unlock');
+        return Promise.resolve();
       }),
-      unlockDevice: jest.fn(),
     };
     const uiCoordinator = {
       enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
-      enterUnlockInteraction: jest.fn(),
+      enterUnlockInteraction: jest.fn(() => calls.push('unlock-prompt')),
+      resumeMethodInteraction: jest.fn(() => calls.push('method-prompt')),
     };
 
     await expect(
-      runMethodWithUnlockPolicy(method as any, device as any, {
-        uiCoordinator: uiCoordinator as any,
-      })
-    ).resolves.toEqual({ address: '0x1' });
-
-    expect(calls).toEqual(['status', 'method-prompt', 'run']);
-    expect(device.commands.typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-    expect(method.run).toHaveBeenCalledTimes(1);
+      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
+    ).resolves.toEqual({ message: 'ok' });
+    expect(calls).toEqual([
+      'method-prompt',
+      'run-1',
+      'unlock-prompt',
+      'unlock',
+      'method-prompt',
+      'run-2',
+    ]);
   });
 
-  test('validates the fresh device identity before starting unlock', async () => {
+  test('restores the expected hidden-wallet session before retrying after unlock', async () => {
     const calls: string[] = [];
-    const identityError = new Error('Unexpected device');
     const method = {
       name: 'evmSignMessage',
-      unlockPolicy: 'none',
+      payload: { passphraseState: 'hidden-state' },
       useDevicePassphraseState: true,
-      run: jest.fn(),
+      unlockPolicy: 'retry-on-locked',
+      run: jest
+        .fn()
+        .mockImplementationOnce(() => {
+          calls.push('run-1');
+          return Promise.reject(deviceLockedError());
+        })
+        .mockImplementationOnce(() => {
+          calls.push('run-2');
+          return Promise.resolve({ message: 'ok' });
+        }),
     };
-    const features = { unlocked: false };
+    const typedCall = jest.fn((requestType: string, _responseType: string, request: any) => {
+      if (requestType === 'ProtocolInfoRequest') {
+        calls.push('negotiate-session');
+        return Promise.resolve({ message: { version: 2 } });
+      }
+      if (requestType === 'DeviceSessionGet') {
+        calls.push('resume-hidden-session');
+        expect(request).toEqual({ session_id: 'hidden-session' });
+        return Promise.resolve({
+          message: {
+            session_id: 'hidden-session',
+            btc_test_address: 'hidden-state',
+          },
+        });
+      }
+      throw new Error(`Unexpected request: ${requestType}`);
+    });
     const device = {
-      features,
-      commands: {
-        typedCall: jest.fn(() => {
-          calls.push('status');
-          return Promise.resolve({ message: { unlocked: false } });
-        }),
-      },
+      features: { unlocked: true, passphraseProtection: true },
+      passphraseState: 'hidden-state',
+      commands: { typedCall },
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn(() => features),
-      unlockDevice: jest.fn(),
+      unlockDevice: jest.fn(() => {
+        calls.push('unlock');
+        return Promise.resolve();
+      }),
+      getCurrentPassphraseProtection: () => true,
+      getInternalState: () => 'hidden-session',
+      clearInternalState: jest.fn(),
+      getCurrentDeviceId: () => 'wallet-device-id',
+      updateInternalState: jest.fn(() => calls.push('validate-hidden-session')),
     };
 
-    await expect(
-      runMethodWithUnlockPolicy(method as any, device as any, {
-        afterStatusBeforeUnlock: () => {
-          calls.push('identity');
-          throw identityError;
-        },
-      })
-    ).rejects.toBe(identityError);
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
+      message: 'ok',
+    });
+    expect(calls).toEqual([
+      'run-1',
+      'unlock',
+      'negotiate-session',
+      'resume-hidden-session',
+      'validate-hidden-session',
+      'run-2',
+    ]);
+  });
 
-    expect(calls).toEqual(['status', 'identity']);
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-    expect(method.run).not.toHaveBeenCalled();
+  test('does not replay a business method when the hidden-wallet session cannot be restored after unlock', async () => {
+    const initialError = deviceLockedError();
+    const restoreError = new Error('Invalid wallet session');
+    const method = {
+      name: 'evmSignMessage',
+      payload: { passphraseState: 'hidden-state' },
+      useDevicePassphraseState: true,
+      unlockPolicy: 'retry-on-locked',
+      run: jest.fn().mockRejectedValueOnce(initialError),
+    };
+    const typedCall = jest.fn((requestType: string) => {
+      if (requestType === 'ProtocolInfoRequest') {
+        return Promise.resolve({ message: { version: 2 } });
+      }
+      if (requestType === 'DeviceSessionGet') {
+        return Promise.reject(restoreError);
+      }
+      throw new Error(`Unexpected request: ${requestType}`);
+    });
+    const device = {
+      features: { unlocked: true, passphraseProtection: true },
+      passphraseState: 'hidden-state',
+      commands: { typedCall },
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
+      getCurrentPassphraseProtection: () => true,
+      getInternalState: () => 'hidden-session',
+      clearInternalState: jest.fn(),
+      getCurrentDeviceId: () => 'wallet-device-id',
+      updateInternalState: jest.fn(),
+    };
+
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(restoreError);
+    expect(method.run).toHaveBeenCalledTimes(1);
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(device.clearInternalState).toHaveBeenCalledTimes(1);
+    expect(device.updateInternalState).not.toHaveBeenCalled();
   });
 
-  test('unlocks before business and never replays the callback', async () => {
+  test('restores the expected hidden-wallet session after pre-unlock without selecting Attach PIN', async () => {
     const calls: string[] = [];
-    const features = { unlocked: true };
     const method = {
       name: 'evmSignMessage',
-      unlockPolicy: 'unlock-before-run',
-      protocolV2UiInteraction: { reason: 'signing-confirmation' },
+      payload: { passphraseState: 'hidden-state' },
+      useDevicePassphraseState: true,
+      unlockPolicy: 'retry-on-locked',
       run: jest.fn(() => {
         calls.push('run');
-        return Promise.resolve({ signature: 'signed' });
+        return Promise.resolve({ message: 'ok' });
       }),
     };
+    const typedCall = jest.fn((requestType: string, _responseType: string, request: any) => {
+      if (requestType === 'ProtocolInfoRequest') {
+        calls.push('negotiate-session');
+        return Promise.resolve({ message: { version: 2 } });
+      }
+      if (requestType === 'DeviceSessionGet') {
+        calls.push('resume-hidden-session');
+        expect(request).toEqual({ session_id: 'hidden-session' });
+        return Promise.resolve({
+          message: {
+            session_id: 'hidden-session',
+            btc_test_address: 'hidden-state',
+          },
+        });
+      }
+      throw new Error(`Unexpected request: ${requestType}`);
+    });
+    const features = {
+      unlocked: false,
+      unlockedAttachPin: true,
+      passphraseProtection: true,
+    };
     const device = {
       features,
-      commands: {
-        typedCall: jest.fn(() => {
-          calls.push('status');
-          return Promise.resolve({ message: { unlocked: false } });
-        }),
-      },
+      passphraseState: 'hidden-state',
+      commands: { typedCall },
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
-        features.unlocked = status.unlocked === true;
-        return features;
-      }),
       unlockDevice: jest.fn(() => {
-        calls.push('unlock');
+        calls.push('unlock-main');
         features.unlocked = true;
-        return Promise.resolve(features);
-      }),
-    };
-    const uiCoordinator = {
-      enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
-      enterUnlockInteraction: jest.fn(() => {
-        calls.push('unlock-prompt');
-        return undefined;
+        features.unlockedAttachPin = false;
+        return Promise.resolve();
       }),
+      getCurrentPassphraseProtection: () => true,
+      getInternalState: () => 'hidden-session',
+      clearInternalState: jest.fn(),
+      getCurrentDeviceId: () => 'wallet-device-id',
+      updateInternalState: jest.fn(() => calls.push('validate-hidden-session')),
     };
 
-    await expect(
-      runMethodWithUnlockPolicy(method as any, device as any, {
-        uiCoordinator: uiCoordinator as any,
-        prepare: () => {
-          calls.push('wallet-session');
-          return Promise.resolve();
-        },
-      })
-    ).resolves.toEqual({ signature: 'signed' });
-
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
+      message: 'ok',
+    });
+    expect(device.unlockDevice).toHaveBeenCalledWith();
     expect(calls).toEqual([
-      'status',
-      'unlock-prompt',
-      'unlock',
-      'wallet-session',
-      'method-prompt',
+      'unlock-main',
+      'negotiate-session',
+      'resume-hidden-session',
+      'validate-hidden-session',
       'run',
     ]);
-    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
-    expect(method.run).toHaveBeenCalledTimes(1);
   });
 
-  test('fails closed when fresh status does not explicitly report unlocked state', async () => {
+  test('does not restore a hidden-wallet session for a standard-wallet pre-unlock', async () => {
     const method = {
       name: 'evmGetAddress',
-      unlockPolicy: 'unlock-before-run',
-      run: jest.fn(),
+      payload: { useEmptyPassphrase: true },
+      useDevicePassphraseState: true,
+      unlockPolicy: 'retry-on-locked',
+      run: jest.fn().mockResolvedValue({ address: 'standard-wallet-address' }),
     };
     const device = {
-      features: { unlocked: undefined },
-      commands: { typedCall: jest.fn().mockResolvedValue({ message: {} }) },
+      features: { unlocked: false },
+      passphraseState: 'stale-hidden-state',
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn(() => ({ unlocked: undefined })),
-      unlockDevice: jest.fn(),
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
     };
 
-    await expect(runMethodWithUnlockPolicy(method as any, device as any)).rejects.toMatchObject({
-      errorCode: HardwareErrorCode.RuntimeError,
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
+      address: 'standard-wallet-address',
     });
-    expect(device.unlockDevice).not.toHaveBeenCalled();
-    expect(method.run).not.toHaveBeenCalled();
+    expect(device.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(method.run).toHaveBeenCalledTimes(1);
   });
 
-  test('returns a business DeviceLocked error without unlocking or replaying', async () => {
-    const error = deviceLockedError();
+  test('refreshes status and unlocks before a protected Protocol V2 method', async () => {
+    const calls: string[] = [];
     const method = {
-      name: 'evmSignMessage',
+      name: 'deviceSettingsPageShow',
       unlockPolicy: 'unlock-before-run',
-      run: jest.fn().mockRejectedValue(error),
+      protocolV2UiInteraction: { reason: 'settings-page' },
+      run: jest.fn(() => {
+        calls.push('run');
+        return Promise.resolve({ message: 'ok' });
+      }),
     };
     const features = { unlocked: true };
     const device = {
       features,
-      commands: { typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }) },
+      commands: {
+        typedCall: jest.fn(() => {
+          calls.push('refresh-status');
+          return Promise.resolve({ message: { unlocked: false } });
+        }),
+      },
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn(() => features),
-      unlockDevice: jest.fn(),
+      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
+        features.unlocked = status.unlocked ?? features.unlocked;
+        return features;
+      }),
+      unlockDevice: jest.fn(() => {
+        calls.push('unlock');
+        features.unlocked = true;
+        return Promise.resolve();
+      }),
+    };
+    const uiCoordinator = {
+      enterMethodInteraction: jest.fn(() => calls.push('method-prompt')),
+      enterUnlockInteraction: jest.fn(() => calls.push('unlock-prompt')),
+      resumeMethodInteraction: jest.fn(() => calls.push('method-prompt')),
     };
 
-    await expect(runMethodWithUnlockPolicy(method as any, device as any)).rejects.toBe(error);
-    expect(device.unlockDevice).not.toHaveBeenCalled();
+    await expect(
+      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
+    ).resolves.toEqual({ message: 'ok' });
+    expect(calls).toEqual(['refresh-status', 'unlock-prompt', 'unlock', 'method-prompt', 'run']);
+    expect(device.commands.typedCall).toHaveBeenCalledWith('DeviceStatusGet', 'DeviceStatus', {});
     expect(method.run).toHaveBeenCalledTimes(1);
+    expect(uiCoordinator.enterMethodInteraction).toHaveBeenCalledTimes(1);
+    expect(uiCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
   });
 
-  test('reuses one lightweight preflight context across nested protected methods', async () => {
-    const features = { unlocked: true };
-    const context = createProtocolV2UnlockContext();
-    const firstMethod = {
-      name: 'allNetworkGetAddress',
-      unlockPolicy: 'unlock-before-run',
-      run: jest.fn().mockResolvedValue({ root: true }),
-    };
-    const nestedMethod = {
-      name: 'evmGetAddress',
+  test('uses refreshed unlocked status instead of a stale locked cache', async () => {
+    const features = { unlocked: false };
+    const method = {
+      name: 'deviceSettings',
       unlockPolicy: 'unlock-before-run',
-      run: jest.fn().mockResolvedValue({ address: '0x1' }),
+      run: jest.fn().mockResolvedValue({ message: 'ok' }),
     };
     const device = {
       features,
-      commands: { typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }) },
+      commands: {
+        typedCall: jest.fn().mockResolvedValue({ message: { unlocked: true } }),
+      },
       isProtocolV2: () => true,
-      isBootloader: () => false,
-      isRomloader: () => false,
-      updateProtocolV2Status: jest.fn(() => features),
+      updateProtocolV2Status: jest.fn((status: { unlocked?: boolean }) => {
+        features.unlocked = status.unlocked ?? features.unlocked;
+        return features;
+      }),
       unlockDevice: jest.fn(),
     };
 
-    await runMethodWithUnlockPolicy(firstMethod as any, device as any, { context });
-    await runMethodWithUnlockPolicy(nestedMethod as any, device as any, { context });
-
-    expect(device.commands.typedCall).toHaveBeenCalledTimes(1);
-    expect(firstMethod.run).toHaveBeenCalledTimes(1);
-    expect(nestedMethod.run).toHaveBeenCalledTimes(1);
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
+      message: 'ok',
+    });
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(method.run).toHaveBeenCalledTimes(1);
   });
 
   test.each(['bootloader', 'romloader'] as const)(
@@ -6436,7 +6610,7 @@ describe('Protocol V2 protected method execution', () => {
         unlockDevice: jest.fn(),
       };
 
-      await expect(runMethodWithUnlockPolicy(method as any, device as any)).resolves.toEqual({
+      await expect(runMethodWithUnlockRetry(method as any, device as any)).resolves.toEqual({
         message: 'updating',
       });
       expect(device.commands.typedCall).not.toHaveBeenCalled();
@@ -6445,30 +6619,157 @@ describe('Protocol V2 protected method execution', () => {
     }
   );
 
-  test('keeps Protocol V1 and lock-free methods outside the preflight path', async () => {
+  test('infers a signing interaction before running a Protocol V2 business method', async () => {
+    const method = {
+      name: 'evmSignMessage',
+      params: { message: 'not-exposed-in-event' },
+      payload: {},
+      unlockPolicy: 'retry-on-locked',
+      run: jest.fn().mockResolvedValue({ signature: 'test' }),
+    };
+    const device = {
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn(),
+    };
+    const uiCoordinator = {
+      enterMethodInteraction: jest.fn(),
+      enterUnlockInteraction: jest.fn(),
+      resumeMethodInteraction: jest.fn(),
+    };
+
+    await runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any);
+
+    expect(uiCoordinator.enterMethodInteraction).toHaveBeenCalledWith({
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'signing-confirmation',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: 'evmSignMessage',
+    });
+  });
+
+  test('does not unlock a Protocol V1 device or a method without the policy', async () => {
     for (const [isProtocolV2, unlockPolicy] of [
-      [false, 'unlock-before-run'],
+      [false, 'retry-on-locked'],
       [true, 'none'],
     ] as const) {
+      const error = deviceLockedError();
       const method = {
         unlockPolicy,
-        useDevicePassphraseState: false,
-        run: jest.fn().mockResolvedValue({ message: 'ok' }),
+        run: jest.fn().mockRejectedValue(error),
       };
       const device = {
-        commands: { typedCall: jest.fn() },
         isProtocolV2: () => isProtocolV2,
         unlockDevice: jest.fn(),
       };
 
-      await expect(runMethodWithUnlockPolicy(method as any, device as any)).resolves.toEqual({
-        message: 'ok',
-      });
-      expect(device.commands.typedCall).not.toHaveBeenCalled();
+      await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(error);
       expect(device.unlockDevice).not.toHaveBeenCalled();
       expect(method.run).toHaveBeenCalledTimes(1);
     }
   });
+
+  test('runs lock-free eventless methods without unlocking or synthesized UI', async () => {
+    const method = {
+      name: 'uploadPortfolio',
+      unlockPolicy: 'none',
+      protocolV2UiMode: 'none',
+      run: jest.fn().mockResolvedValue({ message: 'ok' }),
+    };
+    const device = {
+      features: { unlocked: false },
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
+    };
+    const uiCoordinator = {
+      enterMethodInteraction: jest.fn(),
+      enterUnlockInteraction: jest.fn(),
+      resumeMethodInteraction: jest.fn(),
+    };
+
+    await expect(
+      runMethodWithUnlockRetry(method as any, device as any, uiCoordinator as any)
+    ).resolves.toEqual({ message: 'ok' });
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+    expect(uiCoordinator.enterMethodInteraction).not.toHaveBeenCalled();
+    expect(uiCoordinator.enterUnlockInteraction).not.toHaveBeenCalled();
+    expect(uiCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
+  });
+
+  test('does not unlock or replay a lock-free state-changing method after a locked response', async () => {
+    const error = deviceLockedError();
+    const method = {
+      name: 'uploadPortfolio',
+      unlockPolicy: 'none',
+      run: jest.fn().mockRejectedValue(error),
+    };
+    const device = {
+      features: { unlocked: true },
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn(),
+    };
+
+    await expect(runMethodWithUnlockRetry(method as any, device as any)).rejects.toBe(error);
+    expect(method.run).toHaveBeenCalledTimes(1);
+    expect(device.unlockDevice).not.toHaveBeenCalled();
+  });
+
+  test('does not retry when unlock fails or when the retry is still locked', async () => {
+    const initialError = deviceLockedError();
+    const unlockError = new Error('PIN cancelled');
+    const unlockFailMethod = {
+      unlockPolicy: 'retry-on-locked',
+      run: jest.fn().mockRejectedValue(initialError),
+    };
+    const unlockFailDevice = {
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn().mockRejectedValue(unlockError),
+    };
+    const unlockFailCoordinator = {
+      enterMethodInteraction: jest.fn(),
+      enterUnlockInteraction: jest.fn(),
+      resumeMethodInteraction: jest.fn(),
+    };
+
+    await expect(
+      runMethodWithUnlockRetry(
+        unlockFailMethod as any,
+        unlockFailDevice as any,
+        unlockFailCoordinator as any
+      )
+    ).rejects.toBe(unlockError);
+    expect(unlockFailMethod.run).toHaveBeenCalledTimes(1);
+    expect(unlockFailCoordinator.enterUnlockInteraction).toHaveBeenCalledTimes(1);
+    expect(unlockFailCoordinator.resumeMethodInteraction).not.toHaveBeenCalled();
+
+    const retryError = deviceLockedError();
+    const retryFailMethod = {
+      unlockPolicy: 'retry-on-locked',
+      run: jest.fn().mockRejectedValueOnce(initialError).mockRejectedValueOnce(retryError),
+    };
+    const retryFailDevice = {
+      isProtocolV2: () => true,
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
+    };
+    const retryFailCoordinator = {
+      enterMethodInteraction: jest.fn(),
+      enterUnlockInteraction: jest.fn(),
+      resumeMethodInteraction: jest.fn(),
+    };
+
+    await expect(
+      runMethodWithUnlockRetry(
+        retryFailMethod as any,
+        retryFailDevice as any,
+        retryFailCoordinator as any
+      )
+    ).rejects.toBe(retryError);
+    expect(retryFailMethod.run).toHaveBeenCalledTimes(2);
+    expect(retryFailDevice.unlockDevice).toHaveBeenCalledTimes(1);
+    expect(retryFailCoordinator.enterUnlockInteraction).toHaveBeenCalledTimes(1);
+    expect(retryFailCoordinator.resumeMethodInteraction).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('Protocol V2 current low-level methods', () => {
@@ -6600,9 +6901,7 @@ describe('Protocol V2 current low-level methods', () => {
 
     await method.run();
 
-    expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {
-      eventless_wallet_session: true,
-    });
+    expect(typedCall).toHaveBeenCalledWith('ProtocolInfoRequest', 'ProtocolInfo', {});
   });
 
   test('sends DeviceFactoryInfoSet and DeviceFactoryInfoGet', async () => {