The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { GuestLaunch } from '../api.js'
import type { RegisteredSession } from '../../lib/registry.js'
import type { TmuxRuntimeRef } from '../../lib/terminalTypes.js'
import { createGuestCreate, type GuestCreateDeps } from './guestCreate.js'
import { WindowsBatchLaunchRefused } from '../../lib/windows/launch.js'
// A guest's New Harness: the launch shared machines builds, opened as a pane and recorded as the guest's
// (docs/plans/2026-10-19-guest-machine-sharing-plan.md). The pane is a fake tmux's; nothing runs.
const runtime = { backend: 'tmux', paneId: '%7' } satisfies TmuxRuntimeRef
const launched: GuestLaunch = { ok: true, workspace: '/Users/Shared/HarnessGuests/hg_0123456789ab/work', argv: ['/bin/sh', '-c', 'boot'], env: { TERM: 'xterm-256color' } }
function setup(over: Partial<GuestCreateDeps> & { answer?: GuestLaunch; spawn?: 'ok' | 'fail'; register?: boolean } = {}) {
const session = { agentId: 'agent-1', sessionId: '', engine: 'claude', guest: '[email protected]' } as RegisteredSession
const tmux = {
create: vi.fn(async () => over.spawn === 'fail' ? { state: 'failed' as const, reason: 'no server' } : { state: 'succeeded' as const, runtime }),
kill: vi.fn(async () => {}),
}
const deps: GuestCreateDeps = {
launch: vi.fn(async () => over.answer ?? launched),
tmuxBackend: () => tmux as never,
ensureEngine: vi.fn(async () => ({ ok: true as const })),
resolveEngine: vi.fn((_engine: string, argv: readonly string[]) => [...argv]),
registry: { openPendingAgent: vi.fn(() => over.register === false ? null : session) },
announceSession: vi.fn(),
watchNewPane: vi.fn(async () => {}) as never,
...over,
}
return { create: createGuestCreate(deps), deps, tmux, session }
}
describe('a guest\'s New Harness', () => {
afterEach(() => vi.restoreAllMocks())
const said = () => vi.spyOn(console, 'log').mockImplementation(() => {})
const warned = () => vi.spyOn(console, 'warn').mockImplementation(() => {})
it('opens the launch shared machines built, in the guest\'s workspace, and records it as the guest\'s', async () => {
const log = said()
const { create, deps, tmux, session } = setup()
expect(await create({ engine: 'claude', name: ' Notes ', cwd: '/Users/owner/secret' }, '[email protected]')).toEqual({ ok: true, session })
// The folder asked for goes to shared machines, which starts it there only when the owner shares it: here, not.
// Auto-approve, a harness's default: the engine's own auto mode, never Skip all checks.
expect(deps.launch).toHaveBeenCalledWith({ email: '[email protected]', engine: 'claude', bypassPermission: true,
permissionFlags: ['--permission-mode', 'auto'], cwd: '/Users/owner/secret' })
expect(tmux.create).toHaveBeenCalledWith(expect.objectContaining({ cwd: launched.ok && launched.workspace, command: ['/bin/sh', '-c', 'boot'], env: { TERM: 'xterm-256color' } }))
expect(deps.registry.openPendingAgent).toHaveBeenCalledWith(expect.objectContaining({ engine: 'claude', cwd: launched.ok && launched.workspace,
guest: '[email protected]', defaultName: 'Notes', bypassPermission: true, permissionMode: 'auto' }))
expect(deps.announceSession).toHaveBeenCalledWith(session)
// Watched as any pane, with no install: the pane installs a missing engine for the guest itself.
expect(deps.watchNewPane).toHaveBeenCalledWith('claude', session, expect.objectContaining({ runtime }), ['/bin/sh', '-c', 'boot'], undefined)
expect(log).toHaveBeenCalledWith('[agent] create guest pane open · claude · agent agent-1')
})
it('asks before each command when the guest says so, by mode or by the older flag', async () => {
said()
const { create, deps } = setup()
await create({ engine: 'codex', permissionMode: 'ask' }, '[email protected]')
await create({ engine: 'codex', permissionMode: 'full' }, '[email protected]')
await create({ engine: 'codex', bypassPermission: false, name: ' ' }, '[email protected]')
expect(vi.mocked(deps.launch).mock.calls.map(([input]) => [input.bypassPermission, input.permissionFlags])).toEqual([
[false, []], [true, ['--dangerously-bypass-approvals-and-sandbox']], [false, []]])
// A mode the engine does not have is refused, never approximated.
expect(await create({ engine: 'codex', permissionMode: 'plan' }, '[email protected]'))
.toEqual({ ok: false, error: 'INVALID_PERMISSION_MODE', detail: 'codex has no permission mode "plan"' })
expect(deps.registry.openPendingAgent).toHaveBeenLastCalledWith(expect.objectContaining({ defaultName: null }))
})
it('refuses what would run the owner\'s way, before anything starts, saying why', async () => {
const { create, deps } = setup()
for (const [key, value] of [['dsh', 'acme/blender'], ['resumeSessionId', 'abc-123'], ['agent', 'reviewer']] as const) {
expect(await create({ engine: 'claude', [key]: value }, '[email protected]'), key).toEqual({ ok: false, error: 'GUEST_UNSUPPORTED', detail: expect.any(String) })
}
expect(deps.launch).not.toHaveBeenCalled()
// Empty is absent.
said()
expect((await create({ engine: 'claude', dsh: null, agent: '' }, '[email protected]')).ok).toBe(true)
})
it('makes a launch that names the guest\'s own host there, never the owner\'s pane', async () => {
said()
// Windows: the guest's panes come from its own host, whose processes already run as that account.
const windows: GuestLaunch = { ok: true, workspace: 'C:\\Users\\hg_0123456789ab\\work', argv: ['claude'], env: {},
guestHostUser: 'hg_0123456789ab' }
const runtime = { backend: 'ptyhost', instance: 'p3', paneId: '%1' } as const
const host = { create: vi.fn(async () => ({ state: 'succeeded' as const, runtime })), kill: vi.fn(async () => {}) }
const guestBackend = vi.fn(() => host as never)
const run = setup({ answer: windows, guestBackend })
expect(await run.create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: true, session: run.session })
expect(guestBackend).toHaveBeenCalledWith('hg_0123456789ab')
expect(run.tmux.create).not.toHaveBeenCalled()
// The pane is made on the guest's host, starts in its workspace, and becomes the guest's shell when the engine goes.
expect(host.create).toHaveBeenCalledWith(expect.objectContaining({ cwd: windows.workspace, command: ['claude'], afterExit: expect.any(Object) }))
expect(run.deps.registry.openPendingAgent).toHaveBeenCalledWith(expect.objectContaining({ runtimes: [runtime], guest: '[email protected]' }))
// A host that is gone is said as such: the owner's pane is never a fallback (it would run as the owner).
const missing = setup({ answer: windows, guestBackend: () => null })
expect(await missing.create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'GUEST_HOST_UNAVAILABLE', detail: expect.any(String) })
expect(missing.tmux.create).not.toHaveBeenCalled()
})
it('installs the guest\'s engine before its pane, once even for two launches at once, and reports a failed install', async () => {
said()
const windows: GuestLaunch = { ok: true, workspace: 'C:\\Users\\hg_0123456789ab\\work', argv: ['claude'], env: {},
guestHostUser: 'hg_0123456789ab' }
const host = { create: vi.fn(async () => ({ state: 'succeeded' as const, runtime })), kill: vi.fn(async () => {}) }
let open: () => void = () => {}
const ensureEngine = vi.fn(async () => { await new Promise<void>((resolve) => { open = resolve }); return { ok: true as const } })
const run = setup({ answer: windows, guestBackend: vi.fn(() => host as never), ensureEngine })
const first = run.create({ engine: 'claude' }, '[email protected]')
const second = run.create({ engine: 'claude' }, '[email protected]')
await vi.waitFor(() => expect(ensureEngine).toHaveBeenCalledTimes(1))
open()
await Promise.all([first, second])
// One install for both: the second pane waits for the first rather than running npm beside it.
expect(ensureEngine).toHaveBeenCalledWith(host, { user: 'hg_0123456789ab', engine: 'claude', cwd: windows.workspace, prefix: 'C:\\ProgramData\\HarnessGuests\\hosts\\hg_0123456789ab\\engines' })
expect(host.create).toHaveBeenCalledTimes(2)
// A failed install is the person's answer: no pane, no registration, and npm's own words.
const refused = setup({ answer: windows, guestBackend: () => host as never,
ensureEngine: vi.fn(async () => ({ ok: false as const, error: 'GUEST_ENGINE_INSTALL_FAILED' as const, detail: 'npm said no' })) })
expect(await refused.create({ engine: 'claude' }, '[email protected]'))
.toEqual({ ok: false, error: 'GUEST_ENGINE_INSTALL_FAILED', detail: 'npm said no' })
expect(refused.deps.registry.openPendingAgent).not.toHaveBeenCalled()
expect(refused.tmux.create).not.toHaveBeenCalled()
// A launch Windows refuses (a batch engine whose arguments cmd.exe would read) is the person's answer.
const unsafe = setup({ answer: windows, guestBackend: () => host as never,
resolveEngine: () => { throw new WindowsBatchLaunchRefused('claude', 'C:\\tools\\claude.cmd') } })
expect(await unsafe.create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'ENGINE_LAUNCH_REFUSED',
detail: expect.stringContaining('claude.cmd is a batch file') })
expect(unsafe.deps.registry.openPendingAgent).not.toHaveBeenCalled()
})
it('starts on the guest\'s first message, bounded as the owner\'s are', async () => {
said()
const { create, deps } = setup()
await create({ engine: 'claude', prompt: ' Fix the tests ' }, '[email protected]')
await create({ engine: 'claude', prompt: ' ' }, '[email protected]')
await create({ engine: 'claude', prompt: null }, '[email protected]')
expect(vi.mocked(deps.launch).mock.calls.map(([input]) => input.prompt)).toEqual(['Fix the tests', undefined, undefined])
// A folder to start in goes to shared machines, which starts there only when the owner shares it: this side passes
// what it was given, because only shared machines knows this machine's own absolute form (`/…`, `C:\…`).
await create({ engine: 'claude', cwd: '/Users/dee/docs' }, '[email protected]')
await create({ engine: 'claude', cwd: 'docs' }, '[email protected]')
expect(vi.mocked(deps.launch).mock.calls.slice(3).map(([input]) => input.cwd)).toEqual(['/Users/dee/docs', 'docs'])
expect(await create({ engine: 'claude', prompt: 7 }, '[email protected]')).toEqual({ ok: false, error: 'INVALID_PROMPT', detail: 'prompt must be a string' })
expect(await create({ engine: 'claude', prompt: 'x'.repeat(2001) }, '[email protected]')).toEqual({ ok: false, error: 'PROMPT_TOO_LONG', detail: expect.stringMatching(/2000/) })
expect(deps.launch).toHaveBeenCalledTimes(5)
})
it('installs through the guest host when no one hands in an installer', async () => {
said()
const windows: GuestLaunch = { ok: true, workspace: 'C:\\Users\\hg_0123456789ab\\work', argv: ['claude'], env: {},
guestHostUser: 'hg_0123456789ab' }
let checked = false
const host = {
create: vi.fn(async (_request: { command?: string[]; label?: string }) => ({ state: 'succeeded' as const, dispatch: 'executed' as const, runtime: { backend: 'ptyhost', instance: 'p3-0.5.55-gu0123456789ab', paneId: '%1' } })),
kill: vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const })),
// Missing first, then the install succeeds.
paneState: vi.fn(async () => { const status = checked ? 0 : 1; checked = true; return { dead: true, exitStatus: status, command: 'cmd.exe', engineExit: null } }),
capture: vi.fn(async () => ({ state: 'succeeded' as const, value: 'installed' })),
}
const run = setup({ answer: windows, guestBackend: vi.fn(() => host as never), ensureEngine: undefined, resolveEngine: undefined })
expect(await run.create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: true, session: run.session })
// The check, the install, then the harness's own pane; npm ran from the staged Node, as the guest.
expect(host.create).toHaveBeenCalledTimes(3)
expect(host.create.mock.calls[0]![0]).toMatchObject({ command: ['cmd.exe', '/d', '/s', '/c', 'where claude'] })
expect(host.create.mock.calls[1]![0]).toMatchObject({ label: 'guest-engine-install-claude',
command: expect.arrayContaining([expect.stringContaining('\\bin\\node-'), expect.stringMatching(/engines$/)]) })
expect(run.deps.registry.openPendingAgent).toHaveBeenCalledTimes(1)
})
it('says what stopped it: no tmux, a launch refused, a pane that would not open or register', async () => {
expect(await setup({ tmuxBackend: () => null }).create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'TMUX_UNAVAILABLE' })
expect(await setup({ answer: { ok: false, error: 'GUEST_HELPER_REQUIRED', detail: 'Turn it on.' } }).create({ engine: 'claude' }, '[email protected]'))
.toEqual({ ok: false, error: 'GUEST_HELPER_REQUIRED', detail: 'Turn it on.' })
expect(await setup({ answer: { ok: false, error: 'GUEST_UNAVAILABLE' } }).create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'GUEST_UNAVAILABLE' })
// No engine named: no mode of its to start in.
expect(await setup().create({}, '[email protected]')).toMatchObject({ ok: false, error: 'INVALID_PERMISSION_MODE' })
warned()
expect(await setup({ spawn: 'fail' }).create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'SPAWN_FAILED', detail: 'no server' })
const unregistered = setup({ register: false })
expect(await unregistered.create({ engine: 'claude' }, '[email protected]')).toEqual({ ok: false, error: 'REGISTRATION_FAILED', detail: expect.any(String) })
expect(unregistered.deps.announceSession).not.toHaveBeenCalled()
})
})