@esp-vision/device-core 0.5.1 → 0.6.0

package/tests/test-node-rom-port.mjs

@@ -0,0 +1,305 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { prepareNodeRomPort, recoverNodeRomPort } from '../src/node_rom_port.js'
+
+const MAC = 'e8f60ae75642'
+const native = (path = '/dev/ttyACM0', extra = {}) => ({ path, vendorId: 0x303a, productId: 0x4003, serialNumber: MAC, location: '1-2:1.0', ...extra })
+const rom = (path = '/dev/ttyACM1', extra = {}) => native(path, { productId: 18, location: '1-2', ...extra })
+const failure = (code, message = code) => Object.assign(new Error(message), { code })
+function fixture(options = {}) {
+  let clock = 0, enumerations = 0
+  const calls = { connect: [], control: [], python: [], disconnect: 0, creates: 0, realpath: [], enumerate: [] }
+  const controller = options.controller ?? new AbortController()
+  const connected = { identity: { deviceId: MAC }, capabilities: { sinks: [
+    { id: 'usb', kind: 'usb_otg_cdc', owner: true, state: 'active', ready: true },
+  ] }, ...options.connected }
+  const device = {
+    async connect(request) { calls.connect.push(request); if (options.connectError) throw options.connectError; return connected },
+    python: { async execute(request) { calls.python.push(request); return options.pythonResult ?? { ok: true, outputTruncated: false, output: `__EV_ROM_ID__${MAC}\n` } } },
+    async control(request) {
+      calls.control.push(request)
+      if (options.control) return options.control(controller)
+      if (options.controlError) throw options.controlError
+      return { ok: true, operation: 'bootloader', acknowledged: false, outcome: 'unknown' }
+    },
+    async disconnect() { calls.disconnect += 1; if (options.cleanupError) throw options.cleanupError },
+  }
+  const snapshots = options.snapshots ?? [[native()], [rom()]]
+  const dependencies = {
+    now: () => clock,
+    async sleep(ms, signal) { clock += ms; if (options.onSleep) options.onSleep(controller, clock); signal?.throwIfAborted() },
+    async realpath(path) { calls.realpath.push(path); return options.realpath ? options.realpath(path, clock) : path },
+    async listSerial(request) {
+      calls.enumerate.push(request)
+      if (options.onEnumerate) options.onEnumerate(controller, ++enumerations)
+      if (options.enumerationError) throw options.enumerationError
+      if (options.enumerationDelay) clock += options.enumerationDelay
+      return snapshots[Math.min(enumerations++ , snapshots.length - 1)]
+    },
+    serialTransport(request) { return request },
+    createDevice(request) { calls.creates += 1; calls.transport = request.transport; return device },
+  }
+  const run = (overrides = {}) => prepareNodeRomPort({ port: '/dev/ttyACM0', python: 'selected-python', timeout: 200, signal: controller.signal, ...overrides }, dependencies)
+  const recover = (previous, overrides = {}) => recoverNodeRomPort(previous, { python: 'selected-python', timeout: 200, signal: controller.signal, ...overrides }, dependencies)
+  return { calls, run, recover, controller, now: () => clock }
+}
+
+test('imports are passive; ROM, USJ, UART and unknown selections never create an EV-MUX session', async () => {
+  for (const descriptor of [rom('/dev/ttyACM0'), native('/dev/ttyACM0', { productId: 0x1001 }),
+    native('/dev/ttyACM0', { vendorId: 0x10c4, productId: 0xea60 }), native('/dev/ttyACM0', { vendorId: null, productId: null })]) {
+    const f = fixture({ snapshots: [[descriptor]] })
+    const result = await f.run()
+    assert.equal(result.port, '/dev/ttyACM0')
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(result.expectedMac, descriptor.productId === 18 ? MAC : null)
+  }
+})
+
+test('a missing exact by-id path may settle, then existing ROM uses its canonical OS path', async () => {
+  const selected = '/dev/serial/by-id/exact-selected'
+  const f = fixture({ realpath: (_, time) => { if (time < 100) throw failure('ENOENT'); return '/dev/ttyACM1' }, snapshots: [[rom()]] })
+  const result = await f.run({ port: selected })
+  assert.equal(result.port, '/dev/ttyACM1')
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(result.transition.requested, false)
+  assert.equal(result.transition.location, '1-2')
+  assert.equal(f.calls.creates, 0)
+  assert.ok(f.calls.realpath.every(path => path === selected))
+})
+
+test('a vanished selected by-id never authorizes filename-based selection of another board', async () => {
+  const f = fixture({ realpath: () => { throw failure('ENOENT') }, snapshots: [[rom('/dev/ttyACM8')]] })
+  await assert.rejects(f.run({ port: `/dev/serial/by-id/usb-${MAC}` }), { code: 'ROM_PORT_LOST' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.enumerate.length, 0)
+  assert.equal(f.now(), 200)
+})
+
+test('verified native runtime transitions once and binds only matching ROM serial plus location', async () => {
+  const f = fixture()
+  const result = await f.run()
+  assert.equal(result.port, '/dev/ttyACM1')
+  assert.equal(result.expectedMac, MAC)
+  assert.deepEqual(result.transition.command, { attempted: true, acknowledged: false, outcome: 'unknown' })
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(result.transition.cleanup.ok, true)
+  assert.equal(f.calls.connect.length, 1)
+  assert.deepEqual(f.calls.transport, { serial: '/dev/ttyACM0', role: 'usb', python: 'selected-python' })
+  assert.equal(f.calls.connect[0].probeRepl, false)
+  assert.equal(f.calls.connect[0].autoBaud, false)
+  assert.equal(f.calls.connect[0].role, 'usb')
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.calls.python.length, 0)
+})
+
+test('legacy null deviceId uses one small public Python unique_id probe before bootloader', async () => {
+  const f = fixture({ connected: { identity: { deviceId: null } } })
+  const result = await f.run()
+  assert.equal(result.transition.identitySource, 'machine.unique_id')
+  assert.equal(f.calls.python.length, 1)
+  assert.ok(Buffer.byteLength(f.calls.python[0].source) < 511)
+  assert.equal(f.calls.python[0].completion, 'wait')
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('wrong or malformed non-null identity never falls back to Python or resets', async () => {
+  for (const id of ['e8f60ae75653', 'unknown']) {
+    const f = fixture({ connected: { identity: { deviceId: id } } })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.calls.python.length, 0)
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('incomplete legacy unique_id output cannot authorize reset', async () => {
+  for (const result of [{ ok: true, outputTruncated: true, output: `__EV_ROM_ID__${MAC}\n` },
+    { ok: true, outputTruncated: false, output: `__EV_ROM_ID__${MAC}\n__EV_ROM_ID__${MAC}\n` },
+    { ok: true, outputTruncated: false, output: 'Traceback\n' }]) {
+    const f = fixture({ connected: { identity: { deviceId: null } }, pythonResult: result })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_IDENTITY_UNAVAILABLE' })
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('missing serial or location and ambiguous selected descriptors fail without opening a device', async () => {
+  for (const extra of [{ serialNumber: null }, { serialNumber: 'non-MAC' }, { location: null }]) {
+    const f = fixture({ snapshots: [[native('/dev/ttyACM0', extra)]] })
+    await assert.rejects(f.run(), { code: 'ROM_PORT_IDENTITY_REQUIRED' })
+    assert.equal(f.calls.creates, 0)
+  }
+  const f = fixture({ snapshots: [[native(), native()]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.creates, 0)
+})
+
+test('an inactive USB owner or different owner cannot authorize bootloader', async () => {
+  for (const sinks of [[{ id: 'usb', kind: 'usb_otg_cdc', owner: true, state: 'idle', ready: true }],
+    [{ id: 'usj', kind: 'usb_serial_jtag', owner: true, state: 'active', ready: true }]]) {
+    const f = fixture({ connected: { capabilities: { sinks } } })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_INTERFACE_MISMATCH' })
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('other MACs or physical locations never replace the selected device', async () => {
+  const f = fixture({ snapshots: [[native()], [rom('/dev/ttyACM1', { serialNumber: 'e8f60ae75653' }), rom('/dev/ttyACM2', { location: '1-3' })]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.now(), 200)
+})
+
+test('two matching ROM interfaces are ambiguous and never selected', async () => {
+  const f = fixture({ snapshots: [[native()], [rom('/dev/ttyACM1'), rom('/dev/ttyACM2')]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('unknown command outcome and cleanup failure remain separate from observed ROM', async () => {
+  const controlError = Object.assign(failure('TIMEOUT'), { reset: { outcome: 'unknown', acknowledged: false } })
+  const f = fixture({ controlError, cleanupError: failure('SESSION_RELEASE_TIMEOUT') })
+  const result = await f.run()
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(result.transition.command.acknowledged, false)
+  assert.equal(result.transition.command.outcome, 'unknown')
+  assert.equal(result.transition.command.error.code, 'TIMEOUT')
+  assert.equal(result.transition.cleanup.ok, false)
+  assert.equal(result.transition.cleanup.error.code, 'SESSION_RELEASE_TIMEOUT')
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('ordinary handshake or command errors are returned without bootloader retry', async () => {
+  const error = failure('SESSION_BUSY')
+  const f = fixture({ connectError: error })
+  await assert.rejects(f.run(), value => value === error)
+  assert.equal(f.calls.control.length, 0)
+  assert.equal(f.calls.disconnect, 1)
+  const other = fixture({ controlError: failure('TIMEOUT') })
+  await assert.rejects(other.run(), { code: 'TIMEOUT' })
+  assert.equal(other.calls.control.length, 1)
+  assert.equal(other.calls.enumerate.length, 1)
+})
+
+test('Windows COM aliases and pyserial interface suffixes bind the same physical USB port', async () => {
+  const f = fixture({ snapshots: [[native('COM8', { location: '1-5:x.0' })], [rom('COM9', { location: '1-5' })]] })
+  const result = await f.run({ port: '\\\\.\\com8' })
+  assert.equal(result.port, 'COM9')
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(f.calls.realpath.length, 0)
+})
+
+test('enumeration finishing after the deadline does not accept a late ROM match', async () => {
+  const f = fixture({ enumerationDelay: 250 })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('cancel before entry, during command, and during rebind never replays control', async () => {
+  const reason = Object.assign(new Error('cancelled'), { name: 'AbortError' })
+  const before = fixture(); before.controller.abort(reason)
+  await assert.rejects(before.run(), value => value === reason)
+  assert.equal(before.calls.creates, 0)
+  const during = fixture({ control(controller) { controller.abort(reason); throw reason } })
+  await assert.rejects(during.run(), value => value === reason)
+  assert.equal(during.calls.control.length, 1)
+  assert.equal(during.calls.disconnect, 1)
+  const poll = fixture({ snapshots: [[native()], []], onSleep(controller) { controller.abort(reason) } })
+  await assert.rejects(poll.run(), value => value === reason)
+  assert.equal(poll.calls.control.length, 1)
+  assert.equal(poll.calls.disconnect, 1)
+})
+
+test('unavailable descriptors leave the exact canonical selection untouched and unprobed', async () => {
+  const f = fixture({ enumerationError: failure('SERIAL_UNAVAILABLE'), realpath: () => '/dev/ttyACM7' })
+  const result = await f.run({ port: '/dev/serial/by-id/exact' })
+  assert.deepEqual(result, { port: '/dev/ttyACM7', expectedMac: null, transition: null })
+  assert.equal(f.calls.creates, 0)
+})
+
+
+const previousRom = (extra = {}) => ({ port: '/dev/ttyACM0', expectedMac: MAC,
+  transition: { observed: 'rom', requested: false, serial: MAC, location: '1-2' }, ...extra })
+
+test('confirmed UVC runtime PID4023 uses the same identity-verified one-shot handoff', async () => {
+  const f = fixture({ snapshots: [[native('/dev/ttyACM0', { productId: 0x4023 })], [rom()]] })
+  const result = await f.run()
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(f.calls.control.length, 1)
+  const other = fixture({ snapshots: [[native('/dev/ttyACM0', { productId: 0x4021 })]] })
+  assert.equal((await other.run()).transition, null)
+  assert.equal(other.calls.creates, 0)
+})
+
+test('read-only initialization recovery verifies same-board runtime and reuses production handoff once', async () => {
+  for (const productId of [0x4003, 0x4023]) {
+    const runtime = native('/dev/ttyACM2', { productId })
+    const f = fixture({ snapshots: [[runtime], [runtime], [rom('/dev/ttyACM3')]] })
+    const result = await f.recover(previousRom())
+    assert.equal(result.port, '/dev/ttyACM3')
+    assert.equal(result.expectedMac, MAC)
+    assert.deepEqual(result.transition.recovery, { previousPort: '/dev/ttyACM0', runtimePid: productId })
+    assert.equal(f.calls.transport.serial, '/dev/ttyACM2')
+    assert.equal(f.calls.control.length, 1)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('recovery never repeats a previous active handoff or uses an incomplete previous binding', async () => {
+  for (const previous of [previousRom({ expectedMac: 'unknown' }), previousRom({ transition: null }),
+    previousRom({ transition: { observed: 'rom', requested: true, serial: MAC, location: '1-2' } }),
+    previousRom({ transition: { observed: 'rom', requested: false, serial: 'e8f60ae75653', location: '1-2' } }),
+    previousRom({ transition: { observed: 'rom', requested: false, serial: MAC, location: null } })]) {
+    const f = fixture()
+    assert.equal(await f.recover(previous), null)
+    assert.equal(f.calls.enumerate.length, 0)
+    assert.equal(f.calls.creates, 0)
+  }
+})
+
+test('same ROM or no runtime returns null without issuing a bootloader command', async () => {
+  for (const snapshot of [[rom('/dev/ttyACM1')], [], [native('/dev/ttyACM8', { serialNumber: 'e8f60ae75653', location: '2-3' })]]) {
+    const f = fixture({ snapshots: [snapshot] })
+    assert.equal(await f.recover(previousRom()), null)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('recovery rejects wrong MAC, moved location and ambiguous matching runtimes', async () => {
+  for (const runtime of [native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }), native('/dev/ttyACM2', { location: '2-3' })]) {
+    const f = fixture({ snapshots: [[runtime]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.calls.creates, 0)
+  }
+  const f = fixture({ snapshots: [[native('/dev/ttyACM2'), native('/dev/ttyACM3')]] })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.creates, 0)
+})
+
+test('recovery rechecks identity before connecting when a selected OS path was reused', async () => {
+  const correct = native('/dev/ttyACM2')
+  const wrong = native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' })
+  const f = fixture({ snapshots: [[correct], [wrong]] })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('read-only recovery honors cancel and fresh-enumeration deadline', async () => {
+  const reason = Object.assign(new Error('cancelled'), { name: 'AbortError' })
+  const cancelled = fixture(); cancelled.controller.abort(reason)
+  await assert.rejects(cancelled.recover(previousRom()), value => value === reason)
+  assert.equal(cancelled.calls.creates, 0)
+  const late = fixture({ snapshots: [[native()]], enumerationDelay: 250 })
+  await assert.rejects(late.recover(previousRom()), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(late.calls.creates, 0)
+})

package/tests/test-node-rom.mjs

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import { PassThrough, Writable } from 'node:stream'
+import { openNodeRom } from '../src/node_rom.js'
+
+function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeError } = {}) {
+  const calls = [], requests = []
+  const child = new EventEmitter()
+  child.exitCode = null
+  child.stdout = new PassThrough()
+  child.stdin = new Writable({
+    write(data, encoding, done) {
+      const request = JSON.parse(data.toString())
+      requests.push(request)
+      queueMicrotask(() => child.stdout.write(JSON.stringify(request.method === 'initialize' && initializeError
+        ? { id: request.id, error: 'ROM_OPERATION_FAILED', method: 'initialize', detail: initializeError }
+        : { id: request.id, result: request.method === 'initialize'
+          ? { chipFamily: 0x3280, chipRevision: 302, chipMac: mac, connectionMode: 'no-reset' } : null }) + '\n'))
+      done()
+    },
+    final(done) { child.exitCode = 0; queueMicrotask(() => child.emit('exit', 0)); done() },
+  })
+  child.kill = () => { child.exitCode = 1; child.emit('exit', 1) }
+  const selected = { port: '/dev/rebound-rom', expectedMac: expected, transition: { requested: true } }
+  const dependencies = {
+    async preparePort(options) { calls.push(['prepare', options]); return prepare ? prepare(options) : selected },
+    spawn(...args) { calls.push(['spawn', ...args]); return child },
+  }
+  return { calls, requests, child, selected, dependencies }
+}
+
+test('Node ROM process uses the qualified rebound port and verifies its actual MAC before writes', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime', python: 'test-python' }, f.dependencies)
+  try {
+    await loader.initialize()
+    assert.equal(f.calls[1][2][2], '/dev/rebound-rom')
+    assert.equal(loader.port, '/dev/rebound-rom')
+    assert.equal(loader.chipMac, 'e8f60ae75642')
+    assert.equal(loader.connectionMode, 'no-reset')
+    assert.deepEqual(loader.usbTransition, { requested: true })
+    await loader.flashData(new Uint8Array([1, 2]), () => {}, 65536)
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'write'])
+  } finally { await loader.disconnect() }
+})
+
+test('a ROM MAC mismatch closes the process and cannot be followed by a write', async () => {
+  const f = fixture({ expected: '001122334455' }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), { code: 'ROM_IDENTITY_CHANGED' })
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_CLOSED' })
+  assert.deepEqual(f.requests.map(r => r.method), ['initialize'])
+  assert.equal(f.child.exitCode, 0)
+})
+
+test('initialization is single use and never repeats a bootloader handoff', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await loader.initialize()
+    await assert.rejects(loader.initialize(), { code: 'ROM_ALREADY_INITIALIZED' })
+    assert.equal(f.calls.filter(c => c[0] === 'prepare').length, 1)
+    assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+  } finally { await loader.disconnect() }
+})
+
+test('flash operations before initialization fail without spawning or sending a process request', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_NOT_INITIALIZED' })
+  assert.equal(f.calls.length, 0)
+  assert.equal(f.requests.length, 0)
+  await loader.disconnect()
+})
+
+test('disconnect cancels a pending port handoff before any ROM process can start', async () => {
+  const f = fixture({ prepare: ({ signal }) => new Promise((resolve, reject) => {
+    signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+  }) })
+  const loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  const initializing = loader.initialize()
+  const rejected = assert.rejects(initializing, { code: 'ROM_CLOSED' })
+  await loader.disconnect()
+  await rejected
+  assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 0)
+})
+
+test('handoff failure retains its cause and cannot replay on the same loader', async () => {
+  const reason = Object.assign(new Error('ROM did not re-enumerate'), { code: 'ROM_PORT_LOST' })
+  const f = fixture({ prepare: () => { throw reason } }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), error => error === reason)
+  await assert.rejects(loader.initialize(), { code: 'ROM_CLOSED' })
+  assert.equal(f.calls.length, 1)
+})
+
+test('underlying ROM initialization diagnostics survive cleanup and prevent writes', async () => {
+  const f = fixture({ initializeError: 'No serial data received' }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), error => error.code === 'ROM_OPERATION_FAILED'
+    && error.operation === 'initialize' && error.cause === 'No serial data received')
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_CLOSED' })
+  assert.equal(f.requests.length, 1)
+})
+
+test('one read-only ROM sync failure may hand off the verified same runtime before any write', async () => {
+  const first = fixture({ initializeError: 'No serial data received' }), second = fixture()
+  const oldPort = { port: '/dev/rom', expectedMac: 'e8f60ae75642', transition: { observed: 'rom', requested: false } }
+  const rebound = { port: '/dev/rebound', expectedMac: oldPort.expectedMac, transition: { observed: 'rom', requested: true } }
+  let starts = 0, recoveries = 0
+  const loader = openNodeRom({ port: '/dev/rom' }, {
+    preparePort: async () => oldPort,
+    recoverPort: async previous => { assert.equal(previous, oldPort); recoveries++; return rebound },
+    spawn: () => (++starts === 1 ? first.child : second.child),
+  })
+  try {
+    await loader.initialize()
+    assert.equal(starts, 2)
+    assert.equal(recoveries, 1)
+    assert.equal(loader.usbTransition.previousInitialization.detail, 'No serial data received')
+    assert.deepEqual(first.requests.map(r => r.method), ['initialize'])
+    assert.deepEqual(second.requests.map(r => r.method), ['initialize'])
+    await loader.flashData(new Uint8Array([1]), () => {}, 65536)
+    assert.deepEqual(second.requests.map(r => r.method), ['initialize', 'write'])
+  } finally { await loader.disconnect() }
+})
+
+test('an initialization that already requested bootloader cannot request it again', async () => {
+  const f = fixture({ initializeError: 'Still no serial data' })
+  f.selected.transition = { observed: 'rom', requested: true }
+  let recoveries = 0
+  const loader = openNodeRom({ port: '/dev/runtime' }, { ...f.dependencies,
+    recoverPort: async () => { recoveries++; throw Error('Must not replay bootloader') },
+  })
+  await assert.rejects(loader.initialize(), error => error.cause === 'Still no serial data')
+  assert.equal(recoveries, 0)
+  assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+})
+
+test('absence of a confirmed runtime preserves the initial ROM sync failure without replay', async () => {
+  const f = fixture({ initializeError: 'No serial data received' })
+  f.selected.transition = { observed: 'rom', requested: false }
+  const loader = openNodeRom({ port: '/dev/rom' }, { ...f.dependencies, recoverPort: async () => null })
+  await assert.rejects(loader.initialize(), error => error.code === 'ROM_OPERATION_FAILED'
+    && error.operation === 'initialize' && error.cause === 'No serial data received')
+  assert.equal(f.requests.length, 1)
+})
+
+test('a second initialization sync failure cannot trigger a third process or handoff', async () => {
+  const first = fixture({ initializeError: 'First sync failed' }), second = fixture({ initializeError: 'Second sync failed' })
+  const selected = { port: '/dev/rom', expectedMac: 'e8f60ae75642', transition: { observed: 'rom', requested: false } }
+  let starts = 0, recoveries = 0
+  const loader = openNodeRom({ port: '/dev/rom' }, {
+    preparePort: async () => selected,
+    recoverPort: async () => { recoveries++; return { ...selected, transition: { observed: 'rom', requested: true } } },
+    spawn: () => (++starts === 1 ? first.child : second.child),
+  })
+  await assert.rejects(loader.initialize(), error => error.cause === 'Second sync failed'
+    && error.transition.previousInitialization.detail === 'First sync failed')
+  assert.equal(starts, 2)
+  assert.equal(recoveries, 1)
+  assert.equal(first.requests.length + second.requests.length, 2)
+})