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 { mkdtempSync, readFileSync, rmSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it } from 'vitest'
import { ASSIGNED_GRACE_MS, mayBeBuddy, mayBeLead, RETENTION_LAPSE_MS, retainContributions, retainedHarnesses, retainedLeads, retentionFile } from './retention.js'
const roots: string[] = []
const root = () => { const dir = mkdtempSync(join(tmpdir(), 'super-retention-')); roots.push(dir); return dir }
const row = (harnessId: string, extra: Record<string, unknown> = {}, machineId = 'machine') => ({ tabId: 'tab', agent: { harnessId, machineId }, ...extra })
afterEach(() => { for (const dir of roots.splice(0)) rmSync(dir, { recursive: true, force: true }) })
it('retains exact members durably, avoids unchanged writes and releases only the confirmed host roster', () => {
const dir = root(), now = Date.now()
expect([...retainedHarnesses(dir)]).toEqual([])
retainContributions(dir, 'machine', [row('multiply'), row('divide'), row('multiply')], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['divide', 'multiply'])
const file = retentionFile(dir), before = statSync(file, { bigint: true }).mtimeNs
retainContributions(dir, 'machine', [row('divide'), row('multiply')], now + 1000)
expect(statSync(file, { bigint: true }).mtimeNs).toBe(before)
expect(statSync(file).mode & 0o777).toBe(0o600)
retainContributions(dir, 'machine', [], now)
expect([...retainedHarnesses(dir, now)]).toEqual([])
})
it('retains paused-tab members but not members of only archived groups or rows for another machine', () => {
const dir = root(), now = Date.now()
retainContributions(dir, 'machine', [row('kept'), row('legacy', { active: undefined }), row('paused', { paused: true }),
row('archived', { active: false }), row('foreign', {}, 'other'), {}, row('../bad')], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['kept', 'legacy', 'paused'])
expect(() => retainContributions(dir, '../bad', [])).toThrow()
})
it('lets a new machine identity replace the old entry, and lapses a roster nobody confirms', () => {
const dir = root(), now = Date.now(), file = retentionFile(dir)
retainContributions(dir, 'old-machine', [row('combine', {}, 'old-machine')], now)
retainContributions(dir, 'machine', [row('multiply')], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['multiply'])
// An unchanged roster refreshes the lapse clock at most hourly, without rewriting.
const content = readFileSync(file, 'utf8')
retainContributions(dir, 'machine', [row('multiply')], now + 2 * 60 * 60_000)
expect(readFileSync(file, 'utf8')).toBe(content)
expect(Math.abs(statSync(file).mtimeMs - (now + 2 * 60 * 60_000))).toBeLessThan(1000)
expect([...retainedHarnesses(dir, now + 2 * 60 * 60_000 + RETENTION_LAPSE_MS - 1000)]).toEqual(['multiply'])
expect([...retainedHarnesses(dir, now + 2 * 60 * 60_000 + RETENTION_LAPSE_MS + 1000)]).toEqual([])
})
it('pauses cleanup on corrupt or oversized retention until the host rewrites it or it lapses', () => {
const dir = root(), file = retentionFile(dir), now = Date.now()
retainContributions(dir, 'machine', [row('multiply')], now)
for (const value of ['{', '{}', '{"version":1,"machines":{}}', '{"version":2,"machineId":"machine","harnesses":[null]}', ' '.repeat(4 * 1024 * 1024 + 1)]) {
writeFileSync(file, value)
utimesSync(file, new Date(now), new Date(now))
expect(() => retainedHarnesses(dir, now)).toThrow('Automatic cleanup is paused')
expect([...retainedHarnesses(dir, now + RETENTION_LAPSE_MS + 1)]).toEqual([])
}
retainContributions(dir, 'machine', [row('multiply')], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['multiply'])
unlinkSync(file)
expect([...retainedHarnesses(dir, now)]).toEqual([])
})
// The owner, 2026-10-23: the Lead of an active project is never stopped, in any case. It is kept from cleanup even when
// its groups read as archived, and never lapses: a machine signed out for a week still keeps its Lead.
it('keeps a Lead apart, never lapses it, and releases it only when a confirmed roster no longer marks it', () => {
const dir = root(), now = Date.now()
expect([...retainedLeads(dir)]).toEqual([])
retainContributions(dir, 'machine', [row('lead', { lead: true, active: false }), row('worker'), row('foreign-lead', { lead: true }, 'other')], now)
expect([...retainedLeads(dir)]).toEqual(['lead'])
expect([...retainedHarnesses(dir, now)]).toEqual(['lead', 'worker'])
expect([...retainedHarnesses(dir, now + RETENTION_LAPSE_MS + 1000)]).toEqual(['lead'])
retainContributions(dir, 'machine', [row('lead', { closeSession: true }), row('worker')], now)
expect([...retainedLeads(dir)]).toEqual([])
})
it('reopens no Lead from an unreadable file', () => {
const dir = root()
retainContributions(dir, 'machine', [row('lead', { lead: true })])
writeFileSync(retentionFile(dir), '{')
expect([...retainedLeads(dir)]).toEqual([])
})
// The review of #1635: a file from before Leads were kept, or one that cannot be read, must not let a stop through to a
// Lead. Until a roster says which members are Leads, each member may be one; a file nobody can read protects them all.
it('treats a stop as possibly of a Lead until a valid roster says otherwise', () => {
const dir = root(), file = retentionFile(dir)
expect(mayBeLead(dir, 'anyone')).toBe(false)
retainContributions(dir, 'machine', [row('lead', { lead: true }), row('worker')])
expect([mayBeLead(dir, 'lead'), mayBeLead(dir, 'worker'), mayBeLead(dir, 'personal')]).toEqual([true, false, false])
writeFileSync(file, JSON.stringify({ version: 2, machineId: 'machine', harnesses: ['old-member'] }))
expect([mayBeLead(dir, 'old-member'), mayBeLead(dir, 'personal')]).toEqual([true, false])
writeFileSync(file, '{')
expect([mayBeLead(dir, 'old-member'), mayBeLead(dir, 'personal')]).toEqual([true, true])
retainContributions(dir, 'machine', [row('worker')])
expect([mayBeLead(dir, 'old-member'), mayBeLead(dir, 'worker')]).toEqual([false, false])
})
// A session the backend ends is closed by the host, and only one it already kept as a member: the retention is that proof,
// across host restarts, for the host and for the core's close alike.
it('keeps a session the backend ends only while it was already a member', () => {
const dir = root(), now = Date.now()
retainContributions(dir, 'machine', [row('stranger', { closeSession: true, active: false })], now)
expect([...retainedHarnesses(dir, now)]).toEqual([])
retainContributions(dir, 'machine', [row('member')], now)
retainContributions(dir, 'machine', [row('member', { closeSession: true, active: false }), row('stranger', { closeSession: true })], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['member'])
retainContributions(dir, 'machine', [row('member', { closeSession: true })], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['member'])
retainContributions(dir, 'machine', [], now)
expect([...retainedHarnesses(dir, now)]).toEqual([])
})
// Diego's Buddy, 10-30: closing the tab that showed it stopped it, for 30 minutes, while two proposals waited. A Buddy is in
// no open group and is no Lead, so nothing kept it. The server's roster marks it (its agent's buddyOf); only that keeps it.
it('keeps a Buddy the roster marks, in no open group, until the roster ends or drops it', () => {
const dir = root(), now = Date.now()
const buddy = (extra: Record<string, unknown> = {}) => ({ tabId: 'tab', agent: { harnessId: 'buddy', machineId: 'machine', buddyOf: { personId: 'diego', generation: 'g1' } }, ...extra })
expect(mayBeBuddy(dir, 'buddy')).toBe(false)
retainContributions(dir, 'machine', [buddy({ active: false, lead: false }), row('worker', { active: false }), row('claims', { active: false, buddyOf: { personId: 'diego' } })], now)
expect([mayBeBuddy(dir, 'buddy'), mayBeBuddy(dir, 'worker'), mayBeBuddy(dir, 'claims')]).toEqual([true, false, false])
expect([...retainedHarnesses(dir, now)]).toEqual(['buddy'])
expect(mayBeLead(dir, 'buddy')).toBe(false)
// Another machine's Buddy, or a marker that is not a person's, keeps nothing here.
retainContributions(dir, 'machine', [buddy(), { tabId: 'tab', agent: { harnessId: 'away', machineId: 'other', buddyOf: { personId: 'diego' } } },
{ tabId: 'tab', agent: { harnessId: 'odd', machineId: 'machine', buddyOf: { personId: '../x' } } }], now)
expect([mayBeBuddy(dir, 'away'), mayBeBuddy(dir, 'odd')]).toEqual([false, false])
// Removed by its person: the row that ends it names no Buddy, and the session stays kept only until the host closes it.
retainContributions(dir, 'machine', [{ tabId: 'tab', agent: { id: 'a', harnessId: 'buddy', machineId: 'machine' }, closeSession: true, active: false }], now)
expect(mayBeBuddy(dir, 'buddy')).toBe(false)
expect([...retainedHarnesses(dir, now)]).toEqual(['buddy'])
retainContributions(dir, 'machine', [], now)
expect([mayBeBuddy(dir, 'buddy'), retainedHarnesses(dir, now).has('buddy')]).toEqual([false, false])
})
// Like a Lead's (the review of #1635): a file nobody can read may name anyone, until the host's next roster rewrites it. A
// file from before Buddies were kept names none: the next roster lists them.
it('treats a close as possibly of a Buddy only while the file cannot be read', () => {
const dir = root(), file = retentionFile(dir)
retainContributions(dir, 'machine', [row('worker')])
writeFileSync(file, JSON.stringify({ version: 2, machineId: 'machine', harnesses: ['worker'], leads: [] }))
expect(mayBeBuddy(dir, 'worker')).toBe(false)
writeFileSync(file, '{')
expect(mayBeBuddy(dir, 'worker')).toBe(true)
writeFileSync(file, JSON.stringify({ version: 2, machineId: 'machine', harnesses: [], leads: [], buddies: ['../bad'] }))
expect(mayBeBuddy(dir, 'worker')).toBe(true)
})
// The Product Manager, 10-30: the owner of a computer always stops anything running on it with one explicit action. Stop
// Harness refuses only a Lead (core/main.ts hands it `mayBeLead`), so a Buddy, a teammate's too, must never read as one.
it('leaves every Buddy to Stop Harness: none reads as a Lead', () => {
const dir = root()
const buddyOf = (personId: string, harnessId: string) => ({ tabId: 'tab', agent: { harnessId, machineId: 'machine', buddyOf: { personId } }, active: false })
retainContributions(dir, 'machine', [buddyOf('owner', 'own-buddy'), buddyOf('teammate', 'their-buddy'), row('lead', { lead: true })])
expect([mayBeBuddy(dir, 'own-buddy'), mayBeBuddy(dir, 'their-buddy')]).toEqual([true, true])
expect([mayBeLead(dir, 'own-buddy'), mayBeLead(dir, 'their-buddy'), mayBeLead(dir, 'lead')]).toEqual([false, false, true])
})
// Unlike a Lead, a Buddy lapses with the roster: a machine signed out or unlinked for a week keeps no Buddy from a close.
it('lets a Buddy lapse with a roster nobody confirms for a week', () => {
const dir = root(), now = Date.now()
retainContributions(dir, 'machine', [{ tabId: 'tab', agent: { harnessId: 'buddy', machineId: 'machine', buddyOf: { personId: 'diego' } } }], now)
expect(mayBeBuddy(dir, 'buddy', now + RETENTION_LAPSE_MS - 1000)).toBe(true)
expect(mayBeBuddy(dir, 'buddy', now + RETENTION_LAPSE_MS + 1000)).toBe(false)
})
// 11-04 on the Mac Studio: Tern's last group was archived, so the roster no longer kept it, and the idle cleanup may close it
// in the very poll its next task arrives in (task #2744). An assignment the host holds keeps its harness, and for a minute.
it('retains a harness that holds an assignment, and for a minute after the host first received it', () => {
const dir = root(), now = Date.now(), file = retentionFile(dir)
const work = (harnessId: string) => ({ tabId: 'tab', assignmentId: `work-${harnessId}`, harnessId })
retainContributions(dir, 'machine', [row('tern', { active: false })], now, [work('tern'), { tabId: 'tab' }, work('../bad')])
expect([...retainedHarnesses(dir, now)]).toEqual(['tern'])
// Unchanged while it holds it: no write each poll.
const before = statSync(file, { bigint: true }).mtimeNs
retainContributions(dir, 'machine', [row('tern', { active: false })], now + 20_000, [work('tern')])
expect(statSync(file, { bigint: true }).mtimeNs).toBe(before)
// Its assignment ended: kept until a minute after it first came, then released.
retainContributions(dir, 'machine', [row('tern', { active: false })], now + ASSIGNED_GRACE_MS - 1, [])
expect([...retainedHarnesses(dir, now + ASSIGNED_GRACE_MS - 1)]).toEqual(['tern'])
retainContributions(dir, 'machine', [row('tern', { active: false })], now + ASSIGNED_GRACE_MS, [])
expect([...retainedHarnesses(dir, now + ASSIGNED_GRACE_MS)]).toEqual([])
// A roster read alone, as an older caller makes it, keeps the minute of one received just now.
retainContributions(dir, 'machine', [], now, [work('heron')])
retainContributions(dir, 'machine', [], now + 1000)
expect([...retainedHarnesses(dir, now + 1000)]).toEqual(['heron'])
})
// Task #3397: a crew member is kept in no open group as between tasks, never lapses, and is among the sessions the core may
// reopen; off the crew it is an ordinary member again on the next roster.
it('keeps a crew member with no open group, past the lapse, and names it among those the core reopens', () => {
const dir = root(), now = Date.now(), file = retentionFile(dir)
const crew = { crew: { role: 'Engineer', at: 1, by: 'pm' } }
const crewRow = (harnessId: string, extra: Record<string, unknown> = {}) => ({ tabId: 'tab', agent: { harnessId, machineId: 'machine', ...crew }, ...extra })
retainContributions(dir, 'machine', [crewRow('standing', { active: false }), row('idle', { active: false }), row('pm', { lead: true })], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['pm', 'standing'])
expect([...retainedLeads(dir)].sort()).toEqual(['pm', 'standing'])
expect(JSON.parse(readFileSync(file, 'utf8')).crew).toEqual(['standing'])
const lapsed = new Date(now - RETENTION_LAPSE_MS - 60_000)
utimesSync(file, lapsed, lapsed)
expect([...retainedHarnesses(dir, now)].sort()).toEqual(['pm', 'standing'])
// A crew mark is not a Lead's: a stop still reaches it (leadSwitch.ts mayBeLead).
expect(mayBeLead(dir, 'standing')).toBe(false)
// Security review 1 of #3222: one whose stop is asked for is no crew the core may reopen.
retainContributions(dir, 'machine', [crewRow('standing', { stopRequested: true }), row('pm', { lead: true })], now)
expect([...retainedLeads(dir)]).toEqual(['pm'])
retainContributions(dir, 'machine', [row('standing', { active: false }), row('pm', { lead: true })], now)
expect([...retainedHarnesses(dir, now)]).toEqual(['pm'])
expect([...retainedLeads(dir)]).toEqual(['pm'])
})
it('grants resume only to server-managed main Buddies and revokes it on stop or removal (#3824)', () => {
const dir = root()
const buddy = (id: string, extra: Record<string, unknown> = {}, agent: Record<string, unknown> = {}) => row(id,
{ agent: { harnessId: id, machineId: 'machine', buddyOf: { personId: 'peer', generation: 'g' }, ...agent }, ...extra })
retainContributions(dir, 'machine', [buddy('managed', { buddySleepManaged: true }), buddy('old'),
buddy('thread', { buddySleepManaged: true }, { buddySession: { thread: 'root' } }),
buddy('stopping', { buddySleepManaged: true, stopRequested: true })])
expect([...retainedLeads(dir)]).toEqual(['managed'])
expect(mayBeBuddy(dir, 'managed')).toBe(true)
retainContributions(dir, 'machine', [buddy('managed', { stopRequested: true }), buddy('old')])
expect([...retainedLeads(dir)]).toEqual([])
retainContributions(dir, 'machine', [])
expect([...retainedHarnesses(dir)]).toEqual([])
})