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.

19.5 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { describe, expect, it } from 'vitest'
import type { PtyHostDiscovery } from '../ptyHost/client.js'
import { endPtyHosts, HOST_EXIT_WAIT_MS, PANE_GRACE_MS, ptyHostsDeps, type HostClient, type PtyHostsDeps } from './ptyHosts.js'

const discovery = (pid: number, protocol = 2, instance = `p${protocol}`): PtyHostDiscovery => ({ protocol, instance, endpoint: 'e', pid, version: '0.5.0', token: 't' })
/** When the record was written, as it was read: after both rows' start markers below. */
const WRITTEN = Date.parse('Sun Oct 18 10:00:00 2026')
const rec = (pid: number, protocol = 2, written: number | null = WRITTEN, instance = `p${protocol}`) => ({ discovery: discovery(pid, protocol, instance), written })
const filetime = (ms: number) => `w:${(BigInt(ms) + 11_644_473_600_000n) * 10_000n}`

const WIN_HOME = 'C:\\Users\\u\\.harness\\adapters\\pty'
const WIN_EXE = 'C:\\Users\\u\\.harness\\runtime\\pty\\0.5.0\\harness-pty.exe'
const winRow = (overrides: Record<string, unknown> = {}) => ({ pid: 100, parentPid: 1, executable: WIN_EXE, startMarker: 'w:1', args: `"${WIN_EXE}" serve --home ${WIN_HOME} --history-limit 2000 --no-reexec`, ...overrides })
const UNIX_HOME = '/Users/u/.harness/adapters/pty'
const unixRow = (overrides: Record<string, unknown> = {}) => ({ pid: 100, parentPid: 1, executable: '/Users/u/.harness/runtime/pty/0.5.0/harness-pty', startMarker: 'Sat Oct 17 10:00:00 2026', args: `/Users/u/.harness/runtime/pty/0.5.0/harness-pty serve --home ${UNIX_HOME}`, ...overrides })

function host(panes: string[], options: { refuseFirstShutdown?: boolean; refuseShutdown?: boolean; exitsOnShutdown?: boolean; protocol?: number; inventoryFails?: boolean } = {}) {
  const calls: string[] = []
  let alive = true
  let refused = !options.refuseFirstShutdown
  const table = new Set(panes)
  const client: HostClient = {
    protocol: options.protocol ?? 2,
    pid: 100,
    close: () => { calls.push('close') },
    call: (async (op: { op: string; pane?: string }) => {
      calls.push(op.pane ? `${op.op} ${op.pane}` : op.op)
      if (op.op === 'inventory') {
        if (options.inventoryFails) return { state: 'failed', dispatch: 'rejected', code: 'internal', reason: 'the table is busy' }
        return { state: 'ok', value: { panes: [...table].map((pane) => ({ pane })) } }
      }
      if (op.op === 'kill') { table.delete(op.pane!); return { state: 'ok', value: {} } }
      if (op.op === 'shutdown') {
        if (options.refuseShutdown) return { state: 'failed', dispatch: 'rejected', code: 'bad_request', reason: 'host still has panes (1)' }
        if (!refused) { refused = true; table.add('%9'); return { state: 'failed', dispatch: 'rejected', code: 'bad_request', reason: 'host still has panes (1)' } }
        if (options.exitsOnShutdown !== false) alive = false
        return { state: 'ok', value: {} }
      }
      return { state: 'failed', dispatch: 'rejected', code: 'bad_request', reason: 'no' }
    }) as HostClient['call'],
  }
  return { client, calls, alive: () => alive, kill: () => { alive = false } }
}

function deps(h: ReturnType<typeof host> | null, overrides: Partial<PtyHostsDeps> = {}): { deps: PtyHostsDeps; slept: number[]; ended: string[] } {
  const slept: number[] = []
  const ended: string[] = []
  return {
    slept, ended,
    deps: {
      platform: 'win32',
      home: WIN_HOME,
      discover: () => [rec(100)],
      reach: async () => (h ? { client: h.client } : { unreachable: 'nothing answers' }),
      alive: (pid) => pid === 100 && (h ? h.alive() : true),
      dead: async () => false,
      rows: async () => [winRow()],
      terminate: async (pid, marker) => { ended.push(`${pid} ${marker}`); h?.kill(); return 'ended' },
      sleep: async (ms) => { slept.push(ms) },
      ...overrides,
    },
  }
}

const left = (detail: string, panes = 0) => [{ pid: 100, protocol: 2, panes, how: 'left', detail }]

describe('endPtyHosts', () => {
  it('kills each pane, gives them their grace, then shuts the host down', async () => {
    const h = host(['%1', '%2'])
    const t = deps(h)
    expect(await endPtyHosts(t.deps)).toEqual([{ pid: 100, protocol: 2, panes: 2, how: 'shut down' }])
    expect(h.calls).toEqual(['inventory', 'kill %1', 'kill %2', 'shutdown', 'close'])
    expect(t.slept).toContain(PANE_GRACE_MS)
    expect(t.ended).toEqual([])
  })

  it('goes round once more when a pane appeared before the shutdown', async () => {
    const h = host(['%1'], { refuseFirstShutdown: true })
    expect(await endPtyHosts(deps(h).deps)).toEqual([{ pid: 100, protocol: 2, panes: 2, how: 'shut down' }])
    expect(h.calls).toEqual(['inventory', 'kill %1', 'shutdown', 'inventory', 'kill %9', 'shutdown', 'close'])
  })

  it('ends an unreachable Windows host by its pid and start marker, and leaves a pid that is not a harness-pty', async () => {
    const t = deps(null)
    expect(await endPtyHosts(t.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
    expect(t.ended).toEqual(['100 w:1'])
    const other = deps(null, { rows: async () => [winRow({ executable: 'C:\\x\\notepad.exe', startMarker: 'w:2' })] })
    expect(await endPtyHosts(other.deps)).toEqual(left('nothing answers, and pid 100 is not a harness-pty process'))
    expect(other.ended).toEqual([])
  })

  it('leaves a harness-pty that serves another home, comparing a Windows home without case', async () => {
    const other = deps(null, { rows: async () => [winRow({ args: `"${WIN_EXE}" serve --home C:\\work\\b4\\pty --no-reexec` })] })
    expect(await endPtyHosts(other.deps)).toEqual(left(`nothing answers, and pid 100 is not the host of ${WIN_HOME}`))
    expect(other.ended).toEqual([])
    const noHome = deps(null, { rows: async () => [winRow({ args: `"${WIN_EXE}" ps --json` })] })
    expect((await endPtyHosts(noHome.deps))[0]!.how).toBe('left')
    const cased = deps(null, { rows: async () => [winRow({ args: `"${WIN_EXE}" serve --home "${WIN_HOME.toUpperCase()}\\" --no-reexec` })] })
    expect(await endPtyHosts(cased.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
    const native = deps(null, { rows: async () => [winRow({ args: '', nativeArgv: [WIN_EXE, 'serve', '--home', WIN_HOME] })] })
    expect((await endPtyHosts(native.deps))[0]!.how).toBe('ended')
  })

  it('leaves a harness-pty that started after its record was written, or whose record has no time', async () => {
    const later = deps(null, { rows: async () => [winRow({ startMarker: filetime(WRITTEN + 10_000) })] })
    expect(await endPtyHosts(later.deps)).toEqual(left('nothing answers, and pid 100 started after its record was written, so it is another process'))
    expect((await endPtyHosts(deps(null, { rows: async () => [winRow({ startMarker: filetime(WRITTEN + 1_000) })] }).deps))[0]!.how).toBe('ended')
    // Fail closed: no time for the record, or a start marker that does not read as a time, is no proof.
    const untimed = deps(null, { discover: () => [rec(100, 2, null)] })
    expect(await endPtyHosts(untimed.deps)).toEqual(left("nothing answers, and its record's time could not be read"))
    const unparsed = deps(null, { rows: async () => [winRow({ startMarker: 'soon' })] })
    expect(await endPtyHosts(unparsed.deps)).toEqual(left("nothing answers, and its record's time could not be read"))
    expect([...later.ended, ...untimed.ended, ...unparsed.ended]).toEqual([])
  })

  it('reports a host that exited between the table read and the kill as gone', async () => {
    let asked = 0
    const t = deps(null, { alive: () => asked++ < 1 })
    expect(await endPtyHosts(t.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'gone' }])
    expect(t.ended).toEqual([])
  })

  it('reads a --home value as a whole token: a further token after it is another path', async () => {
    const win = deps(null, { rows: async () => [winRow({ args: `"${WIN_EXE}" serve --home ${WIN_HOME} old` })] })
    expect(await endPtyHosts(win.deps)).toEqual(left(`nothing answers, and pid 100 is not the host of ${WIN_HOME}`))
    const unix = deps(null, { platform: 'linux', home: '/x/pty', rows: async () => [unixRow({ args: 'harness-pty serve --home /x/pty old' })] })
    expect(await endPtyHosts(unix.deps)).toEqual(left('nothing answers, and pid 100 is not the host of /x/pty'))
    expect([...win.ended, ...unix.ended]).toEqual([])
    const flagged = deps(null, { platform: 'linux', home: '/x/pty', alive: () => !flagged.ended.length, rows: async () => [unixRow({ args: 'harness-pty serve --home /x/pty --history-limit 2000' })] })
    expect((await endPtyHosts(flagged.deps))[0]!.how).toBe('ended')
  })

  it('leaves a host whose start time cannot be read, or that changed while it was being ended', async () => {
    const unread = deps(null, { rows: async () => null })
    expect(await endPtyHosts(unread.deps)).toEqual(left('nothing answers, and its start time could not be read'))
    const unmarked = deps(null, { rows: async () => [winRow({ startMarker: '' })] })
    expect(await endPtyHosts(unmarked.deps)).toEqual(left('nothing answers, and its start time could not be read'))
    expect([...unread.ended, ...unmarked.ended]).toEqual([])
    const changed = deps(null, { terminate: async () => 'mismatch' })
    expect(await endPtyHosts(changed.deps)).toEqual(left('nothing answers; pid 100 changed while it was being ended'))
    const vanished = deps(null, { terminate: async () => 'gone' })
    expect(await endPtyHosts(vanished.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'gone' }])
  })

  it('leaves a host proven dead or gone alone', async () => {
    expect(await endPtyHosts(deps(null, { dead: async () => true }).deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'gone' }])
    expect(await endPtyHosts(deps(null, { alive: () => false }).deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'gone' }])
  })

  it('on Unix, ends an unreachable host with the identity-checked SIGTERM, only once its row proves it is the host', async () => {
    let up = true
    const unix = deps(null, { platform: 'darwin', home: UNIX_HOME, alive: () => up, rows: async () => [unixRow()], terminate: async (pid, marker) => { unix.ended.push(`${pid} ${marker}`); up = false; return 'ended' } })
    expect(await endPtyHosts(unix.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
    expect(unix.ended).toEqual(['100 Sat Oct 17 10:00:00 2026'])
    // After a reboot the recorded pid may be any of the user's processes.
    const shell = deps(null, { platform: 'darwin', home: UNIX_HOME, rows: async () => [unixRow({ executable: '/bin/zsh', args: '-zsh' })] })
    expect(await endPtyHosts(shell.deps)).toEqual(left('nothing answers, and pid 100 is not a harness-pty process'))
    const later = deps(null, { platform: 'darwin', home: UNIX_HOME, rows: async () => [unixRow({ startMarker: 'Sun Oct 18 10:00:10 2026' })] })
    expect((await endPtyHosts(later.deps))[0]!.how).toBe('left')
    const elsewhere = deps(null, { platform: 'darwin', home: UNIX_HOME, rows: async () => [unixRow({ args: 'harness-pty serve --home /Users/u/other/pty' })] })
    expect(await endPtyHosts(elsewhere.deps)).toEqual(left(`nothing answers, and pid 100 is not the host of ${UNIX_HOME}`))
    // Unix paths keep their case.
    const cased = deps(null, { platform: 'linux', home: UNIX_HOME, rows: async () => [unixRow({ args: `harness-pty serve --home ${UNIX_HOME.toUpperCase()}` })] })
    expect((await endPtyHosts(cased.deps))[0]!.how).toBe('left')
    expect([...shell.ended, ...later.ended, ...elsewhere.ended, ...cased.ended]).toEqual([])
  })

  it("on macOS, reads the image from argv when ps cuts comm to 16 characters, but only when comm is the start of it", async () => {
    // Measured 2026-10-18: `ps -o comm=` shows `/Users/<user>/` and `pty/target/relea` for two hosts.
    const program = '/Users/John Doe/.harness/runtime/pty/0.5.0/harness-pty'
    const args = `${program} serve --home ${UNIX_HOME} --history-limit 2000`
    let up = true
    const cut = deps(null, { platform: 'darwin', home: UNIX_HOME, alive: () => up, rows: async () => [unixRow({ executable: program.slice(0, 16), args })], terminate: async () => { up = false; return 'ended' } })
    expect(await endPtyHosts(cut.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
    const relative = deps(null, { platform: 'darwin', home: UNIX_HOME, alive: () => up, rows: async () => [unixRow({ executable: 'pty/target/relea', args: `pty/target/release/harness-pty serve --home ${UNIX_HOME}` })], terminate: async () => { up = false; return 'ended' } })
    up = true
    expect((await endPtyHosts(relative.deps))[0]!.how).toBe('ended')
    const renamed = deps(null, { platform: 'darwin', home: UNIX_HOME, rows: async () => [unixRow({ executable: '/usr/bin/python3', args })] })
    expect(await endPtyHosts(renamed.deps)).toEqual(left('nothing answers, and pid 100 is not a harness-pty process'))
    const windows = deps(null, { rows: async () => [winRow({ executable: 'C:\\Users\\u\\', args: `${WIN_EXE} serve --home ${WIN_HOME}` })] })
    expect((await endPtyHosts(windows.deps))[0]!.how).toBe('left')
  })

  it('on Unix, finds a home with a space in it in the unquoted ps text, and reports a host that outlives SIGTERM', async () => {
    const home = '/Users/John Doe/.harness/adapters/pty'
    const spaced = deps(null, { platform: 'darwin', home, rows: async () => [unixRow({ args: `/opt/harness-pty serve --home ${home} --history-limit 2000` })] })
    expect(await endPtyHosts(spaced.deps)).toEqual(left('nothing answers, and it outlived SIGTERM'))
    expect(spaced.ended).toEqual(['100 Sat Oct 17 10:00:00 2026'])
    expect(spaced.slept.filter((ms) => ms === 100)).toHaveLength(HOST_EXIT_WAIT_MS / 100)
    const prefix = deps(null, { platform: 'darwin', home, rows: async () => [unixRow({ args: `/opt/harness-pty serve --home ${home} copy` })] })
    expect((await endPtyHosts(prefix.deps))[0]!.how).toBe('left')
    expect(prefix.ended).toEqual([])
  })

  it('ends a protocol 1 host, which has no shutdown, once its panes are gone, without waiting for it first', async () => {
    const h = host(['%1'], { protocol: 1 })
    const t = deps(h, { discover: () => [rec(100, 1)] })
    expect(await endPtyHosts(t.deps)).toEqual([{ pid: 100, protocol: 1, panes: 1, how: 'ended' }])
    expect(h.calls).toEqual(['inventory', 'kill %1', 'close'])
    expect(t.ended).toEqual(['100 w:1'])
    expect(t.slept).toEqual([PANE_GRACE_MS])
  })

  it('ends a host that refuses to shut down at once, saying why', async () => {
    const h = host(['%1'], { refuseShutdown: true })
    const t = deps(h, { terminate: async () => 'mismatch' })
    expect(await endPtyHosts(t.deps)).toEqual(left('it would not shut down (host still has panes (1)); pid 100 changed while it was being ended', 1))
    expect(t.slept).not.toContain(100)
  })

  it('keeps an inventory that failed as the reason', async () => {
    const h = host([], { protocol: 1, inventoryFails: true })
    const t = deps(h, { discover: () => [rec(100, 1)], terminate: async () => 'mismatch' })
    expect((await endPtyHosts(t.deps))[0]!.detail).toBe('its panes could not be listed (the table is busy); pid 100 changed while it was being ended')
  })

  it('ends a host that agreed to shut down but did not exit', async () => {
    const h = host([], { exitsOnShutdown: false })
    const t = deps(h)
    expect(await endPtyHosts(t.deps)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
    expect(t.slept.filter((ms) => ms === 100)).toHaveLength(HOST_EXIT_WAIT_MS / 100)
    expect(t.ended).toEqual(['100 w:1'])
    const kept = deps(host([], { exitsOnShutdown: false }), { terminate: async () => 'mismatch' })
    expect((await endPtyHosts(kept.deps))[0]!.detail).toBe('it agreed to shut down but did not exit; pid 100 changed while it was being ended')
  })
})

describe('endPtyHosts, several instances', () => {
  it('ends a legacy and two versioned hosts of one protocol in one home', async () => {
    const instances = new Map([[101, 'p2'], [102, 'p2-1.0.0'], [103, 'p2-1.1.0']])
    const up = new Set(instances.keys())
    const reached: string[] = []
    const shut: number[] = []
    const t = deps(null, {
      discover: () => [...instances].map(([pid, instance]) => rec(pid, 2, WRITTEN, instance)),
      alive: (pid) => up.has(pid),
      reach: async (instance) => {
        reached.push(instance)
        const pid = [...instances].find(([, name]) => name === instance)![0]
        const h = host([])
        const call = h.client.call
        h.client.call = (async (op: { op: string }) => { if (op.op === 'shutdown') { up.delete(pid); shut.push(pid) } return call(op as never) }) as typeof call
        return { client: h.client }
      },
    })
    expect(await endPtyHosts(t.deps)).toEqual([101, 102, 103].map((pid) => ({ pid, protocol: 2, panes: 0, how: 'shut down' })))
    expect(reached).toEqual(['p2', 'p2-1.0.0', 'p2-1.1.0'])
    expect(shut).toEqual([101, 102, 103])
  })
})

describe('ptyHostsDeps', () => {
  it('lists every instance with its own record time, legacy and versioned', () => {
    const home = mkdtempSync(path.join(tmpdir(), 'pty-hosts-'))
    try {
      mkdirSync(path.join(home, 'run'))
      const names = ['p2', 'p2-1.0.0', 'p2-1.1.0']
      names.forEach((instance, i) => {
        const file = path.join(home, 'run', instance === 'p2' ? 'pty-host-2.json' : `pty-host-${instance}.json`)
        writeFileSync(file, JSON.stringify(discovery(100 + i, 2, instance)))
        const at = new Date(WRITTEN - (i + 1) * 60_000)
        utimesSync(file, at, at)
      })
      const found = ptyHostsDeps(home).discover()
      expect(found.map((r) => r.discovery.instance).sort()).toEqual([...names].sort())
      for (const r of found) expect(r.written).toBe(WRITTEN - (names.indexOf(r.discovery.instance) + 1) * 60_000)
    } finally {
      rmSync(home, { recursive: true, force: true })
    }
  })

  it("takes each record's time as it reads the record, so a host that removes its record while it exits is still judged", async () => {
    const home = mkdtempSync(path.join(tmpdir(), 'pty-hosts-'))
    try {
      mkdirSync(path.join(home, 'run'))
      const file = path.join(home, 'run', 'pty-host-2.json')
      writeFileSync(file, JSON.stringify(discovery(100)))
      const written = Date.now() - 60_000
      utimesSync(file, new Date(written), new Date(written))
      const real = ptyHostsDeps(home)
      expect(real.home).toBe(home)
      const recorded = real.discover()
      expect(recorded).toEqual([{ discovery: discovery(100), written: statSync(file).mtimeMs }])
      // A host that agreed to shut down removes its record first, then exits; this one does not exit.
      const h = host([], { exitsOnShutdown: false })
      const call = h.client.call
      h.client.call = (async (op: { op: string }) => { if (op.op === 'shutdown') rmSync(file); return call(op as never) }) as typeof call
      const ended: string[] = []
      const t = {
        ...real,
        discover: () => recorded,
        reach: async () => ({ client: h.client }),
        alive: () => h.alive(),
        dead: async () => false,
        rows: async () => [{ pid: 100, parentPid: 1, executable: '/opt/harness-pty', startMarker: filetime(written - 5_000), args: `/opt/harness-pty serve --home ${home}` }],
        terminate: async (pid: number, marker: string) => { ended.push(`${pid} ${marker}`); h.kill(); return 'ended' as const },
        sleep: async () => {},
      }
      expect(await endPtyHosts(t)).toEqual([{ pid: 100, protocol: 2, panes: 0, how: 'ended' }])
      expect(ended).toEqual([`100 ${filetime(written - 5_000)}`])
      expect(real.discover()).toEqual([])
    } finally {
      rmSync(home, { recursive: true, force: true })
    }
  })
})