@onekeyfe/hd-core 1.2.0-alpha.14 → 1.2.0-alpha.141

package/src/device/Device.ts

@@ -1,8 +1,9 @@
 import EventEmitter from 'events';
 import semver from 'semver';
-import { Enum_Capability } from '@onekeyfe/hd-transport';
+import { DeviceRebootType, DeviceSessionPinType, Enum_Capability } from '@onekeyfe/hd-transport';
 import {
   EDeviceType,
+  EFirmwareType,
   ERRORS,
   ERROR_CODES_REQUIRE_DISCONNECT,
   ERROR_CODES_REQUIRE_RELEASE,
@@ -12,30 +13,33 @@ import {
   createDeviceNotSupportMethodError,
 } from '@onekeyfe/hd-shared';
 
-import {
-  LoggerNames,
-  getDeviceBLEFirmwareVersion,
-  getDeviceBleName,
-  getDeviceFirmwareVersion,
-  getDeviceLabel,
-  getDeviceType,
-  getDeviceUUID,
-  getFirmwareType,
-  getLogger,
-} from '../utils';
+import { LoggerNames, getLogger } from '../utils';
 import {
   fixFeaturesFirmwareVersion,
   getPassphraseStateWithRefreshDeviceInfo,
-  supportInputPinOnSoftware,
-  supportModifyHomescreen,
 } from '../utils/deviceFeaturesUtils';
+import { parseDeviceVersion } from '../utils/deviceVersionUtils';
 import { generateInstanceId } from '../utils/tracing';
 // eslint-disable-next-line import/no-cycle
 import { DeviceCommands } from './DeviceCommands';
+import { mergeDeviceFeaturesPatch } from './DeviceFeaturesState';
+import {
+  mapDeviceSettingsToState,
+  mapFeaturesToState,
+  mapProtocolV1OnekeyFeaturesToState,
+  mapProtocolV2DeviceInfoToState,
+  mapProtocolV2DeviceStatusToState,
+} from './DeviceStateMapper';
+import { projectFeatures } from './DeviceStateProjector';
+import { DeviceStateStore, createPublicDeviceState } from './DeviceStateStore';
+import { cloneDeviceState } from './cloneDeviceState';
 import { deviceWalletSessionStore } from './DeviceWalletSessionStore';
 import {
   type DeviceFirmwareRange,
   DeviceModelToTypes,
+  type DeviceStateEvent,
+  type DeviceStatePatch,
+  type DeviceStateUpdateSource,
   DeviceTypeToModels,
   type Device as DeviceTyped,
   EOneKeyDeviceMode,
@@ -50,24 +54,37 @@ import { DEVICE, UI_REQUEST } from '../events';
 import { DataManager } from '../data-manager';
 import TransportManager from '../data-manager/TransportManager';
 import { toHardened } from '../api/helpers/pathUtils';
-import { existCapability } from '../utils/capabilitieUtils';
 import {
-  PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE,
+  PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  type ProtocolV2RuntimeMode,
+  getProtocolV2RuntimeMode,
+  isLegacyProtocolV2ProtocolInfo,
   requestProtocolV2DeviceInfo,
+  requestProtocolV2DeviceStatus,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from '../protocols/protocol-v2/features';
-import { buildProtocolV1FeaturesPayload, buildProtocolV2FeaturesPayload } from '../deviceProfile';
+import { buildProtocolV1FeaturesPayload } from '../deviceProfile';
+import { resolveProtocolV2DeviceIdentity } from '../deviceProfile/protocolV2DeviceIdentity';
 
 import type { PROTO } from '../constants';
+import type { DeviceStateReadOptions } from '../types/api/getDeviceState';
 import type {
   DeviceButtonRequestPayload,
   DeviceFeaturesPayload,
+  HardwareUiInteractionMeta,
   PassphraseRequestPayload,
+  ProtocolV2UiEventMetadata,
 } from '../events';
 import type { PassphrasePromptResponse } from './DeviceCommands';
 import type { Deferred, HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 import type {
   OneKeyDeviceInfo as DeviceDescriptor,
   DeviceStatus,
+  ProtocolInfo,
   ProtocolV2DeviceInfo,
   Success,
 } from '@onekeyfe/hd-transport';
@@ -79,7 +96,15 @@ export type InitOptions = {
   passphraseState?: string;
   deriveCardano?: boolean;
   connectProtocol?: HardwareConnectProtocol;
+  forceProtocolDetection?: boolean;
   protocolV2DeviceInfoTimeoutMs?: number;
+  /** Refresh Protocol V2 runtime state before returning discovery results. */
+  refreshRuntimeState?: boolean;
+  /**
+   * Protocol V1 Initialize response timeout override. Reboot-wait polling passes a
+   * short value so an unanswered probe settles before the next poll tick.
+   */
+  timeoutMs?: number;
 };
 
 export type RunOptions = {
@@ -94,11 +119,35 @@ const parseRunOptions = (options?: RunOptions): RunOptions => {
 
 const Log = getLogger(LoggerNames.Device);
 
+const isProtocolV2DeviceStatusUnsupportedError = (error: unknown) => {
+  if (error instanceof HardwareError) {
+    if (error.errorCode === HardwareErrorCode.DeviceNotSupportMethod) {
+      return true;
+    }
+    if (error.params?.failureCode === 'Failure_UnexpectedMessage') {
+      return true;
+    }
+  }
+
+  const message =
+    error instanceof Error
+      ? error.message
+      : String((error as { message?: unknown } | null)?.message ?? error ?? '');
+  return (
+    /^Failure_UnexpectedMessage(?:,|\b)/i.test(message) ||
+    /\b(?:unsupported message|handler not registered|message handler not found)\b/i.test(message)
+  );
+};
+
 export interface DeviceEvents {
   [DEVICE.PIN]: [Device, PROTO.PinMatrixRequestType | undefined, (err: any, pin: string) => void];
-  [DEVICE.PASSPHRASE_ON_DEVICE]: [Device, ((response: any) => void)?];
+  [DEVICE.PIN_ON_DEVICE]: [Device, DeviceSessionPinType, ProtocolV2UiEventMetadata?];
+  [DEVICE.PIN_ON_DEVICE_COMPLETE]: [Device, HardwareUiInteractionMeta];
+  [DEVICE.PASSPHRASE_ON_DEVICE]: [Device, PassphraseRequestPayload?];
+  [DEVICE.ATTACH_PIN_ON_DEVICE]: [Device, PassphraseRequestPayload?];
   [DEVICE.BUTTON]: [Device, DeviceButtonRequestPayload];
   [DEVICE.FEATURES]: [Device, DeviceFeaturesPayload];
+  [DEVICE.STATE]: [Device, DeviceStateEvent];
   [DEVICE.PASSPHRASE]: [
     Device,
     PassphraseRequestPayload,
@@ -128,7 +177,8 @@ export interface Device {
  * This allows short-lived processes (e.g. CLI) to restore a previously
  * obtained session, avoiding the need to re-enter passphrase on every
  * invocation. The session must have been obtained from a prior
- * getPassphraseState() call on the same device.
+ * wallet-session call on the same device. This compatibility hook is intended
+ * for a trusted CLI process restoring its own OS-keychain entry.
  *
  * @param deviceId - The device's device_id (from features)
  * @param passphraseState - The passphrase state token
@@ -185,25 +235,58 @@ export class Device extends EventEmitter {
    */
   private deviceAcquired = false;
 
-  /**
-   * 唯一设备状态缓存。
-   *
-   * V1 直接保存原生 Features；V2 保存由 DeviceInfoGet 映射出的
-   * Features 视图。Device 不再保存 profile，结构化 DeviceProfile 只作为
-   * getDeviceInfo() 的 API 返回值存在。
-   */
-  features: Features | undefined = undefined;
+  /** Canonical device-state cache; legacy Features is a compatibility projection. */
+  private stateStore = new DeviceStateStore();
 
-  /**
-   * 是否需要更新设备信息。
-   *
-   * 历史名称保留用于兼容现有调用语义；对 V2 表示 features 需要由
-   * DeviceInfoGet 刷新。
-   */
-  featuresNeedsReload = false;
+  /** Force the next initialization to reload DeviceInfo after reconnect or reboot. */
+  private protocolV2StateNeedsReload = false;
+
+  /** Runtime context negotiated once per active Protocol V2 link. */
+  private protocolV2RuntimeContext?: ProtocolInfo;
+
+  /** Coalesces concurrent first-use runtime negotiation on the same active link. */
+  private protocolV2RuntimeContextPromise?: Promise<ProtocolInfo>;
+
+  /** Invalidates an in-flight runtime-context response without adding a transport epoch. */
+  private protocolV2RuntimeContextRequestToken?: object;
+
+  private protocolV2UiInteraction?: {
+    interactionId: string;
+    phaseCounter: number;
+    sequence: number;
+    opened: boolean;
+  };
+
+  private protocolV2UiInteractionCounter = 0;
+
+  get state() {
+    return this.stateStore.getState();
+  }
+
+  get features(): Features | undefined {
+    if (!this.state) return undefined;
+    return projectFeatures(this.state);
+  }
+
+  set features(features: Features | undefined) {
+    this.stateStore = new DeviceStateStore();
+    if (features) {
+      this.stateStore.update(mapFeaturesToState(features), 'compatibility');
+      const { passphraseState } = features;
+      const sessionId = features.sessionId ?? features.session_id;
+      const deviceKey = this.getSessionCacheDeviceKey(features.deviceId ?? undefined);
+      if (passphraseState && sessionId && deviceKey) {
+        this.passphraseState = passphraseState;
+        deviceWalletSessionStore.set(deviceKey, passphraseState, sessionId);
+      }
+    }
+  }
 
   runPromise?: Deferred<void> | null;
 
+  /** Resolves only after the active run has completed its release path. */
+  private runCleanupPromise?: Promise<void>;
+
   externalState: string[] = [];
 
   unavailableCapabilities: UnavailableCapabilities = {};
@@ -254,38 +337,46 @@ export class Device extends EventEmitter {
 
   // simplified object to pass via postMessage
   toMessageObject(): DeviceTyped | null {
-    if (this.isUnacquired()) return null;
+    if (this.isUnacquired() || !this.features) return null;
 
     const env = DataManager.getSettings('env');
     const deviceType = this.getCurrentDeviceType();
 
     const bleName = this.getCurrentBleName();
-    const label = this.getCurrentLabel();
+    const displayName = this.getCurrentDisplayName();
     const serialNo = this.getCurrentSerialNo();
     const connectId = this.getConnectId();
     const deviceId = this.getCurrentDeviceId() || null;
 
     const { features } = this;
+    const state = this.state ? createPublicDeviceState(this.state) : undefined;
 
     return {
-      /** Android uses Mac address, iOS uses uuid, USB uses uuid  */
+      /** Android uses a MAC address, while iOS and USB use transport-specific identifiers. */
       connectId: DataManager.isBleConnect(env) ? this.mainId || null : connectId,
-      /** Hardware ID, will not change at any time */
+      /** Persist this after the first active probe so later calls do not need to guess. */
+      connectProtocol: this.originalDescriptor.protocolType,
+      /** Stable physical-device identity. */
+      serialNo,
+      /** @deprecated Use serialNo instead. */
       uuid: serialNo,
       commType: this.originalDescriptor.commType,
       sdkInstanceId: this.sdkInstanceId,
       instanceId: this.instanceId,
       createdAt: this.createdAt,
       deviceType,
-      /** ID for current seeds, will clear after replace a new seed at device */
+      /** Wallet-lifecycle ID; changes after the device is wiped or reinitialized. */
       deviceId,
       path: this.originalDescriptor?.path,
       bleName,
-      name: bleName || label || `OneKey ${deviceType?.toUpperCase()}`,
-      label: label || 'OneKey',
+      name: bleName || displayName || `OneKey ${deviceType?.toUpperCase()}`,
+      // Keep the legacy top-level field string-compatible while preserving
+      // the canonical nullable value at state.identity.label.
+      label: displayName ?? '',
+      status: this.getStatus(),
       mode: this.getMode(),
       features,
-      sessionId: this.features?.sessionId ?? null,
+      state,
       firmwareVersion: this.getFirmwareVersion(),
       bleFirmwareVersion: this.getBLEFirmwareVersion(),
       unavailableCapabilities: this.unavailableCapabilities,
@@ -296,13 +387,20 @@ export class Device extends EventEmitter {
    * Device connect
    * @returns {Promise<boolean>}
    */
-  connect(connectProtocol?: HardwareConnectProtocol) {
+  connect(
+    connectProtocol?: HardwareConnectProtocol,
+    options?: { forceProtocolDetection?: boolean }
+  ) {
     const env = DataManager.getSettings('env');
     // eslint-disable-next-line no-async-promise-executor
     return new Promise<boolean>(async (resolve, reject) => {
       if (DataManager.isBleConnect(env)) {
+        if (this.hasDeviceAcquire() && this.commands && !this.commands.disposed) {
+          resolve(true);
+          return;
+        }
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -312,7 +410,7 @@ export class Device extends EventEmitter {
       // 不存在 Session ID 或存在 Session ID 但设备在别处使用，都需要 acquire 获取最新 sessionID
       if (!this.mainId || (!this.isUsedHere() && this.originalDescriptor)) {
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -328,25 +426,31 @@ export class Device extends EventEmitter {
   }
 
   async acquire(
-    connectProtocol?: HardwareConnectProtocol,
-    options?: { throwOnRunPromiseError?: boolean }
+    expectedProtocol?: HardwareConnectProtocol,
+    options?: { throwOnRunPromiseError?: boolean; forceProtocolDetection?: boolean }
   ) {
     const env = DataManager.getSettings('env');
     const mainIdKey = DataManager.isBleConnect(env) ? 'id' : 'session';
-    const expectedProtocol = connectProtocol ?? this.originalDescriptor.protocolType;
+    const previousProtocol = this.originalDescriptor.protocolType;
+    // A protocol stored after a successful probe is authoritative. Only the explicit
+    // first-connection/recovery path may bypass it and probe both protocols again.
+    const strictProtocol = options?.forceProtocolDetection
+      ? undefined
+      : expectedProtocol ?? this.originalDescriptor.protocolType;
     try {
       let acquireResult: unknown;
       if (DataManager.isBleConnect(env)) {
-        // forceCleanRunPromise=true（自 e21b83c6 引入，修复 Pro2 BLE 重连）：
-        // acquire 意味着开启一个全新会话，transport 里残留的上一次 runPromise
-        // 必然属于已死亡的会话（如固件升级重启、探测中断），不清理会让新会话的
-        // 调用被旧 promise 卡死。无法在 Device 层面区分“重连恢复”与普通 acquire，
-        // 因此对 BLE acquire 恒清理是有意为之。
+        // acquire starts a new BLE session. Any previous runPromise belongs to a dead
+        // session, such as an interrupted probe or firmware-update reboot, and would
+        // otherwise block the new session. Device cannot distinguish recovery from a
+        // regular acquire, so BLE always clears it intentionally.
         acquireResult = await this.deviceConnector?.acquire(
           this.originalDescriptor.id,
           undefined,
           true,
-          expectedProtocol
+          strictProtocol,
+          undefined,
+          options?.forceProtocolDetection
         );
         this.mainId = (acquireResult as any)?.uuid ?? '';
         Log.debug('Expected uuid:', this.mainId);
@@ -355,30 +459,59 @@ export class Device extends EventEmitter {
           this.originalDescriptor.path,
           this.originalDescriptor.session,
           undefined,
-          expectedProtocol
+          strictProtocol,
+          undefined,
+          options?.forceProtocolDetection
         );
         this.mainId = acquireResult as string | undefined;
         Log.debug('Expected session id:', this.mainId);
       }
-      this.deviceAcquired = true;
-      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
-
       // Propagate protocol version detected during acquire.
       const detectedProtocol =
         (acquireResult as { protocolType?: HardwareConnectProtocol } | undefined)?.protocolType ??
         TransportManager.transport?.getProtocolType?.(
           DataManager.isBleConnect(env) ? this.originalDescriptor.id : this.originalDescriptor.path
         );
+      if (options?.forceProtocolDetection && !detectedProtocol) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `Active protocol detection returned no protocol for ${
+            this.originalDescriptor.path || this.originalDescriptor.id
+          }`
+        );
+      }
       if (detectedProtocol) {
         this.originalDescriptor.protocolType = detectedProtocol;
       }
+      this.deviceAcquired = true;
+      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
 
       if (this.commands) {
         await this.commands.dispose(false);
       }
 
       this.commands = new DeviceCommands(this, this.mainId ?? '');
+      // Protocol V2 runtime metadata belongs to one active transport link. A
+      // successful acquire creates a fresh link/session, so never carry cached
+      // ProtocolInfo or pre-initialize state across that boundary.
+      this.invalidateProtocolV2RuntimeState();
     } catch (error) {
+      if (options?.forceProtocolDetection) {
+        this.originalDescriptor.protocolType = previousProtocol;
+        const failedSession = this.mainId;
+        this.deviceAcquired = false;
+        if (failedSession) {
+          try {
+            await this.deviceConnector?.release?.(failedSession, false);
+          } catch (releaseError) {
+            Log.debug('Failed to release an unsuccessful protocol probe', releaseError);
+          }
+        }
+        if (!DataManager.isBleConnect(env)) {
+          this.mainId = null;
+          this.updateDescriptor({ session: null } as DeviceDescriptor);
+        }
+      }
       if (options?.throwOnRunPromiseError) {
         throw error;
       }
@@ -420,7 +553,8 @@ export class Device extends EventEmitter {
         }
       }
       try {
-        await this.deviceConnector?.release(this.mainId, false);
+        // BLE releases even when keepSession is set, so forward the intent.
+        await this.deviceConnector?.release(this.mainId, false, this.keepSession);
         this.updateDescriptor({ session: null } as DeviceDescriptor);
       } catch (err) {
         Log.error('[Device] release error: ', err);
@@ -482,12 +616,11 @@ export class Device extends EventEmitter {
   }
 
   /**
-   * 唯一协议判别器。
+   * Canonical protocol discriminator.
    *
-   * descriptor.protocolType 是协议探测后的结果；V2 features 由 DeviceInfoGet
-   * 映射产生。
-   * 全 SDK 的协议分支都必须走这里，不要直接读 originalDescriptor.protocolType
-   * 或从 features 反推。
+   * descriptor.protocolType is established by active probing; V2 features are mapped
+   * from DeviceInfoGet. All protocol branches must use this method instead of reading
+   * originalDescriptor.protocolType directly or inferring a protocol from features.
    */
   getProtocol(): 'V1' | 'V2' {
     return this.originalDescriptor.protocolType === 'V2' ? 'V2' : 'V1';
@@ -498,53 +631,75 @@ export class Device extends EventEmitter {
   }
 
   getCurrentDeviceType() {
-    return getDeviceType(this.features);
+    return this.state?.identity.deviceType ?? EDeviceType.Unknown;
   }
 
   getCurrentDeviceId() {
-    return this.features?.deviceId || undefined;
+    return this.state?.identity.deviceId || undefined;
   }
 
   getCurrentSerialNo() {
-    return this.features ? getDeviceUUID(this.features) : '';
+    return this.state?.identity.serialNo ?? '';
   }
 
   getConnectId() {
     const serialNo = this.getCurrentSerialNo();
     if (serialNo) return serialNo;
 
-    // connectId 是 SDK 内部连接路由 key。这里兜底到 transport descriptor，
-    // 不改变 features.serialNo / deviceId 的业务语义。
+    // connectId is an internal routing key. Falling back to the transport descriptor
+    // does not change the business meaning of features.serialNo or deviceId.
     return this.originalDescriptor.path || this.originalDescriptor.id || '';
   }
 
   getCurrentBleName() {
-    return getDeviceBleName(this.features);
+    return this.state?.identity.bleName ?? null;
   }
 
   getCurrentLabel() {
-    return getDeviceLabel(this.features);
+    return this.state?.identity.label ?? null;
+  }
+
+  getCurrentDisplayName() {
+    if (!this.state) return null;
+
+    const label = this.getCurrentLabel();
+    if (label) return label;
+
+    const bleName = this.getCurrentBleName();
+    if (bleName) return bleName;
+
+    const deviceType = this.getCurrentDeviceType();
+    if (deviceType === EDeviceType.ClassicPure) {
+      return 'OneKey Classic 1S';
+    }
+
+    return `OneKey ${deviceType.charAt(0).toUpperCase() + deviceType.slice(1)}`;
   }
 
   getCurrentPassphraseProtection() {
-    return this.features?.passphraseProtection;
+    return this.state?.status.passphraseProtection;
   }
 
   getCurrentFirmwareType() {
-    return getFirmwareType(this.features);
+    return this.state?.identity.firmwareType ?? EFirmwareType.Universal;
   }
 
   getCurrentFirmwareVersionString() {
-    return getDeviceFirmwareVersion(this.features)?.join('.');
+    return parseDeviceVersion(this.state?.versions.firmware).join('.');
   }
 
   getCurrentBLEFirmwareVersionString() {
-    if (!this.features) return undefined;
-    return getDeviceBLEFirmwareVersion(this.features).join('.');
+    if (!this.state) return undefined;
+    return parseDeviceVersion(this.state.versions.ble).join('.');
+  }
+
+  getCurrentBootloaderVersionString() {
+    if (!this.state) return undefined;
+    return parseDeviceVersion(this.state.versions.bootloader).join('.');
   }
 
   getCurrentSafetyChecks() {
-    return this.features?.safetyChecks;
+    return this.state?.settings.safetyChecks;
   }
 
   getCurrentMethodVersionRange(
@@ -557,6 +712,7 @@ export class Device extends EventEmitter {
     // Most-specific model first; must match getMethodVersionRange in deviceInfoUtils,
     // otherwise e.g. Classic1s resolves the looser model_mini range before model_classic1s.
     const modelFallbacks: IDeviceModel[] = [
+      'model_pro2',
       'model_classic1s',
       'model_classic',
       'model_mini',
@@ -576,7 +732,8 @@ export class Device extends EventEmitter {
     if (
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo
     ) {
       return { support: true };
     }
@@ -589,13 +746,12 @@ export class Device extends EventEmitter {
   }
 
   supportInputPinOnSoftware(): SupportFeatureType {
-    if (this.features) return supportInputPinOnSoftware(this.features);
-
     const deviceType = this.getCurrentDeviceType();
     if (
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo
     ) {
       return { support: false };
     }
@@ -608,15 +764,12 @@ export class Device extends EventEmitter {
   }
 
   supportModifyHomescreen(): SupportFeatureType {
-    // Pro2 走独立 1.x 版本线，不能套用 Touch/Pro 的 3.4.0 门槛（恒 false 且未来会误判）。
-    // 依据：firmware-pro2 协议 schema（messages-protocol-v2.json）的 ApplySettings
-    // 包含 homescreen 字段，V2 固件从首个版本即支持修改主屏。
+    // Pro2 has an independent 1.x version line and must not use the Touch/Pro 3.4.0
+    // threshold. ApplySettings includes homescreen from the first V2 firmware version.
     if (this.isProtocolV2()) {
       return { support: true };
     }
 
-    if (this.features) return supportModifyHomescreen(this.features);
-
     const deviceType = this.getCurrentDeviceType();
     if (DeviceModelToTypes.model_mini.includes(deviceType)) {
       return { support: true };
@@ -632,17 +785,25 @@ export class Device extends EventEmitter {
     const deviceId = _deviceId || this.getCurrentDeviceId();
     if (deviceId) return deviceId;
     if (this.isProtocolV2()) {
-      return this.originalDescriptor.path || this.originalDescriptor.id;
+      return this.originalDescriptor.path;
     }
     return undefined;
   }
 
+  private reconcileSessionCacheDeviceIdentity(previousDeviceId?: string) {
+    deviceWalletSessionStore.reconcileDeviceIdentity({
+      temporaryKey: this.isProtocolV2() ? this.originalDescriptor.path : undefined,
+      previousDeviceId,
+      nextDeviceId: this.getCurrentDeviceId(),
+    });
+  }
+
   getInternalState(_deviceId?: string) {
     Log.debug(
       'getInternalState session param: ',
       `device_id: ${_deviceId}`,
-      `features.deviceId: ${this.features?.deviceId}`,
-      `passphraseState: ${this.passphraseState}`
+      `currentDeviceId: ${this.getCurrentDeviceId()}`,
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     const deviceId = this.getSessionCacheDeviceKey(_deviceId);
@@ -658,19 +819,26 @@ export class Device extends EventEmitter {
     return deviceWalletSessionStore.get(deviceId, this.passphraseState);
   }
 
+  getStandardInternalState(_deviceId?: string) {
+    const deviceId = this.getSessionCacheDeviceKey(_deviceId);
+    if (!deviceId) return undefined;
+    return deviceWalletSessionStore.getStandard(deviceId);
+  }
+
   // attach to pin to fix internal state
   updateInternalState(
     enablePassphrase: boolean,
     passphraseState: string | undefined,
     deviceId: string | undefined,
     sessionId: string | null = null,
-    featuresSessionId: string | null = null
+    featuresSessionId: string | null = null,
+    walletType: 'standard' | 'hidden' = 'hidden'
   ) {
     Log.debug(
       'updateInternalState session param: ',
       `device_id: ${deviceId}`,
       `enablePassphrase: ${enablePassphrase}`,
-      `passphraseState: ${passphraseState}`,
+      `hasPassphraseState: ${Boolean(passphraseState)}`,
       `hasSessionId: ${Boolean(sessionId)}`,
       `hasFeaturesSessionId: ${Boolean(featuresSessionId)}`
     );
@@ -681,7 +849,15 @@ export class Device extends EventEmitter {
     if (enablePassphrase) {
       const walletSessionId =
         sessionId || featuresSessionId || deviceWalletSessionStore.getPending(cacheDeviceKey);
-      deviceWalletSessionStore.set(cacheDeviceKey, passphraseState, walletSessionId ?? undefined);
+      if (walletType === 'standard') {
+        deviceWalletSessionStore.setStandard(
+          cacheDeviceKey,
+          passphraseState,
+          walletSessionId ?? undefined
+        );
+      } else {
+        deviceWalletSessionStore.set(cacheDeviceKey, passphraseState, walletSessionId ?? undefined);
+      }
     }
 
     deviceWalletSessionStore.deletePending(cacheDeviceKey);
@@ -692,8 +868,8 @@ export class Device extends EventEmitter {
       'setInternalState session param: ',
       `hasState: ${Boolean(state)}`,
       `initSession: ${initSession}`,
-      `deviceId: ${this.features?.deviceId}`,
-      `passphraseState: ${this.passphraseState}`
+      `deviceId: ${this.getCurrentDeviceId()}`,
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     if (!this.passphraseState && !initSession) return;
@@ -720,61 +896,117 @@ export class Device extends EventEmitter {
     }
   }
 
+  clearStandardInternalState(_deviceId?: string) {
+    const deviceId = this.getSessionCacheDeviceKey(_deviceId);
+    if (!deviceId) return;
+    deviceWalletSessionStore.deleteStandard(deviceId);
+  }
+
   async initialize(options?: InitOptions) {
-    // Protocol V2 不支持传统 Initialize，直接使用协议专用初始化流程。
+    // Protocol V2 does not support legacy Initialize; use its dedicated flow.
     if (this.isProtocolV2()) {
       this.passphraseState = options?.passphraseState;
-      if (this.features && !this.featuresNeedsReload && !options?.initSession) {
-        if (this.features.bootloaderMode) {
+      if (this.state && !options?.initSession && !this.protocolV2StateNeedsReload) {
+        if (this.state.status.mode === 'bootloader' || this.state.status.mode === 'romloader') {
           return;
         }
-        // 不能直接信任缓存 features：设备端 wipe / 完成初始化 / 改 label 后
-        // features 会永久陈旧。每次 run 做一次轻量 status 刷新（不含 fw/SE），
-        // 用字段级合并保留已有版本和 SE 信息。
-        await this._refreshProtocolV2Status(options);
+        // Normal calls reuse the cache. Explicit getDeviceState refreshes, unlock flow,
+        // and device events update dynamic state without polling on every SDK call.
         return;
       }
       await this._initializeProtocolV2(options);
+      this.protocolV2StateNeedsReload = false;
       return;
     }
 
-    // Log.debug('initialize param:', options);
+    try {
+      const callInitialize = async (payload: Record<string, unknown>, initSession?: boolean) => {
+        const initStartAt = Date.now();
+        const { message } = await this.commands.typedCall('Initialize', 'Features', payload, {
+          // iOS BLE bound devices can need close to 20 seconds.
+          timeoutMs: options?.timeoutMs ?? 25 * 1000,
+        });
+        this.setLastInitializeDuration(Date.now() - initStartAt);
+        this._updateFeatures(message, initSession);
+        await TransportManager.reconfigure(this.features);
+      };
 
-    this.passphraseState = options?.passphraseState;
+      const expectedDeviceId = options?.deviceId;
+
+      if (expectedDeviceId && !(this.features && this.checkDeviceId(expectedDeviceId))) {
+        // No locally-cached evidence that the device at this path is the
+        // expected one (first contact, or the cached features already disagree
+        // with the caller). Establish identity with a context-free Initialize
+        // BEFORE any wallet context (session_id / passphrase_state) goes on
+        // the wire. In normal flows features are always fresh — enumerate /
+        // getFeatures run first and every call response refreshes them — so
+        // this extra round trip is confined to the ambiguous cases where the
+        // disclosure risk actually lives.
+        this.passphraseState = undefined;
+        await callInitialize({ is_contains_attach: true });
+        if (!this.checkDeviceId(expectedDeviceId)) {
+          throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
+        }
+      }
 
-    if (options?.initSession) {
-      this.clearInternalState(options?.deviceId);
-    }
+      this.passphraseState = options?.passphraseState;
 
-    const internalState = this.getInternalState(options?.deviceId);
-    const payload: any = {};
-    if (internalState) {
-      payload.session_id = internalState;
-    }
+      if (options?.initSession) {
+        this.clearInternalState(options?.deviceId);
+      }
 
-    if (options?.deriveCardano) {
-      payload.derive_cardano = true;
-    }
-    payload.passphrase_state = options?.passphraseState;
-    payload.is_contains_attach = true;
+      const internalState = this.getInternalState(options?.deviceId);
+      const payload: Record<string, unknown> = {
+        passphrase_state: options?.passphraseState,
+        is_contains_attach: true,
+      };
+      if (internalState) {
+        payload.session_id = internalState;
+      }
+      if (options?.deriveCardano) {
+        payload.derive_cardano = true;
+      }
 
-    const initStartAt = Date.now();
-    try {
-      // @ts-expect-error
-      const { message } = await Promise.race([
-        this.commands.typedCall('Initialize', 'Features', payload),
-        new Promise((_, reject) => {
-          setTimeout(() => {
-            reject(ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed));
-            // iOS ble bound device timeout 20s
-          }, 25 * 1000);
-        }),
-      ]);
-
-      const initCostMs = Date.now() - initStartAt;
-      this.setLastInitializeDuration(initCostMs);
-      this._updateFeatures(message, options?.initSession);
-      await TransportManager.reconfigure(this.features);
+      if (this.features) {
+        // Re-sync the V1 message schema for THIS device before encoding
+        // Initialize: the process-global schema may still reflect another
+        // device (e.g. legacy-firmware Touch/Mini) on multi-device setups, and
+        // a stale legacy schema would silently strip passphrase_state /
+        // is_contains_attach from the wire message. Local operation, no wire
+        // I/O; a no-op when the schema is unchanged.
+        await TransportManager.reconfigure(this.features);
+      }
+
+      // Initialize's own Features response carries device_id, so the physical
+      // device identity is validated on the same round trip instead of via a
+      // separate read-only GetFeatures preflight (which doubled the wire cost
+      // of every deviceId-carrying call). The method fn has not run yet, so a
+      // mismatch still fails before any wallet data can be derived, with the
+      // same DeviceCheckDeviceIdError. Wallet-context selection is unchanged:
+      // it is decided by the Initialize payload above either way.
+      const assertExpectedDeviceIdentity = () => {
+        if (expectedDeviceId && !this.checkDeviceId(expectedDeviceId)) {
+          // The mismatched Initialize may have cached a session under the wrong
+          // device's identity; drop it so no wallet context survives from it.
+          // (This also evicts any session the wrong device legitimately cached
+          // under the same passphraseState — a deliberate conservative purge
+          // after a physical-swap event, consistent with
+          // reconcileDeviceIdentity purging the previous device's sessions.)
+          this.clearInternalState();
+          throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
+        }
+      };
+
+      try {
+        await callInitialize(payload, options?.initSession);
+      } catch (error) {
+        // callInitialize can fail AFTER the wire call cached the session (e.g.
+        // TransportManager.reconfigure rejecting); the identity check must
+        // still run so a wrong-device session never survives the error path.
+        assertExpectedDeviceIdentity();
+        throw error;
+      }
+      assertExpectedDeviceIdentity();
     } catch (error) {
       Log.error('Initialization failed:', error);
       throw error;
@@ -784,59 +1016,34 @@ export class Device extends EventEmitter {
   /**
    * Device initialization over Protocol V2.
    *
-   * Protocol V2 不走传统 Initialize/GetFeatures；直接用 DeviceInfoGet
-   * 生成唯一的 features 状态。
+   * Protocol V2 bypasses legacy Initialize/GetFeatures and builds its canonical
+   * features state directly from DeviceInfoGet.
    */
   private async _initializeProtocolV2(options?: InitOptions) {
     Log.debug('Initialize device via Protocol V2 features adapter');
 
     try {
-      // 超时由 requestProtocolV2DeviceInfo 内部的 typedCall timeoutMs（默认 10s）负责，
-      // 不再额外包一层 Promise.race：外层 race 的 timer 不会清理，
-      // 且 reject 后底层调用仍会残留。
+      // typedCall applies the request timeout. An outer Promise.race would leak its
+      // timer and leave the underlying call active after rejection.
       const deviceInfo = await requestProtocolV2DeviceInfo({
         commands: this.commands,
         timeoutMs: options?.protocolV2DeviceInfoTimeoutMs,
       });
-      // 默认请求不含 SE/hash 数据，scope 如实标注为 basic；
-      // 完整数据由 getDeviceInfo(scope:'verify'|'full') 获取。
-      const features = this.updateProtocolV2Features(deviceInfo);
-      Log.debug('Protocol V2 features:', features);
-      this.featuresNeedsReload = false;
+      // The default request excludes SE/hash data and therefore uses basic scope.
+      // Full version and verification data require getDeviceState({ scope: 'firmware' }).
+      await this.probeProtocolV2RuntimeState(deviceInfo, options?.protocolV2DeviceInfoTimeoutMs);
     } catch (error) {
       Log.error('Protocol V2 initialization failed:', error);
       throw error;
     }
   }
 
-  /**
-   * Protocol V2 的轻量状态刷新（每次 run 前调用）。
-   *
-   * 请求 hw + coprocessor + status（不含 fw/SE target）：status 提供 init_states / label /
-   * passphrase_enabled 等会在设备端变化的字段；hw/coprocessor 提供 serialNo / bleName。
-   * versions 为空时按字段级合并保留旧值，verify 数据不会被降级。
-   */
-  private async _refreshProtocolV2Status(options?: InitOptions) {
-    try {
-      const deviceInfo = await requestProtocolV2DeviceInfo({
-        commands: this.commands,
-        request: PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
-        timeoutMs: options?.protocolV2DeviceInfoTimeoutMs,
-      });
-      const features = this.updateProtocolV2Features(deviceInfo);
-      Log.debug('Protocol V2 features (status refresh):', features);
-    } catch (error) {
-      Log.error('Protocol V2 status refresh failed:', error);
-      throw error;
-    }
-  }
-
   async getFeatures() {
     if (this.isProtocolV2()) {
       const deviceInfo = await requestProtocolV2DeviceInfo({
         commands: this.commands,
       });
-      return this.updateProtocolV2Features(deviceInfo);
+      return this.probeProtocolV2RuntimeState(deviceInfo);
     }
 
     const { message } = await this.commands.typedCall('GetFeatures', 'Features', {});
@@ -844,61 +1051,355 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
+  async getDeviceState(params: DeviceStateReadOptions = {}) {
+    const refresh = new Set(params.refreshSections ?? []);
+    const getProtocolV2DeviceInfoRequest = () => {
+      if (refresh.has('verification')) return PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST;
+      if (refresh.has('versions')) return PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST;
+      return PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST;
+    };
+    let initializedWithDeviceInfo = false;
+    let refreshedDeviceInfo: ProtocolV2DeviceInfo | undefined;
+
+    if (!this.state) {
+      if (this.isProtocolV2()) {
+        const deviceInfo = await requestProtocolV2DeviceInfo({
+          commands: this.commands,
+          request: getProtocolV2DeviceInfoRequest(),
+        });
+        await this.probeProtocolV2RuntimeState(deviceInfo);
+        refreshedDeviceInfo = deviceInfo;
+        initializedWithDeviceInfo = true;
+      } else {
+        await this.getFeatures();
+      }
+    } else if (!this.isProtocolV2() && refresh.size > 0) {
+      await this.getFeatures();
+    }
+
+    const supportsProtocolV1OnekeyFeatures =
+      this.getCurrentDeviceType() === EDeviceType.Touch ||
+      this.getCurrentDeviceType() === EDeviceType.Pro;
+    if (!this.isProtocolV2() && refresh.has('verification') && supportsProtocolV1OnekeyFeatures) {
+      const { message } = await this.commands.typedCall('OnekeyGetFeatures', 'OnekeyFeatures');
+      this.updateState(mapProtocolV1OnekeyFeaturesToState(message), 'device-info');
+    }
+
+    if (this.isProtocolV2()) {
+      const refreshDeviceInfo =
+        refresh.has('identity') || refresh.has('versions') || refresh.has('verification');
+      if (refreshDeviceInfo && !initializedWithDeviceInfo) {
+        const deviceInfo = await requestProtocolV2DeviceInfo({
+          commands: this.commands,
+          request: getProtocolV2DeviceInfoRequest(),
+        });
+        refreshedDeviceInfo = deviceInfo;
+        if (!refresh.has('status')) {
+          this.updateState(
+            mapProtocolV2DeviceInfoToState(deviceInfo, this.state?.status.mode),
+            'device-info'
+          );
+        }
+      }
+
+      if (refresh.has('status') && !initializedWithDeviceInfo) {
+        const cachedMode = this.state?.status.mode;
+        await this.probeProtocolV2RuntimeState(refreshedDeviceInfo, undefined, {
+          // Loader firmware does not support DeviceStatusGet. Renegotiate ProtocolInfo
+          // during an explicit refresh so a device rebooted into application firmware
+          // can leave the cached loader state.
+          forceRuntimeContextRefresh: cachedMode === 'bootloader' || cachedMode === 'romloader',
+        });
+      }
+
+      if (refresh.has('settings') && this.state?.status.mode === 'normal') {
+        const { message } = await this.commands.typedCall(
+          'DeviceSettingsGet',
+          'DeviceSettings',
+          {}
+        );
+        this.updateState(mapDeviceSettingsToState(message), 'settings-read');
+      }
+    }
+
+    if (!this.state) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed);
+    }
+    return params.includeRaw ? cloneDeviceState(this.state) : createPublicDeviceState(this.state);
+  }
+
+  async refreshProtocolV2SettingsAfterMutation() {
+    return this.getDeviceState({ refreshSections: ['status', 'settings'] });
+  }
+
   _updateFeatures(protoFeatures: PROTO.Features | Features, initSession?: boolean) {
-    const previousCacheDeviceKey = this.getSessionCacheDeviceKey();
+    const previousDeviceId = this.getCurrentDeviceId();
     let feat =
       'protocol' in protoFeatures
         ? protoFeatures
         : buildProtocolV1FeaturesPayload(protoFeatures, this.features);
 
-    // GetFeatures doesn't return 'session_id'
-    if (this.features?.sessionId && !feat.sessionId) {
-      feat.sessionId = this.features.sessionId;
-    }
     feat.unlocked = feat.unlocked ?? true;
 
     feat = fixFeaturesFirmwareVersion(feat);
 
-    this.features = feat;
-    const nextCacheDeviceKey = this.getSessionCacheDeviceKey();
-    if (previousCacheDeviceKey && nextCacheDeviceKey) {
-      deviceWalletSessionStore.migrateDeviceKey(previousCacheDeviceKey, nextCacheDeviceKey);
-    }
+    this.updateState(mapFeaturesToState(feat), 'initialize');
+    this.reconcileSessionCacheDeviceIdentity(previousDeviceId);
     if (feat.deviceId && feat.sessionId) {
       this.setInternalState(feat.sessionId, initSession);
     }
-    this.featuresNeedsReload = false;
-    this.emit(DEVICE.FEATURES, this, feat);
   }
 
-  updateProtocolV2Features(deviceInfo?: ProtocolV2DeviceInfo) {
-    const previousCacheDeviceKey = this.getSessionCacheDeviceKey();
-    const features = fixFeaturesFirmwareVersion(
-      buildProtocolV2FeaturesPayload(deviceInfo, this.features)
-    );
-    this.features = features;
-    const nextCacheDeviceKey = this.getSessionCacheDeviceKey();
-    if (previousCacheDeviceKey && nextCacheDeviceKey) {
-      deviceWalletSessionStore.migrateDeviceKey(previousCacheDeviceKey, nextCacheDeviceKey);
+  updateState(patch: DeviceStatePatch, source: DeviceStateUpdateSource) {
+    const result = this.stateStore.update(patch, source);
+    if (result.changedKeys.length === 0) return result.state;
+
+    const event: DeviceStateEvent = {
+      connectId: this.getConnectId() ?? null,
+      state: createPublicDeviceState(result.state),
+      revision: result.revision,
+      source,
+      changedKeys: result.changedKeys,
+    };
+    Log.debug('Device state updated', {
+      source,
+      revision: result.revision,
+      changedKeyCount: result.changedKeys.length,
+    });
+    this.emit(DEVICE.STATE, this, event);
+    if (result.state.protocol === 'V1') {
+      this.emit(DEVICE.FEATURES, this, projectFeatures(result.state));
     }
-    this.featuresNeedsReload = false;
-    this.emit(DEVICE.FEATURES, this, features);
-    return features;
+    return result.state;
+  }
+
+  updateFeaturesPatch(patch: Partial<Features>, source: DeviceStateUpdateSource) {
+    const currentFeatures = this.features;
+    if (!currentFeatures) return undefined;
+
+    const features = mergeDeviceFeaturesPatch(currentFeatures, patch);
+    if (features === currentFeatures) return currentFeatures;
+
+    const normalized = fixFeaturesFirmwareVersion(features);
+    this.updateState(mapFeaturesToState(normalized), source);
+    return this.features;
+  }
+
+  async ensureProtocolV2RuntimeContext(
+    timeoutMs?: number,
+    options?: { forceRefresh?: boolean }
+  ): Promise<ProtocolInfo> {
+    const cachedProtocolInfo =
+      options?.forceRefresh === true
+        ? undefined
+        : this.protocolV2RuntimeContext ??
+          (!this.protocolV2StateNeedsReload
+            ? this.state?.raw?.protocolV2ProtocolInfo ?? undefined
+            : undefined);
+    if (cachedProtocolInfo) {
+      this.protocolV2RuntimeContext = cachedProtocolInfo;
+      return cachedProtocolInfo;
+    }
+
+    if (this.protocolV2RuntimeContextPromise) {
+      return this.protocolV2RuntimeContextPromise;
+    }
+
+    const requestToken = {};
+    const pendingRequest = (async () => {
+      const protocolInfo = await requestProtocolV2ProtocolInfo({
+        commands: this.commands,
+        timeoutMs,
+      });
+      if (this.protocolV2RuntimeContextRequestToken !== requestToken) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.DeviceInitializeFailed,
+          'Protocol V2 runtime context was invalidated while loading.'
+        );
+      }
+      this.protocolV2RuntimeContext = protocolInfo;
+      return protocolInfo;
+    })();
+    this.protocolV2RuntimeContextRequestToken = requestToken;
+    this.protocolV2RuntimeContextPromise = pendingRequest;
+
+    try {
+      return await pendingRequest;
+    } finally {
+      if (this.protocolV2RuntimeContextPromise === pendingRequest) {
+        this.protocolV2RuntimeContextPromise = undefined;
+      }
+      if (this.protocolV2RuntimeContextRequestToken === requestToken) {
+        this.protocolV2RuntimeContextRequestToken = undefined;
+      }
+    }
+  }
+
+  async probeProtocolV2RuntimeState(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    timeoutMs?: number,
+    options?: {
+      forceRuntimeContextRefresh?: boolean;
+    }
+  ) {
+    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs, {
+      forceRefresh: options?.forceRuntimeContextRefresh,
+    });
+    const runtimeDeviceInfo = deviceInfo ?? this.state?.raw?.protocolV2DeviceInfo;
+    const runtimeMode = getProtocolV2RuntimeMode(protocolInfo, runtimeDeviceInfo);
+    const legacyProtocolInfo = isLegacyProtocolV2ProtocolInfo(protocolInfo);
+    const protocolV2DeviceType = runtimeDeviceInfo
+      ? resolveProtocolV2DeviceIdentity(runtimeDeviceInfo.hw?.Device_type).deviceType
+      : this.getCurrentDeviceType();
+    if (
+      runtimeMode === 'romloader' &&
+      protocolV2DeviceType !== EDeviceType.Pro2 &&
+      protocolV2DeviceType !== EDeviceType.Neo
+    ) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.DeviceInitializeFailed,
+        'Protocol V2 romloader mode is only supported for Pro2 and Neo.'
+      );
+    }
+    const deviceStatusSupported =
+      legacyProtocolInfo ||
+      supportsProtocolV2Message(protocolInfo, PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE);
+
+    if (runtimeMode === 'bootloader' || runtimeMode === 'romloader') {
+      return this.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
+    }
+
+    if (!deviceStatusSupported) {
+      if (runtimeMode === 'normal') {
+        return this.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
+      }
+      throw ERRORS.TypedError(
+        HardwareErrorCode.DeviceInitializeFailed,
+        `Unknown Protocol V2 build fingerprint without DeviceStatusGet capability: ${protocolInfo.build_fingerprint}`
+      );
+    }
+
+    let deviceStatus: DeviceStatus;
+    try {
+      deviceStatus = await requestProtocolV2DeviceStatus({
+        commands: this.commands,
+        timeoutMs,
+      });
+    } catch (error) {
+      if (runtimeMode === undefined && isProtocolV2DeviceStatusUnsupportedError(error)) {
+        return this.updateProtocolV2Features(deviceInfo, null, 'bootloader', protocolInfo);
+      }
+      throw error;
+    }
+    return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal', protocolInfo);
+  }
+
+  updateProtocolV2Features(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    deviceStatus?: DeviceStatus | null,
+    runtimeMode?: ProtocolV2RuntimeMode,
+    protocolInfo?: ProtocolInfo
+  ) {
+    const previousDeviceId = this.getCurrentDeviceId();
+    const resolvedMode = runtimeMode ?? (deviceStatus ? 'normal' : this.state?.status.mode);
+    if (deviceInfo) {
+      this.updateState(mapProtocolV2DeviceInfoToState(deviceInfo, resolvedMode), 'device-info');
+    }
+    if (protocolInfo) {
+      this.updateState({ raw: { protocolV2ProtocolInfo: protocolInfo } }, 'device-info');
+    }
+    if (deviceStatus) {
+      this.updateState(mapProtocolV2DeviceStatusToState(deviceStatus), 'device-status');
+    }
+    this.reconcileSessionCacheDeviceIdentity(previousDeviceId);
+    return this.features as Features;
   }
 
   updateProtocolV2Status(status: DeviceStatus) {
-    const previousDeviceInfo = this.features?.raw?.protocolV2DeviceInfo;
-    const previousStatus = previousDeviceInfo?.status;
-    return this.updateProtocolV2Features({
-      ...(previousDeviceInfo ?? {}),
-      protocol_version: previousDeviceInfo?.protocol_version ?? this.features?.protocolVersion ?? 2,
-      status: {
-        ...previousStatus,
-        ...status,
-      },
+    const previousDeviceInfo = this.state?.raw?.protocolV2DeviceInfo;
+    const previousStatus = this.state?.raw?.protocolV2DeviceStatus;
+    return this.updateProtocolV2Features(previousDeviceInfo, {
+      ...previousStatus,
+      ...status,
     });
   }
 
+  private invalidateProtocolV2RuntimeState() {
+    if (!this.isProtocolV2()) return;
+    this.protocolV2StateNeedsReload = true;
+    this.protocolV2RuntimeContext = undefined;
+    this.protocolV2RuntimeContextPromise = undefined;
+    this.protocolV2RuntimeContextRequestToken = undefined;
+    this.clearPreInitialized();
+  }
+
+  markTransportDisconnected() {
+    this.deviceAcquired = false;
+    this.invalidateProtocolV2RuntimeState();
+  }
+
+  invalidateAfterWipe() {
+    const deviceId = this.getCurrentDeviceId();
+    if (deviceId) {
+      deviceWalletSessionStore.deleteDevice(deviceId);
+    }
+    if (this.isProtocolV2()) {
+      if (this.originalDescriptor.path !== deviceId) {
+        deviceWalletSessionStore.deleteDevice(this.originalDescriptor.path);
+      }
+      this.invalidateProtocolV2RuntimeState();
+    }
+
+    this.passphraseState = undefined;
+    this.stateStore = new DeviceStateStore();
+    this.clearPreInitialized();
+    this.needReloadDevice = true;
+  }
+
+  markProtocolV2Reboot(rebootType: DeviceRebootType) {
+    if (!this.isProtocolV2()) return;
+
+    this.invalidateProtocolV2RuntimeState();
+    let loaderMode: 'bootloader' | 'romloader' | undefined;
+    if (rebootType === DeviceRebootType.Bootloader) {
+      loaderMode = 'bootloader';
+    } else if (rebootType === DeviceRebootType.Romloader) {
+      loaderMode = 'romloader';
+    }
+    if (loaderMode) {
+      this.updateState(
+        {
+          identity: { deviceId: null },
+          status: {
+            mode: loaderMode,
+            initialized: null,
+            unlocked: null,
+            firmwarePresent: null,
+            backupRequired: null,
+            noBackup: null,
+            unfinishedBackup: null,
+            recoveryMode: null,
+            passphraseProtection: null,
+            pinProtection: null,
+            attachToPinEnabled: null,
+            unlockedAttachPin: null,
+          },
+          raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
+        },
+        'transport-reconnect'
+      );
+      return;
+    }
+
+    this.updateState(
+      {
+        status: { mode: 'normal', unlocked: null },
+        raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
+      },
+      'transport-reconnect'
+    );
+  }
+
   /**
    * 暂时只在 acquire 后更新 Session ID
    * 后续看是否有需要依据 listen 返回结果更新
@@ -917,8 +1418,7 @@ export class Device extends EventEmitter {
     }
 
     if (forceUpdate) {
-      // 枚举得到的 descriptor 可能不带 protocolType（如 WebUSB enumerate），
-      // 不能让覆盖丢掉已探测的协议结果。
+      // Enumerated descriptors may omit protocolType, so preserve an actively probed value.
       this.originalDescriptor = {
         ...descriptor,
         protocolType: descriptor.protocolType ?? this.originalDescriptor.protocolType,
@@ -933,6 +1433,10 @@ export class Device extends EventEmitter {
     if (device.features) {
       this._updateFeatures(device.features);
     }
+    // Adopting another Device instance's command channel also crosses an active
+    // link boundary. Renegotiate runtime metadata on that channel instead of
+    // retaining ProtocolInfo from the previous instance/session.
+    this.invalidateProtocolV2RuntimeState();
   }
 
   async run(fn?: () => Promise<void>, options?: RunOptions) {
@@ -943,19 +1447,51 @@ export class Device extends EventEmitter {
 
     options = parseRunOptions(options);
 
-    this.runPromise = createDeferred(this._runInner.bind(this, fn, options));
-    return this.runPromise.promise;
+    const runPromise = createDeferred<void>();
+    this.runPromise = runPromise;
+    const cleanupPromise = this._runInner(fn, options, runPromise).catch(error => {
+      if (this.runPromise === runPromise) {
+        this.runPromise = null;
+      }
+      runPromise.reject(error);
+    });
+    this.runCleanupPromise = cleanupPromise;
+    cleanupPromise
+      .finally(() => {
+        if (this.runCleanupPromise === cleanupPromise) {
+          this.runCleanupPromise = undefined;
+        }
+      })
+      .catch(() => undefined);
+    return runPromise.promise;
   }
 
-  async _runInner<T>(fn: (() => Promise<T>) | undefined, options: RunOptions) {
-    if (!this.isUsedHere() || this.commands.disposed) {
-      const env = DataManager.getSettings('env');
+  async _runInner<T>(
+    fn: (() => Promise<T>) | undefined,
+    options: RunOptions,
+    runPromise: Deferred<void>
+  ) {
+    const clearRunPromise = () => {
+      if (this.runPromise === runPromise) {
+        this.runPromise = null;
+      }
+    };
+
+    const env = DataManager.getSettings('env');
+    if (options.forceProtocolDetection && env !== 'react-native' && this.isUsedHere()) {
+      await this.release();
+    }
+
+    if (options.forceProtocolDetection || !this.isUsedHere() || this.commands.disposed) {
       if (env !== 'react-native') {
         try {
-          await this.acquire(options.connectProtocol);
+          await this.acquire(options.connectProtocol, {
+            forceProtocolDetection: options.forceProtocolDetection,
+          });
         } catch (error) {
-          this.runPromise = null;
-          return Promise.reject(error);
+          clearRunPromise();
+          runPromise.reject(error);
+          return;
         }
 
         try {
@@ -965,16 +1501,19 @@ export class Device extends EventEmitter {
             }
           }
         } catch (error) {
-          this.runPromise = null;
+          await this.release();
+          clearRunPromise();
           if (error instanceof HardwareError) {
-            return Promise.reject(error);
+            runPromise.reject(error);
+            return;
           }
-          return Promise.reject(
+          runPromise.reject(
             ERRORS.TypedError(
               HardwareErrorCode.DeviceInitializeFailed,
               `Initialize failed: ${error.message as string}, code: ${error.code as string}`
             )
           );
+          return;
         }
       } else if (env === 'react-native') {
         // TODO: implement react-native acquire
@@ -993,9 +1532,7 @@ export class Device extends EventEmitter {
       try {
         await fn();
       } catch (e) {
-        if (this.runPromise) {
-          this.runPromise.reject(e);
-        }
+        runPromise.reject(e);
 
         if (
           e instanceof HardwareError &&
@@ -1008,7 +1545,7 @@ export class Device extends EventEmitter {
           Log.debug(`error code ${e.errorCode} release device, mainId: ${this.mainId}`);
         }
 
-        this.runPromise = null;
+        clearRunPromise();
         return;
       }
     }
@@ -1022,11 +1559,8 @@ export class Device extends EventEmitter {
       Log.debug('release device, mainId: ', this.mainId);
     }
 
-    if (this.runPromise) {
-      this.runPromise.resolve();
-    }
-
-    this.runPromise = null;
+    runPromise.resolve();
+    clearRunPromise();
   }
 
   async interruptionFromOutside() {
@@ -1040,13 +1574,29 @@ export class Device extends EventEmitter {
 
   async interruptionFromUser() {
     const error = ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
-    await this.cancelableAction?.(error);
+    const cleanupPromise = this.runCleanupPromise;
+    const { cancelableAction } = this;
+    const env = DataManager.getSettings('env');
+    if (cancelableAction) {
+      await cancelableAction(error);
+    } else if (
+      this.isProtocolV2() &&
+      (DataManager.isBleConnect(env) ||
+        DataManager.isBrowserWebUsb(env) ||
+        DataManager.isDesktopWebUsb(env)) &&
+      this.hasDeviceAcquire()
+    ) {
+      await this.commands?.cancelDevice?.().catch(cancelError => {
+        Log.debug('Protocol V2 fallback cancel error', cancelError);
+      });
+    }
     await this.commands?.cancel();
 
     if (this.runPromise) {
       this.runPromise.reject(error);
       this.runPromise = null;
     }
+    await cleanupPromise?.catch(() => undefined);
   }
 
   setCancelableAction(callback: (err?: Error) => Promise<unknown>) {
@@ -1065,33 +1615,37 @@ export class Device extends EventEmitter {
   }
 
   getMode() {
-    if (this.features?.bootloaderMode) {
-      // bootloader mode
-      return EOneKeyDeviceMode.bootloader;
-    }
-
-    if (!this.features?.initialized) {
-      // not initialized
-      return EOneKeyDeviceMode.notInitialized;
+    switch (this.state?.status.mode) {
+      case 'bootloader':
+      case 'romloader':
+        return EOneKeyDeviceMode.bootloader;
+      case 'notInitialized':
+        return EOneKeyDeviceMode.notInitialized;
+      case 'backupMode':
+        return EOneKeyDeviceMode.backupMode;
+      case 'normal':
+        return EOneKeyDeviceMode.normal;
+      default:
+        break;
     }
 
-    if (this.features?.noBackup) {
-      // backup mode
-      return EOneKeyDeviceMode.backupMode;
-    }
-
-    // normal mode
     return EOneKeyDeviceMode.normal;
   }
 
+  getStatus() {
+    if (this.isUsedElsewhere()) return 'occupied' as const;
+    if (this.isUsedHere()) return 'used' as const;
+    return 'available' as const;
+  }
+
   getFirmwareVersion() {
-    if (!this.features) return null;
-    return getDeviceFirmwareVersion(this.features);
+    if (!this.state) return null;
+    return parseDeviceVersion(this.state.versions.firmware);
   }
 
   getBLEFirmwareVersion() {
-    if (!this.features) return null;
-    return getDeviceBLEFirmwareVersion(this.features);
+    if (!this.state) return null;
+    return parseDeviceVersion(this.state.versions.ble);
   }
 
   isUsed() {
@@ -1109,7 +1663,7 @@ export class Device extends EventEmitter {
   isUsedHere() {
     const env = DataManager.getSettings('env');
     if (DataManager.isBleConnect(env)) {
-      return false;
+      return this.deviceAcquired;
     }
     return this.isUsed() && this.originalDescriptor.session === this.mainId;
   }
@@ -1119,19 +1673,32 @@ export class Device extends EventEmitter {
   }
 
   isBootloader() {
-    return this.features && !!this.features.bootloaderMode;
+    if (!this.state) return undefined;
+    return this.state.status.mode === 'bootloader';
+  }
+
+  isRomloader() {
+    if (!this.state) return undefined;
+    return (
+      this.isProtocolV2() &&
+      (this.getCurrentDeviceType() === EDeviceType.Pro2 ||
+        this.getCurrentDeviceType() === EDeviceType.Neo) &&
+      this.state.status.mode === 'romloader'
+    );
   }
 
   isInitialized() {
-    return this.features && !!this.features.initialized;
+    if (!this.state) return undefined;
+    return this.state.status.initialized === true;
   }
 
   isSeedless() {
-    return this.features && !!this.features.noBackup;
+    if (!this.state) return undefined;
+    return this.state.status.noBackup === true;
   }
 
   isUnacquired(): boolean {
-    return this.features === undefined;
+    return this.state === undefined;
   }
 
   hasUnexpectedMode(allow: string[], require: string[]) {
@@ -1161,8 +1728,9 @@ export class Device extends EventEmitter {
     const isModeT =
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2;
-    const unlocked = this.features?.unlocked;
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo;
+    const unlocked = this.state?.status.unlocked;
     const preCheckTouch = isModeT && unlocked === false;
     const passphraseProtection = this.getCurrentPassphraseProtection();
 
@@ -1175,11 +1743,91 @@ export class Device extends EventEmitter {
 
   async lockDevice(): Promise<Success> {
     const res = await this.commands.typedCall('LockDevice', 'Success', {});
+    this.updateState({ status: { unlocked: false } }, 'lock');
     return res.message;
   }
 
+  beginProtocolV2UiInteraction() {
+    if (!this.isProtocolV2()) return;
+    this.protocolV2UiInteraction = {
+      interactionId: `${this.instanceId}:${Date.now()}:${++this.protocolV2UiInteractionCounter}`,
+      phaseCounter: 0,
+      sequence: 0,
+      opened: false,
+    };
+  }
+
+  createProtocolV2UiPhaseMetadata(
+    phase: HardwareUiInteractionMeta['phase'],
+    transition: HardwareUiInteractionMeta['transition'],
+    options?: {
+      phaseId?: string;
+      outcome?: HardwareUiInteractionMeta['outcome'];
+    }
+  ): HardwareUiInteractionMeta | undefined {
+    if (!this.isProtocolV2()) return undefined;
+    if (!this.protocolV2UiInteraction) this.beginProtocolV2UiInteraction();
+
+    const interaction = this.protocolV2UiInteraction;
+    if (!interaction) return undefined;
+    const phaseId =
+      options?.phaseId ?? `${interaction.interactionId}:phase-${++interaction.phaseCounter}`;
+    interaction.opened = true;
+    interaction.sequence += 1;
+
+    return {
+      interactionId: interaction.interactionId,
+      phaseId,
+      sequence: interaction.sequence,
+      phase,
+      transition,
+      ...(options?.outcome ? { outcome: options.outcome } : {}),
+      protocol: 'V2',
+    };
+  }
+
+  completeProtocolV2UiPhase(
+    phase: HardwareUiInteractionMeta,
+    outcome: HardwareUiInteractionMeta['outcome'] = 'succeeded'
+  ) {
+    return this.createProtocolV2UiPhaseMetadata(phase.phase, 'complete', {
+      phaseId: phase.phaseId,
+      outcome,
+    });
+  }
+
+  finishProtocolV2UiInteraction(
+    outcome?: HardwareUiInteractionMeta['outcome'],
+    options?: { ensureMetadata?: boolean }
+  ) {
+    const interaction = this.protocolV2UiInteraction;
+    if (!interaction || (!interaction.opened && !options?.ensureMetadata)) {
+      this.protocolV2UiInteraction = undefined;
+      return undefined;
+    }
+
+    const phaseId = `${interaction.interactionId}:phase-${Math.max(interaction.phaseCounter, 1)}`;
+    interaction.opened = true;
+    interaction.sequence += 1;
+    const metadata: HardwareUiInteractionMeta = {
+      interactionId: interaction.interactionId,
+      phaseId,
+      sequence: interaction.sequence,
+      phase: 'processing',
+      transition: 'finish',
+      outcome: outcome ?? 'succeeded',
+      protocol: 'V2',
+    };
+    this.protocolV2UiInteraction = undefined;
+    return metadata;
+  }
+
+  hasOpenProtocolV2UiInteraction() {
+    return this.protocolV2UiInteraction?.opened === true;
+  }
+
   supportUnlockVersionRange(): DeviceFirmwareRange {
-    // 仅适用于 Protocol V1 的 Pro 系列；Pro2 走独立的 Protocol V2 解锁流程。
+    // This range applies to Protocol V1 Pro devices; Pro2 has a dedicated unlock flow.
     return {
       pro: {
         min: '4.15.0',
@@ -1187,10 +1835,33 @@ export class Device extends EventEmitter {
     };
   }
 
-  async unlockDevice() {
+  async unlockDevice(
+    pinType?: DeviceSessionPinType,
+    options?: ProtocolV2UiEventMetadata & { emitUiEvent?: boolean }
+  ) {
     if (this.isProtocolV2()) {
+      const requestedPinType = pinType ?? DeviceSessionPinType.Main;
+      const interaction =
+        options?.interaction ??
+        (options?.emitUiEvent === false
+          ? undefined
+          : this.createProtocolV2UiPhaseMetadata('pin', 'start'));
+      if (options?.emitUiEvent !== false) {
+        this.emit(DEVICE.PIN_ON_DEVICE, this, requestedPinType, {
+          source: options?.source ?? 'unlock-coordinator',
+          reason: options?.reason ?? 'device-unlock',
+          deviceOnly: options?.deviceOnly ?? true,
+          completion: options?.completion,
+          method: options?.method,
+          page: options?.page,
+          operation: options?.operation,
+          interaction: options?.interaction ?? interaction,
+        });
+      }
       try {
-        await this.commands.typedCall('DeviceSessionAskPin', 'Success');
+        await this.commands.typedCall('DeviceSessionAskPin', 'Success', {
+          type: requestedPinType,
+        });
       } catch (error) {
         const errorText =
           error instanceof Error
@@ -1202,11 +1873,12 @@ export class Device extends EventEmitter {
         throw error;
       }
 
-      const { message: status } = await this.commands.typedCall(
-        'DeviceStatusGet',
-        'DeviceStatus',
-        {}
-      );
+      const completion = interaction ? this.completeProtocolV2UiPhase(interaction) : undefined;
+      if (completion) {
+        this.emit(DEVICE.PIN_ON_DEVICE_COMPLETE, this, completion);
+      }
+
+      const status = await requestProtocolV2DeviceStatus({ commands: this.commands });
       return this.updateProtocolV2Status(status);
     }
 
@@ -1215,8 +1887,7 @@ export class Device extends EventEmitter {
       type => this.supportUnlockVersionRange()[type]
     );
 
-    const supportAttachPinCapability = existCapability(
-      this.features,
+    const supportAttachPinCapability = this.state?.capabilities.includes(
       Enum_Capability.Capability_AttachToPin
     );
     const supportUnlock =
@@ -1227,12 +1898,21 @@ export class Device extends EventEmitter {
 
     if (supportUnlock) {
       const res = await this.commands.typedCall('UnLockDevice', 'UnLockDeviceResponse');
-      if (this.features) {
-        this.features.unlocked = res.message.unlocked == null ? null : res.message.unlocked;
-        this.features.unlockedAttachPin =
-          res.message.unlocked_attach_pin == null ? undefined : res.message.unlocked_attach_pin;
-        this.features.passphraseProtection =
-          res.message.passphrase_protection == null ? null : res.message.passphrase_protection;
+      if (this.state) {
+        this.updateState(
+          {
+            status: {
+              unlocked: res.message.unlocked == null ? null : res.message.unlocked,
+              unlockedAttachPin:
+                res.message.unlocked_attach_pin == null ? null : res.message.unlocked_attach_pin,
+              passphraseProtection:
+                res.message.passphrase_protection == null
+                  ? null
+                  : res.message.passphrase_protection,
+            },
+          },
+          'unlock'
+        );
 
         return Promise.resolve(this.features);
       }
@@ -1259,25 +1939,34 @@ export class Device extends EventEmitter {
   async checkPassphraseStateSafety(
     passphraseState?: string,
     useEmptyPassphrase?: boolean,
-    skipPassphraseCheck?: boolean
+    skipPassphraseCheck?: boolean,
+    deriveCardano?: boolean
   ) {
     if (this.isUnacquired()) return false;
 
+    const expectedPassphraseState = useEmptyPassphrase ? undefined : passphraseState;
     const { passphraseState: newPassphraseState, unlockedAttachPin } =
       await getPassphraseStateWithRefreshDeviceInfo(this, {
-        expectPassphraseState: passphraseState,
+        expectPassphraseState: expectedPassphraseState,
         onlyMainPin: useEmptyPassphrase,
+        deriveCardano,
+        rejectAttachPinForMainWallet: useEmptyPassphrase === true,
       });
 
     // Main wallet and unlock Attach Pin, throw safe error
     const mainWalletUseAttachPin = unlockedAttachPin && useEmptyPassphrase;
     const useErrorAttachPin =
-      unlockedAttachPin && passphraseState && passphraseState !== newPassphraseState;
-    const passphraseStateMismatch = !!passphraseState && passphraseState !== newPassphraseState;
+      unlockedAttachPin &&
+      expectedPassphraseState &&
+      expectedPassphraseState !== newPassphraseState;
+    const passphraseStateMismatch =
+      !!expectedPassphraseState && expectedPassphraseState !== newPassphraseState;
 
     Log.debug('Check passphrase state safety: ', {
-      passphraseState,
-      newPassphraseState,
+      hasExpectedPassphraseState: Boolean(expectedPassphraseState),
+      hasNewPassphraseState: Boolean(newPassphraseState),
+      passphraseStateMatches:
+        Boolean(expectedPassphraseState) && expectedPassphraseState === newPassphraseState,
       unlockedAttachPin,
       useEmptyPassphrase,
     });