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, expect, it, vi } from 'vitest'
import { mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import { fakeCore } from '../testing/fakeCore.js'
import { builtinSqlite } from '../lib/sqliteBuiltin.js'
import type { CreationObservation } from '../lib/creationObservation.js'
import type { MachineResources } from '../lib/machineResources.js'
import { CapacityReservations, LAUNCH_DEADLINE_MS, START_DEADLINE_MS } from './reservations.js'
const books: CapacityReservations[] = [], folders: string[] = []
afterEach(() => { for (const book of books.splice(0)) book.stop(); for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }) })
const id = (n: number) => `fixture-creation-${n}`
const input = (n = 1, memory = 60, disk = 60) => ({ creationId: id(n), cwd: '/fixture/repo', requirements: { memoryBytes: memory, diskBytes: disk, maxCpuPercent: 80 } })
function setup() {
const directory = mkdtempSync(join(tmpdir(), 'super-tab-capacity-')); folders.push(directory)
const native = new Map<string, CreationObservation | null>(), stopped = new Set<string>(), gone = new Set<string>()
const core = fakeCore({ dataDir: directory, agents: {
creationStatus: vi.fn(async key => native.has(key) ? native.get(key)! : { creationId: key, state: 'missing' as const }),
stopped: vi.fn(async key => stopped.has(key)),
gone: vi.fn(async key => gone.has(key)),
} })
const resources: MachineResources = { cpuPercent: 20, memoryTotalBytes: 150, memoryUsedBytes: 50 }
// The live agents' start times (registeredAt) and their measured memory, by harness id.
const live = new Map<string, number>(), measured = new Map<string, number>()
const clock = { now: Date.UTC(2026, 9, 28, 4) }
vi.mocked(core.agents.byAgent).mockImplementation(key => live.has(key) ? { agentId: key, registeredAt: live.get(key)! } as never : undefined)
const deps = { resources: vi.fn(async () => resources),
disk: vi.fn(async (cwd: string) => ({ freeBytes: 100, volume: cwd === '/second-volume' ? 'second' : 'first', path: cwd })),
sqlite: () => builtinSqlite() as never, now: () => clock.now, agentMemory: vi.fn(async () => new Map(measured)), log: vi.fn() }
const open = () => { const book = new CapacityReservations(core, 'machine-1', deps); books.push(book); return book }
/** The start reserved as `n` launched as harness `agent-n` at this moment. */
const launch = (n: number) => { native.set(id(n), { creationId: id(n), state: 'created', agentId: `agent-${n}` }); live.set(`agent-${n}`, clock.now) }
return { directory, file: join(directory, 'super-tabs/capacity.sqlite'), core, native, stopped, gone, resources, deps, open, live, measured, clock, launch }
}
const GiB = 1024 ** 3, MINUTE = 60_000
const free = (f: ReturnType<typeof setup>, bytes: number) => { f.resources.memoryTotalBytes = 32 * GiB; f.resources.memoryUsedBytes = 32 * GiB - Math.round(bytes) }
const agentInput = (n: number) => input(n, 2 * GiB, 0)
// Ken's MacBook Pro, 2026-10-28: 7.85 GiB free of 32 and three settled builders using about 0.4 GiB together, yet a start was
// refused with 1.85 GiB "left". Free memory (vm_stat) already counts what a running agent uses, so its 2 GiB was taken twice.
it("counts a start's memory only during its start window, so settled agents do not block more starts", async () => {
const f = setup(), book = f.open()
free(f, 30 * GiB)
for (const n of [1, 2, 3]) { expect(await book.reserve(agentInput(n))).toMatchObject({ ok: true }); f.launch(n); f.measured.set(`agent-${n}`, 0.13 * GiB) }
f.clock.now += 5 * MINUTE
free(f, 7.85 * GiB)
for (const n of [4, 5, 6]) { expect(await book.reserve(agentInput(n))).toMatchObject({ ok: true }); f.launch(n) }
expect(await book.reserve(agentInput(7))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE',
detail: 'Not enough free memory: 1.8 GiB free, 2 GiB needed. 6 GiB more is set aside for 3 agents still starting, the oldest '
+ 'reserved under a minute ago (start receipts fixture-creation-4, fixture-creation-5, fixture-creation-6).' })
// The first of the three new agents settles: its own use is in free memory now, and its window no longer holds.
f.clock.now += 5 * MINUTE - 1
expect(await book.reserve(agentInput(7))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.clock.now += 1
expect(await book.reserve(agentInput(7))).toMatchObject({ ok: true })
})
it('ends a start window early once the agent measures its whole reservation', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.launch(1)
f.measured.set('agent-1', 2 * GiB - 1)
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.measured.set('agent-1', 2 * GiB)
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
})
it('keeps holding a start that has not launched, and times a launched agent the core no longer lists from its reservation', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.clock.now += START_DEADLINE_MS - 1
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
// Launched, but not in the core's live list (a reconnect in between): its window ran from the reservation and is over.
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'agent-1' })
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
})
it('holds every launched start in its window when its memory cannot be measured', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.launch(1)
f.deps.agentMemory.mockRejectedValue(new Error('ps failed'))
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.clock.now += 5 * MINUTE
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
})
it('still refuses a truly full machine with no other start pending, and says how much memory is free', async () => {
const f = setup(), book = f.open()
free(f, 1.5 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: 'Not enough free memory: 1.5 GiB free, 2 GiB needed.' })
free(f, 20 * GiB); f.resources.memoryPressure = 'critical'
expect(await book.reserve(agentInput(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('critical memory pressure') })
})
it('serializes simultaneous starts across books and accounts for their declared budgets', async () => {
const f = setup(), a = f.open(), b = f.open()
const answers = await Promise.all([a.reserve(input(1)), b.reserve(input(2))])
expect(answers.filter(r => r.ok)).toHaveLength(1)
expect(answers.filter(r => r.error)).toEqual([expect.objectContaining({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('memory') })])
expect(statSync(f.file).mode & 0o777).toBe(0o600)
expect(statSync(join(f.directory, 'super-tabs')).mode & 0o777).toBe(0o700)
})
it('recovers an interrupted reservation reply after restart without reserving twice', async () => {
const f = setup(), first = f.open()
expect(await first.reserve(input())).toMatchObject({ ok: true, reservationId: id(1) })
first.stop()
const second = f.open()
expect(await second.reserve(input())).toMatchObject({ ok: true })
expect(await second.reserve(input(2, 40, 40))).toMatchObject({ ok: true })
expect(await second.reserve(input(3, 1, 1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await second.reserve(input(1, 30, 60))).toMatchObject({ error: 'CAPACITY_RECEIPT_CONFLICT' })
})
it.each(['missing', 'pending', 'unconfirmed', null] as const)('retains %s launches with no inferred stop', async state => {
const f = setup(), book = f.open()
await book.reserve(input())
f.native.set(id(1), state ? { creationId: id(1), state } : null)
expect(await book.reserve(input(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.observe(id(1))).toMatchObject({ ok: true, released: false, harnessId: null })
})
it.each(['failed', 'cancelled'] as const)('releases only the exact durable %s receipt and prevents its reuse', async state => {
const f = setup(), book = f.open()
await book.reserve(input())
f.native.set(id(1), { creationId: id(1), state })
expect(await book.reserve(input(2))).toMatchObject({ ok: true })
expect(await book.reserve(input())).toMatchObject({ error: 'START_FINISHED' })
f.native.set(id(1), null)
expect(await book.observe(id(1))).toMatchObject({ ok: true, released: true })
})
it('retains a learned harness identity after its native window disappears and requires a confirmed stop', async () => {
const f = setup(), book = f.open()
await book.reserve(input())
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'native' })
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'native', released: false })
book.stop()
f.native.set(id(1), null)
const restarted = f.open()
expect(await restarted.reserve(input(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.stopped.add('native')
expect(await restarted.reserve(input(2))).toMatchObject({ ok: true })
expect(await restarted.observe(id(1))).toMatchObject({ harnessId: 'native', released: true })
})
// The review of #1635: the backend's closeSession row names only the harness, so the host finds the Swarm's own start of
// it here, the receipt every start confirmed against the core before it reported success.
it('names the start that created a harness, even after it stopped, and none for a harness it never started', async () => {
const f = setup(), book = f.open()
await book.reserve(input())
expect(book.creationOf('native')).toBeNull()
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'native' })
f.stopped.add('native')
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'native', released: true })
expect(book.creationOf('native')).toBe(id(1))
expect(book.creationOf('another')).toBeNull()
})
it('recovers a harness that started and stopped before the service observed its creation', async () => {
const f = setup(), book = f.open()
await book.reserve(input())
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'already-closed' })
f.stopped.add('already-closed')
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'already-closed', released: true })
expect(await book.reserve(input(2))).toMatchObject({ ok: true })
})
it('releases the memory of an agent the person closed by hand, on the next reserve, and keeps a running one', async () => {
const f = setup(), book = f.open()
await book.reserve(input(1, 100))
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'closed-by-hand' })
expect(await book.reserve(input(2, 100))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('memory') })
f.gone.add('closed-by-hand')
expect(await book.reserve(input(2, 100))).toMatchObject({ ok: true })
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'closed-by-hand', released: true })
f.native.set(id(2), { creationId: id(2), state: 'pending' })
f.gone.add('never-asked')
expect(await book.reserve(input(3, 100))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
})
it('frees the disk of an agent the person closed by hand together with its memory', async () => {
const f = setup(), book = f.open()
await book.reserve(input(1, 0, 60))
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'closed-by-hand' })
expect(await book.reserve(input(2, 0, 60))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })
f.gone.add('closed-by-hand')
expect(await book.reserve(input(2, 0, 60))).toMatchObject({ ok: true })
})
it('does not release on a gone answer that fails or that an older core cannot give', async () => {
const f = setup(), book = f.open()
await book.reserve(input(1, 100))
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'native' })
vi.mocked(f.core.agents.gone!).mockRejectedValueOnce(new Error('offline'))
expect(await book.reserve(input(2, 100))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
delete (f.core.agents as { gone?: unknown }).gone
expect(await book.reserve(input(2, 100))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
})
it('reserves disk on its destination volume and keeps separate volumes independent', async () => {
const f = setup(), book = f.open()
await book.reserve(input(1, 0, 60))
expect(await book.reserve(input(2, 0, 60))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })
expect(await book.reserve({ ...input(3, 0, 60), cwd: '/second-volume', worktree: true })).toMatchObject({ ok: true })
expect(f.deps.disk).toHaveBeenLastCalledWith('/second-volume', true)
})
// Diego's Mac, 2026-10-28: free disk is measured, so it already counts each running agent's worktree; holding its 10 GiB
// past launch counted that space twice. 15 settled agents held 150 GiB on a disk with 140 GiB free and every start was refused.
const diskInput = (n: number) => input(n, 0, 10 * GiB)
const freeDisk = (f: ReturnType<typeof setup>, bytes: number) => f.deps.disk.mockResolvedValue({ freeBytes: bytes, volume: 'first', path: '/fixture/repo' })
it('counts a start\'s disk only during its start window, so settled agents do not block more starts', async () => {
const f = setup(), book = f.open()
freeDisk(f, 1000 * GiB)
for (let n = 1; n <= 15; n++) { expect(await book.reserve(diskInput(n))).toMatchObject({ ok: true }); f.launch(n) }
f.clock.now += 5 * MINUTE
freeDisk(f, 15 * GiB)
expect(await book.reserve(diskInput(16))).toMatchObject({ ok: true })
})
it('keeps holding disk for a start inside its window and for one that has not launched', async () => {
const f = setup(), book = f.open()
freeDisk(f, 15 * GiB)
expect(await book.reserve(diskInput(1))).toMatchObject({ ok: true })
f.clock.now += START_DEADLINE_MS - 1
expect(await book.reserve(diskInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })
f.launch(1)
f.clock.now += 5 * MINUTE - 1
expect(await book.reserve(diskInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })
f.clock.now += 1
expect(await book.reserve(diskInput(2))).toMatchObject({ ok: true })
})
it('lets only one of two simultaneous starts take the last free disk', async () => {
const f = setup(), a = f.open(), b = f.open()
freeDisk(f, 15 * GiB)
const answers = await Promise.all([a.reserve(diskInput(1)), b.reserve(diskInput(2))])
expect(answers.filter(r => r.ok)).toHaveLength(1)
expect(answers.filter(r => r.error)).toEqual([expect.objectContaining({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })])
})
it('refuses to reuse a reservation when an unmount moves the same path to a different volume', async () => {
const f = setup(), book = f.open()
await book.reserve(input())
f.deps.disk.mockResolvedValueOnce({ freeBytes: 100, volume: 'replacement', path: '/fixture/repo' })
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('filesystem changed') })
expect(await book.reserve(input(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
})
it('refuses unknown native/disk/memory readings and critical or excessive load', async () => {
const f = setup(), book = f.open()
f.native.set(id(1), null)
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.native.delete(id(1)); f.deps.disk.mockRejectedValueOnce(new Error('unmounted'))
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.resources.memoryUsedBytes = null
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.resources.memoryUsedBytes = 50; f.resources.memoryPressure = 'critical'
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.resources.memoryPressure = null; f.resources.cpuPercent = 99
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.resources.cpuPercent = null
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.resources.cpuPercent = 20
expect(await book.reserve(input())).toMatchObject({ ok: true })
})
it('does not trust a receipt for another creation or a changed native identity', async () => {
const f = setup(), book = f.open()
f.native.set(id(1), { creationId: id(2), state: 'missing' })
expect(await book.reserve(input())).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
f.native.delete(id(1)); await book.reserve(input())
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'native' })
await book.observe(id(1))
f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'other-native' })
await expect(book.observe(id(1))).rejects.toThrow('identity changed')
})
it.each([{ creationId: 'short' }, { cwd: 'relative' }, { worktree: 'yes' },
{ requirements: { memoryBytes: -1 } }, { requirements: { diskBytes: Infinity } },
{ requirements: { memoryBytes: Number.MAX_SAFE_INTEGER + 1 } }, { requirements: { maxCpuPercent: 101 } },
])('rejects malformed admission without probing the host: %j', async value => {
const f = setup(), book = f.open()
expect(await book.reserve({ ...input(), ...value })).toMatchObject({ error: 'INVALID_REQUEST' })
expect(f.deps.resources).not.toHaveBeenCalled()
})
it('cancels an in-flight admission on disconnect or request cancellation', async () => {
const f = setup(), book = f.open(), controller = new AbortController()
let finish!: () => void
f.deps.resources.mockImplementationOnce(async () => { await new Promise<void>(resolve => { finish = resolve }); return f.resources })
const pending = book.reserve(input(), controller.signal)
await vi.waitFor(() => expect(finish).toBeTypeOf('function'))
controller.abort(); finish()
await expect(pending).rejects.toThrow('disconnected')
expect(await book.observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
f.deps.resources.mockImplementationOnce(async () => { book.stop(); return f.resources })
await expect(book.reserve(input())).rejects.toThrow('disconnected')
expect(await f.open().observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
})
it('does not write an old host admission after its machine identity changes', async () => {
const f = setup(), book = f.open()
f.deps.resources.mockImplementationOnce(async () => { f.core.daemon.machineId = () => 'another-machine'; return f.resources })
await expect(book.reserve(input())).rejects.toThrow('disconnected')
expect(() => new CapacityReservations(f.core, '', f.deps)).toThrow('no confirmed machine identity')
})
it('refuses a replaced, lost, corrupt or unsupported ledger without silently discarding reservations', async () => {
const f = setup(), book = f.open()
await book.reserve(input())
const saved = readFileSync(f.file)
rmSync(f.file); writeFileSync(f.file, saved, { mode: 0o600 })
await expect(book.reserve(input(2))).rejects.toThrow('changed on disk')
book.stop(); rmSync(f.file)
expect(() => f.open()).toThrow('missing')
writeFileSync(f.file, 'corrupted', { mode: 0o600 })
expect(() => f.open()).toThrow()
rmSync(f.file)
const target = join(f.directory, 'elsewhere'); writeFileSync(target, saved, { mode: 0o600 }); symlinkSync(target, f.file)
expect(() => f.open()).toThrow()
expect(() => new CapacityReservations(f.core, 'machine-1', { ...f.deps, sqlite: () => null })).toThrow('Update the Harness CLI runtime')
})
it('serializes real concurrent processes using one disk ledger', async () => {
const f = setup(); f.open().stop()
const script = `
import { CapacityReservations } from './src/superTabs/reservations.ts';
import { builtinSqlite } from './src/lib/sqliteBuiltin.ts';
const core = { dataDir: process.argv[1], daemon: { machineId: () => 'machine-1' }, agents: {
creationStatus: async creationId => ({ creationId, state: 'missing' }), stopped: async () => false
} };
const book = new CapacityReservations(core, 'machine-1', {
resources: async () => { await new Promise(r => setTimeout(r, 150)); return { cpuPercent: 0, memoryTotalBytes: 100, memoryUsedBytes: 0 } },
disk: async () => ({ freeBytes: 100, volume: 'volume', path: '/repo' }), sqlite: builtinSqlite
});
try { console.log(JSON.stringify(await book.reserve({ creationId: process.argv[2], cwd: '/repo', requirements: { memoryBytes: 70, diskBytes: 70 } }))); }
finally { book.stop(); }
`
const run = promisify(execFile)
const answers = await Promise.all([1, 2].map(async n => {
const result = await run(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', script, f.directory, id(n)], { timeout: 15_000 })
return JSON.parse(result.stdout.trim())
}))
expect(answers.filter(r => r.ok)).toHaveLength(1)
expect(answers.filter(r => r.error)).toEqual([expect.objectContaining({ error: 'CAPACITY_UNAVAILABLE' })])
}, 20_000)
// Diego, 2026-10-30: a start the backend refused at dispatch never sent agent_create, and its row (2 GiB, 10 GiB) was held
// for good: every later start on that machine counted it, and at 256 such rows every start there failed.
it('gives back a start whose creation is still missing at the start deadline, so a later start is admitted', async () => {
const f = setup(), book = f.open(), start = (n: number) => input(n, 2 * GiB, 10 * GiB)
free(f, 3 * GiB); freeDisk(f, 15 * GiB)
expect(await book.reserve(start(1))).toMatchObject({ ok: true })
f.clock.now += START_DEADLINE_MS - 1
expect(await book.reserve(start(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('memory') })
free(f, 30 * GiB)
expect(await book.reserve(start(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('disk') })
free(f, 3 * GiB)
f.clock.now += 7 * 24 * 60 * MINUTE
expect(await book.reserve(start(2))).toMatchObject({ ok: true })
expect(await book.observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
// The review of #2361: the start may still be waiting in the backend after a host gap this long. Its next run is
// admitted again against what is free then, never ended: refused while start 2 holds the memory, then admitted.
expect(await book.reserve(start(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('memory') })
free(f, 30 * GiB); freeDisk(f, 30 * GiB)
expect(await book.reserve(start(1))).toMatchObject({ ok: true, reservationId: id(1) })
expect(await book.observe(id(1))).toMatchObject({ ok: true, released: false, harnessId: null })
})
it('times the deadline from the last run that confirmed the reservation, so a resumed start is not released under it', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.clock.now += START_DEADLINE_MS - MINUTE
// A resume confirms the same reservation and goes on to dispatch and create.
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.clock.now += 2 * MINUTE
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.observe(id(1))).toMatchObject({ released: false })
f.clock.now += START_DEADLINE_MS
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
})
// Issue #2989 (trunghieu, 2026-11-04): four dispatched 2 GiB starts that never got an agent, each failed by the Swarm ("did not
// start it within 3 minutes"), read pending or unconfirmed on the machine for good, and every later start there was refused
// with "8 GiB more is set aside for agents still starting", across a restart. Only a dispatched start has a creation, and
// the Swarm fails every dispatched start with no agent by its own start deadline.
it.each(['pending', 'unconfirmed', null] as const)('gives back a %s creation with no agent past the launch deadline, as the Swarm failed its start', async state => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.native.set(id(1), state ? { creationId: id(1), state } : null)
// Still inside the Swarm's own wait for it (up to 15 minutes while its machine reports it preparing): it may launch.
f.clock.now += LAUNCH_DEADLINE_MS - 1
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.observe(id(1))).toMatchObject({ released: false, harnessId: null })
expect(f.deps.log).not.toHaveBeenCalled()
f.clock.now += 1
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
expect(await book.observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
expect(f.deps.log).toHaveBeenCalledTimes(1)
expect(f.deps.log).toHaveBeenCalledWith(expect.stringContaining(`start receipt ${id(1)}`))
})
it('clears every stuck row on the first start after an update and restart, and still refuses a real shortage', async () => {
const f = setup(), before = f.open()
free(f, 16 * GiB)
for (const n of [1, 2, 3, 4]) {
expect(await before.reserve(agentInput(n))).toMatchObject({ ok: true })
f.native.set(id(n), { creationId: id(n), state: n % 2 ? 'pending' : 'unconfirmed' })
}
before.stop()
f.clock.now += 26 * 60 * MINUTE
free(f, 8 * GiB)
const after = f.open()
expect(await after.reserve(agentInput(5))).toMatchObject({ ok: true })
expect(f.deps.log).toHaveBeenCalledTimes(4)
for (const n of [1, 2, 3, 4]) expect(await after.observe(id(n))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
// Only the new start holds now: 8 GiB free fits three more 2 GiB starts and refuses the fourth.
for (const n of [6, 7, 8]) expect(await after.reserve(agentInput(n))).toMatchObject({ ok: true })
expect(await after.reserve(agentInput(9))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE',
detail: expect.stringMatching(/^Not enough free memory: 0 GiB free, 2 GiB needed\. 8 GiB more is set aside for 4 agents still starting/) })
})
// River on task #2890: a start the Swarm failed at 3 minutes held its memory for the whole launch deadline. Its host reads that
// verdict (machines.ts) and ends the reservation at once; the deadline stays the backstop for a verdict it never reads.
it('ends the reservation of a start the Swarm failed at once, whatever its creation reads, unless an agent launched', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.native.set(id(1), { creationId: id(1), state: 'unconfirmed' })
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.ended(id(1))).toEqual({ ok: true, reservationId: id(1), returned: true })
expect(f.deps.log).toHaveBeenCalledWith(expect.stringContaining(`start receipt ${id(1)}: the Swarm failed its start`))
expect(await book.ended(id(1))).toEqual({ ok: true, reservationId: id(1), returned: false })
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
// One whose agent launched keeps its row and identity: its host stops that agent, and the stop releases it.
free(f, 5 * GiB)
expect(await book.reserve(agentInput(3))).toMatchObject({ ok: true })
f.launch(3)
expect(await book.ended(id(3))).toEqual({ ok: true, reservationId: id(3), returned: false })
expect(await book.observe(id(3))).toMatchObject({ ok: true, harnessId: 'agent-3', released: false })
expect(await book.ended('not a creation id')).toEqual({ error: 'INVALID_REQUEST' })
})
it('keeps a creation that launched after the launch deadline, with the identity it learns', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
f.clock.now += 7 * 24 * 60 * MINUTE
f.launch(1)
expect(await book.observe(id(1))).toMatchObject({ ok: true, harnessId: 'agent-1', released: false })
expect(f.deps.log).not.toHaveBeenCalled()
})
it('keeps a launched creation that reads as missing past the deadline: its learned identity is not erased', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
await book.reserve(agentInput(1))
f.launch(1)
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'agent-1', released: false })
f.native.set(id(1), { creationId: id(1), state: 'missing' })
f.clock.now += 7 * 24 * 60 * MINUTE
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'agent-1', released: false })
// Its window is over, so it no longer holds memory either way.
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
})
it('gives a deadline row back once, and never counts it below zero', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
await book.reserve(agentInput(1))
f.clock.now += START_DEADLINE_MS
expect(await book.observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
expect(await book.observe(id(1))).toMatchObject({ error: 'CAPACITY_RECEIPT_MISSING' })
// Only the new start holds: with 3 GiB free one more 2 GiB start fits and a second does not.
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
expect(await book.reserve(agentInput(3))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
})
it('does not release a row a run confirmed again while another start was reading it as past its deadline', async () => {
const f = setup(), book = f.open(), other = f.open()
free(f, 3 * GiB)
const start = f.clock.now
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
const gate = () => { let open!: () => void; const shut = new Promise<void>(resolve => { open = resolve }); return { shut, open, reached: false } }
const disk = gate(), native = gate()
const readDisk = f.deps.disk.getMockImplementation()!, readNative = vi.mocked(f.core.agents.creationStatus!).getMockImplementation()!
f.deps.disk.mockImplementationOnce(async (...args) => { disk.reached = true; await disk.shut; return readDisk(...args) })
// A resume just inside the deadline: its reconcile reads the row as live, then it samples the disk.
f.clock.now = start + START_DEADLINE_MS - 1
const resumed = book.reserve(agentInput(1))
await vi.waitFor(() => expect(disk.reached).toBe(true))
// Another start, past the deadline, reads the same row as missing and expired.
f.clock.now = start + START_DEADLINE_MS + 1
vi.mocked(f.core.agents.creationStatus!).mockImplementationOnce(async key => { native.reached = true; await native.shut; return readNative(key) })
const later = other.reserve(agentInput(2))
await vi.waitFor(() => expect(native.reached).toBe(true))
disk.open()
expect(await resumed).toMatchObject({ ok: true })
native.open()
expect(await later).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.observe(id(1))).toMatchObject({ released: false })
})
// The review of #2361: a dispatch the backend refused for now (a paused machine, a held Team account) keeps its start
// waiting, so its row is given back and its next run reserves again.
it('gives back the reservation of a start its machine has no creation for, and admits that start again later', async () => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
expect(await book.giveBack(id(1))).toEqual({ ok: true, reservationId: id(1), returned: true })
expect(await book.giveBack(id(1))).toEqual({ ok: true, reservationId: id(1), returned: false })
expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
expect(await book.reserve(agentInput(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
free(f, 5 * GiB)
expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true, reservationId: id(1) })
})
it.each([
['pending', { creationId: id(1), state: 'pending' as const }],
['launched', { creationId: id(1), state: 'created' as const, agentId: 'agent-1' }],
['unreadable', null],
])('keeps the reservation of a %s creation when asked to give it back', async (_name, observation) => {
const f = setup(), book = f.open()
free(f, 3 * GiB)
await book.reserve(agentInput(1))
f.native.set(id(1), observation)
expect(await book.giveBack(id(1))).toMatchObject({ error: 'CREATION_PRESENT' })
expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
})
it('keeps a launched row whose creation later reads as missing, and gives back only the creation named', async () => {
const f = setup(), book = f.open()
free(f, 5 * GiB)
await book.reserve(agentInput(1)); await book.reserve(agentInput(2))
f.launch(1)
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'agent-1' })
f.native.set(id(1), { creationId: id(1), state: 'missing' })
expect(await book.giveBack(id(1))).toEqual({ ok: true, reservationId: id(1), returned: false })
expect(await book.observe(id(1))).toMatchObject({ harnessId: 'agent-1', released: false })
expect(await book.observe(id(2))).toMatchObject({ ok: true, released: false })
expect(await book.giveBack('not a creation id')).toEqual({ error: 'INVALID_REQUEST' })
})