@esp-vision/device-core 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.1
+
+### Fixed
+
+- Accept native Windows CRLF startup lines in the direct Python serial-failure regression so its diagnostic and payload-redaction assertions run on Windows.
+
+- Preserve bounded serial read/write OS diagnostics and unexpected Python bridge exit codes/signals instead of reducing them to CONNECTION_CLOSED; omit arbitrary exception text and all transferred bytes, and keep intentional disconnect/cancellation quiet.
+
+- Run package and release checks through npm's JavaScript entry point on Windows, preserving paths and arguments without a command shell; accept checkout CRLF in the generated action-schema check while still rejecting changed schema content.
+- Observe native USB re-enumeration for up to five seconds after read-only ROM initialization failure, requiring the same MAC and physical location before one verified runtime handoff; cancellation, ambiguous descriptors and failed reads/writes cannot replay operations.
+- Forward Node readback packet budgets to the external esptool 5.6.0 reader, using one outstanding 1 KiB packet by default and preserving its ACK/MD5 verification. Reject incompatible versions before initialization or writing and restore temporary instance settings after success or failure.
+
 ## 0.6.0
 
 ### Added

package/README.md

@@ -52,7 +52,7 @@ esp-vision-device inspect --port COM3 --fields identity,capabilities
 esp-vision-device inspect --tcp 192.168.1.100:3232 --fields network,storage --json
 ```
 
-Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Use `firmware update --mode install --board BOARD --port PORT --version VERSION` for blank-device installation over a ROM-capable USJ/UART port. Install replaces data within the complete image range; default updates preserve the existing layout. Historical releases without qualified metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
+Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool==5.6.0; no user loader module is required. Use `firmware update --mode install --board BOARD --port PORT --version VERSION` for blank-device installation over a ROM-capable USJ/UART port. Install replaces data within the complete image range; default updates preserve the existing layout. Historical releases without qualified metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
 
 ## Public device API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -78,5 +78,5 @@
   "devDependencies": {
     "esbuild": "0.25.12"
   },
-  "espVisionReleaseType": "minor"
+  "espVisionReleaseType": "patch"
 }

package/schemas/device-actions-v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ESP Vision Device Actions",
-  "deviceCoreVersion": "0.6.0",
+  "deviceCoreVersion": "0.6.1",
   "schemaVersion": 1,
   "actions": [
     {

package/scripts/generate-action-schema.mjs

@@ -27,7 +27,8 @@ const document = {
 const serialized = `${JSON.stringify(document, null, 2)}\n`
 
 if (process.argv.includes('--check')) {
-  assert.equal(await readFile(outputPath, 'utf8'), serialized, 'Device Action schema artifact is stale; regenerate it')
+  const checkedIn = (await readFile(outputPath, 'utf8')).replaceAll('\r\n', '\n')
+  assert.equal(checkedIn, serialized, 'Device Action schema artifact is stale; regenerate it')
   console.log(`Device Action Schema ${DEVICE_ACTION_SCHEMA_VERSION} is current`)
 } else {
   await mkdir(dirname(outputPath), { recursive: true })

package/scripts/npm-command.mjs

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+// npm.cmd cannot be passed to execFile/spawn without a Windows shell. Invoke
+// npm's JavaScript entry point instead, preserving paths and arguments verbatim.
+export function npmCommand(args, env = process.env) {
+  if (env.npm_execpath) return [process.execPath, [env.npm_execpath, ...args]]
+  if (process.platform === 'win32') {
+    const bundled = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js')
+    if (!existsSync(bundled)) throw new Error('Run this check through npm run so npm_execpath identifies npm')
+    return [process.execPath, [bundled, ...args]]
+  }
+  return ['npm', args]
+}

package/scripts/release-npm.mjs

@@ -3,6 +3,7 @@
 import assert from 'node:assert/strict'
 import { highestStableVersion, validateVersionStep } from './version-policy.mjs'
 import { verifyPublishedIntegrity } from './verify-registry.mjs'
+import { npmCommand } from './npm-command.mjs'
 import { spawnSync } from 'node:child_process'
 import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -48,7 +49,7 @@ try {
   await writeFile(config, `registry=${registry}\n//registry.npmjs.org/:_authToken=\${NPM_PUBLISH_TOKEN}\n`, { mode: 0o600 })
   const env = dryRun ? { ...process.env } : { ...process.env, NPM_CONFIG_USERCONFIG: config }
   function npm(args) {
-    const result = spawnSync('npm', args, { cwd: root, env, encoding: 'utf8' })
+    const result = spawnSync(...npmCommand(args, env), { cwd: root, env, encoding: 'utf8' })
     if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.error?.message}`)
     return result.stdout
   }

package/src/node_rom.js

@@ -11,7 +11,7 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
   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.3,<6 for the built-in flasher' : 'ROM operation failed'), { code })
+  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'))
@@ -98,7 +98,21 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
     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]),

package/src/node_rom.py

@@ -5,6 +5,7 @@ import base64
 import contextlib
 import json
 import os
+import struct
 import sys
 
 
@@ -59,12 +60,73 @@ def _open_rom(esptool, port):
             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:
@@ -101,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

@@ -179,33 +179,41 @@ export async function recoverNodeRomPort(previous, { python = defaultPython, sig
   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
-  let ports
-  try { ports = await enumerate({ python, signal, timeout }) }
-  catch (error) {
+  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)
-    throw fail('ROM_PORT_ENUMERATION_FAILED', 'Cannot verify the selected device for read-only initialization recovery', error)
+    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)
   }
-  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 sameDevice = item => mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location
-  const existingRom = ports.filter(item => nativeRom(item) && sameDevice(item))
-  if (existingRom.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple ROM ports match the selected device')
-  if (existingRom.length) return null
-  const runtimes = ports.filter(nativeRuntime)
-  const conflicting = runtimes.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 = runtimes.filter(sameDevice)
-  if (matches.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple runtime ports match the selected device')
-  if (!matches.length) return null
+  // 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: matches[0].path, python, signal, timeout,
+  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: matches[0].productId }
+  result.transition.recovery = { previousPort: previous.port, runtimePid: runtime.productId }
   return result
 }

package/src/node_serial.py

@@ -11,6 +11,57 @@ import threading
 import serial
 
 
+def _report_serial_error(stage, error):
+    """Emit bounded OS diagnostics, never exception text or transferred bytes."""
+    number = getattr(error, 'errno', None)
+    winerror = getattr(error, 'winerror', None)
+    cause = error.__cause__ or error.__context__
+    if not isinstance(number, int) and cause is not None:
+        number = getattr(cause, 'errno', None)
+    if not isinstance(winerror, int) and cause is not None:
+        winerror = getattr(cause, 'winerror', None)
+    def bounded_number(value):
+        if isinstance(value, int) and not isinstance(value, bool) and -0x80000000 <= value <= 0xffffffff:
+            return value
+        return None
+    number = bounded_number(number)
+    winerror = bounded_number(winerror)
+    # Pyserial sometimes wraps a Windows API failure without preserving errno.
+    # Only recognize fixed API names/messages; arbitrary exception text may
+    # contain application bytes and must not cross this diagnostic channel.
+    text = str(error)[:512]
+    message = 'Serial ' + stage + ' failed'
+    if number is not None and 0 < number < 4096:
+        message = os.strerror(number)
+    else:
+        for needle, safe in (
+            ('ClearCommError', 'ClearCommError failed'),
+            ('GetOverlappedResult', 'GetOverlappedResult failed'),
+            ('ReadFile', 'ReadFile failed'),
+            ('WriteFile', 'WriteFile failed'),
+            ('readiness to read but returned no data', 'Device reports readiness to read but returned no data'),
+            ('write timeout', 'Serial write timed out'),
+            ('Zero-byte serial write', 'Serial write returned zero bytes'),
+        ):
+            if needle.lower() in text.lower():
+                message = safe
+                break
+    record = {'kind': 'serial.error', 'stage': stage, 'type': type(error).__name__[:64],
+              'errno': number, 'winerror': winerror, 'message': message[:160]}
+    # One small line keeps READY/control records intact when the reader thread
+    # fails concurrently with the main thread. stderr failure is terminal too.
+    line = (json.dumps(record, ensure_ascii=True) + '\n').encode()
+    try:
+        offset = 0
+        while offset < len(line):
+            count = os.write(2, line[offset:])
+            if count <= 0:
+                break
+            offset += count
+    except OSError:
+        pass
+
+
 def _configure_serial_exclusive(port, platform=os.name):
     # pyserial implements this as a non-blocking advisory lock on POSIX. The
     # Windows backend does not support this option, so leave its behavior alone.
@@ -50,16 +101,24 @@ def main():
         raise SystemExit(0)
 
     def receive():
-        try:
-            while not stopped.is_set():
+        while not stopped.is_set():
+            try:
                 data = port.read(8192)
-                if data:
+            except (OSError, serial.SerialException) as error:
+                if not stopped.is_set():
+                    _report_serial_error('read', error)
+                    os._exit(2)
+                return
+            if data:
+                try:
                     offset = 0
                     while offset < len(data):
                         offset += os.write(1, data[offset:])
-        except (OSError, serial.SerialException):
-            if not stopped.is_set():
-                os._exit(2)
+                except OSError as error:
+                    if not stopped.is_set():
+                        _report_serial_error('stdout', error)
+                        os._exit(2)
+                    return
 
     signal.signal(signal.SIGTERM, terminate)
     signal.signal(signal.SIGINT, terminate)
@@ -102,12 +161,16 @@ def main():
                     response = {'id': request.get('id'), 'ok': False}
                 print(json.dumps(response), file=sys.stderr, flush=True)
                 continue
-            offset = 0
-            while offset < len(data):
-                written = port.write(data[offset:])
-                if not written:
-                    raise OSError('Zero-byte serial write')
-                offset += written
+            try:
+                offset = 0
+                while offset < len(data):
+                    written = port.write(data[offset:])
+                    if not written:
+                        raise OSError('Zero-byte serial write')
+                    offset += written
+            except (OSError, serial.SerialException) as error:
+                _report_serial_error('write', error)
+                raise SystemExit(2) from None
     finally:
         stopped.set()
         port.close()

package/src/node_transport.js

@@ -39,7 +39,7 @@ export function tcpTransport(options) {
 
 export function serialTransport(options) {
   const events = subscribers()
-  let child, controlId = 0, baudRate = 115200
+  let child, connection, lastError = null, controlId = 0, baudRate = 115200
   const pending = new Map()
   const rejectControls = error => {
     for (const request of pending.values()) request.reject(error)
@@ -58,35 +58,65 @@ export function serialTransport(options) {
     connect({ signal }) {
       return new Promise((resolveConnect, reject) => {
         const adapter = fileURLToPath(new URL('./node_serial.py', import.meta.url))
-        child = spawn(options.python, ['-u', adapter, options.serial], { stdio: ['pipe', 'pipe', 'pipe'] })
+        const bridge = child = spawn(options.python, ['-u', adapter, options.serial], { stdio: ['pipe', 'pipe', 'pipe'] })
+        const current = connection = { intentional: false }
+        lastError = null
+        let adapterCause = null, processCause = null
+        const safeCause = value => {
+          if (value?.kind !== 'serial.error' || !['read', 'write', 'stdout'].includes(value.stage)
+              || typeof value.type !== 'string' || typeof value.message !== 'string') return null
+          const integer = n => Number.isSafeInteger(n) && n >= -0x80000000 && n <= 0xffffffff ? n : null
+          return { stage: value.stage, type: value.type.slice(0, 64), errno: integer(value.errno),
+            winerror: integer(value.winerror), message: value.message.replace(/[\r\n\x00-\x1f\x7f]/g, ' ').slice(0, 160) }
+        }
+        const errorDetails = (exitCode = null, signal = null) => ({
+          ...(adapterCause ?? processCause ?? { stage: 'process', type: 'ProcessExit', errno: null, winerror: null,
+            message: 'Serial adapter exited unexpectedly' }),
+          exitCode: Number.isInteger(exitCode) ? exitCode : null,
+          signal: typeof signal === 'string' ? signal.slice(0, 32) : null,
+        })
         let ready = false, settled = false, runtimeErrorReported = false, stderr = '', lines = ''
         const abort = () => {
-          child.kill('SIGTERM')
+          current.intentional = true
+          bridge.kill('SIGTERM')
           if (!settled) {
             settled = true
             reject(fail('CANCELLED', 'Serial connection cancelled'))
           }
         }
         const cleanup = () => signal.removeEventListener('abort', abort)
-        const serialError = () => {
-          const code = ['SERIAL_ACCESS_DENIED', 'SERIAL_BUSY'].find(code => stderr.includes(code)) ?? 'SERIAL_ERROR'
-          return fail(code, 'Serial adapter failed; ensure Python, pyserial and port access are available')
+        const serialError = details => {
+          const code = ready ? 'SERIAL_ERROR' : ['SERIAL_ACCESS_DENIED', 'SERIAL_BUSY'].find(code => stderr.includes(code)) ?? 'SERIAL_ERROR'
+          const message = ready && details?.stage !== 'process'
+            ? `Serial adapter ${details.stage} failed: ${details.message}`
+            : 'Serial adapter failed; ensure Python, pyserial and port access are available'
+          const error = fail(code, message)
+          error.details = details ?? errorDetails()
+          error.cause = Object.assign(new Error(error.details.message), { ...error.details, name: error.details.type })
+          return error
         }
-        const failBeforeReady = () => {
+        const failBeforeReady = details => {
           if (settled) return
           settled = true
           cleanup()
-          const error = serialError()
+          const error = serialError(details)
           reject(error)
           events.emit('error', error)
         }
-        const reportRuntimeError = () => {
+        const reportRuntimeError = details => {
           if (runtimeErrorReported) return
           runtimeErrorReported = true
-          events.emit('error', serialError())
+          const error = serialError(details)
+          lastError = { ...error.details }
+          events.emit('error', error)
+        }
+        const recordProcessError = (stage, error) => {
+          processCause = { stage, type: 'ProcessError', errno: null, winerror: null,
+            message: typeof error?.code === 'string' && /^[A-Z0-9_]{1,32}$/.test(error.code)
+              ? `Serial adapter ${stage} failed (${error.code})` : `Serial adapter ${stage} failed` }
         }
-        child.on('error', () => { if (ready) reportRuntimeError() })
-        child.stdin.on('error', () => { if (ready) reportRuntimeError() })
+        child.on('error', error => recordProcessError('process', error))
+        child.stdin.on('error', error => recordProcessError('stdin', error))
         child.stdout.on('data', bytes => events.emit('data', bytes))
         child.stderr.on('data', bytes => {
           // Do not print Python errors: they can contain host paths or device data.
@@ -105,6 +135,8 @@ export function serialTransport(options) {
             }
             let response
             try { response = JSON.parse(line) } catch { continue }
+            const diagnostic = safeCause(response)
+            if (diagnostic) { adapterCause = diagnostic; continue }
             const request = pending.get(response.id)
             if (!request) continue
             pending.delete(response.id)
@@ -119,7 +151,23 @@ export function serialTransport(options) {
         })
         // Wait for close rather than exit: stdout/stderr may still have buffered
         // data after exit, including the adapter's stable SERIAL_BUSY marker.
-        child.on('close', () => { cleanup(); rejectControls(fail('SERIAL_CLOSED', 'Serial adapter closed')); if (!ready) failBeforeReady(); events.emit('close') })
+        child.on('close', (code, signal) => {
+          cleanup()
+          if (connection !== current) return
+          const details = errorDetails(code, signal)
+          if (current.intentional) {
+            const error = fail('SERIAL_CLOSED', 'Serial adapter closed')
+            rejectControls(error)
+            if (!settled) { settled = true; reject(error) }
+          } else {
+            lastError = { ...details }
+            const error = serialError(details)
+            rejectControls(error)
+            if (!ready) failBeforeReady(details)
+            else reportRuntimeError(details)
+          }
+          events.emit('close')
+        })
         signal.addEventListener('abort', abort, { once: true })
         if (signal.aborted) abort()
       })
@@ -158,8 +206,9 @@ export function serialTransport(options) {
         send(1, Buffer.from(JSON.stringify({ id, baudRate: speed }))).catch(error => pending.get(id)?.reject(error))
       })
     },
-    getDiagnostics() { return { baudRate } },
+    getDiagnostics() { return { baudRate, ...(lastError ? { lastError: { ...lastError } } : {}) } },
     async disconnect() {
+      if (connection) connection.intentional = true
       rejectControls(fail('SERIAL_CLOSED', 'Serial adapter closed'))
       if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return
       await new Promise(resolveExit => {

package/tests/check-package.mjs

@@ -7,6 +7,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import process from 'node:process'
+import { npmCommand } from '../scripts/npm-command.mjs'
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
@@ -14,7 +15,7 @@ assert.equal(manifest.license, 'Apache-2.0')
 assert.match(await readFile(join(root, 'LICENSE'), 'utf8'), /Apache License[\s\S]*Version 2\.0/)
 const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-device-core-package-'))
 try {
-  const [packed] = JSON.parse(execFileSync('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', temporary], { cwd: root, encoding: 'utf8' }))
+  const [packed] = JSON.parse(execFileSync(...npmCommand(['pack', '--json', '--ignore-scripts', '--pack-destination', temporary]), { cwd: root, encoding: 'utf8' }))
   assert.ok(packed.files.some(({ path }) => path === 'LICENSE'))
   assert.ok(packed.files.some(({ path }) => path === 'NOTICE'))
   assert.ok(packed.files.some(({ path }) => path === 'schemas/device-actions-v1.json'))
@@ -25,7 +26,7 @@ try {
   assert.ok(!packed.files.some(({ path }) => path.includes('__pycache__') || path.endsWith('.pyc')), 'Never ship host Python bytecode')
   const consumer = join(temporary, 'consumer')
   await mkdir(consumer)
-  execFileSync('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)], { cwd: consumer, stdio: 'pipe' })
+  execFileSync(...npmCommand(['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)]), { cwd: consumer, stdio: 'pipe' })
   const installed = join(consumer, 'node_modules/@esp-vision/device-core')
   assert.equal(await readFile(join(installed, 'LICENSE'), 'utf8'), await readFile(join(root, 'LICENSE'), 'utf8'))
   const notice = await readFile(join(installed, 'NOTICE'), 'utf8')
@@ -65,19 +66,19 @@ try {
   for (const required of ['src/node_serial.py', 'src/jpeg_validate.js', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.mjs', 'tests/jpeg-fixtures.mjs', 'tests/test-jpeg-validation.mjs', 'tests/fixtures/device-checks.py']) {
     assert.ok(packed.files.some(({ path }) => path === required), `Missing installed check asset: ${required}`)
   }
-  const unitOutput = execFileSync('npm', ['test'], { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
+  const unitOutput = execFileSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
   const unitCount = Number(/^(?:# tests|ℹ tests) (\d+)$/m.exec(unitOutput)?.[1] ?? 0)
   assert.ok(unitCount > 0, 'Installed npm test must execute a nonempty suite')
-  const hardwareHelp = execFileSync('npm', ['run', 'test:hardware', '--', '--help'], { cwd: installed, encoding: 'utf8' })
+  const hardwareHelp = execFileSync(...npmCommand(['run', 'test:hardware', '--', '--help']), { cwd: installed, encoding: 'utf8' })
   assert.ok(hardwareHelp.includes('--serial PATH'), 'Installed hardware runner must load and show its help')
   // A damaged tarball must fail instead of reporting a successful zero-test run.
   await rm(join(installed, 'tests'), { recursive: true })
   await mkdir(join(installed, 'tests'))
-  const empty = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  const empty = spawnSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8' })
   assert.equal(empty.status, 1, 'An empty suite must fail closed')
   assert.match(empty.stderr, /No Device Core unit tests found/)
   await rm(join(installed, 'tests'), { recursive: true })
-  const missing = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  const missing = spawnSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8' })
   assert.equal(missing.status, 1, 'Missing tests must fail closed')
   console.log(JSON.stringify({ package: packed.name, version: packed.version, entryPoints, unitCount, standalone: true }))
 } finally {

package/tests/test-host-checks.mjs

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { copyFile, cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import { npmCommand } from '../scripts/npm-command.mjs'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+
+test('npm execution preserves Unicode, spaces and shell metacharacters as literal arguments', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'core npm 中文 '))
+  t.after(() => rm(directory, { recursive: true, force: true }))
+  const cli = join(directory, 'npm entry.cjs')
+  await writeFile(cli, 'process.stdout.write(JSON.stringify(process.argv.slice(2))); process.exitCode = 7\n')
+  const args = ['pack', '中文 path', '& echo forbidden', '$(forbidden)', '%PATH%']
+  const env = { ...process.env, npm_execpath: cli }
+  const result = spawnSync(...npmCommand(args, env), { env, encoding: 'utf8' })
+  assert.equal(result.status, 7, result.stderr)
+  assert.deepEqual(JSON.parse(result.stdout), args)
+})
+
+test('schema check accepts checkout CRLF but rejects a real artifact change', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'core schema '))
+  t.after(() => rm(directory, { recursive: true, force: true }))
+  await mkdir(join(directory, 'scripts'))
+  await mkdir(join(directory, 'schemas'))
+  await cp(join(root, 'src'), join(directory, 'src'), { recursive: true })
+  await copyFile(join(root, 'package.json'), join(directory, 'package.json'))
+  const script = join(directory, 'scripts/generate-action-schema.mjs')
+  await copyFile(join(root, 'scripts/generate-action-schema.mjs'), script)
+  const schema = join(directory, 'schemas/device-actions-v1.json')
+  const original = (await readFile(join(root, 'schemas/device-actions-v1.json'), 'utf8')).replaceAll('\r\n', '\n')
+  await writeFile(schema, original.replaceAll('\n', '\r\n'))
+  const current = spawnSync(process.execPath, [script, '--check'], { encoding: 'utf8' })
+  assert.equal(current.status, 0, current.stderr)
+  const changed = JSON.parse(original)
+  changed.deviceCoreVersion = '0.0.0'
+  await writeFile(schema, JSON.stringify(changed, null, 2).replaceAll('\n', '\r\n') + '\r\n')
+  const stale = spawnSync(process.execPath, [script, '--check'], { encoding: 'utf8' })
+  assert.notEqual(stale.status, 0)
+  assert.match(stale.stderr, /Device Action schema artifact is stale/)
+})

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

@@ -265,10 +265,12 @@ test('recovery never repeats a previous active handoff or uses an incomplete pre
   }
 })
 
-test('same ROM or no runtime returns null without issuing a bootloader command', async () => {
+test('persistent ROM or absence exhausts only passive observation before returning null', 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.now(), 200)
+    assert.equal(f.calls.enumerate.length, 4)
     assert.equal(f.calls.creates, 0)
     assert.equal(f.calls.control.length, 0)
   }
@@ -303,3 +305,81 @@ test('read-only recovery honors cancel and fresh-enumeration deadline', async ()
   await assert.rejects(late.recover(previousRom()), { code: 'ROM_PORT_REBIND_TIMEOUT' })
   assert.equal(late.calls.creates, 0)
 })
+
+
+test('read-only recovery observes a real 2.4-second missing-device window before one handoff', async () => {
+  const runtime = native('/dev/ttyACM2', { productId: 0x4023 })
+  const f = fixture({ snapshots: [...Array.from({ length: 48 }, () => []), [runtime], [runtime], [rom('/dev/ttyACM3')]] })
+  const result = await f.recover(previousRom(), { timeout: 5000 })
+  assert.equal(f.now(), 2400)
+  assert.equal(result.port, '/dev/ttyACM3')
+  assert.equal(result.transition.recovery.runtimePid, 0x4023)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.connect.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.calls.enumerate[48].timeout, 2600)
+})
+
+test('a stale ROM followed by disappearance is observed passively until the same runtime returns', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const snapshots = [...Array.from({ length: 10 }, () => [rom('/dev/ttyACM0')]),
+    ...Array.from({ length: 38 }, () => []), [runtime], [runtime], [rom('/dev/ttyACM3')]]
+  const f = fixture({ snapshots })
+  const result = await f.recover(previousRom(), { timeout: 5000 })
+  assert.equal(f.now(), 2400)
+  assert.equal(result.port, '/dev/ttyACM3')
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+})
+
+test('a conflicting MAC or location seen after waiting fails before opening any runtime', async () => {
+  for (const conflicting of [native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }),
+    native('/dev/ttyACM2', { location: '2-3' }), rom('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }),
+    rom('/dev/ttyACM2', { location: '2-3' })]) {
+    const f = fixture({ snapshots: [[], [], [conflicting]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.now(), 100)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('late duplicate runtime or simultaneous ROM/runtime descriptors remain ambiguous', async () => {
+  for (const second of [native('/dev/ttyACM3'), rom('/dev/ttyACM3')]) {
+    const f = fixture({ snapshots: [[], [native('/dev/ttyACM2'), second]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_AMBIGUOUS' })
+    assert.equal(f.now(), 50)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('cancel during passive recovery sleep never creates a session or sends bootloader', async () => {
+  const reason = Object.assign(new Error('cancelled during native USB observation'), { name: 'AbortError' })
+  const f = fixture({ snapshots: [[]], onSleep(controller, clock) { if (clock >= 150) controller.abort(reason) } })
+  await assert.rejects(f.recover(previousRom(), { timeout: 5000 }), value => value === reason)
+  assert.equal(f.now(), 150)
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('late runtime enumeration does not start handoff after the passive deadline', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const f = fixture({ snapshots: [[runtime]], enumerationDelay: 201 })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('a runtime handshake error after settling is propagated without another observation or handoff', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const reason = failure('SESSION_BUSY')
+  const f = fixture({ snapshots: [[], [runtime], [runtime]], connectError: reason })
+  await assert.rejects(f.recover(previousRom()), value => value === reason)
+  assert.equal(f.now(), 50)
+  assert.equal(f.calls.connect.length, 1)
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 0)
+  assert.equal(f.calls.disconnect, 1)
+})

package/tests/test-node-rom.mjs

@@ -6,7 +6,7 @@ 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 } = {}) {
+function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeError, operationError, readResult = 'QUI=' } = {}) {
   const calls = [], requests = []
   const child = new EventEmitter()
   child.exitCode = null
@@ -15,10 +15,11 @@ function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeErro
     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 }
+      const detail = request.method === 'initialize' ? initializeError : operationError
+      queueMicrotask(() => child.stdout.write(JSON.stringify(detail
+        ? { id: request.id, error: 'ROM_OPERATION_FAILED', method: request.method, detail }
         : { id: request.id, result: request.method === 'initialize'
-          ? { chipFamily: 0x3280, chipRevision: 302, chipMac: mac, connectionMode: 'no-reset' } : null }) + '\n'))
+          ? { chipFamily: 0x3280, chipRevision: 302, chipMac: mac, connectionMode: 'no-reset' } : request.method === 'read' ? readResult : null }) + '\n'))
       done()
     },
     final(done) { child.exitCode = 0; queueMicrotask(() => child.emit('exit', 0)); done() },
@@ -158,3 +159,73 @@ test('a second initialization sync failure cannot trigger a third process or han
   assert.equal(recoveries, 1)
   assert.equal(first.requests.length + second.requests.length, 2)
 })
+
+
+test('post-initialize read or write failures never start recovery, a second process, or replay data', async () => {
+  for (const method of ['read', 'write']) {
+    const f = fixture({ operationError: 'Original operation failed' })
+    f.selected.transition = { observed: 'rom', requested: false }
+    let recoveries = 0, progresses = 0
+    const loader = openNodeRom({ port: '/dev/rom' }, { ...f.dependencies,
+      recoverPort: async () => { recoveries++; throw Error('Read/write must not recover') },
+    })
+    try {
+      await loader.initialize()
+      const operation = method === 'read' ? loader.readFlash(0x8000, 1024)
+        : loader.flashData(new Uint8Array([1, 2, 3]), () => { progresses++ }, 0x10000)
+      await assert.rejects(operation, error => error.code === 'ROM_OPERATION_FAILED'
+        && error.operation === method && error.cause === 'Original operation failed')
+      assert.equal(recoveries, 0)
+      assert.equal(progresses, 0)
+      assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+      assert.deepEqual(f.requests.map(r => r.method), ['initialize', method])
+    } finally { await loader.disconnect() }
+  }
+})
+
+
+test('Node ROM reads forward default and explicit budgets and report progress only after complete data', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  const progress = []
+  try {
+    await loader.initialize()
+    assert.deepEqual(await loader.readFlash(0x8000, 2, (...args) => progress.push(args)), new Uint8Array([65, 66]))
+    assert.deepEqual(await loader.readFlash(0x10000, 2, undefined,
+      { chunkSize: 65536, blockSize: 4096, maxInFlight: 2 }), new Uint8Array([65, 66]))
+    assert.deepEqual(f.requests.map(r => [r.method, r.args]), [['initialize', []],
+      ['read', [0x8000, 2, { blockSize: 1024, maxInFlight: 1 }]],
+      ['read', [0x10000, 2, { blockSize: 4096, maxInFlight: 2 }]]])
+    assert.equal(progress.length, 1)
+    assert.deepEqual(progress[0], [new Uint8Array([65, 66]), 2, 2])
+  } finally { await loader.disconnect() }
+})
+
+test('invalid read ranges, progress, or packet budgets never issue a child process RPC', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await loader.initialize()
+    for (const [offset, count, progress, options] of [[-1, 2], [0, 0], [0, 0x100000000], [0xffffffff, 2], [0, 2, null],
+      [0, 2, undefined, null], [0, 2, undefined, []], [0, 2, undefined, { blockSize: 512 }],
+      [0, 2, undefined, { blockSize: true }], [0, 2, undefined, { blockSize: null }], [0, 2, undefined, { maxInFlight: 0 }],
+      [0, 2, undefined, { maxInFlight: 65 }], [0, 2, undefined, { maxInFlight: null }], [0, 2, undefined, { maxInFlight: 1.5 }],
+      [0, 2, undefined, { unknown: 1 }], [0, 2, undefined, { chunkSize: 1 }]]) {
+      await assert.rejects(loader.readFlash(offset, count, progress, options), error => error instanceof TypeError || error instanceof RangeError)
+    }
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize'])
+  } finally { await loader.disconnect() }
+})
+
+test('incomplete read results are rejected without progress, recovery, or duplicate read', async () => {
+  const f = fixture({ readResult: 'QQ==' })
+  let recovered = 0, progressed = 0
+  const loader = openNodeRom({ port: '/dev/runtime' }, { ...f.dependencies,
+    recoverPort: async () => { recovered++; throw Error('Read must not recover') },
+  })
+  try {
+    await loader.initialize()
+    await assert.rejects(loader.readFlash(0, 2, () => { progressed++ }), { code: 'ROM_READ_LENGTH', operation: 'read' })
+    assert.equal(recovered, 0)
+    assert.equal(progressed, 0)
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'read'])
+  } finally { await loader.disconnect() }
+})

package/tests/test-node-serial.mjs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import assert from 'node:assert/strict'
-import { spawnSync } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { delimiter, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -306,5 +306,234 @@ test('Node drain rejects promptly on explicit disconnect or Python bridge exit',
   await f.transport.disconnect()
   await rejected
   const exited = await drainFixture(t, ['exit'])
-  await assert.rejects(exited.transport.drain(), { code: 'SERIAL_CLOSED' })
+  await assert.rejects(exited.transport.drain(), error => error.code === 'SERIAL_ERROR' && error.details.exitCode === 2)
+})
+
+async function failureFixture(t, mode) {
+  await mkdir(tempBase, { recursive: true })
+  const root = await mkdtemp(join(tempBase, 'serial-failure-')), gate = join(root, 'fail')
+  t.after(() => rm(root, { recursive: true, force: true }))
+  await writeFile(join(root, 'serial.py'), `
+import os, signal, time
+MODE = ${JSON.stringify(mode)}
+GATE = ${JSON.stringify(gate)}
+SECRET = 'TRANSFERRED_BYTES_MUST_NOT_ESCAPE_' * 100
+class SerialException(Exception):
+    pass
+class Serial:
+    def __init__(self, *args, **kwargs):
+        self.baudrate = kwargs['baudrate']
+    def open(self):
+        if MODE == 'denied':
+            raise SerialException('Could not open COM7: Access is denied ' + SECRET)
+        if MODE == 'opening':
+            time.sleep(1)
+    def read(self, size):
+        if os.path.exists(GATE):
+            if MODE == 'read':
+                raise OSError(5, SECRET)
+            if MODE == 'read-private':
+                raise SerialException(SECRET)
+            if MODE == 'exit':
+                os._exit(7)
+            if MODE == 'eof':
+                os._exit(0)
+            if MODE == 'signal':
+                os.kill(os.getpid(), signal.SIGKILL)
+        time.sleep(.005)
+        return b''
+    def write(self, data):
+        if MODE == 'write':
+            raise SerialException('GetOverlappedResult failed ' + SECRET + repr(data))
+        return len(data)
+    def flush(self):
+        pass
+    def close(self):
+        pass
+`)
+  return { root, gate, fail: () => writeFile(gate, '') }
+}
+
+function deadline(promise, message) {
+  let timer
+  return Promise.race([promise, new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), 5000)
+  })]).finally(() => clearTimeout(timer))
+}
+
+async function transportFailure(t, mode) {
+  const f = await failureFixture(t, mode), previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [f.root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: '/dev/fixture' }), errors = []
+  let closed
+  const close = new Promise(resolveClose => { closed = resolveClose })
+  transport.subscribe({ error: error => errors.push(error), close: closed })
+  t.after(() => transport.disconnect())
+  await transport.connect({ signal: new AbortController().signal })
+  return { ...f, transport, errors, close: () => deadline(close, 'Serial child did not close') }
+}
+
+test('actual Python reader failure reaches Node with safe OS cause and child status', { skip: !python }, async t => {
+  const f = await transportFailure(t, 'read')
+  await f.fail()
+  await f.close()
+  assert.equal(f.errors.length, 1)
+  const error = f.errors[0]
+  assert.equal(error.code, 'SERIAL_ERROR')
+  assert.deepEqual(error.details, { stage: 'read', type: 'OSError', errno: 5, winerror: null,
+    message: 'Input/output error', exitCode: 2, signal: null })
+  assert.equal(error.cause.name, 'OSError')
+  assert.equal(error.cause.errno, 5)
+  assert.deepEqual(f.transport.getDiagnostics().lastError, error.details)
+  assert.equal(JSON.stringify(error.details).includes('TRANSFERRED_BYTES'), false)
+  const snapshot = f.transport.getDiagnostics()
+  snapshot.lastError.message = 'changed by caller'
+  assert.notEqual(f.transport.getDiagnostics().lastError.message, snapshot.lastError.message)
+})
+
+test('actual Python writer failure keeps its API category without exposing payload or arbitrary exception text', { skip: !python }, async t => {
+  const f = await transportFailure(t, 'write')
+  const payload = new TextEncoder().encode('private transmitted bytes, never a diagnostic')
+  await f.transport.writeBytes(payload)
+  await f.close()
+  assert.equal(f.errors.length, 1)
+  assert.equal(f.errors[0].code, 'SERIAL_ERROR')
+  assert.deepEqual(f.errors[0].details, { stage: 'write', type: 'SerialException', errno: null,
+    winerror: null, message: 'GetOverlappedResult failed', exitCode: 2, signal: null })
+  const diagnostic = JSON.stringify(f.transport.getDiagnostics())
+  assert.equal(diagnostic.includes('TRANSFERRED_BYTES'), false)
+  assert.equal(diagnostic.includes('private transmitted bytes'), false)
+})
+
+test('unrecognized Python exception text is omitted and diagnostics remain bounded', { skip: !python }, async t => {
+  const f = await transportFailure(t, 'read-private')
+  await f.fail()
+  await f.close()
+  assert.equal(f.errors.length, 1)
+  assert.equal(f.errors[0].details.message, 'Serial read failed')
+  assert(JSON.stringify(f.errors[0].details).length < 512)
+  assert.equal(JSON.stringify(f.errors[0].details).includes('TRANSFERRED_BYTES'), false)
+})
+
+test('unexpected bridge exit zero, nonzero or signal reports one serial error with the actual close status', {
+  skip: !python,
+}, async t => {
+  for (const mode of ['exit', 'eof', ...(process.platform === 'win32' ? [] : ['signal'])]) {
+    const f = await transportFailure(t, mode)
+    await f.fail()
+    await f.close()
+    assert.equal(f.errors.length, 1, mode)
+    assert.equal(f.errors[0].code, 'SERIAL_ERROR')
+    assert.equal(f.errors[0].details.stage, 'process')
+    assert.equal(f.errors[0].details.exitCode, mode === 'exit' ? 7 : mode === 'eof' ? 0 : null)
+    assert.equal(f.errors[0].details.signal, mode === 'signal' ? 'SIGKILL' : null)
+  }
+})
+
+test('intentional disconnect and connection cancellation do not become serial failures', { skip: !python }, async t => {
+  const f = await transportFailure(t, 'idle')
+  await f.transport.disconnect()
+  await f.close()
+  assert.deepEqual(f.errors, [])
+  assert.equal(f.transport.getDiagnostics().lastError, undefined)
+  const pending = await failureFixture(t, 'opening'), previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [pending.root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: '/dev/fixture' }), errors = []
+  let closed
+  const close = new Promise(resolveClose => { closed = resolveClose })
+  transport.subscribe({ error: error => errors.push(error), close: closed })
+  t.after(() => transport.disconnect())
+  const controller = new AbortController(), connecting = transport.connect({ signal: controller.signal })
+  const cancelled = assert.rejects(connecting, { code: 'CANCELLED' })
+  controller.abort()
+  await cancelled
+  await deadline(close, 'Cancelled child did not close')
+  assert.deepEqual(errors, [])
+  assert.equal(transport.getDiagnostics().lastError, undefined)
+})
+
+
+test('Python failure stderr is one bounded structured record and never includes transfer data', { skip: !python }, async t => {
+  for (const mode of ['read-private', 'write']) {
+    const f = await failureFixture(t, mode), stderr = [], stdout = []
+    const child = spawn(python, ['-u', adapter, '/dev/fixture'], {
+      env: fixturePythonEnv(f.root), stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
+    })
+    t.after(() => { if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM') })
+    let ready
+    const started = new Promise(resolveReady => { ready = resolveReady })
+    child.stdout.on('data', bytes => stdout.push(bytes))
+    child.stderr.on('data', bytes => { stderr.push(bytes); if (/(?:^|\n)READY\r?\n/.test(Buffer.concat(stderr).toString())) ready() })
+    const closed = new Promise((resolveClose, reject) => { child.on('error', reject); child.on('close', (code, signal) => resolveClose({ code, signal })) })
+    await deadline(started, 'Python fault fixture did not become ready')
+    if (mode === 'write') {
+      const payload = Buffer.from('private serial bytes')
+      const record = Buffer.alloc(5 + payload.length)
+      record.writeUInt8(0, 0); record.writeUInt32BE(payload.length, 1); record.set(payload, 5)
+      child.stdin.write(record)
+    } else await f.fail()
+    assert.deepEqual(await deadline(closed, 'Python fault did not terminate'), { code: 2, signal: null })
+    const text = Buffer.concat(stderr).toString(), lines = text.trim().split(/\r?\n/)
+    assert.equal(lines.filter(line => line === 'READY').length, 1)
+    const records = lines.filter(line => line !== 'READY').map(line => JSON.parse(line))
+    assert.equal(records.length, 1)
+    assert.equal(records[0].kind, 'serial.error')
+    assert.equal(records[0].stage, mode === 'write' ? 'write' : 'read')
+    assert(Buffer.byteLength(lines.find(line => line !== 'READY')) < 512)
+    assert.equal(text.includes('TRANSFERRED_BYTES'), false)
+    assert.equal(text.includes('private serial bytes'), false)
+    assert.equal(Buffer.concat(stdout).length, 0)
+  }
+})
+
+
+test('disconnect before READY settles the pending connection without reporting an unexpected failure', { skip: !python }, async t => {
+  const f = await failureFixture(t, 'opening'), previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [f.root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: '/dev/fixture' }), errors = []
+  transport.subscribe({ error: error => errors.push(error) })
+  t.after(() => transport.disconnect())
+  const connecting = transport.connect({ signal: new AbortController().signal })
+  const closed = assert.rejects(connecting, { code: 'SERIAL_CLOSED' })
+  await transport.disconnect()
+  await deadline(closed, 'Disconnect did not settle the pending connection')
+  assert.deepEqual(errors, [])
+  assert.equal(transport.getDiagnostics().lastError, undefined)
+})
+
+
+test('spawn failure before READY preserves its bounded process cause and settles once', async t => {
+  const transport = serialTransport({ python: join(tempBase, 'missing-python-executable'), serial: '/dev/fixture' }), errors = []
+  transport.subscribe({ error: error => errors.push(error) })
+  t.after(() => transport.disconnect())
+  await assert.rejects(transport.connect({ signal: new AbortController().signal }), error => {
+    assert.equal(error.code, 'SERIAL_ERROR')
+    assert.equal(error.details.stage, 'process')
+    assert.equal(error.details.type, 'ProcessError')
+    assert.equal(error.details.exitCode, process.platform === 'win32' ? -4058 : -2)
+    assert.equal(error.details.signal, null)
+    assert.match(error.details.message, /ENOENT/)
+    return true
+  })
+  assert.equal(errors.length, 1)
+})
+
+test('Windows-style access denial before READY retains its existing error code without port or exception text', { skip: !python }, async t => {
+  const f = await failureFixture(t, 'denied'), previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [f.root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: 'COM7' }), errors = []
+  transport.subscribe({ error: error => errors.push(error) })
+  t.after(() => transport.disconnect())
+  await assert.rejects(transport.connect({ signal: new AbortController().signal }), error => {
+    assert.equal(error.code, 'SERIAL_ACCESS_DENIED')
+    assert.equal(error.details.exitCode, 2)
+    assert.equal(JSON.stringify(error.details).includes('TRANSFERRED_BYTES'), false)
+    assert.equal(error.message.includes('COM7'), false)
+    return true
+  })
+  assert.equal(errors.length, 1)
 })

package/tests/test-npm-release-policy.mjs

@@ -17,23 +17,17 @@ async function fixture(t, published, version = '1.2.3', type = 'patch') {
   await copyFile(join(source, 'release-npm.mjs'), join(scripts, 'release-npm.mjs'))
   await copyFile(join(source, 'verify-registry.mjs'), join(scripts, 'verify-registry.mjs'))
   await copyFile(join(source, 'version-policy.mjs'), join(scripts, 'version-policy.mjs'))
+  await copyFile(join(source, 'npm-command.mjs'), join(scripts, 'npm-command.mjs'))
   await writeFile(join(root, 'package.json'), JSON.stringify({ name: '@esp-vision/device-core', version, espVisionReleaseType: type, license: 'Apache-2.0', publishConfig: { access: 'public', registry: 'https://registry.npmjs.org/' } }))
   const loader = join(root, 'registry.mjs'), npm = join(root, 'npm.cjs')
   // Invoke the fixture with Node on every platform, without shell/PATH resolution.
-  await writeFile(loader, `import childProcess from 'node:child_process';
-import { syncBuiltinESMExports } from 'node:module';
-const spawnSync = childProcess.spawnSync;
-childProcess.spawnSync = (command, ...args) => command === 'npm'
-  ? spawnSync(process.execPath, [${JSON.stringify(npm)}, ...args[0]], args[1])
-  : spawnSync(command, ...args);
-syncBuiltinESMExports();
-let reads = 0; globalThis.fetch = async () => { reads++; const found = ${published} || reads === 2 || reads >= 4; return {ok:found,status:found?200:404,json:async()=>reads===2?({versions:{'1.2.2':{}}}):({dist:{integrity:'sha512-fixture'}})} }`)
+  await writeFile(loader, `let reads = 0; globalThis.fetch = async () => { reads++; const found = ${published} || reads === 2 || reads >= 4; return {ok:found,status:found?200:404,json:async()=>reads===2?({versions:{'1.2.2':{}}}):({dist:{integrity:'sha512-fixture'}})} }`)
   await writeFile(npm, `const fs = require('node:fs'); const args = process.argv.slice(2); fs.appendFileSync(process.env.CALL_LOG, args[0] + '\\n');
 if (args[0] === 'whoami') process.stdout.write('esp-vision');
 else if (args[0] === 'pack') process.stdout.write(JSON.stringify([{name:'@esp-vision/device-core',version:'1.2.3',filename:'core.tgz',integrity:'sha512-fixture',files:[{path:'LICENSE'},{path:'NOTICE'}]}]));
 else if (args[0] !== 'publish') process.exit(2);
 `)
-  const env = { ...process.env, TMPDIR: root, TMP: root, TEMP: root, CALL_LOG: log,
+  const env = { ...process.env, TMPDIR: root, TMP: root, TEMP: root, CALL_LOG: log, npm_execpath: npm,
     NODE_OPTIONS: `--import ${pathToFileURL(loader).href}`, NPM_PUBLISH_TOKEN: 'fixture', CI_PIPELINE_SOURCE: 'push',
     CI_DEFAULT_BRANCH: 'master', CI_COMMIT_BRANCH: 'master', CI_COMMIT_REF_PROTECTED: 'true' }
   const result = spawnSync(process.execPath, [resolve(scripts, 'release-npm.mjs')], { cwd: root, env, encoding: 'utf8' })