@esp-vision/device-core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.7.0
+
+### Fixed
+
+- Allow a serial frame split across the initial 300 ms startup drain to finish within the parser's existing progress/total budgets while rejecting old frames and sending no hello. Freeze the total deadline across successive frames, fail when the parser discards an incomplete frame on timeout, and cancel boundary waits on abort or close; retain conservative failure for injected older parsers without receive-budget support. Add payload-free partial-frame timing/timeout diagnostics and regressions for split/coalesced startup data, bounded progress and cleanup.
+
+### Changed
+
+- Expose the browser ROM adapter's canonical factory `chipMac`, matching Node, and accept a strictly validated optional `expectedMac` before any port access. Bind initialization and baud recovery to that MAC as well as chip family/revision; mismatches preserve `ROM_IDENTITY_CHANGED` and close the adapter before another stub, erase or write. Keep initial manually selected ROM usage compatible when the option is omitted.
+
+- Clear and verify the S31 LP download latch at its own target address after programming, preserving unrelated bits before reset so software ROM entry can return to the application.
+
+- Explicit complete installation clears internal FAT filesystem files, including scripts and models, before writing firmware; application updates retain their existing data-preserving behavior. Hosts must explain this deletion before selecting install mode. Complete images may also replace NVS configuration; SD cards are not erased.
+- Require complete installations to derive the unencrypted writable `ffat` range from the hash-approved ESP partition table, verify layout/MD5, application bounds, chip/security and flash capacity, then erase and verify that exact range before any firmware write. Unsupported layouts/adapters, erase/read errors and cancellation before writing fail without reset or automatic retry.
+- Add `eraseRegion(address, size)` to the built-in browser/Node ROM stubs, using fixed official esptool primitives with sector-aligned bounds. Custom full-install adapters need the same capability; application-only adapters do not.
+- Bind installation qualification to private metadata/data snapshots. Cancellation is honored during erase and erased-range verification; once firmware writing starts, the existing complete-verification/reset policy remains in force.
+
+## 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

@@ -19,11 +19,12 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-This source targets **0.6.0**, a minor release after 0.5.1. The **0.6.x** package line is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Declare a minor-locked dependency and use a lockfile to record the resolved patch and integrity; verify the chosen version exists in the public registry before installing. For unpublished source changes, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
+This source targets **0.7.0**, an unpublished minor release after 0.6.1. Device Core is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Declare a minor-locked dependency and use a lockfile to record the resolved patch and integrity; verify the chosen version exists in the public registry before installing. For unpublished source changes, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm view @esp-vision/device-core@0.6.0 version dist.integrity
-npm install '@esp-vision/device-core@~0.6.0' --registry=https://registry.npmjs.org/
+# Published example; the pending 0.7.0 APIs require a candidate tarball.
+npm view @esp-vision/device-core@0.6.1 version dist.integrity
+npm install '@esp-vision/device-core@~0.6.1' --registry=https://registry.npmjs.org/
 ```
 
 A source version, dry run or open merge request does not publish a package. CLI and Plugin bundles keep their own versions and embedded Core bytes; publishing Core alone does not update those installed tools.
@@ -52,7 +53,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
 
@@ -141,7 +142,9 @@ To validate before npm publication, check out an exact reviewed commit, run `npm
 
 ### Browser ROM flashing
 
-`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal?, interface?, baudRate?, onStatus? })`. Construction is passive; `initialize()` lazily loads the official `esptool-js@0.7.1` backend and synchronizes at 115200. Use a browser bundler such as webpack, Vite or esbuild to include the chip stubs. The root and `/node` entry points do not load browser modules. No Python installation or consumer-side dependency patch is needed.
+`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal?, interface?, baudRate?, onStatus?, expectedMac? })`. Construction is passive; `initialize()` lazily loads the official `esptool-js@0.7.1` backend and synchronizes at 115200. Use a browser bundler such as webpack, Vite or esbuild to include the chip stubs. The root and `/node` entry points do not load browser modules. No Python installation or consumer-side dependency patch is needed.
+
+The candidate 0.7.0 browser adapter exposes `chipMac`, using the same 12 lowercase hexadecimal factory-MAC representation as the Node adapter. It is `null` before identity qualification. The browser reads it through the official chip's `readMac(loader)` primitive, without duplicating eFuse layouts. Pass the verified factory MAC of the selected runtime as `expectedMac` when handing that device to ROM, for example a validated `machine.unique_id()` known to match that board's factory MAC. The host must establish this source; an arbitrary legacy `deviceId` or USB VID/PID does not establish the association. If it cannot verify that value, use an explicitly user-selected manual ROM workflow rather than infer an automatic association. The option accepts exactly 12 hexadecimal characters, normalizes uppercase and rejects separators, whitespace, `null` and other types synchronously before opening a port. A mismatch returns `ROM_IDENTITY_CHANGED`, closes the adapter and cannot start a stub, erase or write. An unreadable/malformed MAC response returns `ROM_IDENTITY_INVALID`. Without the option, manually selecting an initial ROM remains supported; all later synchronization/recovery still binds the original family, revision and MAC, rejecting a different same-model device without rebinding.
 
 `interface` accepts `auto` (default), `uart`, `usb-otg` and `usb-jtag`. Auto detection distinguishes known USB-UART bridge descriptors from Espressif OTG and Serial/JTAG; ambiguous custom descriptors stay conservative and can be identified explicitly. A ready OTG ROM is synchronized without toggling DTR/RTS. A detached or re-enumerated device requires selecting its current download port again; the SDK never treats a stale port object as a recovered session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {

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.7.0",
   "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/browser.js

@@ -1,12 +1,14 @@
 // SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
 // SPDX-License-Identifier: Apache-2.0
+import { normalizeExpectedMac } from './rom_identity.js'
 
 export { serialTransport } from './browser_serial.js'
 
 /** Passive browser ROM adapter. Request the SerialPort in the UI's click handler. */
-export function openBrowserRom({ port, logger = {}, signal, interface: romInterface = 'auto', baudRate = 'auto', onStatus = () => {} } = {}) {
+export function openBrowserRom({ port, logger = {}, signal, interface: romInterface = 'auto', baudRate = 'auto', onStatus = () => {}, expectedMac } = {}) {
   if (!port || typeof port.open !== 'function' || typeof port.close !== 'function') throw new TypeError('A browser SerialPort is required')
   if (signal !== undefined && (!signal || typeof signal.addEventListener !== 'function' || typeof signal.aborted !== 'boolean')) throw new TypeError('signal must be an AbortSignal')
+  const expected = normalizeExpectedMac(expectedMac)
   let raw, initialized, closing = false, cleanup
   const closed = () => Object.assign(new Error('Browser ROM adapter is closed'), { code: 'ROM_CLOSED' })
   const cancelled = () => signal.reason instanceof Error ? signal.reason : Object.assign(new Error('Firmware operation cancelled'), { name: 'AbortError' })
@@ -25,6 +27,7 @@ export function openBrowserRom({ port, logger = {}, signal, interface: romInterf
     get chipName() { return raw?.chipName ?? null },
     get chipFamily() { return raw?.chipFamily ?? null },
     get chipRevision() { return raw?.chipRevision ?? null },
+    get chipMac() { return raw?.chipMac ?? null },
     get interface() { return raw?.interface ?? romInterface },
     get baudRate() { return raw?.baudRate ?? null },
     initialize() {
@@ -43,7 +46,7 @@ export function openBrowserRom({ port, logger = {}, signal, interface: romInterf
             log: (...args) => logger.log?.(...args),
             error: (...args) => logger.error?.(...args),
             debug: (...args) => logger.debug?.(...args),
-          }, { interface: romInterface, baudRate, onStatus })
+          }, { interface: romInterface, baudRate, onStatus, signal, expectedMac: expected })
           if (closing || signal?.aborted) { await disconnect(); check() }
           await raw.initialize()
           check()

package/src/browser_rom.js

@@ -3,6 +3,7 @@
 // Loaded only by openBrowserRom.initialize(), never by the root/Node entry point.
 import { ESPLoader, Transport } from 'esptool-js'
 import { browserRomCompatibility, browserTransportCompatibility, readBrowserFlash, romError, romWords } from './browser_rom_compat.js'
+import { normalizeExpectedMac } from './rom_identity.js'
 
 export const ROM_UART_BAUD_RATES = Object.freeze([2000000, 1500000, 921600, 460800, 115200])
 const families = { 'ESP32-S3': 0x3253, 'ESP32-P4': 0x3280, 'ESP32-S31': 0x3231 }
@@ -29,8 +30,9 @@ export function createBrowserLoader(port, logger = {}, options = {}) {
 // Dependency injection is internal to the package and permits lifecycle/error
 // testing against fake official-loader dependencies without browser globals.
 export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: SerialTransport }, port, logger = {}, {
-  interface: requestedInterface = 'auto', baudRate = 'auto', onStatus = () => {},
+  interface: requestedInterface = 'auto', baudRate = 'auto', onStatus = () => {}, signal, expectedMac,
 } = {}) {
+  const expected = normalizeExpectedMac(expectedMac)
   let kind = browserRomInterface(port, requestedInterface)
   if (baudRate !== 'auto' && !ROM_UART_BAUD_RATES.includes(baudRate)) throw new RangeError('Unsupported ROM UART baudRate')
   let loader, transport, identity, initialized = false, active = false, fault, writing = false, disconnected = false
@@ -61,8 +63,19 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
       await loader.detectChip(mode, 3)
       if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
       if (!loader.chip || !families[loader.chip.CHIP_NAME]) throw romError('ROM_CHIP_UNSUPPORTED', 'Browser flashing supports ESP32-S3, ESP32-P4 and ESP32-S31')
-      const current = { name: loader.chip.CHIP_NAME, family: families[loader.chip.CHIP_NAME], revision: await loader.chip.getChipRevision(loader) }
-      if (identity && (identity.family !== current.family || identity.revision !== current.revision)) throw romError('ROM_IDENTITY_CHANGED', 'Chip identity changed while recovering the download session')
+      const revision = await loader.chip.getChipRevision(loader)
+      if (typeof loader.chip.readMac !== 'function') throw romError('ROM_IDENTITY_INVALID', 'The ROM chip does not expose its factory MAC reader')
+      const rawMac = await loader.chip.readMac(loader)
+      // The pinned official chip API returns six colon-separated hex octets.
+      // Keep register layouts and byte ordering owned by that implementation.
+      if (typeof rawMac !== 'string' || rawMac.length !== 17 || !/^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/i.test(rawMac)) throw romError('ROM_IDENTITY_INVALID', 'The ROM did not return a complete factory MAC')
+      const mac = rawMac.replaceAll(':', '').toLowerCase()
+      const current = { name: loader.chip.CHIP_NAME, family: families[loader.chip.CHIP_NAME], revision, mac }
+      if ((expected !== undefined && current.mac !== expected)
+          || (identity && (identity.family !== current.family || identity.revision !== current.revision || identity.mac !== current.mac))) {
+        throw romError('ROM_IDENTITY_CHANGED', 'ROM identity differs from the selected device or the bound download session')
+      }
+      if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
       identity = current
       if (kind === 'unknown') {
         if (await loader.usesUsbOtg()) kind = 'usb-otg'
@@ -71,8 +84,13 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
       initialized = true
       status({ phase: 'rom-connected', interface: kind, baudRate: transport.baudrate })
     } catch (error) {
-      initialized = false
+      initialized = active = false
       await closeTransport().catch(() => {})
+      if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_IDENTITY_INVALID') {
+        fault = error
+        disconnected = true
+        throw error
+      }
       const lost = /device.*lost|disconnected|setSignals|networkerror/i.test(`${error.name} ${error.message}`)
       if (lost) throw romError('ROM_PORT_LOST', 'Download port detached or re-enumerated; select its current ROM port again', error)
       if (kind === 'usb-otg') throw romError('ROM_MANUAL_DOWNLOAD', 'USB-OTG ROM is not ready. Hold BOOT, press RESET, release BOOT, then select the ROM port again', error)
@@ -128,7 +146,7 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
         return
       } catch (error) {
         status({ phase: 'baud-failed', interface: kind, baudRate: candidate, code: error.code ?? 'ROM_BAUD_FAILED', message: error.message })
-        if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_SECURITY' || error.code === 'ROM_PORT_LOST') throw error
+        if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_IDENTITY_INVALID' || error.code === 'ROM_SECURITY' || error.code === 'ROM_PORT_LOST') throw error
         if (index === candidates.length - 1) throw romError('ROM_BAUD_FAILED', 'No requested UART download speed passed verification', error)
       }
     }
@@ -160,6 +178,37 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
     readRegister: address => operation(() => loader.readReg(address)),
     writeRegister: (address, value, mask = 0xffffffff) => operation(() => loader.writeReg(address, value, mask)),
     readFlash: (address, size, progress, options) => operation(() => readBrowserFlash(loader, address, size, progress, options)),
+    eraseRegion(address, size) {
+      return operation(async () => {
+        if (!Number.isSafeInteger(address) || address < 0 || address % 4096 !== 0
+            || !Number.isSafeInteger(size) || size <= 0 || size > 0xffffffff || size % 4096 !== 0
+            || address + size > 0x100000000) throw new RangeError('ROM erase requires a positive, sector-aligned 32-bit address range')
+        if (loader.ESP_ERASE_REGION !== 0xd1 || typeof loader.timeoutPerMb !== 'function'
+            || !Number.isFinite(loader.ERASE_REGION_TIMEOUT_PER_MB) || loader.ERASE_REGION_TIMEOUT_PER_MB <= 0) throw romError('ROM_ERASE_UNSUPPORTED', 'Use the qualified esptool-js region erase primitives')
+        const cancelled = () => signal.reason instanceof Error ? signal.reason : Object.assign(romError('CANCELLED', 'Flash region erase cancelled'), { name: 'AbortError' })
+        if (signal?.aborted) throw cancelled()
+        let abort
+        const aborted = new Promise((_, reject) => {
+          abort = () => { reject(cancelled()); void adapter.disconnect().catch(() => {}) }
+        })
+        signal?.addEventListener('abort', abort, { once: true })
+        try {
+          if (signal?.aborted) throw cancelled()
+          status({ phase: 'erasing-region', address, size })
+          // 0.7.1 exposes the region command and checked request primitives,
+          // but no eraseRegion convenience method. Retain its framing, status
+          // parser and size-scaled timeout rather than implementing transport.
+          const erasing = loader.checkCommand('erase region', loader.ESP_ERASE_REGION, romWords(address, size), 0, 0,
+            loader.timeoutPerMb(loader.ERASE_REGION_TIMEOUT_PER_MB, size))
+          const result = await (signal ? Promise.race([erasing, aborted]) : erasing)
+          assertReady()
+          if (signal?.aborted) throw cancelled()
+          if (!transport.device?.readable || !transport.device?.writable) throw romError('ROM_PORT_LOST', 'Serial device disconnected during Flash region erase')
+          if (!active || !loader.IS_STUB) throw romError('ROM_STUB_REQUIRED', 'Flash region erase lost its validated stub')
+          if (result !== 0) throw romError('ROM_ERASE_STATUS', `Flash region erase command failed: ${result}`)
+        } finally { signal?.removeEventListener('abort', abort) }
+      })
+    },
     flashData(data, progress, address, _compress) {
       return operation(async () => {
         if (writing) throw romError('ROM_WRITE_REUSE', 'Start a fresh download session before another firmware write')
@@ -175,6 +224,7 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
     get chipName() { return identity?.name ?? null },
     get chipFamily() { return identity?.family ?? null },
     get chipRevision() { return identity?.revision ?? null },
+    get chipMac() { return identity?.mac ?? null },
     get interface() { return kind },
     get baudRate() { return kind === 'uart' ? transport?.baudrate ?? 115200 : null },
     async initialize() { if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed'); await detect(kind === 'uart' || kind === 'usb-jtag' ? 'default_reset' : 'no_reset') },

package/src/device_session.js

@@ -343,6 +343,7 @@ export class DeviceSession {
     this.vmReadinessProbeActive = false
     this.pendingRpc = new Map()
     this.draining = false
+    this.startupDrainWait = null
     this.lastDebugImage = null
     this.runCapture = null
     this.runStarting = false
@@ -690,6 +691,7 @@ export class DeviceSession {
 
   feedBytes(bytes) {
     this.parser.feedBytes(bytes)
+    this.startupDrainWait?.check()
   }
 
   feedText(text) {
@@ -1031,6 +1033,62 @@ export class DeviceSession {
     return tracked
   }
 
+  _startupFrameError(reason) {
+    this._diagnostic('negotiate.startup_incomplete', { reason, parser: this.parser.getDiagnostics?.() })
+    return Object.assign(new Error('Incomplete EV-MUX frame at end of startup drain'), {
+      code: 'SERIAL_STARTUP_INCOMPLETE_FRAME',
+    })
+  }
+
+  _waitForStartupFrameBoundary(signal, timeoutCount, initial, totalDeadline) {
+    this._diagnostic('negotiate.startup_frame_wait', { parser: this.parser.getDiagnostics?.() })
+    return new Promise((resolve, reject) => {
+      let timer = null
+      let settled = false
+      let receiveDeadline = Math.min(totalDeadline, initial.progressDeadline)
+      const finish = (error) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', abort)
+        if (this.startupDrainWait === waiter) this.startupDrainWait = null
+        if (error) reject(error)
+        else resolve()
+      }
+      const abort = () => finish(abortError(signal))
+      const check = () => {
+        if (settled) return
+        clearTimeout(timer)
+        if (signal?.aborted) { abort(); return }
+        // A parser timeout may have emptied the buffer before this callback.
+        // Discarding an unfinished frame is never a completed startup boundary.
+        if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+          finish(this._startupFrameError('receive_timeout'))
+          return
+        }
+        if (Date.now() >= receiveDeadline) {
+          finish(this._startupFrameError('receive_timeout'))
+          return
+        }
+        if (!this.parser.hasPartialFrame?.()) { finish(); return }
+        const current = this.parser._partialFrameBudget?.()
+        if (!Number.isFinite(current?.totalDeadline) || !Number.isFinite(current?.progressDeadline)) {
+          finish(this._startupFrameError('receive_budget_unavailable'))
+          return
+        }
+        // New frames in a coalesced chunk must not extend the original bound.
+        receiveDeadline = Math.min(totalDeadline, current.totalDeadline, current.progressDeadline)
+        const remaining = receiveDeadline - Date.now()
+        if (remaining <= 0) { finish(this._startupFrameError('receive_timeout')); return }
+        timer = setTimeout(() => finish(this._startupFrameError('receive_timeout')), remaining)
+      }
+      const waiter = { check, fail: finish }
+      this.startupDrainWait = waiter
+      signal?.addEventListener('abort', abort, { once: true })
+      check()
+    })
+  }
+
   async _negotiate({ role = 'unknown', drainMs = 300, signal = null, acquire = true, probeRepl = true, expectedDevice = null, autoBaud = true } = {}) {
     this.role = role
     this.state = 'negotiating'
@@ -1039,23 +1097,40 @@ export class DeviceSession {
     // Unclaimed TCP sockets expire in three seconds: acquire immediately.
     if (role === 'tcp') drainMs = 0
     if (drainMs > 0) {
+      const timeoutCount = this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0
       this.draining = true
       try {
         await awaitWithSignal(this.sleep(drainMs), signal)
+        if (signal?.aborted) throw abortError(signal)
+        if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+          throw this._startupFrameError('receive_timeout')
+        }
+        let totalDeadline = null
+        while (this.parser.hasPartialFrame?.()) {
+          const initial = this.parser._partialFrameBudget?.()
+          if (!Number.isFinite(initial?.totalDeadline) || !Number.isFinite(initial?.progressDeadline)) {
+            throw this._startupFrameError('receive_budget_unavailable')
+          }
+          totalDeadline ??= initial.totalDeadline
+          await this._waitForStartupFrameBoundary(signal, timeoutCount, initial, totalDeadline)
+          // An adapter may synchronously deliver another chunk before the
+          // resolved boundary promise resumes this negotiation continuation.
+          if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+            throw this._startupFrameError('receive_timeout')
+          }
+        }
+      } catch (error) {
+        if (error.code === 'SERIAL_STARTUP_INCOMPLETE_FRAME') {
+          this.close(error)
+          this.parser.reset()
+          await this.transport.disconnect?.()
+        }
+        throw error
       } finally {
         this.draining = false
       }
     }
     if (signal?.aborted) throw abortError(signal)
-    if (drainMs > 0 && this.parser.hasPartialFrame?.()) {
-      const error = Object.assign(new Error('Incomplete EV-MUX frame at end of startup drain'), {
-        code: 'SERIAL_STARTUP_INCOMPLETE_FRAME',
-      })
-      this.close(error)
-      this.parser.reset()
-      await this.transport.disconnect?.()
-      throw error
-    }
 
     let capabilities
     let discovery
@@ -1843,6 +1918,7 @@ export class DeviceSession {
 
   close(error = new Error('connection closed')) {
     this.negotiateController?.abort(error)
+    this.startupDrainWait?.fail(error)
     this.draining = false
     clearTimeout(this.keepaliveTimer)
     this.keepaliveTimer = null

package/src/evmux.js

@@ -108,6 +108,7 @@ export class EvMuxParser {
         this.frameTotalTimeoutMs = 12000
         this.partialFrame = null
         this.partialFrameTimer = null
+        this.incompleteFrameTimeouts = 0
     }
 
     setLimits({ metadataMax, payloadMax, frameProgressTimeoutMs, frameTotalTimeoutMs } = {}) {
@@ -152,6 +153,7 @@ export class EvMuxParser {
                 return
             }
             this._clearPartialFrame()
+            this.incompleteFrameTimeouts += 1
             this.buffer = new Uint8Array(0)
             this.rawTextDecoder = new TextDecoder('utf-8', { fatal: false })
             this.replTextDecoders = {
@@ -180,6 +182,17 @@ export class EvMuxParser {
         this.droppedFrames = 0
         this.invalidImageFrames = 0
         this.lastChannel = null
+        this.incompleteFrameTimeouts = 0
+    }
+
+    _partialFrameBudget() {
+        if (!this.partialFrame) return null
+        return {
+            startedAt: this.partialFrame.startedAt,
+            lastProgressAt: this.partialFrame.lastProgressAt,
+            progressDeadline: this.partialFrame.lastProgressAt + this.frameProgressTimeoutMs,
+            totalDeadline: this.partialFrame.startedAt + this.frameTotalTimeoutMs,
+        }
     }
 
     getDiagnostics() {
@@ -192,6 +205,8 @@ export class EvMuxParser {
             droppedFrames: this.droppedFrames,
             invalidImageFrames: this.invalidImageFrames,
             lastChannel: this.lastChannel,
+            partialFrame: this._partialFrameBudget(),
+            incompleteFrameTimeouts: this.incompleteFrameTimeouts,
         }
     }