The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { applyOpencodeSessionModel, parseOpencodeModelId, opencodeMajorVersion, opencodeV2TurnOpen } from '../../engines/launchControl.js'
import { isOpencodeV2 } from '../../engines/launchControl.js'
import { moveCodexConversation } from '../../engines/codex/providerMove.js'
import { binaryOnPath } from '../../lib/binaryOnPath.js'
import { builtinSqlite } from '../../lib/sqliteBuiltin.js'
import { validateLaunchOverrides } from '../../lib/launchOverrides.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { AgentRestartCoordinator, bypassPermissionFor, restartAgent } from '../../lib/restartAgent.js'
import { probeGatewayRuntime } from '../../lib/gatewayRuntime.js'
import { parseRuntimeProfile } from '../../lib/runtimeProfileWire.js'
import { workspaceMissing } from '../../lib/workspaceCheck.js'
import { TerminalAgentReconciler } from '../../lib/terminalAgentReconciler.js'
import type { TerminalBackend } from '../../lib/terminalBackend.js'
import { terminalRouteKey } from '../../lib/terminalRuntime.js'
import { createAgentRetargeter, type RetargetDeps } from './retarget.js'
import type { NativeLaunch } from '../../engines/nativeLaunch.js'
import { GUEST_HARNESS_REFUSAL } from '../guestPolicy.js'
import { createSwarmSkillAdoption } from '../../superTabs/inCore/adoption.js'
import { createLaunchAuthority } from './launchAuthority.js'
import type { SwarmSkillGrant } from '../../lib/swarmSkills.js'
vi.mock('../../engines/launchControl.js', async (real) => ({
...await real<object>(),
isOpencodeV2: vi.fn(() => false), opencodeMajorVersion: vi.fn(() => 1),
applyOpencodeSessionModel: vi.fn(async () => ({ ok: true })),
opencodeV2TurnOpen: vi.fn(async () => false),
parseOpencodeModelId: vi.fn((id: string) => ({ providerID: id.split('/')[0], modelID: id.split('/')[1] })),
}))
// Optional readers cannot gate a native launch decision.
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/codex/providerMove.js', () => ({ moveCodexConversation: vi.fn(async () => 'prepared') }))
vi.mock('../../lib/binaryOnPath.js', () => ({ binaryOnPath: vi.fn(() => true) }))
vi.mock('../../lib/sqliteBuiltin.js', async (real) => ({ ...await real<object>(), builtinSqlite: vi.fn(() => null) }))
vi.mock('../../lib/gatewayRuntime.js', async (real) => ({ ...await real<object>(), probeGatewayRuntime: vi.fn(async () => ({ kind: 'none' })) }))
vi.mock('../../lib/gridLaunchWire.js', async (real) => ({ ...await real<object>(), describeGridLaunch: vi.fn(() => 'claude on Home'), gridEnvVarNames: vi.fn(() => ['ANTHROPIC_BASE_URL']) }))
vi.mock('../../lib/launchOverrides.js', async (real) => ({ ...await real<object>(), validateLaunchOverrides: vi.fn(async () => ({ ok: true })) }))
vi.mock('../../lib/restartAgent.js', async (real) => ({
...await real<object>(),
bypassPermissionFor: vi.fn(async (_s: unknown, live: () => Promise<boolean>) => live()),
restartAgent: vi.fn(async () => ({ ok: true, resumed: true, processIdentity: { pid: 2, startMarker: 'new', executable: '/bin/claude' } })),
}))
vi.mock('../../lib/runtimeProfileWire.js', async (real) => ({ ...await real<object>(), parseRuntimeProfile: vi.fn(() => ({ engine: 'claude', model: 'opus' })) }))
vi.mock('../../lib/processTable.js', async (real) => ({
...await real<object>(),
processLaunchArgs: vi.fn(async () => 'codex -c model_providers.grid.base_url=http://grid.local/v1'),
}))
vi.mock('../../lib/workspaceCheck.js', () => ({ workspaceMissing: vi.fn(() => null) }))
const pane = { backend: 'tmux' as const, paneId: '%4' }
const grid = { networkId: 'g1', networkName: 'Home', baseUrl: 'http://g', model: 'big', apiKey: 'k' }
const agent = (over: Partial<RegisteredSession> = {}): RegisteredSession => ({
agentId: 'a1', sessionId: 's1', engine: 'claude', cwd: '/work', runtimes: [pane], processIdentity: { pid: 1, startMarker: 'old' }, ...over,
}) as unknown as RegisteredSession
function setup(row: RegisteredSession | null = agent(), over: Partial<RetargetDeps> = {}) {
const release = vi.fn(), releaseRoute = vi.fn()
const tmux = { name: 'tmux', holdOpen: vi.fn(), respawn: vi.fn(),
clearEnv: vi.fn<NonNullable<TerminalBackend['clearEnv']>>(async () => ({ state: 'succeeded', dispatch: 'executed' })),
releaseHold: vi.fn<TerminalBackend['releaseHold']>(async () => {}) }
const deps: RetargetDeps = {
sessionTurnOpen: vi.fn(() => false),
purgeBusy: vi.fn(() => false),
terminals: { backendFor: vi.fn((runtime: { backend: string }) => runtime.backend === 'tmux' ? tmux : undefined), instances: () => [tmux] } as unknown as RetargetDeps['terminals'],
registry: {
resolve: vi.fn(() => row ?? undefined),
byAgent: vi.fn(() => row ?? undefined),
updateProcessIdentity: vi.fn(),
setGridLaunch: vi.fn(),
setSubscriptionModel: vi.fn(),
setSubscriptionSession: vi.fn(),
setActive: vi.fn(),
} as unknown as RetargetDeps['registry'],
runtimeProfiles: { selectedModel: vi.fn(() => 'runtime-v1:claude:opus') } as never,
launchOverridesDeps: {} as never,
acquireTerminalControl: vi.fn(() => release),
relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: { gridLaunchRecord: { override: grid, webSearch: 'off' } } })) as never,
downgradedPermission: vi.fn(async (_s, bypass: boolean) => ({ bypassPermission: bypass, permissionMode: null })) as never,
agentReconciler: { holdRoute: vi.fn(() => releaseRoute) },
restartJobs: { busy: vi.fn(() => false), cancel: vi.fn(), revision: () => 0 } as never,
paneSwapDeps: vi.fn(() => ({})) as never,
liveBypassPermission: vi.fn(async () => true),
announceSession: vi.fn(),
refreshGridAssignment: vi.fn(),
opencodeDb: '/db/opencode.db',
...over,
}
return { deps, tmux, release, releaseRoute, retarget: createAgentRetargeter(deps) }
}
describe('retargeting an agent', () => {
beforeEach(() => {
vi.spyOn(console, 'log').mockImplementation(() => {})
vi.spyOn(console, 'warn').mockImplementation(() => {})
})
afterEach(() => { vi.restoreAllMocks(); vi.clearAllMocks() })
it('holds an unavailable native retarget before inspecting or mutating the pane', async () => {
const held = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Waiting for native evidence.' } as const
const run = setup(agent(), { launchOverridesDeps: { native: async () => held } as never })
expect(await run.retarget({ agentId: 'a1', grid })).toEqual(held)
expect(run.deps.sessionTurnOpen).not.toHaveBeenCalled()
expect(restartAgent).not.toHaveBeenCalled()
})
it.each(['ready', 'permission', 'snapshot'] as const)('keeps retarget native write and dispatch on one snapshot: %s', async mode => {
let nativeCurrent = true
const launch = { current: () => nativeCurrent, executable: '/fixture/native/opencode', environment: { HOME: '/fixture/home' }, opencodeMajor: 2 } as unknown as NativeLaunch
const run = setup(agent({ engine: 'opencode' }), {
launchOverridesDeps: { native: async () => ({ ok: true, launch }) } as never,
relaunchOverrides: async () => ({ ok: true, overrides: { native: launch, env: { HOME: '/fixture/home' }, extraArgs: [], clearEnv: [], sessionModel: 'fixture/model' } }),
downgradedPermission: async () => {
if (mode === 'snapshot') nativeCurrent = false
return { bypassPermission: false, ...(mode === 'permission' ? { nativeHold: 'Waiting for native permission flags.' } : {}) }
},
})
vi.mocked(applyOpencodeSessionModel).mockImplementationOnce(async (_input, options) => {
expect(_input.dbPath).toBe('/fixture/home/.local/share/opencode/opencode.db')
expect(options?.current?.()).toBe(true)
expect(options).toMatchObject({ executable: launch.executable, environment: { HOME: '/fixture/home' } })
return { ok: true }
})
const result = await run.retarget({ agentId: 'a1', grid })
expect(opencodeMajorVersion).not.toHaveBeenCalled()
if (mode === 'ready') {
expect(result).toEqual({ ok: true })
expect(restartAgent).toHaveBeenCalledOnce()
} else {
expect(result).toMatchObject({ ok: false, error: 'NATIVE_LAUNCH_HELD' })
expect(restartAgent).not.toHaveBeenCalled()
}
const current = vi.mocked(applyOpencodeSessionModel).mock.calls[0]![1]!.current!
nativeCurrent = false
expect(current()).toBe(false)
nativeCurrent = true
vi.mocked(run.deps.registry.byAgent).mockReturnValue(undefined)
expect(current()).toBe(false)
})
it.each(['prepared', 'clearing', 'hold-open'] as const)('keeps the live process when native proof changes during %s', async phase => {
const actual = await vi.importActual<typeof import('../../lib/restartAgent.js')>('../../lib/restartAgent.js')
vi.mocked(restartAgent).mockImplementationOnce(actual.restartAgent)
let valid = true
const native = { current: () => valid } as NativeLaunch
const terminate = vi.fn(async () => 'gone' as const), respawn = vi.fn(async () => ({ ok: true }))
const run = setup(agent(), { launchOverridesDeps: { native: async () => ({ ok: true, launch: native }) } as never,
relaunchOverrides: async () => {
if (phase === 'prepared') valid = false
return { ok: true, overrides: { native, env: {}, extraArgs: [], clearEnv: [] } }
},
paneSwapDeps: () => ({ holdOpen: async () => { valid = false; return { ok: true } }, terminate, respawn,
waitForProcess: async () => null, buildArgv: () => ['fixture-engine'], log: () => {} }),
})
if (phase === 'clearing') vi.mocked(run.tmux.clearEnv).mockImplementationOnce(async (_pane, _vars, current) => {
valid = false
expect(current?.()).toBe(false)
return { state: 'succeeded', dispatch: 'executed' }
})
expect(await run.retarget({ agentId: 'a1', grid: null })).toMatchObject({ ok: false })
expect(terminate).not.toHaveBeenCalled()
expect(respawn).not.toHaveBeenCalled()
vi.mocked(restartAgent).mockReset().mockResolvedValue({ ok: true, resumed: true, processIdentity: { pid: 2, startMarker: 'new', executable: '/bin/claude' } })
})
it('keeps an admitted external conversation when its retarget resume fails', async () => {
const actual = await vi.importActual<typeof import('../../lib/restartAgent.js')>('../../lib/restartAgent.js')
vi.mocked(restartAgent).mockImplementationOnce(actual.restartAgent)
const respawn = vi.fn(async () => ({ ok: true }))
const keepAbandoned = vi.fn(), buildArgv = vi.fn(options => ['fixture-engine', options.resumeSessionId ?? 'fresh'])
const run = setup(agent({ resumeOnly: true }), { paneSwapDeps: () => ({
holdOpen: async () => ({ ok: true }), terminate: async () => 'gone', respawn,
waitForProcess: async () => null, buildArgv, keepAbandoned, log: () => {},
}) })
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'RESPAWN_FAILED' })
expect(respawn).toHaveBeenCalledExactlyOnceWith(['fixture-engine', 's1'])
expect(keepAbandoned).not.toHaveBeenCalled()
expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
})
describe('refusals before anything is touched', () => {
it('cannot follow a mutable row to a replacement conversation while validation waits', async () => {
const row = agent()
let finish!: () => void
vi.mocked(validateLaunchOverrides).mockImplementationOnce(() => new Promise(done => { finish = () => done({ ok: true } as never) }))
const run = setup(row)
const pending = run.retarget({ agentId: 'a1', grid })
await vi.waitFor(() => expect(finish).toBeTypeOf('function'))
row.sessionId = 'replacement'
row.processIdentity = { pid: 77, startMarker: 'replacement', executable: 'claude' }
finish()
expect(await pending).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
expect(run.deps.sessionTurnOpen).not.toHaveBeenCalled()
expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
expect(restartAgent).not.toHaveBeenCalled()
})
it.each(['validation', 'version', 'preparation', 'native-write', 'environment', 'bypass', 'permission', 'replacement', 'gateway', 'pane-option'] as const)(
'cannot publish or continue a retarget whose owner changes during %s', async phase => {
const row = agent({ engine: 'opencode', subscriptionModel: 'fixture/model' })
const run = setup(row, { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { sessionModel: 'fixture/model', env: {}, extraArgs: [], clearEnv: [] } })) })
const replace = () => { row.sessionId = 'replacement' }
switch (phase) {
case 'validation': vi.mocked(validateLaunchOverrides).mockImplementationOnce(async () => { replace(); return { ok: true } }); break
case 'version': vi.mocked(opencodeMajorVersion).mockImplementationOnce(async () => { replace(); return 2 }); break
case 'preparation': vi.mocked(run.deps.relaunchOverrides).mockImplementationOnce(async () => { replace(); return { ok: true, overrides: { env: {}, extraArgs: [], clearEnv: [] } } }); break
case 'native-write': vi.mocked(applyOpencodeSessionModel).mockImplementationOnce(async () => { replace(); return { ok: true } }); break
case 'environment': vi.mocked(run.tmux.clearEnv).mockImplementationOnce(async () => { replace(); return { state: 'succeeded', dispatch: 'executed' } }); break
case 'bypass': vi.mocked(bypassPermissionFor).mockImplementationOnce(async () => { replace(); return true }); break
case 'permission': vi.mocked(run.deps.downgradedPermission).mockImplementationOnce(async () => { replace(); return {} }); break
case 'replacement': vi.mocked(restartAgent).mockImplementationOnce(async () => { replace(); return { ok: true, resumed: true, processIdentity: { pid: 2, executable: 'opencode', startMarker: 'new' } } }); break
case 'gateway': vi.mocked(probeGatewayRuntime).mockImplementationOnce(async () => { replace(); return { kind: 'none' } as never }); break
case 'pane-option': vi.mocked(run.tmux.releaseHold).mockImplementationOnce(async () => { replace() }); break
}
const result = await createAgentRetargeter(run.deps)({ agentId: 'a1', grid: phase === 'environment' ? null : grid })
expect(result).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
expect(run.deps.registry.setGridLaunch).not.toHaveBeenCalled()
expect(run.deps.announceSession).not.toHaveBeenCalled()
})
it('honors Stop cancellation while service preparation waits, even if the row is unchanged', async () => {
const restartJobs = new AgentRestartCoordinator()
const run = setup(agent(), { restartJobs })
vi.mocked(run.deps.relaunchOverrides).mockImplementationOnce(async () => {
restartJobs.cancel('a1')
return { ok: true, overrides: { env: {}, extraArgs: [], clearEnv: [] } }
})
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
expect(restartAgent).not.toHaveBeenCalled()
expect(run.release).toHaveBeenCalledOnce()
})
it('releases terminal control if preparation throws', async () => {
const run = setup(agent(), { relaunchOverrides: vi.fn(async () => { throw Error('preparation failed') }) })
await expect(run.retarget({ agentId: 'a1', grid })).rejects.toThrow('preparation failed')
expect(run.release).toHaveBeenCalledOnce()
expect(run.releaseRoute).not.toHaveBeenCalled()
})
it('invalidates an older restore as soon as retarget takes control', async () => {
const { deps, retarget, release } = setup()
await retarget({ agentId: 'a1', grid })
expect(deps.restartJobs.cancel).toHaveBeenCalledExactlyOnceWith('a1')
expect(vi.mocked(deps.restartJobs.cancel).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(deps.relaunchOverrides).mock.invocationCallOrder[0])
expect(release).toHaveBeenCalledOnce()
})
it('rechecks a pane operation that began while the move was being checked', async () => {
const purgeBusy = vi.fn().mockReturnValueOnce(false).mockReturnValue(true)
const { retarget, deps } = setup(agent(), { purgeBusy })
expect(await retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY' })
expect(deps.acquireTerminalControl).not.toHaveBeenCalled()
expect(deps.relaunchOverrides).not.toHaveBeenCalled()
})
it('for an agent being purged, no tmux, no agent, no tmux pane or no process to validate', async () => {
expect(await setup(agent(), { purgeBusy: () => true }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY' })
expect(await setup(agent(), { terminals: { backendFor: () => undefined, instances: () => [] } }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'TMUX_UNAVAILABLE' })
// A backend with no restart primitives is none to retarget on, whatever its name.
expect(await setup(agent(), { terminals: { backendFor: () => undefined, instances: () => [{ name: 'tmux' } as never] } }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'TMUX_UNAVAILABLE' })
// A pty host machine's own code (Windows).
expect(await setup(agent(), { noBackendCode: 'PTY_HOST_UNAVAILABLE', terminals: { backendFor: () => undefined, instances: () => [] } }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'PTY_HOST_UNAVAILABLE' })
expect(await setup(null).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_NOT_FOUND' })
// A guest's harness: re-exec'd here it would run as the owner, on the owner's keys.
expect(await setup(agent({ guest: '[email protected]' })).retarget({ agentId: 'a1', grid })).toEqual(GUEST_HARNESS_REFUSAL)
expect(await setup(agent({ runtimes: [] } as Partial<RegisteredSession>)).retarget({ agentId: 'a1', grid })).toMatchObject({ error: 'RETARGET_UNSUPPORTED_BACKEND' })
expect(await setup(agent({ processIdentity: undefined } as Partial<RegisteredSession>)).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'NO_ACTIVE_PROCESS' })
})
it('for a launch this machine cannot do, an OpenCode store it cannot rewrite, or a folder that is gone', async () => {
vi.mocked(validateLaunchOverrides).mockResolvedValueOnce({ ok: false, error: 'GRID_ENGINE_UNSUPPORTED', detail: 'no' } as never)
expect(await setup().retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'GRID_ENGINE_UNSUPPORTED', detail: 'no' })
vi.mocked(binaryOnPath).mockReturnValueOnce(false)
expect(await setup(agent({ engine: 'opencode' } as Partial<RegisteredSession>)).retarget({ agentId: 'a1', grid })).toMatchObject({ error: 'OPENCODE_SQLITE_MISSING' })
// Windows has no sqlite3 CLI, but node:sqlite rewrites the store just as well.
vi.mocked(binaryOnPath).mockReturnValueOnce(false)
vi.mocked(builtinSqlite).mockReturnValueOnce((class {}) as never)
expect(await setup(agent({ engine: 'opencode' } as Partial<RegisteredSession>)).retarget({ agentId: 'a1', grid })).not.toMatchObject({ error: 'OPENCODE_SQLITE_MISSING' })
vi.mocked(workspaceMissing).mockReturnValueOnce({ ok: false, error: 'CWD_NOT_FOUND', detail: 'gone' } as never)
expect(await setup().retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'CWD_NOT_FOUND', detail: 'gone' })
})
it('for a turn in progress, said so, without reading the screen', async () => {
const turn = setup(agent(), { sessionTurnOpen: vi.fn(() => true) })
expect(await turn.retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY',
detail: 'This harness is in a turn. Stop it, then switch the model.' })
expect(turn.deps.sessionTurnOpen).toHaveBeenCalledWith('s1')
expect(turn.deps.acquireTerminalControl).not.toHaveBeenCalled()
expect(restartAgent).not.toHaveBeenCalled()
})
it('for an OpenCode 2 turn, read from its own store since the turn state does not see it', async () => {
const oc2 = agent({ engine: 'opencode' } as Partial<RegisteredSession>)
vi.mocked(isOpencodeV2).mockReturnValue(true)
try {
vi.mocked(opencodeV2TurnOpen).mockResolvedValueOnce(true)
const busy = setup(oc2)
expect(await busy.retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY',
detail: 'This harness is in a turn. Stop it, then switch the model.' })
expect(opencodeV2TurnOpen).toHaveBeenCalledWith('/db/opencode.db', 's1')
expect(busy.deps.acquireTerminalControl).not.toHaveBeenCalled()
// A native OpenCode's store is the one its own HOME holds.
const launch = { current: () => true, executable: '/fixture/native/opencode', environment: { HOME: '/fixture/home' }, opencodeMajor: 2 } as unknown as NativeLaunch
vi.mocked(opencodeV2TurnOpen).mockResolvedValueOnce(true)
expect(await setup(oc2, { launchOverridesDeps: { native: async () => ({ ok: true, launch }) } as never }).retarget({ agentId: 'a1', grid }))
.toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(opencodeV2TurnOpen).toHaveBeenLastCalledWith('/fixture/home/.local/share/opencode/opencode.db', 's1')
// Between turns, or a store it cannot read: no turn known, so it moves.
vi.mocked(opencodeV2TurnOpen).mockResolvedValueOnce(false).mockResolvedValueOnce(null)
expect(await setup(oc2).retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(await setup(oc2).retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
// A harness replaced while the store is read is not moved.
const row = agent({ engine: 'opencode' } as Partial<RegisteredSession>)
vi.mocked(opencodeV2TurnOpen).mockImplementationOnce(async () => { row.sessionId = 'replacement'; return false })
expect(await setup(row).retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
} finally { vi.mocked(isOpencodeV2).mockReturnValue(false) }
// OpenCode 1 is read by the turn state itself.
vi.mocked(opencodeV2TurnOpen).mockClear()
await setup(oc2).retarget({ agentId: 'a1', grid })
expect(opencodeV2TurnOpen).not.toHaveBeenCalled()
})
it('moves an agent between turns whatever its prompt shows, and one with no conversation to ask about', async () => {
// OpenCode 2's placeholder once read as a draft and refused every switch until the first chat.
const idle = setup(agent({ engine: 'opencode' } as Partial<RegisteredSession>))
expect(await idle.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(idle.deps.sessionTurnOpen).toHaveBeenCalledWith('s1')
const fresh = setup(agent({ sessionId: undefined } as Partial<RegisteredSession>), { sessionTurnOpen: vi.fn(() => true) })
expect(await fresh.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(fresh.deps.sessionTurnOpen).not.toHaveBeenCalled()
})
it('for a swap already running, or control it cannot take', async () => {
expect(await setup(agent(), { restartJobs: { busy: () => true, revision: () => 0 } as never }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY' })
expect(await setup(agent(), { acquireTerminalControl: () => null }).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'AGENT_BUSY' })
})
it('for overrides it cannot build, giving control back', async () => {
const run = setup(agent(), { relaunchOverrides: vi.fn(async () => ({ ok: false, error: 'API_UNAVAILABLE', detail: 'removed' })) as never })
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'API_UNAVAILABLE', detail: 'removed' })
expect(run.release).toHaveBeenCalled()
expect(run.deps.agentReconciler.holdRoute).not.toHaveBeenCalled()
})
})
// Security review 1 of #2255: a model switch relaunched an old Buddy with no saved role without asking the Swarm, so it
// came back without its guard.
describe('an old Swarm session with no saved role', () => {
const switchWith = (grant: SwarmSkillGrant | null | undefined) => {
const row = agent({ startedBy: 'agent' })
const adoptSwarmSkill = createSwarmSkillAdoption({ role: async () => grant, candidate: () => false,
authority: createLaunchAuthority({ byAgent: () => row, revision: () => 0, cancelled: () => false }),
save: (_id, skill) => { row.swarmSkill = skill; return true } })
return { row, ...setup(row, { adoptSwarmSkill }) }
}
it('switches its model with its Buddy role, saved on its row', async () => {
const run = switchWith({ role: 'buddy' })
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: true })
expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.objectContaining({ swarmSkill: { role: 'buddy', key: 'a1' } }),
expect.anything(), expect.any(Function), undefined)
expect(run.row.swarmSkill).toEqual({ role: 'buddy', key: 'a1' })
expect(restartAgent).toHaveBeenCalledOnce()
})
it('does not switch a session that changed while its role was read', async () => {
const row = agent({ startedBy: 'agent' })
const adoptSwarmSkill = createSwarmSkillAdoption({ candidate: () => false, save: vi.fn(),
role: async () => { row.cwd = '/replacement'; return { role: 'buddy' as const } },
authority: createLaunchAuthority({ byAgent: () => row, revision: () => 0, cancelled: () => false }) })
const run = setup(row, { adoptSwarmSkill })
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
expect(restartAgent).not.toHaveBeenCalled()
})
it('switches the person\'s own session as before, with no role and no Swarm read', async () => {
const role = vi.fn(async () => ({ role: 'buddy' as const }))
const row = agent()
const run = setup(row, { adoptSwarmSkill: createSwarmSkillAdoption({ role, candidate: () => false, save: vi.fn(),
authority: createLaunchAuthority({ byAgent: () => row, revision: () => 0, cancelled: () => false }) }) })
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: true })
expect(role).not.toHaveBeenCalled()
expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.not.objectContaining({ swarmSkill: expect.anything() }),
expect.anything(), expect.any(Function), undefined)
})
it('refuses the switch, saying why, and leaves the running engine alone while its role cannot be read', async () => {
const run = switchWith(undefined)
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'SWARM_ROLE_UNAVAILABLE',
detail: 'This agent\'s Swarm role could not be confirmed, so its model was not switched. Try again once the Swarm can be reached.' })
expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
expect(run.deps.acquireTerminalControl).not.toHaveBeenCalled()
expect(restartAgent).not.toHaveBeenCalled()
})
})
describe('a move that goes ahead', () => {
// Codex 0.166 refuses to resume a conversation on another provider (thread/resume → ModelProviderMismatch);
// a move between a grid and its own login changes provider, so the conversation goes on in a fork of it.
it.each([
['its own login onto a grid', agent({ engine: 'codex' }), grid, true],
['a grid back to its own login', agent({ engine: 'codex', gridLaunch: grid }), null, true],
['one grid to another (the same provider)', agent({ engine: 'codex', gridLaunch: grid }), { ...grid, networkId: 'g2' }, false],
] as const)('continues a Codex conversation moved from %s in a fork only when its provider changes', async (_how, row, to, forks) => {
const run = setup(row)
expect(await run.retarget({ agentId: 'a1', grid: to })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'codex', sessionId: 's1', ...(forks ? { continueInFork: true } : {}) })
})
it('prepares the fork onto a grid with the launch\'s own arguments, environment and executable', async () => {
const launch = { current: () => true, executable: { command: '/native/codex' }, environment: { NATIVE: '1' } } as unknown as NativeLaunch
const run = setup(agent({ engine: 'codex' }), {
relaunchOverrides: async () => ({ ok: true, overrides: { native: launch, env: { GRID_KEY: 'k' }, extraArgs: ['-m', 'big'], clearEnv: [] } }),
})
await run.retarget({ agentId: 'a1', grid })
expect(await vi.mocked(restartAgent).mock.calls[0][2].prepareFork!()).toBe('prepared')
const move = vi.mocked(moveCodexConversation).mock.calls[0][0]
expect(move).toMatchObject({ sessionId: 's1', toGrid: true, args: ['-m', 'big'], cwd: '/work', env: { GRID_KEY: 'k', NATIVE: '1' } })
expect(move.argv(['app-server'])).toEqual(process.platform === 'win32' ? expect.anything() : ['/native/codex', 'app-server'])
})
it('prepares the fork home on the engine on the path, with the grid\'s variables gone', async () => {
vi.stubEnv('ANTHROPIC_BASE_URL', 'http://grid.local')
const run = setup(agent({ engine: 'codex', gridLaunch: grid, cwd: null }), {
relaunchOverrides: (async () => ({ ok: true, overrides: { env: {}, clearEnv: [] } })) as never,
})
await run.retarget({ agentId: 'a1', grid: null })
await vi.mocked(restartAgent).mock.calls[0][2].prepareFork!()
const move = vi.mocked(moveCodexConversation).mock.calls[0][0]
vi.unstubAllEnvs()
expect(move).toMatchObject({ toGrid: false, args: [] })
expect(move).not.toHaveProperty('cwd')
expect(move.env.ANTHROPIC_BASE_URL).toBeUndefined()
expect(move.argv(['app-server']).at(-1)).toBe('app-server')
})
it('resumes an engine whose conversations follow any provider (Claude Code) on every move', async () => {
const run = setup(agent())
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'claude', sessionId: 's1' })
})
it('starts fresh rather than forking a Codex agent with no conversation yet', async () => {
const run = setup(agent({ engine: 'codex', sessionId: '' }))
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'codex', sessionId: '' })
})
it('keeps its route until a slow replacement is confirmed, even past the default hold timer', async () => {
vi.useFakeTimers()
const onDiscovered = vi.fn()
const reconciler = new TerminalAgentReconciler({ current: () => [], backends: [], backendOrder: ['tmux'],
onDiscovered, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
probe: async () => ({ processTableAvailable: true, ambiguousPlacements: new Set(),
targets: [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: pane, rootPid: 1, cwd: '/work' }] } }],
agents: [{ engine: 'claude', cwd: '/work', processIdentity: { pid: 4, executable: 'claude', startMarker: 'replacement' },
args: 'claude', resumeSessionId: null, runtimes: [pane], primaryRuntimeKey: terminalRouteKey(pane) }],
}),
})
let finish!: () => void
vi.mocked(restartAgent).mockImplementationOnce(() => new Promise(done => { finish = () => done({ ok: false, detail: 'fixture complete' }) }))
const run = setup(agent(), { agentReconciler: reconciler })
const pending = run.retarget({ agentId: 'a1', grid })
try {
await vi.waitFor(() => expect(finish).toBeTypeOf('function'))
await vi.advanceTimersByTimeAsync(30_001)
await reconciler.trigger()
expect(onDiscovered).not.toHaveBeenCalled()
finish()
await pending
await reconciler.trigger()
expect(onDiscovered).toHaveBeenCalledOnce()
} finally { finish?.(); await pending; vi.useRealTimers() }
})
it('cannot release a newer Stop route hold when an older retarget completes', async () => {
const onDiscovered = vi.fn()
const reconciler = new TerminalAgentReconciler({ current: () => [], backends: [], backendOrder: ['tmux'],
onDiscovered, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
probe: async () => ({ processTableAvailable: true, ambiguousPlacements: new Set(),
targets: [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: pane, rootPid: 1, cwd: '/work' }] } }],
agents: [{ engine: 'claude', cwd: '/work', processIdentity: { pid: 4, executable: 'claude', startMarker: 'replacement' },
args: 'claude', resumeSessionId: null, runtimes: [pane], primaryRuntimeKey: terminalRouteKey(pane) }],
}),
})
const restartJobs = new AgentRestartCoordinator()
const run = setup(agent(), { agentReconciler: reconciler, restartJobs })
let releaseStop!: () => void
vi.mocked(restartAgent).mockImplementationOnce(async () => {
restartJobs.cancel('a1')
releaseStop = reconciler.holdRoute(terminalRouteKey(pane))
return { ok: false, detail: 'cancelled' }
})
try {
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
await reconciler.trigger()
expect(onDiscovered).not.toHaveBeenCalled()
releaseStop()
await reconciler.trigger()
expect(onDiscovered).toHaveBeenCalledOnce()
} finally { releaseStop?.() }
})
it.each(['environment', 'permission', 'cancelled'] as const)('discloses an applied model change when later %s preparation fails', async phase => {
const row = agent({ engine: 'opencode', subscriptionModel: 'fixture/model' })
const run = setup(row, { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { env: {}, extraArgs: [], clearEnv: [], sessionModel: 'fixture/model' } })) })
if (phase === 'environment') vi.mocked(run.tmux.clearEnv).mockResolvedValueOnce({ state: 'failed', dispatch: 'rejected', reason: 'fixture failure' })
if (phase === 'permission') vi.mocked(run.deps.downgradedPermission).mockRejectedValueOnce(Error('fixture failure'))
if (phase === 'cancelled') vi.mocked(applyOpencodeSessionModel).mockImplementationOnce(async () => {
row.sessionId = 'replacement'
return { ok: true }
})
await expect(run.retarget({ agentId: 'a1', grid: null })).resolves.toMatchObject({ ok: false,
detail: expect.stringContaining('native model change was applied') })
expect(restartAgent).not.toHaveBeenCalled()
expect(run.release).toHaveBeenCalledOnce()
})
it('retains uncertainty when Stop revokes a write whose reply was lost', async () => {
const row = agent({ engine: 'opencode' })
const run = setup(row, { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { env: {}, extraArgs: [], clearEnv: [], sessionModel: 'fixture/model' } })) })
vi.mocked(applyOpencodeSessionModel).mockImplementationOnce(async () => {
row.sessionId = 'replacement'
return { ok: false, code: 'AGENT_CHANGED', effect: 'uncertain', detail: 'reply lost' }
})
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED',
detail: expect.stringContaining('may already have applied') })
expect(restartAgent).not.toHaveBeenCalled()
})
it('reports a replacement that started before a later non-Error exception', async () => {
const run = setup()
vi.mocked(probeGatewayRuntime).mockRejectedValueOnce('fixture probe unavailable')
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'RETARGET_FAILED',
detail: 'The replacement process started, but retarget did not complete. fixture probe unavailable' })
expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
})
it('does not announce a row removed by a publication observer', async () => {
const run = setup()
vi.mocked(run.deps.registry.setActive).mockImplementationOnce(() => { vi.mocked(run.deps.registry.byAgent).mockReturnValue(undefined); return true })
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(run.deps.announceSession).not.toHaveBeenCalled()
})
it('onto a grid: the pane respawned, the new process adopted, the launch and the model it left kept', async () => {
const log = vi.mocked(console.log)
const run = setup()
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalled()
expect(restartAgent).toHaveBeenCalledWith({ engine: 'claude', sessionId: 's1' }, true, { isCurrent: expect.any(Function) })
// The grid is read off the new process's command line, never its executable alone.
expect(run.deps.registry.updateProcessIdentity).toHaveBeenCalledWith('a1', expect.objectContaining({ pid: 2 }), 'none')
expect(run.deps.registry.setGridLaunch).toHaveBeenCalledWith('a1', { override: grid, webSearch: 'off' })
expect(run.deps.registry.setSubscriptionModel).toHaveBeenCalledWith('a1', 'opus')
expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', true)
expect(run.deps.refreshGridAssignment).toHaveBeenCalledWith(agent())
expect(run.tmux.releaseHold).toHaveBeenCalledWith(pane, expect.any(Function))
expect(run.deps.announceSession).toHaveBeenCalled()
expect(run.release).toHaveBeenCalled()
expect(run.releaseRoute).toHaveBeenCalled()
expect(log.mock.calls.map(([line]) => String(line))).toContain('claude on Home · retargeted a1 · resumed')
})
it('remembers only the model of the agent\'s own login, never a grid\'s, never the one it moves to', async () => {
const validated = () => vi.mocked(validateLaunchOverrides).mock.lastCall?.[2]
// Grid to grid: the memory stays as it was.
const fromGrid = setup(agent({ grid: { baseUrl: 'x' }, subscriptionModel: 'sonnet' } as Partial<RegisteredSession>))
await fromGrid.retarget({ agentId: 'a1', grid })
expect(fromGrid.deps.registry.setSubscriptionModel).toHaveBeenCalledWith('a1', 'sonnet')
// The engine still reports the grid's model: that is not the one to remember.
vi.mocked(parseRuntimeProfile).mockReturnValueOnce({ engine: 'claude', model: 'big' } as never)
const reporting = setup(agent())
await reporting.retarget({ agentId: 'a1', grid })
expect(reporting.deps.registry.setSubscriptionModel).not.toHaveBeenCalled()
// Another engine's model, or none observed: nothing to remember.
vi.mocked(parseRuntimeProfile).mockReturnValueOnce({ engine: 'opencode', model: 'big-pickle' } as never).mockReturnValueOnce(null as never)
await setup().retarget({ agentId: 'a1', grid })
await setup().retarget({ agentId: 'a1', grid })
expect(validated()).toEqual({ gridLaunch: grid, codexHome: undefined })
})
it('back home: the grid\'s variables cleared from the pane, on the remembered model, said plainly', async () => {
const log = vi.mocked(console.log)
const run = setup(agent({ grid: { baseUrl: 'x' }, subscriptionModel: 'opus' } as Partial<RegisteredSession>), {
relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never,
})
vi.mocked(restartAgent).mockResolvedValueOnce({ ok: true, resumed: false, processIdentity: { pid: 2, startMarker: 'n' } } as never)
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(vi.mocked(validateLaunchOverrides).mock.lastCall?.[2]).toEqual({ gridLaunch: null, codexHome: undefined, subscriptionModel: 'opus' })
expect(run.tmux.clearEnv).toHaveBeenCalledWith(pane, ['ANTHROPIC_BASE_URL'], expect.any(Function))
expect(run.deps.registry.setGridLaunch).toHaveBeenCalledWith('a1', null)
expect(run.deps.registry.setSubscriptionModel).not.toHaveBeenCalled()
expect(log.mock.calls.map(([line]) => String(line))).toContain('claude on its own login · retargeted a1 · fresh session')
const none = setup(agent(), { relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never })
await none.retarget({ agentId: 'a1', grid: null })
expect(vi.mocked(validateLaunchOverrides).mock.lastCall?.[2]).toMatchObject({ subscriptionModel: null })
})
// Task #3449: the move home is built from its own source, so it dropped the launch model, and a PM came back from a grid
// without its xhigh (lib/launchOverrides.ts ranks the launch model above the remembered one).
it('back home: the launch model rides with the remembered model; a move onto a grid carries none', async () => {
const launchModel = { model: 'opus', effort: 'xhigh' }
const home = setup(agent({ grid: { baseUrl: 'x' }, subscriptionModel: 'opus', launchModel } as Partial<RegisteredSession>), {
relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never,
})
expect(await home.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(vi.mocked(validateLaunchOverrides).mock.lastCall?.[2]).toEqual({ gridLaunch: null, codexHome: undefined, subscriptionModel: 'opus', launchModel })
expect(home.deps.relaunchOverrides).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ launchModel }), expect.any(Function), undefined)
const away = setup(agent({ launchModel } as Partial<RegisteredSession>))
await away.retarget({ agentId: 'a1', grid })
expect(away.deps.relaunchOverrides).toHaveBeenCalledWith(expect.anything(), expect.not.objectContaining({ launchModel: expect.anything() }),
expect.any(Function), undefined)
})
it('on a ptyhost pane: swapped through that pane\'s own backend, the grid\'s names cleared by the respawn on the way home', async () => {
const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%3' }
const ptyBackend = { name: 'ptyhost', holdOpen: vi.fn(), respawn: vi.fn(), releaseHold: vi.fn(async () => {}) }
const row = agent({ runtimes: [pty], grid: { baseUrl: 'x' }, subscriptionModel: 'opus' } as Partial<RegisteredSession>)
const run = setup(row, {
terminals: { backendFor: vi.fn(() => ptyBackend as never), instances: () => [ptyBackend as never] },
relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never,
})
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(run.deps.terminals.backendFor).toHaveBeenCalledWith(pty)
// No session env to clear first: the grid's names go with the respawn, out of the pane's create-time env.
expect(run.deps.paneSwapDeps).toHaveBeenCalledWith(row, { backend: ptyBackend, runtime: pty }, { clearPaneEnv: ['ANTHROPIC_BASE_URL'] }, null, expect.any(Function))
expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalledWith(terminalRouteKey(pty), null)
expect(ptyBackend.releaseHold).toHaveBeenCalledWith(pty, expect.any(Function))
expect(run.tmux.clearEnv).not.toHaveBeenCalled()
expect(run.tmux.releaseHold).not.toHaveBeenCalled()
})
it('fails cleanly when the pane will not be cleared, or the respawn does not come up', async () => {
const home = { relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never }
const run = setup(agent(), home)
vi.mocked(run.tmux.clearEnv).mockResolvedValueOnce({ state: 'failed', reason: 'no session' } as never).mockResolvedValueOnce({ state: 'unknown' } as never)
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: false, error: 'GRID_CLEAR_FAILED', detail: 'no session' })
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: false, error: 'GRID_CLEAR_FAILED', detail: 'tmux would not clear the pane environment' })
vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, detail: 'no process' } as never)
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'RESPAWN_FAILED', detail: 'no process' })
expect(run.release).toHaveBeenCalledTimes(3)
expect(run.releaseRoute).toHaveBeenCalledTimes(3)
})
it('rewrites a resumed OpenCode session\'s model before the respawn, and refuses if it cannot', async () => {
const opencode = agent({ engine: 'opencode' } as Partial<RegisteredSession>)
const withModel = { relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: { sessionModel: 'grid/big', gridLaunchRecord: null } })) as never }
const run = setup(opencode, withModel)
await run.retarget({ agentId: 'a1', grid })
expect(applyOpencodeSessionModel).toHaveBeenCalledWith({ opencodeMajor: 1, dbPath: '/db/opencode.db', sessionId: 's1', model: { providerID: 'grid', modelID: 'big' }, cwd: '/work', checkCatalog: false }, { current: expect.any(Function) })
vi.mocked(applyOpencodeSessionModel).mockResolvedValueOnce({ ok: false, code: 'SESSION_NOT_FOUND', detail: 'no rows' } as never)
expect(await setup(agent({ engine: 'opencode', cwd: undefined } as Partial<RegisteredSession>), withModel).retarget({ agentId: 'a1', grid })).toEqual({ ok: false, error: 'SESSION_NOT_FOUND', detail: 'no rows' })
// v2 needs no sqlite3; a model the overrides do not name, or one that does not parse, writes nothing.
vi.mocked(isOpencodeV2).mockReturnValueOnce(true)
vi.mocked(binaryOnPath).mockReturnValue(false)
expect(await setup(opencode, { relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never }).retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
vi.mocked(binaryOnPath).mockReturnValue(true)
vi.mocked(parseOpencodeModelId).mockReturnValueOnce(null as never)
await setup(opencode, withModel).retarget({ agentId: 'a1', grid })
expect(applyOpencodeSessionModel).toHaveBeenCalledTimes(2)
// Home to a remembered model with its provider: checked against OpenCode's catalogue.
await setup(agent({ engine: 'opencode', subscriptionModel: 'anthropic/claude' } as Partial<RegisteredSession>), withModel).retarget({ agentId: 'a1', grid: null })
expect(vi.mocked(applyOpencodeSessionModel).mock.lastCall?.[0]).toMatchObject({ checkCatalog: true })
// A remembered model without a provider, or an OpenCode agent with no session: no rewrite at all.
vi.mocked(binaryOnPath).mockReturnValue(false)
expect(await setup(agent({ engine: 'opencode', subscriptionModel: 'claude' } as Partial<RegisteredSession>), withModel).retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(await setup(agent({ engine: 'opencode', sessionId: '' } as Partial<RegisteredSession>), withModel).retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
vi.mocked(binaryOnPath).mockReturnValue(true)
})
it.each(['missing', 'stalled'])('moves OpenCode while its optional reader is %s', async mode => {
const { loadEngine } = await import('../../engines/inProcess.js')
vi.mocked(loadEngine).mockImplementation(() => mode === 'stalled' ? new Promise(() => {}) : Promise.resolve(null))
const run = setup(agent({ engine: 'opencode' } as Partial<RegisteredSession>), {
relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: { sessionModel: 'grid/big', gridLaunchRecord: null } })) as never,
})
let timer: ReturnType<typeof setTimeout> | undefined
try {
const result = await Promise.race([run.retarget({ agentId: 'a1', grid }),
new Promise(resolve => { timer = setTimeout(() => resolve('blocked on optional code'), 1000) })])
expect(result).toEqual({ ok: true })
expect(restartAgent).toHaveBeenCalledOnce()
expect(applyOpencodeSessionModel).toHaveBeenCalledOnce()
expect(loadEngine).not.toHaveBeenCalled()
} finally { clearTimeout(timer) }
})
it('does not act on a row removed before retarget can establish ownership', async () => {
const run = setup()
vi.mocked(run.deps.registry.byAgent).mockReturnValue(undefined)
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
expect(bypassPermissionFor).not.toHaveBeenCalled()
expect(run.deps.liveBypassPermission).not.toHaveBeenCalled()
expect(run.deps.announceSession).not.toHaveBeenCalled()
})
it('reports a confirmed native model change if the subsequent respawn fails', async () => {
const run = setup(agent({ engine: 'opencode' }), { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { env: {}, extraArgs: [], clearEnv: [], sessionModel: 'fixture/model' } })) })
vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, detail: 'spawn failed' })
expect(await run.retarget({ agentId: 'a1', grid })).toMatchObject({ ok: false, error: 'RESPAWN_FAILED',
detail: expect.stringContaining('native model change was applied') })
expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
})
})
// A fresh move starts a new conversation on the grid (a long one would not fit its window) and keeps the one it
// left; the way home reopens that one, not the grid's (design: "Two generic additions to agent_retarget").
describe('a fresh session, and the way home to the one it left', () => {
const onGrid = (over: Partial<RegisteredSession> = {}) =>
agent({ grid: { baseUrl: 'x' }, gridLaunch: grid, sessionId: 'S2', subscriptionSessionId: 'S1', ...over } as Partial<RegisteredSession>)
const home = { relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: {} })) as never }
const order = (fn: unknown) => vi.mocked(fn as () => void).mock.invocationCallOrder[0]
it('a fresh move onto a grid relaunches without --resume and keeps the session it left', async () => {
const run = setup(agent({ sessionId: 'S1' }))
expect(await run.retarget({ agentId: 'a1', grid, fresh: true })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'claude', sessionId: '' })
expect(run.deps.registry.setSubscriptionSession).toHaveBeenCalledExactlyOnceWith('a1', 'S1')
// Kept only once the move worked.
expect(order(run.deps.registry.setSubscriptionSession)).toBeGreaterThan(order(restartAgent))
})
it('a fresh Codex move starts a new conversation rather than forking the one it leaves', async () => {
const run = setup(agent({ engine: 'codex', sessionId: 'S1' }))
expect(await run.retarget({ agentId: 'a1', grid, fresh: true })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'codex', sessionId: '' })
expect(run.deps.registry.setSubscriptionSession).toHaveBeenCalledWith('a1', 'S1')
})
it('a fresh OpenCode move leaves the model of the session it left as it was', async () => {
const run = setup(agent({ engine: 'opencode', sessionId: 'S1' }), { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { env: {}, extraArgs: [], clearEnv: [], sessionModel: 'grid/big' } })) })
expect(await run.retarget({ agentId: 'a1', grid, fresh: true })).toEqual({ ok: true })
expect(applyOpencodeSessionModel).not.toHaveBeenCalled()
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'opencode', sessionId: '' })
})
it('the move home reopens the session a fresh move left, and forgets it once home', async () => {
const run = setup(onGrid(), home)
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'claude', sessionId: 'S1' })
// The swap prepares, guards and (on a fallback) keeps the conversation it reopens, not the grid's.
expect(vi.mocked(run.deps.paneSwapDeps).mock.calls[0][5]).toBe('S1')
expect(run.deps.registry.setSubscriptionSession).toHaveBeenCalledExactlyOnceWith('a1', null)
expect(order(run.deps.registry.setSubscriptionSession)).toBeGreaterThan(order(restartAgent))
})
it('the move home resumes a Codex conversation it left on the own login, without a fork', async () => {
const run = setup(onGrid({ engine: 'codex' }), home)
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'codex', sessionId: 'S1' })
})
it('the move home rewrites the model of the OpenCode session it reopens', async () => {
const run = setup(onGrid({ engine: 'opencode', subscriptionModel: 'anthropic/claude' }), { relaunchOverrides: vi.fn(async () => ({ ok: true as const,
overrides: { sessionModel: 'anthropic/claude', gridLaunchRecord: null } })) as never })
expect(await run.retarget({ agentId: 'a1', grid: null })).toEqual({ ok: true })
expect(vi.mocked(applyOpencodeSessionModel).mock.calls[0][0]).toMatchObject({ sessionId: 'S1' })
})
it('a grid-to-grid move keeps the remembered session, fresh or resumed', async () => {
const fresh = setup(onGrid())
expect(await fresh.retarget({ agentId: 'a1', grid: { ...grid, networkId: 'g2' }, fresh: true })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'claude', sessionId: '' })
expect(fresh.deps.registry.setSubscriptionSession).not.toHaveBeenCalled()
const resumed = setup(onGrid())
expect(await resumed.retarget({ agentId: 'a1', grid: { ...grid, networkId: 'g2' } })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[1][0]).toEqual({ engine: 'claude', sessionId: 'S2' })
expect(resumed.deps.registry.setSubscriptionSession).not.toHaveBeenCalled()
})
it('a move from the own login that keeps its conversation forgets an earlier remembered one', async () => {
const run = setup(agent({ sessionId: 'S3', subscriptionSessionId: 'S1' } as Partial<RegisteredSession>))
expect(await run.retarget({ agentId: 'a1', grid })).toEqual({ ok: true })
expect(vi.mocked(restartAgent).mock.calls[0][0]).toEqual({ engine: 'claude', sessionId: 'S3' })
expect(run.deps.registry.setSubscriptionSession).toHaveBeenCalledExactlyOnceWith('a1', null)
})
it('a refused or failed move leaves the remembered session unchanged', async () => {
// Refused: a turn is open.
const busyOut = setup(agent({ sessionId: 'S1' }), { sessionTurnOpen: vi.fn(() => true) })
expect(await busyOut.retarget({ agentId: 'a1', grid, fresh: true })).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
const busyHome = setup(onGrid(), { ...home, sessionTurnOpen: vi.fn(() => true) })
expect(await busyHome.retarget({ agentId: 'a1', grid: null })).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(restartAgent).not.toHaveBeenCalled()
// Failed: the replacement did not come up.
vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, detail: 'no process' } as never).mockResolvedValueOnce({ ok: false, detail: 'no process' } as never)
const failedOut = setup(agent({ sessionId: 'S1' }))
expect(await failedOut.retarget({ agentId: 'a1', grid, fresh: true })).toMatchObject({ ok: false, error: 'RESPAWN_FAILED' })
const failedHome = setup(onGrid(), home)
expect(await failedHome.retarget({ agentId: 'a1', grid: null })).toMatchObject({ ok: false, error: 'RESPAWN_FAILED' })
for (const run of [busyOut, busyHome, failedOut, failedHome]) expect(run.deps.registry.setSubscriptionSession).not.toHaveBeenCalled()
})
})
})