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 { describe, expect, it } from 'vitest'
import { EventEmitter } from 'node:events'
import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { machineChoices, newAgentPayload, newCommand, NewUsageError, parseNewArgs, resolveNewMachine, trustAsked, type NewCommandDeps, type NewSocket } from './newCommand.js'
import { SANDBOXED } from './unreachable.js'
import { AgentClientError } from '../agentClient/daemon.js'
// POSIX paths, read by POSIX rules wherever the spec runs: on Windows the shell's paths are read as Windows ones.
const env = { cwd: '/work/repo', home: '/home/me', platform: 'linux' as const }
describe('harness new: the words', () => {
it('asks nothing: claude, here, on this machine', () => {
expect(parseNewArgs([], env)).toEqual({
agent: 'claude', machine: null, cwd: '/work/repo', projectName: null, mode: null, prompt: null, name: null, repo: null, acuLimit: null, model: null, json: false,
})
})
it('sends a model as the app\'s box does, for the machine to check, and none for a terminal', () => {
const args = parseNewArgs(['claude', '--model', 'haiku', 'snake', '--', 'build', 'it'], env)
expect(args).toMatchObject({ agent: 'claude', model: 'haiku', projectName: 'snake', prompt: 'build it' })
expect(newAgentPayload(args, null)).toMatchObject({ engine: 'claude', model: 'haiku', projectSource: 'new', projectName: 'snake' })
expect(newAgentPayload(parseNewArgs(['claude'], env), '/work/repo')).not.toHaveProperty('model')
expect(() => parseNewArgs(['claude', '--model'], env)).toThrow('--model needs a value.')
expect(() => parseNewArgs(['terminal', '--model', 'haiku'], env)).toThrow('A terminal runs no model')
})
it('reads agent, --machine and a folder in any order', () => {
const typed = parseNewArgs(['codex', '--machine', 'mini', '~/code/auth'], env)
expect(typed).toMatchObject({ agent: 'codex', machine: 'mini', cwd: '~/code/auth', projectName: null })
expect(parseNewArgs(['~/code/auth', '--machine', 'mini', 'codex'], env)).toEqual(typed)
expect(parseNewArgs(['codex', '--machine', 'Mac mini'], env)).toMatchObject({ machine: 'Mac mini' })
// On this machine ~ and relative paths are resolved here, from where it was run.
expect(parseNewArgs(['codex', '~/code/auth'], env).cwd).toBe('/home/me/code/auth')
expect(parseNewArgs(['codex', './api'], env).cwd).toBe('/work/repo/api')
expect(parseNewArgs(['.'], env)).toMatchObject({ agent: 'claude', cwd: '/work/repo' })
})
it('takes a second word, or --new, as a new project', () => {
expect(parseNewArgs(['codex', 'my-game'], env)).toMatchObject({ agent: 'codex', cwd: null, projectName: 'my-game' })
expect(parseNewArgs(['codex', '--new'], env)).toMatchObject({ cwd: null, projectName: '' })
expect(parseNewArgs(['--new', 'my game', 'codex'], env)).toMatchObject({ agent: 'codex', projectName: 'my game' })
// Another machine has no "here": with nothing named it is a new project there.
expect(parseNewArgs(['codex', '--machine', 'mini'], env)).toMatchObject({ machine: 'mini', cwd: null, projectName: '' })
})
it('refuses the old @machine, saying what to type, rather than making a project called "@office" here', () => {
// `harness new claude @office lamp-first-task` named office until 2026-10-14; read as a word now, it would be this
// machine and a project of that name.
expect(() => parseNewArgs(['claude', '@office', 'lamp-first-task'], env)).toThrow(new NewUsageError('Name the machine with --machine office.'))
expect(() => parseNewArgs(['claude', '@Mac mini'], env)).toThrow(new NewUsageError('Name the machine with --machine "Mac mini".'))
expect(() => parseNewArgs(['@'], env)).toThrow(new NewUsageError('Name the machine with --machine <name>.'))
expect(() => parseNewArgs(['codex', '--new', '@office'], env)).toThrow(new NewUsageError('Name the machine with --machine office.'))
})
it('takes the task after --, or as --task, with nothing to quote', () => {
expect(parseNewArgs(['codex', '--', 'fix', 'the', 'flaky', 'login', 'test'], env)).toMatchObject({ agent: 'codex', prompt: 'fix the flaky login test', cwd: '/work/repo' })
expect(parseNewArgs(['--task', 'write the README'], env).prompt).toBe('write the README')
// Words after -- are never read as an agent, a machine or a folder.
expect(parseNewArgs(['--', '@mini', '--machine', '~/x'], env)).toMatchObject({ agent: 'claude', machine: null, prompt: '@mini --machine ~/x' })
})
it('reads a path the shell already expanded as the other machine\'s home', () => {
// `harness new codex --machine mini ~/code/auth`, unquoted: zsh hands over /home/me/code/auth.
expect(parseNewArgs(['codex', '--machine', 'mini', '/home/me/code/auth'], env).cwd).toBe('~/code/auth')
expect(parseNewArgs(['codex', '--machine', 'mini', '/home/me'], env).cwd).toBe('~')
expect(parseNewArgs(['codex', '--machine', 'mini', '/srv/app'], env).cwd).toBe('/srv/app')
// On this machine an absolute path is just that.
expect(parseNewArgs(['codex', '/home/me/code/auth'], env).cwd).toBe('/home/me/code/auth')
})
it('reads the paths a Windows shell hands over as folders, not as a project name', () => {
const windows = { cwd: 'C:\\work\\repo', home: 'C:\\Users\\me', platform: 'win32' as const }
// The install job's check (B5.12): `harness new terminal $env:TEMP\harness-check-proj --json`.
expect(parseNewArgs(['terminal', 'C:\\Users\\me\\AppData\\Local\\Temp\\harness-check-proj', '--json'], windows))
.toMatchObject({ agent: 'terminal', cwd: 'C:\\Users\\me\\AppData\\Local\\Temp\\harness-check-proj', projectName: null })
expect(parseNewArgs(['codex', 'C:/code/api'], windows)).toMatchObject({ cwd: 'C:/code/api', projectName: null })
expect(parseNewArgs(['codex', '\\\\server\\share\\api'], windows).cwd).toBe('\\\\server\\share\\api')
expect(parseNewArgs(['codex', '.\\api'], windows).cwd).toBe('C:\\work\\repo\\api')
expect(parseNewArgs(['codex', '..\\other'], windows).cwd).toBe('C:\\work\\other')
expect(parseNewArgs(['codex', '~\\code\\auth'], windows).cwd).toBe('C:\\Users\\me\\code\\auth')
// `--new` never takes a path as the new project's name.
expect(() => parseNewArgs(['--new', 'C:\\x', 'codex'], windows)).toThrow(/not both/)
// Another machine resolves its own home, and may not be Windows.
expect(parseNewArgs(['codex', '--machine', 'mini', '~\\code\\auth'], windows).cwd).toBe('~/code/auth')
expect(parseNewArgs(['codex', '--machine', 'mini', 'C:\\Users\\me\\code\\auth'], windows).cwd).toBe('~/code/auth')
// A plain second word is still a new project, and off Windows a drive path is a name as before.
expect(parseNewArgs(['codex', 'my-game'], windows)).toMatchObject({ cwd: null, projectName: 'my-game' })
expect(parseNewArgs(['codex', 'C:\\x'], { ...env, platform: 'darwin' })).toMatchObject({ cwd: null, projectName: 'C:\\x' })
})
it('says what is wrong instead of guessing', () => {
for (const argv of [['a', 'b', 'c'], ['--machine'], ['--machine', '--json'], ['--machine', ' '], ['--machine', 'a', '--machine', 'b'], ['/x', '/y'], ['codex', 'game', '/x'], ['--mode', 'yolo'], ['--prompt'], ['--wat'], ['-x'], ['codex', '..'], ['codex', '--machine', 'mini', './rel']]) {
// `codex ..` is a folder, not an error; every other row must throw.
if (argv.join(' ') === 'codex ..') { expect(parseNewArgs(argv, env).cwd).toBe('/work'); continue }
expect(() => parseNewArgs(argv, env), argv.join(' ')).toThrow(NewUsageError)
}
expect(() => parseNewArgs(['codex', '!!!'], env)).toThrow(/no usable folder name/)
})
it('will not take a project for a terminal, which opens in a folder and makes none', () => {
// The name used to be dropped: the terminal opened in the home folder and no project was made.
expect(() => parseNewArgs(['terminal', 'my-game'], env)).toThrow(/does not make a project/)
expect(() => parseNewArgs(['terminal', '--new'], env)).toThrow(NewUsageError)
// Here, in a folder, or on another machine (its home): as before.
expect(parseNewArgs(['terminal'], env)).toMatchObject({ agent: 'terminal', cwd: env.cwd, projectName: null })
expect(parseNewArgs(['terminal', '~/code'], env)).toMatchObject({ cwd: `${env.home}/code`, projectName: null })
expect(parseNewArgs(['terminal', '--machine', 'mini'], env)).toMatchObject({ machine: 'mini', cwd: null, projectName: '' })
expect(newAgentPayload(parseNewArgs(['terminal', '--machine', 'mini'], env), null)).not.toHaveProperty('projectSource')
})
it('sends what the app sends', () => {
const here = newAgentPayload(parseNewArgs(['codex', '--plan', '--prompt', 'fix the tests'], env), '/work/repo')
expect(here).toMatchObject({ engine: 'codex', cwd: '/work/repo', permissionMode: 'plan', bypassPermission: false, prompt: 'fix the tests' })
expect(here).not.toHaveProperty('projectSource')
expect(typeof here.creationId).toBe('string')
const fresh = newAgentPayload(parseNewArgs(['claude', 'My Game'], env), null)
expect(fresh).toMatchObject({ engine: 'claude', projectSource: 'new', projectName: 'My-Game', bypassPermission: false })
expect(fresh).not.toHaveProperty('permissionMode')
expect(fresh).not.toHaveProperty('cwd')
expect(newAgentPayload(parseNewArgs(['acme/blender', '.'], env), '/work/repo', 'codex')).toMatchObject({ engine: 'codex', dsh: 'acme/blender' })
})
it('sends a cloud coding agent its repository and ACU limit, and refuses them for any other agent (#1444)', () => {
const args = parseNewArgs(['devin-cloud', '--machine', 'office', '--repo', 'acme/api', '--acu-limit', '10', '--json', '--', 'reply', 'to', 'the', 'thread'], env)
expect(args).toMatchObject({ agent: 'devin-cloud', repo: 'acme/api', acuLimit: 10, prompt: 'reply to the thread' })
expect(newAgentPayload(args, null)).toMatchObject({ engine: 'devin-cloud', repositoryUrl: 'acme/api', acuLimit: 10, prompt: 'reply to the thread' })
expect(newAgentPayload(parseNewArgs(['devin-cloud', '--', 'x'], env), null)).not.toHaveProperty('repositoryUrl')
expect(() => parseNewArgs(['codex', '--repo', 'acme/api'], env)).toThrow(/--repo is for a cloud agent/)
expect(() => parseNewArgs(['devin-cloud', '--repo', ' ', '--', 'x'], env)).toThrow(/--repo needs a value/)
expect(() => parseNewArgs(['devin-cloud', '--acu-limit', '0'], env)).toThrow(/1 to 1000/)
expect(() => parseNewArgs(['devin-cloud', '--acu-limit', '2.5'], env)).toThrow(/1 to 1000/)
})
// Swarm v3 (task #4215): an agent starts with its owner's own settings. A mode is sent only when the person typed one;
// the default `auto` went to every engine that has it, and before that to every engine, which the daemon refused
// (INVALID_PERMISSION_MODE) for the ten without a PERMISSION_MODES row.
it('sends a permission mode only when the person typed one', () => {
for (const agent of ['claude', 'codex', 'opencode', 'hermes', 'pi', 'amp', 'muse', 'kilo', 'grok', 'devin', 'commandcode', 'agy', 'copilot']) {
const payload = newAgentPayload(parseNewArgs([agent], env), '/work/repo')
expect(payload, agent).toMatchObject({ engine: agent, bypassPermission: false })
expect(payload, agent).not.toHaveProperty('permissionMode')
}
expect(newAgentPayload(parseNewArgs(['acme/blender'], env), '/work/repo', 'claude')).not.toHaveProperty('permissionMode')
expect(newAgentPayload(parseNewArgs(['claude', '--mode', 'auto'], env), '/work/repo')).toMatchObject({ permissionMode: 'auto', bypassPermission: true })
expect(newAgentPayload(parseNewArgs(['codex', '--mode', 'full'], env), '/work/repo')).toMatchObject({ permissionMode: 'full', bypassPermission: true })
expect(newAgentPayload(parseNewArgs(['claude', '--plan'], env), '/work/repo')).toMatchObject({ permissionMode: 'plan', bypassPermission: false })
expect(newAgentPayload(parseNewArgs(['terminal', '--mode', 'auto'], env), '/work/repo')).not.toHaveProperty('permissionMode')
// A mode the person typed stays theirs to get wrong: the daemon refuses it, it is not silently swapped.
expect(newAgentPayload(parseNewArgs(['hermes', '--mode', 'ask'], env), '/work/repo')).toMatchObject({ engine: 'hermes', permissionMode: 'ask', bypassPermission: false })
expect(newAgentPayload(parseNewArgs(['hermes', '--plan'], env), '/work/repo')).toMatchObject({ engine: 'hermes', permissionMode: 'plan', bypassPermission: false })
expect(newAgentPayload(parseNewArgs(['hermes', '--mode', 'auto'], env), '/work/repo')).toMatchObject({ engine: 'hermes', permissionMode: 'auto', bypassPermission: false })
})
it('finds the machine by id, name or an unambiguous start of one', () => {
const machines = [
{ machineId: 'm1', label: 'Mac mini', status: 'online', current: false },
{ machineId: 'm2', label: 'MacBook Pro', status: 'online', current: true },
]
expect(resolveNewMachine('m1', machines).label).toBe('Mac mini')
expect(resolveNewMachine('mac mini', machines).machineId).toBe('m1')
expect(resolveNewMachine('macb', machines).machineId).toBe('m2')
expect(() => resolveNewMachine('mac', machines)).toThrow(/could be Mac mini or MacBook Pro/)
expect(() => resolveNewMachine('linux', machines)).toThrow(/No machine called/)
})
// Seen 2026-10-16: `harness ps --machine "Mac Auto"` said `No machine called “Mac Auto”` for a machine Tuan
// shared with this account, which the app opened and created on with the owner's rights.
it('finds a machine shared with the account, and its own machine wins a name both have', () => {
const machines = machineChoices({
machines: [
{ machineId: 'own', name: 'MacBook Pro', hostname: 'mbp.local', status: 'running' },
{ machineId: 'own-mini', name: ' ', hostname: 'Mac mini', status: '' },
],
sharedMachines: [
{ machineId: 'auto', name: 'Mac Auto', status: 'running', share: { ownerName: 'Tuan', added: true } },
{ machineId: 'theirs-mini', name: 'Mac mini', status: 'running', share: { ownerName: 'Dee', added: true } },
{ machineId: 'team', name: 'gpu-box', status: 'running', share: { ownerName: 'Lee', added: false } },
{ machineId: 'nameless', hostname: 'studio.local', share: { ownerName: ' ', added: true } },
],
}, 'own')
expect(machines.map((machine) => [machine.machineId, machine.label, machine.status, machine.current, machine.sharedBy, machine.toAdd])).toEqual([
['own', 'MacBook Pro', 'running', true, undefined, undefined],
['own-mini', 'Mac mini', 'unknown', false, undefined, undefined],
['auto', 'Mac Auto', 'running', false, 'Tuan', undefined],
['theirs-mini', 'Mac mini', 'running', false, 'Dee', undefined],
['team', 'gpu-box', 'running', false, 'Lee', true],
['nameless', 'studio.local', 'unknown', false, 'another account', undefined],
])
expect(resolveNewMachine('Mac Auto', machines).machineId).toBe('auto')
expect(resolveNewMachine('auto', machines).machineId).toBe('auto')
expect(resolveNewMachine('mac mini', machines).machineId).toBe('own-mini')
// A domain share not added yet is not the account's to use: its machine refuses it. Named, it says how to add it.
expect(() => resolveNewMachine('gpu-box', machines)).toThrow('Lee shared “gpu-box” with everyone at your company. Add it first: Machines › Shared with your team, in the app or hn.')
expect(() => resolveNewMachine('team', machines)).toThrow(/Add it first/)
expect(() => resolveNewMachine('gpu', machines)).toThrow('No machine called “gpu”. Yours: MacBook Pro, Mac mini. Shared with you: Mac Auto, Mac mini, studio.local.')
expect(() => resolveNewMachine('linux', machineChoices({}, null))).toThrow('No machine called “linux”. Yours: none.')
})
})
class FakeSocket extends EventEmitter implements NewSocket {
sent: Array<{ type: string; payload: Record<string, unknown> }> = []
constructor(private answer: (frame: { type: string; payload: Record<string, unknown> }) => Record<string, unknown> | null) {
super()
}
// Opens once somebody is listening for it, as a real socket opens after it is constructed.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
override on(event: string, listener: (...args: any[]) => void): this {
super.on(event, listener)
if (event === 'open') queueMicrotask(() => this.emit('open'))
return this
}
send(data: string): void {
const frame = JSON.parse(data) as { type: string; payload: Record<string, unknown> }
this.sent.push(frame)
queueMicrotask(() => {
if (frame.type === 'machine_select') { this.emit('message', JSON.stringify({ type: 'connected', payload: {} })); return }
const payload = this.answer(frame)
if (payload) this.emit('message', JSON.stringify({ type: `${frame.type}_result`, payload: { ...payload, requestId: frame.payload.requestId } }))
})
}
close(): void {}
}
function deps(argv: string[], socket: FakeSocket, over: Partial<NewCommandDeps> = {}): NewCommandDeps & { out: string[]; err: string[] } {
const out: string[] = []
const err: string[] = []
return {
argv, cwd: env.cwd, home: env.home, port: 1, localMachineId: 'm2',
daemonRunning: () => true,
listMachines: async () => [
{ machineId: 'm1', label: 'Mac mini', status: 'online', current: false },
{ machineId: 'm2', label: 'MacBook Pro', status: 'online', current: true },
],
connect: () => socket,
output: (line) => out.push(line), error: (line) => err.push(line),
// Never the engines' settings of whoever runs the tests.
env: { HOME: '/nonexistent/home', CODEX_HOME: '/nonexistent/codex' },
timeoutMs: 200, out, err, ...over,
}
}
/** A connect that fails with [code], as `ws` reports it: one 'error', then 'close'. */
class RefusedSocket extends EventEmitter implements NewSocket {
constructor(private code: string) { super() }
// eslint-disable-next-line @typescript-eslint/no-explicit-any
override on(event: string, listener: (...args: any[]) => void): this {
super.on(event, listener)
if (event === 'error') queueMicrotask(() => {
this.emit('error', Object.assign(new Error(`connect ${this.code} 127.0.0.1:1`), { code: this.code }))
this.emit('close', 1006, '')
})
return this
}
send(): void {}
close(): void {}
}
describe('harness new: the daemon', () => {
it('says a sandbox is in the way when the daemon runs but its port is refused, and passes on anything else', async () => {
// Linux: the signal reaches the daemon, so it runs, and the sandbox refuses the connect (lib/unreachable.ts).
const sandboxed = deps(['claude', '--name', 'opinion', '--', 'a second opinion'], new FakeSocket(() => null), { connect: () => new RefusedSocket('EPERM') })
expect(await newCommand(sandboxed)).toBe(1)
expect(sandboxed.err).toEqual([SANDBOXED])
const json = deps(['claude', '--json'], new FakeSocket(() => null), { connect: () => new RefusedSocket('EACCES') })
expect(await newCommand(json)).toBe(1)
expect(JSON.parse(json.out[0]!)).toEqual({ ok: false, error: SANDBOXED })
// Nothing listening is not a sandbox's doing: said as the connection said it.
const refused = deps(['claude'], new FakeSocket(() => null), { connect: () => new RefusedSocket('ECONNREFUSED') })
expect(await newCommand(refused)).toBe(1)
expect(refused.err).toEqual(['connect ECONNREFUSED 127.0.0.1:1'])
})
it('selects this machine, creates here and says where', async () => {
const socket = new FakeSocket((frame) => frame.type === 'agent_create'
? { state: 'created', agent: { id: 'a1', name: 'Codex harness 9-19 10:02', cwd: '/work/repo' } } : null)
const d = deps(['codex'], socket)
expect(await newCommand(d)).toBe(0)
expect(socket.sent.map((frame) => frame.type)).toEqual(['machine_select', 'agent_create'])
// A tool, not a window: a window would turn the question watcher on and count as someone looking.
expect(socket.sent[0]!.payload).toEqual({ machineId: 'm2', localProtocolVersion: 1, tool: true })
expect(socket.sent[1]!.payload).toMatchObject({ engine: 'codex', cwd: '/work/repo' })
expect(d.out[0]).toBe('Created Codex harness 9-19 10:02 on this computer in /work/repo.')
})
it('asks another machine where its home is before using ~', async () => {
const socket = new FakeSocket((frame) => frame.type === 'fs_list_dir' ? { path: '/Users/mini', entries: [] }
: frame.type === 'agent_create' ? { state: 'created', agent: { id: 'a2', name: 'auth' } } : null)
const d = deps(['codex', '--machine', 'mini', '~/code/auth', '--json'], socket)
expect(await newCommand(d)).toBe(0)
expect(socket.sent[0]!.payload.machineId).toBe('m1')
expect(socket.sent.map((frame) => frame.type)).toEqual(['machine_select', 'fs_list_dir', 'agent_create'])
expect(socket.sent[2]!.payload.cwd).toBe('/Users/mini/code/auth')
expect(JSON.parse(d.out[0]!)).toMatchObject({ ok: true, machineId: 'm1', agent: { id: 'a2' } })
})
it('tells a person or a program that started one on another machine how to read it and wait for it from here', async () => {
// The lamp (lamp-4ace, 2026-10-14 21:36), a program outside Harness: `harness new claude @office lamp-first-task`
// told it only ⌘O, and `show` and `wait` without the machine looked on the lamp alone.
const created = (agent: Record<string, unknown>) => new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent } : null)
const lamp = deps(['claude', '--machine', 'mini', 'lamp-first-task', '--', 'What is 2+2?'], created({ id: 'a9b8c7d6e5', name: 'lamp-first-task' }))
expect(await newCommand(lamp)).toBe(0)
expect(lamp.out).toEqual([
'Created lamp-first-task on Mac mini.',
'Open it in Harness with ⌘O.',
'Read it: harness show --machine mini lamp-first-task · wait for it: harness wait --machine mini lamp-first-task',
])
// A machine named with a space is quoted; a harness whose name is a sentence is called by its id.
const spaced = deps(['claude', '--machine', 'Mac mini', 'scratch'], created({ id: 'a9b8c7d6e5', name: 'Claude harness 10-14 9:36' }))
expect(await newCommand(spaced)).toBe(0)
expect(spaced.out.at(-1)).toBe('Read it: harness show --machine "Mac mini" a9b8c7d6 · wait for it: harness wait --machine "Mac mini" a9b8c7d6')
// This computer, named or not, is read without one, as before.
const here = deps(['claude', '--machine', 'MacBook'], created({ id: 'h1', name: 'here' }))
expect(await newCommand(here)).toBe(0)
expect(here.out.at(-1)).toBe('Open it in Harness with ⌘O.')
})
// A typo used to reach the cloud service and come back a counted launch failure (Oct 26 report): refused here, in
// the service's own words, before anything is sent.
it.each([
[['cursor-cloud'], 'Tell Cursor Cloud what to do.'],
[['cursor-cloud', '--', ' '], 'Tell Cursor Cloud what to do.'],
[['cursor-cloud', '--repo', 'gitlab.com/a/b', '--', 'x'], 'That is not a GitHub repository: give owner/name or https://github.com/owner/name.'],
[['cursor-cloud', '--', 'x'], 'Choose a GitHub repository for Cursor Cloud.'],
[['fo'], 'Tell Fo what to do.'],
])('refuses a cloud request the service would refuse, sending nothing: %j', async (argv, words) => {
expect(() => parseNewArgs(argv, env)).toThrow(new NewUsageError(words))
const socket = new FakeSocket(() => null)
const refused = deps(argv, socket)
expect(await newCommand(refused)).toBe(2)
expect(refused.err[0]).toBe(words)
expect(socket.sent).toEqual([])
})
it('lets Devin Cloud start without a repository, and a cloud agent with one', () => {
expect(parseNewArgs(['devin-cloud', '--', 'x'], env)).toMatchObject({ agent: 'devin-cloud', prompt: 'x', repo: null })
expect(parseNewArgs(['cursor-cloud', '--repo', 'https://github.com/acme/api', '--', 'x'], env)).toMatchObject({ repo: 'https://github.com/acme/api' })
expect(parseNewArgs(['fo', '--task', 'book a table'], env)).toMatchObject({ agent: 'fo', prompt: 'book a table' })
})
it('refuses the old @machine before asking anything of a machine, and says what to type', async () => {
const socket = new FakeSocket(() => null)
const old = deps(['claude', '@office', 'lamp-first-task', '--', 'What is 2+2?'], socket)
expect(await newCommand(old)).toBe(2)
expect(old.err[0]).toBe('Name the machine with --machine office.')
expect(socket.sent).toEqual([])
})
it('reads a store harness\'s engine off the machine, and will not create one that is not installed', async () => {
const catalog = [{ id: 'acme/blender', engine: 'codex', installed: true }, { id: 'acme/typst', engine: 'claude', installed: false }]
const socket = new FakeSocket((frame) => frame.type === 'dsh_list' ? { dsh: catalog }
: frame.type === 'agent_create' ? { state: 'created', agent: { id: 'a3', name: 'Blender' } } : null)
expect(await newCommand(deps(['acme/blender'], socket))).toBe(0)
expect(socket.sent[2]!.payload).toMatchObject({ engine: 'codex', dsh: 'acme/blender' })
const refused = deps(['acme/typst'], new FakeSocket((frame) => frame.type === 'dsh_list' ? { dsh: catalog } : null))
expect(await newCommand(refused)).toBe(1)
expect(refused.err[0]).toBe('Install it first: harness dsh install acme/typst')
})
// prompt_unsupported, 4 in the Oct 21–27 report, came from `harness new <engine> --task`: say which flag to drop.
it('tells a first message the engine cannot take to leave out --task', async () => {
const refused = deps(['cursor', '--task', 'fix it'], new FakeSocket((frame) => frame.type === 'agent_create'
? { creationId: 'c1', state: 'failed', failure: { code: 'PROMPT_UNSUPPORTED' } } : null))
expect(await newCommand(refused)).toBe(1)
expect(refused.err[0]).toBe('That agent cannot be started with a first message. Run it again without --task.')
})
it('says a launch the machine refused or could not confirm failed, never "Created"', async () => {
const failed = deps(['codex'], new FakeSocket((frame) => frame.type === 'agent_create'
? { creationId: 'c1', state: 'failed', failure: { code: 'SPAWN_FAILED', detail: 'no codex' } } : null))
expect(await newCommand(failed)).toBe(1)
expect(failed.err[0]).toBe('The agent could not be started. (no codex)')
expect(failed.out).toEqual([])
const unknownCode = deps(['codex', '--json'], new FakeSocket((frame) => frame.type === 'agent_create'
? { creationId: 'c1', state: 'failed', failure: { code: 'ODD' } } : null))
expect(await newCommand(unknownCode)).toBe(1)
expect(JSON.parse(unknownCode.out[0]!)).toEqual({ ok: false, error: 'ODD' })
const bare = deps(['codex'], new FakeSocket((frame) => frame.type === 'agent_create' ? { creationId: 'c1', state: 'failed' } : null))
expect(await newCommand(bare)).toBe(1)
expect(bare.err[0]).toBe('The harness could not be started.')
const unconfirmed = deps(['codex'], new FakeSocket((frame) => frame.type === 'agent_create' || frame.type === 'agent_create_status'
? { creationId: 'c1', state: 'unconfirmed' } : null), { sleep: async () => {} })
expect(await newCommand(unconfirmed)).toBe(1)
expect(unconfirmed.err[0]).toMatch(/could not confirm .*\(unconfirmed\).*harness ps/)
})
it('asks after a launch the machine holds until it is made, by its creation id', async () => {
let asks = 0
const socket = new FakeSocket((frame) => {
if (frame.type === 'agent_create') return { creationId: frame.payload.creationId, state: 'pending' }
if (frame.type === 'agent_create_status') return ++asks < 3 ? { creationId: frame.payload.creationId, state: 'pending' } : { state: 'created', agent: { id: 'h1', name: 'held' } }
return null
})
const slept: number[] = []
const d = deps(['codex'], socket, { sleep: async (ms) => { slept.push(ms) } })
expect(await newCommand(d)).toBe(0)
expect(d.out[0]).toBe('Created held on this computer in /work/repo.')
const create = socket.sent.find((f) => f.type === 'agent_create')!
expect(socket.sent.filter((f) => f.type === 'agent_create_status').every((f) => f.payload.creationId === create.payload.creationId)).toBe(true)
expect(slept).toEqual([2_000, 2_000, 2_000])
})
it('says what a held launch waits for and, given up on, cancels it so it never starts later', async () => {
const held = (detail: string) => ({ state: 'pending', held: { service: 'native', detail } })
let asks = 0
const socket = new FakeSocket((frame) => {
if (frame.type === 'agent_create') return { creationId: frame.payload.creationId, ...held('Installing the required engine.') }
if (frame.type === 'agent_create_status') return ++asks < 5 ? held('Installing the required engine.') : held('Waiting to confirm the selected executable’s permission flags.')
if (frame.type === 'agent_create_cancel') return { creationId: frame.payload.creationId, state: 'cancelled' }
return null
})
const d = deps(['opencode', '--', 'fix it'], socket, { sleep: async () => {} })
expect(await newCommand(d)).toBe(1)
// Each reason once, as it changes, then why it stopped.
expect(d.err).toEqual([
'Installing the required engine.',
'Waiting to confirm the selected executable’s permission flags.',
'Harness did not start the harness within a minute: Waiting to confirm the selected executable’s permission flags. '
+ 'The request is cancelled, so it will not start later.',
])
expect(asks).toBe(30)
const create = socket.sent.find((f) => f.type === 'agent_create')!
expect(socket.sent.filter((f) => f.type === 'agent_create_cancel').map((f) => f.payload.creationId)).toEqual([create.payload.creationId])
expect(d.out).toEqual([])
})
it('waits for an engine Harness is installing, saying so once, then starts the harness', async () => {
// A fresh Ubuntu VM (2026-10-12): Codex took about a minute to install, the whole of the wait every other hold gets.
const installing = { state: 'pending', held: { service: 'install', detail: 'Installing Codex. The harness starts once it is installed.' } }
let asks = 0
const socket = new FakeSocket((frame) => frame.type === 'agent_create' ? installing
: frame.type === 'agent_create_status' ? (++asks < 60 ? installing : asks < 70 ? { state: 'pending', held: { service: 'native', detail: 'Waiting to confirm the engine’s native hooks.' } }
: { state: 'created', agent: { id: 'h3', name: 'cx' } }) : null)
const d = deps(['codex', '--', 'Reply with pong'], socket, { sleep: async () => {} })
expect(await newCommand(d)).toBe(0)
expect(d.err).toEqual(['Installing Codex. The harness starts once it is installed.', 'Waiting to confirm the engine’s native hooks.'])
expect(d.out[0]).toBe('Created cx on this computer in /work/repo.')
expect(socket.sent.some((f) => f.type === 'agent_create_cancel')).toBe(false)
})
it('gives an install five minutes, then says plainly it is still installing and that this request will not start', async () => {
let asks = 0
const socket = new FakeSocket((frame) => frame.type === 'agent_create_cancel' ? { state: 'cancelled' }
: (frame.type === 'agent_create_status' && ++asks, { state: 'pending', held: { service: 'install', detail: 'Installing Claude Code. The harness starts once it is installed.' } }))
const d = deps(['claude'], socket, { sleep: async () => {} })
expect(await newCommand(d)).toBe(1)
expect(asks).toBe(180)
expect(d.err.at(-1)).toBe('Harness is still installing Claude Code. Run the same command again in a minute; this request is cancelled, so it will not start later.')
// A hold after an install has finished is given its minute, and then said as the hold it is.
asks = 0
const after = new FakeSocket((frame) => frame.type === 'agent_create_cancel' ? null
: (frame.type === 'agent_create_status' && ++asks, asks < 10 ? { state: 'pending', held: { service: 'install', detail: 'Installing Codex.' } } : { state: 'pending', held: { service: 'native', detail: 'Waiting.' } }))
const late = deps(['codex'], after, { sleep: async () => {} })
expect(await newCommand(late)).toBe(1)
expect(asks).toBe(39)
expect(late.err.at(-1)).toBe('Harness did not start the harness in time: Waiting. It is still saved and may start later by itself: check with `harness ps` before starting another.')
})
it('takes what became of a launch it could no longer cancel, and says so when it cannot cancel at all', async () => {
const answer = (cancel: Record<string, unknown> | null) => new FakeSocket((frame) =>
frame.type === 'agent_create' || frame.type === 'agent_create_status' ? { state: 'pending' }
: frame.type === 'agent_create_cancel' ? cancel : null)
const started = deps(['codex'], answer({ state: 'created', agent: { id: 'h2', name: 'late' } }), { sleep: async () => {} })
expect(await newCommand(started)).toBe(0)
expect(started.out[0]).toBe('Created late on this computer in /work/repo.')
expect(started.err).toEqual([])
const refused = deps(['codex'], answer({ state: 'failed', failure: { code: 'ENGINE_CANNOT_RUN', detail: 'Codex is installed but cannot run: env: node: No such file or directory' } }), { sleep: async () => {} })
expect(await newCommand(refused)).toBe(1)
expect(refused.err).toEqual(['Codex is installed but cannot run: env: node: No such file or directory'])
// Claimed just before the cancel: starting now, not later, and not cancelled.
const claimed = deps(['codex'], answer({ state: 'unconfirmed' }), { sleep: async () => {} })
expect(await newCommand(claimed)).toBe(1)
expect(claimed.err).toEqual(['Harness could not confirm the harness started (unconfirmed). Check with `harness ps` before starting another.'])
const held = deps(['codex', 'my-game'], answer({ state: 'failed', failure: { code: 'NATIVE_LAUNCH_HELD', detail: 'Waiting to confirm native engine locations.' } }), { sleep: async () => {} })
expect(await newCommand(held)).toBe(1)
expect(held.err).toEqual(['The agent\'s engine was not ready to start. (Waiting to confirm native engine locations.)'])
// A daemon with no cancel (or no answer): the request is still saved, and that is said plainly.
const older = deps(['codex', '--json'], answer(null), { sleep: async () => {} })
expect(await newCommand(older)).toBe(1)
expect(JSON.parse(older.out[0]!)).toEqual({ ok: false, error: 'Harness did not start the harness within a minute. '
+ 'It is still saved and may start later by itself: check with `harness ps` before starting another.' })
expect(older.err).toEqual([])
})
// Review of #1333: a start left pending on another machine was to be checked with `harness ps`, which lists this one.
it('names the machine in what to check, for a start left pending on another one', async () => {
const answer = (cancel: Record<string, unknown> | null) => new FakeSocket((frame) =>
frame.type === 'agent_create' || frame.type === 'agent_create_status' ? { state: 'pending' }
: frame.type === 'agent_create_cancel' ? cancel : null)
const older = deps(['codex', '--machine', 'mini'], answer(null), { sleep: async () => {} })
expect(await newCommand(older)).toBe(1)
expect(older.err.at(-1)).toBe('Harness did not start the harness within a minute. '
+ 'It is still saved and may start later by itself: check with `harness ps --machine mini` before starting another.')
const claimed = deps(['codex', '--machine', 'Mac mini'], answer({ state: 'unconfirmed' }), { sleep: async () => {} })
expect(await newCommand(claimed)).toBe(1)
expect(claimed.err.at(-1)).toBe('Harness could not confirm the harness started (unconfirmed). Check with `harness ps --machine "Mac mini"` before starting another.')
})
// PROJECT_EXISTS was 4 of 7 failed starts on Oct 18: "Name its folder instead" said neither where nor how.
it('says where a typed project already is and the command that starts in it, or to choose another name', async () => {
const exists = (existingFolder?: string) => new FakeSocket((frame) => frame.type === 'agent_create' ? { creationId: 'c1', state: 'failed',
failure: { code: 'PROJECT_EXISTS', detail: '“payments” already exists. Select that folder from your projects.', ...(existingFolder ? { existingFolder } : {}) } } : null)
const here = deps(['codex', 'payments', '--name', 'pay', '--', 'add refunds'], exists('/home/me/harnesses/payments'))
expect(await newCommand(here)).toBe(1)
expect(here.err).toEqual(['“payments” already exists on this computer: ~/harnesses/payments. Choose another name for the new project, '
+ 'or start in that folder: harness new codex ~/harnesses/payments --name pay -- …'])
// On another machine its path is that machine's, named as it is.
const there = deps(['codex', '--machine', 'Mac mini', 'payments'], exists('/home/lee/Harness Projects/payments'))
expect(await newCommand(there)).toBe(1)
expect(there.err).toEqual(['“payments” already exists on Mac mini: /home/lee/Harness Projects/payments. Choose another name for the new project, '
+ 'or start in that folder: harness new codex --machine "Mac mini" "/home/lee/Harness Projects/payments"'])
const mcp = deps(['codex', '--new', 'payments', '--name', 'pay', '--task', 'add refunds'], exists('/home/me/harnesses/payments'),
{ env: { HARNESS_VIA_MCP: '1', HOME: '/nonexistent/home', CODEX_HOME: '/nonexistent/codex' } })
expect(await newCommand(mcp)).toBe(1)
expect(mcp.err.at(-1)).toBe('“payments” already exists on this computer: ~/harnesses/payments. Choose another name for the new project, '
+ 'or start in that folder: harness_start (folder: "~/harnesses/payments", …)')
// A file has that name, or the machine predates naming the folder: only another name helps.
const file = deps(['codex', 'payments', '--json'], exists())
expect(await newCommand(file)).toBe(1)
expect(JSON.parse(file.out[0]!)).toEqual({ ok: false, error: '“payments” already exists on this computer. Choose another name for the new project.' })
})
it('says why the machine refused an engine that cannot run, in the machine\'s words', async () => {
const d = deps(['codex'], new FakeSocket((frame) => frame.type === 'agent_create' ? { creationId: 'c1', state: 'failed',
failure: { code: 'ENGINE_CANNOT_RUN', detail: 'Codex is installed but cannot run: /usr/bin/env: ‘node’: No such file or directory' } } : null))
expect(await newCommand(d)).toBe(1)
expect(d.err).toEqual(['Codex is installed but cannot run: /usr/bin/env: ‘node’: No such file or directory'])
})
it('answers an agent within 40 seconds, leaving a harness still installing to start by itself, recorded by its name', async () => {
// An MCP client ends a tool call at a minute (Codex's default tool_timeout_sec): a Codex install takes about that.
const installing = { state: 'pending', held: { service: 'install', detail: 'Installing Codex. The harness starts once it is installed.' } }
const pending: Array<[string, Record<string, unknown>]> = []
const origin = { check: async () => {}, prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }), existing: async () => null,
pending: (machineId: string, creation: Record<string, unknown>) => { pending.push([machineId, creation]) } }
const run = async (env: NodeJS.ProcessEnv, json = false, name = 'cx') => {
let clock = 0
const socket = new FakeSocket((frame) => frame.type === 'agent_create' || frame.type === 'agent_create_status' ? installing : frame.type === 'agent_create_cancel' ? { state: 'cancelled' } : null)
const d = deps(['codex', '--name', name, ...(json ? ['--json'] : []), '--', 'Reply with pong'], socket,
{ origin: async () => origin, env, now: () => clock, sleep: async (ms) => { clock += ms } })
expect(await newCommand(d)).toBe(0)
expect(clock).toBe(40_000)
expect(socket.sent.some((f) => f.type === 'agent_create_cancel')).toBe(false)
return { d, socket }
}
const mcp = await run({ HARNESS_VIA_MCP: '1' })
expect(mcp.d.out).toEqual(['cx on this computer: installing Codex. It starts by itself once installed; do not start it again.\n'
+ 'Next: harness_wait (names: "cx") (until it has started and answered)'])
expect(mcp.d.err).toEqual([])
const creationId = mcp.socket.sent.find((f) => f.type === 'agent_create')!.payload.creationId
expect(pending).toEqual([['m2', { creationId, name: 'cx', engine: 'codex' }]])
const shell = await run({})
expect(shell.d.err).toEqual(['Installing Codex. The harness starts once it is installed.'])
expect(shell.d.out).toEqual(['cx on this computer: installing Codex. It starts by itself once installed; do not start it again.\n'
+ 'Next: harness wait cx (until it has started and answered)'])
const json = await run({ HARNESS_VIA_MCP: '1' }, true)
expect(JSON.parse(json.d.out[0]!)).toMatchObject({ ok: true, pending: true, machineId: 'm2', name: 'cx',
next: [{ run: 'harness_wait (names: "cx")', when: 'until it has started and answered' }] })
expect(json.d.err).toEqual([])
// A name of two words: one name to wait on, as the shell takes it and as the tool does.
const spaced = await run({}, false, 'code review')
expect(spaced.d.out[0]!.split('\n').at(-1)).toBe('Next: harness wait "code review" (until it has started and answered)')
const spacedMcp = await run({ HARNESS_VIA_MCP: '1' }, false, 'code review')
expect(spacedMcp.d.out[0]!.split('\n').at(-1)).toBe('Next: harness_wait (names: "code review") (until it has started and answered)')
})
it('names no harness it was given no name for, and asks for at least ten seconds however long the setup took', async () => {
let clock = 0
const installing = { state: 'pending', held: { service: 'install', detail: 'Installing Codex.' } }
// Forty seconds gone before the machine answered: a slow line to another machine.
const origin = { check: async () => { clock += 45_000 }, prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }), pending: () => {} }
let asks = 0
const socket = new FakeSocket((frame) => frame.type === 'agent_create' ? installing : frame.type === 'agent_create_status' ? (asks++, installing) : null)
const d = deps(['codex'], socket, { origin: async () => origin, now: () => clock, sleep: async (ms) => { clock += ms } })
expect(await newCommand(d)).toBe(0)
expect(asks).toBe(5)
expect(d.out).toEqual(['The harness on this computer: installing Codex. It starts by itself once installed; do not start it again.\n'
+ 'Next: harness ps (to follow it)'])
})
it('still cancels an agent\'s launch held for anything but an install, at 40 seconds', async () => {
let clock = 0
const origin = { check: async () => {}, prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }), pending: () => {} }
const socket = new FakeSocket((frame) => frame.type === 'agent_create_cancel' ? { state: 'cancelled' }
: frame.type === 'agent_create' || frame.type === 'agent_create_status' ? { state: 'pending', held: { service: 'native', detail: 'Waiting.' } } : null)
const d = deps(['codex', '--name', 'cx'], socket, { origin: async () => origin, now: () => clock, sleep: async (ms) => { clock += ms } })
expect(await newCommand(d)).toBe(1)
expect(d.err.at(-1)).toBe('Harness did not start the harness in time: Waiting. The request is cancelled, so it will not start later.')
})
it('answers an agent asking again for a harness it already has with that one, and asks the machine nothing', async () => {
const socket = new FakeSocket(() => null)
const note = '"cx" is already starting: Harness is installing Codex. It starts by itself; wait for it with harness wait cx. Do not start it again.'
const asked: unknown[] = []
const origin = { check: async () => { throw new Error('not reached') }, prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }),
existing: async (name: string | null, asking: { machineId: string; engine: string }) => {
asked.push(asking)
return name === 'cx' ? { name: 'cx', machineId: 'm2', state: 'starting' as const, note } : null
} }
const d = deps(['codex', '--name', 'cx', '--', 'again'], socket, { origin: async () => origin })
expect(await newCommand(d)).toBe(0)
expect(d.out).toEqual([note])
expect(socket.sent).toEqual([])
const json = deps(['codex', '--name', 'cx', '--json'], socket, { origin: async () => origin })
expect(await newCommand(json)).toBe(0)
expect(JSON.parse(json.out[0]!)).toEqual({ ok: true, existing: true, name: 'cx', machineId: 'm2', state: 'starting', note })
expect(asked).toEqual([{ machineId: 'm2', engine: 'codex' }, { machineId: 'm2', engine: 'codex' }])
})
it('records the creation a harness was asked by when the machine made it', async () => {
const created: unknown[][] = []
const origin = { check: async () => {}, prompt: (text: string) => text, answer: () => ({ effect: '', next: [] }), pending: () => {},
created: async (...args: unknown[]) => { created.push(args); return null } }
const socket = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'k1', name: 'cx' } } : null)
expect(await newCommand(deps(['codex', '--name', 'cx'], socket, { origin: async () => origin }))).toBe(0)
expect(created).toEqual([['m2', { id: 'k1', name: 'cx' }, socket.sent.find((f) => f.type === 'agent_create')!.payload.creationId]])
})
it('reads the folder off the harness the machine made', async () => {
const socket = new FakeSocket((frame) => frame.type === 'agent_create'
? { state: 'created', agent: { id: 'a1', name: 'fixer', project: { cwd: '/work/repo/.worktrees/x' } } } : null)
const d = deps(['codex'], socket)
expect(await newCommand(d)).toBe(0)
expect(d.out[0]).toBe('Created fixer on this computer in /work/repo/.worktrees/x.')
})
it('exits 5 when the agent is refused, and says why in JSON beside the old error', async () => {
const message = 'You have 4 harnesses running. Close one you are done with first (harness close <name>).'
const origin = { check: async () => { throw new AgentClientError('SPAWN_LIMIT', message, 'OPEN_LIMIT') },
prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }) }
const text = deps(['codex', '--name', 'x'], new FakeSocket(() => null), { origin: async () => origin })
expect(await newCommand(text)).toBe(5)
expect(text.err).toEqual([message])
const json = deps(['codex', '--name', 'x', '--json'], new FakeSocket(() => null), { origin: async () => origin })
expect(await newCommand(json)).toBe(5)
expect(JSON.parse(json.out[0]!)).toEqual({ ok: false, error: message, code: 'SPAWN_LIMIT', reason: 'OPEN_LIMIT',
next: [{ run: 'harness close <name>', when: 'one you are done with, to free a place' }] })
// Not a refusal: a failure, as before.
const failing = deps(['codex', '--json'], new FakeSocket(() => null), { origin: async () => ({ ...origin, check: async () => { throw new Error('broke') } }) })
expect(await newCommand(failing)).toBe(1)
expect(JSON.parse(failing.out[0]!)).toEqual({ ok: false, error: 'broke' })
})
it('run by an agent: checks its limits, heads its task with who sent it, records it, and says how to follow it', async () => {
const created: Array<[string, Record<string, unknown>]> = []
let warning: string | null = null
const origin = {
check: async () => {},
prompt: (text: string, machineId: string) => `[from lead on ${machineId}]\n\n${text}`,
created: async (machineId: string, agent: Record<string, unknown>) => { created.push([machineId, agent]); return warning },
answer: (agent: Record<string, unknown>) => ({ effect: 'The person sees it in Harness, beside you.',
next: [{ run: `harness wait ${String(agent.name)}`, when: `until it has answered; then read it: harness show ${String(agent.name)}` }] }),
}
const socket = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'a9', name: 'reviewer' } } : null)
const d = deps(['codex', '--name', 'reviewer', '--', 'review', 'it'], socket, { origin: async () => origin })
expect(await newCommand(d)).toBe(0)
expect(socket.sent[1]!.payload.prompt).toBe('[from lead on m2]\n\nreview it')
// The machine records that an agent started it: the pull requests it opens say so (lib/agentAttribution.ts).
expect(socket.sent[1]!.payload.startedBy).toBe('agent')
expect(created).toEqual([['m2', { id: 'a9', name: 'reviewer' }]])
// Starting, never started the task; what changed; and what to run next.
expect(d.out).toEqual(['reviewer on this computer: starting. Codex, in /work/repo.', 'The person sees it in Harness, beside you.',
'Next: harness wait reviewer (until it has answered; then read it: harness show reviewer)'])
const json = deps(['codex', '--name', 'reviewer', '--json', '--', 'review', 'it'], new FakeSocket((frame) => frame.type === 'agent_create'
? { state: 'created', agent: { id: 'a9', name: 'reviewer' } } : null), { origin: async () => origin })
expect(await newCommand(json)).toBe(0)
expect(JSON.parse(json.out[0]!)).toMatchObject({ ok: true, agent: { id: 'a9' }, effect: 'The person sees it in Harness, beside you.',
next: [{ run: 'harness wait reviewer', when: 'until it has answered; then read it: harness show reviewer' }] })
// No task: nothing to head.
const quiet = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'b1', name: 'idle' } } : null)
expect(await newCommand(deps(['codex'], quiet, { origin: async () => origin }))).toBe(0)
expect(quiet.sent[1]!.payload.prompt).toBeUndefined()
// Over a limit: refused before anything is asked of the machine.
const refused = new FakeSocket(() => null)
const over = deps(['codex', '--', 'go'], refused, { origin: async () => ({ ...origin, check: async () => { throw new Error('You have 8 harnesses running.') } }) })
expect(await newCommand(over)).toBe(1)
expect(over.err[0]).toBe('You have 8 harnesses running.')
expect(refused.sent).toEqual([])
// A record another machine could not keep: said, and the harness is still made.
warning = 'its limits start from zero'
const far = deps(['codex', '--', 'go'], new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'f1', name: 'far' } } : null), { origin: async () => origin })
expect(await newCommand(far)).toBe(0)
expect(far.err).toEqual(['its limits start from zero'])
// Full mode: refused before anything is asked of the machine. Its commands run unasked, so full mode would turn
// the new agent's checks and sandbox off with no one asked; auto, the default, and the other modes are its to ask for.
const unasked = new FakeSocket(() => null)
const full = deps(['codex', '--mode', 'full', '--json', '--', 'go'], unasked, { origin: async () => origin })
expect(await newCommand(full)).toBe(1)
expect(JSON.parse(full.out[0]!)).toMatchObject({ ok: false, error: expect.stringMatching(/^An agent cannot start a harness in full mode.*Nothing was started\.$/) })
expect(unasked.sent).toEqual([])
const planned = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'p1', name: 'planner' } } : null)
expect(await newCommand(deps(['codex', '--plan', '--', 'go'], planned, { origin: async () => origin }))).toBe(0)
expect(planned.sent[1]!.payload).toMatchObject({ permissionMode: 'plan' })
// The person chooses full mode as before.
const theirs = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'x1', name: 'x' } } : null)
expect(await newCommand(deps(['codex', '--mode', 'full', '--', 'go'], theirs, { origin: async () => null }))).toBe(0)
expect(theirs.sent[1]!.payload).toMatchObject({ permissionMode: 'full', bypassPermission: true })
// A terminal: refused before anything is asked of the machine. No verb of the agent's lists one, so it could
// never read or close what it started.
const none = new FakeSocket(() => null)
const shell = deps(['terminal', '--json', '--', 'npm run dev'], none, { origin: async () => origin })
expect(await newCommand(shell)).toBe(1)
expect(JSON.parse(shell.out[0]!)).toMatchObject({ ok: false, error: expect.stringMatching(/^An agent cannot start a terminal.*Nothing was started\.$/) })
expect(none.sent).toEqual([])
// The person's own terminal is still made, where they are.
const own = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 't1', name: 'Terminal' } } : null)
expect(await newCommand(deps(['terminal'], own, { origin: async () => null }))).toBe(0)
expect(own.sent[1]!.payload).toMatchObject({ engine: 'terminal', cwd: env.cwd })
// A person at a terminal: no origin, the old words.
const atTerminal = new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent: { id: 'c1', name: 'x' } } : null)
const person = deps(['codex'], atTerminal, { origin: async () => null })
expect(await newCommand(person)).toBe(0)
expect(person.out[1]).toBe('Open it in Harness with ⌘O.')
expect(atTerminal.sent[1]!.payload).not.toHaveProperty('startedBy')
})
it('run by a harness here: names it as the one that started the new harness, so the windows open it beside it', async () => {
const origin = {
check: async () => {}, prompt: (text: string) => text, created: async () => null, answer: () => ({ effect: '', next: [] }), parentAgentId: 'lead-agent',
}
const created = (id: string) => new FakeSocket((frame) => frame.type === 'fs_list_dir' ? { path: '/Users/mini', entries: [] }
: frame.type === 'agent_create' ? { state: 'created', agent: { id, name: id } } : null)
const here = created('kid')
expect(await newCommand(deps(['codex', '--', 'review it'], here, { origin: async () => origin }))).toBe(0)
expect(here.sent[1]!.payload).toMatchObject({ startedBy: 'agent', parentAgentId: 'lead-agent' })
// `--machine <this computer>` is still here.
const named = created('kid2')
expect(await newCommand(deps(['codex', '--machine', 'MacBook', '--', 'go'], named, { origin: async () => origin }))).toBe(0)
expect(named.sent.find((frame) => frame.type === 'agent_create')!.payload.parentAgentId).toBe('lead-agent')
// Another machine has no harness by that id: it records only that an agent started it.
const far = created('far')
expect(await newCommand(deps(['codex', '--machine', 'mini', '~/w', '--', 'go'], far, { origin: async () => origin }))).toBe(0)
const farCreate = far.sent.find((frame) => frame.type === 'agent_create')!.payload
expect(farCreate.startedBy).toBe('agent')
expect(farCreate).not.toHaveProperty('parentAgentId')
// An agent outside Harness has no harness to name.
const outside = created('helper')
expect(await newCommand(deps(['codex', '--', 'go'], outside, { origin: async () => ({ ...origin, parentAgentId: undefined }) }))).toBe(0)
expect(outside.sent[1]!.payload.startedBy).toBe('agent')
expect(outside.sent[1]!.payload).not.toHaveProperty('parentAgentId')
})
it('turns the machine\'s refusal into words, and a usage slip into the usage', async () => {
const socket = new FakeSocket((frame) => frame.type === 'agent_create' ? { error: 'INVALID_CWD', detail: '/nope' } : null)
const d = deps(['codex', '/nope'], socket)
expect(await newCommand(d)).toBe(1)
expect(d.err[0]).toBe('That folder does not exist on the machine. (/nope)')
const help = deps(['--help'], socket)
expect(await newCommand(help)).toBe(0)
expect(help.out.join('\n')).toContain('Usage: harness new')
expect(help.err).toEqual([])
const slip = deps(['a', 'b', 'c'], socket)
expect(await newCommand(slip)).toBe(2)
expect(slip.err.join('\n')).toContain('Usage: harness new')
const stopped = deps(['codex'], socket, { daemonRunning: () => false })
expect(await newCommand(stopped)).toBe(1)
expect(stopped.err[0]).toMatch(/harness start/)
// Out of a sandbox's reach, what the CLI says instead: never to start a Harness that is running.
const kept = deps(['codex'], socket, { daemonRunning: () => false, unreachable: () => 'kept out by a sandbox' })
expect(await newCommand(kept)).toBe(1)
expect(kept.err).toEqual(['kept out by a sandbox'])
})
})
/** A computer's folders and its engines' settings under a throwaway root: Claude Code's `.claude.json` in its home and
* Codex's config.toml in its CODEX_HOME, as each has them once it has run. */
function computer() {
const root = mkdtempSync(join(tmpdir(), 'new-trust-'))
const home = join(root, 'home'), codex = join(root, 'codex')
mkdirSync(join(home, 'harnesses'), { recursive: true })
mkdirSync(codex)
const claudeTrusts = (...folders: string[]) => writeFileSync(join(home, '.claude.json'),
JSON.stringify({ projects: Object.fromEntries(folders.map((folder) => [folder, { hasTrustDialogAccepted: true }])) }))
const codexTrusts = (...folders: string[]) => writeFileSync(join(codex, 'config.toml'),
folders.map((folder) => `[projects.${JSON.stringify(folder)}]\ntrust_level = "trusted"\n`).join('\n'))
claudeTrusts()
codexTrusts()
const folder = (name: string, ...files: string[]) => {
const dir = join(root, name)
mkdirSync(dir, { recursive: true })
for (const file of files) writeFileSync(join(dir, file), '')
return dir
}
return { root, home, env: { HOME: home, CODEX_HOME: codex }, claudeTrusts, codexTrusts, folder }
}
/** An agent starting harnesses, as agentClient/commands.ts `agentOrigin` is to `harness new`. */
const agentStarting = () => {
const created: string[] = []
return {
created,
origin: {
check: async () => {},
prompt: (text: string) => text,
created: async (_machineId: string, agent: Record<string, unknown>) => { created.push(String(agent.id)); return null },
answer: () => ({ effect: '', next: [{ run: 'harness show it', when: 'to read it' }] }),
},
}
}
const creating = (agent: Record<string, unknown>) => new FakeSocket((frame) => frame.type === 'agent_create' ? { state: 'created', agent } : null)
describe('harness new: a folder the engine would ask about', () => {
it('reads whether Claude Code or Codex will ask the person to trust a folder before it starts', async () => {
const c = computer()
const scratch = c.folder('scratch')
const work = c.folder('work', 'README.md')
for (const engine of ['claude', 'codex']) {
expect(await trustAsked(engine, scratch, c.home, c.env)).toBe('empty')
expect(await trustAsked(engine, work, c.home, c.env)).toBe('content')
// Empty and directly inside the projects root: Harness answers for it as the engine starts.
expect(await trustAsked(engine, c.folder('home/harnesses/review'), c.home, c.env)).toBeNull()
}
// Further down, it is the engine's question again.
expect(await trustAsked('claude', c.folder('home/harnesses/review/deeper'), c.home, c.env)).toBe('empty')
// Nothing to ask: an engine with no such question, a store harness's name, a folder that is not there (the machine says).
expect(await trustAsked('opencode', scratch, c.home, c.env)).toBeNull()
expect(await trustAsked('owner/kit', scratch, c.home, c.env)).toBeNull()
expect(await trustAsked('claude', join(c.root, 'missing'), c.home, c.env)).toBeNull()
})
it('takes the trust an engine has: by the path typed or the one it resolves to, from above, and by the repository', async () => {
const c = computer()
// macOS's /tmp is /private/tmp: a folder reached through a link, trusted as it resolves, or as it was typed.
const real = c.folder('real-scratch')
const typed = join(c.root, 'typed-scratch')
symlinkSync(real, typed)
c.claudeTrusts(realpathSync(real))
c.codexTrusts(typed)
expect(await trustAsked('claude', typed, c.home, c.env)).toBeNull()
expect(await trustAsked('codex', typed, c.home, c.env)).toBeNull()
// Claude Code's trust covers every folder below; Codex's is the folder's own, or its repository's.
c.claudeTrusts(realpathSync(c.root))
expect(await trustAsked('claude', c.folder('anywhere/below'), c.home, c.env)).toBeNull()
expect(await trustAsked('codex', c.folder('anywhere/else'), c.home, c.env)).toBe('empty')
const repo = c.folder('repo/.git').replace(/\/\.git$/, '')
const src = c.folder('repo/src', 'a.ts')
const worktree = c.folder('wt', 'a.ts')
writeFileSync(join(worktree, '.git'), `gitdir: ${realpathSync(repo)}/.git/worktrees/wt\n`)
const relative = c.folder('wt2', 'a.ts')
writeFileSync(join(relative, '.git'), 'gitdir: ../repo/.git/worktrees/wt2\n')
const submodule = c.folder('sub', 'a.ts')
writeFileSync(join(submodule, '.git'), 'gitdir: ../repo/.git/modules/sub\n')
for (const folder of [src, worktree, relative, submodule]) expect(await trustAsked('codex', folder, c.home, c.env)).toBe('content')
c.codexTrusts(realpathSync(repo))
for (const folder of [src, worktree, relative]) expect(await trustAsked('codex', folder, c.home, c.env)).toBeNull()
expect(await trustAsked('codex', submodule, c.home, c.env)).toBe('content')
})
it('refuses an agent an empty folder of its own, in words it can act on, before anything is started', async () => {
// A Codex harness asked for a second opinion from Claude Code made `mktemp -d /tmp/shell-opinion.XXXX` and started
// Claude Code there, which stopped on its trust question (a clean VM, CLI 0.3.75, 2026-10-11).
const c = computer()
const scratch = c.folder('shell-opinion.e0ynGN')
const { origin, created } = agentStarting()
const socket = new FakeSocket(() => null)
const shell = deps(['claude', scratch, '--name', 'opinion', '--', 'a second opinion'], socket, { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(shell)).toBe(1)
expect(shell.err).toEqual([`Claude Code would ask the person to trust ${scratch} before it starts, and it is empty: for scratch or new work `
+ 'give a project name instead — harness new claude opinion --name opinion -- … (Harness makes ~/harnesses/opinion, which needs no '
+ 'approval). Nothing was started.'])
expect(socket.sent.map((frame) => frame.type)).toEqual(['machine_select'])
expect(created).toEqual([])
// Through `harness mcp`: its tool, by the name it gave.
const viaMcp = deps(['codex', scratch, '--name', 'Second opinion', '--', 'a second opinion'], new FakeSocket(() => null),
{ origin: async () => origin, env: { ...c.env, HARNESS_VIA_MCP: '1' }, home: c.home })
expect(await newCommand(viaMcp)).toBe(1)
expect(viaMcp.err).toEqual([`Codex would ask the person to trust ${scratch} before it starts, and it is empty: for scratch or new work `
+ 'give a project name instead — harness_start (project: "Second-opinion", …) (Harness makes ~/harnesses/Second-opinion, which '
+ 'needs no approval). Nothing was started.'])
// Unnamed, and asked for JSON.
const json = deps(['codex', scratch, '--json', '--', 'go'], new FakeSocket(() => null), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(json)).toBe(1)
expect(JSON.parse(json.out[0]!)).toEqual({ ok: false, error: expect.stringContaining('— harness new codex review -- … (Harness makes ~/harnesses/review,') })
// Trusted already, it starts.
c.claudeTrusts(realpathSync(scratch))
const trusted = deps(['claude', scratch, '--', 'go'], creating({ id: 'a1', name: 'opinion' }), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(trusted)).toBe(0)
expect(trusted.out).toEqual([`opinion on this computer: starting. Claude Code, in ${scratch}.`, 'Next: harness show it (to read it)'])
})
it('starts an agent\'s harness in a folder with content, and says it will wait for the person to trust it', async () => {
const c = computer()
const work = c.folder('work', 'README.md')
const { origin, created } = agentStarting()
const shell = deps(['codex', work, '--name', 'reviewer', '--', 'review it'], creating({ id: 'a1', name: 'reviewer' }), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(shell)).toBe(0)
expect(shell.out).toEqual([
`reviewer on this computer: starting. Codex, in ${work}.`,
`Codex will ask the person to trust ${work} before it starts, so it waits for them until they answer (harness wait exits 3). `
+ 'For new work, a project name avoids this: harness new codex reviewer --name reviewer -- …',
'Next: harness show it (to read it)',
])
expect(created).toEqual(['a1'])
const viaMcp = deps(['claude', work, '--name', 'reviewer', '--', 'review it'], creating({ id: 'a2', name: 'reviewer' }),
{ origin: async () => origin, env: { ...c.env, HARNESS_VIA_MCP: '1' }, home: c.home })
expect(await newCommand(viaMcp)).toBe(0)
expect(viaMcp.out[1]).toBe(`Claude Code will ask the person to trust ${work} before it starts, so it waits for them until they answer `
+ '(harness_wait says it needs the person). For new work, a project name avoids this: harness_start (project: "reviewer", …)')
const json = deps(['codex', work, '--json', '--', 'go'], creating({ id: 'a3', name: 'x' }), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(json)).toBe(0)
expect(JSON.parse(json.out[0]!)).toMatchObject({ ok: true, agent: { id: 'a3' }, note: expect.stringContaining('Codex will ask the person to trust') })
// Trusted: nothing to say.
c.codexTrusts(realpathSync(work))
const trusted = deps(['codex', work, '--', 'go'], creating({ id: 'a4', name: 'x' }), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(trusted)).toBe(0)
expect(trusted.out).toEqual([`x on this computer: starting. Codex, in ${work}.`, 'Next: harness show it (to read it)'])
})
it('leaves the person at a terminal, another machine, and a store harness\'s empty folder as they were', async () => {
const c = computer()
const scratch = c.folder('scratch')
const work = c.folder('work', 'README.md')
const { origin } = agentStarting()
// The person is there to answer the question.
const person = deps(['claude', scratch], creating({ id: 'p1', name: 'mine' }), { origin: async () => null, env: c.env, home: c.home })
expect(await newCommand(person)).toBe(0)
expect(person.out).toEqual([`Created mine on this computer in ${scratch}.`, 'Open it in Harness with ⌘O.'])
// Another machine's folders and settings are not here to read.
const far = deps(['claude', '--machine', 'mini', scratch], creating({ id: 'f1', name: 'far' }), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(far)).toBe(0)
expect(far.out).toEqual([`far on Mac mini: starting. Claude Code, in ${scratch}.`, 'Next: harness show it (to read it)'])
// A store harness lays its template into an empty folder, which is then trusted; one with content is still asked about.
const store = (folder: string) => new FakeSocket((frame) => frame.type === 'dsh_list' ? { dsh: [{ id: 'owner/kit', engine: 'claude', installed: true }] }
: frame.type === 'agent_create' ? { state: 'created', agent: { id: 's1', name: 'kit' } } : null)
const empty = deps(['owner/kit', scratch], store(scratch), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(empty)).toBe(0)
expect(empty.out).toEqual([`kit on this computer: starting. Claude Code, in ${scratch}.`, 'Next: harness show it (to read it)'])
const full = deps(['owner/kit', work], store(work), { origin: async () => origin, env: c.env, home: c.home })
expect(await newCommand(full)).toBe(0)
expect(full.out[1]).toBe(`Claude Code will ask the person to trust ${work} before it starts, so it waits for them until they answer `
+ '(harness wait exits 3). For new work, a project name avoids this: harness new owner/kit review -- …')
})
})