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 { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { installedDsh } from '../../dsh/installed.js'
import { dshSupportedEngines } from '../../dsh/manifest.js'
import { loadEngine } from '../../engines/inProcess.js'
import { opencodeMajorVersion } from '../../engines/launchControl.js'
import type { NativeLaunchResult } from '../../engines/nativeLaunch.js'
import { createNativeLaunchPreparer } from '../../engines/prepareNativeLaunch.js'
import { AgentCreationReceiptError, AgentCreationReceipts, creationFingerprint, type AgentCreationOutcome } from '../../lib/agentCreationReceipt.js'
import type { AgentFrame } from '../../lib/agentFrame.js'
import { MAX_FIRST_PROMPT_CHARS, permissionModeApproves, permissionModeFlags, supportsFirstPrompt, supportsNamedAgent, unsupportedLaunchModelFlag } from '../../lib/engineLaunch.js'
import { parseGridLaunchOverride } from '../../lib/gridLaunchWire.js'
import { parseNewAgentModel } from '../../lib/newAgentModel.js'
import { parseProjectFolder, prepareProjectFolder, ProjectFolderError, RepositoryAccessError } from '../../lib/projectFolder.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { createLaunchRequests, type CreateAgent, type ForkAgent, type LaunchRequestDeps, type RestartAgent, type ResumeAgent } from './launches.js'
import * as pendingLaunches from './pendingLaunches.js'
import { SWARM_LAUNCH } from '../../superTabs/inCore/launch.js'
/**
* The requests that start an agent's process, answered by the core: every refusal before a pane exists,
* what each launch is handed, the receipts that let a lost answer be asked for again, and the replies,
* field for field. Trust records, grid reads, project folders and installed harnesses are fakes here:
* they are tested with their own modules, and a test must never write the person's own engine config.
*/
const root = vi.hoisted(() => ({ projects: '' }))
const host = vi.hoisted(() => ({ win32: false }))
vi.mock('../../engines/kit/windowsFiles.js', async (real) => {
const actual = await real<typeof import('../../engines/kit/windowsFiles.js')>()
return { ...actual, hostPlatform: () => host.win32 ? 'win32' : actual.hostPlatform() }
})
// The engines' folder trust (engines/launchPrep.ts), one spy per engine.
const trust = vi.hoisted(() => ({
claudeTrusts: vi.fn((_path: string) => false), codexTrusts: vi.fn((_path: string, _profile?: string | null) => false),
preTrustClaudeProject: vi.fn((_path: string): unknown => undefined), preTrustCodexProject: vi.fn((_path: string, _profile?: string | null): unknown => undefined),
}))
const { claudeTrusts, codexTrusts, preTrustClaudeProject, preTrustCodexProject } = trust
vi.mock('../../engines/launchPrep.js', () => ({ folderTrust: (engine: string, profile?: string | null) => engine === 'claude'
? { trusts: (path: string) => trust.claudeTrusts(path), record: (path: string) => trust.preTrustClaudeProject(path) }
: engine === 'codex' ? { trusts: (path: string) => trust.codexTrusts(path, profile), record: (path: string) => trust.preTrustCodexProject(path, profile) } : null }))
// OpenCode's version probe is its own code, loaded for an OpenCode launch alone; a test may say it could not be.
vi.mock('../../engines/inProcess.js', async (real) => {
const actual = await real<typeof import('../../engines/inProcess.js')>()
return { ...actual, loadEngine: vi.fn(actual.loadEngine) }
})
vi.mock('../../engines/launchControl.js', async (real) => ({ ...await real<object>(), opencodeMajorVersion: vi.fn(() => 1) }))
vi.mock('../../lib/newAgentModel.js', async (real) => ({
...await real<object>(), parseNewAgentModel: vi.fn(() => ({ state: 'absent' })),
}))
vi.mock('../../lib/gridLaunchWire.js', async (real) => ({ ...await real<object>(), parseGridLaunchOverride: vi.fn(() => ({ state: 'absent' })) }))
vi.mock('../../dsh/installed.js', async (real) => ({ ...await real<object>(), installedDsh: vi.fn(() => undefined) }))
vi.mock('../../dsh/manifest.js', async (real) => ({ ...await real<object>(), dshSupportedEngines: vi.fn(() => ['claude', 'codex']) }))
vi.mock('../../lib/engineLaunch.js', async (real) => ({
...await real<object>(),
supportsFirstPrompt: vi.fn(() => true), supportsNamedAgent: vi.fn(() => true),
permissionModeFlags: vi.fn(() => ['--flag']), permissionModeApproves: vi.fn(() => false),
// The engine's own --help is never run by a spec.
unsupportedLaunchModelFlag: vi.fn(async () => null),
}))
vi.mock('../../lib/projectFolder.js', async (real) => {
const actual = await real<typeof import('../../lib/projectFolder.js')>()
return { ...actual, parseProjectFolder: vi.fn(actual.parseProjectFolder), prepareProjectFolder: vi.fn(async () => '/projects/prepared'), projectsRoot: vi.fn(() => root.projects) }
})
const CREATION = 'creation-0123456789abcdef'
/** Where the models service resolves a new agent's grid model (core/api.ts `ModelsPort.launchTarget`). */
const resolveNewAgentModel = vi.fn<LaunchRequestDeps['modelTarget']>()
const session = (agentId = 'a1', over: Partial<RegisteredSession> = {}) => ({ agentId, sessionId: `${agentId}-session`, engine: 'claude', ...over }) as RegisteredSession
const frameOf = (s: RegisteredSession) => ({ id: s.agentId }) as unknown as AgentFrame
const settle = () => new Promise((resolve) => setTimeout(resolve, 0))
let dir: string
let stores = 0
const stopRequests: Array<() => void> = []
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'launches-'))
root.projects = join(dir, 'harnesses')
mkdirSync(root.projects)
})
afterEach(() => {
stopRequests.splice(0).forEach(stop => stop())
rmSync(dir, { recursive: true, force: true })
vi.restoreAllMocks()
vi.resetAllMocks()
})
function setup(over: Partial<LaunchRequestDeps> = {}, launches: { create?: CreateAgent | null; fork?: ForkAgent | null; resume?: ResumeAgent | null; restart?: RestartAgent | null } = {}) {
const create = launches.create === undefined ? vi.fn(async () => ({ ok: true as const, session: session('new-agent') })) : launches.create
const fork = launches.fork === undefined ? vi.fn(async () => ({ ok: true as const, session: session('forked'), level: 'native' as const })) : launches.fork
const resume = launches.resume === undefined ? vi.fn(async () => ({ ok: true as const, session: session('a1'), resumed: true })) : launches.resume
const restart = launches.restart === undefined ? vi.fn(async () => ({ ok: true as const, session: session('a1'), resumed: false })) : launches.restart
const known = new Map([['new-agent', session('new-agent')], ['forked', session('forked')], ['a1', session('a1')]])
const deps: LaunchRequestDeps = {
receipts: new AgentCreationReceipts(join(dir, `receipts-${++stores}`)),
createAgent: () => create, forkAgent: () => fork, resumeAgent: () => resume, restartAgent: () => restart,
byAgent: (id) => known.get(id), toProject: vi.fn(async (s: RegisteredSession) => frameOf(s)),
modelTarget: resolveNewAgentModel,
swarmLaunch: SWARM_LAUNCH,
stoppedAgent: () => undefined,
...over,
}
const requests = createLaunchRequests(deps)
stopRequests.push(requests.stop)
const replies: Array<Record<string, unknown>> = []
const reply = (result: Record<string, unknown>) => { replies.push(result) }
return {
deps, create, fork, resume, restart, replies, requests,
ask: async (payload: Record<string, unknown>, local = true) => { await requests.create(payload, { local }, reply); return replies.at(-1) },
status: async (payload: Record<string, unknown>) => { await requests.createStatus(payload, { local: true }, reply); return replies.at(-1) },
// An app of the owner's own unless a test says otherwise: only that asker may change an agent's launch flags.
relaunch: async (type: string, payload: Record<string, unknown>, asker: { ownerApp: boolean } = { ownerApp: true }) => { await requests.relaunch(type, payload, reply, asker); return replies.at(-1) },
forkAsk: async (payload: Record<string, unknown>) => { await requests.fork(payload, reply); return replies.at(-1) },
}
}
describe('agent_create, refused before any pane exists', () => {
it('keeps a selected model pending before native preparation, then dispatches its fresh resolution once', async () => {
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
const grid = { networkId: 'fixture', networkName: 'Fixture', baseUrl: 'http://fixture.invalid', apiKey: 'fixture' }
resolveNewAgentModel.mockResolvedValueOnce(null).mockResolvedValue(grid)
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: true, dispatch }))
const run = setup({ prepareCreate })
const input = { creationId: CREATION, engine: 'claude', cwd: '/fixture/work', prompt: 'original prompt' }
await run.ask(input)
await vi.waitFor(() => expect(run.replies[0]).toMatchObject({ state: 'pending', held: { service: 'models' } }))
expect(prepareCreate).not.toHaveBeenCalled()
await run.ask(input)
await vi.waitFor(() => expect(run.replies[1]).toMatchObject({ state: 'created' }))
expect(prepareCreate).toHaveBeenCalledWith(expect.objectContaining({ grid, prompt: 'original prompt' }), expect.any(Object), { local: true })
expect(dispatch).toHaveBeenCalledOnce()
})
it('names models when its selected-model request rejects before native preparation', async () => {
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
const prepareCreate = vi.fn()
const run = setup({ prepareCreate, modelTarget: async () => { throw Error('models disconnected') } })
await run.ask({ creationId: CREATION, engine: 'claude', cwd: '/fixture/work' })
await vi.waitFor(() => expect(run.replies[0]).toMatchObject({ state: 'pending', held: { service: 'models' } }))
expect(prepareCreate).not.toHaveBeenCalled()
})
it.each(['model', 'native'] as const)('retains durable cancellation while %s preparation settles', async phase => {
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
const run = setup({
modelTarget: async () => {
if (phase === 'model') run.deps.receipts.cancelIntent(CREATION)
return { networkId: 'fixture', networkName: 'Fixture', baseUrl: 'http://fixture.invalid', apiKey: 'fixture' }
},
prepareCreate: async () => {
run.deps.receipts.cancelIntent(CREATION)
return { ok: true, dispatch }
},
})
await run.ask({ creationId: CREATION, engine: 'claude', cwd: '/fixture/work' })
await vi.waitFor(() => expect(run.replies[0]).toMatchObject({ state: 'cancelled' }))
expect(dispatch).not.toHaveBeenCalled()
})
it.each(['refused', 'bare refusal', 'held', 'uncertain dispatch'] as const)('records native preparation outcomes truthfully: %s', async outcome => {
const dispatch = vi.fn(async () => ({ ok: false as const, error: 'SPAWN_FAILED' }))
const run = setup({ prepareCreate: async () => outcome === 'uncertain dispatch' ? { ok: true, dispatch }
: outcome === 'held' ? { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native' }
: { ok: false, error: 'PERMISSION_MODE_UNSUPPORTED', ...(outcome === 'refused' ? { detail: 'Unsupported fixture mode.' } : {}) } })
const payload = { creationId: CREATION, engine: 'claude', cwd: '/fixture/work' }
await run.ask(payload)
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
expect(run.replies[0]).toMatchObject(outcome === 'held' ? { state: 'pending', held: { service: 'native', detail: 'Waiting for launch preparation.' } }
: outcome === 'uncertain dispatch' ? { state: 'unconfirmed' } : { state: 'failed', failure: { code: 'PERMISSION_MODE_UNSUPPORTED' } })
await run.ask(payload)
await vi.waitFor(() => expect(run.replies).toHaveLength(2))
expect(dispatch).toHaveBeenCalledTimes(outcome === 'uncertain dispatch' ? 1 : 0)
})
it('fences a prepared native dispatch if receipt authority changes before invocation', async () => {
let prepare!: Parameters<typeof pendingLaunches.createPendingLaunches>[0]['prepare']
const factory = pendingLaunches.createPendingLaunches
vi.spyOn(pendingLaunches, 'createPendingLaunches').mockImplementation(deps => { prepare = deps.prepare; return factory(deps) })
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
setup({ prepareCreate: async () => ({ ok: true, dispatch }) })
let current = true
const ready = await prepare({ kind: 'native-create-v1', input: { engine: 'claude', cwd: '/fixture/work' },
label: 'harness-claude-fixture', local: false }, { id: CREATION, current: () => current, hold: vi.fn() })
expect(ready).not.toBeNull()
current = false
expect(await ready!()).toEqual({ state: 'unconfirmed' })
expect(dispatch).not.toHaveBeenCalled()
expect(preTrustClaudeProject).not.toHaveBeenCalled()
})
it('recovers native and later service holds with the same request label and original authority', async () => {
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>().mockResolvedValueOnce({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Waiting for installation.' })
.mockResolvedValueOnce({ ok: false, error: 'GRID_UNAVAILABLE', unavailable: 'models', detail: 'Waiting for models.' })
.mockImplementation(async (_input, authority) => ({ ok: true, dispatch: async () => { expect(authority.current()).toBe(true); return dispatch() } }))
const first = setup({ prepareCreate })
const input = { creationId: CREATION, engine: 'codex', cwd: '/fixture/work', codexHome: '/fixture/profile', prompt: 'fixture first prompt' }
await first.ask(input, false)
await vi.waitFor(() => expect(first.replies[0]).toMatchObject({ state: 'pending', held: { service: 'native' } }))
const label = prepareCreate.mock.calls[0]![1].label
const saved = first.deps.receipts.pendingIntent(CREATION)!
expect(saved.request).toMatchObject({ local: false, label, input: { prompt: 'fixture first prompt', codexHome: '/fixture/profile' } })
first.requests.stop()
const second = setup({ prepareCreate, receipts: first.deps.receipts })
await second.ask(input, true)
await vi.waitFor(() => expect(second.replies[0]).toMatchObject({ state: 'pending', held: { service: 'models' } }))
await second.ask(input, true)
await vi.waitFor(() => expect(dispatch).toHaveBeenCalledOnce())
expect(prepareCreate.mock.calls.every(([, authority]) => authority.label === label && authority.id === CREATION)).toBe(true)
expect(first.create).not.toHaveBeenCalled()
expect(second.create).not.toHaveBeenCalled()
expect(first.deps.receipts.status(CREATION)).toEqual({ state: 'created', agentId: 'new-agent' })
expect(preTrustCodexProject).not.toHaveBeenCalled()
await second.ask(input)
await settle()
expect(dispatch).toHaveBeenCalledOnce()
})
it('an engine it does not know, a folder it cannot read, or a cwd that is not an absolute path', async () => {
const { ask, create } = setup()
expect(await ask({ cwd: '/w' })).toStrictEqual({ error: 'INVALID_ENGINE' })
expect(await ask({ engine: 'gpt', cwd: '/w' })).toStrictEqual({ error: 'INVALID_ENGINE' })
expect(await ask({ engine: 'claude', projectSource: 'bogus' })).toStrictEqual({ error: 'INVALID_PROJECT_SOURCE', detail: 'Choose a project.' })
vi.mocked(parseProjectFolder).mockImplementationOnce(() => { throw new Error('unexpected') })
expect(await ask({ engine: 'claude', projectSource: 'new' })).toStrictEqual({ error: 'INVALID_PROJECT_SOURCE' })
expect(await ask({ engine: 'terminal', projectSource: 'new', creationId: CREATION }))
.toStrictEqual({ error: 'INVALID_PROJECT_SOURCE', detail: 'a terminal opens in a folder, it does not prepare one' })
expect(await ask({ engine: 'claude', cwd: 'relative/path' })).toStrictEqual({ error: 'INVALID_CWD' })
expect(await ask({ engine: 'claude' })).toStrictEqual({ error: 'INVALID_CWD' })
expect(await ask({ engine: 'terminal', cwd: 'relative' })).toStrictEqual({ error: 'INVALID_CWD' })
expect(create).not.toHaveBeenCalled()
})
it('on a machine that cannot launch, a creation id that is not one, and a folder asked for without a receipt or beside a cwd', async () => {
expect(await setup({}, { create: null }).ask({ engine: 'claude', cwd: '/w' })).toStrictEqual({ error: 'UNSUPPORTED_ON_REMOTE' })
const { ask } = setup()
expect(await ask({ engine: 'claude', cwd: '/w', creationId: 'short' })).toStrictEqual({ error: 'INVALID_CREATION_ID' })
expect(await ask({ engine: 'claude', projectSource: 'new' })).toStrictEqual({ error: 'INVALID_PROJECT_SOURCE' })
expect(await ask({ engine: 'claude', projectSource: 'new', creationId: CREATION, cwd: '/w' })).toStrictEqual({ error: 'INVALID_PROJECT_SOURCE' })
})
it('a model or grid that is not one, a grid for a terminal, and a codexHome anywhere but on codex without a grid', async () => {
const { ask, create } = setup()
vi.mocked(parseNewAgentModel).mockReturnValueOnce({ state: 'invalid', detail: 'no such model' } as never)
expect(await ask({ engine: 'claude', cwd: '/w' })).toStrictEqual({ error: 'INVALID_GRID', detail: 'no such model' })
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'invalid', reason: 'no baseUrl' } as never)
expect(await ask({ engine: 'claude', cwd: '/w' })).toStrictEqual({ error: 'INVALID_GRID', detail: 'no baseUrl' })
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'ok', override: { networkId: 'g' } } as never)
expect(await ask({ engine: 'terminal' })).toStrictEqual({ error: 'INVALID_GRID', detail: 'a terminal has no engine to point at a grid' })
const codexHomeRefused = { error: 'INVALID_CODEX_HOME', detail: 'codexHome is only valid for codex, without a grid' }
expect(await ask({ engine: 'claude', cwd: '/w', codexHome: '/homes/codex' })).toStrictEqual(codexHomeRefused)
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'ok', override: { networkId: 'g' } } as never)
expect(await ask({ engine: 'codex', cwd: '/w', codexHome: '/homes/codex' })).toStrictEqual(codexHomeRefused)
expect(create).not.toHaveBeenCalled()
// One that is not a plain absolute path is not a codexHome at all, and is dropped rather than refused.
for (const codexHome of ['relative', '/with\nnewline', `/${'x'.repeat(4096)}`, 7]) await ask({ engine: 'claude', cwd: '/w', codexHome })
expect(vi.mocked(create!).mock.calls.map(([input]) => input.codexHome)).toEqual([null, null, null, null])
})
it('claudeHome is refused for codex and with a grid (INVALID_CLAUDE_HOME), and dropped when it is not a plain absolute path', async () => {
const { ask, create } = setup()
const refused = { error: 'INVALID_CLAUDE_HOME', detail: 'claudeHome is only valid for claude, without a grid' }
expect(await ask({ engine: 'codex', cwd: '/w', claudeHome: '/homes/claude' })).toStrictEqual(refused)
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'ok', override: { networkId: 'g' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', claudeHome: '/homes/claude' })).toStrictEqual(refused)
expect(create).not.toHaveBeenCalled()
for (const claudeHome of ['relative', '/with\nnewline', `/${'x'.repeat(4096)}`, 7]) await ask({ engine: 'claude', cwd: '/w', claudeHome })
expect(vi.mocked(create!).mock.calls.map(([input]) => 'claudeHome' in input)).toEqual([false, false, false, false])
})
it('claudeHome is accepted only when it is a profile this machine offers', async () => {
const { ask, create } = setup({ claudeHomeOffered: (home) => home === '/homes/offered' })
expect(await ask({ engine: 'claude', cwd: '/w', claudeHome: '/homes/other' })).toStrictEqual({ error: 'INVALID_CLAUDE_HOME', detail: 'claudeHome is not a Claude profile of this machine' })
expect(create).not.toHaveBeenCalled()
await ask({ engine: 'claude', cwd: '/w', claudeHome: '/homes/offered' })
expect(vi.mocked(create!).mock.calls[0][0]).toMatchObject({ claudeHome: '/homes/offered' })
})
// #4183: on Windows a profile folder is `C:\\…`; the check that wanted a leading '/' dropped every one, so the agent ran on
// the default account and reported its quota.
it('on Windows a drive-letter codexHome or claudeHome reaches the create input, and a POSIX one is dropped', async () => {
host.win32 = true
try {
const { ask, create } = setup()
await ask({ engine: 'codex', cwd: '/w', codexHome: 'C:\\Users\\u\\.codex-work' })
await ask({ engine: 'claude', cwd: '/w', claudeHome: 'C:\\Users\\u\\.claude-work' })
await ask({ engine: 'claude', cwd: '/w', claudeHome: '/Users/u/.claude-work' })
const inputs = vi.mocked(create!).mock.calls.map(([input]) => input)
expect(inputs[0]).toMatchObject({ codexHome: 'C:\\Users\\u\\.codex-work' })
expect(inputs[1]).toMatchObject({ claudeHome: 'C:\\Users\\u\\.claude-work' })
expect('claudeHome' in inputs[2]).toBe(false)
} finally {
host.win32 = false
}
})
it('claudeHome reaches the create input', async () => {
const { ask, create } = setup()
await ask({ engine: 'claude', cwd: '/w', claudeHome: '/homes/claude' })
expect(vi.mocked(create!).mock.calls[0][0]).toMatchObject({ engine: 'claude', claudeHome: '/homes/claude' })
})
it('a harness that is not an id, not installed here, a viewer, or not for this engine', async () => {
const { ask, create } = setup()
expect(await ask({ engine: 'claude', cwd: '/w', dsh: 'not an id' })).toStrictEqual({ error: 'INVALID_DSH', detail: 'dsh must be an owner/name id' })
expect(await ask({ engine: 'claude', cwd: '/w', dsh: 7 })).toStrictEqual({ error: 'INVALID_DSH', detail: 'dsh must be an owner/name id' })
expect(await ask({ engine: 'claude', cwd: '/w', dsh: 'acme/notes' })).toStrictEqual({ error: 'INVALID_DSH', detail: 'acme/notes is not installed on this machine' })
vi.mocked(installedDsh).mockReturnValueOnce({ id: 'acme/viewer', manifest: { kind: 'viewer' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', dsh: 'acme/viewer' })).toStrictEqual({ error: 'INVALID_DSH', detail: 'acme/viewer is a viewer package, not an agent' })
vi.mocked(installedDsh).mockReturnValueOnce({ id: 'acme/notes', manifest: { kind: 'agent' } } as never)
expect(await ask({ engine: 'pi', cwd: '/w', dsh: 'acme/notes' })).toStrictEqual({ error: 'INVALID_DSH', detail: 'acme/notes supports claude, codex; pi is not compatible' })
expect(create).not.toHaveBeenCalled()
})
it('passes explicit Swarm roles and refuses invalid role metadata before dispatch', async () => {
const { ask, create } = setup()
// Taken as the kinds the CLI keeps (project instructions, phase 4); a Reviewer keeps its swarm-review file.
const kinds = { lead: { swarmRole: 'coordinator' }, dev: { swarmRole: 'agent' }, review: { swarmRole: 'agent', swarmFallback: 'review' } }
for (const engine of ['claude', 'codex']) for (const swarmRole of ['lead', 'dev', 'review'] as const) {
await ask({ engine, cwd: '/w', swarmRole })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).toMatchObject({ engine, ...kinds[swarmRole] })
}
for (const swarmRole of [7, '', 'builder', 'reviewer']) {
expect(await ask({ engine: 'claude', cwd: '/w', swarmRole })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
}
expect(await ask({ engine: 'terminal', cwd: '/w', swarmRole: 'dev' })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
expect(await ask({ engine: 'codex', cwd: '/w', swarmRole: 'dev', resumeSessionId: 'old-session' })).toMatchObject({ error: 'INVALID_SESSION' })
})
// Project instructions, phase 4 (decision 1): an older Harness sends lead, dev or review; the next one may send the kinds.
it('takes older and newer Swarm roles from agent_create', async () => {
const { ask, create } = setup()
const launched = () => vi.mocked(create!).mock.calls.at(-1)![0]
await ask({ engine: 'claude', cwd: '/w', swarmRole: 'review' })
expect(launched()).toMatchObject({ swarmRole: 'agent', swarmFallback: 'review' })
for (const [swarmRole, role] of [['lead', 'coordinator'], ['dev', 'agent'], ['buddy', 'buddy'], ['coordinator', 'coordinator'], ['agent', 'agent']]) {
await ask({ engine: 'codex', cwd: '/w', swarmRole })
expect(launched()).toMatchObject({ swarmRole: role })
expect(launched()).not.toHaveProperty('swarmFallback')
}
const calls = vi.mocked(create!).mock.calls.length
for (const swarmRole of ['pm', 'Coordinator', 'reviewer']) {
expect(await ask({ engine: 'claude', cwd: '/w', swarmRole })).toStrictEqual({ error: 'INVALID_SWARM_ROLE',
detail: 'A Swarm role is coordinator, agent or buddy (or lead, dev or review from an older Harness), for Claude Code or Codex.' })
}
expect(vi.mocked(create!).mock.calls).toHaveLength(calls)
})
it('finds the receipt a start got before role kinds when it is asked again, whichever role values it carries', async () => {
const { ask, create, deps, replies } = setup()
// What this machine fingerprinted for a Reviewer's start before its update.
const before = { engine: 'claude', cwd: '/w', bypassPermission: true, permissionMode: null, grid: null, codexHome: null, dsh: null, prompt: null,
swarmRole: 'review', name: null, agent: null, resumeSessionId: null, takeOver: null }
await deps.receipts.run(CREATION, creationFingerprint(before), async () => ({ state: 'created', agentId: 'new-agent' }))
await ask({ engine: 'claude', cwd: '/w', swarmRole: 'review', creationId: CREATION })
await vi.waitFor(() => expect(replies.at(-1)).toMatchObject({ state: 'created' }))
await ask({ engine: 'claude', cwd: '/w', swarmRole: 'agent', creationId: `${CREATION}-new` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(create).toHaveBeenCalledTimes(1)
expect(deps.receipts.has(`${CREATION}-new`, creationFingerprint({ ...before, swarmRole: 'dev' }))).toBe(true)
})
it('passes the project\'s skill mode with a Swarm role, and refuses one it does not know before dispatch', async () => {
const { ask, create } = setup()
for (const swarmSkillMode of ['default', 'orchestration']) {
await ask({ engine: 'claude', cwd: '/w', swarmRole: 'dev', swarmSkillMode })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).toMatchObject({ swarmRole: 'agent', swarmSkillMode })
}
// From a start before modes: the session launches as it did then.
await ask({ engine: 'claude', cwd: '/w', swarmRole: 'dev' })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).not.toHaveProperty('swarmSkillMode')
const calls = vi.mocked(create!).mock.calls.length
for (const swarmSkillMode of ['light', 7, null]) {
expect(await ask({ engine: 'claude', cwd: '/w', swarmRole: 'dev', swarmSkillMode })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
}
expect(vi.mocked(create!).mock.calls).toHaveLength(calls)
})
it('passes the GitHub App flag with a Swarm role only, and refuses anything else before dispatch', async () => {
const { ask, create } = setup()
await ask({ engine: 'codex', cwd: '/w', swarmRole: 'dev', swarmGitHub: true })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).toMatchObject({ swarmRole: 'agent', swarmGitHub: true })
await ask({ engine: 'codex', cwd: '/w', swarmRole: 'dev' })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).not.toHaveProperty('swarmGitHub')
const calls = vi.mocked(create!).mock.calls.length
for (const payload of [{ swarmRole: 'dev', swarmGitHub: false }, { swarmRole: 'dev', swarmGitHub: 'yes' }, { swarmGitHub: true }]) {
expect(await ask({ engine: 'claude', cwd: '/w', ...payload })).toMatchObject({ error: 'INVALID_SWARM_ROLE' })
}
expect(vi.mocked(create!).mock.calls).toHaveLength(calls)
})
// HARNESS_SWARM=off: nothing of the Swarm's is asked of a launch, and a start that asks for it is refused at the wire.
it('refuses every Swarm field while the Swarm is off, before dispatch, and starts everything else as before', async () => {
const { ask, create } = setup({ swarmLaunch: undefined })
for (const payload of [{ swarmRole: 'dev' }, { swarmSkillMode: 'default' }, { swarmGitHub: true }, { swarmRole: 'lead', swarmSkillMode: 'orchestration', swarmGitHub: true }]) {
expect(await ask({ engine: 'claude', cwd: '/w', ...payload })).toStrictEqual({ error: 'INVALID_SWARM_ROLE', detail: 'The Swarm is off on this computer (HARNESS_SWARM).' })
}
expect(create).not.toHaveBeenCalled()
await ask({ engine: 'claude', cwd: '/w', swarmRole: null })
expect(vi.mocked(create!).mock.calls.at(-1)![0]).not.toHaveProperty('swarmRole')
})
it('a first prompt that is not text, too long, or for an engine that cannot take one', async () => {
const { ask, create } = setup()
expect(await ask({ engine: 'claude', cwd: '/w', prompt: 7 })).toStrictEqual({ error: 'INVALID_PROMPT', detail: 'prompt must be a string' })
expect(await ask({ engine: 'claude', cwd: '/w', prompt: 'x'.repeat(MAX_FIRST_PROMPT_CHARS + 1) }))
.toStrictEqual({ error: 'PROMPT_TOO_LONG', detail: `prompt is longer than ${MAX_FIRST_PROMPT_CHARS} characters` })
vi.mocked(supportsFirstPrompt).mockReturnValueOnce(false)
expect(await ask({ engine: 'claude', cwd: '/w', prompt: 'fix it' })).toMatchObject({ error: 'PROMPT_UNSUPPORTED' })
expect(create).not.toHaveBeenCalled()
})
it('a named agent that is not a name, or one its engine cannot open as (OpenCode v2 counts as cannot)', async () => {
const { ask, create } = setup()
expect(await ask({ engine: 'claude', cwd: '/w', agent: '../reviewer' })).toStrictEqual({ error: 'INVALID_AGENT', detail: 'agent must be 1-64 letters, digits, `-` or `_`' })
expect(await ask({ engine: 'claude', cwd: '/w', agent: 7 })).toMatchObject({ error: 'INVALID_AGENT' })
vi.mocked(supportsNamedAgent).mockReturnValueOnce(false)
vi.mocked(opencodeMajorVersion).mockResolvedValueOnce(2)
expect(await ask({ engine: 'opencode', cwd: '/w', agent: 'reviewer' })).toMatchObject({ error: 'AGENT_UNSUPPORTED' })
expect(supportsNamedAgent).toHaveBeenLastCalledWith('opencode', 2)
expect(create).not.toHaveBeenCalled()
})
it('validates a named OpenCode launch without optional code', async () => {
const { ask, create } = setup()
vi.mocked(loadEngine).mockResolvedValue(null)
await ask({ engine: 'opencode', cwd: '/w', agent: 'reviewer' })
expect(create).toHaveBeenCalledOnce()
await ask({ engine: 'claude', cwd: '/w', agent: 'reviewer' })
expect(loadEngine).not.toHaveBeenCalled()
})
it('a permission mode the engine does not have, and a conversation to resume that is not one or comes with new-conversation choices', async () => {
const { ask, create } = setup()
vi.mocked(permissionModeFlags).mockReturnValueOnce(null as never)
expect(await ask({ engine: 'claude', cwd: '/w', permissionMode: 'yolo' })).toStrictEqual({ error: 'INVALID_PERMISSION_MODE', detail: 'claude has no permission mode "yolo"' })
expect(await ask({ engine: 'claude', cwd: '/w', permissionMode: 7 })).toStrictEqual({ error: 'INVALID_PERMISSION_MODE', detail: 'claude has no permission mode 7' })
const notASession = { error: 'INVALID_SESSION', detail: 'resumeSessionId must be a session id' }
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: '../x' })).toStrictEqual(notASession)
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 7 })).toStrictEqual(notASession)
const fresh = { error: 'INVALID_SESSION', detail: 'a resumed conversation takes no new folder, grid, harness, prompt or agent' }
expect(await ask({ engine: 'terminal', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
expect(await ask({ engine: 'claude', projectSource: 'new', creationId: CREATION, resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'ok', override: { networkId: 'g' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
vi.mocked(parseNewAgentModel).mockReturnValueOnce({ state: 'ok', selection: { model: 'm', grid: 'fixture-grid' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
vi.mocked(installedDsh).mockReturnValueOnce({ id: 'acme/notes', manifest: { kind: 'agent' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', dsh: 'acme/notes', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
expect(await ask({ engine: 'claude', cwd: '/w', prompt: 'go', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
expect(await ask({ engine: 'claude', cwd: '/w', agent: 'reviewer', resumeSessionId: 'ses_abc' })).toStrictEqual(fresh)
const takeOver = { error: 'INVALID_SESSION', detail: 'takeOver is idle, now or wait, with a resumeSessionId' }
expect(await ask({ engine: 'claude', cwd: '/w', takeOver: 'now' })).toStrictEqual(takeOver)
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 'ses_abc', takeOver: 'later' })).toStrictEqual(takeOver)
expect(create).not.toHaveBeenCalled()
})
it('a starter that is not another agent: absent is the person, anything else is refused', async () => {
const { ask, create } = setup()
const refused = { error: 'INVALID_STARTED_BY', detail: 'startedBy is agent, or absent for the person' }
expect(await ask({ engine: 'claude', cwd: '/w', startedBy: 'person' })).toStrictEqual(refused)
expect(await ask({ engine: 'claude', cwd: '/w', startedBy: true })).toStrictEqual(refused)
// Which harness started it: an agent id, and only beside startedBy agent.
const noParent = { error: 'INVALID_STARTED_BY', detail: 'parentAgentId is the agent id of the harness that started it, with startedBy agent' }
expect(await ask({ engine: 'claude', cwd: '/w', parentAgentId: 'a1' })).toStrictEqual(noParent)
expect(await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent', parentAgentId: '../a1' })).toStrictEqual(noParent)
expect(await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent', parentAgentId: 7 })).toStrictEqual(noParent)
expect(create).not.toHaveBeenCalled()
})
})
describe('agent_create, launched', () => {
it('hands the creator every choice, as one input, and answers with the new agent\'s frame', async () => {
vi.mocked(installedDsh).mockReturnValueOnce({ id: 'acme/notes', manifest: { kind: 'agent' } } as never)
vi.mocked(permissionModeApproves).mockReturnValueOnce(true)
const { ask, create } = setup()
const reply = await ask({ engine: 'codex', cwd: '/w', codexHome: '/homes/codex', dsh: 'acme/notes', prompt: ' fix the build ', name: ' Builder ',
agent: 'reviewer', permissionMode: 'auto' })
expect(reply).toStrictEqual({ agent: { id: 'new-agent' } })
expect(create).toHaveBeenCalledWith({ engine: 'codex', cwd: '/w', bypassPermission: true, permissionMode: 'auto', grid: null, codexHome: '/homes/codex',
dsh: 'acme/notes', prompt: 'fix the build', name: 'Builder', agent: 'reviewer', resumeSessionId: null, takeOver: null })
expect(Object.keys(vi.mocked(create!).mock.calls[0][0])).toEqual(['engine', 'cwd', 'bypassPermission', 'permissionMode', 'grid', 'codexHome', 'dsh', 'prompt', 'name', 'agent', 'resumeSessionId', 'takeOver'])
})
it('hands on that another agent started it, and nothing for the person, so their receipts\' fingerprints stay as they were', async () => {
const { ask, create } = setup()
await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent' })
await ask({ engine: 'claude', cwd: '/w', startedBy: null })
const [byAgent, byPerson] = vi.mocked(create!).mock.calls.map(([input]) => input)
expect(byAgent).toMatchObject({ engine: 'claude', cwd: '/w', startedBy: 'agent' })
expect(Object.keys(byPerson!)).not.toContain('startedBy')
})
it('hands a Claude launch its model and effort, and nothing for default, so older receipts\' fingerprints stay as they were', async () => {
const { ask, create } = setup()
await ask({ engine: 'claude', cwd: '/w', model: 'opus', effort: 'high' })
await ask({ engine: 'claude', cwd: '/w', model: 'default', effort: 'default' })
await ask({ engine: 'claude', cwd: '/w' })
const [routed, byDefault, plain] = vi.mocked(create!).mock.calls.map(([input]) => input)
expect(routed).toMatchObject({ engine: 'claude', launchModel: { model: 'opus', effort: 'high' } })
expect(Object.keys(byDefault!)).not.toContain('launchModel')
expect(Object.keys(plain!)).not.toContain('launchModel')
})
it('refuses a launch model before any receipt when the installed engine lacks a flag, and proceeds when it has them', async () => {
const { ask, create, deps } = setup()
vi.mocked(unsupportedLaunchModelFlag).mockResolvedValueOnce('--effort')
expect(await ask({ engine: 'claude', cwd: '/w', creationId: CREATION, model: 'opus', effort: 'high' }))
.toMatchObject({ error: 'LAUNCH_MODEL_UNSUPPORTED', detail: expect.stringContaining('--effort') })
expect(unsupportedLaunchModelFlag).toHaveBeenCalledWith('claude', { model: 'opus', effort: 'high' })
expect(create).not.toHaveBeenCalled()
expect(deps.receipts.has(CREATION, 'any')).toBe(false)
expect(deps.receipts.pendingIntent(CREATION)).toBeFalsy()
// The same creation id is then free to start the agent without them.
vi.mocked(unsupportedLaunchModelFlag).mockResolvedValueOnce(null)
await ask({ engine: 'claude', cwd: '/w', creationId: CREATION, model: 'opus', effort: 'high' })
await vi.waitFor(() => expect(create).toHaveBeenCalledOnce())
expect(vi.mocked(create!).mock.calls[0][0]).toMatchObject({ launchModel: { model: 'opus', effort: 'high' } })
})
it('refuses a launch model its engine cannot take, a malformed one, and one beside a grid or a resumed conversation', async () => {
const { ask, create } = setup()
expect(await ask({ engine: 'codex', cwd: '/w', model: 'gpt-5', effort: 'high' })).toMatchObject({ error: 'LAUNCH_MODEL_UNSUPPORTED', detail: expect.stringContaining('codex') })
expect(await ask({ engine: 'claude', cwd: '/w', model: 'opus; ls' })).toMatchObject({ error: 'INVALID_LAUNCH_MODEL' })
expect(await ask({ engine: 'claude', cwd: '/w', effort: 'enormous' })).toMatchObject({ error: 'INVALID_LAUNCH_MODEL' })
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'ok', override: { networkName: 'g' } } as never)
expect(await ask({ engine: 'claude', cwd: '/w', model: 'opus' })).toMatchObject({ error: 'INVALID_LAUNCH_MODEL', detail: expect.stringContaining('grid') })
vi.mocked(parseNewAgentModel).mockReturnValueOnce({ state: 'ok', selection: { model: 'm', grid: 'g' } })
expect(await ask({ engine: 'claude', cwd: '/w', model: 'opus' })).toMatchObject({ error: 'INVALID_LAUNCH_MODEL' })
expect(await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 'abc12345', model: 'opus' })).toMatchObject({ error: 'INVALID_SESSION' })
expect(create).not.toHaveBeenCalled()
})
it('hands on which harness here started it, and leaves out one this machine does not know', async () => {
const { ask, create } = setup()
await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent', parentAgentId: 'a1' })
// Closed and forgotten while it ran `harness new`: its child still starts, beside nothing.
await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent', parentAgentId: 'gone' })
await ask({ engine: 'claude', cwd: '/w', startedBy: 'agent', parentAgentId: null })
const [known, unknown, none] = vi.mocked(create!).mock.calls.map(([input]) => input)
expect(known).toMatchObject({ startedBy: 'agent', parentAgentId: 'a1' })
expect(Object.keys(unknown!)).not.toContain('parentAgentId')
expect(Object.keys(none!)).not.toContain('parentAgentId')
})
it('opens a terminal in the home folder, bypasses permission unless told not to, and takes blank choices as none', async () => {
const { ask, create } = setup()
vi.mocked(parseGridLaunchOverride).mockReturnValueOnce({ state: 'absent' } as never).mockReturnValueOnce({ state: 'ok', override: { networkId: 'g' } } as never)
await ask({ engine: 'terminal' })
await ask({ engine: 'claude', cwd: '/w', bypassPermission: false, prompt: ' ', name: ' ', dsh: null, agent: null, permissionMode: null, resumeSessionId: null, takeOver: null })
await ask({ engine: 'claude', cwd: '/w', resumeSessionId: 'ses_abc', takeOver: 'idle' })
const inputs = vi.mocked(create!).mock.calls.map(([input]) => input)
expect(inputs[0]).toMatchObject({ engine: 'terminal', cwd: homedir(), bypassPermission: true })
expect(inputs[1]).toMatchObject({ cwd: '/w', bypassPermission: false, prompt: null, name: null, grid: { networkId: 'g' } })
expect(inputs[2]).toMatchObject({ resumeSessionId: 'ses_abc', takeOver: 'idle' })
})
it('points a model picked by name at its grid as read now, or says the model is unavailable', async () => {
const { ask, create } = setup()
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'm', grid: 'fixture-grid' } } as never)
resolveNewAgentModel.mockResolvedValueOnce({ networkId: 'resolved' } as never).mockResolvedValueOnce(null).mockRejectedValueOnce(new Error('offline'))
await ask({ engine: 'claude', cwd: '/w' })
expect(vi.mocked(create!).mock.calls[0][0].grid).toEqual({ networkId: 'resolved' })
const unavailable = { error: 'GRID_UNAVAILABLE', detail: 'The selected model is unavailable. Choose another model or refresh the list.' }
expect(await ask({ engine: 'claude', cwd: '/w' })).toStrictEqual(unavailable)
expect(await ask({ engine: 'claude', cwd: '/w' })).toStrictEqual(unavailable)
expect(create).toHaveBeenCalledOnce()
})
it('passes a refusal on with its cause when it has one', async () => {
const refused = setup({}, { create: vi.fn(async () => ({ ok: false as const, error: 'SPAWN_FAILED', detail: 'tmux: no server' })) })
expect(await refused.ask({ engine: 'claude', cwd: '/w' })).toStrictEqual({ error: 'SPAWN_FAILED', detail: 'tmux: no server' })
const bare = setup({}, { create: vi.fn(async () => ({ ok: false as const, error: 'ENGINE_MISSING' })) })
expect(await bare.ask({ engine: 'claude', cwd: '/w' })).toStrictEqual({ error: 'ENGINE_MISSING' })
})
})
describe('agent_create with a receipt', () => {
it('keeps a temporary model outage pending across receipt readers instead of completing it as failed', async () => {
const { ask, create, replies, status } = setup()
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
resolveNewAgentModel.mockRejectedValueOnce(new Error('fixture models disconnected'))
await ask({ engine: 'claude', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(create).not.toHaveBeenCalled()
expect(replies[0]).toMatchObject({ creationId: CREATION, state: 'pending', held: { service: 'models', detail: expect.any(String) } })
expect(await status({ creationId: CREATION })).toMatchObject({ state: 'pending', held: { service: 'models' } })
const recovered = new AgentCreationReceipts(join(dir, `receipts-${stores}`))
expect(recovered.status(CREATION)).toMatchObject({ state: 'pending', held: { service: 'models' } })
})
it('recovers the original request and authorization after restart, then returns the same created agent', async () => {
const { ask, replies, deps, create } = setup()
const cwd = join(root.projects, 'remote-request'); mkdirSync(cwd)
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
resolveNewAgentModel.mockRejectedValueOnce(new Error('disconnected'))
await ask({ engine: 'claude', cwd, prompt: 'Keep this task', creationId: CREATION }, false)
await vi.waitFor(() => expect(replies).toHaveLength(1))
const recovered = createLaunchRequests({ ...deps, receipts: new AgentCreationReceipts(join(dir, `receipts-${stores}`)) })
stopRequests.push(recovered.stop)
const target = { networkId: 'fixture-grid', networkName: 'Fixture', baseUrl: 'http://fixture.invalid/v1', apiKey: 'rotated-key' }
resolveNewAgentModel.mockResolvedValue(target)
await recovered.recover()
expect(create).not.toHaveBeenCalled()
recovered.open()
await recovered.recover()
await vi.waitFor(() => expect(create).toHaveBeenCalledOnce())
expect(create).toHaveBeenCalledWith(expect.objectContaining({ cwd, prompt: 'Keep this task', grid: target }))
expect(preTrustClaudeProject).not.toHaveBeenCalled()
const answer = vi.fn()
await recovered.createStatus({ creationId: CREATION }, { local: true }, answer)
expect(answer).toHaveBeenCalledWith({ creationId: CREATION, state: 'created', agent: { id: 'new-agent' } })
await recovered.recover()
expect(create).toHaveBeenCalledOnce()
})
it('cancels an undispatched model request durably and refuses a late create with the same ID', async () => {
const { ask, requests, create, replies } = setup()
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
resolveNewAgentModel.mockResolvedValue(null)
await ask({ engine: 'claude', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
const answer = vi.fn()
await requests.cancelCreate({ creationId: CREATION }, { local: true }, answer)
expect(answer).toHaveBeenLastCalledWith({ creationId: CREATION, state: 'cancelled' })
resolveNewAgentModel.mockResolvedValue({ networkId: 'fixture-grid' } as never)
requests.open(); await requests.recover()
await ask({ engine: 'claude', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(replies[1]).toEqual({ creationId: CREATION, state: 'cancelled' })
expect(create).not.toHaveBeenCalled()
})
it('reads a completed receipt before checking mutable package or native version state', async () => {
const { ask, replies, create } = setup()
vi.mocked(installedDsh).mockReturnValue({ id: 'fixture/package', manifest: { kind: 'agent', name: 'Fixture' } } as never)
await ask({ engine: 'claude', cwd: '/fixture/work', dsh: 'fixture/package', agent: 'named', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
vi.mocked(installedDsh).mockReturnValue(undefined)
vi.mocked(supportsNamedAgent).mockReturnValue(false)
await ask({ engine: 'claude', cwd: '/fixture/work', dsh: 'fixture/package', agent: 'named', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(replies[1]).toEqual(replies[0])
expect(create).toHaveBeenCalledOnce()
})
it('answers outside the connection\'s line, with the creation id and the new agent, and a retry is the same launch', async () => {
let finish!: (value: { ok: true; session: RegisteredSession }) => void
const create = vi.fn(() => new Promise<{ ok: true; session: RegisteredSession }>((resolve) => { finish = resolve }))
const { ask, replies, status } = setup({}, { create })
await ask({ engine: 'claude', cwd: '/w', creationId: CREATION })
expect(replies).toEqual([])
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'pending' })
finish({ ok: true, session: session('new-agent') })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(replies[1]).toStrictEqual({ creationId: CREATION, state: 'created', agent: { id: 'new-agent' } })
expect(Object.keys(replies[1])).toEqual(['creationId', 'state', 'agent'])
await ask({ engine: 'claude', cwd: '/w', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(3))
expect(create).toHaveBeenCalledOnce()
// The same id for another launch is a conflict, never a second process.
await ask({ engine: 'codex', cwd: '/w', creationId: CREATION })
expect(replies.at(-1)).toStrictEqual({ error: 'CREATION_CONFLICT' })
})
it('records a launch that may have started as unconfirmed, and any other refusal as failed, with its folder and its cause, cut short', async () => {
for (const [error, expected] of [['SPAWN_FAILED', 'unconfirmed'], ['REGISTRATION_FAILED', 'unconfirmed'], ['ENGINE_MISSING', 'failed']] as const) {
const { ask, replies } = setup({}, { create: vi.fn(async () => ({ ok: false as const, error, detail: 'd'.repeat(3000) })) })
await ask({ engine: 'claude', cwd: '/w', creationId: `${CREATION}-${error.toLowerCase()}`.slice(0, 64).replace(/_/g, '-') })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(replies[0].state).toBe(expected)
if (expected === 'failed') expect(replies[0]).toStrictEqual({ creationId: expect.any(String), state: 'failed', failure: { code: 'ENGINE_MISSING', detail: 'd'.repeat(2000) } })
}
const bare = setup({}, { create: vi.fn(async () => ({ ok: false as const, error: 'ENGINE_MISSING' })) })
await bare.ask({ engine: 'claude', cwd: '/w', creationId: CREATION })
await vi.waitFor(() => expect(bare.replies).toStrictEqual([{ creationId: CREATION, state: 'failed', failure: { code: 'ENGINE_MISSING' } }]))
})
it('prepares the project folder it was asked for, named after the harness or the engine, and launches in it', async () => {
const { ask, create, replies } = setup()
vi.mocked(installedDsh).mockReturnValue({ id: 'acme/notes', manifest: { kind: 'agent', name: 'Notes' } } as never)
await ask({ engine: 'claude', projectSource: 'new', projectName: 'Docs', creationId: CREATION, dsh: 'acme/notes' })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(prepareProjectFolder).toHaveBeenCalledWith({ source: 'new', name: 'Docs' }, { label: 'Notes', onPrepared: expect.any(Function) })
expect(vi.mocked(create!).mock.calls[0][0].cwd).toBe('/projects/prepared')
vi.mocked(installedDsh).mockReturnValue(undefined)
await ask({ engine: 'pi', projectSource: 'new', creationId: `${CREATION}-pi` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(prepareProjectFolder).toHaveBeenLastCalledWith({ source: 'new' }, { label: 'Pi', onPrepared: expect.any(Function) })
expect(vi.mocked(create!).mock.calls[1][0].scmLaunchRecord).toBeNull()
})
it('hands the launch the SCM record the prepared workspace reported (registry `scmLaunch`)', async () => {
const { ask, create, replies } = setup()
vi.mocked(prepareProjectFolder).mockImplementationOnce(async (_project, options) => {
options?.onPrepared?.({ cwd: '/projects/prepared', scmLaunchRecord: { kind: 'git' } })
return '/projects/prepared'
})
await ask({ engine: 'claude', projectSource: 'worktree', gitSource: '/work/repo', branchRef: 'refs/heads/main', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(vi.mocked(create!).mock.calls[0][0]).toMatchObject({ cwd: '/projects/prepared', scmLaunchRecord: { kind: 'git' } })
})
it('fetches nothing with this machine\'s login for another person\'s Swarm worktree: its host already fetched with the app\'s token', async () => {
const { ask, replies } = setup()
await ask({ engine: 'codex', projectSource: 'worktree', gitSource: '/swarm/project', branchName: 'super-tab/start-1', branchBase: 'default',
swarmRole: 'dev', swarmGitHub: true, creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(prepareProjectFolder).toHaveBeenLastCalledWith({ source: 'worktree', gitSource: '/swarm/project', branchName: 'super-tab/start-1',
fromDefaultBranch: true, offline: true }, expect.anything())
// A Swarm start that is the machine owner's own fetches as before.
await ask({ engine: 'codex', projectSource: 'worktree', gitSource: '/swarm/project', branchName: 'super-tab/start-2', branchBase: 'default',
swarmRole: 'dev', creationId: `${CREATION}-own` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(vi.mocked(prepareProjectFolder).mock.calls.at(-1)![0]).not.toHaveProperty('offline')
})
it('records a folder it could not prepare as failed, in the folder\'s own words when it has them', async () => {
const { ask, create, replies } = setup()
vi.mocked(prepareProjectFolder).mockRejectedValueOnce(new ProjectFolderError('CLONE_FAILED', 'Could not clone it.')).mockRejectedValueOnce(new Error('disk full'))
await ask({ engine: 'claude', projectSource: 'new', creationId: CREATION })
await ask({ engine: 'claude', projectSource: 'new', creationId: `${CREATION}-2` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(replies.map((r) => r.failure)).toEqual([
{ code: 'CLONE_FAILED', detail: 'Could not clone it.' }, { code: 'PROJECT_PREPARATION_FAILED', detail: 'Could not prepare the project folder.' },
])
expect(create).not.toHaveBeenCalled()
})
it('records the folder a typed name found already there, so the apps can offer to start in it', async () => {
const { ask, status, create, replies } = setup()
vi.mocked(prepareProjectFolder).mockRejectedValueOnce(new ProjectFolderError('PROJECT_EXISTS', '“payments” already exists.', '/projects/payments'))
await ask({ engine: 'claude', projectSource: 'new', projectName: 'payments', creationId: CREATION })
const refused = { creationId: CREATION, state: 'failed', failure: { code: 'PROJECT_EXISTS', detail: '“payments” already exists.', existingFolder: '/projects/payments' } }
await vi.waitFor(() => expect(replies).toStrictEqual([refused]))
// Kept with the receipt: asked again, the answer is the same.
expect(await status({ creationId: CREATION })).toStrictEqual(refused)
expect(create).not.toHaveBeenCalled()
})
it('lets the person\'s own clone try every way in, says which alias worked, and calls a refusal everywhere denied', async () => {
const { ask, status, replies } = setup()
const remote = { engine: 'claude', projectSource: 'remote', repositoryUrl: 'https://github.com/acme/app' }
vi.mocked(prepareProjectFolder).mockImplementationOnce(async (_project, options) => {
options?.onCloned?.({ url: 'git@gh-work:acme/app.git', alias: 'gh-work' })
return '/projects/prepared'
})
const answer = async (payload: Record<string, unknown>) => {
const before = replies.length
await ask(payload)
await vi.waitFor(() => expect(replies.length).toBeGreaterThan(before))
return replies.at(-1)!
}
expect(await answer({ ...remote, creationId: CREATION })).toMatchObject({ state: 'created', agent: { id: 'new-agent' }, clonedVia: { alias: 'gh-work' } })
expect(vi.mocked(prepareProjectFolder).mock.calls.at(-1)![1]).toMatchObject({ cloneFallback: true })
expect(await status({ creationId: CREATION })).toMatchObject({ clonedVia: { alias: 'gh-work' } })
// A transport switch is no news: the account is the same.
vi.mocked(prepareProjectFolder).mockImplementationOnce(async (_project, options) => {
options?.onCloned?.({ url: '[email protected]:acme/app.git' })
return '/projects/prepared'
})
expect(await answer({ ...remote, creationId: `${CREATION}-plain` })).not.toHaveProperty('clonedVia')
vi.mocked(prepareProjectFolder).mockRejectedValueOnce(new RepositoryAccessError('CLONE_FAILED', 'Could not access this repository.'))
expect(await answer({ ...remote, creationId: `${CREATION}-denied` })).toStrictEqual({ creationId: `${CREATION}-denied`, state: 'failed',
failure: { code: 'CLONE_FAILED', detail: 'Could not access this repository.', access: 'denied' } })
// A Swarm agent's repository was cloned by its start, one address per transport and never an alias.
await answer({ ...remote, swarmRole: 'lead', creationId: `${CREATION}-swarm` })
expect(vi.mocked(prepareProjectFolder).mock.calls.at(-1)![1]).toMatchObject({ cloneFallback: false })
})
it('records the prepared folder of a launch that then failed, so the person can open it', async () => {
const { ask, replies } = setup({}, { create: vi.fn(async () => ({ ok: false as const, error: 'ENGINE_MISSING' })) })
await ask({ engine: 'claude', projectSource: 'new', creationId: CREATION })
await vi.waitFor(() => expect(replies).toStrictEqual([{ creationId: CREATION, state: 'failed', preparedFolder: '/projects/prepared', failure: { code: 'ENGINE_MISSING' } }]))
})
it('waits for a new project\'s engine to be installed before making its folder, then launches in it', async () => {
// A fresh Ubuntu VM (2026-10-12): `harness new codex scratch1` was refused at once, its folder made, saying the
// launch would continue after the install; nothing did, and the folder then refused the same command.
const installing = { ok: false as const, error: 'NATIVE_LAUNCH_HELD' as const, unavailable: 'native' as const, installing: true as const,
detail: 'Installing Codex. The harness starts once it is installed.' }
const prepareEngine = vi.fn<NonNullable<LaunchRequestDeps['prepareEngine']>>().mockResolvedValueOnce(installing)
.mockResolvedValue({ ok: true, launch: {} as never })
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: true, dispatch }))
const { ask, replies, create, deps } = setup({ prepareCreate, prepareEngine })
const payload = { engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION, prompt: 'Reply with pong' }
await ask(payload)
await vi.waitFor(() => expect(replies[0]).toMatchObject({ state: 'pending', held: { service: 'install', detail: installing.detail } }))
expect(prepareProjectFolder).not.toHaveBeenCalled()
expect(deps.receipts.pendingIntent(CREATION)!.request).toMatchObject({ projectFolder: { source: 'new', name: 'scratch1' }, input: { cwd: '' } })
await ask(payload)
await vi.waitFor(() => expect(replies[1]).toMatchObject({ state: 'created', agent: { id: 'new-agent' } }))
expect(prepareEngine).toHaveBeenCalledWith('codex', expect.objectContaining({ prompt: 'Reply with pong' }), expect.objectContaining({ id: CREATION }))
expect(prepareProjectFolder).toHaveBeenCalledOnce()
expect(prepareCreate).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/projects/prepared', prompt: 'Reply with pong' }),
expect.objectContaining({ id: CREATION, label: expect.stringMatching(/^harness-codex-/) }), { local: true })
expect(dispatch).toHaveBeenCalledOnce()
expect(create).not.toHaveBeenCalled()
})
it('makes no folder for a new project cancelled while its engine was being made ready', async () => {
let prepare!: Parameters<typeof pendingLaunches.createPendingLaunches>[0]['prepare']
const factory = pendingLaunches.createPendingLaunches
vi.spyOn(pendingLaunches, 'createPendingLaunches').mockImplementation(deps => { prepare = deps.prepare; return factory(deps) })
let current = true
const prepareEngine = vi.fn<NonNullable<LaunchRequestDeps['prepareEngine']>>(async () => { current = false; return { ok: true, launch: {} as never } })
setup({ prepareCreate: vi.fn(), prepareEngine })
expect(await prepare({ kind: 'native-create-v1', input: { engine: 'codex', cwd: '' }, projectFolder: { source: 'new', name: 'scratch1' },
label: 'harness-codex-fixture', local: true }, { id: CREATION, current: () => current, hold: vi.fn() })).toBeNull()
expect(prepareProjectFolder).not.toHaveBeenCalled()
})
it('refuses a new project for a harness it does not have at once, before any engine install or folder', async () => {
const prepareEngine = vi.fn<NonNullable<LaunchRequestDeps['prepareEngine']>>()
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>()
const { ask, deps } = setup({ prepareCreate, prepareEngine })
expect(await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION, dsh: 'acme/notes' }))
.toStrictEqual({ error: 'INVALID_DSH', detail: 'acme/notes is not installed on this machine' })
expect(deps.receipts.status(CREATION)).toEqual({ state: 'missing' })
expect(prepareEngine).not.toHaveBeenCalled()
expect(prepareProjectFolder).not.toHaveBeenCalled()
})
it('refuses a new project whose engine could not be installed, before any folder exists', async () => {
const prepareEngine = vi.fn<NonNullable<LaunchRequestDeps['prepareEngine']>>(async () => ({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native',
refusal: 'ENGINE_INSTALL_FAILED', detail: 'Codex could not be installed: getaddrinfo ENOTFOUND registry.npmjs.org' }))
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>()
const { ask, replies } = setup({ prepareCreate, prepareEngine })
await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION })
await vi.waitFor(() => expect(replies).toStrictEqual([{ creationId: CREATION, state: 'failed',
failure: { code: 'ENGINE_INSTALL_FAILED', detail: 'Codex could not be installed: getaddrinfo ENOTFOUND registry.npmjs.org' } }]))
expect(prepareProjectFolder).not.toHaveBeenCalled()
expect(prepareCreate).not.toHaveBeenCalled()
})
it('removes the empty folder a new project made when nothing starts in it, and keeps one that has anything', async () => {
const made = join(root.projects, 'scratch1')
vi.mocked(prepareProjectFolder).mockImplementation(async () => { mkdirSync(made); return made })
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: false, error: 'CODEX_CLI_TOO_OLD', detail: 'Update codex.' }))
const { ask, replies } = setup({ prepareCreate })
await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION })
await vi.waitFor(() => expect(replies).toStrictEqual([{ creationId: CREATION, state: 'failed', failure: { code: 'CODEX_CLI_TOO_OLD', detail: 'Update codex.' } }]))
expect(existsSync(made)).toBe(false)
prepareCreate.mockImplementationOnce(async () => { writeFileSync(join(made, 'notes.md'), 'kept'); return { ok: false, error: 'CODEX_CLI_TOO_OLD' } })
await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: `${CREATION}-2` })
await vi.waitFor(() => expect(replies[1]).toStrictEqual({ creationId: `${CREATION}-2`, state: 'failed', preparedFolder: made, failure: { code: 'CODEX_CLI_TOO_OLD' } }))
expect(existsSync(join(made, 'notes.md'))).toBe(true)
})
it('holds a launch whose engine Harness is installing under install', async () => {
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: false, error: 'NATIVE_LAUNCH_HELD',
unavailable: 'native', installing: true, detail: 'Installing Codex. The harness starts once it is installed.' }))
const { ask, replies } = setup({ prepareCreate })
await ask({ engine: 'codex', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(replies[0]).toMatchObject({ state: 'pending', held: { service: 'install', detail: 'Installing Codex. The harness starts once it is installed.' } }))
})
it('holds a create while Desktop Harness downloads its engine, and creates it once by itself when the download ends', async () => {
// A brand-new Mac (2026-10-16): the Desktop sends agent_create as soon as its own download of Codex is under way.
// The launch is held as an install, tried again every two seconds with nobody asking, and dispatched once.
let downloading = true, clock = Date.now()
vi.spyOn(Date, 'now').mockImplementation(() => clock)
const missing: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Not installed',
install: { command: 'fixture-installer', source: 'fixture', executable: { names: ['codex'] } }, environment: { HOME: '/fixture/home' } }
const inspect = vi.fn(async (): Promise<NativeLaunchResult> => downloading ? missing : { ok: true, launch: {} as never })
const ensure = vi.fn()
// Read as it is asked: an attempt keeps the answer it was given, whatever the test says after.
const downloadingNow = vi.fn(async () => downloading)
const prepareEngine = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect, downloading: downloadingNow })
const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: true, dispatch }))
const { ask, replies, requests, deps } = setup({ prepareCreate, prepareEngine })
await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION })
await vi.waitFor(() => expect(replies[0]).toMatchObject({ state: 'pending',
held: { service: 'install', detail: 'Downloading Codex. The harness starts once it is downloaded.' } }))
requests.open()
// Still downloading: asked again and held again, nothing installed beside it, no folder, nothing created.
clock += 3_000; await requests.recover()
await vi.waitFor(() => expect(inspect).toHaveBeenCalledTimes(2))
await vi.waitFor(() => expect(downloadingNow).toHaveBeenCalledTimes(2))
expect(deps.receipts.status(CREATION)).toMatchObject({ state: 'pending', held: { service: 'install' } })
expect(prepareProjectFolder).not.toHaveBeenCalled()
// The download ends: the next pass creates it.
downloading = false
clock += 3_000; await requests.recover()
await vi.waitFor(() => expect(dispatch).toHaveBeenCalledOnce())
await vi.waitFor(() => expect(deps.receipts.status(CREATION)).toEqual({ state: 'created', agentId: 'new-agent' }))
// Once: later passes find nothing to do.
for (let pass = 0; pass < 3; pass++) { clock += 3_000; await requests.recover() }
await settle()
expect(dispatch).toHaveBeenCalledOnce()
expect(prepareProjectFolder).toHaveBeenCalledOnce()
expect(ensure).not.toHaveBeenCalled()
})
it('trusts only a folder it just made empty, or a worktree of a repository the engine already trusts', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const { ask, replies } = setup()
const launch = async (payload: Record<string, unknown>, n: number) => { await ask({ creationId: `${CREATION}-${n}`, ...payload }); await vi.waitFor(() => expect(replies).toHaveLength(n)) }
await launch({ engine: 'claude', projectSource: 'new' }, 1)
expect(preTrustClaudeProject).toHaveBeenCalledWith('/projects/prepared')
vi.mocked(codexTrusts).mockReturnValueOnce(true)
await launch({ engine: 'codex', projectSource: 'worktree', gitSource: '/repo', branchName: 'feature' }, 2)
expect(codexTrusts).toHaveBeenCalledWith('/repo', null)
expect(preTrustCodexProject).toHaveBeenCalledWith('/projects/prepared', null)
await launch({ engine: 'claude', projectSource: 'worktree', gitSource: '/repo', branchName: 'feature' }, 3)
await launch({ engine: 'claude', projectSource: 'branch', gitSource: '/repo', branchRef: 'refs/heads/main' }, 4)
await launch({ engine: 'pi', projectSource: 'new' }, 5)
expect(preTrustClaudeProject).toHaveBeenCalledOnce()
expect(preTrustCodexProject).toHaveBeenCalledOnce()
vi.mocked(preTrustClaudeProject).mockImplementationOnce(() => { throw new Error('config locked') }).mockImplementationOnce(() => { throw 'busy' })
await launch({ engine: 'claude', projectSource: 'new' }, 6)
await launch({ engine: 'claude', projectSource: 'new' }, 7)
expect(console.warn).toHaveBeenCalledWith('[agent] pre-trust /projects/prepared · config locked')
expect(console.warn).toHaveBeenCalledWith('[agent] pre-trust /projects/prepared · busy')
expect(claudeTrusts).toHaveBeenCalledWith('/repo')
})
// WIN-DELL and the Mac Studio, 2026-10-26: Swarm Leads in a reused or fresh checkout of the project's repository sat at
// Claude Code's trust question, and so did the next Lead in a worktree of it, its source never answered.
it('trusts a Swarm agent\'s checkout of its remote project in its owner\'s own mode, and no other existing folder', async () => {
const { ask, replies } = setup()
const launch = async (payload: Record<string, unknown>, n: number) => { await ask({ creationId: `${CREATION}-${n}`, ...payload }); await vi.waitFor(() => expect(replies).toHaveLength(n)) }
const remote = { projectSource: 'remote', repositoryUrl: 'https://github.com/acme/app.git' }
await launch({ engine: 'claude', ...remote, swarmRole: 'lead' }, 1)
expect(preTrustClaudeProject).toHaveBeenCalledWith('/projects/prepared')
// The guard: the same checkout outside a Swarm, and a Swarm agent in a folder it was handed.
await launch({ engine: 'claude', ...remote, permissionMode: 'full' }, 2)
await launch({ engine: 'claude', cwd: dir, swarmRole: 'lead' }, 3)
await launch({ engine: 'claude', cwd: dir, swarmRole: 'lead', permissionMode: 'full' }, 4)
await ask({ creationId: `${CREATION}-5`, engine: 'claude', projectSource: 'worktree', gitSource: '/elsewhere', branchName: 'feature', swarmRole: 'lead' }, false)
await vi.waitFor(() => expect(replies).toHaveLength(5))
expect(preTrustClaudeProject).toHaveBeenCalledOnce()
// Claude Code only: a Codex Lead's checkout is not trusted for it.
await launch({ engine: 'codex', ...remote, swarmRole: 'lead' }, 6)
expect(preTrustCodexProject).not.toHaveBeenCalled()
// A worktree made from that checkout then inherits its answer.
vi.mocked(claudeTrusts).mockImplementation(path => path === '/projects/prepared')
await launch({ engine: 'claude', projectSource: 'worktree', gitSource: '/projects/prepared', branchName: 'feature', swarmRole: 'lead' }, 7)
expect(preTrustClaudeProject).toHaveBeenCalledTimes(2)
})
// 2026-10-30: a new Swarm made with Cmd+S on a local openharness checkout started its PM in a worktree of that
// checkout, which Claude Code had never been told to trust; the PM sat at the question, shown as Idle in the Swarm.
it('trusts the worktree of a repository the person picked in this machine\'s window for a Swarm agent in any mode', async () => {
const { ask, replies } = setup()
const launch = async (payload: Record<string, unknown>, local: boolean, n: number) => { await ask({ creationId: `${CREATION}-${n}`, ...payload }, local); await vi.waitFor(() => expect(replies).toHaveLength(n)) }
const worktree = { projectSource: 'worktree', gitSource: '/Users/me/openharness', branchName: 'lively-meteor' }
await launch({ engine: 'claude', ...worktree, swarmRole: 'lead' }, true, 1)
expect(preTrustClaudeProject).toHaveBeenCalledWith('/projects/prepared')
await launch({ engine: 'claude', ...worktree, swarmRole: 'lead', permissionMode: 'full' }, true, 2)
expect(preTrustClaudeProject).toHaveBeenCalledTimes(2)
// Not relayed, not outside a Swarm, not for Codex: those stay the person's question.
await launch({ engine: 'claude', ...worktree, swarmRole: 'lead' }, false, 3)
await launch({ engine: 'claude', ...worktree, permissionMode: 'full' }, true, 4)
await launch({ engine: 'codex', ...worktree, swarmRole: 'lead' }, true, 5)
expect(preTrustClaudeProject).toHaveBeenCalledTimes(2)
expect(preTrustCodexProject).not.toHaveBeenCalled()
})
// A Codex agent on its own profile reads its trust from THAT profile's config.toml: the trust was
// read and written in ~/.codex alone, so it got Codex's trust prompt in a folder Harness had just made.
it('asks and records a Codex agent\'s trust in its own profile', async () => {
const { ask, replies } = setup()
const empty = join(root.projects, 'fresh-profile')
mkdirSync(empty)
vi.mocked(codexTrusts).mockReturnValueOnce(true)
await ask({ creationId: `${CREATION}-1`, engine: 'codex', codexHome: '/profiles/work', projectSource: 'worktree', gitSource: '/repo', branchName: 'feature' })
await ask({ creationId: `${CREATION}-2`, engine: 'codex', codexHome: '/profiles/work', cwd: empty })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(codexTrusts).toHaveBeenCalledWith('/repo', '/profiles/work')
expect(preTrustCodexProject).toHaveBeenNthCalledWith(1, '/projects/prepared', '/profiles/work')
expect(preTrustCodexProject).toHaveBeenNthCalledWith(2, empty, '/profiles/work')
})
it('trusts an empty workspace this machine\'s own window made in the projects folder, and nothing else', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const { ask, replies } = setup()
const empty = join(root.projects, 'fresh')
const filled = join(root.projects, 'filled')
mkdirSync(empty)
mkdirSync(filled)
writeFileSync(join(filled, 'README.md'), 'mine')
const launch = async (payload: Record<string, unknown>, local: boolean, n: number) => { await ask({ creationId: `${CREATION}-${n}`, ...payload }, local); await vi.waitFor(() => expect(replies).toHaveLength(n)) }
await launch({ engine: 'claude', cwd: empty }, true, 1)
await launch({ engine: 'codex', cwd: empty }, true, 2)
expect(preTrustClaudeProject).toHaveBeenCalledWith(empty)
expect(preTrustCodexProject).toHaveBeenCalledWith(empty, null)
await launch({ engine: 'claude', cwd: filled }, true, 3)
await launch({ engine: 'claude', cwd: join(root.projects, 'missing') }, true, 4)
await launch({ engine: 'claude', cwd: empty }, false, 5)
await launch({ engine: 'claude', cwd: dir }, true, 6)
await launch({ engine: 'pi', cwd: empty }, true, 7)
vi.mocked(installedDsh).mockReturnValueOnce({ id: 'acme/notes', manifest: { kind: 'agent' } } as never)
await launch({ engine: 'claude', cwd: empty, dsh: 'acme/notes' }, true, 8)
expect(preTrustClaudeProject).toHaveBeenCalledOnce()
expect(preTrustCodexProject).toHaveBeenCalledOnce()
vi.mocked(preTrustCodexProject).mockImplementationOnce(() => { throw new Error('config locked') }).mockImplementationOnce(() => { throw 'busy' })
await launch({ engine: 'codex', cwd: empty }, true, 9)
await launch({ engine: 'codex', cwd: empty }, true, 10)
expect(warn).toHaveBeenCalledWith(`[agent] pre-trust ${empty} · config locked`)
expect(warn).toHaveBeenCalledWith(`[agent] pre-trust ${empty} · busy`)
})
it('resolves a model picked by name inside the receipt, and holds it when it cannot be read', async () => {
const { ask, create, replies } = setup()
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'm', grid: 'fixture-grid' } } as never)
resolveNewAgentModel.mockResolvedValueOnce({ networkId: 'resolved' } as never).mockRejectedValueOnce(new Error('offline'))
await ask({ engine: 'claude', cwd: '/w', creationId: CREATION })
await ask({ engine: 'claude', cwd: '/w', creationId: `${CREATION}-2` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(vi.mocked(create!).mock.calls[0][0].grid).toEqual({ networkId: 'resolved' })
expect(replies.find(reply => reply.creationId === `${CREATION}-2`)).toMatchObject({ creationId: `${CREATION}-2`, state: 'pending', held: { service: 'models' } })
})
it('says why a receipt could not be kept, and answers INTERNAL when the answer cannot be put together', async () => {
const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }) } })
expect(await storage.ask({ engine: 'claude', cwd: '/w', creationId: CREATION })).toStrictEqual({ error: 'CREATION_STORAGE_FAILED' })
const broken = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new Error('bug') }) } })
expect(await broken.ask({ engine: 'claude', cwd: '/w', creationId: CREATION })).toStrictEqual({ error: 'INTERNAL' })
const frameless = setup({ toProject: vi.fn(async () => { throw new Error('no frame') }) })
await frameless.ask({ engine: 'claude', cwd: '/w', creationId: CREATION })
await vi.waitFor(() => expect(frameless.replies).toStrictEqual([{ error: 'INTERNAL' }]))
})
})
describe('durable model request validation', () => {
it('retains canonical DSH identity for old-name requests and existing v1 fingerprints', async () => {
const { ask, deps, create, replies } = setup()
vi.mocked(installedDsh).mockReturnValue({ id: 'acme/current', manifest: { kind: 'agent', formerly: ['acme/former'] } } as never)
const input = { engine: 'claude', cwd: '/w', bypassPermission: false, permissionMode: null,
grid: null, codexHome: null, dsh: 'acme/current', prompt: null, name: null, agent: null, resumeSessionId: null, takeOver: null }
await deps.receipts.run(CREATION, creationFingerprint(input), async () => ({ state: 'created', agentId: 'new-agent' }))
const payload = { engine: 'claude', cwd: '/w', dsh: 'acme/former', creationId: CREATION, bypassPermission: false }
await ask(payload)
await vi.waitFor(() => expect(replies.at(-1)).toMatchObject({ state: 'created' }))
expect(create).not.toHaveBeenCalled()
await ask({ ...payload, creationId: `${CREATION}-new` })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(create).toHaveBeenCalledWith(input)
})
it('keeps fresh legacy installation refusals correctable with the same ID', async () => {
const { ask, replies, deps } = setup()
const payload = { engine: 'claude', cwd: '/w', dsh: 'acme/notes', creationId: CREATION }
expect(await ask(payload)).toMatchObject({ error: 'INVALID_DSH' })
expect(deps.receipts.status(CREATION)).toEqual({ state: 'missing' })
vi.mocked(installedDsh).mockReturnValue({ id: 'acme/notes', manifest: { kind: 'agent' } } as never)
await ask(payload)
await vi.waitFor(() => expect(replies.at(-1)).toMatchObject({ state: 'created' }))
})
it('reports a current installation refusal after the model becomes available', async () => {
const { ask, replies, create } = setup()
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'm', grid: 'fixture-grid' } })
resolveNewAgentModel.mockResolvedValue({ networkId: 'resolved' } as never)
await ask({ engine: 'claude', cwd: '/w', dsh: 'acme/notes', creationId: CREATION })
await vi.waitFor(() => expect(replies.at(-1)).toMatchObject({ state: 'failed', failure: { code: 'INVALID_DSH' } }))
expect(create).not.toHaveBeenCalled()
})
it('holds unfamiliar or incomplete saved intent without preparing a project or dispatching', async () => {
const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>()
const { deps, requests, create } = setup({ prepareCreate })
const records = [{ kind: 'future-kind' }, { kind: 'model-create-v1', local: true, input: {}, selection: {} },
{ kind: 'native-create-v1' }, { kind: 'native-create-v1', local: true, input: {}, label: 'harness-claude-fixture' },
{ kind: 'native-create-v1', local: true, input: { engine: 'claude', cwd: '' }, label: 'harness-claude-fixture', projectFolder: { source: 7 } }]
const held = { service: 'models', detail: 'Waiting for the model.' }
for (const [n, request] of records.entries()) {
await deps.receipts.runIntent(`${CREATION}-${n}`, creationFingerprint(request), request, held, async () => null)
}
const retry = vi.spyOn(deps.receipts, 'runIntent')
requests.open(); await requests.recover()
await vi.waitFor(() => expect(retry).toHaveBeenCalledTimes(records.length))
for (let n = 0; n < records.length; n++) expect(deps.receipts.status(`${CREATION}-${n}`)).toEqual({ state: 'pending', held })
expect(resolveNewAgentModel).not.toHaveBeenCalled()
expect(prepareProjectFolder).not.toHaveBeenCalled()
expect(create).not.toHaveBeenCalled()
expect(prepareCreate).not.toHaveBeenCalled()
})
it('holds recovery while no local creator is available', async () => {
const { deps, requests } = setup({}, { create: null })
const request = { kind: 'model-create-v1', local: true, input: { engine: 'claude', cwd: '/w', grid: null }, selection: { grid: 'fixture-grid', model: 'm' } }
const held = { service: 'models', detail: 'Waiting for the model.' }
await deps.receipts.runIntent(CREATION, creationFingerprint(request), request, held, async () => null)
const retry = vi.spyOn(deps.receipts, 'runIntent')
requests.open(); await requests.recover()
await vi.waitFor(() => expect(retry).toHaveBeenCalledOnce())
expect(deps.receipts.status(CREATION)).toEqual({ state: 'pending', held })
expect(resolveNewAgentModel).not.toHaveBeenCalled()
})
it('rejects invalid cancellation IDs and reports storage uncertainty without acknowledging cancellation', async () => {
const { deps, requests } = setup()
const answer = vi.fn()
await requests.cancelCreate({ creationId: '../invalid' }, { local: true }, answer)
expect(answer).toHaveBeenLastCalledWith({ error: 'INVALID_CREATION_ID' })
const cancel = vi.spyOn(deps.receipts, 'cancelIntent')
cancel.mockImplementationOnce(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') })
await requests.cancelCreate({ creationId: CREATION }, { local: true }, answer)
expect(answer).toHaveBeenLastCalledWith({ error: 'CREATION_STORAGE_FAILED' })
cancel.mockImplementationOnce(() => { throw new Error('unknown') })
await requests.cancelCreate({ creationId: CREATION }, { local: true }, answer)
expect(answer).toHaveBeenLastCalledWith({ error: 'INTERNAL' })
})
})
describe('agent_create_status', () => {
it('reports the model and effort flags saved by a completed native launch', async () => {
const { status, deps } = setup()
const request = { kind: 'native-create-v1', input: { launchModel: { model: 'opus', effort: 'high' } } }
await deps.receipts.runIntent(CREATION, creationFingerprint(request), request,
{ service: 'launch', detail: 'Preparing.' }, async () => async () => ({ state: 'created', agentId: 'new-agent' }))
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'created', agent: { id: 'new-agent' },
launchModel: { model: 'opus', effort: 'high' } })
})
it('names a launch by a valid creation id, and says what became of it', async () => {
const { status, deps } = setup()
expect(await status({ creationId: 'short' })).toStrictEqual({ error: 'INVALID_CREATION_ID' })
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'missing' })
const outcome = (value: AgentCreationOutcome | { state: 'pending' }) => { vi.spyOn(deps.receipts, 'status').mockReturnValueOnce(value as never) }
outcome({ state: 'created', agentId: 'forked', level: 'handoff', resumed: true })
const created = await status({ creationId: CREATION })
expect(created).toStrictEqual({ creationId: CREATION, state: 'created', agent: { id: 'forked' }, level: 'handoff', resumed: true })
expect(Object.keys(created!)).toEqual(['creationId', 'state', 'agent', 'level', 'resumed'])
outcome({ state: 'created', agentId: 'deleted-since' })
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'unavailable', createdAgentId: 'deleted-since' })
outcome({ state: 'failed', error: 'ENGINE_MISSING', detail: 'claude is not installed', preparedFolder: '/projects/prepared' })
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'failed', preparedFolder: '/projects/prepared', failure: { code: 'ENGINE_MISSING', detail: 'claude is not installed' } })
outcome({ state: 'unconfirmed' })
expect(await status({ creationId: CREATION })).toStrictEqual({ creationId: CREATION, state: 'unconfirmed' })
})
it('says why a receipt could not be read', async () => {
const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), run: vi.fn(), status: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }) } })
expect(await storage.status({ creationId: CREATION })).toStrictEqual({ error: 'CREATION_STORAGE_FAILED' })
const broken = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), run: vi.fn(), status: vi.fn(() => { throw new Error('bug') }) } })
expect(await broken.status({ creationId: CREATION })).toStrictEqual({ error: 'INTERNAL' })
})
it('tells the host why when the status read fails on a permissions problem (task #3861)', async () => {
const detail = 'The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions).'
const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), run: vi.fn(), status: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED', detail) }) } })
expect(await storage.status({ creationId: CREATION })).toStrictEqual({ error: 'CREATION_STORAGE_FAILED', detail })
})
})
describe('agent_resume and agent_restart', () => {
it('relaunch the agent named, resume taking a permission mode, and answer with its frame and whether it resumed', async () => {
const { relaunch, resume, restart } = setup()
expect(await relaunch('agent_restart', { agentId: 'a1' })).toStrictEqual({ agent: { id: 'a1' }, resumed: false })
expect(await relaunch('agent_resume', { agentId: 'a1' })).toStrictEqual({ agent: { id: 'a1' }, resumed: true })
expect(await relaunch('agent_resume', { agentId: 'a1', permissionMode: 'plan' })).toMatchObject({ resumed: true })
expect(restart).toHaveBeenCalledWith('a1')
expect(vi.mocked(resume!).mock.calls).toEqual([['a1'], ['a1', 'plan']])
})
it('refuse a resume that would trade Team-written work\'s mode for another: its project settings stay off (audit H2)', async () => {
const run = setup({ byAgent: (id: string) => id === 'written' ? { ...session('written'), permissionMode: 'teamWritten' } : undefined })
expect(await run.relaunch('agent_resume', { agentId: 'written', permissionMode: 'full' })).toStrictEqual({ error: 'INVALID_PERMISSION_MODE' })
})
it('refuse a request with no agent, on a machine that cannot relaunch, and a permission mode a restart has no use for', async () => {
const { relaunch, restart } = setup()
expect(await relaunch('agent_restart', {})).toStrictEqual({ error: 'MISSING_AGENT_ID' })
expect(await setup({}, { restart: null }).relaunch('agent_restart', { agentId: 'a1' })).toStrictEqual({ error: 'UNSUPPORTED_ON_REMOTE' })
expect(await setup({}, { resume: null }).relaunch('agent_resume', { agentId: 'a1' })).toStrictEqual({ error: 'UNSUPPORTED_ON_REMOTE' })
for (const [type, permissionMode] of [['agent_restart', 'auto'], ['agent_resume', 7], ['agent_resume', 'allow']] as const) {
expect(await relaunch(type, { agentId: 'a1', permissionMode })).toStrictEqual({ error: 'INVALID_PERMISSION_MODE' })
}
expect(restart).not.toHaveBeenCalled()
})
it('pass a refusal on with its cause when it has one', async () => {
const failed = setup({}, { restart: vi.fn(async () => ({ ok: false as const, error: 'RESTART_FAILED', detail: 'claude did not come back up' })) })
expect(await failed.relaunch('agent_restart', { agentId: 'a1' })).toStrictEqual({ error: 'RESTART_FAILED', detail: 'claude did not come back up' })
const bare = setup({}, { restart: vi.fn(async () => ({ ok: false as const, error: 'AGENT_NOT_FOUND' })) })
expect(await bare.relaunch('agent_restart', { agentId: 'a1' })).toStrictEqual({ error: 'AGENT_NOT_FOUND' })
})
// Which check refused a resume's history (lib/resumeAgentService.ts) reaches the reply, so its counter can name it.
it('pass a refusal\'s reason on, directly and through a receipt', async () => {
const refused = { ok: false as const, error: 'RESUME_PREPARATION_FAILED', reason: 'invalid_json', detail: 'Could not prepare the saved conversation.' }
const direct = setup({}, { resume: vi.fn(async () => refused) })
expect(await direct.relaunch('agent_resume', { agentId: 'a1' })).toStrictEqual({ error: 'RESUME_PREPARATION_FAILED', reason: 'invalid_json', detail: 'Could not prepare the saved conversation.' })
const kept = setup({}, { resume: vi.fn(async () => refused) })
await kept.relaunch('agent_resume', { agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(kept.replies).toStrictEqual([{ creationId: CREATION, state: 'failed',
failure: { code: 'RESUME_PREPARATION_FAILED', reason: 'invalid_json', detail: 'Could not prepare the saved conversation.' } }]))
})
it('keep a receipt: one relaunch per creation id, an unobserved one unconfirmed, a refusal failed and cut short', async () => {
const { relaunch, replies, resume } = setup()
await relaunch('agent_resume', { agentId: 'a1', creationId: CREATION, permissionMode: 'auto' })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(replies[0]).toStrictEqual({ creationId: CREATION, state: 'created', agent: { id: 'a1' }, resumed: true })
await relaunch('agent_resume', { agentId: 'a1', creationId: CREATION, permissionMode: 'ask' })
expect(replies.at(-1)).toStrictEqual({ error: 'CREATION_CONFLICT' })
expect(resume).toHaveBeenCalledOnce()
expect(await relaunch('agent_restart', { agentId: 'a1', creationId: 'short' })).toStrictEqual({ error: 'INVALID_CREATION_ID' })
for (const [error, state] of [['RESTART_FAILED', 'unconfirmed'], ['RESUME_UNCONFIRMED', 'unconfirmed'], ['AGENT_BUSY', 'failed']] as const) {
const run = setup({}, { restart: vi.fn(async () => ({ ok: false as const, error, detail: 'd'.repeat(3000) })) })
await run.relaunch('agent_restart', { agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
expect(run.replies[0].state).toBe(state)
if (state === 'failed') expect(run.replies[0].failure).toStrictEqual({ code: 'AGENT_BUSY', detail: 'd'.repeat(2000) })
}
const bare = setup({}, { restart: vi.fn(async () => ({ ok: false as const, error: 'AGENT_BUSY' })) })
await bare.relaunch('agent_restart', { agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(bare.replies).toStrictEqual([{ creationId: CREATION, state: 'failed', failure: { code: 'AGENT_BUSY' } }]))
})
it('say why a receipt could not be kept, and INTERNAL when the answer cannot be put together', async () => {
const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }) } })
expect(await storage.relaunch('agent_restart', { agentId: 'a1', creationId: CREATION })).toStrictEqual({ error: 'CREATION_STORAGE_FAILED' })
const broken = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new Error('bug') }) } })
expect(await broken.relaunch('agent_restart', { agentId: 'a1', creationId: CREATION })).toStrictEqual({ error: 'INTERNAL' })
const frameless = setup({ toProject: vi.fn(async () => { throw new Error('no frame') }) })
await frameless.relaunch('agent_restart', { agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(frameless.replies).toStrictEqual([{ error: 'INTERNAL' }]))
})
})
describe('agent_restart with launchArgs', () => {
/** A record the launch itself writes, as a real restart does once the engine is back: the daemon saves on success. */
const records = (flags?: string[]) => {
const row = { ...session('a1'), ...(flags ? { launchArgs: flags } : {}) }
return { row, byAgent: (id: string) => id === 'a1' ? row : undefined }
}
it('hands the parsed words to the restart, saving nothing itself, and echoes what the record then holds, directly and through a receipt', async () => {
const store = records()
const restart = vi.fn(async (_id: string, words?: string[]) => { store.row.launchArgs = words; return { ok: true as const, session: store.row, resumed: false } })
const run = setup({ byAgent: store.byAgent }, { restart })
expect(await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome' })).toStrictEqual({ agent: { id: 'a1' }, resumed: false, launchArgs: ['--chrome'] })
expect(restart).toHaveBeenCalledWith('a1', ['--chrome'])
run.replies.length = 0
await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome', creationId: CREATION })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
expect(run.replies[0]).toMatchObject({ creationId: CREATION, state: 'created', launchArgs: ['--chrome'] })
// The same receipt asked again does not restart a second time.
await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome', creationId: CREATION })
expect(run.replies.at(-1)).toMatchObject({ launchArgs: ['--chrome'] })
expect(restart).toHaveBeenCalledTimes(2)
})
it('clears with an empty string and echoes an empty list', async () => {
const store = records(['--old'])
const restart = vi.fn(async (_id: string, words?: string[]) => { store.row.launchArgs = words?.length ? words : undefined; return { ok: true as const, session: store.row, resumed: false } })
const run = setup({ byAgent: store.byAgent }, { restart })
expect(await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '' })).toMatchObject({ launchArgs: [] })
expect(restart).toHaveBeenCalledWith('a1', [])
})
it('refuses a flag Harness sets, a non-string, a Team-written agent, an unknown agent and a non-owner, restarting nothing', async () => {
const run = setup({ byAgent: (id: string) => id === 'written' ? { ...session('written'), permissionMode: 'teamWritten' } : id === 'a1' ? session('a1') : undefined })
expect(await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--model x' }))
.toStrictEqual({ error: 'INVALID_LAUNCH_ARGS', detail: '--model is set by Harness and can\'t be added here.' })
expect(await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: 5 })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
expect(await run.relaunch('agent_restart', { agentId: 'written', launchArgs: '--chrome' })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
expect(await run.relaunch('agent_restart', { agentId: 'gone', launchArgs: '--chrome' })).toStrictEqual({ error: 'AGENT_NOT_FOUND' })
expect(run.restart).not.toHaveBeenCalled()
})
// The words are run by the engine as the owner: a device (dial, Pro), an agent's own CLI and a guest may not set them.
it('takes them only from the owner\'s own app, whichever way the others ask', async () => {
const run = setup()
for (const type of ['agent_restart', 'agent_resume']) {
expect(await run.relaunch(type, { agentId: 'a1', launchArgs: '--chrome' }, { ownerApp: false }))
.toStrictEqual({ error: 'INVALID_LAUNCH_ARGS', detail: 'Launch flags can only be changed from your own Harness app.' })
expect(await run.relaunch(type, { agentId: 'a1', launchArgs: '--chrome', creationId: CREATION }, { ownerApp: false })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
}
expect(run.restart).not.toHaveBeenCalled()
expect(run.resume).not.toHaveBeenCalled()
// The same asker still restarts and resumes without them.
expect(await run.relaunch('agent_restart', { agentId: 'a1' }, { ownerApp: false })).toMatchObject({ resumed: false })
expect(await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome' })).toMatchObject({ resumed: false })
expect(run.restart).toHaveBeenCalledTimes(2)
})
it('takes them on a resume too, validated, handed over and fingerprinted, with a permission mode beside them', async () => {
const store = records()
const resume = vi.fn(async (_id: string, _mode?: string, words?: string[]) => { store.row.launchArgs = words; return { ok: true as const, session: store.row, resumed: true } })
const run = setup({ byAgent: store.byAgent }, { resume })
expect(await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--chrome' })).toStrictEqual({ agent: { id: 'a1' }, resumed: true, launchArgs: ['--chrome'] })
expect(resume).toHaveBeenLastCalledWith('a1', undefined, ['--chrome'])
await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--chrome', permissionMode: 'plan' })
expect(resume).toHaveBeenLastCalledWith('a1', 'plan', ['--chrome'])
expect(await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--model x' })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
run.replies.length = 0
await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--chrome', creationId: CREATION })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--other', creationId: CREATION })
expect(run.replies.at(-1)).toStrictEqual({ error: 'CREATION_CONFLICT' })
})
// A harness a bad flag left stopped lives in the stopped-agents store, not the registry (resumeAgentService.ts).
it('resumes a stopped agent with them: its engine and Team-written mode are read from the stopped store', async () => {
const stopped = { ...session('a1'), engine: 'codex' as const }
const resume = vi.fn(async () => ({ ok: true as const, session: stopped, resumed: true }))
const run = setup({ byAgent: () => undefined, stoppedAgent: (id) => id === 'a1' ? stopped : undefined }, { resume })
// Codex's own -c is the owner's to use; a key Harness sets is not, and the engine is the stopped row's.
expect(await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '-c model=x' })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
expect(await run.relaunch('agent_resume', { agentId: 'a1', launchArgs: '-c model_reasoning_effort=high' })).toMatchObject({ resumed: true })
expect(resume).toHaveBeenCalledExactlyOnceWith('a1', undefined, ['-c', 'model_reasoning_effort=high'])
const written = setup({ byAgent: () => undefined, stoppedAgent: () => ({ ...stopped, permissionMode: 'teamWritten' }) })
expect(await written.relaunch('agent_resume', { agentId: 'a1', launchArgs: '--chrome' })).toMatchObject({ error: 'INVALID_LAUNCH_ARGS' })
expect(await run.relaunch('agent_resume', { agentId: 'nowhere', launchArgs: '--chrome' })).toStrictEqual({ error: 'AGENT_NOT_FOUND' })
})
// Nothing is saved here: the launch saves on success. A refusal, a missing process or an engine that does not start
// carries no echo, because there is nothing new on the record to report.
it('echoes nothing on a failed reply, directly or through a receipt, whatever the failure', async () => {
for (const error of ['AGENT_BUSY', 'NO_ACTIVE_PROCESS', 'RESTART_FAILED', 'RESUME_UNCONFIRMED']) {
for (const creationId of [undefined, CREATION]) {
const run = setup({}, { restart: vi.fn(async () => ({ ok: false as const, error })) })
await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome', ...(creationId ? { creationId } : {}) })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
expect(run.replies[0], `${error} ${creationId}`).not.toHaveProperty('launchArgs')
expect(run.replies[0]).not.toHaveProperty('agent')
}
}
})
it('treats the same receipt with different flags as a different request', async () => {
const run = setup()
await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--chrome', creationId: CREATION })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
await run.relaunch('agent_restart', { agentId: 'a1', launchArgs: '--other', creationId: CREATION })
expect(run.replies.at(-1)).toStrictEqual({ error: 'CREATION_CONFLICT' })
expect(run.restart).toHaveBeenCalledOnce()
})
})
describe('agent_fork', () => {
it('forks the agent named, with a name and a first message when given, and answers with the new one\'s frame and what it got', async () => {
const { forkAsk, fork } = setup()
expect(await forkAsk({ agentId: 'a1', name: ` ${'n'.repeat(130)} `, prompt: 'carry on' })).toStrictEqual({ agent: { id: 'forked' }, level: 'native' })
expect(fork).toHaveBeenCalledWith({ agentId: 'a1', name: 'n'.repeat(120), prompt: 'carry on' })
await forkAsk({ agentId: 'a1', name: ' ', prompt: ' ' })
await forkAsk({ agentId: 'a1', prompt: null })
expect(vi.mocked(fork!).mock.calls.slice(1).map(([input]) => input)).toEqual([{ agentId: 'a1', name: null, prompt: null }, { agentId: 'a1', name: null, prompt: null }])
})
it('refuses a request with no agent, on a machine that cannot fork, and a first message that is not text or too long', async () => {
const { forkAsk, fork } = setup()
expect(await forkAsk({})).toStrictEqual({ error: 'MISSING_AGENT_ID' })
expect(await setup({}, { fork: null }).forkAsk({ agentId: 'a1' })).toStrictEqual({ error: 'UNSUPPORTED_ON_REMOTE' })
expect(await forkAsk({ agentId: 'a1', prompt: 7 })).toStrictEqual({ error: 'INVALID_PROMPT' })
expect(await forkAsk({ agentId: 'a1', prompt: 'x'.repeat(MAX_FIRST_PROMPT_CHARS + 1) })).toStrictEqual({ error: 'PROMPT_TOO_LONG' })
expect(await forkAsk({ agentId: 'a1', creationId: 'short' })).toStrictEqual({ error: 'INVALID_CREATION_ID' })
expect(fork).not.toHaveBeenCalled()
})
it('passes a refusal on with its cause when it has one', async () => {
const failed = setup({}, { fork: vi.fn(async () => ({ ok: false as const, error: 'SPAWN_FAILED', detail: 'tmux: no server' })) })
expect(await failed.forkAsk({ agentId: 'a1' })).toStrictEqual({ error: 'SPAWN_FAILED', detail: 'tmux: no server' })
const bare = setup({}, { fork: vi.fn(async () => ({ ok: false as const, error: 'NOT_FORKABLE' })) })
expect(await bare.forkAsk({ agentId: 'a1' })).toStrictEqual({ error: 'NOT_FORKABLE' })
})
it('keeps a receipt like agent_create: one fork per creation id, a spawn it cannot confirm unconfirmed, a refusal failed and cut short', async () => {
const { forkAsk, replies, fork } = setup()
await forkAsk({ agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(replies[0]).toStrictEqual({ creationId: CREATION, state: 'created', agent: { id: 'forked' }, level: 'native' })
await forkAsk({ agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(replies).toHaveLength(2))
expect(fork).toHaveBeenCalledOnce()
for (const [error, state] of [['SPAWN_FAILED', 'unconfirmed'], ['REGISTRATION_FAILED', 'unconfirmed'], ['NOT_FORKABLE', 'failed']] as const) {
const run = setup({}, { fork: vi.fn(async () => ({ ok: false as const, error, detail: 'd'.repeat(3000) })) })
await run.forkAsk({ agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(run.replies).toHaveLength(1))
expect(run.replies[0].state).toBe(state)
if (state === 'failed') expect(run.replies[0].failure).toStrictEqual({ code: 'NOT_FORKABLE', detail: 'd'.repeat(2000) })
}
const bare = setup({}, { fork: vi.fn(async () => ({ ok: false as const, error: 'NOT_FORKABLE' })) })
await bare.forkAsk({ agentId: 'a1', creationId: CREATION })
await vi.waitFor(() => expect(bare.replies).toStrictEqual([{ creationId: CREATION, state: 'failed', failure: { code: 'NOT_FORKABLE' } }]))
})
it('says why a receipt could not be kept, and INTERNAL when the answer cannot be put together', async () => {
const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_CONFLICT') }) } })
expect(await storage.forkAsk({ agentId: 'a1', creationId: CREATION })).toStrictEqual({ error: 'CREATION_CONFLICT' })
const broken = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), status: vi.fn(), run: vi.fn(() => { throw new Error('bug') }) } })
expect(await broken.forkAsk({ agentId: 'a1', creationId: CREATION })).toStrictEqual({ error: 'INTERNAL' })
const frameless = setup({ toProject: vi.fn(async () => { throw new Error('no frame') }) })
await frameless.forkAsk({ agentId: 'a1', creationId: CREATION })
await settle()
await vi.waitFor(() => expect(frameless.replies).toStrictEqual([{ error: 'INTERNAL' }]))
})
})
describe('agent_create, from a guest', () => {
// A guest's New Harness never reaches the owner's launch: it is built as the guest's own OS user
// (core/agents/guestCreate.ts, docs/plans/2026-10-19-guest-machine-sharing-plan.md).
const guestAsk = async (run: ReturnType<typeof setup>, payload: Record<string, unknown>, guest = '[email protected]') => {
await run.requests.create(payload, { local: false, guest }, (result) => { run.replies.push(result) })
return run.replies.at(-1)
}
it('is the guest\'s own launch, never the owner\'s, answered as the owner\'s are', async () => {
const guestCreate = vi.fn(async () => ({ ok: true as const, session: session('guest-agent', { guest: '[email protected]' }) }))
const run = setup({ guestCreate: () => guestCreate })
expect(await guestAsk(run, { engine: 'claude', cwd: '/Users/owner' })).toEqual({ agent: { id: 'guest-agent' } })
expect(guestCreate).toHaveBeenCalledWith({ engine: 'claude', cwd: '/Users/owner' }, '[email protected]')
expect(run.create).not.toHaveBeenCalled()
guestCreate.mockResolvedValueOnce({ ok: false, error: 'GUEST_HELPER_REQUIRED', detail: 'Turn it on.' } as never)
expect(await guestAsk(run, { engine: 'claude' })).toEqual({ error: 'GUEST_HELPER_REQUIRED', detail: 'Turn it on.' })
guestCreate.mockResolvedValueOnce({ ok: false, error: 'TMUX_UNAVAILABLE' } as never)
expect(await guestAsk(run, { engine: 'claude' })).toEqual({ error: 'TMUX_UNAVAILABLE' })
})
it('keeps a receipt under its creationId, so a retry finds the same harness and a status check what became of it', async () => {
const guestCreate = vi.fn(async () => ({ ok: true as const, session: session('guest-agent', { guest: '[email protected]' }) }))
const run = setup({ guestCreate: () => guestCreate, byAgent: (id) => id === 'guest-agent' ? session('guest-agent') : undefined })
await guestAsk(run, { creationId: CREATION, engine: 'claude' })
await vi.waitFor(() => expect(run.replies.at(-1)).toEqual({ creationId: CREATION, state: 'created', agent: { id: 'guest-agent' } }))
await guestAsk(run, { creationId: CREATION, engine: 'claude' })
await vi.waitFor(() => expect(run.replies).toHaveLength(2))
expect(guestCreate).toHaveBeenCalledTimes(1)
// The same id for another launch is a conflict, not a second harness.
await guestAsk(run, { creationId: CREATION, engine: 'codex' })
await vi.waitFor(() => expect(run.replies.at(-1)).toEqual({ error: 'CREATION_CONFLICT' }))
})
it('records a refusal as the outcome, with its words', async () => {
const guestCreate = vi.fn(async () => ({ ok: false as const, error: 'GUEST_UNSUPPORTED', detail: 'On a computer shared with you, start a new conversation.' }))
const run = setup({ guestCreate: () => guestCreate })
await guestAsk(run, { creationId: CREATION, engine: 'claude' })
await vi.waitFor(() => expect(run.replies.at(-1)).toEqual({ creationId: CREATION, state: 'failed', failure: { code: 'GUEST_UNSUPPORTED', detail: 'On a computer shared with you, start a new conversation.' } }))
guestCreate.mockResolvedValueOnce({ ok: false, error: 'TMUX_UNAVAILABLE' } as never)
await guestAsk(run, { creationId: 'creation-fedcba9876543210', engine: 'claude' })
await vi.waitFor(() => expect(run.replies.at(-1)).toEqual({ creationId: 'creation-fedcba9876543210', state: 'failed', failure: { code: 'TMUX_UNAVAILABLE' } }))
})
it('starts nothing on a machine that cannot start a guest\'s harness, or for an id that is not one', async () => {
expect(await guestAsk(setup(), { engine: 'claude' })).toEqual({ error: 'GUEST_NOT_ALLOWED' })
expect(await guestAsk(setup({ guestCreate: () => null }), { engine: 'claude' })).toEqual({ error: 'GUEST_NOT_ALLOWED' })
const guestCreate = vi.fn()
expect(await guestAsk(setup({ guestCreate: () => guestCreate }), { creationId: 'short', engine: 'claude' })).toEqual({ error: 'INVALID_CREATION_ID' })
expect(guestCreate).not.toHaveBeenCalled()
})
it('answers INTERNAL when its receipt cannot be kept or its answer cannot be built', async () => {
const guestCreate = vi.fn(async () => ({ ok: true as const, session: session('guest-agent') }))
const broken = setup({ guestCreate: () => guestCreate })
vi.spyOn(broken.deps.receipts, 'run').mockImplementation(() => { throw new Error('disk full') })
expect(await guestAsk(broken, { creationId: CREATION, engine: 'claude' })).toEqual({ error: 'INTERNAL' })
const conflict = setup({ guestCreate: () => guestCreate })
vi.spyOn(conflict.deps.receipts, 'run').mockImplementation(() => { throw new AgentCreationReceiptError('CREATION_CONFLICT') })
expect(await guestAsk(conflict, { creationId: CREATION, engine: 'claude' })).toEqual({ error: 'CREATION_CONFLICT' })
const unbuilt = setup({ guestCreate: () => guestCreate, toProject: async () => { throw new Error('gone') }, byAgent: () => session('guest-agent') })
vi.spyOn(unbuilt.deps.receipts, 'run').mockResolvedValue({ state: 'created', agentId: 'guest-agent' })
await guestAsk(unbuilt, { creationId: CREATION, engine: 'claude' })
await vi.waitFor(() => expect(unbuilt.replies.at(-1)).toEqual({ error: 'INTERNAL' }))
})
})
describe('agent_create_status and agent_create_cancel, by who created the launch', () => {
// A guest sees and cancels only its own creations; for anyone else's id it hears what an unknown id gets.
const KIM = '[email protected]', LEE = '[email protected]'
const OTHER = 'creation-fedcba9876543210'
const guestCreate = () => vi.fn(async () => ({ ok: true as const, session: session('guest-agent', { guest: KIM }) }))
const as = (run: ReturnType<typeof setup>, guest?: string) => ({
status: async (creationId: string) => { const answer = vi.fn(); await run.requests.createStatus({ creationId }, guest ? { local: false, guest } : { local: true }, answer); return answer.mock.calls.at(-1)![0] },
cancel: async (creationId: string) => { const answer = vi.fn(); await run.requests.cancelCreate({ creationId }, guest ? { local: false, guest } : { local: true }, answer); return answer.mock.calls.at(-1)![0] },
})
const ownerHeld = async (run: ReturnType<typeof setup>, id = CREATION) => {
vi.mocked(parseNewAgentModel).mockReturnValue({ state: 'ok', selection: { model: 'fixture-model', grid: 'fixture-grid' } })
resolveNewAgentModel.mockResolvedValue(null)
await run.ask({ engine: 'claude', cwd: '/fixture/work', creationId: id })
await vi.waitFor(() => expect(run.replies.at(-1)).toMatchObject({ state: 'pending' }))
}
const guestMade = async (run: ReturnType<typeof setup>, guest = KIM, id = CREATION) => {
await run.requests.create({ creationId: id, engine: 'claude' }, { local: false, guest }, (result) => { run.replies.push(result) })
await vi.waitFor(() => expect(run.replies.at(-1)).toMatchObject({ creationId: id, state: 'created' }))
}
const withGuests = () => setup({ guestCreate: guestCreate, byAgent: (id) => id === 'guest-agent' || id === 'new-agent' ? session(id) : undefined })
it('answers a guest for the owner\'s pending creation exactly as for an unknown id, and cancels nothing', async () => {
const run = withGuests()
await ownerHeld(run)
const unknown = await as(run, KIM).status(OTHER)
expect(unknown).toEqual({ creationId: OTHER, state: 'missing' })
expect(await as(run, KIM).status(CREATION)).toEqual({ ...unknown, creationId: CREATION })
expect(await as(run, KIM).cancel(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run, KIM).cancel(OTHER)).toEqual({ creationId: OTHER, state: 'missing' })
expect(await as(run).status(CREATION)).toMatchObject({ state: 'pending' })
// The guest's cancel of an unknown id wrote nothing: no cancelled mark, no receipt file.
expect(await as(run).status(OTHER)).toEqual({ creationId: OTHER, state: 'missing' })
expect(existsSync(join(dir, `receipts-${stores}`, `${OTHER}.json`))).toBe(false)
})
it('answers a guest for the owner\'s finished creation as for an unknown id, and a cancel leaves it', async () => {
const run = withGuests()
await run.ask({ engine: 'claude', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(run.replies.at(-1)).toMatchObject({ state: 'created' }))
expect(await as(run, KIM).status(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run, KIM).cancel(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run).status(CREATION)).toMatchObject({ state: 'created', agent: { id: 'new-agent' } })
})
it('keeps one guest\'s creation from another, and shows a guest its own', async () => {
const run = withGuests()
await guestMade(run, KIM)
expect(await as(run, LEE).status(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run, LEE).cancel(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run, KIM).status(CREATION)).toEqual({ creationId: CREATION, state: 'created', agent: { id: 'guest-agent' } })
expect(await as(run, KIM).cancel(CREATION)).toMatchObject({ creationId: CREATION, state: 'created' })
})
it('lets the owner read and cancel its own creations and a guest\'s', async () => {
const run = withGuests()
await guestMade(run, KIM)
expect(await as(run).status(CREATION)).toMatchObject({ state: 'created', agent: { id: 'guest-agent' } })
await ownerHeld(run, OTHER)
expect(await as(run).status(OTHER)).toMatchObject({ state: 'pending' })
expect(await as(run).cancel(OTHER)).toEqual({ creationId: OTHER, state: 'cancelled' })
expect(await as(run).cancel(CREATION)).toMatchObject({ state: 'created' })
})
it('treats a receipt written before creators were recorded as the owner\'s, and keeps a guest\'s across a restart', async () => {
const run = withGuests()
await guestMade(run, KIM)
const reloaded = createLaunchRequests({ ...run.deps, receipts: new AgentCreationReceipts(join(dir, `receipts-${stores}`)) })
stopRequests.push(reloaded.stop)
const reread = async (guest: string | undefined, id: string) => {
const answer = vi.fn(); await reloaded.createStatus({ creationId: id }, guest ? { local: false, guest } : { local: true }, answer); return answer.mock.calls.at(-1)![0]
}
expect(await reread(KIM, CREATION)).toMatchObject({ state: 'created' })
expect(await reread(LEE, CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
writeFileSync(join(dir, `receipts-${stores}`, `${OTHER}.json`),
JSON.stringify({ version: 1, fingerprint: creationFingerprint({ old: true }), outcome: { state: 'created', agentId: 'new-agent' } }), { mode: 0o600 })
expect(await reread(KIM, OTHER)).toEqual({ creationId: OTHER, state: 'missing' })
expect(await reread(undefined, OTHER)).toMatchObject({ state: 'created' })
})
it('refuses a guest that reuses the owner\'s creation id, without telling what became of it', async () => {
const run = withGuests()
await run.ask({ engine: 'claude', cwd: '/fixture/work', creationId: CREATION })
await vi.waitFor(() => expect(run.replies.at(-1)).toMatchObject({ state: 'created' }))
run.replies.length = 0
await run.requests.create({ creationId: CREATION, engine: 'claude' }, { local: false, guest: KIM }, (result) => { run.replies.push(result) })
expect(run.replies).toEqual([{ error: 'CREATION_CONFLICT' }])
await ownerHeld(run, OTHER)
run.replies.length = 0
await run.requests.create({ creationId: OTHER, engine: 'claude' }, { local: false, guest: KIM }, (result) => { run.replies.push(result) })
expect(run.replies).toEqual([{ error: 'CREATION_CONFLICT' }])
})
it('lets a guest repeat its own create and still get its receipt', async () => {
const run = withGuests()
await guestMade(run, KIM)
run.replies.length = 0
await run.requests.create({ creationId: CREATION, engine: 'claude' }, { local: false, guest: KIM }, (result) => { run.replies.push(result) })
await vi.waitFor(() => expect(run.replies).toEqual([{ creationId: CREATION, state: 'created', agent: { id: 'guest-agent' } }]))
})
it('refuses an invalid id to a guest as to anyone, and hides damaged evidence from a guest but not from the owner', async () => {
const run = withGuests()
expect(await as(run, KIM).status('short')).toEqual({ error: 'INVALID_CREATION_ID' })
expect(await as(run, KIM).cancel('short')).toEqual({ error: 'INVALID_CREATION_ID' })
const damaged = () => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }
vi.spyOn(run.deps.receipts, 'creator').mockImplementation(damaged)
expect(await as(run, KIM).status(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
expect(await as(run, KIM).cancel(CREATION)).toEqual({ creationId: CREATION, state: 'missing' })
vi.spyOn(run.deps.receipts, 'status').mockImplementation(damaged)
vi.spyOn(run.deps.receipts, 'cancelIntent').mockImplementation(damaged)
expect(await as(run).status(CREATION)).toEqual({ error: 'CREATION_STORAGE_FAILED' })
expect(await as(run).cancel(CREATION)).toEqual({ error: 'CREATION_STORAGE_FAILED' })
})
it('answers INTERNAL, not missing, when a guest\'s creator lookup fails for another reason', async () => {
const run = withGuests()
vi.spyOn(run.deps.receipts, 'creator').mockImplementation(() => { throw new Error('bug') })
expect(await as(run, KIM).status(CREATION)).toEqual({ error: 'INTERNAL' })
})
})