@onekeyfe/hd-core 1.2.0-alpha.19 → 1.2.0-alpha.20

package/src/api/FirmwareUpdateV4.ts

@@ -22,11 +22,9 @@ import { DevicePool } from '../device/DevicePool';
 import {
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
   ProtocolV2FirmwareTargetType,
-  isProtocolV2LoaderDeviceInfo,
 } from '../protocols/protocol-v2';
 import { requestProtocolV2DeviceInfo } from '../protocols/protocol-v2/features';
 import {
-  PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
   getProtocolV2UnknownErrorText,
   isProtocolV2DeviceDisconnectedError,
 } from './protocol-v2/helpers';
@@ -46,6 +44,7 @@ const Log = getLogger(LoggerNames.Method);
 
 const SESSION_ERROR = 'session not found';
 const PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT = 60 * 1000;
+const PROTOCOL_V2_FINAL_RECONNECT_TIMEOUT = 2 * 60 * 1000;
 const PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT = 5 * 1000;
 const PROTOCOL_V2_START_UPDATE_TIMEOUT = 3 * 60 * 1000;
 const PROTOCOL_V2_INSTALL_TIMEOUT = 5 * 60 * 1000;
@@ -95,10 +94,7 @@ type ProtocolV2FirmwareUpdateStatusTarget = {
   path?: string;
 };
 
-type ProtocolV2FirmwareUpdateStartResponse =
-  | TypedResponseMessage<'Success'>
-  | TypedResponseMessage<'DeviceFirmwareUpdateStatus'>
-  | undefined;
+type ProtocolV2FirmwareUpdateStartResponse = TypedResponseMessage<'Success'>;
 
 type ProtocolV2TargetBinary = { fileName: string; binary: ArrayBuffer; targetId: number };
 type ProtocolV2InstallItem = ProtocolV2TargetBinary & {
@@ -115,12 +111,12 @@ type ProtocolV2FileTransferParams = PROTO.FirmwareUpload & {
   onTransferredBytes?: (transferredBytes: number) => void;
 };
 
-/** RESC bundle okpkg（FileWrite 直写模式），每个独立同步到 devicePath */
+/** RESC bundle okpkg written independently to devicePath through FileWrite. */
 type ProtocolV2ResourceBundleBinary = {
   name: string;
   binary: ArrayBuffer;
   devicePath: string;
-  /** 远端配置模式下的下载 URL（手动模式不填） */
+  /** Download URL for remote-config mode; omitted in manual mode. */
   url?: string;
   version?: IVersionArray;
   payloadHash?: string;
@@ -203,8 +199,8 @@ const PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID = new Map<number, FirmwareUpdateV4T
 const PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE =
   'FW_MGMT_TARGET_ROMLOADER is not accepted by the current Pro2 bootloader update request. Flash romloader with the loader-specific flow instead of firmwareUpdateV4.';
 
-// hd-transport 的历史 decode 行为会把单值 enum 输出为枚举名字符串；
-// Protocol V2 沿用这个 SDK 语义，内部比较前再映射回固件协议数值。
+// hd-transport historically decodes scalar enums as enum-name strings.
+// Map them back to firmware protocol values before internal comparisons.
 const PROTOCOL_V2_TARGET_ID_BY_DECODED_NAME = new Map<string, number>(
   Object.entries(ProtocolV2FirmwareTargetType).map(([key, value]) => [key, value])
 );
@@ -230,13 +226,12 @@ const isProtocolV2ReconnectProbeError = (error: unknown) => {
   );
 };
 
-const isProtocolV2StartUpdateTransientError = (error: unknown) => {
+const isProtocolV2FirmwareStatusEndpointUnavailable = (error: unknown) => {
   const message = getProtocolV2UnknownErrorText(error).toLowerCase();
   return (
-    isProtocolV2DeviceDisconnectedError(error) ||
-    isProtocolV2ReconnectProbeError(error) ||
-    message.includes('libusb_transfer_timed_out') ||
-    (message.includes('response timeout') && message.includes('devicefirmwareupdaterequest'))
+    message.includes('handler not registered') ||
+    message.includes('message handler not found') ||
+    message.includes('unsupported message')
   );
 };
 
@@ -403,6 +398,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   init() {
     this.allowDeviceMode = [UI_REQUEST.BOOTLOADER, UI_REQUEST.NOT_INITIALIZE];
     this.requireDeviceMode = [];
+    this.unlockPolicy = 'retry-on-locked';
     this.useDevicePassphraseState = false;
     this.skipForceUpdateCheck = true;
 
@@ -495,6 +491,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     let fwBinaryMap: ProtocolV2TargetBinary[] = [];
     let bootloaderBinary: ArrayBuffer | null = null;
     let installItems: ProtocolV2InstallItem[] | undefined;
+    let resourceBundles: ProtocolV2ResourceBundleBinary[] | undefined;
     try {
       this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
       fwBinaryMap = this.collectExplicitTargetBinaries();
@@ -508,13 +505,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         fwBinaryMap = remoteBinaries.fwBinaryMap;
         installItems = remoteBinaries.installItems;
       }
+      resourceBundles = this.prepareProtocolV2ResourceBundles(firmwareType, deviceFeatures);
+      if (resourceBundles?.length) {
+        resourceBundles = await this.prefetchProtocolV2ResourceBundles(resourceBundles);
+      }
       this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
     } catch (err) {
       throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
     }
 
-    const resourceBundles = this.prepareProtocolV2ResourceBundles(firmwareType, deviceFeatures);
-
     if (!bootloaderBinary && fwBinaryMap.length === 0 && !resourceBundles?.length) {
       throw ERRORS.TypedError(
         HardwareErrorCode.FirmwareUpdateDownloadFailed,
@@ -742,22 +741,22 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   // ============================================================
-  // RESC bundle 直写增量同步（FileRead 比对 + FilesystemFileWrite 直写）
+  // Incremental RESC bundle sync through FileRead and FilesystemFileWrite
   // ============================================================
 
   /**
-   * 准备 RESC bundle 列表。
+   * Prepare the RESC bundle list.
    *
-   * 两种模式（同 FirmwareUpdateV3 的 binary vs version 模式）：
-   * - 用户传了 resourceBundleFiles（binary 数组）：直接用，不做版本比对。
-   * - 用户没传：从远端 config.json 的 release.resourceBundles 拉取，
-   *   此时 syncProtocolV2ResourceBundles 会按需下载 + 比对设备已有 header 跳过。
+   * Two modes, matching FirmwareUpdateV3 binary-versus-version behavior:
+   * - resourceBundleFiles supplied: use binaries directly without version checks.
+   * - Otherwise load release.resourceBundles from remote config.json; the binaries
+   *   are prefetched before reboot and synchronization skips matching device headers.
    */
   private prepareProtocolV2ResourceBundles(
     firmwareType: EFirmwareType,
     features: Features
   ): ProtocolV2ResourceBundleBinary[] | undefined {
-    // 模式1：用户手动传入 binary，直接安装，不比对
+    // Manual binaries are installed directly without comparison.
     if (this.params.resourceBundleFiles?.length) {
       return this.params.resourceBundleFiles.map(file => ({
         name: file.devicePath.split('/').pop() ?? file.devicePath,
@@ -770,7 +769,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       return undefined;
     }
 
-    // 模式2：远端配置模式，后续按需下载 + 比对
+    // Remote-config bundles are downloaded and compared later.
     const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
     if (!release?.resourceBundles?.length) return undefined;
 
@@ -785,11 +784,32 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     })) as ProtocolV2ResourceBundleBinary[];
   }
 
+  private async prefetchProtocolV2ResourceBundles(
+    bundles: ProtocolV2ResourceBundleBinary[]
+  ): Promise<ProtocolV2ResourceBundleBinary[]> {
+    const prefetched: ProtocolV2ResourceBundleBinary[] = [];
+    for (const bundle of bundles) {
+      let { binary } = bundle;
+      if (binary.byteLength === 0) {
+        if (!bundle.url) {
+          throw new Error(`Missing Protocol V2 RESC bundle binary: ${bundle.name}`);
+        }
+        Log.log(`[FirmwareUpdateV4] downloading RESC bundle ${bundle.name} from ${bundle.url}`);
+        ({ binary } = await getSysResourceBinary(bundle.url));
+      }
+      if (binary.byteLength === 0) {
+        throw new Error(`Protocol V2 RESC bundle is empty: ${bundle.name}`);
+      }
+      prefetched.push({ ...bundle, binary });
+    }
+    return prefetched;
+  }
+
   /**
-   * 同步 RESC bundles 到设备。
+   * Synchronize RESC bundles to the device.
    *
-   * 手动传入模式（有 binary）：直接 FileWrite 直写，不比对。
-   * 远端配置模式（无 binary，有 url）：按需下载 + FileRead 比对跳过已更新的。
+   * Manual mode writes supplied binaries directly.
+   * Remote-config mode uses prefetched binaries and skips matching bundles after FileRead.
    */
   private async syncProtocolV2ResourceBundles(
     bundles: ProtocolV2ResourceBundleBinary[],
@@ -798,20 +818,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     const transferStartTime = Date.now();
     const transferTransport = this.getProtocolV2FirmwareTransferTransport();
 
-    const isManualMode = bundles.every(b => b.binary.byteLength > 0);
+    const isRemoteMode = bundles.some(bundle => !!bundle.url);
     let bundlesToSync = bundles;
 
-    // 远端配置模式：按需下载 + 比对跳过
-    if (!isManualMode) {
+    // Remote binaries were prefetched before bootloader entry. Only device-local
+    // header comparison and transfer are allowed in this phase.
+    if (isRemoteMode) {
       const filtered: ProtocolV2ResourceBundleBinary[] = [];
       for (const bundle of bundles) {
-        // 下载 binary
-        if (bundle.binary.byteLength === 0 && bundle.url) {
-          Log.log(`[FirmwareUpdateV4] downloading RESC bundle ${bundle.name} from ${bundle.url}`);
-          const { binary } = await getSysResourceBinary(bundle.url);
-          bundle.binary = binary;
-        }
-        // 比对设备上已有 header
+        // Compare the existing device header.
         const upToDate = await this.isProtocolV2ResourceBundleUpToDate(bundle);
         if (upToDate) {
           Log.log(`[FirmwareUpdateV4] skip RESC bundle ${bundle.name}; already up to date`);
@@ -827,7 +842,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       return { processedSize: 0, totalSize: firmwareSize };
     }
 
-    // FileWrite 直写到设备
+    // Write directly to the device through FileWrite.
     let totalSize = 0;
     for (const b of bundlesToSync) totalSize += b.binary.byteLength;
 
@@ -855,7 +870,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   /**
-   * 比对设备上已有 okpkg 的 OKPP header（仅远端配置模式使用）。
+   * Compare the existing okpkg OKPP header in remote-config mode.
    */
   private async isProtocolV2ResourceBundleUpToDate(
     bundle: ProtocolV2ResourceBundleBinary
@@ -894,8 +909,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   async enterProtocolV2BootloaderMode() {
-    // romloader 本身就是升级链路的首段执行环境，能够接收更新请求并把待处理目标交给 bootloader。
-    // 它不接受 DeviceRebootType.Bootloader，因此这里必须直接复用当前连接。
+    // romloader is the first update environment and forwards targets to bootloader.
+    // It rejects DeviceRebootType.Bootloader, so reuse the current connection.
     if (this.isProtocolV2BootloaderMode() || this.device.features?.mode === 'romloader') {
       Log.debug('Protocol V2 device is already in loader mode, skip reboot to bootloader');
       return false;
@@ -931,9 +946,9 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
           commands: this.device.getCommands(),
           timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
         });
-        // 重启进入 bootloader 后，旧的普通模式 DeviceStatus 已失效。
-        // 此阶段只以新的 DeviceInfo 为准，避免继续请求或复用 DeviceStatus。
-        const features = this.device.updateProtocolV2Features(deviceInfo, null);
+        // This is a reconnect probe after a Bootloader reboot. Bootloader does not
+        // support DeviceStatusGet, so the generic runtime-mode probe is invalid here.
+        const features = this.device.updateProtocolV2Features(deviceInfo, null, 'bootloader');
         assertProtocolV2ReconnectIdentity(
           this.protocolV2ExpectedDeviceId,
           features.deviceId ?? undefined,
@@ -959,8 +974,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   /**
-   * 收集按 DeviceFirmwareTargetType 拆分的显式目标二进制。
-   * 文件名仅用于 staging 路径展示，target_id 已显式给定。
+   * Collect explicit target binaries grouped by DeviceFirmwareTargetType.
+   * Filenames are display-only staging paths because target_id is explicit.
    */
   private collectExplicitTargetBinaries() {
     const entries: ProtocolV2TargetBinary[] = [];
@@ -1030,7 +1045,7 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       totalSize = resourceTransfer.totalSize;
     }
 
-    // 只有 RESC bundle、没有固件 target 时跳过 staging/install 阶段
+    // Skip staging and installation when the update contains RESC bundles only.
     if (orderedInstallItems.length === 0) {
       Log.log('[FirmwareUpdateV4] no firmware targets to install (RESC bundles only)');
       if (totalSize > 0) {
@@ -1100,8 +1115,8 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       path: item.path,
     }));
     Log.log(`[FirmwareUpdateV4] DeviceFirmwareUpdateRequest targets=${JSON.stringify(allTargets)}`);
-    const startResponse = await this.protocolV2StartFirmwareUpdate({ targets: allTargets });
-    await this.waitForProtocolV2FirmwareUpdateComplete(allTargets, startResponse);
+    await this.protocolV2StartFirmwareUpdate({ targets: allTargets });
+    await this.waitForProtocolV2FirmwareUpdateComplete(allTargets);
   }
 
   private getProtocolV2InstallItemStagingPath(item: ProtocolV2InstallItem) {
@@ -1121,98 +1136,117 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     }
   }
 
-  private isProtocolV2NormalModeFeatures(features?: Features | null) {
-    return !!features && !features.bootloaderMode && features.mode !== 'bootloader';
-  }
-
-  private async probeProtocolV2NormalMode() {
-    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    const deviceInfo = await requestProtocolV2DeviceInfo({
-      commands: this.device.getCommands(),
-      timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
-    });
-    if (isProtocolV2LoaderDeviceInfo(deviceInfo, null)) {
-      this.device.updateProtocolV2Features(deviceInfo, null);
-      return false;
-    }
-    const { message: deviceStatus } = await typedCall(
-      'DeviceStatusGet',
-      'DeviceStatus',
-      {},
-      { timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT }
-    );
-    const features = this.device.updateProtocolV2Features(deviceInfo, deviceStatus);
-    assertProtocolV2ReconnectIdentity(
-      this.protocolV2ExpectedDeviceId,
-      features.deviceId ?? undefined
-    );
-    if (this.isProtocolV2NormalModeFeatures(features)) {
-      Log.log('Protocol V2 firmware install finished; device is back in normal mode');
-      return true;
-    }
-    return false;
-  }
-
   private assertProtocolV2TargetStatus(
     statusTargets: ProtocolV2FirmwareUpdateStatusTarget[],
     expectedTargetIds: Set<number>
   ) {
+    Log.log(
+      `[FirmwareUpdateV4] DeviceFirmwareUpdateStatus records=${JSON.stringify(statusTargets)}`
+    );
     const failedTarget = statusTargets.find(
       target =>
         expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
         isProtocolV2TargetStatusFailed(target.status)
     );
     if (failedTarget) {
+      const failedTargetDetails = JSON.stringify({
+        targetId: failedTarget.target_id,
+        status: failedTarget.status,
+        payloadVersion: failedTarget.payload_version,
+        path: failedTarget.path,
+      });
+      Log.error(`[FirmwareUpdateV4] firmware install failed target=${failedTargetDetails}`);
       throw ERRORS.TypedError(
         HardwareErrorCode.FirmwareError,
-        `Protocol V2 firmware target ${failedTarget.target_id} failed`
+        `Protocol V2 firmware target failed: target=${failedTarget.target_id} status=${
+          failedTarget.status ?? 'unknown'
+        } payloadVersion=${failedTarget.payload_version ?? 'unknown'} path=${
+          failedTarget.path ?? 'unknown'
+        }`
       );
     }
 
-    const completedTargets = statusTargets.filter(
-      target =>
-        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
-        isProtocolV2TargetStatusFinished(target.status)
+    const matchingTargets = statusTargets.filter(target =>
+      expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1)
+    );
+    const completedTargets = matchingTargets.filter(target =>
+      isProtocolV2TargetStatusFinished(target.status)
     );
     if (completedTargets.length === expectedTargetIds.size && expectedTargetIds.size > 0) {
+      this.postProgressMessage(100, 'installingFirmware');
       return true;
     }
 
-    const inProgressTarget = statusTargets.find(
-      target =>
-        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
+    if (expectedTargetIds.size > 0 && matchingTargets.length > 0) {
+      const hasInProgressTarget = matchingTargets.some(target =>
         isProtocolV2TargetStatusInProgress(target.status)
-    );
-    if (inProgressTarget) {
-      this.postProgressMessage(99, 'installingFirmware');
+      );
+      const completedProgress = Math.floor(
+        (completedTargets.length / expectedTargetIds.size) * 100
+      );
+      // The protocol exposes no per-target percentage, so report coarse progress by
+      // completed targets and use 1% once work starts to keep the UI responsive.
+      const progress = Math.min(99, Math.max(completedProgress, hasInProgressTarget ? 1 : 0));
+      this.postProgressMessage(progress, 'installingFirmware');
     }
 
     return false;
   }
 
   private async waitForProtocolV2FirmwareUpdateComplete(
-    targets: Array<{ target_id: number; path: string }>,
-    startResponse?: ProtocolV2FirmwareUpdateStartResponse
+    targets: Array<{ target_id: number; path: string }>
   ) {
     const expectedTargetIds = new Set(targets.map(target => target.target_id));
-    if (startResponse?.type === 'DeviceFirmwareUpdateStatus') {
-      const statusTargets = (startResponse.message.records ??
-        []) as ProtocolV2FirmwareUpdateStatusTarget[];
-      // 仅消费安装请求自身返回的状态，用于尽早报告明确失败和安装中进度。
-      // 后续完成判定不再主动轮询 DeviceFirmwareUpdateStatusGet。
-      this.assertProtocolV2TargetStatus(statusTargets, expectedTargetIds);
-    }
-
     const startTime = Date.now();
     let lastError: unknown;
 
     while (Date.now() - startTime < PROTOCOL_V2_INSTALL_TIMEOUT) {
       try {
         await this.reconnectProtocolV2Device();
-        if (await this.probeProtocolV2NormalMode()) {
-          return;
+        try {
+          const statusResponse = await this.device.getCommands().typedCall(
+            'DeviceFirmwareUpdateStatusGet',
+            'DeviceFirmwareUpdateStatus',
+            {
+              fields: {
+                status: true,
+                payload_version: true,
+                path: true,
+              },
+            },
+            { timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT }
+          );
+          if (
+            this.assertProtocolV2TargetStatus(
+              (statusResponse.message.records ?? []) as ProtocolV2FirmwareUpdateStatusTarget[],
+              expectedTargetIds
+            )
+          ) {
+            return;
+          }
+          lastError = new Error('Protocol V2 firmware targets are still installing');
+        } catch (error) {
+          if (
+            error instanceof HardwareError &&
+            error.errorCode === HardwareErrorCode.FirmwareError
+          ) {
+            throw error;
+          }
+          // App firmware does not register DeviceFirmwareUpdateStatusGet. If the
+          // device already rebooted into App, this endpoint error signals that the
+          // install phase ended; the later phase performs the final readiness check.
+          if (isProtocolV2FirmwareStatusEndpointUnavailable(error)) {
+            Log.log(
+              '[FirmwareUpdateV4] firmware status endpoint unavailable after reboot; continue with normal-mode verification'
+            );
+            return;
+          }
+          lastError = error;
+          Log.log(
+            '[FirmwareUpdateV4] DeviceFirmwareUpdateStatusGet unavailable during install: ',
+            error
+          );
         }
-        lastError = new Error('Protocol V2 device is reachable but is not in normal mode');
       } catch (error) {
         lastError = error;
         if (error instanceof HardwareError && error.errorCode === HardwareErrorCode.FirmwareError) {
@@ -1230,22 +1264,15 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
   }
 
   private async exitProtocolV2BootloaderToNormal() {
-    this.postTipMessage(FirmwareUpdateTipMessage.SwitchFirmwareReconnectDevice);
-    try {
-      await this.reconnectProtocolV2Device();
-      if (await this.probeProtocolV2NormalMode()) {
-        Log.log('Protocol V2 device is already in normal mode, skip normal reboot');
-        return;
-      }
-    } catch (error) {
-      Log.log('Protocol V2 normal-mode probe before reboot failed: ', error);
-    }
+    await this.reconnectProtocolV2Device();
+    // The connection may still be in bootloader. Request a Normal reboot directly;
+    // repeating it after an automatic App reboot is idempotent.
     await this.protocolV2Reboot(DeviceRebootType.Normal);
   }
 
   private async waitForProtocolV2FinalFeatures() {
     const features = await this.waitForProtocolV2ReconnectAndFeatures(
-      PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT
+      PROTOCOL_V2_FINAL_RECONNECT_TIMEOUT
     );
 
     const bootloaderVersion = getDeviceBootloaderVersion(features).join('.');
@@ -1274,15 +1301,18 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         const deviceInfo = await requestProtocolV2DeviceInfo({
           commands: this.device.getCommands(),
           timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
-          // 更新完成判定只需要各 target 版本号；scope 与请求内容保持一致
+          // Completion needs target versions only; keep scope aligned with the request.
           request: PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
         });
-        const features = this.device.updateProtocolV2Features(deviceInfo);
+        const features = await this.device.probeProtocolV2RuntimeState(
+          deviceInfo,
+          PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT
+        );
         assertProtocolV2ReconnectIdentity(
           this.protocolV2ExpectedDeviceId,
           features.deviceId ?? undefined
         );
-        if (features.bootloaderMode || features.mode === 'bootloader') {
+        if (features.mode !== 'normal' || features.bootloaderMode) {
           throw ERRORS.TypedError(
             HardwareErrorCode.DeviceNotFound,
             'Protocol V2 device is still in bootloader mode'
@@ -1290,6 +1320,11 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         }
         return features;
       } catch (error) {
+        // A confirmed deviceId change is a firmware contract violation and cannot be
+        // fixed by polling. A temporarily missing identity may still become ready.
+        if (this.isProtocolV2ReconnectIdentityMismatch(error)) {
+          throw error;
+        }
         lastError = error;
         Log.log('Protocol V2 normal mode not ready, polling Ping: ', error);
         await wait(1000);
@@ -1324,19 +1359,21 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
         },
         true
       );
-      await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, { throwOnRunPromiseError: true });
+      await this.ensureProtocolV2DeviceAcquired();
       this.device.commands.disposed = false;
       this.device.getCommands().mainId = this.device.mainId ?? '';
       assertProtocolV2ReconnectIdentity(
         this.protocolV2ExpectedDeviceId,
         this.device.getCurrentDeviceId(),
-        { allowMissingActual: this.isProtocolV2BootloaderMode() }
+        // Cached identity may be absent immediately after acquire. Reject only an
+        // existing mismatch; the final refresh performs strict identity validation.
+        { allowMissingActual: true }
       );
       return;
     }
 
-    // App 与 bootloader 序列号暂时可能不一致。V4 升级重连阶段只接受唯一枚举设备，
-    // 避免继续按旧 app connectId 查缓存导致反复输出 path mismatch 日志。
+    // App and bootloader serials may differ temporarily. During V4 reconnect, accept
+    // only a uniquely enumerated device instead of repeatedly using the old App path.
     const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
       connectProtocol: PROTOCOL_V2_CONNECT_PROTOCOL,
     });
@@ -1349,16 +1386,36 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
       deviceList[0].getConnectId()
     );
     this.device.updateFromCache(deviceList[0]);
-    await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, { throwOnRunPromiseError: true });
+    await this.ensureProtocolV2DeviceAcquired();
     this.device.commands.disposed = false;
     this.device.getCommands().mainId = this.device.mainId ?? '';
     assertProtocolV2ReconnectIdentity(
       this.protocolV2ExpectedDeviceId,
       this.device.getCurrentDeviceId(),
-      { allowMissingActual: this.isProtocolV2BootloaderMode() }
+      // Cached identity may be absent immediately after acquire. Reject only an
+      // existing mismatch; the final refresh performs strict identity validation.
+      { allowMissingActual: true }
     );
   }
 
+  /**
+   * After acquiring a USB session, polling reuses its command channel. Reacquire only
+   * after reboot or enumeration changes cause hasDeviceAcquire() to become false.
+   */
+  private async ensureProtocolV2DeviceAcquired() {
+    const commands = this.device.getCommands();
+    if (this.device.hasDeviceAcquire() && !commands.disposed) {
+      return;
+    }
+    await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, {
+      throwOnRunPromiseError: true,
+    });
+  }
+
+  private isProtocolV2ReconnectIdentityMismatch(error: unknown) {
+    return this.normalizeErrorMessage(error).includes('Protocol V2 reconnect identity mismatch');
+  }
+
   private async protocolV2CommonUpdateProcess(params: ProtocolV2FileTransferParams) {
     let lastError: unknown;
     for (let attempt = 1; attempt <= PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT; attempt += 1) {
@@ -1505,35 +1562,16 @@ export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareU
     targets: Array<{ target_id: number; path: string }>;
   }) {
     const commands = this.device.getCommands();
-    let response: ProtocolV2FirmwareUpdateStartResponse;
-    try {
-      response = await commands.typedCall(
-        'DeviceFirmwareUpdateRequest',
-        PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
-        {
-          targets,
-        },
-        {
-          intermediateTypes: ['DeviceFirmwareUpdateStatus'],
-          timeoutMs: PROTOCOL_V2_START_UPDATE_TIMEOUT,
-          onIntermediateResponse: (response: { type?: string }) => {
-            if (response.type === 'DeviceFirmwareUpdateStatus') {
-              this.postProgressMessage(99, 'installingFirmware');
-            }
-          },
-        }
-      );
-    } catch (error) {
-      if (isProtocolV2StartUpdateTransientError(error)) {
-        Log.log(
-          'Protocol V2 firmware update request did not return; continue status polling',
-          error
-        );
-      } else {
-        throw error;
-      }
-    }
+    const response: ProtocolV2FirmwareUpdateStartResponse = await commands.typedCall(
+      'DeviceFirmwareUpdateRequest',
+      'Success',
+      { targets },
+      { timeoutMs: PROTOCOL_V2_START_UPDATE_TIMEOUT }
+    );
+    // Success acknowledges that the device accepted installation. End confirmation
+    // and begin status polling only after receiving this ACK.
     this.postTipMessage(FirmwareUpdateTipMessage.FirmwareUpdating);
+    this.postProgressMessage(0, 'installingFirmware');
     return response;
   }
 

package/src/api/GetPassphraseState.ts

@@ -1,4 +1,4 @@
-import { EDeviceType } from '@onekeyfe/hd-shared';
+import { ERRORS, HardwareErrorCode, createDeviceNotSupportMethodError } from '@onekeyfe/hd-shared';
 
 import { UI_REQUEST } from '../constants/ui-request';
 import { getPassphraseStateWithRefreshDeviceInfo } from '../utils/deviceFeaturesUtils';
@@ -11,23 +11,17 @@ export default class GetPassphraseState extends BaseMethod {
   }
 
   async run() {
-    const { passphraseState } = await getPassphraseStateWithRefreshDeviceInfo(this.device, {
-      expectPassphraseState: this.payload.passphraseState,
-      onlyMainPin: this.payload.useEmptyPassphrase,
-      initSession: this.payload.initSession,
-    });
+    if (this.device.isProtocolV2()) {
+      throw createDeviceNotSupportMethodError(this.name, this.device.getCurrentFirmwareType());
+    }
+    if (!this.device.features) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed);
+    }
 
-    const passphraseProtection = this.device.getCurrentPassphraseProtection();
-    const deviceType = this.device.getCurrentDeviceType();
+    const { passphraseState } = await getPassphraseStateWithRefreshDeviceInfo(this.device);
 
-    if (deviceType === EDeviceType.Pro2) {
-      // Protocol V2 的钱包身份由 DeviceSession 返回的 btc_test_address 决定，
-      // 不依赖固件 passphrase_enabled 状态。
-      return Promise.resolve(passphraseState);
-    }
+    const passphraseProtection = this.device.getCurrentPassphraseProtection();
 
-    return Promise.resolve(
-      deviceType === EDeviceType.Pro || passphraseProtection === true ? passphraseState : undefined
-    );
+    return Promise.resolve(passphraseProtection === true ? passphraseState : undefined);
   }
 }