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, describe, expect, it, vi } from 'vitest'
import type { PurgeDeps } from '../../lib/purgeAgentService.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { createResumeAgentService } from '../../lib/resumeAgentService.js'
import { AgentStopError, createStopAgentService } from '../../lib/stopAgentService.js'
import { createAgentLifecycle, createPurgeRequest, createStopRequest, LeadProtectedError, type LifecycleDeps } from './lifecycle.js'
import { IdentityReadUnavailable } from '../../engines/kit/identityScan.js'
import { GUEST_HARNESS_REFUSAL } from '../guestPolicy.js'
import { moveHeldLine } from '../../lib/hostMove/moveAgent.js'
vi.mock('../../lib/stopAgentService.js', async (real) => ({ ...await real<object>(), createStopAgentService: vi.fn(() => vi.fn(async () => {})) }))
vi.mock('../../lib/resumeAgentService.js', async (real) => ({
...await real<object>(),
createResumeAgentService: vi.fn(() => vi.fn(async () => ({ ok: true }))),
}))
// The real purge service, recording what it was built with so its callbacks can be driven directly.
vi.mock('../../lib/purgeAgentService.js', async (real) => {
const actual = await real<typeof import('../../lib/purgeAgentService.js')>()
class RecordingPurgeAgentService extends actual.PurgeAgentService {
constructor(readonly given: PurgeDeps) { super(given) }
}
return { ...actual, PurgeAgentService: RecordingPurgeAgentService }
})
const row = (over: Partial<RegisteredSession> = {}) => ({ agentId: 'a1', sessionId: 's1', cwd: '/work', ...over }) as RegisteredSession
function setup(over: Partial<LifecycleDeps> = {}) {
const deps: LifecycleDeps = {
registry: {
byAgent: vi.fn(() => row()),
resolve: vi.fn((id: string) => (id === 'a1' || id === 's1' ? row() : undefined)),
list: vi.fn(() => [row()]),
deleteSavedNames: vi.fn(),
} as unknown as LifecycleDeps['registry'],
stoppedAgents: { list: vi.fn(() => [row({ agentId: 'a2' })]), get: vi.fn(() => undefined) } as unknown as LifecycleDeps['stoppedAgents'],
restartJobs: { busy: vi.fn(() => false) } as unknown as LifecycleDeps['restartJobs'],
createBackend: null,
backendFor: vi.fn(() => undefined),
agentReconciler: {} as never,
forgetSession: vi.fn(),
markDeleted: vi.fn(),
clearDeleted: vi.fn(),
stopNative: vi.fn(async () => {}),
sessionCheckpoints: {} as never,
mirror: { deleteHistory: vi.fn() },
sessionSearch: { deleteHistory: vi.fn() },
send: vi.fn(),
pinnedControls: new Set<string>(),
retainExitedSession: vi.fn(),
announceSession: vi.fn(),
relaunchOverrides: vi.fn() as never,
prepareSessionResume: vi.fn(),
refreshGridWebSearch: vi.fn(),
attachDsh: vi.fn(),
attachSession: vi.fn(async () => true),
...over,
}
const lifecycle = createAgentLifecycle(deps)
const purge = (lifecycle.purgeAgentService as unknown as { given: PurgeDeps }).given
return { deps, lifecycle, purge }
}
describe('stopping, purging and resuming an agent', () => {
afterEach(() => { vi.restoreAllMocks(); vi.clearAllMocks() })
it('builds stop on one map of stops in flight, which resume and the lifecycle share', () => {
const { deps, lifecycle } = setup()
expect(createStopAgentService).toHaveBeenCalledWith({
registry: deps.registry, stoppedAgents: deps.stoppedAgents, restartJobs: deps.restartJobs, stopJobs: lifecycle.stopJobs,
backendFor: deps.backendFor, agentReconciler: deps.agentReconciler, forgetSession: deps.forgetSession,
markDeleted: deps.markDeleted, clearDeleted: deps.clearDeleted, stopNative: deps.stopNative,
})
expect(createResumeAgentService).toHaveBeenCalledWith({
registry: deps.registry, stoppedAgents: deps.stoppedAgents, createBackend: null, backendFor: deps.backendFor, restartJobs: deps.restartJobs,
stopJobs: lifecycle.stopJobs, pinnedControls: deps.pinnedControls, retainExitedSession: deps.retainExitedSession,
announceSession: deps.announceSession, relaunchOverrides: deps.relaunchOverrides, prepareSessionResume: deps.prepareSessionResume,
refreshGridWebSearch: deps.refreshGridWebSearch, clearDeleted: deps.clearDeleted, attachDsh: deps.attachDsh,
attachSession: deps.attachSession,
})
})
it('stops through the stop service, then tells the cleanup the agent was stopped, never while the stop can fail', async () => {
// A harness closed takes the harnesses it started with it (services/agentCleanup.ts): a window's close and Stop
// Harness, `harness close` and a purge all stop through here.
const stopped = vi.fn()
const { lifecycle } = setup({ stopped })
const stop = vi.mocked(createStopAgentService).mock.results[0].value as ReturnType<typeof vi.fn>
const options = { current: () => true }
await lifecycle.stopAgent('s1', options)
expect(stop).toHaveBeenCalledWith('s1', options)
expect(stopped).toHaveBeenCalledWith('a1')
// One already gone is told by the id it was asked by: its harnesses are orphans all the same.
await lifecycle.stopAgent('gone')
expect(stopped).toHaveBeenLastCalledWith('gone')
stop.mockRejectedValueOnce(new AgentStopError('Harness changed while saving its conversation. Try stopping again.'))
await expect(lifecycle.stopAgent('a1')).rejects.toThrow('Harness changed')
expect(stopped).toHaveBeenCalledTimes(2)
// With nobody to tell, a stop is a stop.
await expect(setup().lifecycle.stopAgent('a1')).resolves.toBeUndefined()
})
// The owner, 2026-10-23: the Lead of an active project is never stopped, in any case. Every stop goes through here (a
// window's close and Stop Harness, `harness close`, a purge, the cleanup), so one guard refuses them all.
it('refuses to stop a Swarm Lead, by agent or session id, and stops nothing', async () => {
const stopped = vi.fn(), leadProtected = vi.fn((agentId: string) => agentId === 'a1')
const { lifecycle } = setup({ stopped, leadProtected })
const stop = vi.mocked(createStopAgentService).mock.results[0].value as ReturnType<typeof vi.fn>
for (const target of ['a1', 's1']) {
const refusal = await lifecycle.stopAgent(target).catch((error: unknown) => error)
expect(refusal).toBeInstanceOf(LeadProtectedError)
expect(refusal).toMatchObject({ code: 'LEAD_PROTECTED', message: expect.stringContaining('Delete its project first') })
}
expect(stop).not.toHaveBeenCalled()
expect(stopped).not.toHaveBeenCalled()
await lifecycle.stopAgent('gone')
expect(stop).toHaveBeenCalledWith('gone', undefined)
})
// Security review 1 of #2493: only the stop a Product Manager's switch makes carries that switch to the guard; every other
// stop asks without one (superTabs/leadSwitch.ts decides).
it('asks the Lead guard with the switch a stop carries, and without one for any other stop', async () => {
const CHANGE = 'a'.repeat(32)
const leadProtected = vi.fn((agentId: string, leadSwitch?: string) => agentId === 'a1' && leadSwitch !== CHANGE)
const { lifecycle } = setup({ leadProtected })
const stop = vi.mocked(createStopAgentService).mock.results[0].value as ReturnType<typeof vi.fn>
await expect(lifecycle.stopAgent('a1')).rejects.toBeInstanceOf(LeadProtectedError)
await expect(lifecycle.stopAgent('a1', { leadSwitch: 'b'.repeat(32) })).rejects.toBeInstanceOf(LeadProtectedError)
expect(stop).not.toHaveBeenCalled()
await lifecycle.stopAgent('a1', { leadSwitch: CHANGE })
expect(stop).toHaveBeenCalledWith('a1', { leadSwitch: CHANGE })
expect(leadProtected.mock.calls.map(call => call[1])).toEqual([undefined, 'b'.repeat(32), CHANGE])
})
describe('purge', () => {
it('sees live and stopped agents, stops through the stop service, and checkpoints where stop does', () => {
const { deps, lifecycle, purge } = setup()
expect(purge.live('a1')).toEqual(row())
expect(deps.registry.byAgent).toHaveBeenCalledWith('a1')
expect(purge.sessions()).toEqual([row(), row({ agentId: 'a2' })])
expect(purge.stopped).toBe(deps.stoppedAgents)
expect(purge.checkpoints).toBe(deps.sessionCheckpoints)
expect(purge.stop).toBe(lifecycle.stopAgent)
expect(purge.leadProtected).toBeUndefined()
})
// Security review 2 of #2493: a Product Manager's saved conversation is never deleted; the purge asks the same guard.
it('hands the purge the Lead guard, asked without a switch', () => {
const leadProtected = vi.fn((agentId: string) => agentId === 'a1')
const { purge } = setup({ leadProtected })
expect([purge.leadProtected?.('a1'), purge.leadProtected?.('a2')]).toEqual([true, false])
expect(leadProtected.mock.calls).toEqual([['a1'], ['a2']])
})
it('asks the pane, through the core, whether an agent waits at its folder-trust question', () => {
const atFolderTrust = vi.fn(async () => true)
const atEmptyComposer = vi.fn(async () => true)
const { purge } = setup({ atFolderTrust, atEmptyComposer })
expect(purge.atFolderTrust).toBe(atFolderTrust)
expect(purge.atEmptyComposer).toBe(atEmptyComposer)
})
it('waits on an agent that is restarting or stopping', () => {
const restarting = setup({ restartJobs: { busy: vi.fn((id: string) => id === 'a1') } as never })
expect(restarting.purge.restarting('a1')).toBe(true)
const { lifecycle, purge } = setup()
expect(purge.restarting('a1')).toBe(false)
lifecycle.stopJobs.set('a1', Promise.resolve())
expect(purge.restarting('a1')).toBe(true)
})
it('forgets a deleted conversation\'s lines, search entries and names, and tells every window', () => {
const { deps, purge } = setup()
purge.deleted(row())
expect(deps.mirror.deleteHistory).toHaveBeenCalledWith('s1')
expect(deps.sessionSearch?.deleteHistory).toHaveBeenCalledWith('s1')
expect(deps.registry.deleteSavedNames).toHaveBeenCalledWith(['a1', 's1'])
expect(deps.send).toHaveBeenCalledWith({ type: 'agent_deleted', payload: { agentId: 'a1', retained: false } })
})
it('with no session yet, or no search index, forgets only what there is', () => {
const { deps, purge } = setup({ sessionSearch: null })
purge.deleted(row())
expect(deps.mirror.deleteHistory).toHaveBeenCalledWith('s1')
purge.deleted(row({ sessionId: '' }))
expect(deps.mirror.deleteHistory).toHaveBeenCalledTimes(1)
expect(deps.registry.deleteSavedNames).toHaveBeenLastCalledWith(['a1'])
})
})
describe('resume', () => {
it('goes ahead for an agent no purge holds, with the mode asked for', async () => {
const { deps, lifecycle } = setup()
expect(await lifecycle.resumeAgent('a1', 'plan')).toEqual({ ok: true })
const resume = vi.mocked(createResumeAgentService).mock.results[0].value
expect(resume).toHaveBeenCalledWith('a1', 'plan', undefined)
expect(deps.stoppedAgents.get).toHaveBeenCalledWith('a1')
})
it('carries the owner\'s new launch words to the resume', async () => {
const { lifecycle } = setup()
await lifecycle.resumeAgent('a1', undefined, ['--chrome'])
expect(vi.mocked(createResumeAgentService).mock.results[0].value).toHaveBeenCalledWith('a1', undefined, ['--chrome'])
})
it('resumes no guest\'s harness, stopped or running: it would run as the owner', async () => {
const stopped = setup({ stoppedAgents: { list: () => [], get: vi.fn(() => row({ guest: '[email protected]' })) } as never })
expect(await stopped.lifecycle.resumeAgent('a1')).toEqual(GUEST_HARNESS_REFUSAL)
const running = setup({ stoppedAgents: { list: () => [], get: vi.fn(() => undefined) } as never })
vi.spyOn(running.deps.registry, 'byAgent').mockReturnValue(row({ guest: '[email protected]' }))
expect(await running.lifecycle.resumeAgent('a1')).toEqual(GUEST_HARNESS_REFUSAL)
expect(vi.mocked(createResumeAgentService).mock.results.every((r) => !vi.mocked(r.value).mock.calls.length)).toBe(true)
})
it('starts no engine for an agent a stopped move may still run beside, stopped or running, this start', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const held = setup({ moveHeld: (id) => id === 'a1', stoppedAgents: { list: () => [], get: vi.fn(() => row()) } as never })
expect(await held.lifecycle.resumeAgent('a1')).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(vi.mocked(createResumeAgentService).mock.results.at(-1)!.value).not.toHaveBeenCalled()
expect(warn).toHaveBeenCalledWith(moveHeldLine('a1'))
warn.mockRestore()
})
it('holds an id that no store knows by that id, as given', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const held = setup({ moveHeld: (id) => id === 'ghost', stoppedAgents: { list: () => [], get: vi.fn(() => undefined) } as never })
vi.spyOn(held.deps.registry, 'byAgent').mockReturnValue(undefined)
expect(await held.lifecycle.resumeAgent('ghost')).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(warn).toHaveBeenCalledWith(moveHeldLine('ghost'))
warn.mockRestore()
})
it('waits while the agent is being purged, or while a purge holds its folder', async () => {
const busy = setup()
vi.spyOn(busy.lifecycle.purgeAgentService, 'busy').mockReturnValue(true)
expect(await busy.lifecycle.resumeAgent('a1')).toEqual({ ok: false, error: 'AGENT_BUSY' })
const folder = setup({ stoppedAgents: { list: () => [], get: vi.fn(() => row({ cwd: '/work/tree' })) } as never })
const blocks = vi.spyOn(folder.lifecycle.purgeAgentService, 'blocksFolder').mockReturnValue(true)
expect(await folder.lifecycle.resumeAgent('a1')).toEqual({ ok: false, error: 'AGENT_BUSY' })
expect(blocks).toHaveBeenCalledWith('/work/tree')
expect(vi.mocked(createResumeAgentService).mock.results[1].value).not.toHaveBeenCalled()
})
})
})
describe('agent_delete', () => {
const agents = new Map([['a1', { agentId: 'a1', sessionId: 's1' }], ['pending', { agentId: 'pending', sessionId: '' }]]) as unknown as Map<string, RegisteredSession>
const request = (stop: (agentId: string) => Promise<void>) => createStopRequest({ byAgent: (id) => agents.get(id), stop })
it('stops the agent the frame names, by agent id or session id, and says so', async () => {
const stop = vi.fn(async () => {})
expect(await request(stop)({ agentId: 'a1' })).toStrictEqual({ deleted: true })
expect(await request(stop)({ sessionId: 's9' })).toStrictEqual({ deleted: true })
expect(stop.mock.calls).toEqual([['a1'], ['s9']])
expect(await request(stop)({})).toStrictEqual({ error: 'MISSING_AGENT_ID' })
expect(stop).toHaveBeenCalledTimes(2)
})
it('refuses a stop for a conversation that changed since it was reviewed', async () => {
const stop = vi.fn(async () => {})
const changed = await request(stop)({ agentId: 'a1', expectedSessionId: 's0' })
expect(changed).toStrictEqual({ error: 'SESSION_CHANGED', detail: 'This conversation changed. Refresh and review it before stopping.' })
expect(Object.keys(changed)).toEqual(['error', 'detail'])
expect(await request(stop)({ agentId: 'gone', expectedSessionId: 's1' })).toMatchObject({ error: 'SESSION_CHANGED' })
expect(stop).not.toHaveBeenCalled()
// The conversation it reviewed: none yet, or the same one.
expect(await request(stop)({ agentId: 'pending', expectedSessionId: null })).toStrictEqual({ deleted: true })
expect(await request(stop)({ agentId: 'a1', expectedSessionId: 's1' })).toStrictEqual({ deleted: true })
})
it('says a stop it could not confirm was not confirmed, and lets any other failure through', async () => {
const unconfirmed = await request(async () => { throw new AgentStopError('The process could not be verified.') })({ agentId: 'a1' })
expect(unconfirmed).toStrictEqual({ error: 'STOP_UNCONFIRMED', detail: 'The process could not be verified.' })
expect(Object.keys(unconfirmed)).toEqual(['error', 'detail'])
await expect(request(async () => { throw new Error('tmux gone') })({ agentId: 'a1' })).rejects.toThrow('tmux gone')
})
it('says why a Swarm Lead is not stopped', async () => {
const refused = await request(async () => { throw new LeadProtectedError() })({ agentId: 'a1' })
expect(refused).toStrictEqual({ error: 'LEAD_PROTECTED', detail: new LeadProtectedError().message })
})
it('returns an unavailable native identity as a retryable hold and permits the same Stop after recovery', async () => {
const error = new IdentityReadUnavailable('the native record is incomplete')
const stop = vi.fn().mockRejectedValueOnce(error).mockResolvedValueOnce(undefined)
const run = request(stop)
expect(await run({ agentId: 'a1' })).toStrictEqual({ error: error.code, detail: error.message, held: true, retryable: true })
expect(await run({ agentId: 'a1' })).toStrictEqual({ deleted: true })
expect(stop.mock.calls).toEqual([['a1'], ['a1']])
})
})
describe('agent_purge and agent_worktree_delete', () => {
const OWNER = { owner: true }
const reviewed = { agentId: 'a1', sessionId: 's1', createdAt: 1234, mode: 'inspect' }
function setup(service: { request: ReturnType<typeof vi.fn>; worktreeRequest: ReturnType<typeof vi.fn> } | null = {
request: vi.fn(async () => ({ reviewId: 'review' })), worktreeRequest: vi.fn(async () => ({ reviewId: 'review' })),
}) {
const invalidateStorage = vi.fn()
const replies: Array<Record<string, unknown>> = []
const purge = createPurgeRequest({ purgeAgentService: () => service as never, invalidateStorage })
const ask = (type: string, payload: Record<string, unknown>, asker = OWNER) => purge(type, payload, asker, (result) => { replies.push(result) })
return { service, invalidateStorage, replies, ask }
}
it('is the owner\'s alone, and needs a purge service to ask', () => {
const { service, replies, ask } = setup()
ask('agent_purge', reviewed, { owner: false })
expect(replies).toStrictEqual([{ error: 'OWNER_REQUIRED' }])
expect(service!.request).not.toHaveBeenCalled()
const none = setup(null)
none.ask('agent_purge', reviewed)
expect(none.replies).toStrictEqual([{ error: 'UNSUPPORTED' }])
})
it('refuses a request that does not name what was reviewed, or a deletion without its review', () => {
const { service, replies, ask } = setup()
for (const wrong of [
{ ...reviewed, agentId: 7 }, { ...reviewed, sessionId: undefined }, { ...reviewed, createdAt: '1234' },
{ ...reviewed, createdAt: Number.NaN }, { ...reviewed, mode: 'erase' }, { ...reviewed, mode: 'describe' },
{ ...reviewed, mode: 'delete' }, { ...reviewed, choices: 'all' }, { ...reviewed, choices: null },
{ ...reviewed, choices: { sessionData: true, worktreeData: 'yes' } }, { ...reviewed, choices: { sessionData: 1, worktreeData: true } },
]) ask('agent_purge', wrong)
expect(replies).toStrictEqual(Array.from({ length: 11 }, () => ({ error: 'INVALID_DELETE_REQUEST' })))
expect(service!.request).not.toHaveBeenCalled()
})
it('hands the purge service exactly what was reviewed and chosen, and answers once it is done', async () => {
let done!: (result: Record<string, unknown>) => void
const { service, invalidateStorage, replies, ask } = setup({ request: vi.fn(() => new Promise((resolve) => { done = resolve })), worktreeRequest: vi.fn() })
ask('agent_purge', { ...reviewed, sessionId: null, mode: 'delete', reviewId: 'review', path: '/reviewed', discardChanges: true,
includeWorktree: true, choices: { sessionData: false, worktreeData: true }, requestId: 'r' })
const deletion = service!.request.mock.calls[0][0]
expect(deletion).toStrictEqual({ agentId: 'a1', sessionId: null, createdAt: 1234, mode: 'delete', reviewId: 'review', path: '/reviewed',
discardChanges: true, includeWorktree: true, choices: { sessionData: false, worktreeData: true } })
expect(Object.keys(deletion)).toEqual(['agentId', 'sessionId', 'createdAt', 'mode', 'reviewId', 'path', 'discardChanges', 'includeWorktree', 'choices'])
expect(replies).toEqual([])
done({ deleted: true })
await vi.waitFor(() => expect(replies).toStrictEqual([{ deleted: true }]))
expect(invalidateStorage).toHaveBeenCalledOnce()
ask('agent_purge', { ...reviewed, discardChanges: 'yes' })
expect(service!.request).toHaveBeenLastCalledWith({ ...reviewed, discardChanges: false, includeWorktree: false })
})
it('describes, inspects and deletes a worktree through the worktree request, and forgets storage only once something went', async () => {
const results = [{ worktreeDeleted: true }, { reviewId: 'review' }]
const { service, invalidateStorage, replies, ask } = setup({ request: vi.fn(), worktreeRequest: vi.fn(async () => results.shift()) })
ask('agent_worktree_delete', { ...reviewed, mode: 'describe' })
ask('agent_worktree_delete', reviewed)
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(service!.worktreeRequest.mock.calls.map(([request]) => request.mode)).toEqual(['describe', 'inspect'])
expect(service!.request).not.toHaveBeenCalled()
expect(invalidateStorage).toHaveBeenCalledOnce()
})
it('says a deletion that failed failed', async () => {
const { replies, ask } = setup({ request: vi.fn(async () => { throw new Error('disk full') }), worktreeRequest: vi.fn() })
ask('agent_purge', reviewed)
await vi.waitFor(() => expect(replies).toStrictEqual([{ error: 'DELETE_FAILED' }]))
})
})