@esp-vision/device-core 0.1.0 → 0.2.0

package/tests/test-device-actions.mjs

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert/strict'
+import {
+  DEVICE_ACTION_DESCRIPTORS,
+  DEVICE_ACTION_SCHEMA_VERSION,
+  DeviceActionError,
+  DeviceActionGateway,
+  DeviceActionRegistry,
+  DeviceLease,
+  OperationCoordinator,
+} from '../src/device_actions.js'
+import {
+  DeviceEvidenceBuffer,
+  EPHEMERAL_PYTHON_PATH,
+  EphemeralPythonController,
+  bindSessionDeviceActions,
+} from '../src/device_bindings.js'
+
+function deferred() {
+  let resolve
+  const promise = new Promise((done) => { resolve = done })
+  return { promise, resolve }
+}
+
+async function testRegistryContract() {
+  const registry = new DeviceActionRegistry()
+  assert.equal(registry.schemaVersion, DEVICE_ACTION_SCHEMA_VERSION)
+  assert.equal(DEVICE_ACTION_SCHEMA_VERSION, 1)
+  assert.deepEqual(
+    registry.list().map(({ name }) => name),
+    DEVICE_ACTION_DESCRIPTORS.map(({ name }) => name),
+  )
+  const input = registry.validate('python.execute', { code: 'print(1)' })
+  assert.equal(input.timeoutMs, 8000)
+  assert.throws(
+    () => registry.validate('python.execute', { code: 'print(1)', surprise: true }),
+    (error) => error instanceof DeviceActionError && error.code === 'INVALID_INPUT',
+  )
+  assert.deepEqual(
+    registry.validate('deviceFile.remove', { path: '/agent-test.py' }),
+    { path: '/agent-test.py', kind: 'file' },
+  )
+  assert.deepEqual(
+    registry.validate('device.control', { operation: 'bootloader' }),
+    { operation: 'bootloader', confirmBootloader: false },
+  )
+  assert.deepEqual(
+    registry.validate('python.runEphemeral', { code: 'print(1)' }),
+    { code: 'print(1)', maxDurationMs: 180000 },
+  )
+  assert.match(registry.descriptor('device.rpc').description, /reuse the exact same ID and payload/)
+}
+
+async function testNetworkOperationIdReuse() {
+  const registry = new DeviceActionRegistry()
+  bindSessionDeviceActions(registry)
+  const calls = []
+  const session = {
+    async rpc(method, payload, options) {
+      calls.push({ method, payload, options })
+      return { ok: true }
+    },
+  }
+  const operationId = '44444444444444444444444444444444'
+  const payload = { action: 'network.configure', operationId, ssid: 'mock-network', password: 'mock-secret' }
+  const handler = registry.handler('device.rpc')
+  await handler({ method: 'device.control', payload, timeoutMs: 1000 }, { session, signal: null })
+  await handler({ method: 'device.control', payload, timeoutMs: 1000 }, { session, signal: null })
+  assert.deepEqual(calls.map(({ payload: request }) => request.operationId), [operationId, operationId])
+  assert.ok(calls.every(({ method, options }) => method === 'device.control' && options.timeout === 1000))
+}
+
+function fakeEphemeralSession({ cleanupFails = false } = {}) {
+  let current = null
+  return {
+    repl: {
+      async removeFile(path) {
+        assert.equal(path, EPHEMERAL_PYTHON_PATH)
+        if (cleanupFails) throw new Error('device disconnected before cleanup')
+      },
+    },
+    async stopForRepl() { return true },
+    scriptRunSnapshot() {
+      return current ? { path: EPHEMERAL_PYTHON_PATH, output: current.output } : null
+    },
+    runScript(path, code, { signal, onStarted }) {
+      assert.equal(path, EPHEMERAL_PYTHON_PATH)
+      current = { code, output: '' }
+      onStarted()
+      return new Promise((resolve, reject) => {
+        current.finish = (output = '') => {
+          current.output = output
+          resolve({ output })
+        }
+        current.fail = (message) => reject(new Error(message))
+        signal.addEventListener('abort', () => {
+          const error = new Error('stopped')
+          error.name = 'AbortError'
+          reject(error)
+        }, { once: true })
+      })
+    },
+    appendOutput(value) { current.output += value },
+    finish(value) { current.finish(value) },
+    fail(value) { current.fail(value) },
+  }
+}
+
+async function testEphemeralRunLifecycle() {
+  const evidence = new DeviceEvidenceBuffer(10)
+  const session = fakeEphemeralSession()
+  const controller = new EphemeralPythonController(session, { evidence, generation: 'generation-7' })
+  const started = await controller.start('print("ready")', { maxDurationMs: 5000 })
+  assert.match(started.runId, /^generation-7:/)
+  assert.equal(started.status, 'running')
+  await assert.rejects(controller.start('print("duplicate")'), /already active/)
+  session.appendOutput('ready\n')
+  const observed = await controller.observe(started.runId, { waitMs: 0 })
+  assert.equal(observed.output, 'ready\n')
+  assert.equal(observed.finished, false)
+  session.finish('ready\ndone\n')
+  const finished = await controller.observe(started.runId, { waitMs: 100 })
+  assert.equal(finished.status, 'finished')
+  assert.equal(finished.cleaned, true)
+  assert.equal(finished.output, 'ready\ndone\n')
+  await assert.rejects(controller.observe('generation-6:old', { waitMs: 0 }), /stale/)
+  assert.equal(evidence.snapshot().length, 2)
+}
+
+async function testEphemeralTimeoutAndDisconnect() {
+  const timedSession = fakeEphemeralSession()
+  const timedController = new EphemeralPythonController(timedSession, { generation: 'generation-9' })
+  const timed = await timedController.start('while True: pass')
+  timedSession.fail('script run timeout after 1000ms')
+  const timedResult = await timedController.observe(timed.runId, { waitMs: 100 })
+  assert.equal(timedResult.status, 'timed-out')
+  assert.equal(timedResult.cleaned, true)
+
+  const disconnectedSession = fakeEphemeralSession({ cleanupFails: true })
+  const disconnectedController = new EphemeralPythonController(disconnectedSession, { generation: 'generation-10' })
+  const disconnected = await disconnectedController.start('print("disconnect")')
+  disconnectedSession.fail('serial closed')
+  const disconnectedResult = await disconnectedController.observe(disconnected.runId, { waitMs: 100 })
+  assert.equal(disconnectedResult.status, 'failed')
+  assert.equal(disconnectedResult.cleaned, false)
+  assert.equal(disconnectedResult.residualPath, EPHEMERAL_PYTHON_PATH)
+}
+
+async function testEphemeralStopAndCleanupFailure() {
+  const session = fakeEphemeralSession({ cleanupFails: true })
+  const controller = new EphemeralPythonController(session, { generation: 'generation-8' })
+  const started = await controller.start('while True: pass')
+  const stopped = await controller.stop(started.runId)
+  assert.equal(stopped.status, 'stopped')
+  assert.equal(stopped.finished, true)
+  assert.equal(stopped.cleaned, false)
+  assert.equal(stopped.residualPath, EPHEMERAL_PYTHON_PATH)
+  assert.match(stopped.cleanupError, /disconnected/)
+  await assert.rejects(controller.start('print(2)', { signal: AbortSignal.abort() }), /cancelled|aborted/i)
+}
+
+async function testBootloaderAuthorization() {
+  const registry = new DeviceActionRegistry()
+  const lease = new DeviceLease()
+  const token = lease.acquire('agent')
+  const session = { state: 'ready' }
+  let calls = 0
+  registry.bind('device.control', async () => { calls += 1 })
+  const gateway = new DeviceActionGateway({
+    registry,
+    lease,
+    getSession: () => session,
+    authorize: async (descriptor, input) => (
+      descriptor.name !== 'device.control'
+      || input.operation !== 'bootloader'
+      || input.confirmBootloader === true
+    ),
+  })
+  await assert.rejects(
+    gateway.invoke('device.control', { operation: 'bootloader' }, {
+      actor: 'agent',
+      requestId: 'bootloader-denied',
+    }),
+    (error) => error.code === 'ACTION_NOT_AUTHORIZED',
+  )
+  await gateway.invoke('device.control', {
+    operation: 'bootloader',
+    confirmBootloader: true,
+  }, {
+    actor: 'agent',
+    requestId: 'bootloader-approved',
+  })
+  assert.equal(calls, 1)
+  token.release()
+}
+
+async function testLeaseOwnership() {
+  const lease = new DeviceLease()
+  const first = lease.acquire('agent')
+  const second = lease.acquire('agent')
+  assert.throws(
+    () => lease.acquire('unknown-client'),
+    (error) => error.code === 'INVALID_ACTOR',
+  )
+  lease.assertAccess('agent')
+  assert.deepEqual(lease.snapshot().actors, ['agent'])
+  assert.equal(lease.snapshot().holders, 2)
+  second.release()
+  first.release()
+  assert.equal(lease.snapshot().state, 'free')
+}
+
+async function testCoordinatorFifoAndCancellation() {
+  const coordinator = new OperationCoordinator()
+  const gate = deferred()
+  const order = []
+  const first = coordinator.run({
+    actor: 'agent',
+    requestId: 'agent-active',
+    actionName: 'deviceTest.run',
+  }, async () => {
+    order.push('agent-active')
+    await gate.promise
+  })
+  const second = coordinator.run({
+    actor: 'agent',
+    requestId: 'agent-queued-1',
+    actionName: 'device.inspect',
+  }, async () => { order.push('agent-queued-1') })
+  const third = coordinator.run({
+    actor: 'agent',
+    requestId: 'agent-queued-2',
+    actionName: 'device.inspect',
+  }, async () => { order.push('agent-queued-2') })
+  gate.resolve()
+  await Promise.all([first, second, third])
+  assert.deepEqual(order, ['agent-active', 'agent-queued-1', 'agent-queued-2'])
+
+  let wasAborted = false
+  const controller = new AbortController()
+  const activeAgent = coordinator.run({
+    actor: 'agent',
+    requestId: 'cancel-me',
+    actionName: 'deviceTest.run',
+    signal: controller.signal,
+  }, async (signal) => {
+    await new Promise((resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        wasAborted = true
+        reject(signal.reason)
+      }, { once: true })
+    })
+  })
+  await Promise.resolve()
+  controller.abort(new Error('cancelled by test'))
+  await assert.rejects(activeAgent)
+  assert.equal(wasAborted, true)
+  coordinator.close()
+}
+
+async function testGateway() {
+  const registry = new DeviceActionRegistry()
+  const lease = new DeviceLease()
+  const token = lease.acquire('agent')
+  const session = { state: 'ready', marker: 'session' }
+  registry.bind('device.inspect', async (input, context) => ({
+    input,
+    actor: context.actor,
+    session: context.session.marker,
+  }))
+  const gateway = new DeviceActionGateway({ registry, lease, getSession: () => session })
+  const result = await gateway.invoke('device.inspect', { includeFiles: false }, {
+    actor: 'agent',
+    requestId: 'inspect-1',
+  })
+  assert.equal(result.actor, 'agent')
+  assert.equal(result.input.logLimit, 100)
+  assert.equal(result.session, 'session')
+  token.release()
+  await assert.rejects(
+    gateway.invoke('device.inspect', {}, { actor: 'agent', requestId: 'inspect-2' }),
+    (error) => error.code === 'DEVICE_LEASE_REQUIRED',
+  )
+}
+
+async function testBusyRecovery() {
+  const registry = new DeviceActionRegistry()
+  registry.bind('device.connect', async () => {
+    const error = new Error('open failed: Device or resource busy')
+    error.code = 'EBUSY'
+    throw error
+  })
+  const gateway = new DeviceActionGateway({ registry })
+  await assert.rejects(
+    gateway.invoke('device.connect', { port: '/dev/test' }, {
+      actor: 'agent',
+      requestId: 'busy-connect',
+    }),
+    (error) => error.code === 'DEVICE_BUSY' && /explicit handoff/.test(error.recovery),
+  )
+}
+
+async function testPathRecovery() {
+  for (const code of ['INVALID_PATH', 'PATH_TOO_LONG']) {
+    const registry = new DeviceActionRegistry()
+    registry.bind('deviceFile.write', async () => {
+      const error = new Error('Device RPC path exceeds the firmware path contract')
+      error.code = code
+      throw error
+    })
+    const lease = new DeviceLease()
+    const handle = lease.acquire('agent')
+    const gateway = new DeviceActionGateway({ registry, lease, getSession: () => ({ state: 'ready' }) })
+    await assert.rejects(
+      gateway.invoke('deviceFile.write', { path: '/test.py', content: '' }, {
+        actor: 'agent', requestId: `path-${code}`,
+      }),
+      (error) => error.code === code && /path/.test(error.recovery),
+    )
+    handle.release()
+  }
+}
+
+async function testFirmwareVersionRecovery() {
+  const registry = new DeviceActionRegistry()
+  registry.bind('device.connect', async () => {
+    const error = new Error('acquire requires evMuxVersion 4')
+    error.code = 'VERSION_MISMATCH'
+    throw error
+  })
+  const gateway = new DeviceActionGateway({ registry })
+  await assert.rejects(
+    gateway.invoke('device.connect', { port: '/dev/test' }, { actor: 'agent', requestId: 'v4-required' }),
+    (error) => error.code === 'FIRMWARE_INCOMPATIBLE' && /explicitly supports EV-MUX v4/.test(error.recovery),
+  )
+}
+
+async function testControlCancellationBinding() {
+  const registry = new DeviceActionRegistry()
+  bindSessionDeviceActions(registry)
+  const lease = new DeviceLease()
+  const token = lease.acquire('agent')
+  const controller = new AbortController()
+  const session = {
+    state: 'ready',
+    control: async (operation, { signal }) => {
+      assert.equal(operation, 'soft-reset')
+      assert.ok(signal, 'the shared control binding must forward cancellation')
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+        queueMicrotask(() => controller.abort())
+      })
+    },
+  }
+  const gateway = new DeviceActionGateway({ registry, lease, getSession: () => session })
+  try {
+    await assert.rejects(gateway.invoke('device.control', { operation: 'soft-reset' }, {
+      actor: 'agent', requestId: 'reset-cancelled', signal: controller.signal,
+    }), (error) => error.code === 'ACTION_CANCELLED')
+  } finally { token.release() }
+}
+
+await testRegistryContract()
+await testControlCancellationBinding()
+await testNetworkOperationIdReuse()
+await testBootloaderAuthorization()
+await testLeaseOwnership()
+await testCoordinatorFifoAndCancellation()
+await testGateway()
+await testBusyRecovery()
+await testPathRecovery()
+await testFirmwareVersionRecovery()
+await testEphemeralRunLifecycle()
+await testEphemeralStopAndCleanupFailure()
+await testEphemeralTimeoutAndDisconnect()
+console.log('Device action contract tests passed')

package/tests/test-device-api.mjs

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import * as api from '../src/index.js'
+import { DeviceSession, EV_MUX_REQUIRED_FEATURES, EV_MUX_REQUIRED_CHANNELS, EV_MUX_DEFAULT_LIMITS } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+const capabilities = { ok: true, protocol: { evMuxVersion: 4 },
+  features: [...EV_MUX_REQUIRED_FEATURES, 'debug.capture_frame', 'script.write', 'script.run', 'device.control'],
+  channels: EV_MUX_REQUIRED_CHANNELS, limits: { ...EV_MUX_DEFAULT_LIMITS, txLargePayloadMax: 262144 },
+  session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 } }
+function peer({ silent = false, screen = false } = {}) {
+  let handlers, subscriptions = 0, disconnects = 0
+  const requests = [], order = [], id = 'a'.repeat(32)
+  const stdout = payload => handlers?.data(makeEvMuxFrame({ channel: 'repl.stdout', type: 'data', sessionId: id, vmEpoch: 1, payload }))
+  const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
+    if (silent) return false
+    const payload = metadata.channel.endsWith('.rpc') ? JSON.parse(new TextDecoder().decode(bytes)) : new TextDecoder().decode(bytes)
+    requests.push({ metadata, payload })
+    if (metadata.channel === 'repl.stdin') { stdout(`${payload}\r\n${payload.includes('EVIDE_BOOT_OK') ? 'EVIDE_BOOT_OK' : 'result'}\r\n>>> `); return false }
+    if (!metadata.channel.endsWith('.rpc')) return false
+    let result = { ok: true }
+    if (metadata.method === 'hello') result = { ok: true, evMuxVersion: 4, deviceId: 'e8f60ae75642', hostname: 'esp-vision-test', board: 'TEST', firmware: { version: 'test' }, vmReady: true, session: { id, vmEpoch: 1, leaseMs: 15000, keepaliveMs: 5000 } }
+    if (metadata.method === 'capabilities') result = { ...capabilities, features: [...capabilities.features, ...(screen ? ['debug.capture_screen'] : [])] }
+    if (metadata.method === 'session.keepalive') result = { ok: true, sessionId: id, vmEpoch: 1 }
+    if (metadata.method === 'debug.capture_frame' || (screen && metadata.method === 'debug.capture_screen')) {
+      handlers.data(makeEvMuxFrame({ channel: 'debug.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq, sessionId: id, vmEpoch: 1, contentType: 'image/jpeg', width: 2, height: 1, payload: new Uint8Array([255,216,0,255,217]) })); return false
+    }
+    handlers.data(makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq, ...((metadata.method !== 'capabilities' && (metadata.method !== 'hello' || payload.acquire)) ? {sessionId: id, vmEpoch: 1} : {}), payload: JSON.stringify(result) }))
+    return false
+  } })
+  const transport = {
+    subscribe(value) { handlers = value; subscriptions++; order.push('subscribe'); return () => { subscriptions--; order.push('unsubscribe') } },
+    async connect() { order.push('connect') },
+    async disconnect() { disconnects++; order.push('disconnect') },
+    async writeBytes(bytes) { parser.feedBytes(bytes) },
+  }
+  return { transport, requests, order, stdout, close: () => handlers.close(), get subscriptions() { return subscriptions }, get disconnects() { return disconnects } }
+}
+
+test('root exports only the application API; protocols remain explicit adapters', () => {
+  assert.deepEqual(Object.keys(api).sort(), ['createDevice'])
+  const device = api.createDevice()
+  assert.equal(device.session, undefined)
+  assert.equal(device.repl, undefined)
+  assert.equal(device.rpc, undefined)
+  assert.deepEqual(Object.keys(device.python).sort(), ['execute', 'input'])
+  assert.deepEqual(Object.keys(device.files).sort(), ['list','mkdir','read','remove','write'])
+})
+
+test('facade subscribes before connection, negotiates, streams input and disposes exactly once', async () => {
+  const p = peer(), d = api.createDevice({ transport: p.transport }), output = []
+  const unsubscribe = d.on('python.output', value => output.push(value))
+  const ready = await d.connect({ role: 'tcp' })
+  assert.equal(ready.identity.deviceId, 'e8f60ae75642')
+  assert.deepEqual(p.order.slice(0, 2), ['subscribe','connect'])
+  assert.equal(p.subscriptions, 1)
+  await d.python.input('print(2)\r')
+  assert.ok(output.some(text => text.includes('result')))
+  unsubscribe(); const count = output.length; p.stdout('ignored\r\n'); assert.equal(output.length,count)
+  await Promise.all([d.disconnect(), d.disconnect()])
+  assert.equal(p.subscriptions,0); assert.equal(p.disconnects,1)
+  assert.ok(p.requests.some(x => x.metadata.method === 'session.release'))
+  await assert.rejects(d.files.read({path:'/x'}), {code:'DEVICE_NOT_READY'})
+})
+
+test('capture returns binary bytes and unsupported LCD capture never captures the camera', async () => {
+  const p = peer(), d = api.createDevice({transport:p.transport})
+  try {
+    await d.connect({role:'tcp'})
+    const image = await d.capture({source:'camera',quality:70})
+    assert.deepEqual(image.data,new Uint8Array([255,216,0,255,217]))
+    assert.equal(image.mimeType,'image/jpeg')
+    const count=p.requests.length
+    await assert.rejects(d.capture({source:'screen'}),{code:'UNSUPPORTED_OPERATION'})
+    assert.equal(p.requests.length,count)
+  } finally {await d.disconnect()}
+})
+
+test('listener failures cannot break parser delivery and are diagnosed without leaking error text', async () => {
+  const p=peer(),d=api.createDevice({transport:p.transport}),diagnostics=[]
+  d.on('python.output',()=>{throw new Error('secret listener text')})
+  d.on('diagnostic',value=>diagnostics.push(value))
+  try {await d.connect({role:'tcp'});p.stdout('hello\r\n');assert.ok(diagnostics.some(x=>x.event==='listener.error'));assert.ok(!JSON.stringify(diagnostics).includes('secret listener text'))}finally{await d.disconnect()}
+})
+
+test('connection timeout and cancellation dispose reader and transport', async () => {
+  const p=peer({silent:true}),d=api.createDevice({transport:p.transport})
+  await assert.rejects(d.connect({role:'tcp',timeout:20}),{code:'TIMEOUT'})
+  assert.equal(p.subscriptions,0);assert.equal(p.disconnects,1)
+  const controller=new AbortController();controller.abort(new Error('cancelled'))
+  await assert.rejects(d.connect({role:'tcp',signal:controller.signal}),/cancelled/)
+  assert.equal(p.disconnects,1)
+})
+
+test('transport loss clears the connection and permits reconnection',async()=>{
+  const p=peer(),d=api.createDevice({transport:p.transport})
+  await d.connect({role:'tcp'});p.close();await d.disconnect()
+  assert.equal(p.subscriptions,0)
+  await d.connect({role:'tcp'});await d.disconnect();assert.equal(p.disconnects,2)
+})
+
+test('discovery works before any transport is connected',async()=>{
+  const d=api.createDevice({discovery:{async list(){return [{deviceId:'e8f60ae75642',hostname:'esp-vision-test',board:'TEST',firmwareVersion:'1',evMuxVersion:4,port:3232,addresses:['192.168.1.2']}]}}})
+  assert.equal((await d.discover({timeout:50}))[0].compatible,true)
+})
+
+test('binary capture results correlate by sequence even when responses arrive in reverse order',async()=>{
+  let s;const requests=[]
+  const parser=new EvMuxParser({filterFrame(metadata){requests.push(metadata);return false}})
+  s=new DeviceSession({transport:{async writeBytes(b){parser.feedBytes(b)}},EvMuxParser,EvRepl,makeEvMuxFrame})
+  s.state='ready';s.sessionId='a'.repeat(32);s.vmEpoch=1;s.vmReady=true;s.capabilities={features:[]}
+  try {
+    const first=s.captureImage('debug.capture_frame'),second=s.captureImage('debug.capture_frame')
+    first.catch(()=>{});second.catch(()=>{})
+    await new Promise(setImmediate)
+    for(const [index,payload] of [[1,22],[0,11]]){const req=requests[index];s.feedBytes(makeEvMuxFrame({channel:'debug.rpc',type:'rsp',method:req.method,seq:req.seq,sessionId:s.sessionId,vmEpoch:1,contentType:'image/jpeg',payload:new Uint8Array([payload])}))}
+    assert.deepEqual((await first).data,new Uint8Array([11]));assert.deepEqual((await second).data,new Uint8Array([22]))
+  }finally{s.close()}
+})
+
+test('long Unicode paths stay within REPL budget for directory reads and inline execution',async()=>{
+  const repl=new EvRepl({writeEvmux(){}}),path='/'+ 'é'.repeat(61),commands=[]
+  repl.execPy=async source=>{commands.push(source);assert.ok(repl.execInputBytes(source)<=511);return source.includes('__EVLIST__')?'__EVLIST__[]\n':''}
+  assert.deepEqual(await repl.listFs(path),[])
+  assert.equal(commands.length,2,'Long escaped paths are assigned separately from directory code')
+  const command=repl.createScriptRunCommand(path)
+  assert.ok(new TextEncoder().encode(command).length<=511)
+  if(repl.scriptRunPrelude)assert.ok(repl.execInputBytes(repl.scriptRunPrelude)<=511)
+  repl.cancelScriptEndSentinel()
+})
+
+test('inspection snapshots cannot change internal capabilities',async()=>{
+  const p=peer(),d=api.createDevice({transport:p.transport})
+  try{
+    await d.connect({role:'tcp'})
+    const value=await d.inspect({fields:['runtime']});value.runtime.capabilities.features.length=0
+    const image=await d.capture({source:'camera'});assert.equal(image.mimeType,'image/jpeg')
+  }finally{await d.disconnect()}
+})
+
+test('file read and removal keep the longest escaped paths below REPL input limits',async()=>{
+  const repl=new EvRepl({writeEvmux(){}}),path='/'+ 'é'.repeat(61),sources=[]
+  repl._execPy=async source=>{
+    sources.push(source);assert.ok(repl.execInputBytes(source)<=511)
+    return source.includes('__EVREAD_OK__')?'__EVREAD_OK__1:1:ff\n':source.includes("'ok':True")?'true\n'+JSON.stringify({ok:true}):''
+  }
+  assert.deepEqual(await repl.readFile(path),new Uint8Array([255]))
+  await repl.removeFile(path);await repl.removeDir(path)
+  assert.ok(sources.some(s=>s.includes('__evcore_read_path=')))
+  assert.ok(sources.some(s=>s.includes('__evcore_fs_path=')))
+})
+
+test('LCD capture uses its advertised screen method and preserves dimensions and quality', async () => {
+  const p = peer({ screen: true }), d = api.createDevice({ transport: p.transport })
+  try {
+    await d.connect({ role: 'tcp' })
+    const image = await d.capture({ source: 'screen', format: 'jpeg', quality: 85 })
+    assert.equal(image.mimeType, 'image/jpeg')
+    assert.equal(image.metadata.width, 2)
+    assert.equal(image.metadata.height, 1)
+    assert.deepEqual(image.data, new Uint8Array([255,216,0,255,217]))
+    const request = p.requests.find(x => x.metadata.method === 'debug.capture_screen')
+    assert.deepEqual(request.payload, { quality: 85 })
+    assert.equal(p.requests.some(x => x.metadata.method === 'debug.capture_frame'), false)
+  } finally { await d.disconnect() }
+})
+
+test('firmware facade trusts connected identity and releases EV-MUX before opening ROM', async () => {
+  const { firmwareSha256 } = await import('../src/firmware_flash.js')
+  const p = peer(), device = api.createDevice({ transport: p.transport })
+  const ready = await device.connect({ role: 'tcp' }), data = new Uint8Array([0xe9, 1])
+  const release = { board: ready.identity.board, version: 'next', image: { evMuxVersion: 4, chipFamily: 1, chipRevision: 0, offset: 65536, bytes: 2, partitionSize: 4096, sha256: await firmwareSha256(data), partitionTable: { offset: 32768, bytes: 1, sha256: '0'.repeat(64) } } }
+  const result = await device.firmware.check({ catalog: { schemaVersion: 1, releases: [release] }, identity: { board: 'OTHER', firmwareVersion: 'wrong' } })
+  assert.equal(result.available, true); assert.equal(result.currentVersion, ready.identity.firmwareVersion)
+  await assert.rejects(device.firmware.update({ release, data, async openLoader() {
+    assert.equal(p.disconnects, 1)
+    assert.equal(p.subscriptions, 0)
+    throw new Error('expected port-selection failure')
+  } }), /expected port-selection failure/)
+  await assert.rejects(device.inspect(), { code: 'DEVICE_NOT_READY' })
+})