The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { spawn } from 'node:child_process'
import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { pathToFileURL } from 'node:url'
import { describe, expect, it, vi } from 'vitest'
import { CableFleet as SourceFleet, testDialDiscovery, type CableFleetOptions } from './cableFleet.js'
import { CableSession, type CableHost, type CablePort } from './cableSession.js'
import { CableDecoder, CableType, encodeCableFrame } from './cableFrame.js'
import { DialLog } from './dialLog.js'
import { DialVerdicts } from './dialPortVerdicts.js'
import { completeFlash } from '../lib/flashRecovery.js'
import { createDarwinDialFinder, parseDarwinDialPorts, portInUse, type DialPort } from './serial.js'
// Run the same two-device scenarios against the staged helper before deployment.
const CableFleet: typeof SourceFleet = process.env.HARNESS_TEST_USB_FLEET
? (await import(pathToFileURL(process.env.HARNESS_TEST_USB_FLEET).href)).CableFleet : SourceFleet
const device = (path: string, serialNumber: string): DialPort => ({ path, serialNumber, vendorId: 0x303a, productId: 0x1001 })
class Peer implements CablePort {
isOpen = true
sent: Record<string, unknown>[] = []
private decoder = new CableDecoder()
constructor(readonly path: string, private onData: (chunk: Buffer) => void, private onClosed: (why: string) => void) {}
async write(bytes: Uint8Array) { this.decoder.feed(bytes, frame => {
if (frame.type === CableType.Json) this.sent.push(JSON.parse(Buffer.from(frame.payload).toString()))
}) }
async close(why = 'disconnected') { if (this.isOpen) { this.isOpen = false; this.onClosed(why) } }
say(message: Record<string, unknown>) { this.onData(Buffer.from(encodeCableFrame(CableType.Json, Buffer.from(JSON.stringify(message))))) }
raw(bytes: Buffer) { this.onData(bytes) }
pcm(value: number) { this.onData(Buffer.from(encodeCableFrame(CableType.Pcm, Buffer.alloc(3200, value)))) }
}
function fixture(extra: Partial<CableFleetOptions> = {}, Log: typeof DialLog = DialLog) {
let present = [device('/dev/tim', 'AA:01'), device('/dev/tux', 'BB:02')]
const ports: Peer[] = []
const host: CableHost = {
localMachine: () => ({ id: 'local', name: 'Fixture' }),
listMachines: async () => ({ machines: [], source: 'backend' }),
selectedMachine: () => 'local', selectMachine: async () => ({ ok: true }),
listSwarms: () => ({ selected: 'tab', swarms: [], tiles: [] }), listUnread: () => [],
selectSwarm: vi.fn(), appName: () => 'harness', voiceLang: () => 'en',
listAgents: async () => [{ id: 'a', name: 'A', engine: 'codex' }], agentTotal: () => 1,
activeSwarm: () => 'tab', describe: () => ({ name: 'A', engine: 'codex', machine: 'local' }),
sendTurn: vi.fn(), stopTurn: vi.fn(), scrolled: vi.fn(), answer: vi.fn(), focus: vi.fn(),
openAgent: vi.fn(), forkAgent: async () => ({ ok: true, agentId: 'fork' }), updateAgent: vi.fn(),
listModels: async () => [], recentSummaries: async () => [],
transcribe: vi.fn(async pcm => `audio-${pcm[0]}`),
route: async () => ({ agentId: 'a', confidence: 1, reason: 'fixture' }), log: vi.fn(),
onDialAttached: vi.fn(), onDialGone: vi.fn(), onDialStatus: vi.fn(),
}
const logs = mkdtempSync(join(tmpdir(), 'usb-fleet-'))
const options = {
canUseUsb: vi.fn(() => true),
// Nobody else holds these ports. The default asks `lsof`, a process per port per scan, which on a
// loaded machine outlasts the second a test waits for both dials.
inUse: vi.fn(async () => false),
discover: vi.fn(async () => present), intervalMs: 60_000,
open: vi.fn(async (path: string, onData: (chunk: Buffer) => void, onClosed: (why: string) => void) => {
const port = new Peer(path, onData, onClosed); ports.push(port); return port
}),
}
const fleet = new CableFleet(CableSession, host, logs, Log, { ...options, ...extra })
async function start() { fleet.start(); await vi.waitFor(() => expect(ports).toHaveLength(2)); await greet(ports) }
async function greet(peers: Peer[]) {
for (const p of peers) p.say({ t: 'hello', product: 'harness', mac: p.path, fw: 'fixture', proto: 3 })
await vi.waitFor(() => { for (const p of peers) expect(p.sent.some(m => m.t === 'agents.end')).toBe(true) })
}
return { fleet, host, ports, options, logs, start, greet, setPorts: (p: DialPort[]) => { present = p } }
}
describe('the end-to-end suite\'s dial', () => {
it('is found at the pseudo-terminal it names, and nothing is changed without one', async () => {
expect(testDialDiscovery(undefined)).toEqual({})
expect(testDialDiscovery('')).toEqual({})
const { discover } = testDialDiscovery('/dev/ttys042')
expect(await discover!()).toEqual([{ path: '/dev/ttys042', vendorId: 0x303a, productId: 0x1001, serialNumber: 'E2E-DIAL' }])
})
it('are the pseudo-terminals a file lists, read at every scan, so a test can plug and unplug them', async () => {
let listed = '[{"path":"/dev/ttys001","serial":"E2E-1"},{"path":"/dev/ttys002","serial":"E2E-2"},{"path":7},null]'
const { discover } = testDialDiscovery('/tmp/dials.json', () => listed)
expect((await discover!()).map((port) => [port.path, port.serialNumber])).toEqual([['/dev/ttys001', 'E2E-1'], ['/dev/ttys002', 'E2E-2']])
listed = '{"not": "a list"}'
expect(await discover!()).toEqual([])
listed = 'half a file'
expect(await discover!()).toEqual([])
})
})
describe('one dial failing', () => {
it('is dropped alone after five faults, its port looked at again after a wait, while the other dial goes on', async () => {
const f = fixture({ faults: new Set(['dial.AA:01']), dropBackoffMs: 300 })
const scan = () => (f.fleet as unknown as { scan(): Promise<void> }).scan()
try {
f.fleet.start()
await vi.waitFor(() => expect(f.ports).toHaveLength(2))
const [faulty, healthy] = f.ports
await f.greet([healthy])
// Every greeting the faulty dial sends fails in its session, as its firmware greets on a cadence.
for (let i = 0; i < 5; i++) faulty.say({ t: 'hello', product: 'harness', mac: faulty.path, fw: 'fixture', proto: 3 })
await vi.waitFor(() => expect(faulty.isOpen).toBe(false))
expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/cable: \/dev\/tim dropped \(5 faults in a minute: injected fault: dial\.AA:01\) — this dial alone; its port is looked at again in 0 s \[usb AA:01\]/))
// The other dial is untouched: still attached, still told the desk's work.
expect(healthy.isOpen).toBe(true)
healthy.sent.length = 0
await f.fleet.turnStarted('a', 'working')
await vi.waitFor(() => expect(healthy.sent.some((m) => m.t === 'turn.started')).toBe(true))
expect(f.fleet.isConnected).toBe(true)
// Not before its wait is over; then it is opened again.
await scan()
expect(f.ports).toHaveLength(2)
await new Promise((resolve) => setTimeout(resolve, 350))
await scan()
expect(f.ports).toHaveLength(3)
} finally { await f.fleet.stop() }
})
it('is dropped at once when it floods the port with what no dial sends, and waits longer each time it does again', async () => {
const f = fixture({ dropBackoffMs: 100 })
const scan = () => (f.fleet as unknown as { scan(): Promise<void> }).scan()
try {
await f.start()
const [flooding, healthy] = f.ports
flooding.raw(Buffer.alloc(70 * 1024, 0x41))
await vi.waitFor(() => expect(flooding.isOpen).toBe(false))
expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/cable: flooded · 716\d\d B that are no frames in a second, more than a dial sends/))
expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/\/dev\/tim dropped \(flooding the port: .*\) — this dial alone; its port is looked at again in 0 s/))
expect(healthy.isOpen).toBe(true)
await new Promise((resolve) => setTimeout(resolve, 150))
await scan()
expect(f.ports).toHaveLength(3)
// Again, soon after: the wait doubles.
f.ports[2].raw(Buffer.alloc(70 * 1024, 0x41))
await vi.waitFor(() => expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/\/dev\/tim dropped .* looked at again in 0 s/)))
await vi.waitFor(() => expect(f.ports[2].isOpen).toBe(false))
await new Promise((resolve) => setTimeout(resolve, 120))
await scan()
expect(f.ports).toHaveLength(3)
await new Promise((resolve) => setTimeout(resolve, 150))
await scan()
expect(f.ports).toHaveLength(4)
} finally { await f.fleet.stop() }
})
it('is dropped for a flood of frames, or for frames that take the decoder too long', async () => {
const f = fixture({ dropBackoffMs: 60_000 })
try {
await f.start()
const [chatty, healthy] = f.ports
const ping = Buffer.from(encodeCableFrame(CableType.Json, Buffer.from('{"t":"pong"}')))
chatty.raw(Buffer.concat(Array.from({ length: 2_100 }, () => ping)))
await vi.waitFor(() => expect(chatty.isOpen).toBe(false))
expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/\d{4} frames in a second, more than a dial sends/))
expect(healthy.isOpen).toBe(true)
const budget = CableSession.BUDGET.decodeMs
;(CableSession.BUDGET as { decodeMs: number }).decodeMs = -1
try {
healthy.say({ t: 'pong' })
await vi.waitFor(() => expect(healthy.isOpen).toBe(false))
expect(f.host.log).toHaveBeenCalledWith(expect.stringMatching(/ms of decoding in a second/))
} finally { (CableSession.BUDGET as { decodeMs: number }).decodeMs = budget }
} finally { await f.fleet.stop() }
})
it('keeps its own fault when what it sends throws as it is read, and the process goes on', async () => {
class ThrowingLog extends DialLog { device(): void { throw new Error('the log could not be written') } }
const f = fixture({ dropBackoffMs: 60_000 }, ThrowingLog)
try {
await f.start()
const [noisy, quiet] = f.ports
for (let i = 0; i < 5; i++) noisy.raw(Buffer.from(encodeCableFrame(CableType.Log, Buffer.from('I (12) boot: line'))))
await vi.waitFor(() => expect(noisy.isOpen).toBe(false))
expect(f.host.log).toHaveBeenCalledWith(expect.stringContaining('cable: fault · the log could not be written'))
expect(quiet.isOpen).toBe(true)
} finally { await f.fleet.stop() }
})
})
describe('USB dial fleet', () => {
it('releases every dial on a macOS user switch and reconnects only when its account returns', async () => {
const f = fixture()
const scan = () => (f.fleet as unknown as { scan(): Promise<void> }).scan()
try {
f.options.canUseUsb.mockReturnValue(false)
f.fleet.start()
await scan()
expect(f.options.discover).not.toHaveBeenCalled()
expect(f.ports).toHaveLength(0)
f.options.canUseUsb.mockReturnValue(true)
await scan()
await vi.waitFor(() => expect(f.ports).toHaveLength(2))
await f.greet(f.ports)
expect(f.fleet.isConnected).toBe(true)
f.options.canUseUsb.mockReturnValue(false)
await scan()
expect(f.ports.every(port => !port.isOpen)).toBe(true)
expect(f.fleet.isConnected).toBe(false)
const discoveries = f.options.discover.mock.calls.length
await scan()
expect(f.options.discover).toHaveBeenCalledTimes(discoveries)
f.options.canUseUsb.mockReturnValue(true)
await scan()
await vi.waitFor(() => expect(f.ports).toHaveLength(4))
await f.greet(f.ports.slice(2))
expect(f.fleet.isConnected).toBe(true)
} finally { await f.fleet.stop() }
})
it('closes an opening port if the desktop account changes before open finishes', async () => {
const f = fixture()
f.setPorts([device('/dev/tim', 'AA:01')])
let finish!: () => void
f.options.open.mockImplementationOnce(async (path, onData, onClosed) => {
const peer = new Peer(path, onData, onClosed)
f.ports.push(peer)
await new Promise<void>(resolve => { finish = resolve })
return peer
})
try {
f.fleet.start()
await vi.waitFor(() => expect(f.ports).toHaveLength(1))
f.options.canUseUsb.mockReturnValue(false)
finish()
await vi.waitFor(() => expect(f.ports[0].isOpen).toBe(false))
expect(f.fleet.isConnected).toBe(false)
} finally { finish?.(); await f.fleet.stop() }
})
it('names every device on the desk, and changes the settings of ONE of them', async () => {
/*
* Before this the fleet picked a row and threw the rest away, so the app drew one robot however
* many were plugged in — and a preference had nowhere to be addressed to.
*
* Every other command here broadcasts ON PURPOSE: both devices show the same desktop. A setting
* does not, because it belongs to the glass it was set on.
*/
const f = fixture()
try {
await f.start()
const settings = {
brightness: 60, character: 0, face: 466, muted: false, quiet: false, straightTitle: false,
focusFace: false, scrollReversed: false, round: true, voiceLang: 'vi',
}
for (const port of f.ports) {
port.say({ t: 'hello', product: 'harness', mac: port.path, fw: 'fixture', proto: 3, settings })
}
await vi.waitFor(() => expect(f.fleet.devices().filter(d => d.settings)).toHaveLength(2))
expect(f.fleet.devices().map(d => d.id)).toEqual(['AA:01', 'BB:02'])
expect(f.fleet.devices().map(d => d.mac)).toEqual(['/dev/tim', '/dev/tux'])
for (const device of f.fleet.devices()) expect(device.settings).toEqual(settings)
// The whole desk rides on the status a window receives, with one row repeated flat.
expect(f.host.onDialStatus).toHaveBeenLastCalledWith(
expect.objectContaining({ attached: true, devices: expect.arrayContaining([expect.objectContaining({ id: 'BB:02' })]) }))
for (const port of f.ports) port.sent.length = 0
expect(await f.fleet.setSettings('BB:02', { brightness: 20 })).toEqual({ ok: true })
await vi.waitFor(() => expect(f.ports[1].sent).toContainEqual({ t: 'settings.set', brightness: 20 }))
expect(f.ports[0].sent).toHaveLength(0) // the other robot was not touched
expect(await f.fleet.setSettings('ZZ:99', { muted: true }))
.toEqual({ ok: false, error: 'That device is not plugged into this computer.' })
} finally { await f.fleet.stop() }
})
it('keeps an unplugged device on the desk, with what it last held', async () => {
// A pane that emptied the moment a cable was pulled would be a pane nobody could read their own
// settings out of. Read-only is the app's job; keeping the row is this one's.
const f = fixture()
try {
await f.start()
const settings = {
brightness: 40, character: 1, face: 466, muted: true, quiet: true, straightTitle: true,
focusFace: false, scrollReversed: true, round: false, voiceLang: 'en',
}
f.ports[0].say({ t: 'hello', product: 'harness', mac: '/dev/tim', fw: 'fixture', proto: 3, settings })
await vi.waitFor(() => expect(f.fleet.devices()[0]?.settings).toEqual(settings))
await f.ports[0].close('unplugged')
await vi.waitFor(() => expect(f.fleet.devices()[0]?.attached).toBe(false))
expect(f.fleet.devices()[0]).toMatchObject({ id: 'AA:01', attached: false, settings })
expect(await f.fleet.setSettings('AA:01', { muted: false }))
.toEqual({ ok: false, error: 'That device is unplugged.' })
} finally { await f.fleet.stop() }
})
it('connects both dials, broadcasts work, and keeps the remaining dial attached', async () => {
const f = fixture()
try {
await f.start(); f.fleet.start(); await f.fleet['scan']()
expect(f.options.open).toHaveBeenCalledTimes(2)
expect(f.host.onDialAttached).toHaveBeenCalledTimes(1)
await f.fleet.turnStarted('a', 'Working')
for (const port of f.ports) expect(port.sent).toContainEqual({ t: 'turn.started', agentId: 'a', text: 'Working' })
// The Swarm cards reach every session; a dial that did not name them is sent nothing.
await f.fleet.syncSwarmCards(true)
await f.fleet.swarmCardRecap({ tabId: 'st1', leadId: 'l1', text: 'x', at: 1, none: false })
for (const port of f.ports) expect(port.sent.some(m => String(m.t).startsWith('supertab'))).toBe(false)
f.setPorts([device('/dev/tux', 'BB:02')]); await f.fleet['scan']()
expect(f.ports[0].isOpen).toBe(false)
expect(f.ports[1].isOpen).toBe(true)
expect(f.fleet.isConnected).toBe(true)
expect(f.host.onDialGone).not.toHaveBeenCalled()
expect(f.host.onDialStatus).toHaveBeenLastCalledWith(expect.objectContaining({ attached: true }))
await f.fleet.turnDone('a')
expect(f.ports[1].sent.some(m => m.t === 'turn.done')).toBe(true)
await vi.waitFor(() => expect(readdirSync(f.logs).sort()).toEqual(['usb-AA-01', 'usb-BB-02']))
f.setPorts([]); await f.fleet['scan']()
expect(f.fleet.isConnected).toBe(false)
expect(f.host.onDialGone).toHaveBeenCalledTimes(1)
expect(f.host.onDialStatus).toHaveBeenLastCalledWith({ attached: false, devices: [] })
} finally { await f.fleet.stop() }
})
it('keeps simultaneous voice uploads separate even with the same upload id', async () => {
const f = fixture()
try {
await f.start()
for (const p of f.ports) p.say({ t: 'voice.begin', uploadId: 'same', agentId: 'a' })
f.ports[0].pcm(17); f.ports[1].pcm(34)
for (const p of f.ports) p.say({ t: 'voice.end' })
await vi.waitFor(() => expect(f.host.sendTurn).toHaveBeenCalledTimes(2))
const audio = vi.mocked(f.host.transcribe).mock.calls.map(c => c[0])
expect(audio.map(b => [b.length, b[0]])).toEqual([[3200, 17], [3200, 34]])
expect(audio.every(b => b.every(v => v === b[0]))).toBe(true)
for (const [i, p] of f.ports.entries()) {
expect(p.sent.some(m => m.t === 'voice.transcript' && m.text === `audio-${i ? 34 : 17}`)).toBe(true)
}
} finally { await f.fleet.stop() }
})
it('does not cancel the other dial while its transcription is pending', async () => {
const f = fixture(); let finish!: (text: string) => void
vi.mocked(f.host.transcribe).mockImplementation(() => new Promise(resolve => { finish = resolve }))
try {
await f.start()
f.ports[1].say({ t: 'voice.begin', uploadId: 'pending', agentId: 'a' }); f.ports[1].pcm(42)
f.ports[1].say({ t: 'voice.end' })
await vi.waitFor(() => expect(f.host.transcribe).toHaveBeenCalledTimes(1))
f.setPorts([device('/dev/tux', 'BB:02')]); await f.fleet['scan']()
finish('keep recording')
await vi.waitFor(() => expect(f.host.sendTurn).toHaveBeenCalledWith('a', 'keep recording'))
expect(f.host.onDialGone).not.toHaveBeenCalled()
} finally { await f.fleet.stop() }
})
it('preserves healthy sessions when discovery fails and replaces a moved USB path', async () => {
const f = fixture()
try {
await f.start()
f.options.discover.mockRejectedValueOnce(new Error('inventory unavailable'))
await f.fleet['scan'](); expect(f.ports.every(p => p.isOpen)).toBe(true)
f.setPorts([device('/dev/tim-new', 'AA:01'), device('/dev/tux', 'BB:02')])
await f.fleet['scan'](); await vi.waitFor(() => expect(f.ports).toHaveLength(3))
await f.greet([f.ports[2]])
expect(f.ports[0].isOpen).toBe(false); expect(f.ports[1].isOpen).toBe(true)
expect(f.ports[2].path).toBe('/dev/tim-new')
expect(f.host.onDialGone).not.toHaveBeenCalled()
expect(f.host.onDialAttached).toHaveBeenCalledTimes(1)
} finally { await f.fleet.stop() }
})
it('opens only selected serial numbers', async () => {
const f = fixture()
const fleet = new CableFleet(CableSession, f.host, f.logs, DialLog, { ...f.options, serials: ['bb:02'] })
try {
fleet.start(); await fleet['scan']()
await vi.waitFor(() => expect(f.ports).toHaveLength(1))
expect(f.ports[0].path).toBe('/dev/tux')
} finally { await fleet.stop() }
})
it('closes a port that finishes opening after shutdown', async () => {
const f = fixture(); let finish!: (port: Peer) => void; let late!: Peer
f.setPorts([device('/dev/tim', 'AA:01')])
f.options.open.mockImplementation((path, onData, onClosed) => {
late = new Peer(path, onData, onClosed)
return new Promise(resolve => { finish = resolve })
})
try {
f.fleet.start(); await vi.waitFor(() => expect(late).toBeDefined())
await f.fleet.stop(); finish(late)
await vi.waitFor(() => expect(late.isOpen).toBe(false))
expect(f.fleet.isConnected).toBe(false)
expect(f.host.onDialAttached).not.toHaveBeenCalled()
} finally { await f.fleet.stop() }
})
})
describe('a board that is not a dial', () => {
it('reopens only the successfully flashed board after a stopped daemon missed the flash and USB attachment stayed the same', async () => {
const directory = mkdtempSync(join(tmpdir(), 'fleet-flash-recovery-'))
const file = join(directory, 'dial-ports.json')
const a = { ...device('COM3', 'FLASH-A'), session: 'unchanged-a' }
const b = { ...device('COM4', 'OTHER-B'), session: 'unchanged-b' }
const previous = new DialVerdicts(file)
previous.markForeign(a); previous.markForeign(b)
// No fleet runs during the write, so it cannot observe a busy -> free edge.
await completeFlash('COM3', { verdictFile: file, findPorts: async () => [a, b], stopDiscovery: () => {} })
const f = fixture({ verdicts: new DialVerdicts(file) })
f.setPorts([a, b])
try {
f.fleet.start()
await vi.waitFor(() => expect(f.ports.map(port => port.path)).toEqual(['COM3']))
await f.greet(f.ports)
expect(f.fleet.isConnected).toBe(true)
expect(new DialVerdicts(file).isForeign(b)).toBe(true)
} finally { await f.fleet.stop(); rmSync(directory, { recursive: true, force: true }) }
})
/**
* Found on a desk with a second ESP32-S3 plugged in for its own work: it shares the dial's USB ids, so
* the daemon opened it, heard nothing it understood, waited a minute and opened it again, for as long
* as it ran. That corrupted an esptool flash read twice. A board is looked at once per attachment.
*/
const scenario = (opts: { inUse?: (path: string) => Promise<boolean>; file?: string } = {}) => {
const f = fixture()
const foreign = { ...device('/dev/other', 'CC:03'), session: '100' }
const dial = { ...device('/dev/tim', 'AA:01'), session: '200' }
f.setPorts([foreign, dial])
const options = { ...f.options, verdicts: new DialVerdicts(opts.file), watchEveryMs: 0, ...(opts.inUse ? { inUse: opts.inUse } : { inUse: async () => false }) }
const fleet = new CableFleet(CableSession, f.host, f.logs, DialLog, options)
const opens = () => f.options.open.mock.calls.map(c => c[0])
const scan = async () => { await (fleet as unknown as { scan(): Promise<void> }).scan(); await new Promise(r => setTimeout(r, 5)) }
return { f, fleet, foreign, dial, options, opens, scan }
}
it('is probed once, then left alone, while the dial beside it carries on', async () => {
const s = scenario()
try {
s.fleet.start()
await vi.waitFor(() => expect(s.f.ports).toHaveLength(2))
const other = s.f.ports.find(p => p.path === '/dev/other')!
const tim = s.f.ports.find(p => p.path === '/dev/tim')!
other.say({ t: 'hello', product: 'grid', mac: 'other', fw: '1', proto: 1 })
await s.f.greet([tim])
await vi.waitFor(() => expect(other.isOpen).toBe(false))
const after = s.opens().filter(p => p === '/dev/other').length
for (let i = 0; i < 4; i++) await s.scan()
expect(s.opens().filter(p => p === '/dev/other').length).toBe(after)
expect(tim.isOpen).toBe(true)
expect(s.f.host.log).toHaveBeenCalledWith(expect.stringContaining('leaving it alone until it is unplugged or reset'))
} finally { await s.fleet.stop() }
})
it('is looked at again once it has been unplugged and plugged back in', async () => {
const s = scenario()
try {
s.fleet.start()
await vi.waitFor(() => expect(s.f.ports).toHaveLength(2))
s.f.ports.find(p => p.path === '/dev/other')!.say({ t: 'hello', product: 'grid', mac: 'other', fw: '1', proto: 1 })
await vi.waitFor(() => expect(s.f.ports.find(p => p.path === '/dev/other')!.isOpen).toBe(false))
const before = s.opens().filter(p => p === '/dev/other').length
// Unplugged and plugged back in: same board, new attachment.
s.f.setPorts([{ ...s.foreign, session: '101' }, s.dial])
// Scanning as the interval would: the old entry leaves on a timer of its own, so the first scan
// may still find it there and the next one starts the new attachment.
await vi.waitFor(async () => {
await s.scan()
expect(s.opens().filter(p => p === '/dev/other').length).toBeGreaterThan(before)
}, { timeout: 5000 })
} finally { await s.fleet.stop() }
})
it('is looked at again once a program has worked on it and let go, which is what a flash looks like', async () => {
// A reset or a reflash over USB-Serial/JTAG leaves the attachment as it was (measured with esptool on
// the desk), so the USB view cannot say a board became a dial. Somebody holding its port for a while,
// and then not, can: that is esptool or idf.py. The board is looked at once more when they let go.
let busy = false
const s = scenario({ inUse: async path => path === '/dev/other' && busy })
try {
s.fleet.start()
await vi.waitFor(() => expect(s.f.ports).toHaveLength(2))
s.f.ports.find(p => p.path === '/dev/other')!.say({ t: 'hello', product: 'grid', mac: 'other', fw: '1', proto: 1 })
await vi.waitFor(() => expect(s.f.ports.find(p => p.path === '/dev/other')!.isOpen).toBe(false))
const before = s.opens().filter(p => p === '/dev/other').length
// Still ruled out while nothing has touched it, and while it is being worked on.
for (let i = 0; i < 3; i++) await s.scan()
busy = true
for (let i = 0; i < 3; i++) await s.scan()
expect(s.opens().filter(p => p === '/dev/other').length).toBe(before)
// They let go: it may be a different board now.
busy = false
await vi.waitFor(async () => {
await s.scan()
expect(s.opens().filter(p => p === '/dev/other').length).toBeGreaterThan(before)
}, { timeout: 5000 })
expect(s.f.host.log).toHaveBeenCalledWith(expect.stringContaining('was in use and is free again'))
} finally { await s.fleet.stop() }
})
it('is not probed again by the next daemon either', async () => {
const file = join(mkdtempSync(join(tmpdir(), 'fleet-verdicts-')), 'dial-ports.json')
const first = scenario({ file })
try {
first.fleet.start()
await vi.waitFor(() => expect(first.f.ports).toHaveLength(2))
first.f.ports.find(p => p.path === '/dev/other')!.say({ t: 'hello', product: 'grid', mac: 'other', fw: '1', proto: 1 })
await vi.waitFor(() => expect(first.f.ports.find(p => p.path === '/dev/other')!.isOpen).toBe(false))
} finally { await first.fleet.stop() }
const second = scenario({ file })
try {
second.fleet.start()
await vi.waitFor(() => expect(second.opens()).toContain('/dev/tim'))
for (let i = 0; i < 3; i++) await second.scan()
expect(second.opens()).not.toContain('/dev/other')
} finally { await second.fleet.stop() }
})
it('remembers a board that greeted as a dial, so a later silent probe never marks it foreign', async () => {
const file = join(mkdtempSync(join(tmpdir(), 'fleet-verdicts-')), 'dial-ports.json')
const s = scenario({ file })
try {
s.fleet.start()
await vi.waitFor(() => expect(s.f.ports.map(p => p.path)).toContain('/dev/tim'))
await s.f.greet(s.f.ports.filter(p => p.path === '/dev/tim'))
await vi.waitFor(() => expect(s.fleet.isConnected).toBe(true))
} finally { await s.fleet.stop() }
const dial = { ...device('/dev/tim', 'AA:01'), session: '201' }
const verdicts = new DialVerdicts(file)
verdicts.markForeign(dial)
expect(verdicts.isForeign(dial)).toBe(false)
})
it('is never opened while another program has it, and only then once that program is done', async () => {
let busy = true
const s = scenario({ inUse: async path => path === '/dev/other' && busy })
try {
s.fleet.start()
await vi.waitFor(() => expect(s.opens()).toContain('/dev/tim'))
for (let i = 0; i < 3; i++) await s.scan()
expect(s.opens()).not.toContain('/dev/other')
expect(s.f.host.log).toHaveBeenCalledWith(expect.stringContaining('/dev/other is in use by another program'))
busy = false
await s.scan()
await vi.waitFor(() => expect(s.opens()).toContain('/dev/other'))
} finally { await s.fleet.stop() }
})
it('reads a port as held when a process other than this one has it open', async () => {
// Skipped without lsof; the fleet treats "cannot tell" as free, so there is nothing to prove there.
const file = join(mkdtempSync(join(tmpdir(), 'held-')), 'tty')
writeFileSync(file, '')
const holder = spawn('tail', ['-f', file], { stdio: 'ignore' })
try {
await new Promise(r => setTimeout(r, 300))
const held = await portInUse(file)
const lsofExists = await new Promise<boolean>(r => spawn('lsof', ['-v'], { stdio: 'ignore' }).on('error', () => r(false)).on('exit', () => r(true)))
if (lsofExists) expect(held).toBe(true)
} finally {
holder.kill()
await new Promise(r => holder.on('exit', r))
}
expect(await portInUse(file)).toBe(false)
})
})
describe('macOS USB inventory', () => {
it('reads multiple USB-rooted subtrees without leaking IDs into their siblings', () => {
const dump = `+-o Tim <class IOUSBHostDevice>
"idVendor" = 12346
"idProduct" = 4097
"USB Serial Number" = "AA:01"
+-o CDC
+-o serial
"IOCalloutDevice" = "/dev/tim"
+-o unrelated <class IOUSBHostDevice>
"idVendor" = 12346
"idProduct" = 12
+-o serial
"IOCalloutDevice" = "/dev/unrelated"
+-o Tux <class IOUSBHostDevice>
"USB Serial Number" = "BB:02"
"idProduct" = 4097
"idVendor" = 12346
+-o serial
"IOCalloutDevice" = "/dev/tux"`
expect(parseDarwinDialPorts(dump)).toEqual([device('/dev/tim', 'AA:01'), device('/dev/tux', 'BB:02')])
expect(parseDarwinDialPorts('')).toEqual([])
})
it('associates each tty with its own matching USB parent and serial in either property order', () => {
const dump = `+-o root
+-o Tim
"USB Serial Number" = "AA:01"
"idProduct" = 4097
"idVendor" = 12346
+-o driver
+-o serial
"IOCalloutDevice" = "/dev/tim"
"IOCalloutDevice" = "/dev/tim"
+-o unrelated
"idVendor" = 12346
"idProduct" = 12
+-o serial
"IOCalloutDevice" = "/dev/unrelated"
+-o Tux
"idVendor" = 12346
"idProduct" = 4097
"sessionID" = 14351572441873
"USB Serial Number" = "BB:02"
+-o serial
"sessionID" = 99
"IOCalloutDevice" = "/dev/tux"
+-o console
"IOCalloutDevice" = "/dev/debug-console"`
// The attachment identity is the USB device's own sessionID, not one from a node below it.
expect(parseDarwinDialPorts(dump)).toEqual([device('/dev/tim', 'AA:01'), { ...device('/dev/tux', 'BB:02'), session: '14351572441873' }])
})
describe('dial scan gate', () => {
const dump = `+-o Tim <class IOUSBHostDevice>
"idVendor" = 12346
"idProduct" = 4097
"USB Serial Number" = "AA:01"
+-o CDC
+-o serial
"IOCalloutDevice" = "/dev/cu.usbmodem1101"`
const base = ['cu.debug-console:623:1', 'cu.usbmodem1101:900:7']
function rig(entries = base) {
const state = { entries, now: 0, listDev: () => state.entries }
const runIoreg = vi.fn(async () => dump)
const find = createDarwinDialFinder({ listDev: () => state.listDev(), runIoreg, now: () => state.now })
return { state, runIoreg, find }
}
it('runs ioreg once for an unchanged /dev set and serves copies', async () => {
const { runIoreg, find } = rig()
for (let i = 0; i < 3; i++) expect(await find()).toEqual([device('/dev/cu.usbmodem1101', 'AA:01')])
expect(runIoreg).toHaveBeenCalledTimes(1)
const first = await find()
first[0].path = 'x'
expect(await find()).toEqual([device('/dev/cu.usbmodem1101', 'AA:01')])
})
it('ignores the order of /dev entries', async () => {
const { state, runIoreg, find } = rig()
await find()
state.entries = [...base].reverse()
await find()
expect(runIoreg).toHaveBeenCalledTimes(1)
})
it('rescans on an added or removed entry, a new inode, or a new rdev', async () => {
const { state, runIoreg, find } = rig()
await find()
state.entries = [...base, 'cu.usbmodem2:950:8']; await find()
expect(runIoreg).toHaveBeenCalledTimes(2)
state.entries = base; await find()
expect(runIoreg).toHaveBeenCalledTimes(3)
state.entries = ['cu.debug-console:623:1', 'cu.usbmodem1101:901:7']; await find()
expect(runIoreg).toHaveBeenCalledTimes(4)
state.entries = ['cu.debug-console:623:1', 'cu.usbmodem1101:901:8']; await find()
expect(runIoreg).toHaveBeenCalledTimes(5)
await find() // the confirm scan after the last change
expect(runIoreg).toHaveBeenCalledTimes(6)
await find()
expect(runIoreg).toHaveBeenCalledTimes(6)
})
it('confirms a change with one more scan, so a plug edge cannot cache a half-seen port', async () => {
const { state, runIoreg, find } = rig()
await find()
state.entries = [...base, 'cu.usbmodem2:950:8']
runIoreg.mockResolvedValueOnce('') // devfs has the node, the IORegistry does not yet
expect(await find()).toEqual([])
expect(await find()).toEqual([device('/dev/cu.usbmodem1101', 'AA:01')])
expect(runIoreg).toHaveBeenCalledTimes(3)
await find()
expect(runIoreg).toHaveBeenCalledTimes(3)
})
it('rescans after 5 minutes, not before', async () => {
const { state, runIoreg, find } = rig()
await find()
state.now = 299_999; await find()
expect(runIoreg).toHaveBeenCalledTimes(1)
state.now = 300_000; await find()
expect(runIoreg).toHaveBeenCalledTimes(2)
state.now = 300_001; await find()
expect(runIoreg).toHaveBeenCalledTimes(2)
})
it('rescans when the clock steps back below the last scan', async () => {
const { state, runIoreg, find } = rig()
state.now = 1_000_000; await find()
state.now = 500_000; await find()
expect(runIoreg).toHaveBeenCalledTimes(2)
})
it('treats an empty /dev/cu.* set as a valid fingerprint', async () => {
const { runIoreg, find } = rig([])
runIoreg.mockResolvedValue('') // no cu.* nodes, so no dial in the IORegistry either
for (let i = 0; i < 3; i++) await find()
expect(runIoreg).toHaveBeenCalledTimes(1)
})
it('keeps rescanning while ioreg lists a port whose /dev node is gone, then caches again', async () => {
const { state, runIoreg, find } = rig()
await find()
state.entries = ['cu.debug-console:623:1'] // unplugged: the node left /dev, the IORegistry still lists the dial
for (let i = 0; i < 3; i++) expect(await find()).toEqual([device('/dev/cu.usbmodem1101', 'AA:01')])
expect(runIoreg).toHaveBeenCalledTimes(4)
runIoreg.mockResolvedValue('') // the IORegistry caught up
expect(await find()).toEqual([])
expect(runIoreg).toHaveBeenCalledTimes(5)
await find()
await find()
expect(runIoreg).toHaveBeenCalledTimes(5) // nothing left to doubt, so cached
})
it('retries after an ioreg failure and never serves stale ports for changed entries', async () => {
const { state, runIoreg, find } = rig()
runIoreg.mockRejectedValueOnce(new Error('Could not enumerate USB dials'))
await expect(find()).rejects.toThrow('Could not enumerate USB dials')
expect(await find()).toEqual([device('/dev/cu.usbmodem1101', 'AA:01')])
expect(runIoreg).toHaveBeenCalledTimes(2)
state.entries = [...base, 'cu.usbmodem2:950:8']
runIoreg.mockRejectedValueOnce(new Error('Could not enumerate USB dials'))
await expect(find()).rejects.toThrow('Could not enumerate USB dials')
await find()
expect(runIoreg).toHaveBeenCalledTimes(4)
await find() // confirm scan for the change that the failure interrupted
expect(runIoreg).toHaveBeenCalledTimes(5)
await find()
expect(runIoreg).toHaveBeenCalledTimes(5)
})
it('falls back to ioreg every call while /dev cannot be read', async () => {
const { state, runIoreg, find } = rig()
state.listDev = () => { throw new Error('EACCES') }
for (let i = 0; i < 3; i++) await find()
expect(runIoreg).toHaveBeenCalledTimes(3)
state.listDev = () => state.entries
await find()
expect(runIoreg).toHaveBeenCalledTimes(4)
await find() // recovery counts as a change, so it is confirmed once
expect(runIoreg).toHaveBeenCalledTimes(5)
await find()
expect(runIoreg).toHaveBeenCalledTimes(5)
})
})
})
describe('a Harness Pro that is silent from the moment its port opens', () => {
// A user's Pro, started beside a booting Mac, sent nothing at all on 20-26 Oct: the daemon wrote it off as
// "not a Harness dial" and the Pro sat on its Home screen until it was replugged. This session stands in for
// CableSession's 20 s silence (tested there) so each step is one call.
class Quiet {
static made: Quiet[] = []
isConnected = false
wantsStats = false
constructor(readonly host: CableHost) { Quiet.made.push(this) }
start() {}
async stop() {}
petDial() { return { supported: false, held: [], sending: null, errors: {} } }
silent() { this.host.onForeignPort?.('/dev/pro', 'silent') }
}
const PRO = 'E8:F6:0A:E7:63:7D'
const NOTICE = 'Not answering — unplug and replug'
function setup(opts: { verdicts?: DialVerdicts; session?: string; serial?: string } = {}) {
Quiet.made = []
const f = fixture()
const port = { ...device('/dev/pro', opts.serial ?? PRO), session: opts.session ?? '7' }
f.setPorts([port])
const reset = vi.fn(async () => true)
const verdicts = opts.verdicts ?? new DialVerdicts()
const fleet = new CableFleet(Quiet as unknown as typeof CableSession, f.host, f.logs, DialLog, { ...f.options, verdicts, watchEveryMs: 0, reset })
const scan = async () => { await (fleet as unknown as { scan(): Promise<void> }).scan(); await new Promise(r => setTimeout(r, 5)) }
const rows = () => (vi.mocked(f.host.onDialStatus!).mock.calls.at(-1)?.[0].devices ?? [])
return { f, fleet, port, reset, verdicts, scan, rows }
}
it('is reset over the cable once, watched again, and only then is the person told', async () => {
const s = setup()
s.verdicts.markDial(s.port, 'pro')
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.reset).toHaveBeenCalledWith('/dev/pro'))
// Looked at again, by a fresh session, after the reset.
await vi.waitFor(async () => { await s.scan(); expect(Quiet.made).toHaveLength(2) })
expect(s.rows()).toEqual([])
Quiet.made[1].silent()
await vi.waitFor(() => expect(s.rows()).toEqual([{ id: PRO, attached: false, board: 'pro', problem: NOTICE }]))
// Exactly one reset, and the port is then left alone for this attachment.
for (let i = 0; i < 3; i++) await s.scan()
expect(s.reset).toHaveBeenCalledTimes(1)
expect(Quiet.made).toHaveLength(2)
expect(s.verdicts.isForeign(s.port)).toBe(false)
// Replugged: a new attachment is looked at again, and the notice goes.
s.f.setPorts([{ ...s.port, session: '8' }])
await vi.waitFor(async () => { await s.scan(); expect(Quiet.made).toHaveLength(3) })
expect(s.rows()).toEqual([])
} finally { await s.fleet.stop() }
})
it('is told to the person at once where the board cannot be reset', async () => {
const s = setup()
s.verdicts.markDial(s.port, 'pro')
s.reset.mockResolvedValue(false)
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.rows()).toEqual([{ id: PRO, attached: false, board: 'pro', problem: NOTICE }]))
for (let i = 0; i < 3; i++) await s.scan()
expect(Quiet.made).toHaveLength(1)
} finally { await s.fleet.stop() }
})
it('is never reset when its port has no USB serial, since only a serial says which board it is: notice only', async () => {
const s = setup()
const nameless = { path: '/dev/pro', vendorId: 0x303a, productId: 0x1001, session: '7' }
s.f.setPorts([nameless])
s.verdicts.markDial(nameless, 'pro')
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.rows()).toEqual([{ id: '/dev/pro', attached: false, board: 'pro', problem: NOTICE }]))
expect(s.reset).not.toHaveBeenCalled()
} finally { await s.fleet.stop() }
})
it('is not reset when the daemon stops or USB passes to another account just before the reset', async () => {
for (const change of ['usb', 'stop'] as const) {
const s = setup()
s.verdicts.markDial(s.port, 'pro')
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
// The change lands while the silent session is being stopped, after the decision to reset.
Quiet.made[0].stop = async () => {
if (change === 'usb') s.f.options.canUseUsb.mockReturnValue(false)
else void s.fleet.stop()
}
Quiet.made[0].silent()
await new Promise(r => setTimeout(r, 50))
expect(s.reset).not.toHaveBeenCalled()
} finally { await s.fleet.stop() }
}
})
it('withdraws a notice it has shown when the second silent round is given up, and says so to the window', async () => {
const s = setup()
s.verdicts.markDial(s.port, 'pro')
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(async () => { await s.scan(); expect(Quiet.made).toHaveLength(2) })
// Stopping the second, still silent, session reports it gone, which publishes the notice; then USB passes
// to another account before the notice is settled.
Quiet.made[1].stop = async () => {
Quiet.made[1].host.onDialStatus?.({ attached: false })
s.f.options.canUseUsb.mockReturnValue(false)
}
Quiet.made[1].silent()
await vi.waitFor(() => expect(vi.mocked(s.f.host.onDialStatus!).mock.calls.some(([st]) => st.devices?.some(d => d.problem))).toBe(true))
await new Promise(r => setTimeout(r, 50))
expect(s.rows()).toEqual([])
} finally { await s.fleet.stop() }
})
it('withdraws its notice when USB passes to another account at this computer', async () => {
const s = setup()
s.verdicts.markDial(s.port, 'pro')
s.reset.mockResolvedValue(false)
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.rows()).toEqual([{ id: PRO, attached: false, board: 'pro', problem: NOTICE }]))
s.f.options.canUseUsb.mockReturnValue(false)
await s.scan()
expect(s.rows()).toEqual([])
} finally { await s.fleet.stop() }
})
it('never resets a silent board this computer has not seen greet as a Harness Pro', async () => {
for (const known of ['nothing', 'round dial'] as const) {
const s = setup({ serial: 'CC:03' })
if (known === 'round dial') s.verdicts.markDial(s.port)
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.f.host.log).toHaveBeenCalledWith(expect.stringContaining('is not a Harness dial (silent)')))
await s.scan()
expect(s.reset).not.toHaveBeenCalled()
expect(s.rows().some(r => r.problem)).toBe(false)
} finally { await s.fleet.stop() }
}
})
it('is known from its own dial log when it greeted before the record kept the board, so a verdict does not pin it', async () => {
// This user's Pro: last greeted a daemon older than the board record, then judged foreign on this very
// attachment, which held for 6 h and across every restart.
const file = join(mkdtempSync(join(tmpdir(), 'fleet-verdicts-')), 'dial-ports.json')
const pinned = new DialVerdicts(file)
const s = setup({ verdicts: pinned })
pinned.markForeign(s.port)
const folder = join(s.f.logs, 'usb-E8-F6-0A-E7-63-7D')
mkdirSync(folder)
writeFileSync(join(folder, 'dial-20261022.log'), '2026-10-22T09:49:09.860Z [daemon] dial E8:F6:0A:E7:63:7D on fw 0.1.13 proto 3 hw harness-pro board pro caps swarms\n')
try {
s.fleet.start()
await vi.waitFor(() => expect(Quiet.made).toHaveLength(1))
expect(new DialVerdicts(file).isPro(s.port)).toBe(true)
Quiet.made[0].silent()
await vi.waitFor(() => expect(s.reset).toHaveBeenCalledTimes(1))
} finally { await s.fleet.stop() }
})
})