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 { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import { b64e, newIdentity, sign } from '../lib/e2ee/core.js'
import { encodeRoster, keyChangeBytes, rosterBytes, type Roster } from './roster.js'
import { ALERT_WINDOW_MS, RosterStore, type RosterAlertCode } from './rosterStore.js'
const owner = newIdentity(), stranger = newIdentity()
const TAB = 'a1b2c3d4e5f6a1b2c3d4e5f6'
const roster = (version: number): Roster => ({
sharedTabId: TAB, version, name: 'app',
owner: { accountId: 'u-alice', email: '[email protected]', machineId: 'alice-mac', machinePublicKey: b64e(owner.pub) },
leader: null, members: [], invites: [],
harnesses: [{ accountId: 'u-alice', machineId: 'alice-mac', machinePublicKey: b64e(owner.pub), agentId: 'lead', name: 'lead', engine: 'codex' }],
})
const signed = (version: number, by = owner) => {
const r = roster(version), body = encodeRoster(r)
return { body, signature: b64e(sign(by.priv, rosterBytes(TAB, version, body))) }
}
describe('the roster store', () => {
let dir: string, path: string
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'rosters-')); path = join(dir, 'rosters.json') })
afterEach(() => rmSync(dir, { recursive: true, force: true }))
it('says it changed after every save, so that Share derives its observers again, and not when nothing was saved', () => {
let changes = 0
const store = new RosterStore(path, Date.now, (kind) => { if (kind === 'tabs') changes++ })
store.pin(TAB, b64e(owner.pub))
expect(changes).toBe(1)
store.pin(TAB, b64e(owner.pub))
expect(store.offer(signed(2))).toEqual({ roster: roster(2) })
expect(changes).toBe(2)
expect(store.offer(signed(2))).toEqual({ stale: true })
expect(changes).toBe(2)
store.forget(TAB)
expect(changes).toBe(3)
// An alert is saved, but changes no tab: neither the observers nor the consent follow it (final review of 1b), and a
// roster refused for its signature, at the relay's 20 frames a second, wakes nothing.
store.pin(TAB, b64e(owner.pub))
expect(changes).toBe(4)
store.alert(TAB, 'own_machine_listed')
expect(store.offer(signed(3, stranger))).toEqual({ error: 'bad_signature' })
expect(changes).toBe(4)
expect(store.alerts()).toHaveLength(2)
store.forget(TAB)
expect(changes).toBe(5)
// What it saved is on disk by the time it says so.
const seen: number[] = []
const reader = new RosterStore(path, Date.now, () => { seen.push(RosterStore.readRosters(path)!.length) })
reader.pin(TAB, b64e(owner.pub)); reader.offer(signed(3))
expect(seen).toEqual([0, 1])
})
it('tells its owner whether tabs or only alerts changed', () => {
const kinds: string[] = []
const store = new RosterStore(path, () => 1_000, (kind) => kinds.push(kind))
store.alert(TAB, 'bad_signature')
store.pin(TAB, b64e(owner.pub))
expect(kinds).toEqual(['alerts', 'tabs'])
})
it('releases a tab on the relay\'s word: the roster goes, the pin and the version held stay, and the same roster is taken back', () => {
let changes = 0
const store = new RosterStore(path, Date.now, () => { changes++ })
store.release(TAB)
expect(changes).toBe(0)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(3))
store.release(TAB)
expect(changes).toBe(3)
expect(store.current(TAB)).toBeNull()
expect(store.all()).toEqual([])
expect(store.pinned(TAB)).toBe(b64e(owner.pub))
// Read again from the file, released twice: the floor is the version it held, never lowered.
const again = new RosterStore(path)
again.release(TAB)
expect(again.offer(signed(2))).toEqual({ stale: true })
expect(again.offer(signed(3, stranger))).toEqual({ error: 'bad_signature' })
expect(again.offer(signed(3))).toEqual({ roster: roster(3) })
// A pin taken with no roster yet has no floor: any version it signed is taken.
const fresh = new RosterStore(join(dir, 'fresh.json'))
fresh.pin(TAB, b64e(owner.pub)); fresh.release(TAB)
expect(fresh.offer(signed(1))).toEqual({ roster: roster(1) })
// Forgotten, the pin goes too.
again.forget(TAB)
expect(again.pinned(TAB)).toBeNull()
})
it('takes nothing for a tab it never pinned', () => {
expect(new RosterStore(path).offer(signed(1))).toEqual({ error: 'not_pinned' })
})
it('keeps the newest valid roster, and says an older or equal one is stale', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub))
expect(store.offer(signed(2))).toEqual({ roster: roster(2) })
expect(store.offer(signed(1))).toEqual({ stale: true })
expect(store.offer(signed(2))).toEqual({ stale: true })
expect(store.current(TAB)?.roster.version).toBe(2)
expect(store.alerts()).toEqual([])
})
it('keeps the last valid roster and records an alert when a forged one arrives', () => {
const store = new RosterStore(path, () => Date.parse('2026-10-15T10:00:00Z'))
store.pin(TAB, b64e(owner.pub))
store.offer(signed(2))
expect(store.offer(signed(5, stranger))).toEqual({ error: 'bad_signature' })
expect(store.current(TAB)?.roster.version).toBe(2)
expect(store.alerts()).toEqual([{ id: expect.any(String), sharedTabId: TAB, at: '2026-10-15T10:00:00.000Z', error: 'bad_signature' }])
})
it('survives a restart, and keeps its file private', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(3))
const again = new RosterStore(path)
expect(again.current(TAB)?.roster.version).toBe(3)
expect(again.all().map(r => r.version)).toEqual([3])
expect(statSync(path).mode & 0o777).toBe(0o600)
})
it('persists the pin it was given', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub))
expect(JSON.parse(readFileSync(path, 'utf8')).tabs[TAB].pinned).toBe(b64e(owner.pub))
})
it('forgets a tab entirely', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(1)); store.forget(TAB)
expect(store.current(TAB)).toBeNull()
expect(store.offer(signed(2))).toEqual({ error: 'not_pinned' })
})
it('moves an unreadable file aside, starts empty and records file_unreadable, rather than refusing to start', () => {
const at = Date.parse('2026-10-15T10:00:00Z')
writeFileSync(path, '{bad')
const store = new RosterStore(path, () => at)
expect(store.all()).toEqual([])
expect(store.alerts()).toEqual([{ id: expect.any(String), sharedTabId: '', at: '2026-10-15T10:00:00.000Z', error: 'file_unreadable' }])
// Kept for the person, under a name the next start never reads.
expect(readFileSync(`${path}.unreadable-${at}`, 'utf8')).toBe('{bad')
// The fresh file is the store's own: read again, it gives the same alert and no other.
expect(new RosterStore(path, () => at + 1).alerts()).toHaveLength(1)
// A file that reads but is not the store's shape is moved aside the same way.
writeFileSync(path, JSON.stringify({ tabs: 7, alerts: [] }))
const again = new RosterStore(path, () => at + 2)
expect(again.alerts()).toEqual([{ id: expect.any(String), sharedTabId: '', at: '2026-10-15T10:00:00.002Z', error: 'file_unreadable' }])
expect(readFileSync(`${path}.unreadable-${at + 2}`, 'utf8')).toBe('{"tabs":7,"alerts":[]}')
again.pin(TAB, b64e(owner.pub))
expect(new RosterStore(path).pinned(TAB)).toBe(b64e(owner.pub))
})
it('throws, and moves nothing aside, when the file cannot be read at all: it may be whole, and the next wake tries again', () => {
// A folder where the file should be: reading it fails as EACCES, EMFILE or EIO would, never as bad contents.
mkdirSync(path)
expect(() => new RosterStore(path)).toThrow(expect.objectContaining({ code: 'EISDIR' }))
expect(RosterStore.readRosters(path)).toBeNull()
expect(readdirSync(dir)).toEqual(['rosters.json'])
})
it('reads the rosters for another process without writing, renaming or alerting; null when the file is unreadable', () => {
expect(RosterStore.readRosters(path)).toEqual([])
expect(readdirSync(dir)).toEqual([])
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(3))
// A tab pinned with no roster yet, and one whose stored roster no longer verifies, give nothing.
store.pin('b'.repeat(24), b64e(owner.pub))
const state = JSON.parse(readFileSync(path, 'utf8'))
state.tabs['c'.repeat(24)] = { pinned: b64e(stranger.pub), signed: signed(4) }
writeFileSync(path, JSON.stringify(state))
const before = readFileSync(path, 'utf8')
expect(RosterStore.readRosters(path)).toEqual([roster(3)])
expect(readFileSync(path, 'utf8')).toBe(before)
writeFileSync(path, '{bad')
expect(RosterStore.readRosters(path)).toBeNull()
expect(readFileSync(path, 'utf8')).toBe('{bad')
expect(readdirSync(dir)).toEqual(['rosters.json'])
})
it('says not pinned when the body hides its tab id, and when the tab is unknown', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub))
expect(store.offer({ body: '{}', signature: '' })).toEqual({ error: 'not_pinned' })
expect(store.current('ffffffffffffffffffffffff')).toBeNull()
})
it('stamps alerts with the real clock by default, and keeps only the latest fifty', () => {
const store = new RosterStore(path)
const codes: RosterAlertCode[] = ['foreign_machine', 'machine_key_mismatch', 'own_machine_listed', 'already_pinned']
for (let i = 0; i < 52; i++) store.alert(`${i % 13}`.padStart(24, 'a'), codes[Math.floor(i / 13)])
expect(store.alerts()).toHaveLength(50)
expect(store.alerts()[0]).toMatchObject({ sharedTabId: '2'.padStart(24, 'a'), error: 'foreign_machine' })
expect(Number.isNaN(Date.parse(store.alerts()[0].at))).toBe(false)
})
it('counts the same alert for the same tab within ALERT_WINDOW_MS on the last one, so a flood pushes no other out', () => {
let clock = Date.UTC(2026, 9, 16)
const store = new RosterStore(path, () => clock)
store.pin(TAB, b64e(owner.pub))
store.alert(TAB, 'foreign_machine')
// A member's machine sending a bad roster 20 times a second for ten seconds: one alert, counted, at the last time.
for (let i = 0; i < 200; i++) { clock += 50; store.offer(signed(i + 1, stranger)) }
expect(store.alerts()).toEqual([{ id: expect.any(String), sharedTabId: TAB, at: new Date(Date.UTC(2026, 9, 16)).toISOString(), error: 'foreign_machine' },
{ id: expect.any(String), sharedTabId: TAB, at: new Date(clock).toISOString(), error: 'bad_signature', count: 200 }])
// Kept on disk as counted; another tab's, or another error, is an alert of its own, and the latest comes last.
expect(new RosterStore(path).alerts()).toEqual(store.alerts())
store.alert('b'.repeat(24), 'bad_signature')
store.alert(TAB, 'foreign_machine')
expect(store.alerts().map((a) => [a.sharedTabId, a.error, a.count])).toEqual([
[TAB, 'bad_signature', 200], ['b'.repeat(24), 'bad_signature', undefined], [TAB, 'foreign_machine', 2]])
// Once the window has passed since the last, the next is a new alert.
clock += ALERT_WINDOW_MS
store.offer(signed(1, stranger))
expect(store.alerts().map((a) => [a.error, a.count])).toEqual([['bad_signature', 200], ['bad_signature', undefined], ['foreign_machine', 2], ['bad_signature', undefined]])
})
it('keeps the held roster when a tab is pinned again, and drops one whose stored copy no longer verifies', () => {
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(1)); store.pin(TAB, b64e(owner.pub))
expect(store.current(TAB)?.roster.version).toBe(1)
const file = JSON.parse(readFileSync(path, 'utf8'))
file.tabs[TAB].signed.body = file.tabs[TAB].signed.body.replace('"app"', '"evil"')
writeFileSync(path, JSON.stringify(file))
const again = new RosterStore(path)
expect(again.current(TAB)).toBeNull()
expect(again.all()).toEqual([])
})
it('refuses a roster whose body names two tabs, filing it under neither', () => {
const TAB2 = 'b1b2c3d4e5f6a1b2c3d4e5f6'
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.pin(TAB2, b64e(owner.pub))
const body2 = encodeRoster({ ...roster(1), sharedTabId: TAB2 })
const body = `{"sharedTabId":"${TAB}",${body2.slice(1)}`
const signature = b64e(sign(owner.priv, rosterBytes(TAB2, 1, body)))
expect(store.offer({ body, signature })).toEqual({ error: 'malformed' })
expect(store.current(TAB)).toBeNull()
expect(store.alerts().map(a => a.error)).toEqual(['malformed'])
})
it('does not return a stored roster that names another tab than the one it is filed under', () => {
const TAB2 = 'b1b2c3d4e5f6a1b2c3d4e5f6'
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(1))
const file = JSON.parse(readFileSync(path, 'utf8'))
file.tabs[TAB2] = file.tabs[TAB]
writeFileSync(path, JSON.stringify(file))
expect(new RosterStore(path).current(TAB2)).toBeNull()
})
it('refuses to replace a pin with a different key, records it, and lets the same key pin again', () => {
const store = new RosterStore(path)
expect(store.pin(TAB, b64e(owner.pub))).toBe('pinned')
store.offer(signed(8))
expect(store.pin(TAB, b64e(owner.pub))).toBe('pinned')
expect(store.pin(TAB, b64e(stranger.pub))).toBe('already_pinned')
expect(store.current(TAB)?.roster.version).toBe(8)
expect(store.offer(signed(1, stranger))).toEqual({ error: 'bad_signature' })
expect(store.alerts().map(a => a.error)).toEqual(['already_pinned', 'bad_signature'])
store.forget(TAB)
expect(store.pin(TAB, b64e(stranger.pub))).toBe('pinned')
})
it('moves the pin on a key change the old key signed, and then refuses the old key', () => {
const next = newIdentity()
const store = new RosterStore(path)
store.pin(TAB, b64e(owner.pub)); store.offer(signed(1))
const moved = encodeRoster({ ...roster(2), owner: { ...roster(2).owner, machinePublicKey: b64e(next.pub) } })
const keyChange = { previousPub: b64e(owner.pub), signature: b64e(sign(owner.priv, keyChangeBytes(TAB, b64e(next.pub)))) }
expect(store.offer({ body: moved, signature: b64e(sign(next.priv, rosterBytes(TAB, 2, moved))), keyChange })).toHaveProperty('roster')
const again = new RosterStore(path)
expect(again.current(TAB)?.roster.version).toBe(2)
const third = encodeRoster({ ...roster(3), owner: { ...roster(2).owner, machinePublicKey: b64e(next.pub) } })
expect(again.offer({ body: third, signature: b64e(sign(next.priv, rosterBytes(TAB, 3, third))) })).toHaveProperty('roster')
expect(again.offer(signed(4))).toEqual({ error: 'unpinned_key' })
expect(again.current(TAB)?.roster.version).toBe(3)
})
it('records an alert a member\'s own check raises, and keeps it across a restart', () => {
const store = new RosterStore(path, () => Date.parse('2026-10-15T11:00:00Z'))
store.alert(TAB, 'foreign_machine')
store.alert(TAB, 'machine_key_mismatch')
const expected = [{ id: expect.any(String), sharedTabId: TAB, at: '2026-10-15T11:00:00.000Z', error: 'foreign_machine' },
{ id: expect.any(String), sharedTabId: TAB, at: '2026-10-15T11:00:00.000Z', error: 'machine_key_mismatch' }]
expect(store.alerts()).toEqual(expected)
expect(new RosterStore(path).alerts()).toEqual(expected)
})
it('says which owner key a tab is pinned to, with or without a roster yet, and none once forgotten', () => {
const store = new RosterStore(path)
expect(store.pinned(TAB)).toBeNull()
store.pin(TAB, b64e(owner.pub))
expect(store.pinned(TAB)).toBe(b64e(owner.pub))
store.offer(signed(1))
expect(new RosterStore(path).pinned(TAB)).toBe(b64e(owner.pub))
store.forget(TAB)
expect(store.pinned(TAB)).toBeNull()
})
it('gives each alert an id, hides a dismissed one, and starts a new one when it happens again', () => {
let t = 1_000
const store = new RosterStore(path, () => t)
store.alert(TAB, 'bad_signature')
const [a] = store.alerts()
expect(a).toMatchObject({ id: expect.any(String), sharedTabId: TAB, error: 'bad_signature' })
expect(store.dismiss(a.id)).toBe(true)
expect(store.alerts()).toEqual([])
t += 1_000
// Within ALERT_WINDOW_MS, but the last was dismissed.
store.alert(TAB, 'bad_signature')
expect(store.alerts()).toEqual([expect.objectContaining({ error: 'bad_signature' })])
expect(store.alerts()[0].count).toBeUndefined()
expect(store.alerts()[0].id).not.toBe(a.id)
expect(store.dismiss(a.id)).toBe(false)
expect(store.dismiss('nope')).toBe(false)
})
it('tells the windows of a dismissed alert, as an alert change only', () => {
const kinds: string[] = []
const store = new RosterStore(path, Date.now, (kind) => kinds.push(kind))
store.alert(TAB, 'bad_signature')
store.dismiss(store.alerts()[0].id)
expect(kinds).toEqual(['alerts', 'alerts'])
expect(new RosterStore(path).alerts()).toEqual([])
})
it('tells of an alert only when one is added or dismissed, never for a repeat counted on it (final review of 1c, I4)', () => {
const kinds: string[] = []
let t = 1_000
const store = new RosterStore(path, () => t, (kind) => kinds.push(kind))
for (let i = 0; i < 20; i++) { store.alert(TAB, 'bad_signature'); t += 50 }
expect(store.alerts()).toEqual([expect.objectContaining({ error: 'bad_signature', count: 20 })])
// The count is saved, but nobody is woken for it.
expect(new RosterStore(path).alerts()[0].count).toBe(20)
expect(kinds).toEqual(['alerts'])
store.alert(TAB, 'malformed')
store.dismiss(store.alerts()[0].id)
expect(kinds).toEqual(['alerts', 'alerts', 'alerts'])
// A file from 1b given ids on load wakes nobody either.
writeFileSync(path, JSON.stringify({ tabs: {}, alerts: [{ sharedTabId: TAB, at: '2026-10-16T10:00:00.000Z', error: 'bad_signature' }] }))
const told: string[] = []
new RosterStore(path, Date.now, (kind) => told.push(kind))
expect(told).toEqual([])
})
it('gives an id to an alert a file from 1b kept without one, and keeps it', () => {
writeFileSync(path, JSON.stringify({ tabs: {}, alerts: [{ sharedTabId: TAB, at: '2026-10-16T10:00:00.000Z', error: 'bad_signature' }] }))
const id = new RosterStore(path).alerts()[0].id
expect(id).toEqual(expect.any(String))
expect(new RosterStore(path).alerts()[0].id).toBe(id)
})
it('keeps an alert\'s id when it happens again, so it can still be dismissed', () => {
let t = 1_000
const store = new RosterStore(path, () => t)
store.alert(TAB, 'bad_signature')
const { id } = store.alerts()[0]
t += 1_000
store.alert(TAB, 'bad_signature')
expect(store.alerts()).toEqual([expect.objectContaining({ id, count: 2 })])
expect(store.dismiss(id)).toBe(true)
expect(store.alerts()).toEqual([])
})
})