@esp-vision/device-core 0.5.1 → 0.6.1

package/src/node_rom.js

@@ -4,14 +4,18 @@ import { spawn } from 'node:child_process'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import { defaultPython } from './node_inventory.js'
+import { prepareNodeRomPort, recoverNodeRomPort } from './node_rom_port.js'
 
-export function openNodeRom({ port, python = defaultPython, signal } = {}) {
+export function openNodeRom({ port, python = defaultPython, signal } = {}, dependencies = {}) {
   if (!port) throw new TypeError('Firmware update requires a local --port')
-  let child, input, pending, sequence = 0, closed = false
-  const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool>=5.3,<6 for the built-in flasher' : 'ROM operation failed'), { code })
+  const lifecycle = new AbortController()
+  signal = signal ? AbortSignal.any([signal, lifecycle.signal]) : lifecycle.signal
+  let child, input, pending, sequence = 0, closed = false, initializing = false, romReady = false
+  const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool==5.6.0 for the built-in flasher' : 'ROM operation failed'), { code })
   const reject = code => { if (pending) { clearTimeout(pending.timer); pending.reject(fail(code)); pending = null } }
   function rpc(method, args = []) {
     if (closed) return Promise.reject(fail('ROM_CLOSED'))
+    if (!child || (method !== 'initialize' && !romReady)) return Promise.reject(fail('ROM_NOT_INITIALIZED'))
     if (pending) return Promise.reject(fail('ROM_BUSY'))
     return new Promise((resolve, rejectPromise) => {
       const id = ++sequence
@@ -19,45 +23,104 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}) {
       child.stdin.write(JSON.stringify({ id, method, args }) + '\n', error => { if (error) reject('ROM_IO_FAILED') })
     })
   }
+  async function closeProcess() {
+    const process = child
+    child = null; romReady = false; reject('ROM_CLOSED'); input?.close(); input = null
+    if (!process || process.exitCode !== null) return
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { process.kill(); resolve() }, 2000)
+      process.once('exit', () => { clearTimeout(timer); resolve() })
+      process.stdin.end()
+    })
+  }
+  function startProcess(selected) {
+    signal.throwIfAborted()
+    const process = (dependencies.spawn ?? spawn)(python, ['-u', fileURLToPath(new URL('./node_rom.py', import.meta.url)), selected.port], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true })
+    child = process
+    const active = action => { if (child === process) action() }
+    process.on('error', () => active(() => reject('ESPTOOL_UNAVAILABLE')))
+    process.on('exit', () => active(() => reject('ROM_CLOSED')))
+    process.stdin.on('error', () => active(() => reject('ROM_IO_FAILED')))
+    input = createInterface({ input: process.stdout })
+    input.on('line', line => {
+      if (child !== process) return
+      try {
+        const message = JSON.parse(line)
+        if (message.error && !message.id) return reject(message.error)
+        if (!pending || message.id !== pending.id) return
+        const operation = pending; pending = null; clearTimeout(operation.timer)
+        if (message.error) operation.reject(Object.assign(fail(message.error), { operation: message.method, cause: message.detail })); else operation.resolve(message.result)
+      } catch { reject('ROM_RESPONSE_INVALID') }
+    })
+    return rpc('initialize')
+  }
   const loader = {
     async initialize() {
-      signal?.throwIfAborted()
-      child = spawn(python, ['-u', fileURLToPath(new URL('./node_rom.py', import.meta.url)), port], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true })
-      child.on('error', () => reject('ESPTOOL_UNAVAILABLE'))
-      child.on('exit', () => reject('ROM_CLOSED'))
-      child.stdin.on('error', () => reject('ROM_IO_FAILED'))
-      input = createInterface({ input: child.stdout })
-      input.on('line', line => {
-        try {
-          const message = JSON.parse(line)
-          if (message.error && !message.id) return reject(message.error)
-          if (!pending || message.id !== pending.id) return
-          const operation = pending; pending = null; clearTimeout(operation.timer)
-          if (message.error) operation.reject(Object.assign(fail(message.error), { operation: message.method, cause: message.detail })); else operation.resolve(message.result)
-        } catch { reject('ROM_RESPONSE_INVALID') }
-      })
+      signal.throwIfAborted()
+      if (closed) throw fail('ROM_CLOSED')
+      if (initializing || child) throw fail('ROM_ALREADY_INITIALIZED')
+      initializing = true
+      let selected
       const cancelled = () => { reject('CANCELLED'); void loader.disconnect() }
-      signal?.addEventListener('abort', cancelled, { once: true })
-      try { Object.assign(loader, await rpc('initialize')) }
-      finally { signal?.removeEventListener('abort', cancelled) }
+      signal.addEventListener('abort', cancelled, { once: true })
+      try {
+        selected = await (dependencies.preparePort ?? prepareNodeRomPort)({ port, python, signal })
+        signal.throwIfAborted()
+        let identity
+        try { identity = await startProcess(selected) }
+        catch (error) {
+          await closeProcess()
+          signal.throwIfAborted()
+          // No writes have been accepted. A ROM/stub can return to its app
+          // between enumeration and SYNC. Recover only after observing that
+          // same physical device's runtime; never repeat a previous handoff.
+          if (error.code !== 'ROM_OPERATION_FAILED' || error.operation !== 'initialize'
+              || !selected.expectedMac || selected.transition?.observed !== 'rom'
+              || selected.transition.requested !== false) throw error
+          const recovered = await (dependencies.recoverPort ?? recoverNodeRomPort)(selected, { python, signal })
+          if (!recovered) throw error
+          selected = recovered
+          selected.transition.previousInitialization = { code: error.code, operation: error.operation, detail: String(error.cause ?? '').slice(0, 1024) }
+          signal.throwIfAborted()
+          identity = await startProcess(selected)
+        }
+        if (selected.expectedMac && identity.chipMac !== selected.expectedMac) {
+          throw Object.assign(new Error('ROM MAC differs from the selected USB device'), { code: 'ROM_IDENTITY_CHANGED' })
+        }
+        Object.assign(loader, identity, { port: selected.port, usbTransition: selected.transition })
+        romReady = true
+      } catch (error) {
+        if (error && typeof error === 'object' && selected?.transition) error.transition ??= selected.transition
+        await loader.disconnect()
+        throw error
+      } finally { initializing = false; signal.removeEventListener('abort', cancelled) }
     },
     flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
     async runStub() { await rpc('stub'); return loader },
-    async readFlash(offset, bytes) { return new Uint8Array(Buffer.from(await rpc('read', [offset, bytes]), 'base64')) },
+    async readFlash(offset, bytes, progress, options) {
+      if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(bytes) || bytes <= 0 || bytes > 0xffffffff
+          || offset + bytes > 0x100000000) throw new RangeError('ROM read requires a positive 32-bit address range')
+      if (progress !== undefined && typeof progress !== 'function') throw new TypeError('ROM read progress must be a function')
+      if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) throw new TypeError('ROM read options must be an object')
+      if (options && Object.keys(options).some(key => !['blockSize', 'maxInFlight', 'chunkSize'].includes(key))) throw new TypeError('Unsupported ROM read option')
+      const blockSize = options?.blockSize === undefined ? 1024 : options.blockSize
+      const maxInFlight = options?.maxInFlight === undefined ? 1 : options.maxInFlight
+      if (![1024, 4096].includes(blockSize) || !Number.isSafeInteger(maxInFlight) || maxInFlight < 1 || maxInFlight > 64) throw new RangeError('ROM read requires 1024 or 4096 byte blocks and 1..64 outstanding packets')
+      if (options?.chunkSize !== undefined && (!Number.isSafeInteger(options.chunkSize) || options.chunkSize <= 0 || bytes > options.chunkSize)) throw new RangeError('ROM read exceeds the requested chunk size')
+      const data = new Uint8Array(Buffer.from(await rpc('read', [offset, bytes, { blockSize, maxInFlight }]), 'base64'))
+      if (data.length !== bytes) throw Object.assign(fail('ROM_READ_LENGTH'), { operation: 'read' })
+      progress?.(data, data.length, bytes)
+      return data
+    },
     async flashData(bytes, progress, offset) { await rpc('write', [offset, Buffer.from(bytes).toString('base64')]); progress(bytes.byteLength, bytes.byteLength) },
     readRegister: address => rpc('readRegister', [address]),
     writeRegister: (address, value, mask) => rpc('writeRegister', [address, value, mask]),
     hardReset: () => rpc('reset'),
     async disconnect() {
       if (closed) return
-      closed = true; reject('ROM_CLOSED'); input?.close()
-      if (!child || child.exitCode !== null) return
-      await new Promise(resolve => {
-        const timer = setTimeout(() => { child.kill(); resolve() }, 2000)
-        child.once('exit', () => { clearTimeout(timer); resolve() })
-        child.stdin.end()
-      })
+      closed = true; lifecycle.abort(fail('ROM_CLOSED'))
+      await closeProcess()
     },
   }
   return loader

package/src/node_rom.py

@@ -4,15 +4,129 @@
 import base64
 import contextlib
 import json
+import os
+import struct
 import sys
 
 
+def _port_key(port):
+    name = str(port)
+    if name.startswith('\\\\.\\'):
+        name = name[4:]
+    if name.upper().startswith('COM') and name[3:].isdigit():
+        return name.upper()
+    return os.path.realpath(name)
+
+
+def _reset_supported(port):
+    # Descriptors permit a reset policy, never establish firmware/board identity.
+    # Unknown/native USB ports must not receive the UART DTR/RTS sequence.
+    try:
+        from serial.tools.list_ports import comports
+        matches = {(item.vid, item.pid) for item in comports()
+                   if _port_key(item.device) == _port_key(port)}
+    except (ImportError, OSError, ValueError):
+        return False
+    if len(matches) != 1:
+        return False
+    vid, pid = next(iter(matches))
+    return vid in {0x10c4, 0x1a86, 0x0403, 0x067b} or (vid, pid) == (0x303a, 0x1001)
+
+
+def _open_rom(esptool, port):
+    import serial
+    modes = ['no-reset', 'default-reset'] if _reset_supported(port) else ['no-reset']
+    first_error = None
+    for mode in modes:
+        if mode == 'default-reset' and not _reset_supported(port):
+            raise RuntimeError(f'Port no longer permits reset after synchronization failed: {first_error}') from first_error
+        connection = serial.serial_for_url(port, baudrate=115200, exclusive=True, do_not_open=True)
+        try:
+            # Set before open on every OS, as esptool does on Windows. Opening
+            # with asserted RTS can otherwise perturb an already-running stub.
+            connection.rts = False
+            connection.dtr = False
+            connection.open()
+            loader = esptool.detect_chip(port=connection, connect_mode=mode,
+                                         connect_attempts=1 if mode == 'no-reset' else 7)
+            return loader, mode
+        except Exception as error:
+            if connection.is_open:
+                connection.close()
+            if mode == modes[-1]:
+                if first_error is not None:
+                    raise RuntimeError(f'No-reset synchronization failed: {first_error}; reset connection failed: {error}') from error
+                raise
+            first_error = error
+
+
+
+def _read_flash(esp, offset, length, options=None):
+    """Bound the upstream stub reader without replacing its ACK/MD5 parser."""
+    if type(offset) is not int or offset < 0 or type(length) is not int or length <= 0 or length > 0xffffffff or offset + length > 0x100000000:
+        raise ValueError('ROM read requires a positive 32-bit address range')
+    if options is None:
+        options = {}
+    if not isinstance(options, dict) or set(options) - {'blockSize', 'maxInFlight'}:
+        raise ValueError('Unsupported ROM read options')
+    block_size, max_in_flight = options.get('blockSize', 1024), options.get('maxInFlight', 1)
+    if type(block_size) is not int or block_size not in (1024, 4096) or type(max_in_flight) is not int or not 1 <= max_in_flight <= 64:
+        raise ValueError('ROM read requires 1024 or 4096 byte blocks and 1..64 outstanding packets')
+    if not getattr(esp, 'IS_STUB', False):
+        raise RuntimeError('Bounded Flash read requires an initialized flasher stub')
+    if getattr(esp, 'FLASH_SECTOR_SIZE', None) != 4096 or not callable(getattr(esp, 'check_command', None)):
+        raise RuntimeError('Unsupported esptool stub read layout; use esptool==5.6.0')
+    command = esp.ESP_CMDS['READ_FLASH']
+    original_check = esp.check_command
+    missing = object()
+    old_check = vars(esp).get('check_command', missing)
+    old_block = vars(esp).get('FLASH_SECTOR_SIZE', missing)
+    commands = 0
+    block_changed = check_changed = False
+
+    def bounded_check(op_description, op=None, data=b'', *args, **kwargs):
+        nonlocal commands
+        if op == command:
+            commands += 1
+            if commands != 1 or not isinstance(data, bytes) or len(data) != 16:
+                raise RuntimeError('Unsupported esptool READ_FLASH command layout')
+            wire_offset, wire_length, wire_block, wire_window = struct.unpack('<IIII', data)
+            if (wire_offset, wire_length, wire_block, wire_window) != (offset, length, block_size, 64):
+                raise RuntimeError('Unexpected esptool READ_FLASH range or packet layout')
+            data = struct.pack('<IIII', offset, length, block_size, max_in_flight)
+        return original_check(op_description, op, data, *args, **kwargs)
+
+    try:
+        # Upstream 5.6.0 uses this instance field for both its request and its
+        # short-packet validation. Changing only the wire request is invalid.
+        esp.FLASH_SECTOR_SIZE = block_size
+        block_changed = True
+        esp.check_command = bounded_check
+        check_changed = True
+        result = esp.read_flash(offset, length)
+        if commands != 1 or not isinstance(result, bytes) or len(result) != length:
+            raise RuntimeError('Upstream Flash read did not complete the bounded request')
+        return result
+    finally:
+        try:
+            if check_changed:
+                if old_check is missing:
+                    del esp.check_command
+                else:
+                    esp.check_command = old_check
+        finally:
+            if block_changed:
+                if old_block is missing:
+                    del esp.FLASH_SECTOR_SIZE
+                else:
+                    esp.FLASH_SECTOR_SIZE = old_block
+
+
 def main():
     with contextlib.redirect_stdout(sys.stderr):
         import esptool
-    major, minor = map(int, esptool.__version__.split('.')[:2])
-    if major != 5 or minor < 3:
-        raise RuntimeError('Install esptool>=5.3,<6')
+    if esptool.__version__ != '5.6.0':
+        raise RuntimeError('Install esptool==5.6.0 for the verified bounded Flash reader')
     esp = None
     families = {'ESP32-P4': 0x3280, 'ESP32-S3': 0x3253, 'ESP32-S31': 0x3231}
     try:
@@ -22,9 +136,23 @@ def main():
                 with contextlib.redirect_stdout(sys.stderr):
                     method, args = request['method'], request.get('args', [])
                     result = None
+                    if method != 'initialize' and esp is None:
+                        raise RuntimeError('Initialize the ROM adapter before issuing operations')
                     if method == 'initialize':
-                        esp = esptool.detect_chip(port=sys.argv[1])
-                        result = {'chipFamily': families.get(esp.CHIP_NAME), 'chipRevision': esp.get_chip_revision()}
+                        if esp is not None:
+                            raise RuntimeError('ROM adapter is already initialized')
+                        candidate, mode = _open_rom(esptool, sys.argv[1])
+                        try:
+                            mac = bytes(candidate.read_mac())
+                            if len(mac) != 6:
+                                raise RuntimeError('ROM did not return a six-byte factory MAC')
+                            result = {'chipFamily': families.get(candidate.CHIP_NAME), 'chipRevision': candidate.get_chip_revision(),
+                                      'connectionMode': mode, 'stubRunning': bool(candidate.IS_STUB), 'chipMac': mac.hex()}
+                        except Exception:
+                            if candidate._port.is_open:
+                                candidate._port.close()
+                            raise
+                        esp = candidate
                     elif method == 'security':
                         security = esp.get_security_info()
                         result = {'flags': security['flags'], 'flashCryptCnt': security['flash_crypt_cnt']}
@@ -35,7 +163,7 @@ def main():
                     elif method == 'flashId':
                         result = esp.flash_id()
                     elif method == 'read':
-                        result = base64.b64encode(esp.read_flash(*args)).decode('ascii')
+                        result = base64.b64encode(_read_flash(esp, *args)).decode('ascii')
                     elif method == 'write':
                         offset, encoded = args
                         data = base64.b64decode(encoded, validate=True)

package/src/node_rom_port.js

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import { realpath } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+import { createDevice } from './index.js'
+import { defaultPython, listSerial } from './node_inventory.js'
+import { serialTransport } from './node_transport.js'
+
+const ROM_PIDS = new Set([2, 9, 18, 32])
+// Confirmed ESP-VISION runtime composites: CDC+MSC and CDC+MSC+UVC.
+const RUNTIME_PIDS = new Set([0x4003, 0x4023])
+const UNIQUE_ID_SOURCE = "import machine,ubinascii\nprint('__EV_ROM_ID__'+ubinascii.hexlify(machine.unique_id()).decode())"
+function fail(code, message, cause) { return Object.assign(new Error(message), { code, ...(cause ? { cause } : {}) }) }
+function checkAbort(signal) {
+  if (!signal?.aborted) return
+  throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error('ROM port preparation cancelled'), { name: 'AbortError' })
+}
+function errorInfo(error) { return { code: error?.code ?? error?.name ?? 'ERROR', message: String(error?.message ?? error).slice(0, 512) } }
+function mac(value) {
+  if (typeof value !== 'string') return null
+  const result = value.replace(/[:-]/g, '').toLowerCase()
+  return /^[0-9a-f]{12}$/.test(result) ? result : null
+}
+function comKey(value) {
+  return typeof value === 'string' && /^(?:\\\\\.\\)?COM[1-9]\d*$/i.test(value)
+    ? value.replace(/^\\\\\.\\/, '').toUpperCase() : null
+}
+function physicalLocation(value) {
+  // pyserial adds :configuration.interface (Windows uses :x.interface).
+  return typeof value === 'string' && value.trim() ? value.trim().replace(/:(?:\d+|x)\.\d+$/i, '') : null
+}
+function nativeRom(port) { return port.vendorId === 0x303a && ROM_PIDS.has(port.productId) }
+function nativeRuntime(port) { return port.vendorId === 0x303a && RUNTIME_PIDS.has(port.productId) }
+
+/** Resolve only the selected port. Descriptors authorize a handoff, never a flash. */
+export async function prepareNodeRomPort({ port, python = defaultPython, signal, timeout = 5000, expectedIdentity } = {}, dependencies = {}) {
+  if (typeof port !== 'string' || !port || /[\x00-\x1f\x7f]/.test(port)) throw new TypeError('ROM preparation requires a local port')
+  if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 5000) throw new RangeError('ROM preparation timeout must be positive and at most 5000 ms')
+  const required = expectedIdentity == null ? null : { mac: mac(expectedIdentity.mac), location: physicalLocation(expectedIdentity.location) }
+  if (required && (!required.mac || !required.location)) throw new TypeError('Bound ROM preparation requires a MAC and physical USB location')
+  const enumerate = dependencies.listSerial ?? listSerial
+  const resolvePath = dependencies.realpath ?? realpath
+  const now = dependencies.now ?? (() => performance.now())
+  const sleep = dependencies.sleep ?? ((ms, abortSignal) => delay(ms, undefined, { signal: abortSignal }))
+  const makeDevice = dependencies.createDevice ?? createDevice
+  const makeTransport = dependencies.serialTransport ?? serialTransport
+  checkAbort(signal)
+  const settleDeadline = now() + timeout
+  let canonical = comKey(port)
+  while (!canonical) {
+    checkAbort(signal)
+    try {
+      canonical = await resolvePath(port)
+      if (typeof canonical !== 'string' || !canonical) throw fail('ROM_PORT_LOST', 'The selected path has no canonical serial address')
+    }
+    catch (error) {
+      checkAbort(signal)
+      if (error.code !== 'ENOENT' || now() >= settleDeadline) throw fail('ROM_PORT_LOST', 'The selected serial path is unavailable; select its current port', error)
+      await sleep(Math.min(50, settleDeadline - now()), signal)
+    }
+  }
+  checkAbort(signal)
+  let ports
+  try { ports = await enumerate({ python, signal, timeout }) }
+  catch (error) {
+    checkAbort(signal)
+    if (required) throw fail('ROM_PORT_IDENTITY_REQUIRED', 'Cannot confirm the bound runtime descriptors', error)
+    // A known OS path may still be used without descriptors, but never probed
+    // as an EV-MUX runtime or rebound to a different port.
+    return { port: canonical, expectedMac: null, transition: null }
+  }
+  checkAbort(signal)
+  if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
+  const selected = ports.filter(item => item.path === port || item.path === canonical || (comKey(item.path) && comKey(item.path) === canonical))
+  if (selected.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'The selected port has ambiguous descriptors')
+  if (!selected.length) {
+    if (required) throw fail('ROM_PORT_LOST', 'The bound runtime port is no longer enumerated')
+    return { port: canonical, expectedMac: null, transition: null }
+  }
+  const current = selected[0]
+  const expectedMac = mac(current.serialNumber)
+  const location = physicalLocation(current.location)
+  if (required && (expectedMac !== required.mac || location !== required.location)) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'The selected runtime descriptors changed before recovery')
+  if (nativeRom(current)) return {
+    port: current.path, expectedMac,
+    transition: { requested: false, observed: 'rom', selectedPort: port, port: current.path, serial: expectedMac, location },
+  }
+  if (!nativeRuntime(current)) return { port: canonical, expectedMac: null, transition: null }
+  if (!expectedMac || !location) throw fail('ROM_PORT_IDENTITY_REQUIRED', 'Native USB runtime requires a MAC serial and physical USB location')
+
+  const transition = { requested: false, selectedPort: port, runtimePort: current.path, expectedMac, location,
+    command: { attempted: false, acknowledged: false, outcome: 'not_attempted' }, cleanup: null, observed: null }
+  let device, primary
+  try {
+    device = makeDevice({ transport: makeTransport({ serial: current.path, role: 'usb', python }) })
+    const connected = await device.connect({ role: 'usb', probeRepl: false, autoBaud: false, timeout, signal })
+    checkAbort(signal)
+    const owners = connected?.capabilities?.sinks?.filter(sink => sink.owner === true) ?? []
+    if (owners.length !== 1 || owners[0].id !== 'usb' || owners[0].kind !== 'usb_otg_cdc' || owners[0].state !== 'active' || owners[0].ready !== true) {
+      throw fail('ROM_RUNTIME_INTERFACE_MISMATCH', 'The selected runtime did not establish the active USB owner')
+    }
+    let runtimeMac = connected?.identity?.deviceId
+    let identitySource = 'runtime.deviceId'
+    if (runtimeMac == null) {
+      const result = await device.python.execute({ source: UNIQUE_ID_SOURCE, completion: 'wait', timeout, maxOutputChars: 512, signal })
+      checkAbort(signal)
+      const matches = typeof result?.output === 'string' ? [...result.output.matchAll(/^__EV_ROM_ID__([0-9a-f]{12})\r?$/gim)] : []
+      if (result?.ok !== true || result.outputTruncated !== false || matches.length !== 1 || /Traceback/.test(result.output)) {
+        throw fail('ROM_RUNTIME_IDENTITY_UNAVAILABLE', 'The legacy runtime did not return one complete unique_id')
+      }
+      runtimeMac = matches[0][1]
+      identitySource = 'machine.unique_id'
+    }
+    if (mac(runtimeMac) !== expectedMac) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime identity does not match the selected USB serial')
+    transition.identitySource = identitySource
+    checkAbort(signal)
+    transition.requested = true
+    transition.command = { attempted: true, acknowledged: false, outcome: 'unknown' }
+    try {
+      const result = await device.control({ action: 'bootloader', timeout, signal })
+      checkAbort(signal)
+      if (result?.ok !== true || result.operation !== 'bootloader') throw fail('ROM_BOOTLOADER_REJECTED', 'Runtime did not accept the bootloader command')
+      transition.command = { attempted: true, acknowledged: result.acknowledged === true, outcome: result.outcome ?? 'unknown' }
+    } catch (error) {
+      checkAbort(signal)
+      if (error.reset?.outcome !== 'unknown' && error.outcome !== 'unknown') throw error
+      transition.command = { attempted: true, acknowledged: false, outcome: 'unknown', error: errorInfo(error) }
+    }
+  } catch (error) { primary = error }
+  finally {
+    if (device) {
+      try { await device.disconnect(); transition.cleanup = { ok: true } }
+      catch (error) { transition.cleanup = { ok: false, error: errorInfo(error) } }
+    }
+  }
+  try { checkAbort(signal) } catch (error) { primary ??= error }
+  if (primary) {
+    primary.transition = transition
+    if (transition.cleanup?.ok === false) primary.cleanupError = transition.cleanup.error
+    throw primary
+  }
+
+  // No reset replay: only the selected physical device's ROM may finish the
+  // handoff. A successful match does not turn an unknown command into an ACK.
+  const deadline = now() + timeout
+  while (now() < deadline) {
+    checkAbort(signal)
+    const remaining = Math.max(1, Math.ceil(deadline - now()))
+    let candidates
+    try { candidates = await enumerate({ python, signal, timeout: remaining }) }
+    catch (error) {
+      checkAbort(signal)
+      throw Object.assign(fail('ROM_PORT_REBIND_FAILED', 'Cannot enumerate the selected device after bootloader submission', error), { transition })
+    }
+    checkAbort(signal)
+    if (now() >= deadline) break
+    if (!Array.isArray(candidates)) throw Object.assign(fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors'), { transition })
+    const matches = candidates.filter(item => nativeRom(item) && mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location)
+    if (matches.length > 1) throw Object.assign(fail('ROM_PORT_AMBIGUOUS', 'Multiple ROM ports match the selected device'), { transition })
+    if (matches.length === 1) {
+      const selectedRom = matches[0]
+      transition.observed = 'rom'
+      transition.port = selectedRom.path
+      return { port: selectedRom.path, expectedMac, transition }
+    }
+    await sleep(Math.min(50, Math.max(1, deadline - now())), signal)
+  }
+  throw Object.assign(fail('ROM_PORT_REBIND_TIMEOUT', 'The selected device did not expose one matching ROM port within the deadline'), { transition })
+}
+
+
+/** Only for the caller's first read-only initialize failure, never read/write. */
+export async function recoverNodeRomPort(previous, { python = defaultPython, signal, timeout = 5000 } = {}, dependencies = {}) {
+  checkAbort(signal)
+  if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 5000) throw new RangeError('ROM recovery timeout must be positive and at most 5000 ms')
+  const expectedMac = mac(previous?.expectedMac)
+  const location = physicalLocation(previous?.transition?.location)
+  if (!expectedMac || !location || previous?.transition?.observed !== 'rom' || previous.transition.requested !== false) return null
+  if (mac(previous.transition.serial) !== expectedMac) return null
+  const enumerate = dependencies.listSerial ?? listSerial
+  const now = dependencies.now ?? (() => performance.now())
+  const sleep = dependencies.sleep ?? ((ms, abortSignal) => delay(ms, undefined, { signal: abortSignal }))
+  const deadline = now() + timeout
+  const sameDevice = item => mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location
+  let runtime
+  // A closed native stub may still enumerate as ROM, then disappear before
+  // the same device's runtime reappears. Only observe during this window;
+  // never re-SYNC the stale ROM or issue a second handoff while it settles.
+  while (now() < deadline) {
+    checkAbort(signal)
+    let ports
+    try { ports = await enumerate({ python, signal, timeout: Math.max(1, Math.ceil(deadline - now())) }) }
+    catch (error) {
+      checkAbort(signal)
+      throw fail('ROM_PORT_ENUMERATION_FAILED', 'Cannot verify the selected device for read-only initialization recovery', error)
+    }
+    checkAbort(signal)
+    if (now() >= deadline) throw fail('ROM_PORT_REBIND_TIMEOUT', 'Read-only initialization recovery enumeration exceeded its deadline')
+    if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
+    const candidates = ports.filter(item => nativeRom(item) || nativeRuntime(item))
+    const conflicting = candidates.filter(item => (mac(item.serialNumber) === expectedMac || physicalLocation(item.location) === location) && !sameDevice(item))
+    if (conflicting.length) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime descriptors do not match the previously selected ROM device')
+    const matches = candidates.filter(sameDevice)
+    if (matches.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple native USB ports match the selected device')
+    if (matches.length && nativeRuntime(matches[0])) { runtime = matches[0]; break }
+    await sleep(Math.min(50, Math.max(1, deadline - now())), signal)
+  }
+  // Returning null preserves the caller's original initialize failure.
+  if (!runtime) return null
+  // Revalidate at prepare's fresh enumeration, before opening EV-MUX. An OS port
+  // may have been reused for a different board since the recovery snapshot.
+  const result = await prepareNodeRomPort({ port: runtime.path, python, signal, timeout,
+    expectedIdentity: { mac: expectedMac, location } }, dependencies)
+  if (result.expectedMac !== expectedMac || result.transition?.observed !== 'rom' || physicalLocation(result.transition.location) !== location) {
+    throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Recovery did not preserve the selected physical device identity')
+  }
+  result.transition.recovery = { previousPort: previous.port, runtimePid: runtime.productId }
+  return result
+}