Skip to content

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.

48.4 KB
Raw Blame
/**
 * Harness for agents on the real daemon (docs/design/2026-10-11-agent-client.md): an agent, from its own pane, runs
 * the `harness` verbs as it would through its shell tool. It lists the harnesses, starts one with a task, waits for
 * it, reads its answer, and closes it; it may not close one it did not start. Neither may message the other while
 * they share no tab (owner, 2026-10-11: Agent Messages off means off). The fake engines answer by echoing
 * (harness/fakeEngine.mjs). Agent-started harnesses retain their coordination instructions, without
 * adding Harness attribution to pull requests, even if an older account setting still asks for it.
 *
 * What agents may do is the account's (Settings ▸ Experimental, every switch off by default): signed in to the fake
 * backend, which answers the account's experiments and its tabs (there are none), and turned on where a test needs it.
 */
import { execFileSync, spawn } from 'node:child_process'
import { createInterface } from 'node:readline'
import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { pathToFileURL } from 'node:url'
import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
import { LocalClient } from './harness/client.js'
import { CLI_ROOT, IsolatedDaemon, until } from './harness/daemon.js'
import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'
import { retainContributions, retainedHarnesses } from '../src/superTabs/retention.js'
import { overOldRoutes } from './harness/swarmReads.js'

const HARNESS_INSTRUCTIONS = 'You are running in Harness, and the person can watch you. You can hand work to other agents (Claude Code, Codex) that run in their own harnesses: `harness new`, `harness wait`, `harness show`, `harness close` (see `harness --help`). Start one only for work that can run in parallel, needs another model, or takes long; do quick work yourself, and close each one once you have its answer. Only use or close harnesses you started.'
const ME: FakeMachine = { machineId: 'b8'.repeat(16), computerId: 'e2e-computer-0000-0000-0000000000b8', name: 'studio', token: 'e2e-token-agent-client' }
const signIn = (d: IsolatedDaemon) => writeFileSync(join(d.root, 'auth', 'session.json'), JSON.stringify({
  version: 1, accessToken: ME.token, autonomousEnv: 'prod', computerId: ME.computerId,
  machineId: ME.machineId, expiresAt: Date.now() + 30 * 24 * 3600_000, updatedAt: Date.now(), signInEpoch: 'e2e',
}), { mode: 0o600 })

/** `harness <args>` from [pane], as an agent's shell tool runs it: not a terminal, so plain text. */
function harness(d: IsolatedDaemon, pane: string, args: string[], extra: Record<string, string> = {}): Promise<{ code: number; out: string; err: string }> {
  return new Promise((done) => {
    const child = spawn(process.execPath, ['--import', 'tsx', 'src/cli.ts', ...args], {
      cwd: CLI_ROOT, env: { ...d.env, TMUX_PANE: pane, ...extra }, stdio: ['ignore', 'pipe', 'pipe'],
    })
    let out = '', err = ''
    child.stdout.on('data', (chunk) => { out += chunk })
    child.stderr.on('data', (chunk) => { err += chunk })
    child.on('close', (code) => done({ code: code ?? -1, out, err }))
  })
}

/** `harness mcp` as an MCP client starts it: requests in on stdin, answers by id from stdout. */
function mcp(d: IsolatedDaemon, extra: Record<string, string> = {}) {
  const child = spawn(process.execPath, ['--import', 'tsx', 'src/cli.ts', 'mcp'], {
    cwd: CLI_ROOT, env: { ...d.env, TMUX_PANE: '', ...extra }, stdio: ['pipe', 'pipe', 'pipe'],
  })
  const waiting = new Map<number, (reply: Record<string, any>) => void>()
  createInterface({ input: child.stdout }).on('line', (line) => {
    const reply = JSON.parse(line)
    waiting.get(reply.id)?.(reply)
  })
  let next = 1
  return {
    request(method: string, params: Record<string, unknown> = {}): Promise<Record<string, any>> {
      const id = next++
      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
      return new Promise((done) => waiting.set(id, done))
    },
    notify(method: string): void { child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method })}\n`) },
    async call(name: string, args: Record<string, unknown>): Promise<{ text: string; isError: boolean }> {
      const reply = await this.request('tools/call', { name, arguments: args })
      return { text: reply.result.content.map((c: { text: string }) => c.text).join('\n'), isError: reply.result.isError === true }
    },
    close(): void { child.stdin.end() },
  }
}

/** The account's agent experiments as [d] keeps them (lib/agentSettings.ts), once it has read them. */
const kept = (d: IsolatedDaemon, want: (settings: Record<string, unknown>) => boolean = () => true) => until('the account\'s experiments to be kept', () => {
  try {
    const settings = JSON.parse(readFileSync(join(d.dataDir, 'agent-settings.json'), 'utf8')) as Record<string, unknown>
    return want(settings) ? settings : null
  } catch { return null }
}, 30_000, 200)

describe('Harness for agents, end to end', () => {
  let daemon: IsolatedDaemon | undefined
  let backend: FakeBackend | undefined
  afterEach(async () => {
    await daemon?.close(); daemon = undefined
    await backend?.close(); backend = undefined
  })
  /** A daemon signed in to the fake backend, whose account has [experiments] on, read and kept before the test goes on. */
  const signedIn = async (experiments: Record<string, boolean>, options: { trustPrompt?: boolean; before?: (d: IsolatedDaemon) => void; env?: Record<string, string> } = {}) => {
    const relay = await FakeBackend.start()
    backend = relay
    relay.addMachine(ME)
    relay.agentMessages = { revision: 1, machines: [{ machineId: ME.machineId, name: 'studio' }], tabs: [] }
    Object.assign(relay.experiments, experiments)
    const d = await IsolatedDaemon.create({ trustPrompt: options.trustPrompt, env: {
      BACKEND_WS_URL: relay.wsUrl, WEB_URL: relay.httpUrl, ADAPTER_COMPUTER_ID: ME.computerId,
      HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000', ...options.env,
    } })
    daemon = d
    onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-200).join('\n')}`) })
    signIn(d)
    options.before?.(d)
    await d.start()
    await kept(d, (settings) => Object.entries(experiments).every(([feature, on]) => settings[{ agents_start_agents: 'agentsStartAgents', agent_pull_request_line: 'pullRequestLine', agent_messages: 'agentMessages' }[feature]!] === on))
    return { relay, d }
  }

  it('an agent sees, starts, waits for, reads and closes a harness of its own, and may not message it outside a shared tab', async () => {
    const { d } = await signedIn({ agents_start_agents: true, agent_messages: true })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })

    const leadDir = join(d.projectsDir, 'lead')
    mkdirSync(leadDir, { recursive: true })
    const made = await client.request('agent_create', { engine: 'claude', cwd: leadDir, bypassPermission: true, name: 'lead' }, 90_000)
    expect(made.error, JSON.stringify(made)).toBeUndefined()
    const lead = await until('lead to bind its conversation', async () => {
      const row = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.id === made.agent.id)
      return row?.sessionId && row.status === 'active' ? row : null
    }, 60_000, 500)
    const run = (...args: string[]) => harness(d, String(lead.tmuxPane), args)

    // It sees itself.
    const ps = await run('ps')
    expect(ps.code, ps.err).toBe(0)
    expect(ps.out).toMatch(/^You: Claude Code "lead" \(/)
    expect(ps.out).toMatch(/\nlead +Claude Code +\w+ +person \(you\)/)

    // A terminal is the person's: no verb here lists one, so the agent could never read or close it. Refused, none made.
    const shell = await run('new', 'terminal', '--', 'npm run dev')
    expect(shell.code, shell.out).toBe(1)
    expect(shell.err).toContain('An agent cannot start a terminal')
    expect((await client.request<{ agents: unknown[] }>('agents_list', {}, 30_000)).agents).toHaveLength(1)

    // It starts a harness with a task, which reads who sent it, in a project Harness makes for it.
    const started = await run('new', 'claude', 'kid', '--name', 'kid', '--', 'hello kid')
    expect(started.code, started.err).toBe(0)
    expect(started.out).toContain(`kid on this computer: starting. Claude Code, in ${join(d.env.HOME!, 'harnesses', 'kid')}.`)
    expect(started.out).toContain('Next: harness wait kid  (until it has answered; then read it: harness show kid)')
    expect(started.out).not.toContain('harness send')
    // Started lines: a create the machine answers pending first also writes a pending one (agentClient/ledger.ts).
    const ledger = readFileSync(join(d.dataDir, 'agent-client', 'started.jsonl'), 'utf8').trim().split('\n').map((line) => JSON.parse(line)).filter((row) => row.child)
    expect(ledger).toEqual([expect.objectContaining({ depth: 1, by: expect.objectContaining({ agentId: lead.id, name: 'lead' }), child: expect.objectContaining({ name: 'kid' }) })])

    // It waits for it, then reads its answer.
    const waited = await run('wait', 'kid', '--timeout', '2m')
    expect(waited.code, waited.out + waited.err).toBe(0)
    expect(waited.out.trim()).toBe('kid: idle · read it: harness show kid')
    const shown = await run('show', 'kid')
    expect(shown.code, shown.err).toBe(0)
    expect(shown.out).toMatch(/^kid on .+: idle · Claude Code · started by you\n/)
    expect(shown.out).toContain('asked: [from lead · Claude Code · ')
    expect(shown.out).toContain('the harness that started you. It reads your answer itself.]')
    expect(shown.out).not.toContain('harness send')
    expect(shown.out).toContain('hello kid')
    expect((await run('ps')).out).toMatch(/\nkid +Claude Code +\w+ +you /)

    // They share no tab: neither messages the other, either way, as for any two harnesses, though the account has Agent
    // Messages on. Since #1180 the two messaged each other with no tab, and the owner found agents talking before
    // turning Agent Messages on.
    const off = 'No other harness is in this tab. The person puts harnesses in one tab for them to message each other.'
    const sent = await run('send', 'kid', 'Also check the footer.')
    expect(sent.code, sent.out + sent.err).toBe(1)
    expect(sent.err).toContain(off)
    const kid = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.name === 'kid')!
    // The windows open it beside the harness that started it, and say so in its header: its frame names that harness,
    // in the list and in the push a window first sees it by (desktop `Agent.parentAgentId`). The person's has none.
    expect(kid.parentAgentId).toBe(lead.id)
    expect(lead.parentAgentId).toBeNull()
    expect(client.frames.some((f) => f.type === 'agent_synced' && f.payload?.agent?.id === kid.id && f.payload.agent.parentAgentId === lead.id)).toBe(true)
    const back = await harness(d, String(kid.tmuxPane), ['send', 'lead', 'Footer checked.'])
    expect(back.code, back.out + back.err).toBe(1)
    expect(back.err).toContain(off)
    // Nor does `harness send` alone name the other.
    const listed = await harness(d, String(kid.tmuxPane), ['send'])
    expect(listed.code, listed.err).toBe(0)
    expect(listed.out.trim()).toBe('No teammates in this tab yet.')

    // It closes what it started, and only that; the harness it started may not close it.
    const own = await run('close', 'lead')
    // Refused, not failed: exit 5.
    expect(own.code).toBe(5)
    expect(own.err).toContain('That is your own harness.')
    const fromKid = await harness(d, String(kid.tmuxPane), ['close', 'lead'])
    expect(fromKid.code, fromKid.out).toBe(5)
    expect(fromKid.err).toContain('You did not start lead')
    await run('wait', 'kid', '--timeout', '2m')
    const closed = await run('close', 'kid')
    expect(closed.code, closed.err).toBe(0)
    expect(closed.out.trim()).toMatch(/^kid on .+: closed\. Its conversation is kept; the person can resume it\.\nNext: nothing; you have 0 open of 4\.$/)
    const after = await run('ps', '--all', '--json')
    expect(JSON.parse(after.out).harnesses).toEqual(expect.arrayContaining([expect.objectContaining({ name: 'kid', state: 'stopped', startedBy: 'you' })]))

    // The same through `harness mcp` run in its pane (`harness_start`), as Claude Code with the plugin does.
    const server = mcp(d, { TMUX_PANE: String(lead.tmuxPane) })
    await server.request('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'claude-code', version: '1' } })
    server.notify('notifications/initialized')
    const viaMcp = await server.call('harness_start', { task: 'hello from the pane', project: 'pane-kid', name: 'panekid' })
    expect(viaMcp.isError, viaMcp.text).toBe(false)
    const paneKid = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.name === 'panekid')
    expect(paneKid?.parentAgentId).toBe(lead.id)
    server.close()
    client.close()
  })

  it('a harness another agent started may not start more, is closed with its starter, and is the person\'s once they type into it', async () => {
    // Owner, October 12: "we need to be very careful about when to start a new agent so we don't waste user token and we
    // need to properly clean up after too". The cleanup runs in its own process here, as it does by default (the edge
    // host): what the core tells it and what it asks back cross the link.
    const { d, relay } = await signedIn({ agents_start_agents: true })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const list = async (includeStopped = false) => (await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped }, 30_000)).agents
    const lead = async (name: string) => {
      const dir = join(d.projectsDir, name)
      mkdirSync(dir, { recursive: true })
      const made = await client.request('agent_create', { engine: 'claude', cwd: dir, bypassPermission: true, name }, 90_000)
      expect(made.error, JSON.stringify(made)).toBeUndefined()
      const bound = await until(`${name} to bind its conversation`, async () => {
        const row = (await list()).find((a) => a.id === made.agent.id)
        return row?.sessionId && row.status === 'active' ? row : null
      }, 60_000, 500)
      // One turn of the person's first: a close saves a conversation, and one with nothing in it yet has none to save.
      const from = client.frames.length
      client.send('message', { agentId: bound.id, content: `hello ${name}` })
      const opened = await client.waitFor((f) => f.type === 'turn_started' && f.agentId === bound.id, 60_000, `${name}'s first turn`, from)
      await client.waitFor((f) => f.type === 'turn_ended' && f.agentId === bound.id, 60_000, `${name}'s first turn to end`, client.frames.indexOf(opened) + 1)
      return bound
    }
    const start = async (from: Record<string, any>, name: string) => {
      const started = await harness(d, String(from.tmuxPane), ['new', 'claude', name, '--name', name, '--', `hello ${name}`])
      expect(started.code, started.out + started.err).toBe(0)
      return until(`${name} to run`, async () => (await list()).find((a) => a.name === name && a.status === 'active' && a.tmuxPane) ?? null, 60_000, 500)
    }
    const stateOf = async (agent: Record<string, any>) => (await list(true)).find((a) => a.id === agent.id)?.status

    const first = await lead('lead')
    const kid = await start(first, 'kid')

    // One level down: the harness lead started may not start one itself, and nothing is started.
    const deeper = await harness(d, String(kid.tmuxPane), ['new', 'claude', 'deeper', '--name', 'deeper', '--', 'hello deeper'])
    expect(deeper.code, deeper.out).toBe(5)
    expect(deeper.err.trim()).toBe('A harness another agent started may not start harnesses itself. Do the work yourself, or say in your answer what else is needed.')
    expect((await list(true)).some((a) => a.name === 'deeper')).toBe(false)

    // Lead reads its answer, and is told to close it; `ps` counts what it has open.
    const waited = await harness(d, String(first.tmuxPane), ['wait', 'kid', '--timeout', '2m'])
    expect(waited.code, waited.out + waited.err).toBe(0)
    const shown = await harness(d, String(first.tmuxPane), ['show', 'kid'])
    expect(shown.out.trim().split('\n').at(-1)).toBe('Next: harness close kid  (once you have what you need)')
    const ps = await harness(d, String(first.tmuxPane), ['ps'])
    expect(ps.out.trim().split('\n').at(-1)).toBe('Next: harness show kid  (read its answer, then close it: harness close kid)')

    // A second lead with two: the person types into one of them, from a window.
    const second = await lead('lead2')
    const joined = await start(second, 'joined')
    const left = await start(second, 'left')
    const shared = await start(second, 'shared')
    relay.superTabs = overOldRoutes(async (_method, raw) => {
      const path = new URL(raw, relay.httpUrl).pathname
      return { data: path === `/api/super-tabs/hosts/${ME.machineId}`
        ? [{ tabId: 'retained-team', agent: { id: 'shared-member', harnessId: shared.id, machineId: ME.machineId }, observers: [] }]
        : [] }
    })
    expect(await client.request('super_tabs', { action: 'wake' })).toMatchObject({ ok: true })
    await until('the team host to retain its member', () => retainedHarnesses(d.dataDir).has(shared.id) || null, 10_000, 100)
    client.send('message', { agentId: joined.id, content: 'hello from the person' })

    // The app closes lead, as a pane's close does (`agent_close`): kid closes with it.
    const closed = await client.request('agent_close', { agentId: first.id, sessionId: first.sessionId, createdAt: first.createdAt, mode: 'now' }, 60_000)
    expect(closed, JSON.stringify(closed)).toMatchObject({ closed: true })
    await until('kid to close with lead', async () => (await stateOf(kid)) === 'stopped' || null, 60_000, 500)
    // A window closing the tab both are in closes kid's pane next, a moment later: closed, not "it changed".
    const again = await client.request('agent_close', { agentId: kid.id, sessionId: kid.sessionId, createdAt: kid.createdAt, mode: 'idle' }, 60_000)
    expect(again, JSON.stringify(again)).toMatchObject({ closed: true })

    // The person closes lead2 from a terminal: the one they typed into stays, the other closes.
    const byPerson = await harness(d, '', ['close', 'lead2', '--now'])
    expect(byPerson.code, byPerson.out + byPerson.err).toBe(0)
    await until('left to close with lead2', async () => (await stateOf(left)) === 'stopped' || null, 60_000, 500)
    expect(await stateOf(joined)).toBe('active')
    expect(await stateOf(shared)).toBe('active')
    // One line for each close.
    expect(d.log()).toMatch(/\[agent-cleanup\] closed kid \(\w+\): the harness that started it was closed\. Its conversation is kept\./)
    expect(d.log()).toMatch(/\[agent-cleanup\] closed left \(\w+\): the harness that started it was closed\./)
    expect(d.log()).not.toMatch(/\[agent-cleanup\] closed joined/)
    expect(d.log()).not.toMatch(/\[agent-cleanup\] closed shared/)
    client.close()
  })

  // HARNESS_SWARM=off (the review of #1765): the agent cleanup, in the edge host, is handed none of the Swarm, and a harness
  // the Swarm's saved roster names is closed with its starter as any other. On, the test above keeps it (`shared`).
  it('with the Swarm off, a harness the Swarm\'s saved roster keeps is closed with its starter, as any other', async () => {
    const { d } = await signedIn({ agents_start_agents: true }, { env: { HARNESS_SWARM: 'off' } })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const list = async () => (await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents
    const dir = join(d.projectsDir, 'lead')
    mkdirSync(dir, { recursive: true })
    const made = await client.request('agent_create', { engine: 'claude', cwd: dir, bypassPermission: true, name: 'lead' }, 90_000)
    expect(made.error, JSON.stringify(made)).toBeUndefined()
    const lead = await until('lead to bind its conversation', async () => {
      const row = (await list()).find((a) => a.id === made.agent.id)
      return row?.sessionId && row.status === 'active' ? row : null
    }, 60_000, 500)
    const from = client.frames.length
    client.send('message', { agentId: lead.id, content: 'hello lead' })
    await client.waitFor((f) => f.type === 'turn_ended' && f.agentId === lead.id, 60_000, 'lead\'s first turn to end', from)
    const started = await harness(d, String(lead.tmuxPane), ['new', 'claude', 'kept', '--name', 'kept', '--', 'hello kept'])
    expect(started.code, started.out + started.err).toBe(0)
    const kept = await until('kept to run', async () => (await list()).find((a) => a.name === 'kept' && a.status === 'active' && a.tmuxPane) ?? null, 60_000, 500)
    // What the Swarm's host would have kept here had it run: its retention names the harness as a Super Tab member.
    retainContributions(d.dataDir, ME.machineId, [{ tabId: 'retained-team', agent: { harnessId: kept.id, machineId: ME.machineId } }])
    expect(retainedHarnesses(d.dataDir).has(kept.id)).toBe(true)
    const closed = await client.request('agent_close', { agentId: lead.id, sessionId: lead.sessionId, createdAt: lead.createdAt, mode: 'now' }, 60_000)
    expect(closed, JSON.stringify(closed)).toMatchObject({ closed: true })
    await until('kept to close with lead', async () => (await list()).find((a) => a.id === kept.id)?.status === 'stopped' || null, 60_000, 500)
    expect(d.log()).toMatch(/\[agent-cleanup\] closed kept \(\w+\): the harness that started it was closed\./)
    expect(d.log()).not.toMatch(/\[harnessd\] service superTabs started/)
    client.close()
  })

  it('signed out, the person starts, waits for, reads and closes a harness from a terminal', async () => {
    // Never signed in: the daemon runs as this computer (core/main.ts), and the app made harnesses while `harness new`
    // refused with "This computer is not signed in to Harness".
    const d = await IsolatedDaemon.create()
    daemon = d
    onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
    await d.start()
    const dir = join(d.projectsDir, 'solo')
    mkdirSync(dir, { recursive: true })
    const run = (...args: string[]) => harness(d, '', args)

    const started = await run('new', 'claude', dir, '--name', 'solo', '--', 'hello solo')
    expect(started.code, started.out + started.err).toBe(0)
    expect(started.out).toContain('Created solo on this computer')
    const waited = await run('wait', 'solo', '--timeout', '2m')
    expect(waited.code, waited.out + waited.err).toBe(0)
    const shown = await run('show', 'solo')
    expect(shown.code, shown.err).toBe(0)
    expect(shown.out).toContain('hello solo')
    // The person's task, as they typed it: no header.
    expect(shown.out).not.toContain('[from')
    const closed = await run('close', 'solo')
    expect(closed.code, closed.err).toBe(0)
    // What agents may do is the account's: signed out every switch is off, and there is none to turn on.
    const listed = await run('settings')
    expect(listed.code, listed.err).toBe(0)
    expect(listed.out).toMatch(/^agents-start-agents +off /m)
    expect(listed.out).toContain('Signed out: these are experiments of your account. Sign in (harness login) to turn them on.')
    const refused = await run('settings', 'agents-start-agents', 'on')
    expect(refused.code).toBe(1)
    expect(refused.err.trim()).toBe('Sign in to Harness to change this: what agents may do is an experiment of your account (Settings ▸ Experimental).')
  })

  it('an agent outside Harness starts, reads and closes a harness of its own, and may not close the person\'s', async () => {
    const { d } = await signedIn({ agents_start_agents: true })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const personDir = join(d.projectsDir, 'person')
    mkdirSync(personDir, { recursive: true })
    const theirs = await client.request('agent_create', { engine: 'claude', cwd: personDir, bypassPermission: true, name: 'theirs' }, 90_000)
    expect(theirs.error, JSON.stringify(theirs)).toBeUndefined()
    // Claude Code in a terminal app: no pane, and the session its shell names.
    const run = (...args: string[]) => harness(d, '', args, { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'outside-session' })

    const ps = await run('ps')
    expect(ps.code, ps.err).toBe(0)
    expect(ps.out.split('\n')[0]).toMatch(/^You: Claude Code, outside Harness, on .+\. Nothing can message you here\.$/)
    const started = await run('new', 'claude', 'helper', '--name', 'helper', '--', 'check it')
    expect(started.code, started.out + started.err).toBe(0)
    // Nothing can message an agent with no pane: no `send` in what to do next.
    expect(started.out).toContain('Next: harness wait helper  (until it has answered; then read it: harness show helper)')
    // No pane to open it beside.
    expect(started.out).toContain('The person sees it in Harness.\n')
    expect(started.out).not.toContain('harness send')
    // Started lines: a create the machine answers pending first also writes a pending one (agentClient/ledger.ts).
    const ledger = readFileSync(join(d.dataDir, 'agent-client', 'started.jsonl'), 'utf8').trim().split('\n').map((line) => JSON.parse(line)).filter((row) => row.child)
    expect(ledger).toEqual([expect.objectContaining({ depth: 1, by: expect.objectContaining({ agentId: 'claude-code:outside-session', name: 'Claude Code' }), child: expect.objectContaining({ name: 'helper' }) })])
    // No harness started it, so no window has one to open it beside.
    const helper = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.name === 'helper')
    expect(helper).toMatchObject({ parentAgentId: null })

    const waited = await run('wait', 'helper', '--timeout', '2m')
    expect(waited.code, waited.out + waited.err).toBe(0)
    const shown = await run('show', 'helper')
    expect(shown.out).toContain('asked: [from Claude Code outside Harness · ')
    expect(shown.out).toContain('the agent that started you. It reads your answer itself.]')
    expect(shown.out).toContain('check it')

    const person = await run('close', 'theirs')
    expect(person.code).toBe(5)
    expect(person.err).toContain('You did not start theirs')
    // Another session of the same agent did not start it either.
    const other = await harness(d, '', ['close', 'helper'], { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'another-session' })
    expect(other.code).toBe(5)
    const closed = await run('close', 'helper')
    expect(closed.code, closed.err).toBe(0)
    client.close()
  })

  // Codex 0.162.1 in a clean macOS VM (2026-10-12): `harness close <it> --now` a second after `harness new` answered
  // "Conversation identity is held: the native control descriptor type is unavailable." and the harness kept working,
  // because for its first seconds every read of the Codex process was refused. The fake Codex holds such a descriptor
  // for as long, and its first hook is as late: until then nothing could bind its conversation, as there.
  it.each([
    ['binds its conversation a few seconds in', 6_000, /^pong on .+: closed\. Its conversation is kept; the person can resume it\.\nNext: nothing; you have 0 open of 4\.$/],
    ['never binds while the close waits', 120_000, /^pong on .+: closed\. It was still starting, so no conversation was kept\.\nNext: nothing; you have 0 open of 4\.$/],
  ] as const)('an agent closes a Codex it started a second ago, which %s', async (_, unboundMs, said) => {
    const module = pathToFileURL(join(CLI_ROOT, 'e2e', 'harness', 'fakeEngine.mjs')).href
    const { d } = await signedIn({ agents_start_agents: true }, { before: (d) => {
      const config = { ...d.engineConfig, unreadableDescriptorMs: unboundMs, firstHookDelayMs: unboundMs }
      writeFileSync(join(d.root, 'bin', 'codex'), `#!${process.execPath}\nimport(${JSON.stringify(module)}).then((m) => m.run('codex', ${JSON.stringify(config)}))\n`, { mode: 0o755 })
    } })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const run = (...args: string[]) => harness(d, '', args, { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'outside-session' })

    const started = await run('new', 'codex', 'pong', '--name', 'pong', '--', 'Reply with pong')
    expect(started.code, started.out + started.err).toBe(0)
    // The same start asked again is the same harness, started "just now", not "1 min ago".
    const again = await run('new', 'codex', 'pong', '--name', 'pong', '--', 'Reply with pong')
    expect(again.out + again.err).toContain('you started it just now')
    const row = async () => ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents).find((a) => a.name === 'pong')
    const live = await until('pong running', async () => { const r = await row(); return r?.status === 'active' && r.tmuxPane ? r : null }, 60_000, 250)
    await new Promise((resolve) => setTimeout(resolve, 1_000))
    const closed = await run('close', 'pong', '--now')
    expect(closed.err).not.toMatch(/descriptor|identity is held/)
    expect(closed.code, closed.out + closed.err).toBe(0)
    expect(closed.out.trim()).toMatch(said)
    const stopped = await until('pong stopped', async () => { const r = await row(); return !r || r.status === 'stopped' ? r ?? {} : null }, 30_000, 250)
    if (unboundMs < 10_000) expect(stopped.sessionId).toBeTruthy()
    expect(await enginesIn(d, String(live.tmuxPane))).toBe('')
    // It closed it itself: `wait` says so, and is not a failure.
    const waited = await run('wait', 'pong', '--timeout', '30s')
    expect(waited.out.trim()).toBe('pong: closed (you closed it)')
    expect(waited.code, waited.out + waited.err).toBe(0)
    client.close()
  }, 180_000)

  it('an agent that uses MCP does the same through harness mcp', async () => {
    const { d } = await signedIn({ agents_start_agents: true })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const personDir = join(d.projectsDir, 'person')
    mkdirSync(personDir, { recursive: true })
    const theirs = await client.request('agent_create', { engine: 'claude', cwd: personDir, bypassPermission: true, name: 'theirs' }, 90_000)
    expect(theirs.error, JSON.stringify(theirs)).toBeUndefined()
    // An editor's agent: nothing in its environment says whose session it is, so the server does.
    const server = mcp(d)
    const hello = await server.request('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'cursor', version: '1' } })
    expect(hello.result).toMatchObject({ protocolVersion: '2025-06-18', serverInfo: { name: 'harness' } })
    expect(hello.result.instructions).toContain('Never give work to, or close, a harness you did not start')
    server.notify('notifications/initialized')
    const tools = (await server.request('tools/list')).result.tools.map((t: { name: string }) => t.name)
    expect(tools).toEqual(['harness_whoami', 'harness_list', 'harness_search', 'harness_machines', 'harness_start', 'harness_wait', 'harness_read', 'harness_close'])

    // An empty folder of its own: refused, with the project it can ask for instead.
    const scratch = join(d.root, 'tmp', 'mcp-scratch')
    mkdirSync(scratch, { recursive: true })
    const scratchRefused = await server.call('harness_start', { task: 'hello from mcp', folder: scratch, name: 'mcpkid' })
    expect(scratchRefused).toEqual({ isError: true, text: `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_start (project: "mcpkid", …)  (Harness makes ~/harnesses/mcpkid, '
      + 'which needs no approval). Nothing was started.' })
    const started = await server.call('harness_start', { task: 'hello from mcp', project: 'mcp-kid', name: 'mcpkid' })
    expect(started.isError, started.text).toBe(false)
    expect(started.text).toContain(`mcpkid on this computer: starting. Claude Code, in ${join(d.env.HOME!, 'harnesses', 'mcp-kid')}.`)
    // Its next steps are named as the tools: an MCP client may have no shell to run `harness show` in.
    expect(started.text).toContain('Next: harness_wait (names: "mcpkid")  (until it has answered; then read it: harness_read (name: "mcpkid"))')
    // Started lines: a create the machine answers pending first also writes a pending one (agentClient/ledger.ts).
    const ledger = readFileSync(join(d.dataDir, 'agent-client', 'started.jsonl'), 'utf8').trim().split('\n').map((line) => JSON.parse(line)).filter((row) => row.child)
    expect(ledger).toEqual([expect.objectContaining({ by: expect.objectContaining({ agentId: expect.stringMatching(/^agent:cursor:mcp-\d+$/), name: 'Cursor' }) })])
    const waited = await server.call('harness_wait', { names: ['mcpkid'], timeout_seconds: 120 })
    expect(waited).toEqual({ text: 'mcpkid: idle · read it: harness_read (name: "mcpkid")', isError: false })
    const read = await server.call('harness_read', { name: 'mcpkid' })
    expect(read.text).toContain('asked: [from Cursor outside Harness · ')
    expect(read.text).toContain('hello from mcp')
    const listed = await server.call('harness_list', {})
    expect(listed.text.split('\n')[0]).toMatch(/^You: Cursor, outside Harness, on .+\. Nothing can message you here\.$/)
    expect(listed.text).toMatch(/\nmcpkid +Claude Code +\w+ +you /)
    const refused = await server.call('harness_close', { name: 'theirs' })
    // A refusal is an answer, not an error to retry.
    expect(refused).toEqual({ text: 'You did not start theirs, so you may not close it. Only the person can.', isError: false })
    const closed = await server.call('harness_close', { name: 'mcpkid' })
    expect(closed.isError).toBe(false)
    expect(closed.text).toMatch(/^mcpkid on .+: closed\. Its conversation is kept; the person can resume it\.\nNext: nothing; you have 0 open of 4\.$/)
    server.close()
    client.close()
  })

  it('once Harness runs, Claude Code and Codex here run its commands and MCP tools without asking, the person\'s own rules kept', async () => {
    // Owner, 2026-10-12: "no asking. just do. the best ux." Codex asked before every verb (its sandbox cannot reach
    // the daemon), about four times a hand-off. The daemon writes the rules into the person's own settings at start
    // (docs/design/2026-10-11-agent-client.md, No permission prompts); what an agent may do stays Harness's to decide.
    const d = await IsolatedDaemon.create()
    daemon = d
    onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
    const settings = join(d.env.HOME!, '.claude', 'settings.json'), rules = join(d.env.CODEX_HOME!, 'rules', 'harness.rules')
    mkdirSync(join(d.env.HOME!, '.claude'), { recursive: true })
    writeFileSync(settings, JSON.stringify({ permissions: { allow: ['Bash(npm test:*)'], deny: ['Bash(harness close:*)'] } }))
    await d.start()
    await until('Harness to allow its commands in Claude Code and Codex', () => existsSync(rules)
      && readFileSync(settings, 'utf8').includes('mcp__plugin_harness_harness__harness_send'), 30_000)
    const tools = { whoami: 'harness_whoami', ps: 'harness_list', search: 'harness_search', machines: 'harness_machines', show: 'harness_read', wait: 'harness_wait', new: 'harness_start', close: 'harness_close', send: 'harness_send' }
    const verbs = Object.keys(tools) as Array<keyof typeof tools>, launcher = join(d.env.HOME!, '.local', 'bin', 'harness')
    // The person's deny of `harness close` is theirs: no allow for it in either spelling (Claude Code does not count the
    // launcher's path as the same command). Its MCP tool is another tool, and is allowed by name. `harness --help`,
    // which every harness reads as it starts, comes first: it names no verb (#1239, which left this list as it was,
    // so this test failed on main from then on).
    expect(JSON.parse(readFileSync(settings, 'utf8')).permissions).toEqual({
      allow: ['Bash(npm test:*)', 'Bash(harness --help)', 'Bash(harness -h)', `Bash(${launcher} --help)`, ...verbs.flatMap((verb) => [
        ...(verb === 'close' ? [] : [`Bash(harness ${verb}:*)`, `Bash(${launcher} ${verb}:*)`]),
        `mcp__harness__${tools[verb]}`, `mcp__plugin_harness_harness__${tools[verb]}`,
      ])],
      deny: ['Bash(harness close:*)'],
    })
    // Codex: each verb runs outside the sandbox on its first try, by name or by the launcher's path (which Codex reads
    // as `harness` only for that path); a file Harness owns.
    const list = JSON.stringify(verbs).replace(/,/g, ', ')
    const written = readFileSync(rules, 'utf8').split('\n').filter((line) => line && !line.startsWith('#'))
    expect(written).toHaveLength(3)
    expect(written[0]).toBe(`host_executable(name="harness", paths=[${JSON.stringify(launcher)}])`)
    expect(written[1]).toBe(`prefix_rule(pattern=["harness", ${list}], decision="allow")`)
    expect(written[2]).toMatch(new RegExp(`^prefix_rule\\(pattern=\\["[^"]+", "[^"]+/cli\\.js", ${list.replace(/[[\]]/g, '\\$&')}\\], decision="allow"\\)$`))
    expect(statSync(rules).mode & 0o777).toBe(0o600)
  })

  it('an agent is told, not left waiting, when Claude Code or Codex would ask the person to trust its folder', 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: the agent could only report that it was waiting (a clean
    // VM, CLI 0.3.75, 2026-10-11). The fake engines ask as the real ones do, of a folder their settings do not trust.
    // Both engines have run here before: their settings exist, which is when Harness adds the folders it makes.
    const { d } = await signedIn({ agents_start_agents: true }, { trustPrompt: true, before: (d) => {
      writeFileSync(join(d.env.HOME!, '.claude.json'), '{}')
      appendFileSync(join(d.env.CODEX_HOME!, 'config.toml'), '')
    } })
    // Codex in a terminal app: no pane, the session its shell names.
    const run = (...args: string[]) => harness(d, '', args, { CODEX_THREAD_ID: 'lead-thread' })

    // An empty folder of its own: refused before anything starts, with what to run instead.
    const scratch = join(d.root, 'tmp', 'shell-opinion.e0ynGN')
    mkdirSync(scratch, { recursive: true })
    const refused = await run('new', 'claude', scratch, '--name', 'opinion', '--', 'a second opinion on the shell script')
    expect(refused.code, refused.out).toBe(1)
    expect(refused.err.trim()).toBe(`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(JSON.parse((await run('ps', '--json')).out).harnesses).toEqual([])

    // The project it names instead: Harness makes it, answers the question for it, and the work is done with nobody asked.
    const started = await run('new', 'claude', 'opinion', '--name', 'opinion', '--', 'a second opinion on the shell script')
    expect(started.code, started.out + started.err).toBe(0)
    expect(started.out).toContain(`opinion on this computer: starting. Claude Code, in ${join(d.env.HOME!, 'harnesses', 'opinion')}.`)
    expect(started.out).not.toContain('trust')
    const waited = await run('wait', 'opinion', '--timeout', '2m')
    expect(waited.out.trim(), waited.err).toBe('opinion: idle · read it: harness show opinion')
    expect((await run('show', 'opinion')).out).toContain('a second opinion on the shell script')

    // A folder with something in it may be just what the work needs: it starts, and the agent is told it waits for the person.
    const work = join(d.root, 'work')
    mkdirSync(work, { recursive: true })
    writeFileSync(join(work, 'README.md'), 'the person\'s work\n')
    const asked = await run('new', 'codex', work, '--name', 'checker', '--', 'check the readme')
    expect(asked.code, asked.out + asked.err).toBe(0)
    expect(asked.out).toContain(`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 checker --name checker -- …')
    const held = await run('wait', 'checker', '--timeout', '2m')
    expect(held.code, held.out + held.err).toBe(3)
    expect(held.out.trim()).toMatch(/^checker: needs the person · /)
    expect((await run('close', 'opinion')).code).toBe(0)
  })

  it('an agent may not start a harness until the account turns that on, and is told how; the person turns it on from a terminal', async () => {
    // Every switch off by default (owner, 2026-10-12): signed in, with an account that never turned any on.
    const { relay, d } = await signedIn({})
    expect(await kept(d)).toMatchObject({ agentsStartAgents: false, pullRequestLine: false, agentMessages: false })
    // Claude Code in a terminal app, refused with where the person turns it on.
    const asAgent = { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'held-session' }
    const refused = await harness(d, '', ['new', 'claude', 'held', '--name', 'held', '--', 'hello'], asAgent)
    expect(refused.code, refused.out).toBe(5)
    expect(refused.err.trim()).toBe('Agents may not start harnesses: the person turns on "Agents can start other agents" in Harness Settings ▸ Experimental, or runs `harness settings agents-start-agents on`. Until then, do the work yourself.')
    expect(JSON.parse((await harness(d, '', ['ps', '--json'])).out).harnesses).toEqual([])
    // The person, at a terminal: written through this computer's daemon to the account, and kept here at once.
    const on = await harness(d, '', ['settings', 'agents-start-agents', 'on'])
    expect(on.code, on.err).toBe(0)
    expect(on.out.trim()).toBe('agents-start-agents is on for your account.')
    expect(relay.experiments).toEqual({ agents_start_agents: true })
    expect((await harness(d, '', ['settings'])).out).toMatch(/^agents-start-agents +on /m)
    const started = await harness(d, '', ['new', 'claude', 'held', '--name', 'held', '--', 'hello'], asAgent)
    expect(started.code, started.out + started.err).toBe(0)
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const held = await until('held to be up', async () => {
      const row = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.name === 'held')
      return row?.sessionId && row.status === 'active' ? row : null
    }, 60_000, 500)
    client.close()
    // Its pull request line is the account's other switch, still off: none.
    expect(await commandsIn(d, String(held.tmuxPane))).not.toContain('--settings')
    // Turned off on another computer: this one hears desk_changed, and refuses again.
    relay.setExperiment('agents_start_agents', false)
    await kept(d, (settings) => settings.agentsStartAgents === false)
    const again = await harness(d, '', ['new', 'claude', 'again', '--name', 'again', '--', 'hello'], asAgent)
    expect(again.code, again.out).toBe(5)
    expect(again.err).toContain('Settings ▸ Experimental')
  })

  it('keeps delegation instructions without PR attribution, even with an older account setting', async () => {
    const { d } = await signedIn({ agents_start_agents: true, agent_pull_request_line: true })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const live = (name: string) => until(`${name} to be up`, async () => {
      const row = ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents).find((a) => a.name === name)
      return row?.sessionId && row.status === 'active' ? row : null
    }, 60_000, 500)
    const folder = (name: string) => { const dir = join(d.projectsDir, name); mkdirSync(dir, { recursive: true }); return dir }

    // The person's own harness: no line.
    const made = await client.request('agent_create', { engine: 'claude', cwd: folder('lead'), bypassPermission: true, name: 'lead' }, 90_000)
    expect(made.error, JSON.stringify(made)).toBeUndefined()
    const lead = await live('lead')
    expect(await commandsIn(d, String(lead.tmuxPane))).not.toContain('--settings')
    // Every harness is told how to use Harness while the account lets agents start agents, the person's too.
    expect(await commandsIn(d, String(lead.tmuxPane))).toContain(`--append-system-prompt ${HARNESS_INSTRUCTIONS}`)
    const run = (...args: string[]) => harness(d, String(lead.tmuxPane), args)

    // An older account switch must not add attribution to a new Claude harness.
    expect((await run('new', 'claude', 'kid', '--name', 'kid', '--', 'hello kid')).code).toBe(0)
    const kid = await live('kid')
    const kidCommand = await commandsIn(d, String(kid.tmuxPane))
    expect(kidCommand).toContain(HARNESS_INSTRUCTIONS)
    expect(kidCommand).not.toContain('--settings')

    // Codex receives delegation instructions, without an instruction to mark PRs.
    expect((await run('new', 'codex', 'kidx', '--name', 'kidx', '--', 'hello kidx')).code).toBe(0)
    const kidx = await live('kidx')
    const codexCommand = await commandsIn(d, String(kidx.tmuxPane))
    expect(codexCommand).toContain(HARNESS_INSTRUCTIONS)
    expect(codexCommand).not.toContain('When you create or update a pull request')
    expect(codexCommand).not.toContain('Started by another agent')

    // Restarting a saved harness does not restore the removed attribution.
    const restarted = await client.request('agent_restart', { agentId: kid.id }, 90_000)
    expect(restarted.error, JSON.stringify(restarted)).toBeUndefined()
    await until('kid to come back with delegation instructions', async () => {
      const row = await live('kid')
      const command = row.tmuxPane ? await commandsIn(d, String(row.tmuxPane)) : ''
      if (!command.includes(HARNESS_INSTRUCTIONS)) return null
      expect(command).not.toContain('--settings')
      return row
    }, 60_000, 500)

    // Turned off by the person: the next one an agent starts has no line.
    const off = await harness(d, '', ['settings', 'pull-request-line', 'off'])
    expect(off.code, off.err).toBe(0)
    expect(off.out.trim()).toBe('pull-request-line is off for your account.')
    expect((await run('new', 'claude', 'quiet', '--name', 'quiet', '--', 'hello quiet')).code).toBe(0)
    const quiet = await live('quiet')
    const command = await commandsIn(d, String(quiet.tmuxPane))
    expect(command).toContain('hello quiet')
    expect(command).not.toContain('--settings')

    // Agents starting agents turned off: a harness is no longer told how.
    expect((await harness(d, '', ['settings', 'agents-start-agents', 'off'])).code).toBe(0)
    const alone = await client.request('agent_create', { engine: 'claude', cwd: folder('alone'), bypassPermission: true, name: 'alone' }, 90_000)
    expect(alone.error, JSON.stringify(alone)).toBeUndefined()
    const aloneRow = await live('alone')
    expect(await commandsIn(d, String(aloneRow.tmuxPane))).not.toContain('You are running in Harness')
    client.close()
  })
})

/** The fake engines still running in [pane]'s process tree, or '' once none is: a pane closed with them has no tree. */
async function enginesIn(d: IsolatedDaemon, pane: string): Promise<string> {
  const panes = await d.tmux.run('list-panes', '-a', '-F', '#{pane_id}').catch(() => '')
  if (!panes.split('\n').includes(pane)) return ''
  return (await commandsIn(d, pane)).split('\n').filter((line) => /^(?:codex|claude)\s/.test(line)).join('\n')
}

/** The command lines of the processes in [pane], as `ps` prints them: the engine's carries the arguments it was launched
 *  with (the fake engines' process title is their engine's name, then their arguments, as a CLI's is). */
async function commandsIn(d: IsolatedDaemon, pane: string): Promise<string> {
  const panes = (await d.tmux.run('list-panes', '-a', '-F', '#{pane_id} #{pane_pid}')).split('\n').map((line) => line.split(' '))
  const root = Number(panes.find(([id]) => id === pane)?.[1])
  const table = execFileSync('ps', ['-A', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' }).split('\n')
    .map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)).filter((match): match is RegExpMatchArray => !!match)
  const tree = new Set([root])
  for (let grew = true; grew;) {
    grew = false
    for (const [, pid, ppid] of table) if (tree.has(Number(ppid)) && !tree.has(Number(pid))) { tree.add(Number(pid)); grew = true }
  }
  return table.filter(([, pid]) => tree.has(Number(pid))).map(([, , , command]) => command).join('\n')
}