@esp-vision/device-core 0.4.1 → 0.5.0

package/src/evrepl.js

@@ -74,9 +74,13 @@ export class EvRepl {
         this.buffer = ''
         this.waiters = []
         this.onScriptEnd = null
+        this.scriptStartMarker = null
+        this.scriptStartSeen = false
+        this.scriptStartWaiter = null
         this.scriptEndMarker = null
         this.scriptEndCommand = null
         this.scriptSentinelSeq = 0
+        this.scriptEndPromptOffset = null
         this.execQueue = Promise.resolve()
         this.closedError = null
         this.inputMaxBytes = EV_REPL_INPUT_MAX_BYTES
@@ -94,11 +98,70 @@ export class EvRepl {
         return `${this.scriptEndCommand}\r\n`
     }
 
-    createScriptRunCommand(path) {
+    createScriptStartSentinel() {
+        const randomId = globalThis.crypto?.randomUUID?.() ||
+            `${Date.now().toString(36)}-${++this.scriptSentinelSeq}`
+        this.scriptStartMarker = `~~EVSCRIPT-START:${randomId}~~`
+        this.scriptStartSeen = false
+        return `print(${pythonString(this.scriptStartMarker)})`
+    }
+
+    waitForScriptStart({ timeout = 5000, signal = null } = {}) {
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+            throw new RangeError('Script start acknowledgement timeout must be positive')
+        }
+        if (this.scriptStartSeen) {
+            this.scriptStartSeen = false
+            return Promise.resolve()
+        }
+        if (!this.scriptStartMarker) {
+            return Promise.reject(Object.assign(new Error('Script start acknowledgement is unavailable'), {
+                code: 'SCRIPT_START_MISSING',
+            }))
+        }
+        if (signal?.aborted) {
+            return Promise.reject(abortReason(signal))
+        }
+        if (this.scriptStartWaiter) return this.scriptStartWaiter.promise
+
+        let waiter
+        const promise = new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(waiter.timer)
+                signal?.removeEventListener('abort', onAbort)
+                if (this.scriptStartWaiter === waiter) this.scriptStartWaiter = null
+            }
+            const settle = (callback, value) => {
+                cleanup()
+                callback(value)
+            }
+            const onAbort = () => settle(reject, abortReason(signal))
+            waiter = {
+                promise: null,
+                resolve: () => {
+                    this.scriptStartSeen = false
+                    settle(resolve)
+                },
+                reject: error => settle(reject, error),
+                timer: setTimeout(() => settle(reject, Object.assign(
+                    new Error(`script start acknowledgement timeout after ${timeout}ms`),
+                    { code: 'SCRIPT_START_TIMEOUT' },
+                )), timeout),
+            }
+            this.scriptStartWaiter = waiter
+            signal?.addEventListener('abort', onAbort, { once: true })
+            if (signal?.aborted) onAbort()
+        })
+        waiter.promise = promise
+        return promise
+    }
+
+    createScriptRunCommand(path, { acknowledgeStart = false } = {}) {
+        const start = acknowledgeStart ? this.createScriptStartSentinel() : null
         const end = this.createScriptEndSentinel().trim()
         // Generate completion inside the running statement. A second queued
         // stdin command would otherwise be consumed by Python input().
-        const source = target => `try:\n execfile(${target})\nexcept BaseException as __evcore_error:\n __import__('sys').print_exception(__evcore_error)\nfinally:\n ${end}`
+        const source = target => `try:\n${start ? ` ${start}\n` : ''} execfile(${target})\nexcept BaseException as __evcore_error:\n __import__('sys').print_exception(__evcore_error)\nfinally:\n ${end}`
         let command = `exec("${escapeForExec(source(pythonString(path)))}")\r\n`
         this.scriptRunPrelude = null
         if (new TextEncoder().encode(command).length > this.inputMaxBytes) {
@@ -115,11 +178,59 @@ export class EvRepl {
         return command
     }
 
-    cancelScriptEndSentinel() {
+    createInlineSourceAssignments(source, variableName) {
+        if (typeof source !== 'string' || !/^__[A-Za-z0-9_]+$/.test(variableName)) {
+            throw new TypeError('Inline Python source requires a string and a private variable name')
+        }
+        const characters = Array.from(source)
+        const statements = []
+        let chunk = ''
+        const statementFor = (value, first) => `${variableName}${first ? '=' : '+='}${JSON.stringify(value)}`
+        for (const character of characters) {
+            const candidate = chunk + character
+            const candidateStatement = statementFor(candidate, statements.length === 0)
+            if (this.execInputBytes(candidateStatement) <= this.inputMaxBytes) {
+                chunk = candidate
+                continue
+            }
+            if (!chunk) throw new Error('Inline Python source character exceeds the REPL input limit')
+            statements.push(statementFor(chunk, statements.length === 0))
+            chunk = character
+            if (this.execInputBytes(statementFor(chunk, false)) > this.inputMaxBytes) {
+                throw new Error('Inline Python source character exceeds the REPL input limit')
+            }
+        }
+        if (chunk || statements.length === 0) statements.push(statementFor(chunk, statements.length === 0))
+        return statements
+    }
+
+    createInlineScriptRunCommand(variableName) {
+        if (!/^__[A-Za-z0-9_]+$/.test(variableName)) {
+            throw new TypeError('Inline Python run requires a private variable name')
+        }
+        const end = this.createScriptEndSentinel().trim()
+        const source = `try:\n exec(${variableName})\nexcept BaseException as __evcore_error:\n __import__('sys').print_exception(__evcore_error)\nfinally:\n try:\n  del ${variableName}\n except NameError:\n  pass\n ${end}`
+        const command = `exec("${escapeForExec(source)}")\r\n`
+        if (new TextEncoder().encode(command).length > this.inputMaxBytes) {
+            this.cancelScriptEndSentinel()
+            throw new Error('Inline Python runner exceeds the REPL input limit')
+        }
+        this.scriptEndCommand = command.trimEnd()
+        this.scriptRunEcho = true
+        return command
+    }
+
+    cancelScriptEndSentinel(error = null) {
+        this.scriptStartMarker = null
+        this.scriptStartSeen = false
+        this.scriptStartWaiter?.reject(error || Object.assign(new Error('Script ended before its start acknowledgement'), {
+            code: 'SCRIPT_START_MISSING',
+        }))
         this.scriptEndMarker = null
         this.scriptEndCommand = null
         this.scriptRunEcho = false
         this.scriptRunPrelude = null
+        this.scriptEndPromptOffset = null
     }
 
     /**
@@ -138,6 +249,7 @@ export class EvRepl {
                 this.scriptRunEcho = false
             }
         }
+        this.drainScriptStart()
         const marker = this.scriptEndMarker
         if (!marker) {
             return
@@ -180,11 +292,43 @@ export class EvRepl {
             }
             this.buffer = before + this.buffer.slice(end)
             this.cancelScriptEndSentinel()
+            this.scriptEndPromptOffset = before.length
             this.onScriptEnd?.()
             return
         }
     }
 
+    drainScriptStart() {
+        const marker = this.scriptStartMarker
+        if (!marker) return
+        let searchFrom = 0
+        for (;;) {
+            const at = this.buffer.indexOf(marker, searchFrom)
+            if (at < 0) return
+            let end = at + marker.length
+            const tail = this.buffer[end]
+            if (tail === undefined) return
+            if (tail !== '\r' && tail !== '\n') {
+                // The friendly-REPL echo includes the marker inside the
+                // runner command. Only its standalone printed line is proof
+                // that the VM entered the runner.
+                searchFrom = end
+                continue
+            }
+            if (tail === '\r') {
+                if (end + 1 >= this.buffer.length) return
+                end += this.buffer[end + 1] === '\n' ? 2 : 1
+            } else {
+                end += 1
+            }
+            this.buffer = this.buffer.slice(0, at) + this.buffer.slice(end)
+            this.scriptStartMarker = null
+            this.scriptStartSeen = true
+            this.scriptStartWaiter?.resolve()
+            return
+        }
+    }
+
     /**
      * Length of the buffer suffix that could grow into the sentinel marker
      * (starts with at least '~~'). Held back from passthrough so a marker
@@ -201,11 +345,13 @@ export class EvRepl {
             // until its output marker arrives and both can be removed.
             return this.buffer.length - commandAt
         }
-        if (this.buffer.endsWith(marker + '\r')) {
-            return marker.length + 1
+        for (const activeMarker of [this.scriptStartMarker, marker]) {
+            if (activeMarker && this.buffer.endsWith(activeMarker + '\r')) {
+                return activeMarker.length + 1
+            }
         }
         let hold = 0
-        for (const candidate of [marker, this.scriptEndCommand]) {
+        for (const candidate of [this.scriptStartMarker, marker, this.scriptEndCommand]) {
             if (!candidate) {
                 continue
             }
@@ -234,12 +380,29 @@ export class EvRepl {
         }
         this.buffer += text
         this.drainScriptEnd()
+        let passthrough = ''
+        let holdPromptTail = false
+        if (this.scriptEndPromptOffset !== null) {
+            const prefix = this.buffer.slice(0, this.scriptEndPromptOffset)
+            const tail = this.buffer.slice(this.scriptEndPromptOffset)
+            if (tail.length < PROMPT.length && PROMPT.startsWith(tail)) {
+                this.buffer = tail
+                this.scriptEndPromptOffset = 0
+                passthrough = prefix
+                holdPromptTail = true
+            } else if (tail.startsWith(PROMPT)) {
+                this.buffer = prefix + tail.slice(PROMPT.length)
+                this.scriptEndPromptOffset = null
+            } else {
+                this.scriptEndPromptOffset = null
+            }
+        }
         this.drain()
         if (this.waiters.length === 0) {
-            const hold = this.partialMarkerTail()
+            const hold = holdPromptTail ? this.buffer.length : this.partialMarkerTail()
             const out = this.buffer.slice(0, this.buffer.length - hold)
             this.buffer = this.buffer.slice(this.buffer.length - hold)
-            return out
+            return passthrough + out
         }
         return ''
     }
@@ -278,7 +441,7 @@ export class EvRepl {
             waiter.removeAbortListener?.()
             waiter.reject(error)
         }
-        this.cancelScriptEndSentinel()
+        this.cancelScriptEndSentinel(error)
         this.buffer = ''
     }
 
@@ -305,11 +468,11 @@ export class EvRepl {
         return result
     }
 
-    writeStdin(data) {
+    writeStdin(data, { signal = null } = {}) {
         return this.enqueue(async () => {
             const bytes = data instanceof Uint8Array ? data : new TextEncoder().encode(data)
             if (bytes.length <= this.inputMaxBytes) {
-                return this.writeEvmux('repl.stdin', 'data', null, data)
+                return this.writeEvmux('repl.stdin', 'data', null, data, { signal })
             }
             let result
             for (let offset = 0; offset < bytes.length; offset += this.inputMaxBytes) {
@@ -318,10 +481,11 @@ export class EvRepl {
                     'data',
                     null,
                     bytes.subarray(offset, Math.min(offset + this.inputMaxBytes, bytes.length)),
+                    { signal },
                 )
             }
             return result
-        })
+        }, { signal })
     }
 
     execLine(line, { timeout = 8000, signal = null } = {}) {
@@ -353,7 +517,7 @@ export class EvRepl {
                 reject(error)
             }
             const timer = setTimeout(() => {
-                fail(new Error(`repl exec timeout: ${line.slice(0, 60)}`))
+                fail(Object.assign(new Error(`repl exec timeout: ${line.slice(0, 60)}`), { code: 'TIMEOUT' }))
             }, timeout)
             const abort = () => {
                 fail(abortReason(signal))
@@ -385,7 +549,7 @@ export class EvRepl {
         completion.catch(() => {})
         if (signal?.aborted) return completion
         try {
-            await this.writeEvmux('repl.stdin', 'data', null, line + '\r\n')
+            await this.writeEvmux('repl.stdin', 'data', null, line + '\r\n', { signal })
             commandWritten = true
         } catch (err) {
             const index = this.waiters.indexOf(waiter)
@@ -553,14 +717,26 @@ walk('')
         return result
     }
 
-    async readFile(fn, { timeout = 30000, signal = null, maxBytes = null } = {}) {
+    async readFile(fn, { timeout = null, chunkTimeout = 30000, signal = null, maxBytes = null } = {}) {
+        if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
+            throw new RangeError('Device file read timeout must be positive or null')
+        }
+        if (!Number.isFinite(chunkTimeout) || chunkTimeout <= 0) {
+            throw new RangeError('Device file read chunk timeout must be positive')
+        }
         if (maxBytes !== null && (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > 16 * 1024 * 1024)) {
             throw Object.assign(new Error('Invalid bounded file read limit'), { code: 'DEVICE_READ_LIMIT_INVALID' })
         }
         // Keep each stdout burst bounded, allowing the transport task to send
         // keepalives between chunks. Serialize the whole read with REPL work.
         return this.enqueue(async () => {
-            const deadline = Date.now() + timeout
+            const deadline = timeout === null ? null : Date.now() + timeout
+            const commandBudget = () => {
+                if (deadline === null) return chunkTimeout
+                const remaining = deadline - Date.now()
+                if (remaining <= 0) throw Object.assign(new Error('Device file read timeout'), { code: 'TIMEOUT' })
+                return Math.min(chunkTimeout, remaining)
+            }
             const chunks = []
             let offset = 0
             let size = null
@@ -568,8 +744,6 @@ walk('')
             const incomplete = () => Object.assign(new Error(`Incomplete file response for ${fn}`), { code: 'DEVICE_FILE_READ_INCOMPLETE' })
             for (;;) {
                 throwIfAborted(signal)
-                const remaining = deadline - Date.now()
-                if (remaining <= 0) throw new Error('Device file read timeout')
                 const count = maxBytes === null ? 1024 : Math.min(1024, maxBytes - offset + 1)
                 let source = `
 import binascii
@@ -584,13 +758,13 @@ except Exception as e:
  print('__EVREAD_ERROR__'+repr(e))
 `
                 if (this.execInputBytes(source) > this.inputMaxBytes) {
-                    await this._execPy(`__evcore_read_path=${pythonString(fn)}`, remaining, signal)
+                    await this._execPy(`__evcore_read_path=${pythonString(fn)}`, commandBudget(), signal)
+                    commandBudget()
                     source = source.replace(filePath, '__evcore_read_path')
                     filePath = '__evcore_read_path'
                 }
-                const budget = deadline - Date.now()
-                if (budget <= 0) throw new Error('Device file read timeout')
-                const rsp = await this._execPy(source, budget, signal)
+                const rsp = await this._execPy(source, commandBudget(), signal)
+                commandBudget()
                 const errorAt = rsp.indexOf('__EVREAD_ERROR__')
                 if (errorAt >= 0) throw new Error(`Unable to read ${fn}: ${rsp.slice(errorAt + 16).trim()}`)
                 const match = /(?:^|\n)__EVREAD_OK__(\d+):(\d+):([0-9a-fA-F]*)\s*$/.exec(rsp)

package/src/firmware_flash.js

@@ -112,7 +112,10 @@ export class FirmwareFlashSession {
         }
         await this.reset()
       }
-      catch { onPhase('Firmware verified. Press RESET or reconnect power to start it.'); return { verified: true, needsReset: true } }
+      catch (error) {
+        onPhase('Firmware verified. Automatic reset did not complete; wait for runtime reconnection or press RESET.')
+        return { verified: true, needsReset: true, resetError: { code: error?.code ?? 'RESET_FAILED', message: error?.message ?? String(error) } }
+      }
       onPhase('Firmware verified and reset. Reconnect in the IDE to verify EV-MUX v4.')
       return { verified: true, needsReset: false }
     } catch (error) { this.state = 'error'; throw error }

package/src/node.js

@@ -3,3 +3,13 @@
 // Node-only adapters. Creating them does not acquire a session or serial port.
 export { tcpTransport, serialTransport } from './node_transport.js'
 export { openNodeRom } from './node_rom.js'
+export { defaultPython, filterSerialPorts, inventory, listSerial, serialEntry, transportFor } from './node_inventory.js'
+
+// Bundlers copy these exact published adapters beside their bundled Node entry.
+// Returning URLs is passive and keeps transport assets owned by the SDK.
+export function nodeAdapterAssets() {
+  return Object.freeze({
+    serial: new URL('./node_serial.py', import.meta.url),
+    rom: new URL('./node_rom.py', import.meta.url),
+  })
+}

package/src/node_inventory.js

@@ -8,14 +8,17 @@ import { createDevice } from './index.js'
 import { serialTransport, tcpTransport } from './node_transport.js'
 
 export const defaultPython = process.platform === 'win32' ? 'python' : 'python3'
-export async function listSerial({ python = defaultPython, signal } = {}) {
+export async function listSerial({ python = defaultPython, signal, timeout = 10000 } = {}, dependencies = {}) {
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('Serial enumeration timeout must be positive')
   try {
-    const { stdout } = await promisify(execFile)(python, [fileURLToPath(new URL('./node_serial.py', import.meta.url)), '--list'], { signal, timeout: 10000, maxBuffer: 1024 * 1024, windowsHide: true })
+    const run = dependencies.execFile ?? promisify(execFile)
+    const { stdout } = await run(python, [fileURLToPath(new URL('./node_serial.py', import.meta.url)), '--list'], { signal, timeout, maxBuffer: 1024 * 1024, windowsHide: true })
     const ports = JSON.parse(stdout)
     if (!Array.isArray(ports)) throw new Error('Invalid serial list')
     return ports
   } catch (cause) {
     if (signal?.aborted) throw signal.reason
+    if (cause?.code === 'ETIMEDOUT') throw Object.assign(new Error('Serial enumeration timed out'), { code: 'TIMEOUT', cause })
     throw Object.assign(new Error('Serial enumeration unavailable: install Python and pyserial, or select --python'), { code: 'SERIAL_UNAVAILABLE', cause })
   }
 }
@@ -53,7 +56,7 @@ export function serialEntry(port) {
     : usb ? 'serial' : 'uart'
   return { interface: kind, address: port.path, status: 'unprobed', identity: null, usb: { vendorId: vid ?? null, productId: pid ?? null, serialNumber: port.serialNumber ?? null, product: port.product ?? null, manufacturer: port.manufacturer ?? null }, interfaceSource: 'descriptor-candidate' }
 }
-export function transportFor(entry, options) {
+export function transportFor(entry, options = {}) {
   return entry.interface === 'tcp' ? tcpTransport({ host: entry.host, port: entry.port })
     : serialTransport({ serial: entry.address, role: entry.interface, python: options.python ?? defaultPython })
 }
@@ -84,7 +87,7 @@ export async function inventory(options = {}, dependencies = {}) {
     signal?.throwIfAborted()
     const device = (dependencies.createDevice ?? createDevice)({ transport: (dependencies.transportFor ?? transportFor)(row, options) })
     try {
-      const result = await device.connect({ role: row.interface === 'serial' ? 'unknown' : row.interface, timeout: options.probeTimeout ?? 5000, signal, ...(row.advertisement ? { expectedDevice: row.advertisement } : {}) })
+      const result = await device.connect({ role: row.interface === 'serial' ? 'unknown' : row.interface, timeout: options.probeTimeout ?? 5000, signal, probeRepl: false, ...(row.advertisement ? { expectedDevice: row.advertisement } : {}) })
       row.identity = result.identity; row.inspection = await device.inspect({ fields: options.fields, signal }); row.status = 'identified'
     } catch (error) {
       if (signal?.aborted) throw error

package/src/node_serial.py

@@ -10,6 +10,13 @@ import threading
 import serial
 
 
+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.
+    if platform == 'posix':
+        port.exclusive = True
+
+
 def main():
     if sys.argv[1] == '--list':
         from serial.tools.list_ports import comports
@@ -23,6 +30,7 @@ def main():
     port.rts = False
     port.dtr = True
     port.port = sys.argv[1]
+    _configure_serial_exclusive(port)
     stopped = threading.Event()
 
     def terminate(*_args):
@@ -64,6 +72,6 @@ if __name__ == '__main__':
         main()
     except Exception as error:
         text = str(error).lower()
-        code = 'SERIAL_ACCESS_DENIED' if ('permission denied' in text or 'access is denied' in text or 'access denied' in text) else 'SERIAL_BUSY' if ('resource busy' in text or 'exclusively lock' in text) else 'SERIAL_ERROR'
+        code = 'SERIAL_ACCESS_DENIED' if ('permission denied' in text or 'access is denied' in text or 'access denied' in text) else 'SERIAL_BUSY' if ('resource busy' in text or 'resource temporarily unavailable' in text or 'exclusively lock' in text) else 'SERIAL_ERROR'
         print(code, file=sys.stderr, flush=True)
         sys.exit(2)

package/src/node_transport.js

@@ -46,20 +46,49 @@ export function serialTransport(options) {
       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'] })
-        let ready = false, stderr = ''
-        const abort = () => { child.kill('SIGTERM'); reject(fail('CANCELLED', 'Serial connection cancelled')) }
+        let ready = false, settled = false, runtimeErrorReported = false, stderr = ''
+        const abort = () => {
+          child.kill('SIGTERM')
+          if (!settled) {
+            settled = true
+            reject(fail('CANCELLED', 'Serial connection cancelled'))
+          }
+        }
         const cleanup = () => signal.removeEventListener('abort', abort)
-        const error = () => { cleanup(); const code = ['SERIAL_ACCESS_DENIED', 'SERIAL_BUSY'].find(code => stderr.includes(code)) ?? 'SERIAL_ERROR'; const error = fail(code, 'Serial adapter failed; ensure Python, pyserial and port access are available'); reject(error); events.emit('error', error) }
-        child.on('error', error)
-        child.stdin.on('error', error)
+        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 failBeforeReady = () => {
+          if (settled) return
+          settled = true
+          cleanup()
+          const error = serialError()
+          reject(error)
+          events.emit('error', error)
+        }
+        const reportRuntimeError = () => {
+          if (runtimeErrorReported) return
+          runtimeErrorReported = true
+          events.emit('error', serialError())
+        }
+        child.on('error', () => { if (ready) reportRuntimeError() })
+        child.stdin.on('error', () => { if (ready) reportRuntimeError() })
         child.stdout.on('data', bytes => events.emit('data', bytes))
         child.stderr.on('data', bytes => {
           if (ready) return
           // Do not print Python errors: they can contain host paths or device data.
           stderr = (stderr + bytes.toString()).slice(-128)
-          if (stderr.split(/\r?\n/).includes('READY')) { ready = true; cleanup(); resolveConnect() }
+          if (stderr.split(/\r?\n/).includes('READY')) {
+            ready = true
+            settled = true
+            cleanup()
+            resolveConnect()
+          }
         })
-        child.on('exit', () => { cleanup(); if (!ready) error(); events.emit('close') })
+        // 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(); if (!ready) failBeforeReady(); events.emit('close') })
         signal.addEventListener('abort', abort, { once: true })
         if (signal.aborted) abort()
       })

package/tests/check-browser.mjs

@@ -23,7 +23,7 @@ try {
   assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32p4.json')))
   assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32s31.json')))
   assert.ok(!Object.keys(result.metafile.inputs).some(path => /src\/(node|cli)/.test(path)))
-  const context = vm.createContext({ EventTarget, URL, TextDecoder, TextEncoder, Uint8Array, AbortController, setTimeout, clearTimeout, console, crypto: webcrypto, structuredClone })
+  const context = vm.createContext({ atob, btoa, EventTarget, URL, TextDecoder, TextEncoder, Uint8Array, AbortController, setTimeout, clearTimeout, console, crypto: webcrypto, structuredClone })
   vm.runInContext(code, context)
   let opens = 0, closes = 0
   const adapter = context.DeviceCore.openBrowserRom({ port: {
@@ -46,6 +46,29 @@ try {
     raw._inputBuffer.push(0xc0, 0xdb, 0x47, 0xc0)
     await assert.rejects(raw.readPacket(100), /Invalid SLIP escape/)
   }
+  // Exercise real upstream stub status decoding. A ROM reset consumes four
+  // status bytes while the running stub replies with two; route reset to it.
+  {
+    const raw = new context.DeviceCore.TestLoader({ getInfo: () => ({ usbVendorId: 0x303a, usbProductId: 0x1001 }) }, { log() {}, error() {}, debug() {} })
+    raw.chipFamily = 0x3280; raw.chipRevision = 302
+    raw.memBegin = raw.memBlock = raw.memFinish = async () => {}
+    raw.readPacket = async () => new Uint8Array([79, 72, 65, 73])
+    context.DeviceCore.testCompatibility(raw)
+    const stub = await raw.runStub(true)
+    let writes = 0
+    stub.detectUsbConnectionType = async () => true
+    stub.getUsbMode = async () => ({ mode: 'usb-jtag-serial' })
+    stub.sendCommand = async () => { writes++ }
+    stub.getResponse = async () => [0, new Uint8Array([0, 0])]
+    // Confirm the original ROM instance rejects the exact same stub response.
+    raw.detectUsbConnectionType = stub.detectUsbConnectionType
+    raw.getUsbMode = stub.getUsbMode
+    raw.sendCommand = async () => {}
+    raw.getResponse = stub.getResponse
+    await assert.rejects(context.DeviceCore.TestLoader.prototype.hardReset.call(raw), /status|response|enough/i)
+    await raw.hardReset()
+    assert.equal(writes, 4, 'P4 watchdog writes must use the running stub status decoder')
+  }
   const prototype = context.DeviceCore.TestLoader.prototype
   const originals = Object.fromEntries(['initialize', 'disconnect', 'getSecurityInfo', 'runStub', 'hardReset'].map(key => [key, prototype[key]]))
   let initializeCalls = 0, disconnectCalls = 0
@@ -115,6 +138,7 @@ try {
         async flashData() { writes++; writing.abort() },
         async readFlash(offset) { return offset === 32768 ? table : data },
         async readRegister() { return 0 },
+        async hardReset() { resets++ },
       }
     }
     prototype.hardReset = async () => { resets++ }

package/tests/check-package.mjs

@@ -19,6 +19,8 @@ try {
   assert.ok(packed.files.some(({ path }) => path === 'NOTICE'))
   assert.ok(packed.files.some(({ path }) => path === 'schemas/device-actions-v1.json'))
   assert.ok(packed.files.every(({ path }) => /^(src\/|schemas\/|tests\/|scripts\/|package\.json$|README\.md$|LICENSE$|NOTICE$|CHANGELOG\.md$)/.test(path)), 'tarball must contain only the standalone library')
+  assert.ok(!Object.hasOwn(manifest, 'bin'), 'Device Core no longer installs a management CLI')
+  assert.ok(!packed.files.some(({ path }) => path === 'src/cli.js'), 'the Core package must not contain the CLI')
   assert.ok(!packed.files.some(({ path }) => path.startsWith('docs/')), 'Documentation is published by the ESP-VISION documentation center')
   assert.ok(!packed.files.some(({ path }) => path.includes('__pycache__') || path.endsWith('.pyc')), 'Never ship host Python bytecode')
   const consumer = join(temporary, 'consumer')
@@ -39,10 +41,12 @@ try {
   const { DeviceSession } = await import('@esp-vision/device-core/session');
   const { FirmwareFlashSession, loadOfficialFirmware, loadReleaseManifest } = await import('@esp-vision/device-core/firmware');
   if (typeof loadOfficialFirmware !== 'function' || typeof loadReleaseManifest !== 'function') throw new Error('Missing public release manifest readers');
-  const { tcpTransport, serialTransport, openNodeRom } = await import('@esp-vision/device-core/node');
+  const { defaultPython, filterSerialPorts, inventory, listSerial, serialEntry, tcpTransport, serialTransport, transportFor, openNodeRom } = await import('@esp-vision/device-core/node');
   const { openBrowserRom } = await import('@esp-vision/device-core/browser');
   if (typeof openBrowserRom !== 'function' || typeof openBrowserRom({ port: { open() { throw new Error('Not opened'); }, close() {} } }).initialize !== 'function') throw new Error('Missing passive browser ROM adapter');
   if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
+  if (typeof inventory !== 'function' || typeof listSerial !== 'function' || typeof filterSerialPorts !== 'function'
+      || typeof serialEntry !== 'function' || typeof transportFor !== 'function' || typeof defaultPython !== 'string') throw new Error('Missing public Node inventory APIs');
   const { createNodeDiscovery } = await import('@esp-vision/device-core/discovery/node');
   const { EventEmitter } = await import('node:events');
   let queries = 0;
@@ -58,18 +62,11 @@ try {
   api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });
   if (typeof DeviceSession !== 'function' || typeof FirmwareFlashSession !== 'function') throw new Error('Missing host adapter APIs');`
   execFileSync(process.execPath, ['--input-type=module', '-e', script], { cwd: consumer, stdio: 'pipe' })
-  assert.equal(manifest.bin['esp-vision-device'], './src/cli.js')
-  const help = execFileSync(process.execPath, [join(consumer, 'node_modules/@esp-vision/device-core/src/cli.js'), '--help'], { encoding: 'utf8' })
-  assert.ok(help.includes('esp-vision-device inspect'))
-  if (process.platform !== 'win32') {
-    const installedHelp = execFileSync(join(consumer, 'node_modules/.bin/esp-vision-device'), ['--help'], { encoding: 'utf8' })
-    assert.ok(installedHelp.includes('esp-vision-device inspect'), 'The installed npm command must execute through its symlink')
-  }
   for (const required of ['src/node_serial.py', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.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 unitCount = Number(/^# tests (\d+)$/m.exec(unitOutput)?.[1] ?? 0)
+  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' })
   assert.ok(hardwareHelp.includes('--serial PATH'), 'Installed hardware runner must load and show its help')

package/tests/device-checks.mjs

@@ -4,7 +4,7 @@ import { readFile, mkdir, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { EV_REPL_INPUT_MAX_BYTES, evReplExecInputBytes } from '../src/evrepl.js'
 
-export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream'])
+export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream', 'camera_display_lifecycle', 'image_copy_to_fb', 'image_transform_argument', 'sensor_snapshot_buffer', 'memory_policy'])
 const MARKER = '__EVDEVICECHECK__'
 const failure = (code, message) => Object.assign(new Error(message), { code })
 const unsupported = error => error?.code === 'UNSUPPORTED_OPERATION' || /ESP_ERR_NOT_SUPPORTED|ESP_ERR_NOT_FOUND|no module named|ENODEV/i.test(error?.message ?? '')
@@ -43,7 +43,7 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
   const results = [], namespace = `_evhil_${nonce}`
   let loaded = false, namespaceStarted = false, loadError = null, inputLimit = EV_REPL_INPUT_MAX_BYTES
   const parameters = { frames: options.frames, framesize: options.framesize, pixformat: options.pixformat, displayHold: options.displayHold, screenCapture: Boolean(options.screenOutput) }
-  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
+  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'camera_display_lifecycle' ? options.frameTimeout + 80 : name === 'memory_policy' ? options.frameTimeout + 60 : name === 'sensor_snapshot_buffer' ? options.frameTimeout + 40 : name === 'image_copy_to_fb' ? 30 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
   const execute = async (source, timeout = 10000, operationSignal = signal) => {
     // Larger python.execute() requests use temporary files in Device Core.
     // Keep fixtures in RAM by respecting the actual encoded REPL-line budget.