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.

10.0 KB
Raw Blame
/**
 * A guest's harness against an owner's, on a real Mac with guest access: the same program, run in the owner's tmux
 * as the owner and through the guest helper as a guest's own OS user (docs/plans/2026-10-19-guest-machine-sharing-plan.md).
 * A guest's harness runs differently, and each difference broke something on 2026-10-22 that nothing tested: Stop
 * was refused (the owner can neither read nor signal another user's process), and a Claude Code harness was named
 * "Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA" (the helper's `env -i` leaves it no TMUX, so it asked the terminal for graphics).
 *
 * Needs the installed helper (`harness` turns guest access on), its sudoers drop-in, and a guest user already made;
 * it makes none and changes none. Run: `RUN_REAL_GUEST_PARITY=1 npx vitest run src/lib/guestParity.real.spec.ts`.
 */
import { execFileSync } from 'node:child_process'
import { chmodSync, existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
import { userInfo } from 'node:os'
import { join } from 'node:path'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import { isolatedTmux, type IsolatedTmux } from '../testing/isolatedTmux.js'
import { GUEST_HELPER_PATH, guestHomeRoot, guestRunCommand } from './guestAccounts.js'
import { guestPaneCommand } from './guestPaneCommand.js'
import { checkPidRuntime } from './deleteAgentFallback.js'
import { processRows } from './processTable.js'
import { registry } from './registry.js'
import { stoppedAgents } from './stoppedAgents.js'
import { AgentRestartCoordinator } from './restartAgent.js'
import { createStopAgentService } from './stopAgentService.js'
import { TmuxBackend } from './tmuxBackend.js'
import { listPaneTitles } from './tmux.js'

const NODE = '/usr/local/lib/harness/node/bin/node'
const QUERY = 'Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA'
const guestUser = (() => {
  try {
    return readdirSync(guestHomeRoot()).find((name) => /^hg_[0-9a-f]{12}$/.test(name) && existsSync(join(guestHomeRoot(), name, 'work'))) ?? null
  } catch { return null }
})()
const ready = process.env.RUN_REAL_GUEST_PARITY === '1' && process.platform === 'darwin' && existsSync(GUEST_HELPER_PATH)
  && existsSync(NODE) && guestUser !== null
const real = ready ? describe : describe.skip

// What Claude Code does with its terminal, as seen on the shared Mac: it reports what it was given (here, the names of
// its environment), and asks a terminal it believes is not tmux whether it can show images.
const PROBE = [
  "process.stdout.write('ENV ' + JSON.stringify(Object.keys(process.env).sort()) + '\\n')",
  "if (!process.env.TMUX) process.stdout.write('\\x1b_" + QUERY + "\\x1b\\\\')",
  'setInterval(() => {}, 1 << 30)',
].join('\n')

real('a guest\'s harness against an owner\'s', () => {
  let server: IsolatedTmux
  let dir: string
  /** The variables a guest's Claude Code is given (guestPaneCommand). */
  let given: string[] = []
  const panes: Record<'owner' | 'guest', { pane: string; pid: number }> = {} as never
  const work = join(guestHomeRoot(), guestUser ?? '', 'work')

  const pidOf = async (pane: string): Promise<number> => {
    // The pane runs sudo for the guest (four of them, as root); the program is the one below it running the probe.
    // (By its arguments: macOS `ps` cuts the command name to 16 characters, `/usr/local/lib/h`.)
    const root = Number(await server.run('display', '-p', '-t', pane, '#{pane_pid}'))
    return vi.waitFor(async () => {
      const rows = (await processRows()) ?? []
      const below = (pid: number): number[] => rows.filter((r) => r.parentPid === pid).flatMap((r) => [r.pid, ...below(r.pid)])
      const found = [root, ...below(root)].map((pid) => rows.find((r) => r.pid === pid))
        .filter((r) => r && r.executable !== 'sudo' && r.args.includes(join(dir, 'probe.js')))
      if (!found.length) throw new Error(`no program yet below ${root}`)
      return found.at(-1)!.pid
    }, { timeout: 15_000, interval: 200 })
  }
  const userOf = (pid: number): string => execFileSync('ps', ['-o', 'user=', '-p', String(pid)], { encoding: 'utf8' }).trim()
  const envOf = async (pane: string): Promise<string[]> => vi.waitFor(async () => {
    const line = (await server.run('capture-pane', '-p', '-J', '-t', pane)).split('\n').find((l) => l.startsWith('ENV '))
    if (!line) throw new Error('no ENV line yet')
    return JSON.parse(line.slice(4)) as string[]
  }, { timeout: 15_000, interval: 200 })

  beforeAll(async () => {
    server = await isolatedTmux({ PATH: process.env.PATH, TERM: 'xterm-256color', LANG: 'en_US.UTF-8' })
    vi.stubEnv('TMUX', undefined)
    vi.stubEnv('TMUX_PANE', undefined)
    vi.stubEnv('TMUX_TMPDIR', server.root)
    // The guest reads the program from a folder every account may read; the owner's temporary folder is its own.
    dir = mkdtempSync('/tmp/guest-parity-')
    chmodSync(dir, 0o755)
    writeFileSync(join(dir, 'probe.js'), PROBE, { mode: 0o644 })
    const owner = await server.run('new-session', '-d', '-P', '-F', '#{pane_id}', '-s', 'parity', '-x', '200', '-y', '50',
      NODE, join(dir, 'probe.js'))
    // As a guest's Claude Code is started (guestPaneCommand, set on its pane as guestCreate does): the variables it is
    // given, through the helper, as the guest, in the guest's workspace. Only the program is the probe.
    const account = { user: guestUser!, home: join(guestHomeRoot(), guestUser!), workspace: work }
    const env = guestPaneCommand({ account, engine: 'claude', bypassPermission: true }).env
    given = Object.keys(env)
    const guest = guestRunCommand(guestUser!, work, env, [NODE, join(dir, 'probe.js')])
    const guestPane = await server.run('new-window', '-d', '-P', '-F', '#{pane_id}', '-t', 'parity', '-c', dir,
      ...Object.entries(guest.env).flatMap(([key, value]) => ['-e', `${key}=${value}`]), ...guest.argv)
    panes.owner = { pane: owner, pid: await pidOf(owner) }
    panes.guest = { pane: guestPane, pid: await pidOf(guestPane) }
  }, 60_000)

  afterAll(async () => {
    vi.unstubAllEnvs()
    await server?.close()
    if (dir) rmSync(dir, { recursive: true, force: true })
  })

  it('runs the guest\'s program as the guest\'s own user, the owner\'s as the owner', async () => {
    expect(userOf(panes.guest.pid)).toBe(guestUser)
    expect(userOf(panes.owner.pid)).toBe(userInfo().username)
  })

  it('tells the owner\'s engine it is in tmux, and the guest\'s nothing of the owner\'s terminal', async () => {
    const owner = await envOf(panes.owner.pane)
    const guest = await envOf(panes.guest.pane)
    // What tmux gives a pane: the owner's engine knows its terminal is tmux, and engines act on it (Claude Code does not
    // ask a tmux pane for graphics). The guest's is started with `env -i`: none of it, by design (the socket path is the
    // owner's). A change to either side shows here, to be decided for guests rather than found on a shared Mac.
    for (const key of ['TMUX', 'TMUX_PANE', 'TERM_PROGRAM']) {
      expect(owner, key).toContain(key)
      expect(guest, key).not.toContain(key)
    }
    // Exactly what it was given (guestPaneCommand: TERM, COLORTERM, LANG) and what starting as the guest
    // sets (measured: macOS 26, sudo -u … env -i), and nothing of the owner's.
    const login = ['HOME', 'LOGNAME', 'OLDPWD', 'PATH', 'PWD', 'SHELL', 'SHLVL', 'USER', '__CF_USER_TEXT_ENCODING']
    expect(guest).toEqual([...new Set([...given, ...login])].sort())
    // Known, and the plan's "Turn status": a guest's engine has no Harness hooks yet, so its turns are not reported
    // and its activity reads unknown. Giving it the guest-scoped hook token makes this fail: update it then.
    for (const key of ['HARNESS_HOOK_URL', 'HARNESS_HOOK_TOKEN', 'HARNESS_AGENT_ID']) expect(guest, key).not.toContain(key)
  })

  it('names both harnesses alike: the guest\'s graphics query is not a title', async () => {
    const raw = async (pane: string) => server.run('display', '-p', '-t', pane, '#{pane_title}')
    await vi.waitFor(async () => expect(await raw(panes.guest.pane)).toBe(QUERY), { timeout: 10_000, interval: 200 })
    expect(await raw(panes.owner.pane)).not.toBe(QUERY)
    const titles = await listPaneTitles()
    expect(titles.get(panes.guest.pane), 'the query names nothing').toBeUndefined()
    expect([...titles.values()]).not.toContain(QUERY)
  })

  it('stops both by their panes; only the owner\'s can be signalled', async () => {
    // The owner may signal its own process, and never a guest's: the guest's stop cannot be a signal.
    expect(() => process.kill(panes.owner.pid, 0)).not.toThrow()
    expect(() => process.kill(panes.guest.pid, 'SIGTERM')).toThrow(/EPERM/)
    // The daemon's own Stop on the guest's row, through tmux, as in production (stopAgentService's guest path).
    const row = (await processRows())!.find((r) => r.pid === panes.guest.pid)!
    const agent = registry.openPendingAgent({ engine: 'claude', cwd: work, runtimes: [{ backend: 'tmux', paneId: panes.guest.pane }] })!
    Object.assign(agent, { guest: '[email protected]', sessionId: '', processIdentity: { pid: row.pid, executable: row.executable, startMarker: row.startMarker } })
    const backend = new TmuxBackend()
    const stop = createStopAgentService({
      registry, stoppedAgents, restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(),
      backendFor: (runtime) => runtime.backend === 'tmux' ? backend : undefined,
      agentReconciler: { suppress: () => {}, holdRoute: () => {}, releaseRoute: () => {}, trigger: async () => {} },
      forgetSession: (id) => { registry.removeAgent(id) }, markDeleted: () => {}, clearDeleted: () => {},
      stopNative: async () => { throw new Error('a guest\'s engine is not this daemon\'s to unload') },
    })
    await stop(agent.agentId)
    expect((await checkPidRuntime({ engine: 'claude', processIdentity: agent.processIdentity })).state).toBe('gone')
    expect(registry.byAgent(agent.agentId)).toBeUndefined()
    // The owner's harness, its pane closed the same way, leaves as well.
    await server.run('kill-pane', '-t', panes.owner.pane)
    await vi.waitFor(() => expect(() => process.kill(panes.owner.pid, 0)).toThrow(/ESRCH/), { timeout: 10_000, interval: 200 })
  }, 60_000)
})