@onekeyfe/hd-transport 1.2.0-alpha.13 → 1.2.0-alpha.131

package/__tests__/protocol-v2.test.js

@@ -2,12 +2,27 @@ const { ProtocolV2 } = require('../src/protocols');
 const { parseConfigure } = require('../src/serialization/protobuf/messages');
 const {
   ProtocolV2FrameAssembler,
+  ProtocolV2LinkError,
   ProtocolV2SequenceCursor,
   ProtocolV2Session,
   hexToBytes,
+  isProtocolV2HighThroughputCall,
   probeProtocolV2,
+  isProtocolV2LinkDisabledFailure,
 } = require('../src/protocols/v2/session');
 const protocolV2 = require('../src/protocols/v2');
+const {
+  PROTOCOL_V2_BLE_FIRMWARE_FILE_CHUNK_SIZE,
+  PROTOCOL_V2_BLE_FRAME_MAX_BYTES,
+  PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+  PROTOCOL_V2_FRAME_MAX_BYTES,
+} = require('../src/constants');
+
+test('keeps sensitive acknowledgements separate from high-throughput calls', () => {
+  expect(isProtocolV2HighThroughputCall('PassphraseAck')).toBe(false);
+  expect(isProtocolV2HighThroughputCall('PinMatrixAck')).toBe(false);
+  expect(isProtocolV2HighThroughputCall('FilesystemFileWrite')).toBe(true);
+});
 
 const protocolV1Messages = parseConfigure({
   nested: {
@@ -68,14 +83,14 @@ const protocolV2Messages = parseConfigure({
           type: 'uint32',
           id: 1,
         },
-        supported_messages: {
-          type: 'uint32',
+        build_fingerprint: {
+          type: 'string',
           id: 2,
-          rule: 'repeated',
         },
-        protobuf_definition: {
-          type: 'string',
+        supported_messages: {
+          type: 'uint32',
           id: 3,
+          rule: 'repeated',
         },
       },
     },
@@ -123,7 +138,7 @@ const protocolV2Messages = parseConfigure({
         },
       },
     },
-    DeviceFirmwareUpdateRequest: {
+    DeviceFirmwareUpdateStage: {
       fields: {
         targets: {
           type: 'DeviceFirmwareTarget',
@@ -132,6 +147,9 @@ const protocolV2Messages = parseConfigure({
         },
       },
     },
+    DeviceFirmwareUpdateRequest: {
+      fields: {},
+    },
     DeviceFirmwareUpdateRecord: {
       fields: {
         target_id: {
@@ -161,6 +179,18 @@ const protocolV2Messages = parseConfigure({
         },
       },
     },
+    DeviceSession: {
+      fields: {
+        session_id: {
+          type: 'bytes',
+          id: 1,
+        },
+        btc_test_address: {
+          type: 'string',
+          id: 2,
+        },
+      },
+    },
     FileWrite: {
       fields: {},
     },
@@ -192,8 +222,10 @@ const protocolV2Messages = parseConfigure({
         MessageType_Success: 60207,
         MessageType_Failure: 60208,
         MessageType_FileWrite: 60805,
-        MessageType_DeviceFirmwareUpdateRequest: 61000,
+        MessageType_DeviceFirmwareUpdateStage: 61000,
+        MessageType_DeviceFirmwareUpdateRequest: 61001,
         MessageType_DeviceFirmwareUpdateStatus: 61002,
+        MessageType_DeviceSession: 61201,
         MessageType_PartialNested: 62000,
       },
     },
@@ -204,9 +236,37 @@ const schemas = {
   protocolV1: protocolV1Messages,
   protocolV2: protocolV2Messages,
 };
+const productionProtocolV2Messages = parseConfigure(require('../messages-protocol-v2.json'));
+
+const legacyProtocolInfoMessage = parseConfigure({
+  nested: {
+    ProtocolInfo: {
+      fields: {
+        version: {
+          type: 'uint32',
+          id: 1,
+          rule: 'required',
+        },
+        supported_messages: {
+          type: 'uint32',
+          id: 2,
+          rule: 'repeated',
+          options: {
+            packed: false,
+          },
+        },
+        protobuf_definition: {
+          type: 'string',
+          id: 3,
+        },
+      },
+    },
+  },
+}).lookupType('ProtocolInfo');
 
 const rewriteSeq = (frame, seq) => {
   const copy = new Uint8Array(frame);
+  copy[4] = 1;
   copy[6] = seq;
   copy[copy.length - 1] = protocolV2.crc8(copy, copy.length - 1);
   return copy;
@@ -216,8 +276,8 @@ describe('Protocol V2 framing and session', () => {
   test('encodes and decodes Protocol V2 protobuf frames', () => {
     const frame = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
       version: 1,
+      build_fingerprint: 'application__1.0.0__abc__DEV__DEBUG',
       supported_messages: [60200, 60201],
-      protobuf_definition: 'proto',
     });
 
     const parsed = protocolV2.decodeFrame(frame);
@@ -232,12 +292,70 @@ describe('Protocol V2 framing and session', () => {
       seq: parsed.seq,
       message: {
         version: 1,
+        build_fingerprint: 'application__1.0.0__abc__DEV__DEBUG',
         supported_messages: [60200, 60201],
-        protobuf_definition: 'proto',
       },
     });
   });
 
+  test('decodes a two-byte legacy ProtocolInfo at the generic frame boundary', () => {
+    const frame = protocolV2.encodeProtobufFrame(60201, new Uint8Array([0x08, 0x01]));
+    const productionSchemas = {
+      protocolV1: protocolV1Messages,
+      protocolV2: productionProtocolV2Messages,
+    };
+
+    expect(ProtocolV2.decodeFrame(productionSchemas, frame)).toMatchObject({
+      type: 'ProtocolInfo',
+      message: {
+        version: 1,
+        build_fingerprint: '',
+        supported_messages: [],
+        protobuf_definition: null,
+      },
+    });
+  });
+
+  test('does not reinterpret a malformed current ProtocolInfo as the legacy layout', () => {
+    const frame = protocolV2.encodeProtobufFrame(60201, new Uint8Array([0x08, 0x01, 0x18, 0x01]));
+
+    expect(() =>
+      ProtocolV2.decodeFrame(
+        {
+          protocolV1: protocolV1Messages,
+          protocolV2: productionProtocolV2Messages,
+        },
+        frame
+      )
+    ).toThrow('Protocol V2 protobuf decode failed for "ProtocolInfo"');
+  });
+
+  test('preserves legacy ProtocolInfo capabilities when using the old field numbers', () => {
+    const payload = legacyProtocolInfoMessage
+      .encode({
+        version: 1,
+        supported_messages: [60602],
+        protobuf_definition: 'legacy',
+      })
+      .finish();
+    const frame = protocolV2.encodeProtobufFrame(60201, payload);
+
+    const decoded = ProtocolV2.decodeFrame(
+      {
+        protocolV1: protocolV1Messages,
+        protocolV2: productionProtocolV2Messages,
+      },
+      frame
+    );
+
+    expect(decoded.message).toEqual({
+      version: 1,
+      build_fingerprint: '',
+      supported_messages: [60602],
+      protobuf_definition: null,
+    });
+  });
+
   test('does not encode V1-only messages into Protocol V2 frames', () => {
     expect(() => ProtocolV2.encodeFrame(schemas, 'Ping', { message: 'ok' })).not.toThrow();
     expect(() => ProtocolV2.encodeFrame(schemas, 'OnekeyGetFeatures', {})).toThrow(
@@ -258,6 +376,34 @@ describe('Protocol V2 framing and session', () => {
     expect(decoded.message).toEqual({ message: 'ok' });
   });
 
+  test('round-trips a DeviceSession response with a 32-byte session id', () => {
+    const sessionId = '01'.repeat(32);
+    const frame = ProtocolV2.encodeFrame(schemas, 'DeviceSession', {
+      session_id: sessionId,
+      btc_test_address: 'tb1qwallet',
+    });
+
+    const decoded = ProtocolV2.decodeFrame(schemas, frame);
+
+    expect(decoded.type).toBe('DeviceSession');
+    expect(decoded.message).toEqual({
+      session_id: sessionId,
+      btc_test_address: 'tb1qwallet',
+    });
+  });
+
+  test('reports malformed DeviceSession protobuf as a schema-compatible transport error', () => {
+    const malformedPayload = new Uint8Array(32);
+    malformedPayload[0] = 0x0a;
+    malformedPayload[1] = 101;
+    const frame = protocolV2.encodeProtobufFrame(61201, malformedPayload);
+
+    expect(() => ProtocolV2.decodeFrame(schemas, frame)).toThrow(
+      'Protocol V2 protobuf decode failed for "DeviceSession" (61201, 32-byte payload); ' +
+        'the payload is malformed or incompatible with the active SDK schema.'
+    );
+  });
+
   test('decodes missing optional nested messages as null', () => {
     const frame = ProtocolV2.encodeFrame(schemas, 'PartialNested', {
       label: 'only label',
@@ -284,6 +430,60 @@ describe('Protocol V2 framing and session', () => {
     expect(() => assembler.push(oversized)).toThrow('Protocol V2 frame too large');
   });
 
+  test('enforces a transport-specific receive frame boundary', () => {
+    const assembler = new ProtocolV2FrameAssembler(2048);
+    const oversizedHeader = new Uint8Array([0x5a, 0x01, 0x08]);
+
+    expect(() => assembler.push(oversizedHeader)).toThrow('Protocol V2 frame too large: 2049');
+  });
+
+  test('enforces the firmware 4200-byte Protocol V2 frame boundary', () => {
+    const boundaryFrame = ProtocolV2.encodeFrame(schemas, 'Ping', {
+      message: 'x'.repeat(4187),
+    });
+
+    expect(PROTOCOL_V2_FRAME_MAX_BYTES).toBe(4200);
+    expect(boundaryFrame).toHaveLength(PROTOCOL_V2_FRAME_MAX_BYTES);
+    expect(() =>
+      ProtocolV2.encodeFrame(schemas, 'Ping', {
+        message: 'x'.repeat(4188),
+      })
+    ).toThrow('Protocol V2 frame too large: 4201 > 4200');
+  });
+
+  test('keeps optimized BLE firmware chunks inside the transport frame boundary', () => {
+    const productionSchemas = {
+      protocolV1: protocolV1Messages,
+      protocolV2: productionProtocolV2Messages,
+    };
+    const stagingPaths = [
+      'vol0:/bootloader.bin',
+      'vol0:/application_p1.bin',
+      'vol0:/application_p2.bin',
+      'vol0:/coprocessor.bin',
+      'vol0:/se01.bin',
+      'vol0:/se02.bin',
+      'vol0:/se03.bin',
+      'vol0:/se04.bin',
+    ];
+
+    for (const path of stagingPaths) {
+      const frame = ProtocolV2.encodeFrame(productionSchemas, 'FilesystemFileWrite', {
+        file: {
+          path,
+          offset: 0xffffffff,
+          total_size: 0xffffffff,
+          data: new Uint8Array(PROTOCOL_V2_BLE_FIRMWARE_FILE_CHUNK_SIZE),
+        },
+        overwrite: true,
+        append: false,
+        ui_percentage: 100,
+      });
+
+      expect(frame.length).toBeLessThanOrEqual(PROTOCOL_V2_BLE_FRAME_MAX_BYTES);
+    }
+  });
+
   test('keeps bytes after the first complete frame for the next read', () => {
     const first = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
       version: 1,
@@ -329,19 +529,51 @@ describe('Protocol V2 framing and session', () => {
       type: 'ProtocolInfo',
       message: {
         version: 2,
+        build_fingerprint: null,
         supported_messages: [60206],
+      },
+    });
+  });
+
+  test('session decodes legacy ProtocolInfo through the generic frame boundary', async () => {
+    const productionSchemas = {
+      protocolV1: protocolV1Messages,
+      protocolV2: productionProtocolV2Messages,
+    };
+    const response = protocolV2.encodeProtobufFrame(60201, new Uint8Array([0x08, 0x01]));
+    const session = new ProtocolV2Session({
+      schemas: productionSchemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
+    });
+
+    await expect(
+      session.call(
+        'ProtocolInfoRequest',
+        { eventless_wallet_session: true },
+        {
+          expectedTypes: ['ProtocolInfo'],
+        }
+      )
+    ).resolves.toEqual({
+      type: 'ProtocolInfo',
+      message: {
+        version: 1,
+        build_fingerprint: '',
+        supported_messages: [],
         protobuf_definition: null,
       },
     });
   });
 
-  test('session logs Protocol V2 TX and RX frame metadata without payloads', async () => {
+  test('session does not log Protocol V2 TX and RX frames', async () => {
     const written = [];
     const logger = { debug: jest.fn() };
     const response = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
       version: 2,
+      build_fingerprint: 'application__1.0.0__sensitive__DEV__DEBUG',
       supported_messages: [60206],
-      protobuf_definition: 'sensitive-schema',
     });
     const session = new ProtocolV2Session({
       schemas,
@@ -358,27 +590,10 @@ describe('Protocol V2 framing and session', () => {
 
     await session.call('ProtocolInfoRequest', {});
 
-    const tx = protocolV2.decodeFrame(written[0]);
-    const rx = protocolV2.decodeFrame(rewriteSeq(response, tx.seq));
-    expect(logger.debug).toHaveBeenCalledWith('[ProtocolV2 Test] TX', {
-      method: 'ProtocolInfoRequest',
-      type: 'ProtocolInfoRequest',
-      typeId: tx.messageTypeId,
-      seq: tx.seq,
-      bytes: written[0].length,
-    });
-    expect(logger.debug).toHaveBeenCalledWith('[ProtocolV2 Test] RX', {
-      method: 'ProtocolInfoRequest',
-      type: 'ProtocolInfo',
-      typeId: rx.messageTypeId,
-      seq: rx.seq,
-      bytes: response.length,
-    });
-    expect(JSON.stringify(logger.debug.mock.calls)).not.toContain('sensitive-schema');
-    expect(JSON.stringify(logger.debug.mock.calls)).not.toContain('supported_messages');
+    expect(logger.debug).not.toHaveBeenCalled();
   });
 
-  test('session logs RX frame metadata before protobuf payload decoding fails', async () => {
+  test('session does not log RX frame metadata when protobuf payload decoding fails', async () => {
     const logger = { debug: jest.fn() };
     const response = protocolV2.encodeProtobufFrame(
       60208,
@@ -390,19 +605,12 @@ describe('Protocol V2 framing and session', () => {
       logger,
       logPrefix: 'ProtocolV2 Test',
       writeFrame: () => Promise.resolve(),
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
     });
 
     await expect(session.call('Ping', { message: 'hello' })).rejects.toThrow();
 
-    const rx = protocolV2.decodeFrame(response);
-    expect(logger.debug).toHaveBeenCalledWith('[ProtocolV2 Test] RX', {
-      method: 'Ping',
-      type: 'Failure',
-      typeId: rx.messageTypeId,
-      seq: rx.seq,
-      bytes: response.length,
-    });
+    expect(logger.debug).not.toHaveBeenCalled();
   });
 
   test('session skips Proto Link ACK frames before decoding the protobuf response', async () => {
@@ -419,7 +627,10 @@ describe('Protocol V2 framing and session', () => {
     const response = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'ok',
     });
-    const readFrame = jest.fn().mockResolvedValueOnce(ack).mockResolvedValueOnce(response);
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(ack)
+      .mockResolvedValueOnce(rewriteSeq(response, 1));
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
@@ -436,6 +647,96 @@ describe('Protocol V2 framing and session', () => {
     expect(readFrame).toHaveBeenCalledTimes(2);
   });
 
+  test('session accepts a terminal response before an ACK', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
+    });
+
+    await expect(
+      session.call('Ping', { message: 'hello' }, { expectedTypes: ['Success'] })
+    ).resolves.toEqual({
+      type: 'Success',
+      message: {
+        message: 'ok',
+      },
+    });
+  });
+
+  test('session uses the unified response timeout before the first ACK', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const readFrame = jest.fn(() => Promise.resolve(rewriteSeq(response, 1)));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await expect(
+      session.call(
+        'Ping',
+        { message: 'hello' },
+        {
+          timeoutMs: 12_345,
+          expectedTypes: ['Success'],
+        }
+      )
+    ).resolves.toEqual({
+      type: 'Success',
+      message: {
+        message: 'ok',
+      },
+    });
+    expect(readFrame).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 12_345 }));
+  });
+
+  test('session rejects an ACK that belongs to another request sequence', async () => {
+    const ack = new Uint8Array(8);
+    ack[0] = 0x5a;
+    ack[1] = 8;
+    ack[4] = 1;
+    ack[5] = 1;
+    ack[6] = 2;
+    ack[3] = protocolV2.crc8(ack, 3);
+    ack[7] = protocolV2.crc8(ack, 7);
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(ack),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).rejects.toEqual(
+      expect.objectContaining({
+        name: 'ProtocolV2LinkError',
+        code: 'ack-sequence',
+        message: 'Protocol V2 ACK sequence mismatch: expected 1, got 2',
+      })
+    );
+  });
+
+  test('session rejects a response from another routing channel', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'wrong route' });
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(response),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).rejects.toBeInstanceOf(
+      ProtocolV2LinkError
+    );
+  });
+
   test('session rejects BLE frames above its configured frame limit before writing', async () => {
     const writeFrame = jest.fn().mockResolvedValue(undefined);
     const response = ProtocolV2.encodeFrame(schemas, 'Success', {
@@ -446,7 +747,7 @@ describe('Protocol V2 framing and session', () => {
       router: 1,
       maxFrameBytes: 2048,
       writeFrame,
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
     });
 
     await expect(session.call('Ping', { message: 'x'.repeat(2048) })).rejects.toThrow(
@@ -455,28 +756,40 @@ describe('Protocol V2 framing and session', () => {
     expect(writeFrame).not.toHaveBeenCalled();
   });
 
-  test('session starts response timeout after the frame is written', async () => {
-    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
-      message: 'ok',
-    });
+  test('session watchdog covers a write that never settles', async () => {
+    const readFrame = jest.fn();
+    let writeSignal;
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
-      writeFrame: () =>
-        new Promise(resolve => {
-          setTimeout(resolve, 30);
-        }),
-      readFrame: () => Promise.resolve(response),
+      writeFrame: (_frame, context) => {
+        writeSignal = context.signal;
+        return new Promise(() => {});
+      },
+      readFrame,
     });
 
     await expect(
       session.call('Ping', { message: 'hello' }, { timeoutMs: 10, expectedTypes: ['Success'] })
-    ).resolves.toEqual({
-      type: 'Success',
-      message: {
-        message: 'ok',
-      },
+    ).rejects.toThrow('Protocol V2 response timeout after 10ms for Ping');
+    expect(writeSignal.aborted).toBe(true);
+    expect(readFrame).not.toHaveBeenCalled();
+  });
+
+  test('session watchdog covers prepareCall before writing', async () => {
+    const writeFrame = jest.fn();
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      prepareCall: () => new Promise(() => {}),
+      writeFrame,
+      readFrame: jest.fn(),
     });
+
+    await expect(session.call('Ping', { message: 'hello' }, { timeoutMs: 10 })).rejects.toThrow(
+      'Protocol V2 response timeout after 10ms for Ping'
+    );
+    expect(writeFrame).not.toHaveBeenCalled();
   });
 
   test('session logs a device-owned response seq without rejecting the frame', async () => {
@@ -499,17 +812,46 @@ describe('Protocol V2 framing and session', () => {
       type: 'ProtocolInfo',
       message: {
         version: 2,
+        build_fingerprint: null,
         supported_messages: [],
-        protobuf_definition: null,
       },
     });
-    expect(logger.debug).toHaveBeenCalledWith('[ProtocolV2] RX', {
-      method: 'ProtocolInfoRequest',
-      type: 'ProtocolInfo',
-      typeId: 60201,
-      seq: 200,
-      bytes: response.length,
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  test('session accepts gaps in the firmware-global response sequence', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(rewriteSeq(response, 1))
+      .mockResolvedValueOnce(rewriteSeq(response, 4));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
     });
+
+    await session.call('Ping', { message: 'first' });
+    await expect(session.call('Ping', { message: 'second' })).resolves.toMatchObject({
+      type: 'Success',
+    });
+  });
+
+  test('session rejects a duplicate device response sequence', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    const readFrame = jest.fn(() => Promise.resolve(rewriteSeq(response, 7)));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await session.call('Ping', { message: 'first' });
+    await expect(session.call('Ping', { message: 'second' })).rejects.toThrow(
+      'Protocol V2 duplicate response sequence: 7'
+    );
   });
 
   test('session does not log transmit or receive payload details', async () => {
@@ -523,7 +865,7 @@ describe('Protocol V2 framing and session', () => {
       schemas,
       router: 1,
       writeFrame: () => Promise.resolve(),
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
       logger,
       logPrefix: 'ProtocolV2 Test',
     });
@@ -535,10 +877,7 @@ describe('Protocol V2 framing and session', () => {
       },
     });
 
-    expect(logger.debug).toHaveBeenCalledTimes(2);
-    const logs = JSON.stringify(logger.debug.mock.calls);
-    expect(logs).not.toContain('hello');
-    expect(logs).not.toContain('accepted');
+    expect(logger.debug).not.toHaveBeenCalled();
   });
 
   test('session suppresses debug logs for file transfer calls', async () => {
@@ -552,7 +891,7 @@ describe('Protocol V2 framing and session', () => {
       schemas,
       router: 1,
       writeFrame: () => Promise.resolve(),
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
       logger,
     });
 
@@ -566,6 +905,34 @@ describe('Protocol V2 framing and session', () => {
     expect(logger.debug).not.toHaveBeenCalled();
   });
 
+  test('session reports when the complete request frame has been written', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const events = [];
+    const onWriteCompleted = jest.fn(metrics => events.push(['written', metrics]));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: frame => {
+        events.push(['write', frame.byteLength]);
+        return Promise.resolve();
+      },
+      readFrame: () => {
+        events.push(['read']);
+        return Promise.resolve(rewriteSeq(response, 1));
+      },
+    });
+
+    await session.call('Ping', { message: 'metrics' }, { onWriteCompleted });
+
+    expect(events.map(event => event[0])).toEqual(['write', 'written', 'read']);
+    expect(onWriteCompleted).toHaveBeenCalledWith({
+      elapsedMs: expect.any(Number),
+      frameBytes: expect.any(Number),
+    });
+  });
+
   test('session skips unrelated terminal frames when expected response types are provided', async () => {
     const stale = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'stale response',
@@ -577,7 +944,10 @@ describe('Protocol V2 framing and session', () => {
     const logger = {
       debug: jest.fn(),
     };
-    const readFrame = jest.fn().mockResolvedValueOnce(stale).mockResolvedValueOnce(response);
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(rewriteSeq(stale, 1))
+      .mockResolvedValueOnce(rewriteSeq(response, 2));
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
@@ -592,8 +962,8 @@ describe('Protocol V2 framing and session', () => {
       type: 'ProtocolInfo',
       message: {
         version: 2,
+        build_fingerprint: null,
         supported_messages: [],
-        protobuf_definition: null,
       },
     });
 
@@ -601,22 +971,10 @@ describe('Protocol V2 framing and session', () => {
     expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining('skip unexpected response'));
   });
 
-  test('session consumes intermediate response frames before returning the final response', async () => {
+  test('session can return after a request frame is written', async () => {
     const written = [];
-    const progress = ProtocolV2.encodeFrame(schemas, 'DeviceFirmwareUpdateStatus', {
-      records: [{ target_id: 4, status: 1 }],
-    });
-    const success = ProtocolV2.encodeFrame(schemas, 'Success', {
-      message: 'ok',
-    });
-    const onIntermediateResponse = jest.fn();
-    const readFrame = jest.fn(() => {
-      const [writtenFrame] = written;
-      const { seq } = protocolV2.decodeFrame(writtenFrame);
-      return Promise.resolve(
-        readFrame.mock.calls.length === 1 ? rewriteSeq(progress, seq) : rewriteSeq(success, seq)
-      );
-    });
+    const readFrame = jest.fn();
+    const onWriteCompleted = jest.fn();
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
@@ -629,26 +987,20 @@ describe('Protocol V2 framing and session', () => {
 
     const result = await session.call(
       'DeviceFirmwareUpdateRequest',
-      { targets: [{ target_id: 4, path: 'vol1:firmware.bin' }] },
+      {},
       {
-        intermediateTypes: ['DeviceFirmwareUpdateStatus'],
-        onIntermediateResponse,
+        returnAfterWrite: true,
+        onWriteCompleted,
       }
     );
 
-    expect(readFrame).toHaveBeenCalledTimes(2);
-    expect(onIntermediateResponse).toHaveBeenCalledWith({
-      type: 'DeviceFirmwareUpdateStatus',
-      message: {
-        records: [{ target_id: 4, status: 1, payload_version: null, path: null }],
-      },
-    });
-    expect(result).toEqual({
-      type: 'Success',
-      message: {
-        message: 'ok',
-      },
-    });
+    expect(written).toHaveLength(1);
+    expect(ProtocolV2.decodeFrame(schemas, written[0]).messageName).toBe(
+      'DeviceFirmwareUpdateRequest'
+    );
+    expect(readFrame).not.toHaveBeenCalled();
+    expect(onWriteCompleted).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ type: 'WriteCompleted', message: {} });
   });
 
   test('probeProtocolV2 accepts Success as a normal V2 probe response', async () => {
@@ -667,6 +1019,36 @@ describe('Protocol V2 framing and session', () => {
     ).resolves.toBe(false);
   });
 
+  test('recognizes USB-priority firmware failures independently of surrounding whitespace', () => {
+    expect(isProtocolV2LinkDisabledFailure('Failure_ProcessError', ' link disabled ')).toBe(true);
+    expect(isProtocolV2LinkDisabledFailure(5, 'Link Disabled')).toBe(true);
+    expect(isProtocolV2LinkDisabledFailure('Failure_ProcessError', 'busy')).toBe(false);
+  });
+
+  test.each(['Failure_ProcessError', 5])(
+    'probeProtocolV2 surfaces link disabled without resetting the link for code %s',
+    async code => {
+      const onProbeFailed = jest.fn();
+
+      await expect(
+        probeProtocolV2({
+          call: () =>
+            Promise.resolve({
+              type: 'Failure',
+              message: { code, message: ' link disabled ' },
+            }),
+          timeoutMs: 1,
+          onProbeFailed,
+        })
+      ).rejects.toMatchObject({
+        name: 'ProtocolV2LinkDisabledError',
+        failureCode: code,
+        firmwareMessage: ' link disabled ',
+      });
+      expect(onProbeFailed).not.toHaveBeenCalled();
+    }
+  );
+
   test('decodeFrame rejects frames that are too short', () => {
     expect(() => protocolV2.decodeFrame(new Uint8Array([0x5a, 0x08, 0x00]))).toThrow(
       'Protocol V2 frame too short'
@@ -791,7 +1173,7 @@ describe('Protocol V2 framing and session', () => {
         }
         return Promise.resolve();
       },
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
     });
 
     await expect(session.call('Ping', { message: '1' })).rejects.toThrow('transport write failed');
@@ -860,6 +1242,7 @@ describe('Protocol V2 framing and session', () => {
     const writeContexts = [];
     const readContexts = [];
     const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    let responseSeq = 0;
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
@@ -870,18 +1253,67 @@ describe('Protocol V2 framing and session', () => {
       },
       readFrame: context => {
         readContexts.push(context);
-        return Promise.resolve(response);
+        responseSeq = protocolV2.nextProtoSeq(responseSeq);
+        return Promise.resolve(rewriteSeq(response, responseSeq));
       },
     });
 
     await session.call('Ping', { message: 'ping' }, { timeoutMs: 123 });
-    await session.call('FileWrite', {}, { timeoutMs: 456 });
+    await session.call('FileWrite', {}, { timeoutMs: 456, writeWithResponse: true });
+    await session.call('Ping', { message: 'default-timeout' });
 
-    expect(writeContexts).toEqual([
-      { messageName: 'Ping', timeoutMs: 123, highVolume: false, generation: 7 },
-      { messageName: 'FileWrite', timeoutMs: 456, highVolume: true, generation: 7 },
+    const normalizeContext = ({ signal, ...context }) => ({
+      ...context,
+      signalAborted: signal.aborted,
+    });
+    expect(writeContexts.map(normalizeContext)).toEqual([
+      {
+        messageName: 'Ping',
+        timeoutMs: 123,
+        highThroughput: false,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'FileWrite',
+        timeoutMs: 456,
+        highThroughput: true,
+        writeWithResponse: true,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'Ping',
+        timeoutMs: PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+        highThroughput: false,
+        generation: 7,
+        signalAborted: false,
+      },
+    ]);
+    expect(readContexts.map(normalizeContext)).toEqual([
+      {
+        messageName: 'Ping',
+        timeoutMs: 123,
+        highThroughput: false,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'FileWrite',
+        timeoutMs: 456,
+        highThroughput: true,
+        writeWithResponse: true,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'Ping',
+        timeoutMs: PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+        highThroughput: false,
+        generation: 7,
+        signalAborted: false,
+      },
     ]);
-    expect(readContexts).toEqual(writeContexts);
   });
 
   test('assembler throws and resets on frames with an impossible length field', () => {