@onekeyfe/hwk-trezor-adapter 1.2.7 → 1.2.8-alpha.1

package/dist/index.mjs

@@ -3,12 +3,27 @@ import {
   DEVICE,
   DeviceJobQueue,
   HardwareErrorCode,
+  OperationRegistry,
+  SDK,
   TypedEventEmitter,
   UI_REQUEST,
   UI_RESPONSE,
   UiRequestRegistry,
+  canReplayHardwareMethodAfterTransportFailure,
+  createHwkError,
+  defaultOriginForCode,
   failure,
+  isConnectionLost,
+  isHardwareOperationId,
+  isHwkRecoveryHint,
+  isUserRefusal,
+  isWalletSafetyFailure,
+  operationMayHaveCompletedParams,
   rehydrateConnectorError,
+  requestBleDeviceSelection,
+  requestSaveDeviceBinding,
+  resolveHardwareOperationTarget,
+  resolveSearchTargetReusePolicy,
   runAllNetworkGetAddress,
   success
 } from "@onekeyfe/hwk-adapter-core";
@@ -762,10 +777,34 @@ function debugLog(...args) {
   emitLog("debug", ...args);
 }
 
+// src/utils/queueKey.ts
+function trezorQueueKey({
+  operationId,
+  connectId
+}) {
+  return operationId || connectId || "";
+}
+
 // src/adapter/TrezorAdapter.ts
 var KNOWN_HARDWARE_ERROR_CODES = new Set(
   Object.values(HardwareErrorCode).filter((value) => typeof value === "number")
 );
+var ALL_NETWORK_COMMON_PARAM_KEYS = [
+  "autoInstallApp",
+  "passphraseState",
+  "useEmptyPassphrase",
+  "operationId",
+  "knownConnections",
+  "extra",
+  "allowDeviceSelection",
+  "supportedTransports"
+];
+var ALL_NETWORK_ROUTING_PARAM_KEYS = [
+  "operationId",
+  "knownConnections",
+  "allowDeviceSelection",
+  "supportedTransports"
+];
 var TREZOR_BTC_NETWORK_COIN_MAP = {
   btc: "Bitcoin",
   bitcoin: "Bitcoin",
@@ -782,9 +821,24 @@ var TREZOR_BTC_NETWORK_COIN_MAP = {
   dash: "Dash"
 };
 var _TrezorAdapter = class _TrezorAdapter {
-  constructor(connector) {
+  constructor(connector, options) {
     this.vendor = "trezor";
+    // The connector has no protocol-level cancel: the adapter stops waiting and
+    // drops the late response, the device carries on.
+    this.cancelCapability = "stops-waiting";
     this._emitter = new TypedEventEmitter();
+    this._operations = new OperationRegistry({
+      vendor: "trezor",
+      onEnded: (operation, reason) => {
+        this._emitter.emit(SDK.OPERATION_ENDED, {
+          type: SDK.OPERATION_ENDED,
+          payload: { operationId: operation.operationId, reason }
+        });
+        if (reason === "timeout") {
+          void this._releaseOperationConnection(operation).catch(() => void 0);
+        }
+      }
+    });
     this._devices = /* @__PURE__ */ new Map();
     this._sessions = /* @__PURE__ */ new Map();
     this._connectingPromises = /* @__PURE__ */ new Map();
@@ -793,12 +847,21 @@ var _TrezorAdapter = class _TrezorAdapter {
     this._uiRegistry = new UiRequestRegistry();
     this._passphraseRequestContextByConnectId = /* @__PURE__ */ new Map();
     this._verifiedPassphraseSessionsByConnectId = /* @__PURE__ */ new Map();
+    /** Raw connector calls that outlive an aborted caller, keyed by session. */
+    this._unsettledConnectorOperations = /* @__PURE__ */ new Map();
+    this._connectorIdleWaiters = /* @__PURE__ */ new Set();
+    this._resetPromise = null;
+    this._connectorTeardownTail = Promise.resolve();
+    this._pendingConnectorTeardowns = 0;
+    this._stateGeneration = 0;
+    this._knownDeviceConnections = /* @__PURE__ */ new Map();
     this._onDeviceConnect = (data) => {
       const device = this._connectorDeviceToDeviceInfo(data.device);
       this._devices.set(device.connectId, device);
       this._emitter.emit(DEVICE.CONNECT, { type: DEVICE.CONNECT, payload: device });
     };
     this._onDeviceDisconnect = (data) => {
+      this._operations.endByConnectionKey(data.connectId, "disconnect");
       this._sessions.delete(data.connectId);
       this._verifiedPassphraseSessionsByConnectId.delete(data.connectId);
       this._devices.delete(data.connectId);
@@ -818,25 +881,32 @@ var _TrezorAdapter = class _TrezorAdapter {
         payload: { device }
       });
     };
+    // The one outlet for every connector-raised UI request (PIN, passphrase,
+    // button, THP pairing), so the operation is stamped here instead of at each
+    // connector call site.
     this._onUiRequest = (data) => {
+      const operationId = this._activeOperationId();
+      const basePayload = data.payload && typeof data.payload === "object" ? data.payload : {};
+      const attribution = operationId === void 0 ? {} : { operationId };
       if (data.type === UI_REQUEST.REQUEST_PASSPHRASE) {
-        const payload = data.payload && typeof data.payload === "object" ? data.payload : {};
-        const connectId = typeof payload.connectId === "string" ? payload.connectId : void 0;
+        const connectId = typeof basePayload.connectId === "string" ? basePayload.connectId : void 0;
         const context = connectId ? this._passphraseRequestContextByConnectId.get(connectId) : void 0;
         this._emitter.emit(
           data.type,
           {
             ...data,
             payload: {
-              ...payload,
+              ...basePayload,
               ...context?.passphraseState !== void 0 ? { passphraseState: context.passphraseState } : {},
-              ...context?.useEmptyPassphrase !== void 0 ? { useEmptyPassphrase: context.useEmptyPassphrase } : {}
+              ...context?.useEmptyPassphrase !== void 0 ? { useEmptyPassphrase: context.useEmptyPassphrase } : {},
+              ...attribution
             }
           }
         );
         return;
       }
-      this._emitter.emit(data.type, data);
+      const payload = operationId === void 0 ? data.payload : { ...basePayload, ...attribution };
+      this._emitter.emit(data.type, { ...data, payload });
     };
     this._onUiEvent = (data) => {
       this._emitter.emit("ui-event", data);
@@ -848,6 +918,11 @@ var _TrezorAdapter = class _TrezorAdapter {
       });
     };
     this._connector = connector;
+    for (const connection of options?.knownDeviceConnections ?? []) {
+      if (connection.deviceId) {
+        this._knownDeviceConnections.set(connection.deviceId, { ...connection });
+      }
+    }
     this._jobQueue = new DeviceJobQueue();
     this._registerConnectorEvents();
   }
@@ -872,29 +947,35 @@ var _TrezorAdapter = class _TrezorAdapter {
       const {
         passphraseState,
         autoInstallApp: _autoInstallApp,
+        operationId,
         useEmptyPassphrase,
+        knownConnections,
+        extra,
+        allowDeviceSelection,
+        supportedTransports,
         ...rest
       } = params;
       return {
         passphraseState: typeof passphraseState === "string" ? passphraseState : void 0,
         useEmptyPassphrase: typeof useEmptyPassphrase === "boolean" ? useEmptyPassphrase : void 0,
+        operationId: typeof operationId === "string" ? operationId : void 0,
+        connectionContext: {
+          knownConnections,
+          extra,
+          allowDeviceSelection: typeof allowDeviceSelection === "boolean" ? allowDeviceSelection : void 0,
+          supportedTransports
+        },
         rest
       };
     }
     return { rest: params ?? {} };
   }
   static _withAllNetworkRequestCommonParams(item, commonParams) {
-    const autoInstallApp = commonParams?.autoInstallApp;
-    const passphraseState = commonParams?.passphraseState;
-    const useEmptyPassphrase = commonParams?.useEmptyPassphrase;
-    if (autoInstallApp === void 0 && passphraseState === void 0 && useEmptyPassphrase === void 0) {
-      return item;
-    }
+    const defined = ALL_NETWORK_COMMON_PARAM_KEYS.filter((key) => commonParams?.[key] !== void 0);
     return {
       ...item,
-      ...autoInstallApp !== void 0 ? { autoInstallApp } : {},
-      ...passphraseState !== void 0 ? { passphraseState } : {},
-      ...useEmptyPassphrase !== void 0 ? { useEmptyPassphrase } : {}
+      ...Object.fromEntries(defined.map((key) => [key, commonParams?.[key]])),
+      ...Object.fromEntries(ALL_NETWORK_ROUTING_PARAM_KEYS.map((key) => [key, commonParams?.[key]]))
     };
   }
   static _normalizeLogKey(key) {
@@ -1018,13 +1099,11 @@ var _TrezorAdapter = class _TrezorAdapter {
    * selected is gone (the device evicted it from its limited slot pool). The
    * caller drops the stale cache entry and recreates from scratch.
    *
-   * NOTE: the exact eviction code still needs real-device confirmation — match
-   * conservatively so a genuine error isn't mistaken for an evicted session
-   * (which would silently re-prompt the passphrase).
+   * Match only the protocol's explicit unallocated-channel code. Guessing from
+   * an error message could replay a request after an unrelated business error.
    */
   static _isStaleSessionError(code) {
-    if (typeof code !== "string") return false;
-    return code === "ThpUnallocatedChannel" || /invalid.?session|unallocated.?session|session.?not.?found/i.test(code);
+    return code === "ThpUnallocatedChannel";
   }
   static _errorCode(error) {
     return error.code ?? _TrezorAdapter._trezorFailureMessage(error).code;
@@ -1038,13 +1117,13 @@ var _TrezorAdapter = class _TrezorAdapter {
     return protocolError.name === "TrezorProtocolError" && protocolError.code === "Malformed protocol format" && protocolError.message === "Malformed protocol format";
   }
   /**
-   * Race a promise against an abort signal. Copied from LedgerAdapter:
-   * IConnector.call() can't actually be cancelled at the protocol level, but
-   * the caller gets the abort immediately and the underlying work completes
-   * uselessly in the background.
+   * Race a promise against an abort signal. IConnector.call() can't actually
+   * be cancelled at the protocol level, so the caller gets the abort while the
+   * adapter keeps the transport exclusively reserved until the raw call drains.
    */
   static _abortable(signal, promise) {
     if (signal.aborted) {
+      void promise.catch(() => void 0);
       return Promise.reject(
         signal.reason ?? new Error("Aborted")
       );
@@ -1066,17 +1145,37 @@ var _TrezorAdapter = class _TrezorAdapter {
       );
     });
   }
-  async _connectSession(connectId, signal) {
+  async _connectSession(connectId, signal, stateGeneration, transportType) {
     const connectOnce = async () => {
-      const connectPromise = this._connector.connect(connectId);
-      if (!signal) return connectPromise;
+      if (signal?.aborted) {
+        throw signal.reason ?? new Error("Aborted");
+      }
+      this._assertConnectorIdle("connectDevice");
+      const releaseOperation = this._retainConnectorOperation(`connect:${connectId}`);
+      let connectPromise;
       try {
-        return await _TrezorAdapter._abortable(signal, connectPromise);
+        connectPromise = transportType ? this._connector.connect(connectId, { transportType }) : this._connector.connect(connectId);
       } catch (error) {
-        void connectPromise.then(
-          (orphan) => this._connector.disconnect(orphan.sessionId).catch(() => void 0),
-          () => void 0
-        );
+        releaseOperation();
+        throw error;
+      }
+      if (!signal) {
+        try {
+          return await connectPromise;
+        } finally {
+          releaseOperation();
+        }
+      }
+      try {
+        const session2 = await _TrezorAdapter._abortable(signal, connectPromise);
+        releaseOperation();
+        return session2;
+      } catch (error) {
+        if (signal.aborted) {
+          void connectPromise.then((orphan) => this._connector.disconnect(orphan.sessionId).catch(() => void 0)).catch(() => void 0).finally(releaseOperation);
+        } else {
+          releaseOperation();
+        }
         throw error;
       }
     };
@@ -1092,8 +1191,13 @@ var _TrezorAdapter = class _TrezorAdapter {
       });
       session = await connectOnce();
     }
-    if (this._disconnectRequested.delete(connectId)) {
-      await this._connector.disconnect(session.sessionId).catch(() => void 0);
+    if (signal?.aborted || stateGeneration !== this._stateGeneration || this._disconnectRequested.delete(connectId)) {
+      const releaseCleanup = this._retainConnectorOperation(`disconnect:${session.sessionId}`);
+      try {
+        await this._connector.disconnect(session.sessionId).catch(() => void 0);
+      } finally {
+        releaseCleanup();
+      }
       throw Object.assign(new Error("Trezor connection aborted"), {
         code: HardwareErrorCode.UserAborted
       });
@@ -1109,14 +1213,9 @@ var _TrezorAdapter = class _TrezorAdapter {
   async init(_config) {
   }
   async dispose() {
+    await this._resetStateAndDisconnectSessions();
     this._unregisterConnectorEvents();
-    this._uiRegistry.reset();
-    this._jobQueue.clear();
     this._connector.reset();
-    this._devices.clear();
-    this._sessions.clear();
-    this._verifiedPassphraseSessionsByConnectId.clear();
-    this._connectingPromises.clear();
     this._emitter.removeAllListeners();
   }
   /**
@@ -1125,12 +1224,30 @@ var _TrezorAdapter = class _TrezorAdapter {
    * error flows. Aborts active jobs and releases UI waits.
    */
   resetState() {
+    void this._resetStateAndDisconnectSessions();
+  }
+  _resetStateAndDisconnectSessions() {
+    if (this._resetPromise) return this._resetPromise;
+    const sessionIds = new Set(this._sessions.values());
+    this._stateGeneration += 1;
+    this._operations.endAll("runtime-reset");
     this._uiRegistry.reset();
     this._jobQueue.clear();
     this._devices.clear();
     this._sessions.clear();
     this._verifiedPassphraseSessionsByConnectId.clear();
     this._connectingPromises.clear();
+    const resetPromise = this._runConnectorTeardown(async () => {
+      for (const sessionId of sessionIds) {
+        await this._connector.disconnect(sessionId).catch(() => void 0);
+      }
+    });
+    this._resetPromise = resetPromise;
+    return resetPromise.finally(() => {
+      if (this._resetPromise === resetPromise) {
+        this._resetPromise = null;
+      }
+    });
   }
   getAvailableTransports() {
     return this.activeTransport ? [this.activeTransport] : [];
@@ -1138,32 +1255,162 @@ var _TrezorAdapter = class _TrezorAdapter {
   async switchTransport(_type) {
   }
   async searchDevices(options) {
-    await this._ensureDevicePermission();
+    await this._ensureDevicePermission(void 0, void 0, options?.transportType);
+    return this._searchDevices(options);
+  }
+  async _searchDevices(options, signal) {
+    if (options?.transportType && !this._availableTransports().includes(options.transportType))
+      return [];
+    if (options?.resetSession) {
+      await this._resetStateAndDisconnectSessions();
+    } else {
+      await this._connectorTeardownTail;
+    }
+    if (signal?.aborted) throw signal.reason;
+    const stateGeneration = this._stateGeneration;
     const scanned = await this._connector.searchDevices(
-      options?.waitForAllTransports ? { waitForAll: true } : void 0
+      options?.waitForAllTransports || options?.transportType ? {
+        ...options.waitForAllTransports ? { waitForAll: true } : {},
+        ...options.transportType ? { transportType: options.transportType } : {}
+      } : void 0
     );
+    if (signal?.aborted) throw signal.reason;
+    if (stateGeneration !== this._stateGeneration) {
+      throw createHwkError({
+        code: HardwareErrorCode.UserAborted,
+        message: "Trezor discovery belongs to an ended operation"
+      });
+    }
     const scannedIds = new Set(scanned.map((d) => d.connectId));
     for (const connectId of [...this._devices.keys()]) {
-      if (!scannedIds.has(connectId) && !this._sessions.has(connectId)) {
+      if ((!options?.transportType || this._devices.get(connectId)?.connectionType === options.transportType) && !scannedIds.has(connectId) && !this._sessions.has(connectId)) {
         this._devices.delete(connectId);
       }
     }
     for (const device of scanned) {
       const info = this._connectorDeviceToDeviceInfo(device);
-      this._devices.set(info.connectId, info);
+      if (!this._sessions.has(info.connectId)) this._devices.set(info.connectId, info);
     }
-    return Array.from(this._devices.values());
+    return Array.from(this._devices.values()).filter(
+      (device) => !options?.transportType || device.connectionType === options.transportType
+    );
   }
-  async connectDevice(connectId) {
+  async searchDeviceTargets(options) {
+    const devices = await this.searchDevices(options);
+    return devices.map((device) => ({
+      searchTargetId: device.connectId,
+      searchTargetReusePolicy: resolveSearchTargetReusePolicy(device),
+      vendor: "trezor",
+      connectionType: device.connectionType,
+      kind: "physical",
+      label: device.label,
+      model: device.model,
+      modelName: device.modelName,
+      serialNumber: device.serialNumber
+    }));
+  }
+  async listConnectionTargets(options) {
+    const targets = await this.searchDeviceTargets(options);
+    return targets.map(({ searchTargetId, ...target }) => ({
+      ...target,
+      targetId: searchTargetId
+    }));
+  }
+  async bindBleDevice(params) {
+    if (params.identity?.vendor !== "trezor" || !params.identity.value) {
+      return failure(HardwareErrorCode.InvalidParams, "Trezor device identity is required");
+    }
+    const { value: deviceId } = params.identity;
     try {
-      await this._ensureDevicePermission(connectId);
-      await this._ensureSession(connectId);
-      return success(connectId);
+      return await this._jobQueue.enqueue(
+        deviceId,
+        async (signal) => {
+          const selected = await this._selectBleDeviceForBinding(
+            deviceId,
+            signal,
+            { extra: params.extra },
+            "manual-rebind"
+          );
+          try {
+            const persisted = await this._emitVerifiedBinding(
+              deviceId,
+              selected.connectId,
+              selected.selectionRequestId,
+              { extra: params.extra },
+              signal
+            );
+            if (!persisted) {
+              throw createHwkError({
+                code: HardwareErrorCode.UnknownError,
+                message: "Bluetooth binding could not be saved",
+                origin: "host"
+              });
+            }
+            this._rememberVerifiedConnection(deviceId, selected.connectId);
+            return success(selected.connectId);
+          } catch (error) {
+            await this._releaseProvisionalConnection(selected.connectId, signal);
+            throw error;
+          }
+        },
+        {
+          label: "bindBleDevice",
+          rejectIfBusy: true,
+          busyError: _TrezorAdapter._createDeviceBusyError("bindBleDevice")
+        }
+      );
     } catch (error) {
       return this._errorToFailure(error);
     }
   }
-  async disconnectDevice(connectId) {
+  async connectDevice(searchTargetId) {
+    const scope = this._jobQueue.createCancelScope(searchTargetId);
+    try {
+      await _TrezorAdapter._abortable(
+        scope.signal,
+        this._ensureDevicePermission(
+          searchTargetId,
+          void 0,
+          this._devices.get(searchTargetId)?.connectionType
+        )
+      );
+      await this._ensureSession(searchTargetId, scope.signal);
+      if (scope.signal.aborted) throw scope.signal.reason;
+      const device = this._devices.get(searchTargetId);
+      if (!device) {
+        return failure(HardwareErrorCode.DeviceNotFound, "Trezor device not found after connect");
+      }
+      this._operations.endByConnectionKey(searchTargetId, "explicit");
+      const operation = this._operations.create({
+        searchTargetId,
+        connectId: searchTargetId,
+        device,
+        connectionType: device.connectionType,
+        connectionKeys: [this._sessions.get(searchTargetId) ?? ""]
+      });
+      return success(operation.operationId);
+    } catch (error) {
+      if (scope.signal.aborted) {
+        await this._waitForConnectorOperationsToDrain();
+        return failure(HardwareErrorCode.UserAborted, "Trezor connection aborted");
+      }
+      return this._errorToFailure(error);
+    } finally {
+      scope.release();
+    }
+  }
+  async releaseOperation(operationId) {
+    const operation = this._operations.find(operationId);
+    if (!operation) {
+      this._operations.resolve(operationId);
+      return;
+    }
+    const endedOperation = this._operations.end(operationId, "explicit");
+    if (!endedOperation) return;
+    await this._releaseOperationConnection(endedOperation);
+  }
+  async _releaseOperationConnection(operation) {
+    const { connectId } = operation;
     const connecting = this._connectingPromises.has(connectId);
     this._connectingPromises.delete(connectId);
     const sessionId = this._sessions.get(connectId);
@@ -1171,90 +1418,131 @@ var _TrezorAdapter = class _TrezorAdapter {
       if (connecting) this._disconnectRequested.add(connectId);
       return;
     }
-    this._sessions.delete(connectId);
-    this._verifiedPassphraseSessionsByConnectId.delete(connectId);
-    await this._connector.disconnect(sessionId);
+    await this._disconnectSession(connectId, sessionId);
   }
-  async getDeviceInfo(connectId, deviceId) {
+  async getDeviceInfo(connectIdOrOperationId, deviceId) {
+    let connectId;
+    try {
+      connectId = isHardwareOperationId(connectIdOrOperationId) ? this._operations.resolve(connectIdOrOperationId).connectId : connectIdOrOperationId;
+    } catch (error) {
+      return this._errorToFailure(error);
+    }
     const device = this._devices.get(connectId) ?? Array.from(this._devices.values()).find((item) => item.deviceId === deviceId);
     if (!device) return failure(HardwareErrorCode.DeviceNotFound, "Trezor device not found");
     return success(device);
   }
-  getSupportedChains() {
-    return ["btc", "evm", "sol", "tron"];
-  }
   async allNetworkGetAddress(connectId, deviceId, params) {
+    const target = resolveHardwareOperationTarget(connectId, params.operationId, "trezor");
+    if (!target.success) return target;
+    let effectiveTargetId = target.payload.targetId ?? "";
+    let releaseOperationRetention;
+    try {
+      releaseOperationRetention = target.payload.operationId ? this._operations.retain(target.payload.operationId) : void 0;
+    } catch (error) {
+      return this._errorToFailure(error);
+    }
+    const cancelScope = this._jobQueue.createCancelScope(
+      trezorQueueKey({ operationId: target.payload.operationId, connectId: effectiveTargetId })
+    );
     let liveDeviceId = "";
+    const bundleContext = {};
     const topLevelFailureIndexes = /* @__PURE__ */ new Set();
     const isSingleNetworkBundle = params.bundle.every(
       (item) => item.network === params.bundle[0]?.network
     );
-    const getLiveDeviceId = async () => {
+    const getLiveDeviceId = async (expectedDeviceId) => {
       if (liveDeviceId) return success(liveDeviceId);
-      const deviceIdResponse = await this._getTrezorDeviceId(connectId);
+      const deviceIdResponse = await this._getTrezorDeviceId(
+        effectiveTargetId,
+        expectedDeviceId || deviceId,
+        params,
+        bundleContext
+      );
       if (deviceIdResponse.success) {
         liveDeviceId = deviceIdResponse.payload;
+        if (!target.payload.operationId) {
+          effectiveTargetId = bundleContext.connection?.connectId ?? effectiveTargetId;
+        }
       }
       return deviceIdResponse;
     };
-    return runAllNetworkGetAddress({
-      connectId,
-      deviceId,
-      params,
-      normalizeItem: _TrezorAdapter._normalizeAllNetworkItem,
-      callItem: async ({ method, item, index }) => {
-        const expectedDeviceId = _TrezorAdapter._getItemDeviceId(item) ?? deviceId;
-        if (expectedDeviceId) {
-          const fingerprint = await getLiveDeviceId();
-          if (!fingerprint.success) {
+    try {
+      return await runAllNetworkGetAddress({
+        connectId: effectiveTargetId,
+        deviceId,
+        params,
+        normalizeItem: _TrezorAdapter._normalizeAllNetworkItem,
+        callItem: async ({ method, item, index }) => {
+          if (cancelScope.signal.aborted) {
             topLevelFailureIndexes.add(index);
-            return fingerprint;
+            return _TrezorAdapter._buildCancelledFailure(cancelScope.signal);
           }
-          if (expectedDeviceId !== fingerprint.payload) {
-            topLevelFailureIndexes.add(index);
-            return failure(
-              HardwareErrorCode.DeviceMismatch,
-              `Wrong device: expected ${expectedDeviceId}, got ${fingerprint.payload}`,
-              { expected: expectedDeviceId, actual: fingerprint.payload }
-            );
+          const expectedDeviceId = _TrezorAdapter._getItemDeviceId(item) ?? deviceId;
+          if (expectedDeviceId) {
+            const fingerprint = await getLiveDeviceId(expectedDeviceId);
+            if (!fingerprint.success) {
+              topLevelFailureIndexes.add(index);
+              return fingerprint;
+            }
+            if (expectedDeviceId !== fingerprint.payload) {
+              topLevelFailureIndexes.add(index);
+              return failure(
+                HardwareErrorCode.DeviceMismatch,
+                `Wrong device: expected ${expectedDeviceId}, got ${fingerprint.payload}`,
+                { expected: expectedDeviceId, actual: fingerprint.payload }
+              );
+            }
           }
-        }
-        const callItem = _TrezorAdapter._withAllNetworkRequestCommonParams(item, params);
-        return this._callAllNetworkMethod(connectId, method, callItem);
-      },
-      attachIdentity: async ({ item, chain, payload }) => {
-        if (!liveDeviceId) {
-          const fingerprint = await getLiveDeviceId();
-          if (!fingerprint.success) {
-            return { ...item, success: false, payload: fingerprint.payload };
+          const callItem = _TrezorAdapter._withAllNetworkRequestCommonParams(item, params);
+          return this._callAllNetworkMethod(effectiveTargetId, method, callItem, bundleContext);
+        },
+        attachIdentity: async ({ item, chain, payload, index }) => {
+          if (!liveDeviceId) {
+            if (cancelScope.signal.aborted) {
+              topLevelFailureIndexes.add(index);
+              const cancelled = _TrezorAdapter._buildCancelledFailure(cancelScope.signal);
+              return { ...item, success: false, payload: cancelled.payload };
+            }
+            const fingerprint = await getLiveDeviceId(deviceId);
+            if (!fingerprint.success) {
+              return { ...item, success: false, payload: fingerprint.payload };
+            }
           }
+          return {
+            ...item,
+            success: true,
+            payload: {
+              ...payload,
+              deviceIdentity: {
+                vendor: "trezor",
+                type: "deviceId",
+                value: liveDeviceId
+              },
+              chainFingerprint: liveDeviceId,
+              chainFingerprintChain: chain
+            }
+          };
+        },
+        // One named boolean per abort reason.
+        shouldAbortBundle: (response, { index }) => {
+          const isSessionLevelFailure = topLevelFailureIndexes.has(index);
+          const isWholeChainForbidden = isSingleNetworkBundle && response.payload?.code === HardwareErrorCode.DevicePathForbidden;
+          const { code } = response.payload ?? {};
+          return isSessionLevelFailure || isWholeChainForbidden || isWalletSafetyFailure(code) || isUserRefusal(code) || isConnectionLost(code);
         }
-        return {
-          ...item,
-          success: true,
-          payload: {
-            ...payload,
-            deviceIdentity: {
-              vendor: "trezor",
-              type: "deviceId",
-              value: liveDeviceId
-            },
-            chainFingerprint: liveDeviceId,
-            chainFingerprintChain: chain
-          }
-        };
-      },
-      // One named boolean per abort reason.
-      shouldAbortBundle: (response, { index }) => {
-        const isSessionLevelFailure = topLevelFailureIndexes.has(index);
-        const isWholeChainForbidden = isSingleNetworkBundle && response.payload?.code === HardwareErrorCode.DevicePathForbidden;
-        const isPassphrasePolicyFailure = response.payload?.code === HardwareErrorCode.PassphraseAlwaysOnDevice;
-        return isSessionLevelFailure || isWholeChainForbidden || isPassphrasePolicyFailure;
-      }
-    });
+      });
+    } finally {
+      cancelScope.release();
+      releaseOperationRetention?.();
+    }
   }
-  getFeatures(connectId) {
-    return this._callDeviceManagerMethod("getFeatures", connectId, {});
+  getFeatures(connectId, operationContext) {
+    return this._callDeviceManagerMethod(
+      "getFeatures",
+      connectId,
+      {},
+      operationContext
+    );
   }
   /**
    * Device authenticity attestation. Sends a host-generated challenge, has the
@@ -1314,28 +1602,65 @@ var _TrezorAdapter = class _TrezorAdapter {
       }
     });
   }
-  deviceSettings(connectId, params) {
+  deviceSettings(connectId, params, operationContext) {
     return this._callDeviceManagerMethod(
       "deviceSettings",
       connectId,
-      params
+      params,
+      operationContext
     );
   }
-  setBrightness(connectId, params = {}) {
+  setBrightness(connectId, params = {}, operationContext) {
     return this._callDeviceManagerMethod(
       "setBrightness",
       connectId,
-      params
+      params,
+      operationContext
     );
   }
-  changePin(connectId, params = {}) {
-    return this._callDeviceManagerMethod("changePin", connectId, params);
+  changePin(connectId, params = {}, operationContext) {
+    return this._callDeviceManagerMethod(
+      "changePin",
+      connectId,
+      params,
+      operationContext
+    );
   }
-  wipeDevice(connectId) {
-    return this._callDeviceManagerMethod("wipeDevice", connectId, {});
+  wipeDevice(connectId, operationContext) {
+    return this._callDeviceManagerMethod(
+      "wipeDevice",
+      connectId,
+      {},
+      operationContext
+    );
   }
-  async _getTrezorDeviceId(connectId) {
-    const features = await this.getFeatures(connectId);
+  async _getTrezorDeviceId(connectId, expectedDeviceId, commonParams, bundleContext) {
+    const hasConnectionContext = commonParams?.knownConnections !== void 0 || commonParams?.extra !== void 0;
+    const features = bundleContext || hasConnectionContext ? await this._callMethod(
+      "getFeatures",
+      connectId,
+      hasConnectionContext || !connectId ? expectedDeviceId : void 0,
+      hasConnectionContext ? {
+        operationId: commonParams.operationId,
+        knownConnections: commonParams.knownConnections,
+        extra: commonParams.extra,
+        allowDeviceSelection: commonParams.allowDeviceSelection,
+        supportedTransports: commonParams.supportedTransports,
+        passphraseState: commonParams.passphraseState,
+        useEmptyPassphrase: commonParams.useEmptyPassphrase
+      } : {},
+      false,
+      bundleContext
+    ) : await this.getFeatures(
+      connectId,
+      !connectId && expectedDeviceId ? {
+        expectedDeviceIdentity: {
+          vendor: "trezor",
+          type: "deviceId",
+          value: expectedDeviceId
+        }
+      } : void 0
+    );
     if (!features.success) return features;
     const liveDeviceId = features.payload.device_id;
     if (typeof liveDeviceId !== "string" || liveDeviceId.length === 0) {
@@ -1344,23 +1669,67 @@ var _TrezorAdapter = class _TrezorAdapter {
     return success(liveDeviceId);
   }
   cancel(connectId) {
+    if (isHardwareOperationId(connectId)) {
+      try {
+        this._operations.resolve(connectId);
+      } catch {
+        return;
+      }
+    }
     const userAbortReason = Object.assign(new Error("User aborted operation"), {
       code: HardwareErrorCode.UserAborted
     });
-    this._uiRegistry.cancel();
-    this._connector.uiResponse({ type: UI_RESPONSE.CANCEL });
-    if (connectId) {
-      this._jobQueue.forceCancelActive(connectId, userAbortReason);
-      void this._connector.cancel(this._sessions.get(connectId) ?? connectId);
+    const activeJobId = this._jobQueue.getActiveJob()?.deviceId;
+    const targetId = connectId ?? activeJobId;
+    if (targetId) {
+      let resolvedConnectId = targetId;
+      let operationId;
+      if (isHardwareOperationId(targetId)) {
+        try {
+          operationId = targetId;
+          resolvedConnectId = this._operations.resolve(targetId).connectId;
+        } catch {
+          resolvedConnectId = "";
+        }
+      }
+      const interactionForPhysicalId = !operationId && connectId ? this._operations.findActiveByConnectionKey(connectId) : void 0;
+      const pendingOperationId = operationId ?? interactionForPhysicalId?.operationId;
+      if (!connectId) {
+        this._uiRegistry.cancel();
+      } else if (pendingOperationId) {
+        this._uiRegistry.cancel(void 0, void 0, pendingOperationId);
+      }
+      const queueKeys = /* @__PURE__ */ new Set([trezorQueueKey({ connectId: targetId })]);
+      if (pendingOperationId) queueKeys.add(trezorQueueKey({ operationId: pendingOperationId }));
+      const ownsConnectorInteraction = activeJobId !== void 0 ? queueKeys.has(activeJobId) || pendingOperationId !== void 0 && this._activeOperationId() === pendingOperationId : this._connectingPromises.size === 1 && this._connectingPromises.has(resolvedConnectId);
+      if (connectId === void 0 || ownsConnectorInteraction) {
+        this._connector.uiResponse({ type: UI_RESPONSE.CANCEL });
+      }
+      for (const key of queueKeys) {
+        this._jobQueue.cancelActiveAndPending(key, userAbortReason);
+      }
+      if (resolvedConnectId) {
+        void this._connector.cancel(this._sessions.get(resolvedConnectId) ?? resolvedConnectId);
+      }
       return;
     }
-    for (const cid of this._sessions.keys()) {
-      this._jobQueue.forceCancelActive(cid, userAbortReason);
-    }
+    this._uiRegistry.cancel();
+    this._connector.uiResponse({ type: UI_RESPONSE.CANCEL });
+    this._jobQueue.cancelActiveAndPending(void 0, userAbortReason);
     for (const sessionId of this._sessions.values()) {
       void this._connector.cancel(sessionId);
     }
   }
+  /**
+   * Operation owning the running job: its queue key when pinned, else the live
+   * operation of its connectId, so a mid-call UI request can name it.
+   */
+  _activeOperationId() {
+    const activeJobId = this._jobQueue.getActiveJob()?.deviceId;
+    if (!activeJobId) return void 0;
+    if (isHardwareOperationId(activeJobId)) return activeJobId;
+    return this._operations.findActiveByConnectionKey(activeJobId)?.operationId;
+  }
   /**
    * Routes to BOTH the adapter's local UI registry (preemption decisions,
    * future SELECT_DEVICE / DEVICE_PERMISSION) AND the connector's registry
@@ -1369,6 +1738,7 @@ var _TrezorAdapter = class _TrezorAdapter {
    */
   uiResponse(response) {
     this._uiRegistry.resolve(response.type, response.payload);
+    if (response.type === UI_RESPONSE.RECEIVE_SELECT_DEVICE) return;
     this._connector.uiResponse(response);
   }
   /**
@@ -1380,8 +1750,8 @@ var _TrezorAdapter = class _TrezorAdapter {
    * Unlike Ledger (which hashes a per-chain address), it is chain-global, so
    * `chain` is accepted for API parity but ignored.
    */
-  async getChainFingerprint(connectId, _deviceId, _chain) {
-    return this._getTrezorDeviceId(connectId);
+  async getChainFingerprint(connectId, deviceId, _chain) {
+    return this._getTrezorDeviceId(connectId, deviceId);
   }
   /**
    * Resolve the active passphrase wallet identity (`passphraseState`).
@@ -1391,17 +1761,87 @@ var _TrezorAdapter = class _TrezorAdapter {
    * can't interleave with a chain call on the same device (which would desync
    * the THP session selection).
    */
-  getPassphraseState(connectId, passphraseState) {
-    return this._jobQueue.enqueue(
+  getPassphraseState(connectId, passphraseState, operationContext) {
+    const expectedIdentity = operationContext?.expectedDeviceIdentity;
+    if (expectedIdentity && (expectedIdentity.vendor !== "trezor" || expectedIdentity.type !== "deviceId")) {
+      return Promise.resolve(
+        failure(HardwareErrorCode.InvalidParams, "Trezor device identity is required")
+      );
+    }
+    const target = resolveHardwareOperationTarget(
       connectId,
+      operationContext?.operationId,
+      "trezor"
+    );
+    if (!target.success) return Promise.resolve(target);
+    const { operationId } = target.payload;
+    let resolvedConnectId = target.payload.targetId ?? "";
+    let releaseOperationRetention;
+    if (operationId) {
+      try {
+        resolvedConnectId = this._operations.resolve(operationId).connectId;
+        releaseOperationRetention = this._operations.retain(operationId);
+      } catch (error) {
+        return Promise.resolve(this._errorToFailure(error));
+      }
+    }
+    return this._jobQueue.enqueue(
+      trezorQueueKey({ operationId, connectId: resolvedConnectId }),
       async (signal) => {
-        const restorePassphraseRequestContext = this._setPassphraseRequestContext(connectId, {
-          passphraseState
-        });
+        let selectionRequestId;
+        let verified = false;
         try {
-          return await this._resolvePassphraseState(connectId, passphraseState, signal);
+          if (!operationId && expectedIdentity?.value && (!connectId || operationContext?.knownConnections !== void 0)) {
+            const resolved = await this._resolveExpectedDeviceConnectId(
+              expectedIdentity.value,
+              signal,
+              operationContext
+            );
+            resolvedConnectId = resolved.connectId;
+            selectionRequestId = resolved.selectionRequestId;
+          }
+          if (expectedIdentity?.value) {
+            if (!operationId) await this._ensureSession(resolvedConnectId, signal);
+            if (this._devices.get(resolvedConnectId)?.deviceId !== expectedIdentity.value) {
+              return failure(
+                HardwareErrorCode.DeviceMismatch,
+                "Trezor device identity does not match"
+              );
+            }
+          }
+          const restorePassphraseRequestContext = this._setPassphraseRequestContext(
+            resolvedConnectId,
+            {
+              passphraseState
+            }
+          );
+          try {
+            const result = await this._resolvePassphraseState(
+              resolvedConnectId,
+              passphraseState,
+              signal,
+              operationId
+            );
+            if (result.success && expectedIdentity?.value) {
+              await this._emitVerifiedBinding(
+                expectedIdentity.value,
+                resolvedConnectId,
+                selectionRequestId,
+                operationContext,
+                signal
+              );
+              verified = true;
+              this._rememberVerifiedConnection(expectedIdentity.value, resolvedConnectId);
+            }
+            return result;
+          } finally {
+            restorePassphraseRequestContext();
+          }
         } finally {
-          restorePassphraseRequestContext();
+          if (selectionRequestId && !verified) {
+            this._emitBindingStatus(selectionRequestId, signal.aborted ? "cancelled" : "failed");
+            await this._releaseProvisionalConnection(resolvedConnectId, signal);
+          }
         }
       },
       {
@@ -1409,7 +1849,7 @@ var _TrezorAdapter = class _TrezorAdapter {
         rejectIfBusy: true,
         busyError: _TrezorAdapter._createDeviceBusyError("getPassphraseState")
       }
-    ).catch((error) => this._errorToFailure(error));
+    ).catch((error) => this._errorToFailure(error)).finally(() => releaseOperationRetention?.());
   }
   evmGetAddress(connectId, deviceId, params) {
     return this._callWalletMethod("evmGetAddress", connectId, deviceId, params);
@@ -1472,11 +1912,94 @@ var _TrezorAdapter = class _TrezorAdapter {
     }
     return result;
   }
-  static async _callConnector(connector, sessionId, method, params, signal) {
-    const promise = connector.call(sessionId, method, params);
+  async _callConnector(sessionId, method, params, signal) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new Error("Aborted");
+    }
+    this._assertConnectorIdle(method);
+    const releaseOperation = this._retainConnectorOperation(`call:${sessionId}`);
+    let promise;
+    try {
+      promise = this._connector.call(sessionId, method, params).finally(() => {
+        releaseOperation();
+      });
+    } catch (error) {
+      releaseOperation();
+      throw error;
+    }
     const result = signal ? await _TrezorAdapter._abortable(signal, promise) : await promise;
     return _TrezorAdapter._unwrapConnectorResult(result);
   }
+  _assertConnectorIdle(method) {
+    if (this._resetPromise || this._pendingConnectorTeardowns > 0 || this._unsettledConnectorOperations.size > 0) {
+      throw _TrezorAdapter._createDeviceBusyError(method);
+    }
+  }
+  _runConnectorTeardown(task) {
+    const previous = this._connectorTeardownTail;
+    let releaseTail = () => void 0;
+    this._connectorTeardownTail = new Promise((resolve) => {
+      releaseTail = resolve;
+    });
+    this._pendingConnectorTeardowns += 1;
+    return (async () => {
+      try {
+        await previous;
+        await this._waitForConnectorOperationsToDrain();
+        await task();
+      } finally {
+        this._pendingConnectorTeardowns -= 1;
+        releaseTail();
+      }
+    })();
+  }
+  async _disconnectSession(connectId, sessionId = this._sessions.get(connectId)) {
+    this._sessions.delete(connectId);
+    this._verifiedPassphraseSessionsByConnectId.delete(connectId);
+    if (sessionId) await this._runConnectorTeardown(() => this._connector.disconnect(sessionId));
+  }
+  _availableTransports() {
+    return this._connector.availableTransports ?? [this._connector.connectionType];
+  }
+  async _releaseProvisionalConnection(connectId, signal) {
+    const sessionId = this._sessions.get(connectId);
+    this._sessions.delete(connectId);
+    this._verifiedPassphraseSessionsByConnectId.delete(connectId);
+    if (!sessionId) return;
+    const teardown = this._runConnectorTeardown(() => this._connector.disconnect(sessionId)).catch(
+      () => void 0
+    );
+    if (!signal.aborted) await teardown;
+  }
+  _waitForConnectorOperationsToDrain() {
+    if (this._unsettledConnectorOperations.size === 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this._connectorIdleWaiters.add(resolve);
+    });
+  }
+  _retainConnectorOperation(key) {
+    this._unsettledConnectorOperations.set(
+      key,
+      (this._unsettledConnectorOperations.get(key) ?? 0) + 1
+    );
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const remaining = (this._unsettledConnectorOperations.get(key) ?? 1) - 1;
+      if (remaining > 0) {
+        this._unsettledConnectorOperations.set(key, remaining);
+      } else {
+        this._unsettledConnectorOperations.delete(key);
+      }
+      if (this._unsettledConnectorOperations.size === 0) {
+        for (const resolve of this._connectorIdleWaiters) resolve();
+        this._connectorIdleWaiters.clear();
+      }
+    };
+  }
   static _normalizeAllNetworkItem(method, item) {
     if (method !== "btcGetAddress" && method !== "btcGetPublicKey") {
       return item;
@@ -1495,18 +2018,21 @@ var _TrezorAdapter = class _TrezorAdapter {
     const { deviceId } = item;
     return typeof deviceId === "string" && deviceId.length > 0 ? deviceId : void 0;
   }
-  _callAllNetworkMethod(connectId, method, item) {
+  /** UserAborted is a top-level abort code, so this ends the bundle. */
+  static _buildCancelledFailure(signal) {
+    const reason = signal.reason;
+    const code = typeof reason?.code === "number" ? reason.code : HardwareErrorCode.UserAborted;
+    const message = typeof reason?.message === "string" ? reason.message : "";
+    return failure(code, message || "All-network get-address cancelled");
+  }
+  _callAllNetworkMethod(connectId, method, item, bundleContext) {
     switch (method) {
       case "evmGetAddress":
-        return this.evmGetAddress(connectId, "", item);
       case "btcGetAddress":
-        return this.btcGetAddress(connectId, "", item);
       case "btcGetPublicKey":
-        return this.btcGetPublicKey(connectId, "", item);
       case "solGetAddress":
-        return this.solGetAddress(connectId, "", item);
       case "tronGetAddress":
-        return this.tronGetAddress(connectId, "", item);
+        return this._callMethod(method, connectId, "", item, true, bundleContext);
       default:
         return Promise.resolve(
           failure(
@@ -1525,11 +2051,51 @@ var _TrezorAdapter = class _TrezorAdapter {
   _callWalletMethod(methodName, connectId, deviceId, params) {
     return this._callMethod(methodName, connectId, deviceId, params, true);
   }
-  _callDeviceManagerMethod(methodName, connectId, params) {
-    return this._callMethod(methodName, connectId, void 0, params, false);
+  _callDeviceManagerMethod(methodName, connectId, params, operationContext) {
+    const expectedIdentity = operationContext?.expectedDeviceIdentity;
+    if (expectedIdentity && (expectedIdentity.vendor !== "trezor" || expectedIdentity.type !== "deviceId")) {
+      return Promise.resolve(
+        failure(
+          HardwareErrorCode.InvalidParams,
+          "Trezor device-manager operations require a Trezor deviceId identity"
+        )
+      );
+    }
+    return this._callMethod(
+      methodName,
+      connectId,
+      expectedIdentity?.value,
+      {
+        ...params && typeof params === "object" ? params : {},
+        knownConnections: operationContext?.knownConnections,
+        extra: operationContext?.extra,
+        allowDeviceSelection: operationContext?.allowDeviceSelection,
+        supportedTransports: operationContext?.supportedTransports,
+        ...operationContext?.operationId ? { operationId: operationContext.operationId } : {}
+      },
+      false
+    );
   }
-  async _callMethod(methodName, connectId, deviceId, params, requiresWalletIntent) {
+  async _callMethod(methodName, connectId, deviceId, params, requiresWalletIntent, bundleContext) {
     const call = _TrezorAdapter._normalizeCallArgs(connectId, deviceId, params);
+    const commonParams = _TrezorAdapter._splitCommonParams(call.params);
+    const positionalOperationId = isHardwareOperationId(call.connectId) ? call.connectId : void 0;
+    if (positionalOperationId && commonParams.operationId && positionalOperationId !== commonParams.operationId) {
+      return failure(HardwareErrorCode.InvalidParams, "Conflicting Trezor operation ids", {
+        positionalOperationId,
+        commonOperationId: commonParams.operationId
+      });
+    }
+    const operationId = commonParams.operationId ?? positionalOperationId;
+    let releaseOperationRetention;
+    try {
+      if (operationId) {
+        call.connectId = this._operations.resolve(operationId).connectId;
+        releaseOperationRetention = this._operations.retain(operationId);
+      }
+    } catch (error) {
+      return this._errorToFailure(error);
+    }
     debugLog("[TrezorAdapter][REQ]", {
       method: methodName,
       connectId: call.connectId || "(empty)",
@@ -1538,15 +2104,40 @@ var _TrezorAdapter = class _TrezorAdapter {
     });
     try {
       const response = await this._jobQueue.enqueue(
-        call.connectId,
-        (signal) => this._callWithRetry(
-          call.connectId,
-          methodName,
-          call.params,
-          requiresWalletIntent,
-          true,
-          signal
-        ),
+        trezorQueueKey({ operationId, connectId: call.connectId }),
+        async (signal) => {
+          let effectiveConnectId = call.connectId;
+          let selectionRequestId;
+          try {
+            if (!bundleContext?.connection && !operationId && deviceId && (!connectId || commonParams.connectionContext?.knownConnections !== void 0)) {
+              const resolved = await this._resolveExpectedDeviceConnectId(
+                deviceId,
+                signal,
+                commonParams.connectionContext
+              );
+              effectiveConnectId = resolved.connectId;
+              selectionRequestId = resolved.selectionRequestId;
+            }
+          } catch (error) {
+            return this._errorToFailure(error);
+          }
+          const response2 = await this._callWithRetry(
+            bundleContext?.connection?.connectId ?? effectiveConnectId,
+            methodName,
+            call.params,
+            deviceId || "",
+            requiresWalletIntent,
+            true,
+            signal,
+            operationId,
+            selectionRequestId,
+            bundleContext
+          );
+          if (!response2.success && selectionRequestId) {
+            await this._releaseProvisionalConnection(effectiveConnectId, signal);
+          }
+          return response2;
+        },
         {
           label: methodName,
           rejectIfBusy: true,
@@ -1567,16 +2158,53 @@ var _TrezorAdapter = class _TrezorAdapter {
         payload: _TrezorAdapter._sanitizeForLog(response.payload, methodName)
       });
       return response;
+    } finally {
+      releaseOperationRetention?.();
     }
   }
-  async _callWithRetry(connectId, methodName, params, requiresWalletIntent, allowRetry, signal) {
-    const { passphraseState, useEmptyPassphrase, rest } = _TrezorAdapter._splitCommonParams(params);
+  async _callWithRetry(connectId, methodName, params, expectedDeviceId, requiresWalletIntent, allowRetry, signal, operationId, selectionRequestId, bundleContext) {
+    const { passphraseState, useEmptyPassphrase, rest, connectionContext } = _TrezorAdapter._splitCommonParams(params);
+    let pendingBindingRequestId = selectionRequestId;
+    let businessCallStarted = false;
     const restorePassphraseRequestContext = this._setPassphraseRequestContext(connectId, {
       passphraseState,
       useEmptyPassphrase
     });
     try {
-      const sessionId = await this._ensureSession(connectId, signal);
+      if (bundleContext?.connection) {
+        const pinned = bundleContext.connection;
+        if (this._sessions.get(pinned.connectId) !== pinned.sessionId) {
+          return failure(
+            HardwareErrorCode.DeviceDisconnected,
+            "Trezor all-network connection ended"
+          );
+        }
+      }
+      const sessionId = operationId ? this._sessions.get(this._operations.resolve(operationId).connectId) : await this._ensureSession(connectId, signal);
+      if (!sessionId) {
+        if (operationId) {
+          this._operations.end(operationId, "disconnect");
+          return failure(
+            HardwareErrorCode.OperationEnded,
+            "Trezor operation connection is no longer active",
+            { operationId, reason: "disconnect" }
+          );
+        }
+        return failure(HardwareErrorCode.DeviceNotFound, "Trezor session was not found");
+      }
+      if (bundleContext && !bundleContext.connection) {
+        bundleContext.connection = { connectId, sessionId };
+      }
+      if (expectedDeviceId) {
+        const actualDeviceId = this._devices.get(connectId)?.deviceId;
+        if (!actualDeviceId || actualDeviceId !== expectedDeviceId) {
+          return failure(
+            HardwareErrorCode.DeviceMismatch,
+            `Wrong device: expected ${expectedDeviceId}, got ${actualDeviceId || "unknown"}`,
+            { expected: expectedDeviceId, actual: actualDeviceId || "" }
+          );
+        }
+      }
       if (requiresWalletIntent && !passphraseState && useEmptyPassphrase !== true) {
         return failure(
           HardwareErrorCode.InvalidParams,
@@ -1591,39 +2219,85 @@ var _TrezorAdapter = class _TrezorAdapter {
       } else if (useEmptyPassphrase === true) {
         await _TrezorAdapter._abortable(signal, this._createFreshAppSession(sessionId, signal));
       }
+      if (expectedDeviceId) {
+        await this._emitVerifiedBinding(
+          expectedDeviceId,
+          connectId,
+          pendingBindingRequestId,
+          connectionContext,
+          signal
+        );
+        pendingBindingRequestId = void 0;
+        this._rememberVerifiedConnection(expectedDeviceId, connectId);
+      }
+      businessCallStarted = true;
       const result = await _TrezorAdapter._abortable(
         signal,
-        _TrezorAdapter._callConnector(this._connector, sessionId, methodName, rest)
+        this._callConnector(sessionId, methodName, rest, signal)
       );
       return success(result);
     } catch (error) {
       if (signal.aborted) {
+        if (pendingBindingRequestId) {
+          this._emitBindingStatus(pendingBindingRequestId, "cancelled");
+          pendingBindingRequestId = void 0;
+        }
         return this._errorToFailure(error);
       }
       const code = _TrezorAdapter._errorCode(error);
-      if (allowRetry && code === HardwareErrorCode.DeviceDisconnected) {
+      const willRetryStaleSession = allowRetry && (passphraseState || useEmptyPassphrase === true) && _TrezorAdapter._isStaleSessionError(code);
+      if (pendingBindingRequestId && !willRetryStaleSession) {
+        this._emitBindingStatus(pendingBindingRequestId, "failed");
+        pendingBindingRequestId = void 0;
+      }
+      const ambiguousTransportFailure = code === HardwareErrorCode.DeviceDisconnected || code === HardwareErrorCode.OperationTimeout || code === HardwareErrorCode.TransportError;
+      if (ambiguousTransportFailure) {
         this._sessions.delete(connectId);
         this._verifiedPassphraseSessionsByConnectId.delete(connectId);
-        return await this._callWithRetry(
-          connectId,
-          methodName,
-          params,
-          requiresWalletIntent,
-          false,
-          signal
-        );
+        const mayHaveCompleted = businessCallStarted && !canReplayHardwareMethodAfterTransportFailure(methodName);
+        const mayHaveCompletedMessage = `Trezor ${methodName} may have completed before the connection was lost`;
+        if (operationId) {
+          this._operations.end(operationId, "disconnect");
+          const endedParams = { operationId, reason: "disconnect" };
+          return mayHaveCompleted ? failure(
+            HardwareErrorCode.OperationEnded,
+            mayHaveCompletedMessage,
+            operationMayHaveCompletedParams(methodName, endedParams),
+            void 0,
+            { scope: "unknown" }
+          ) : failure(
+            HardwareErrorCode.OperationEnded,
+            "Trezor operation connection was lost",
+            endedParams
+          );
+        }
+        if (mayHaveCompleted) {
+          return failure(
+            code,
+            mayHaveCompletedMessage,
+            operationMayHaveCompletedParams(methodName),
+            void 0,
+            { scope: "unknown" }
+          );
+        }
       }
-      if (allowRetry && (passphraseState || useEmptyPassphrase === true) && _TrezorAdapter._isStaleSessionError(code)) {
+      if (willRetryStaleSession) {
         if (passphraseState) {
           this._forgetVerifiedPassphraseSession(connectId, passphraseState);
         }
+        const retryBindingRequestId = pendingBindingRequestId;
+        pendingBindingRequestId = void 0;
         return await this._callWithRetry(
           connectId,
           methodName,
           params,
+          expectedDeviceId,
           requiresWalletIntent,
           false,
-          signal
+          signal,
+          operationId,
+          retryBindingRequestId,
+          bundleContext
         );
       }
       debugLog("[TrezorAdapter][ERROR]", {
@@ -1634,36 +2308,252 @@ var _TrezorAdapter = class _TrezorAdapter {
       return this._errorToFailure(error);
     } finally {
       restorePassphraseRequestContext();
+      if (pendingBindingRequestId) {
+        this._emitBindingStatus(pendingBindingRequestId, signal.aborted ? "cancelled" : "failed");
+        pendingBindingRequestId = void 0;
+      }
     }
   }
-  async _ensureSession(connectId, signal) {
+  async _ensureSession(connectId, signal, transportType) {
     const existing = this._sessions.get(connectId);
     if (existing) return existing;
     const pending = this._connectingPromises.get(connectId);
     if (pending) return pending;
+    const stateGeneration = this._stateGeneration;
     const promise = (async () => {
+      if (signal?.aborted) {
+        throw Object.assign(new Error("Trezor connection aborted"), {
+          code: HardwareErrorCode.UserAborted
+        });
+      }
       try {
-        if (signal?.aborted) {
-          throw Object.assign(new Error("Trezor connection aborted"), {
-            code: HardwareErrorCode.UserAborted
-          });
-        }
-        try {
-          return await this._connectSession(connectId, signal);
-        } catch (error) {
-          if (_TrezorAdapter._isConnectionUnavailableError(error)) {
-            this._sessions.delete(connectId);
-            this._verifiedPassphraseSessionsByConnectId.delete(connectId);
-          }
-          throw error;
+        return await this._connectSession(connectId, signal, stateGeneration, transportType);
+      } catch (error) {
+        if (_TrezorAdapter._isConnectionUnavailableError(error)) {
+          this._sessions.delete(connectId);
+          this._verifiedPassphraseSessionsByConnectId.delete(connectId);
         }
-      } finally {
-        this._connectingPromises.delete(connectId);
-        this._disconnectRequested.delete(connectId);
+        throw error;
       }
     })();
     this._connectingPromises.set(connectId, promise);
-    return promise;
+    try {
+      return await promise;
+    } finally {
+      if (this._connectingPromises.get(connectId) === promise) {
+        this._connectingPromises.delete(connectId);
+      }
+      this._disconnectRequested.delete(connectId);
+    }
+  }
+  /** An identity probe tears down only a session it opened; another caller's stays up. */
+  _hasSessionOrConnect(connectId) {
+    return this._sessions.has(connectId) || this._connectingPromises.has(connectId);
+  }
+  async _resolveExpectedDeviceConnectId(expectedDeviceId, signal, context) {
+    const connectedMatch = Array.from(this._devices.values()).find(
+      (device) => device.deviceId === expectedDeviceId && this._sessions.has(device.connectId)
+    );
+    if (connectedMatch) return { connectId: connectedMatch.connectId };
+    const availableTransports = this._availableTransports();
+    if (availableTransports.includes("usb")) {
+      await _TrezorAdapter._abortable(
+        signal,
+        this._ensureDevicePermission(void 0, expectedDeviceId, "usb")
+      );
+    }
+    const candidates = await _TrezorAdapter._abortable(
+      signal,
+      this._searchDevices({ transportType: "usb" }, signal)
+    );
+    const mismatchedDeviceIds = [];
+    const knownConnection = this._knownDeviceConnections.get(expectedDeviceId);
+    const knownUsbIds = context?.knownConnections !== void 0 ? context.knownConnections.flatMap(
+      (connection) => connection.transport === "usb" ? [connection.connectId] : []
+    ) : [knownConnection?.usbConnectId].filter((id) => Boolean(id));
+    const suppliedBleIds = context?.knownConnections?.flatMap(
+      (connection) => connection.transport === "ble" ? [connection.connectId] : []
+    );
+    const knownBleIds = suppliedBleIds?.length ? suppliedBleIds : [knownConnection?.bleConnectId].filter((id) => Boolean(id));
+    const usbCandidates = candidates.filter(
+      (device) => device.connectionType === "usb" && (!knownUsbIds.length || knownUsbIds.includes(device.connectId))
+    );
+    for (const candidate of usbCandidates) {
+      let sessionId;
+      const probeOpensSession = !this._hasSessionOrConnect(candidate.connectId);
+      try {
+        sessionId = await this._ensureSession(candidate.connectId, signal, "usb");
+        const actualDeviceId = this._devices.get(candidate.connectId)?.deviceId ?? "";
+        if (actualDeviceId === expectedDeviceId) return { connectId: candidate.connectId };
+        mismatchedDeviceIds.push(actualDeviceId || "unknown");
+      } catch (error) {
+        if (signal.aborted) throw error;
+        if (!_TrezorAdapter._isConnectionUnavailableError(error)) throw error;
+      }
+      if (sessionId && probeOpensSession) {
+        await this._disconnectSession(candidate.connectId, sessionId);
+      }
+    }
+    if (mismatchedDeviceIds.length) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceSearchMismatch,
+        message: "The connected Trezor is not the wallet this operation needs. Unplug it and connect the right device.",
+        params: { connectedDeviceIds: mismatchedDeviceIds }
+      });
+    }
+    if (usbCandidates.length > 0) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceNotFound,
+        message: "Trezor devices are present but none could be opened to check its identity."
+      });
+    }
+    const [knownBleConnectId] = knownBleIds;
+    if (knownBleConnectId && availableTransports.includes("ble")) {
+      await _TrezorAdapter._abortable(
+        signal,
+        this._ensureDevicePermission(knownBleConnectId, expectedDeviceId, "ble")
+      );
+      const probeOpensSession = !this._hasSessionOrConnect(knownBleConnectId);
+      await this._ensureSession(knownBleConnectId, signal, "ble");
+      const actualDeviceId = this._devices.get(knownBleConnectId)?.deviceId;
+      if (actualDeviceId === expectedDeviceId) return { connectId: knownBleConnectId };
+      if (probeOpensSession) await this._disconnectSession(knownBleConnectId);
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceMismatch,
+        message: "The bound Trezor Bluetooth device has a different identity"
+      });
+    }
+    if (context?.supportedTransports && !context.supportedTransports.includes("ble")) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceNotFound,
+        message: "This Trezor model has no Bluetooth transport; connect it over USB"
+      });
+    }
+    if (context?.allowDeviceSelection === false) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceNotFound,
+        message: "No known Trezor connection is available"
+      });
+    }
+    return this._selectBleDeviceForBinding(expectedDeviceId, signal, context, "missing-binding");
+  }
+  async _selectBleDeviceForBinding(expectedDeviceId, signal, context, reason) {
+    const availableTransports = this._availableTransports();
+    const allowUsbFallback = reason !== "manual-rebind" && availableTransports.includes("usb");
+    const knownUsbIds = context?.knownConnections ? context.knownConnections.flatMap(
+      (connection) => connection.transport === "usb" ? [connection.connectId] : []
+    ) : [this._knownDeviceConnections.get(expectedDeviceId)?.usbConnectId];
+    if (availableTransports.includes("ble")) {
+      await _TrezorAdapter._abortable(
+        signal,
+        this._ensureDevicePermission(void 0, expectedDeviceId, "ble")
+      );
+    }
+    const bleCandidates = (await _TrezorAdapter._abortable(
+      signal,
+      this._searchDevices({ transportType: "ble", waitForAllTransports: true }, signal)
+    )).filter((device) => device.connectionType === "ble");
+    if (signal.aborted) throw signal.reason;
+    const rejectedConnectIds = /* @__PURE__ */ new Set();
+    const bindingSessionId = this._uiRegistry.createRequestId();
+    let rejectedConnectId;
+    while (availableTransports.includes("ble") && this._emitter.listenerCount(UI_REQUEST.REQUEST_SELECT_DEVICE)) {
+      const { device: selected, requestId } = await requestBleDeviceSelection({
+        emitter: this._emitter,
+        registry: this._uiRegistry,
+        signal,
+        allowUsbFallback,
+        scan: async () => {
+          if (allowUsbFallback) {
+            const usbCandidates = (await this._searchDevices({ transportType: "usb" }, signal)).filter(
+              (device) => device.connectionType === "usb" && !rejectedConnectIds.has(device.connectId)
+            );
+            const candidate = usbCandidates.find((device) => knownUsbIds.includes(device.connectId)) ?? usbCandidates[0];
+            if (candidate) return [candidate];
+          }
+          return (await this._searchDevices({ transportType: "ble", waitForAllTransports: true }, signal)).filter(
+            (device) => device.connectionType === "ble" && !rejectedConnectIds.has(device.connectId)
+          );
+        },
+        request: {
+          devices: bleCandidates.filter((device) => !rejectedConnectIds.has(device.connectId)),
+          bindingSessionId,
+          rejectedConnectId,
+          context: {
+            kind: "bind-connection",
+            transport: "ble",
+            reason
+          },
+          extra: context?.extra,
+          operationId: this._activeOperationId()
+        }
+      });
+      let probeOpensSession = false;
+      try {
+        if (reason === "manual-rebind") {
+          this._operations.endByConnectionKey(selected.connectId, "explicit");
+          await this._releaseProvisionalConnection(selected.connectId, signal);
+        }
+        probeOpensSession = !this._hasSessionOrConnect(selected.connectId);
+        await this._ensureSession(selected.connectId, signal, selected.connectionType);
+      } catch (error) {
+        this._emitBindingStatus(requestId, signal.aborted ? "cancelled" : "failed");
+        throw error;
+      }
+      if (this._devices.get(selected.connectId)?.deviceId !== expectedDeviceId) {
+        if (probeOpensSession) await this._disconnectSession(selected.connectId);
+        rejectedConnectId = selected.connectId;
+        rejectedConnectIds.add(selected.connectId);
+        continue;
+      }
+      if (selected.connectionType === "usb") {
+        this._emitBindingStatus(requestId, "cancelled");
+        return { connectId: selected.connectId };
+      }
+      return { connectId: selected.connectId, selectionRequestId: requestId };
+    }
+    throw createHwkError({
+      code: HardwareErrorCode.DeviceNotFound,
+      message: "No readable Trezor device is available"
+    });
+  }
+  _emitBindingStatus(selectionRequestId, status) {
+    this._emitter.emit(UI_REQUEST.DEVICE_BINDING_STATUS, {
+      type: UI_REQUEST.DEVICE_BINDING_STATUS,
+      payload: { selectionRequestId, status }
+    });
+  }
+  _rememberVerifiedConnection(deviceId, connectId) {
+    const device = this._devices.get(connectId);
+    if (!device || device.deviceId !== deviceId) return;
+    const known = this._knownDeviceConnections.get(deviceId) ?? { deviceId };
+    if (device.connectionType === "ble") {
+      known.bleConnectId = connectId;
+    } else if (device.connectionType === "usb" && device.capabilities?.persistentDeviceIdentity) {
+      known.usbConnectId = connectId;
+    }
+    this._knownDeviceConnections.set(deviceId, known);
+  }
+  async _emitVerifiedBinding(deviceId, connectId, selectionRequestId, context, signal) {
+    if (!selectionRequestId) return false;
+    const device = this._devices.get(connectId);
+    if (!device || device.deviceId !== deviceId || device.connectionType !== "ble") {
+      this._emitBindingStatus(selectionRequestId, "cancelled");
+      return false;
+    }
+    const outcome = await requestSaveDeviceBinding(
+      this._emitter,
+      this._uiRegistry,
+      {
+        selectionRequestId,
+        connection: { transport: "ble", connectId },
+        identity: { vendor: "trezor", type: "deviceId", value: deviceId },
+        extra: context?.extra,
+        operationId: this._activeOperationId()
+      },
+      signal
+    );
+    return outcome.saved;
   }
   /**
    * Pin the device's active wallet session to `passphraseState` (the target
@@ -1685,12 +2575,21 @@ var _TrezorAdapter = class _TrezorAdapter {
     if (reused) return;
     const created = await _TrezorAdapter._abortable(
       signal,
-      _TrezorAdapter._callConnector(this._connector, sessionId, "__thpCreateSession", {
-        passphraseMode: "prompt"
-      })
+      this._callConnector(
+        sessionId,
+        "__thpCreateSession",
+        {
+          passphraseMode: "prompt"
+        },
+        signal
+      )
     );
-    if (created?.protocol === "thp" && !created.thpSessionId) return;
-    if (created?.protocol !== "thp" && created?.protocol !== "v1") return;
+    if (created?.protocol === "thp" && !created.thpSessionId || created?.protocol !== "thp" && created?.protocol !== "v1") {
+      throw createHwkError({
+        code: HardwareErrorCode.TransportError,
+        message: "Cannot verify the requested Trezor wallet session"
+      });
+    }
     const state = await this._deriveState(sessionId, signal);
     if (state !== passphraseState) {
       throw Object.assign(
@@ -1740,9 +2639,14 @@ var _TrezorAdapter = class _TrezorAdapter {
         if (!cached.thpSessionId) return false;
         await _TrezorAdapter._abortable(
           signal,
-          _TrezorAdapter._callConnector(this._connector, sessionId, "__thpSelectSession", {
-            thpSessionId: cached.thpSessionId
-          })
+          this._callConnector(
+            sessionId,
+            "__thpSelectSession",
+            {
+              thpSessionId: cached.thpSessionId
+            },
+            signal
+          )
         );
       }
       const state = await this._deriveState(sessionId, signal);
@@ -1760,9 +2664,14 @@ var _TrezorAdapter = class _TrezorAdapter {
   async _createFreshAppSession(sessionId, signal) {
     await _TrezorAdapter._abortable(
       signal,
-      _TrezorAdapter._callConnector(this._connector, sessionId, "__thpCreateSession", {
-        passphraseMode: "empty"
-      })
+      this._callConnector(
+        sessionId,
+        "__thpCreateSession",
+        {
+          passphraseMode: "empty"
+        },
+        signal
+      )
     );
   }
   /**
@@ -1777,10 +2686,15 @@ var _TrezorAdapter = class _TrezorAdapter {
   async _deriveState(sessionId, signal) {
     const derived = await _TrezorAdapter._abortable(
       signal,
-      _TrezorAdapter._callConnector(this._connector, sessionId, "btcGetPublicKey", {
-        path: "m/44'/0'/0'",
-        showOnDevice: false
-      })
+      this._callConnector(
+        sessionId,
+        "btcGetPublicKey",
+        {
+          path: "m/44'/0'/0'",
+          showOnDevice: false
+        },
+        signal
+      )
     );
     const state = derived?.publicKey;
     if (!state) {
@@ -1790,23 +2704,34 @@ var _TrezorAdapter = class _TrezorAdapter {
     }
     return state;
   }
-  async _resolvePassphraseState(connectId, passphraseState, signal) {
+  async _resolvePassphraseState(connectId, passphraseState, signal, operationId) {
     try {
-      const sessionId = await this._ensureSession(connectId, signal);
+      const sessionId = operationId ? this._sessions.get(this._operations.resolve(operationId).connectId) : await this._ensureSession(connectId, signal);
+      if (!sessionId) {
+        return failure(
+          HardwareErrorCode.OperationEnded,
+          "Trezor operation connection is no longer active"
+        );
+      }
       if (passphraseState) {
         await this._alignAppSession(connectId, sessionId, passphraseState, signal);
         return success(passphraseState);
       }
       const created = await _TrezorAdapter._abortable(
         signal,
-        _TrezorAdapter._callConnector(this._connector, sessionId, "__thpCreateSession", {
-          passphraseMode: "prompt"
-        })
+        this._callConnector(
+          sessionId,
+          "__thpCreateSession",
+          {
+            passphraseMode: "prompt"
+          },
+          signal
+        )
       );
       const state = await this._deriveState(sessionId, signal);
       const features = await _TrezorAdapter._abortable(
         signal,
-        _TrezorAdapter._callConnector(this._connector, sessionId, "getFeatures", { refresh: true })
+        this._callConnector(sessionId, "getFeatures", { refresh: true }, signal)
       );
       if (features?.passphrase_protection !== true) {
         return success(null);
@@ -1856,7 +2781,16 @@ var _TrezorAdapter = class _TrezorAdapter {
     }
     const trustedNumericCode = typeof typed.code === "number" && KNOWN_HARDWARE_ERROR_CODES.has(typed.code) ? typed.code : void 0;
     const code = trustedNumericCode ?? _TrezorAdapter._mapTrezorFailureCode(error) ?? HardwareErrorCode.UnknownError;
-    return failure(code, typed.message ?? String(error));
+    const stampedOrigin = error?.origin;
+    const origin = stampedOrigin === "device" || stampedOrigin === "transport" || stampedOrigin === "host" ? stampedOrigin : defaultOriginForCode(code);
+    const params = typed.params && typeof typed.params === "object" ? typed.params : void 0;
+    return failure(
+      code,
+      typed.message ?? String(error),
+      params,
+      origin,
+      isHwkRecoveryHint(typed.recovery) ? typed.recovery : void 0
+    );
   }
   /**
    * Emit `REQUEST_DEVICE_PERMISSION` and await the host's
@@ -1871,29 +2805,33 @@ var _TrezorAdapter = class _TrezorAdapter {
    *   - no `connectId` → environment-level check (scan / picker)
    *   - with `connectId` → device-level check (per-call gating)
    */
-  async _ensureDevicePermission(connectId, deviceId) {
+  async _ensureDevicePermission(connectId, deviceId, requestedTransport) {
     if (!this._emitter.listenerCount(UI_REQUEST.REQUEST_DEVICE_PERMISSION)) {
       return;
     }
-    const transportType = this.activeTransport ?? "usb";
+    const transportType = requestedTransport ?? this.activeTransport ?? "usb";
+    const operationId = this._activeOperationId();
     const waitPromise = this._uiRegistry.wait(
       UI_REQUEST.REQUEST_DEVICE_PERMISSION,
-      { timeoutMs: 6e4 }
+      { timeoutMs: 6e4, operationId }
     );
     this._emitter.emit(UI_REQUEST.REQUEST_DEVICE_PERMISSION, {
       type: UI_REQUEST.REQUEST_DEVICE_PERMISSION,
-      payload: { transportType, connectId, deviceId }
+      payload: { transportType, connectId, deviceId, operationId }
     });
-    const { granted } = await waitPromise;
+    const { granted, reason } = await waitPromise;
     if (!granted) {
       throw Object.assign(new Error("Device permission denied"), {
-        code: HardwareErrorCode.DevicePermissionDenied
+        code: HardwareErrorCode.DevicePermissionDenied,
+        ...reason ? { params: { permissionDeniedReason: reason } } : {}
       });
     }
   }
 };
 // Keys are matched after normalizeLogKey, so snake_case/camelCase both hit.
 _TrezorAdapter._sensitiveLogKeys = /* @__PURE__ */ new Set([
+  "extra",
+  "knownconnections",
   "credential",
   "credentials",
   "entropy",