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.7 KB
Raw Blame
import { once } from 'node:events'
import { spawnSync } from 'node:child_process'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
import net from 'node:net'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { removeTree } from '../terminalBackend.contract.js'
import { PtyHostClient } from './client.js'
import { binaryVersion, currentPtyVersion, discoveredHostDead, ensurePtyHost, forgetExitedHost, listDiscoveries, ptyHostBinary, reachable, reachPtyHost, readInstanceDiscovery, removeUnusedPtyVersions, startMarkerMs, targetHost } from './launch.js'
import { discoveryFileName } from './instance.js'
import { helloProof, PTY_PROTOCOL, SUPPORTED_PTY_PROTOCOLS } from './protocol.js'

const exe = process.platform === 'win32' ? 'harness-pty.exe' : 'harness-pty'
const cleanup: Array<() => unknown> = []
afterEach(async () => {
  for (const step of cleanup.splice(0).reverse()) await step()
})

function tempDir(prefix: string): string {
  const dir = mkdtempSync(path.join(tmpdir(), prefix))
  cleanup.push(() => removeTree(dir))
  return dir
}

function executable(file: string, body = ''): string {
  mkdirSync(path.dirname(file), { recursive: true })
  writeFileSync(file, body)
  chmodSync(file, 0o755)
  return file
}

/** The instance a host from before versioned instances has: `p<protocol>`, in `pty-host-<protocol>.json`. */
const LEGACY = `p${PTY_PROTOCOL}`
const discoveryFile = (home: string) => path.join(home, 'run', `pty-host-${PTY_PROTOCOL}.json`)
function writeDiscovery(home: string, value: unknown): void {
  mkdirSync(path.join(home, 'run'), { recursive: true })
  writeFileSync(discoveryFile(home), JSON.stringify(value))
}

describe('ptyHostBinary', () => {
  it('takes HARNESS_PTY_BIN first, as it is', () => {
    expect(ptyHostBinary({ env: { HARNESS_PTY_BIN: ' /opt/x/harness-pty ' }, runtimeDir: '/nowhere', besideDir: '/nowhere' }))
      .toBe('/opt/x/harness-pty')
  })

  it('takes the version <runtime>/pty/current-pty names, not the newest there', () => {
    const runtime = tempDir('rt-')
    executable(path.join(runtime, 'pty', '0.9.0', exe))
    executable(path.join(runtime, 'pty', '0.10.0', exe))
    // Newer, perhaps another install's of another protocol: not the pinned one.
    executable(path.join(runtime, 'pty', '0.11.0', exe))
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.10.0\n')
    const besideDir = tempDir('dist-')
    executable(path.join(besideDir, 'pty', exe))
    expect(currentPtyVersion(runtime)).toBe('0.10.0')
    expect(ptyHostBinary({ env: {}, runtimeDir: runtime, besideDir })).toBe(path.join(runtime, 'pty', '0.10.0', exe))
    // HARNESS_PTY_BIN still comes first.
    expect(ptyHostBinary({ env: { HARNESS_PTY_BIN: '/o/harness-pty' }, runtimeDir: runtime, besideDir })).toBe('/o/harness-pty')
  })

  it('falls back to the bundle\'s binary when current-pty is missing, not a version, or names no binary', () => {
    const runtime = tempDir('rt-')
    executable(path.join(runtime, 'pty', '0.9.0', exe))
    const besideDir = tempDir('dist-')
    const beside = executable(path.join(besideDir, 'pty', exe))
    // No pointer: the newest directory is not guessed at.
    expect(currentPtyVersion(runtime)).toBeNull()
    expect(ptyHostBinary({ env: {}, runtimeDir: runtime, besideDir })).toBe(beside)
    // A pointer names only a version directory: never a path out of <runtime>/pty.
    for (const pointer of ['../../bin', '/usr/bin', 'latest', '']) {
      writeFileSync(path.join(runtime, 'pty', 'current-pty'), pointer)
      expect(currentPtyVersion(runtime)).toBeNull()
      expect(ptyHostBinary({ env: {}, runtimeDir: runtime, besideDir })).toBe(beside)
    }
    // A version whose install did not finish.
    mkdirSync(path.join(runtime, 'pty', '0.10.0'))
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.10.0')
    expect(ptyHostBinary({ env: {}, runtimeDir: runtime, besideDir })).toBe(beside)
  })

  it.skipIf(process.platform === 'win32')('skips a managed binary that is not executable', () => {
    const runtime = tempDir('rt-')
    const file = executable(path.join(runtime, 'pty', '1.0.0', exe))
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '1.0.0')
    chmodSync(file, 0o644)
    expect(ptyHostBinary({ env: {}, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
  })

  it('falls back to the binary in pty/ beside the bundle (build-bundle.mjs), then to null', () => {
    const besideDir = tempDir('dist-')
    expect(ptyHostBinary({ env: {}, runtimeDir: '/nowhere', besideDir })).toBeNull()
    // Not loose beside it: the host's ConPTY payload travels in its folder.
    executable(path.join(besideDir, exe))
    expect(ptyHostBinary({ env: {}, runtimeDir: '/nowhere', besideDir })).toBeNull()
    executable(path.join(besideDir, 'pty', exe))
    expect(ptyHostBinary({ env: { HARNESS_PTY_BIN: '  ' }, runtimeDir: '/nowhere', besideDir })).toBe(path.join(besideDir, 'pty', exe))
  })
})

describe('readInstanceDiscovery', () => {
  const valid = { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint: '/x.sock', pid: 7, version: '0.1.0', token: 't' }

  it('reads a legacy p<n> from <home>/run/pty-host-<n>.json, and a versioned one from pty-host-<instance>.json', () => {
    const home = tempDir('h-')
    writeDiscovery(home, valid)
    expect(readInstanceDiscovery(home, LEGACY)).toEqual(valid)
    const versioned = { ...valid, instance: `p${PTY_PROTOCOL}-0.4.21`, version: '0.4.21' }
    writeFileSync(path.join(home, 'run', `pty-host-p${PTY_PROTOCOL}-0.4.21.json`), JSON.stringify(versioned))
    expect(readInstanceDiscovery(home, versioned.instance)).toEqual(versioned)
    // Each instance its own file.
    expect(readInstanceDiscovery(home, LEGACY)).toEqual(valid)
  })

  it('gives null for a missing, unreadable or malformed file, another protocol or another instance', () => {
    const home = tempDir('h-')
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    mkdirSync(path.join(home, 'run'))
    writeFileSync(discoveryFile(home), '{"protocol":')
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    writeDiscovery(home, { ...valid, pid: '7' })
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    writeDiscovery(home, null)
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    writeDiscovery(home, { ...valid, protocol: PTY_PROTOCOL + 1 })
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    writeDiscovery(home, { ...valid, instance: `p${PTY_PROTOCOL}-0.4.21` })
    expect(readInstanceDiscovery(home, LEGACY)).toBeNull()
    // Not an instance: never a path.
    expect(readInstanceDiscovery(home, '../run/pty-host-2')).toBeNull()
  })
})

describe('listDiscoveries', () => {
  it('listDiscoveries finds legacy and versioned hosts, oldest first', () => {
    const dir = tempDir('h-')
    expect(listDiscoveries(dir)).toEqual([])
    expect(listDiscoveries(path.join(dir, 'none'))).toEqual([])
    writeDiscoveryOf(dir, 2, { endpoint: '/b', pid: 2, version: '0.4.21' }, 'p2-0.4.21')
    writeDiscoveryOf(dir, 3, { endpoint: '/e', pid: 5, version: '0.1.0' }, 'p3-0.1.0')
    writeDiscoveryOf(dir, 2, { endpoint: '/a', pid: 1, version: '0.4.20' }, 'p2-0.4.20')
    writeDiscoveryOf(dir, 2, { endpoint: '/l', pid: 9, version: '0.4.19' })
    writeDiscoveryOf(dir, 2, { endpoint: '/d', pid: 3, version: '0.4.21-dev.win1' }, 'p2-0.4.21-dev.win1')
    writeDiscoveryOf(dir, 1, { endpoint: '/o', pid: 4, version: '0.3.0' })
    // Not discovery files: the wrong shape, an instance another file is named for, a protocol its instance is not of.
    writeFileSync(path.join(dir, 'run', 'pty-host-junk.json'), JSON.stringify({ protocol: 2, instance: 'junk', endpoint: '/j', pid: 6, version: 'x', token: 't' }))
    writeFileSync(path.join(dir, 'run', 'pty-host-p2-9.json'), JSON.stringify({ protocol: 2, instance: 'p2-0.4.20', endpoint: '/j', pid: 6, version: 'x', token: 't' }))
    writeFileSync(path.join(dir, 'run', 'pty-host-p2-8.json'), JSON.stringify({ protocol: 1, instance: 'p2-8', endpoint: '/j', pid: 6, version: 'x', token: 't' }))
    writeFileSync(path.join(dir, 'run', 'pty-host-p2-7.json'), '{"protocol":')
    writeFileSync(path.join(dir, 'run', 'pty-host-p2-0.4.20.lock'), '')
    expect(listDiscoveries(dir).map(host => host.instance)).toEqual(['p1', 'p2', 'p2-0.4.20', 'p2-0.4.21-dev.win1', 'p2-0.4.21', 'p3-0.1.0'])
    expect(listDiscoveries(dir)[2]).toEqual({ protocol: 2, instance: 'p2-0.4.20', endpoint: '/a', pid: 1, version: '0.4.20', token: 't' })
  })
})

/**
 * A stand-in for `harness-pty serve --home <dir>`: a Node script that records each start in
 * `<home>/spawns`, then serves (writing its discovery file once it listens), fails, or exits
 * at once as a host that found another one serving does.
 */
function fakeBinary(mode: 'serve' | 'fail' | 'quiet' | 'deaf', options: { instance?: string; versionLine?: string; file?: string } = {}): string {
  const instance = options.instance ?? LEGACY
  const name = discoveryFileName(instance)!
  return executable(options.file ?? path.join(tempDir('bin-'), exe), `#!${process.execPath}
import crypto from 'node:crypto'
import fs from 'node:fs'
import net from 'node:net'
import path from 'node:path'
if (process.argv[2] === 'version') {
  if (process.env.FAKE_PTY_RUNS) fs.appendFileSync(process.env.FAKE_PTY_RUNS, 'version\\n')
  process.stdout.write(${JSON.stringify(`${options.versionLine ?? ''}\n`)})
  process.exit(0)
}
const home = process.argv[process.argv.indexOf('--home') + 1]
const run = path.join(home, 'run')
fs.mkdirSync(run, { recursive: true })
fs.appendFileSync(path.join(home, 'spawns'), process.pid + '\\n')
// What the host was started with, for the spawn-environment test.
fs.writeFileSync(path.join(home, 'env.json'), JSON.stringify({ TMUX: process.env.TMUX ?? null, TMUX_PANE: process.env.TMUX_PANE ?? null, KEPT: process.env.PTY_LAUNCH_KEPT ?? null }))
fs.writeFileSync(path.join(home, 'cwd'), process.cwd())
if (${JSON.stringify(mode)} === 'fail') process.exit(4)
if (${JSON.stringify(mode)} === 'quiet') process.exit(0)
const endpoint = path.join(run, 'h.sock')
fs.rmSync(endpoint, { force: true })
if (${JSON.stringify(mode)} === 'deaf') {
  // A discovery file naming an endpoint nothing listens at, from a host that then stays up.
  const file = path.join(run, ${JSON.stringify(name)})
  fs.writeFileSync(file, JSON.stringify({ protocol: ${PTY_PROTOCOL}, instance: ${JSON.stringify(instance)}, endpoint, pid: process.pid, version: 'fake', token: 'fake-token' }))
  setInterval(() => {}, 1000)
} else {
const server = net.createServer(socket => {
  socket.on('error', () => {})
  let pending = ''
  let said = false
  socket.on('data', chunk => {
    pending += chunk
    let at
    while ((at = pending.indexOf('\\n')) >= 0) {
      const value = JSON.parse(pending.slice(0, at))
      pending = pending.slice(at + 1)
      if (!said) {
        said = true
        const proof = crypto.createHash('sha256').update('fake-token').update('\\0').update(String(value.hello.nonce)).digest('hex')
        socket.write(JSON.stringify({ hello: { ok: true, instance: ${JSON.stringify(instance)}, version: 'fake', pid: process.pid, proof } }) + '\\n')
        continue
      }
      socket.write(JSON.stringify(value.op === 'inventory' ? { id: value.id, ok: true, panes: [] } : { id: value.id, ok: true }) + '\\n')
    }
  })
})
server.listen(endpoint, () => {
  const file = path.join(run, ${JSON.stringify(name)})
  fs.writeFileSync(file + '.tmp', JSON.stringify({ protocol: ${PTY_PROTOCOL}, instance: ${JSON.stringify(instance)}, endpoint, pid: process.pid, version: 'fake', token: 'fake-token' }))
  fs.renameSync(file + '.tmp', file)
})
}
`)
}

/** A home whose spawned fake hosts are killed after the test. */
function home(): string {
  const dir = tempDir('h-')
  cleanup.push(() => {
    const spawns = path.join(dir, 'spawns')
    if (!existsSync(spawns)) return
    for (const pid of readFileSync(spawns, 'utf8').split('\n').filter(Boolean)) {
      try { process.kill(Number(pid), 'SIGKILL') } catch { /* already gone */ }
    }
  })
  return dir
}
const spawnCount = (dir: string) => existsSync(path.join(dir, 'spawns'))
  ? readFileSync(path.join(dir, 'spawns'), 'utf8').split('\n').filter(Boolean).length
  : 0

async function clientOf(result: Awaited<ReturnType<typeof ensurePtyHost>>): Promise<PtyHostClient> {
  if (!('client' in result)) throw new Error(`no client: ${JSON.stringify(result)}`)
  cleanup.push(() => result.client.close())
  return result.client
}

// The fake binary is a script with a shebang, which Windows cannot run.
describe.skipIf(process.platform === 'win32')('ensurePtyHost', () => {
  it('connects to the host the discovery file names, without starting one', async () => {
    const dir = home()
    const binary = fakeBinary('serve')
    const first = await clientOf(await ensurePtyHost(dir, { target: null, binary }))
    expect(spawnCount(dir)).toBe(1)
    const second = await clientOf(await ensurePtyHost(dir, { target: null, binary: null }))
    expect(second).not.toBe(first)
    expect(await second.call({ op: 'inventory' })).toEqual({ state: 'ok', value: { panes: [] } })
    expect(spawnCount(dir)).toBe(1)
  })

  it('starts the host without the daemon\'s tmux identity: its panes are not inside the daemon\'s tmux pane', async () => {
    vi.stubEnv('TMUX', '/tmp/tmux-501/default,1,0')
    vi.stubEnv('TMUX_PANE', '%42')
    vi.stubEnv('PTY_LAUNCH_KEPT', 'yes')
    try {
      const dir = home()
      await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
      expect(JSON.parse(readFileSync(path.join(dir, 'env.json'), 'utf8'))).toEqual({ TMUX: null, TMUX_PANE: null, KEPT: 'yes' })
      expect(process.env.TMUX_PANE).toBe('%42')
    } finally { vi.unstubAllEnvs() }
  })

  it('starts the host in its home, not in the daemon\'s directory', async () => {
    const dir = home()
    await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
    expect(readFileSync(path.join(dir, 'cwd'), 'utf8')).toBe(realpathSync(dir))
    expect(realpathSync(process.cwd())).not.toBe(realpathSync(dir))
  })

  it('starts the host in a home that does not exist yet, making it', async () => {
    const parent = home()
    const dir = path.join(parent, 'not', 'yet')
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
    cleanup.push(() => {
      const pid = readInstanceDiscovery(dir, LEGACY)?.pid
      if (pid) try { process.kill(pid, 'SIGKILL') } catch { /* already gone */ }
    })
    expect(client.instance).toBe(LEGACY)
    expect(readFileSync(path.join(dir, 'cwd'), 'utf8')).toBe(realpathSync(dir))
    expect(statSync(dir).mode & 0o777).toBe(0o700)
  })

  it('starts a host when there is no discovery file, and waits for it', async () => {
    const dir = home()
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
    expect(client.instance).toBe(LEGACY)
    expect(readInstanceDiscovery(dir, LEGACY)?.pid).toBe(Number(readFileSync(path.join(dir, 'spawns'), 'utf8').trim()))
  })

  it('starts a host when the endpoint in the discovery file refuses', async () => {
    const dir = home()
    writeDiscovery(dir, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint: path.join(dir, 'gone.sock'), pid: 999_999, version: 'old', token: 't' })
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
    expect(await client.call({ op: 'inventory' })).toMatchObject({ state: 'ok' })
    expect(readInstanceDiscovery(dir, LEGACY)?.version).toBe('fake')
  })

  it('without a target, waits for whichever host of this protocol the binary starts: a versioned one too', async () => {
    const dir = home()
    // A legacy host that has exited is no host.
    writeDiscovery(dir, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint: path.join(dir, 'gone.sock'), pid: deadPid(), version: 'old', token: 't' })
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve', { instance: `p${PTY_PROTOCOL}-0.4.21` }) }))
    expect(client.instance).toBe(`p${PTY_PROTOCOL}-0.4.21`)
    expect(spawnCount(dir)).toBe(1)
  })

  it('starts one host for concurrent calls', async () => {
    const dir = home()
    const binary = fakeBinary('serve')
    const results = await Promise.all([ensurePtyHost(dir, { target: null, binary }), ensurePtyHost(dir, { target: null, binary }), ensurePtyHost(dir, { target: null, binary })])
    for (const result of results) await clientOf(result)
    expect(spawnCount(dir)).toBe(1)
  })

  it('is unavailable when there is no binary', async () => {
    expect(await ensurePtyHost(home(), { target: null, binary: null })).toEqual({
      unavailable: expect.stringContaining('harness-pty'), code: 'PTY_HOST_UNAVAILABLE',
    })
  })

  it('is unavailable when the binary cannot be started', async () => {
    const result = await ensurePtyHost(home(), { target: null, binary: path.join(tempDir('bin-'), 'missing') })
    expect(result).toEqual({ unavailable: expect.stringContaining('could not start'), code: 'PTY_HOST_UNAVAILABLE' })
  })

  it('is unavailable at once when the host exits with an error', async () => {
    const started = Date.now()
    const result = await ensurePtyHost(home(), { target: null, binary: fakeBinary('fail'), waitMs: 5_000 })
    expect(result).toEqual({ unavailable: expect.stringContaining('exited with code 4'), code: 'PTY_HOST_UNAVAILABLE' })
    expect(Date.now() - started).toBeLessThan(4_000)
  })

  it('is unavailable when no discovery file appears in time', async () => {
    const result = await ensurePtyHost(home(), { target: null, binary: fakeBinary('quiet'), waitMs: 300 })
    expect(result).toEqual({ unavailable: expect.stringContaining('300 ms'), code: 'PTY_HOST_UNAVAILABLE' })
  })

  it('is unavailable, saying so, when the endpoint a new discovery file names refuses connections', async () => {
    const result = await ensurePtyHost(home(), { target: null, binary: fakeBinary('deaf') })
    expect(result).toEqual({
      unavailable: 'no harness-pty answers at the endpoint its discovery file names', code: 'PTY_HOST_UNAVAILABLE',
    })
  })

  it('reports a host that refuses this daemon as incompatible, without starting another', async () => {
    const dir = home()
    const endpoint = path.join(dir, 'r.sock')
    const server = net.createServer(socket => {
      socket.on('error', () => {})
      socket.once('data', () => {
        socket.end(`${JSON.stringify({ hello: { ok: false, code: 'incompatible', reason: 'wrong token' } })}\n`)
      })
    })
    server.listen(endpoint)
    await once(server, 'listening')
    cleanup.push(() => new Promise(resolve => server.close(resolve)))
    writeDiscovery(dir, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint, pid: 1, version: 'v', token: 'stale' })
    expect(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') })).toEqual({ incompatible: 'incompatible: wrong token' })
    expect(spawnCount(dir)).toBe(0)
  })

  it('never dials the endpoint a dead host\'s discovery file names: whoever has it now is not the host', async () => {
    const dir = home()
    const endpoint = path.join(dir, 'squatted.sock')
    let dialled = 0
    const squatter = net.createServer(socket => {
      dialled++
      socket.on('error', () => {})
      socket.once('data', () => socket.end(`${JSON.stringify({ hello: { ok: false, code: 'incompatible', reason: 'squatter' } })}\n`))
    })
    squatter.listen(endpoint)
    await once(squatter, 'listening')
    cleanup.push(() => new Promise(resolve => squatter.close(resolve)))
    writeDiscovery(dir, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint, pid: deadPid(), version: 'v', token: 'stale' })
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve') }))
    expect(await client.call({ op: 'inventory' })).toMatchObject({ state: 'ok' })
    expect(spawnCount(dir)).toBe(1)
    expect(dialled).toBe(0)
  })

  it('takes a pid given to another process since the file was written for a dead host, and a live one\'s refusal as an error', async () => {
    const dir = home()
    const endpoint = path.join(dir, 'refusing.sock')
    let dialled = 0
    const server = net.createServer(socket => {
      dialled++
      socket.on('error', () => {})
      socket.once('data', () => socket.end(`${JSON.stringify({ hello: { ok: false, code: 'incompatible', reason: 'wrong token' } })}\n`))
    })
    server.listen(endpoint)
    await once(server, 'listening')
    cleanup.push(() => new Promise(resolve => server.close(resolve)))
    writeDiscovery(dir, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint, pid: process.pid, version: 'v', token: 'stale' })
    // The host that wrote the file started before it; this one after: not it.
    // (The host started in its place is listed too, as having started before its own file.)
    const started = () => existsSync(path.join(dir, 'spawns'))
      ? readFileSync(path.join(dir, 'spawns'), 'utf8').split('\n').filter(Boolean).map(Number) : []
    const later = { alive: () => true, rows: async () => [
      { pid: process.pid, executable: 'x', startMarker: filetime(Date.now() + 60_000) },
      ...started().map(pid => ({ pid, executable: 'harness-pty', startMarker: filetime(Date.now() - 60_000) })),
    ] }
    expect(await clientOf(await ensurePtyHost(dir, { target: null, binary: fakeBinary('serve'), liveness: later }))).toBeTruthy()
    expect(dialled).toBe(0)
    // The process that wrote it, still running and refusing: an error, and no other host is started.
    const other = home()
    writeDiscovery(other, { protocol: PTY_PROTOCOL, instance: LEGACY, endpoint, pid: process.pid, version: 'v', token: 'stale' })
    const earlier = { alive: () => true, rows: async () => [{ pid: process.pid, executable: 'x', startMarker: filetime(Date.now() - 60_000) }] }
    expect(await ensurePtyHost(other, { target: null, binary: fakeBinary('serve'), liveness: earlier })).toEqual({ incompatible: 'incompatible: wrong token' })
    expect(dialled).toBe(1)
    expect(spawnCount(other)).toBe(0)
  })

  it('tries again once when the discovery file changed during a refused hello', async () => {
    const dir = home()
    const binary = fakeBinary('serve')
    await clientOf(await ensurePtyHost(dir, { target: null, binary }))
    const live = readInstanceDiscovery(dir, LEGACY)!
    // A host that just restarted: the file still names the old token while the new host answers.
    const endpoint = path.join(dir, 'r.sock')
    const server = net.createServer(socket => {
      socket.on('error', () => {})
      socket.once('data', () => {
        writeDiscovery(dir, live)
        socket.end(`${JSON.stringify({ hello: { ok: false, code: 'incompatible', reason: 'wrong token' } })}\n`)
      })
    })
    server.listen(endpoint)
    await once(server, 'listening')
    cleanup.push(() => new Promise(resolve => server.close(resolve)))
    writeDiscovery(dir, { ...live, endpoint, token: 'old', pid: 1 })
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: null }))
    expect(await client.call({ op: 'inventory' })).toMatchObject({ state: 'ok' })
  })
})

/** An endpoint for a test server: a named pipe on Windows, a socket file in [dir] elsewhere. */
const endpointIn = (dir: string, name: string) => process.platform === 'win32'
  ? `\\\\.\\pipe\\pty-launch-${path.basename(dir)}-${name}`
  : path.join(dir, `${name}.sock`)

/**
 * A host stand-in in this process that proves [token] and answers every request `ok`, saying hello as [instance]
 * (`p<protocol>` by default); the protocols said hello in.
 */
async function answeringHost(endpoint: string, token: string, instance?: string): Promise<number[]> {
  const protocols: number[] = []
  const server = net.createServer(socket => {
    socket.on('error', () => {})
    let pending = ''
    let said = false
    socket.on('data', chunk => {
      pending += chunk
      let at
      while ((at = pending.indexOf('\n')) >= 0) {
        const value = JSON.parse(pending.slice(0, at))
        pending = pending.slice(at + 1)
        if (said) { socket.write(`${JSON.stringify({ id: value.id, ok: true })}\n`); continue }
        said = true
        protocols.push(value.hello.protocol)
        socket.write(`${JSON.stringify({ hello: { ok: true, instance: instance ?? `p${value.hello.protocol}`, version: 'v', pid: process.pid, proof: helloProof(token, value.hello.nonce) } })}\n`)
      }
    })
  })
  server.listen(endpoint)
  await once(server, 'listening')
  cleanup.push(() => new Promise(resolve => server.close(resolve)))
  return protocols
}

/** [instance]'s discovery file (a legacy `p<protocol>` by default), in the file it is read from. */
const writeDiscoveryOf = (home: string, protocol: number, value: Record<string, unknown>, instance = `p${protocol}`) => {
  mkdirSync(path.join(home, 'run'), { recursive: true })
  writeFileSync(path.join(home, 'run', discoveryFileName(instance)!), JSON.stringify({ protocol, instance, version: '0.1.0', token: 't', ...value }))
}
/** A pid no process has: a child that has exited. */
function deadPid(): number {
  const child = spawnSync(process.execPath, ['-e', ''])
  return child.pid!
}

/** A Windows start marker for [ms] since the epoch. */
const filetime = (ms: number) => `w:${(BigInt(ms) + 11_644_473_600_000n) * 10_000n}`

describe('discoveredHostDead', () => {
  it('reads both kinds of start marker', () => {
    expect(startMarkerMs(filetime(1_791_893_045_123))).toBe(1_791_893_045_123)
    expect(startMarkerMs('Thu Oct 15 10:00:00 2026')).toBe(new Date(2026, 9, 15, 10, 0, 0).getTime())
    expect(startMarkerMs('soon')).toBeNull()
  })

  it('is proven only by a pid that runs nothing, a table without it, or a process that started after the file', async () => {
    const dir = tempDir('h-')
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: '/x', pid: 42 })
    const discovery = { instance: `p${PTY_PROTOCOL}`, pid: 42 }
    const row = (startMarker: string) => ({ pid: 42, executable: 'harness-pty.exe', startMarker })
    expect(await discoveredHostDead(dir, discovery, { alive: () => false })).toBe(true)
    // The pid alone, alive: no proof.
    expect(await discoveredHostDead(dir, discovery, { alive: () => true })).toBe(false)
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => [] })).toBe(true)
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => [row(filetime(Date.now() + 60_000))] })).toBe(true)
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => [row(filetime(Date.now() - 60_000))] })).toBe(false)
    // Within a second-resolution stamp's slack of the file: the host that wrote it.
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => [row(filetime(Date.now() + 1_000))] })).toBe(false)
    // A table that cannot be read, a marker that cannot be read, a file that is not there: no proof.
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => null })).toBe(false)
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => { throw new Error('ps') } })).toBe(false)
    expect(await discoveredHostDead(dir, discovery, { alive: () => true, rows: async () => [row('soon')] })).toBe(false)
    expect(await discoveredHostDead(tempDir('h-'), discovery, { alive: () => true, rows: async () => [row(filetime(Date.now() + 60_000))] })).toBe(false)
    // A versioned instance is judged against its own file: another instance's says nothing of it.
    const versioned = { instance: `p${PTY_PROTOCOL}-0.4.21`, pid: 42 }
    expect(await discoveredHostDead(dir, versioned, { alive: () => true, rows: async () => [row(filetime(Date.now() + 60_000))] })).toBe(false)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: '/x', pid: 42 }, versioned.instance)
    expect(await discoveredHostDead(dir, versioned, { alive: () => true, rows: async () => [row(filetime(Date.now() + 60_000))] })).toBe(true)
  })
})


describe('reachPtyHost', () => {
  it('connects to the host of the instance asked, in its own protocol, and never starts one', async () => {
    const dir = tempDir('h-')
    const protocol = SUPPORTED_PTY_PROTOCOLS[0]
    const endpoint = endpointIn(dir, 'old')
    const protocols = await answeringHost(endpoint, 't')
    writeDiscoveryOf(dir, protocol, { endpoint, pid: process.pid })
    const result = await reachPtyHost(dir, `p${protocol}`)
    const client = await clientOf(result as Awaited<ReturnType<typeof ensurePtyHost>>)
    expect(client.protocol).toBe(protocol)
    expect(protocols).toEqual([protocol])
    // A versioned instance, from its own file.
    const versioned = endpointIn(dir, 'versioned')
    const heard = await answeringHost(versioned, 't', `p${PTY_PROTOCOL}-0.4.21`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: versioned, pid: process.pid }, `p${PTY_PROTOCOL}-0.4.21`)
    const other = await clientOf(await reachPtyHost(dir, `p${PTY_PROTOCOL}-0.4.21`) as Awaited<ReturnType<typeof ensurePtyHost>>)
    expect(other.instance).toBe(`p${PTY_PROTOCOL}-0.4.21`)
    expect(heard).toEqual([PTY_PROTOCOL])
    expect(protocols).toEqual([protocol])
  })

  it('never dials a dead host\'s endpoint, even when something answers there', async () => {
    const dir = tempDir('h-')
    const protocol = SUPPORTED_PTY_PROTOCOLS[0]
    const endpoint = endpointIn(dir, 'squatted')
    const protocols = await answeringHost(endpoint, 't')
    const dead = deadPid()
    writeDiscoveryOf(dir, protocol, { endpoint, pid: dead })
    expect(await reachPtyHost(dir, `p${protocol}`)).toEqual({ unavailable: expect.stringContaining(`pid ${dead}`), code: 'PTY_HOST_UNAVAILABLE', pid: dead, missing: false })
    expect(protocols).toEqual([])
  })

  it('says what the file named when nothing answers, and never that the host has gone', async () => {
    const dir = tempDir('h-')
    expect(await reachPtyHost(dir, 'p1')).toEqual({ unavailable: 'there is no pty-host-1.json', code: 'PTY_HOST_UNAVAILABLE', pid: null, missing: true })
    expect(await reachPtyHost(dir, 'p2-0.4.21')).toEqual({ unavailable: 'there is no pty-host-p2-0.4.21.json', code: 'PTY_HOST_UNAVAILABLE', pid: null, missing: true })
    mkdirSync(path.join(dir, 'run'), { recursive: true })
    writeFileSync(path.join(dir, 'run', 'pty-host-1.json'), '{"protocol":')
    expect(await reachPtyHost(dir, 'p1')).toEqual({ unavailable: 'pty-host-1.json cannot be read', code: 'PTY_HOST_UNAVAILABLE', pid: null, missing: false })
    const dead = deadPid()
    writeDiscoveryOf(dir, 1, { endpoint: endpointIn(dir, 'none'), pid: dead })
    expect(await reachPtyHost(dir, 'p1')).toEqual({ unavailable: expect.stringContaining(`pid ${dead}`), code: 'PTY_HOST_UNAVAILABLE', pid: dead, missing: false })
  })
})

describe('forgetExitedHost', () => {
  it('takes down the discovery file (and Unix socket) of a host that has exited, and only that one', () => {
    const dir = tempDir('h-')
    const file = path.join(dir, 'run', 'pty-host-1.json')
    const socket = path.join(dir, 'run', 'pty-host-1.sock')
    const dead = deadPid()
    writeDiscoveryOf(dir, 1, { endpoint: socket, pid: dead })
    writeFileSync(socket, '')
    // Another pid's file (a host that took its place), or a live one: kept.
    forgetExitedHost(dir, 'p1', dead + 1)
    expect(existsSync(file)).toBe(true)
    writeDiscoveryOf(dir, 1, { endpoint: socket, pid: process.pid })
    forgetExitedHost(dir, 'p1', process.pid)
    expect(existsSync(file)).toBe(true)
    writeDiscoveryOf(dir, 1, { endpoint: socket, pid: dead })
    forgetExitedHost(dir, 'p1', dead)
    expect(existsSync(file)).toBe(false)
    expect(existsSync(socket)).toBe(process.platform === 'win32')
    // Nothing there: nothing to do.
    forgetExitedHost(dir, 'p1', dead)
    // A versioned instance's own file, and never another instance's.
    const instance = `p${PTY_PROTOCOL}-0.4.21`
    const own = path.join(dir, 'run', `pty-host-${instance}.json`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: socket, pid: dead }, instance)
    writeDiscoveryOf(dir, 1, { endpoint: socket, pid: dead })
    forgetExitedHost(dir, instance, dead)
    expect([existsSync(own), existsSync(file)]).toEqual([false, true])
  })

  it('takes the lock and pane-id files of the exited instance with it, and never while the host runs or another instance\'s', () => {
    const dir = tempDir('h-')
    const instance = `p${PTY_PROTOCOL}-0.4.21`
    const other = `p${PTY_PROTOCOL}-0.4.22`
    const run = path.join(dir, 'run')
    const files = (name: string) => ['json', 'lock', 'panes'].map((ext) => path.join(run, `pty-host-${name}.${ext}`))
    const dead = deadPid()
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: path.join(run, 'x.sock'), pid: process.pid }, instance)
    for (const file of [...files(instance).slice(1), ...files(other)]) writeFileSync(file, '1')
    // A live host keeps all of them.
    forgetExitedHost(dir, instance, process.pid)
    expect(files(instance).map((file) => existsSync(file))).toEqual([true, true, true])
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: path.join(run, 'x.sock'), pid: dead }, instance)
    forgetExitedHost(dir, instance, dead)
    expect(files(instance).map((file) => existsSync(file))).toEqual([false, false, false])
    expect(files(other).map((file) => existsSync(file))).toEqual([true, true, true])
  })

  it('goes on when a lock file cannot be removed', () => {
    const dir = tempDir('h-')
    const instance = `p${PTY_PROTOCOL}-0.4.23`
    const run = path.join(dir, 'run')
    const dead = deadPid()
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: path.join(run, 'x.sock'), pid: dead }, instance)
    // A directory in the lock's place cannot be removed as a file, as a lock a scanner still holds on Windows.
    mkdirSync(path.join(run, `pty-host-${instance}.lock`))
    writeFileSync(path.join(run, `pty-host-${instance}.panes`), '1')
    forgetExitedHost(dir, instance, dead)
    expect([existsSync(path.join(run, `pty-host-${instance}.json`)), existsSync(path.join(run, `pty-host-${instance}.panes`))]).toEqual([false, false])
  })
})

const SEED_LINE = (version: string) => JSON.stringify({ version, protocol: PTY_PROTOCOL, features: ['seed'] })

// The fake binary is a script with a shebang, which Windows cannot run.
describe.skipIf(process.platform === 'win32')('targetHost', () => {
  it('targetHost reads current-pty, and is installed', () => {
    const runtime = tempDir('rt-')
    // The binary says another version than its folder: the installed CLI's pointer names the version.
    fakeBinary('serve', { file: path.join(runtime, 'pty', '0.4.21', exe), versionLine: SEED_LINE('0.4.21') })
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.4.21\n')
    expect(targetHost({ env: {}, runtimeDir: runtime, besideDir: '/nowhere' })).toEqual({
      protocol: PTY_PROTOCOL, version: '0.4.21', instance: `p${PTY_PROTOCOL}-0.4.21`, features: ['seed'], source: 'installed',
    })
    // HARNESS_PTY_BIN naming that very binary is still the installed one.
    expect(targetHost({ env: { HARNESS_PTY_BIN: path.join(runtime, 'pty', '0.4.21', exe) }, runtimeDir: runtime, besideDir: '/nowhere' })?.source).toBe('installed')
  })

  it('targetHost asks a dev binary its version, and is binary', () => {
    const runtime = tempDir('rt-')
    const binary = fakeBinary('serve', { versionLine: SEED_LINE('9.9.9') })
    expect(targetHost({ env: { HARNESS_PTY_BIN: binary }, runtimeDir: runtime, besideDir: '/nowhere' })).toEqual({
      protocol: PTY_PROTOCOL, version: '9.9.9', instance: `p${PTY_PROTOCOL}-9.9.9`, features: ['seed'], source: 'binary',
    })
    // No current-pty: the binary beside the bundle, asked.
    const besideDir = tempDir('dist-')
    fakeBinary('serve', { file: path.join(besideDir, 'pty', exe), versionLine: SEED_LINE('0.4.21-dev.win1') })
    expect(targetHost({ env: {}, runtimeDir: runtime, besideDir })).toMatchObject({ version: '0.4.21-dev.win1', instance: `p${PTY_PROTOCOL}-0.4.21-dev.win1`, source: 'binary' })
    // A host from before versioned instances lists no features, and is still `p<protocol>`.
    const old = fakeBinary('serve', { versionLine: JSON.stringify({ version: '0.4.19', protocol: PTY_PROTOCOL }) })
    expect(targetHost({ env: { HARNESS_PTY_BIN: old }, runtimeDir: runtime, besideDir: '/nowhere' })).toEqual({
      protocol: PTY_PROTOCOL, version: '0.4.19', instance: LEGACY, features: [], source: 'binary',
    })
  })

  it('targetHost is null when neither is known', () => {
    const runtime = tempDir('rt-')
    expect(targetHost({ env: {}, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
    for (const line of ['', 'harness-pty 0.4.21', '{"version":"","protocol":2}', '{"version":"1","protocol":"2"}', '{"version":"1","protocol":2,"features":"seed"}']) {
      const binary = fakeBinary('serve', { versionLine: line })
      expect(targetHost({ env: { HARNESS_PTY_BIN: binary }, runtimeDir: runtime, besideDir: '/nowhere' }), line).toBeNull()
    }
    // A binary that is not there.
    expect(targetHost({ env: { HARNESS_PTY_BIN: path.join(runtime, 'missing') }, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
  })

  it('targetHost is unknown, said once, for a host of a protocol this daemon does not speak: the newest supported host is used', () => {
    const runtime = tempDir('rt-')
    // A paired host left in current-pty without its CLI build: above this daemon's protocol, or below every supported one.
    fakeBinary('serve', { file: path.join(runtime, 'pty', '0.5.0', exe), versionLine: JSON.stringify({ version: '0.5.0', protocol: PTY_PROTOCOL + 1, features: ['seed'] }) })
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.5.0\n')
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    try {
      expect(targetHost({ env: {}, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
      expect(targetHost({ env: {}, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
      const said = error.mock.calls.map((call) => String(call[0])).filter((line) => line.includes('0.5.0'))
      expect(said).toEqual([`[terminal] ptyhost: the host 0.5.0 speaks protocol ${PTY_PROTOCOL + 1}, which this daemon does not (it speaks ${SUPPORTED_PTY_PROTOCOLS.join(' and ')}): target unknown, the newest running host of protocol ${PTY_PROTOCOL} is used`])
      const old = fakeBinary('serve', { versionLine: JSON.stringify({ version: '0.0.9', protocol: 0, features: [] }) })
      expect(targetHost({ env: { HARNESS_PTY_BIN: old }, runtimeDir: runtime, besideDir: '/nowhere' })).toBeNull()
    } finally { error.mockRestore() }
  })

  it('binaryVersion runs the binary once per build: cached by its path and mtime', () => {
    const runs = path.join(tempDir('runs-'), 'runs')
    vi.stubEnv('FAKE_PTY_RUNS', runs)
    try {
      const binary = fakeBinary('serve', { versionLine: SEED_LINE('1.2.3') })
      expect(binaryVersion(binary)).toEqual({ version: '1.2.3', protocol: PTY_PROTOCOL, features: ['seed'] })
      expect(binaryVersion(binary)).toEqual({ version: '1.2.3', protocol: PTY_PROTOCOL, features: ['seed'] })
      expect(readFileSync(runs, 'utf8').split('\n').filter(Boolean)).toHaveLength(1)
      // A new build at the same path is asked again.
      fakeBinary('serve', { file: binary, versionLine: SEED_LINE('1.2.4') })
      utimesSync(binary, new Date(), new Date(Date.now() + 10_000))
      expect(binaryVersion(binary)?.version).toBe('1.2.4')
      expect(readFileSync(runs, 'utf8').split('\n').filter(Boolean)).toHaveLength(2)
    } finally { vi.unstubAllEnvs() }
  })
})

/** A target for [version] of this protocol, as `targetHost` gives it. */
const targetOf = (version: string) => ({
  protocol: PTY_PROTOCOL, version, instance: `p${PTY_PROTOCOL}-${version}`, features: ['seed'], source: 'binary' as const,
})

describe('ensurePtyHost by instance', () => {
  it('ensurePtyHost with a target never connects to another version\'s host', async () => {
    const dir = tempDir('h-')
    const older = await answeringHost(endpointIn(dir, 'older'), 't', `p${PTY_PROTOCOL}-0.4.20`)
    const newer = await answeringHost(endpointIn(dir, 'newer'), 't', `p${PTY_PROTOCOL}-0.4.21`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'older'), pid: process.pid, version: '0.4.20' }, `p${PTY_PROTOCOL}-0.4.20`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'newer'), pid: process.pid, version: '0.4.21' }, `p${PTY_PROTOCOL}-0.4.21`)
    // The older one is the target: never the newer, though it runs too.
    const client = await clientOf(await ensurePtyHost(dir, { target: targetOf('0.4.20'), binary: null }))
    expect(client.instance).toBe(`p${PTY_PROTOCOL}-0.4.20`)
    expect([older, newer]).toEqual([[PTY_PROTOCOL], []])
    // A target with no host: started (here there is no binary), and neither running host is dialled.
    expect(await ensurePtyHost(dir, { target: targetOf('0.5.0'), binary: null })).toEqual({
      unavailable: expect.stringContaining('harness-pty'), code: 'PTY_HOST_UNAVAILABLE',
    })
    expect([older, newer]).toEqual([[PTY_PROTOCOL], []])
  })

  it('ensurePtyHost without a target connects to the newest running host', async () => {
    const dir = tempDir('h-')
    const legacy = await answeringHost(endpointIn(dir, 'legacy'), 't')
    const older = await answeringHost(endpointIn(dir, 'older'), 't', `p${PTY_PROTOCOL}-0.4.20`)
    const newer = await answeringHost(endpointIn(dir, 'newer'), 't', `p${PTY_PROTOCOL}-0.4.21`)
    const squatted = await answeringHost(endpointIn(dir, 'squatted'), 't', `p${PTY_PROTOCOL}-0.4.22`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'legacy'), pid: process.pid, version: '0.4.19' })
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'older'), pid: process.pid, version: '0.4.20' }, `p${PTY_PROTOCOL}-0.4.20`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'newer'), pid: process.pid, version: '0.4.21' }, `p${PTY_PROTOCOL}-0.4.21`)
    // Newest of all, but its host has exited: its endpoint is never dialled.
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'squatted'), pid: deadPid(), version: '0.4.22' }, `p${PTY_PROTOCOL}-0.4.22`)
    const client = await clientOf(await ensurePtyHost(dir, { target: null, binary: null }))
    expect(client.instance).toBe(`p${PTY_PROTOCOL}-0.4.21`)
    expect([legacy, older, newer, squatted]).toEqual([[], [], [PTY_PROTOCOL], []])
  })

  it.skipIf(process.platform === 'win32')('ensurePtyHost with a target starts its binary beside another version\'s host, once for concurrent calls', async () => {
    const dir = home()
    const older = await answeringHost(endpointIn(dir, 'older'), 't', `p${PTY_PROTOCOL}-0.4.20`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: endpointIn(dir, 'older'), pid: process.pid, version: '0.4.20' }, `p${PTY_PROTOCOL}-0.4.20`)
    const target = targetOf('0.4.21')
    const binary = fakeBinary('serve', { instance: target.instance })
    const results = await Promise.all([ensurePtyHost(dir, { target, binary }), ensurePtyHost(dir, { target, binary })])
    for (const result of results) expect((await clientOf(result)).instance).toBe(target.instance)
    expect(spawnCount(dir)).toBe(1)
    expect(readInstanceDiscovery(dir, target.instance)?.pid).toBe(Number(readFileSync(path.join(dir, 'spawns'), 'utf8').trim()))
    expect(older).toEqual([])
  })
})

describe('removeUnusedPtyVersions', () => {
  it('deletes the versions older than current-pty that no running host of the home has', () => {
    const runtime = tempDir('rt-')
    const dir = tempDir('h-')
    for (const version of ['0.8.0', '0.9.0', '0.9.5', '0.10.0', '0.11.0']) executable(path.join(runtime, 'pty', version, exe))
    executable(path.join(runtime, 'pty', 'tools', exe))
    writeFileSync(path.join(runtime, 'pty', '0.7.0'), 'a file, not a directory')
    // Without the installed CLI's pointer nothing is known to be old.
    expect(removeUnusedPtyVersions(dir, runtime)).toEqual([])
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.10.0')
    // 0.9.5 runs a host still draining here; 0.9.0's host has exited.
    writeDiscoveryOf(dir, SUPPORTED_PTY_PROTOCOLS[0], { endpoint: '/x', pid: process.pid, version: '0.9.5' })
    if (SUPPORTED_PTY_PROTOCOLS.length > 1) writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: '/y', pid: deadPid(), version: '0.9.0' })
    expect(removeUnusedPtyVersions(dir, runtime).sort()).toEqual(['0.8.0', '0.9.0'])
    expect(readdirSync(path.join(runtime, 'pty')).sort()).toEqual(['0.10.0', '0.11.0', '0.7.0', '0.9.5', 'current-pty', 'tools'])
    // No runtime directory at all.
    expect(removeUnusedPtyVersions(dir, path.join(runtime, 'none'))).toEqual([])
  })

  it('removeUnusedPtyVersions keeps a folder a versioned host runs from', () => {
    const runtime = tempDir('rt-')
    const dir = tempDir('h-')
    for (const version of ['0.4.19', '0.4.20', '0.4.21', '0.4.22']) executable(path.join(runtime, 'pty', version, exe))
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.4.21')
    // Two hosts of one protocol, side by side: 0.4.20's runs, 0.4.19's has exited.
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: '/a', pid: process.pid, version: '0.4.20' }, `p${PTY_PROTOCOL}-0.4.20`)
    writeDiscoveryOf(dir, PTY_PROTOCOL, { endpoint: '/b', pid: deadPid(), version: '0.4.19' }, `p${PTY_PROTOCOL}-0.4.19`)
    expect(removeUnusedPtyVersions(dir, runtime)).toEqual(['0.4.19'])
    // Newer than current-pty stays, as before.
    expect(readdirSync(path.join(runtime, 'pty')).sort()).toEqual(['0.4.20', '0.4.21', '0.4.22', 'current-pty'])
  })

  it('removeUnusedPtyVersions keeps the version a host on probation would roll back to', () => {
    const runtime = tempDir('rt-')
    const dir = tempDir('h-')
    for (const version of ['0.4.19', '0.4.20', '0.4.21']) executable(path.join(runtime, 'pty', version, exe))
    writeFileSync(path.join(runtime, 'pty', 'current-pty'), '0.4.21')
    // 0.4.21 is on probation (lib/windows/ptyInstall.ts): no host runs from 0.4.20, and it is the rollback target.
    writeFileSync(path.join(runtime, 'pty', 'pty-pending.json'), JSON.stringify({ version: '0.4.21', previous: '0.4.20' }))
    expect(removeUnusedPtyVersions(dir, runtime)).toEqual(['0.4.19'])
    // Once it is kept, the marker goes, and so may the folder.
    rmSync(path.join(runtime, 'pty', 'pty-pending.json'))
    expect(removeUnusedPtyVersions(dir, runtime)).toEqual(['0.4.20'])
  })
})

describe('reachable', () => {
  afterEach(() => { vi.restoreAllMocks() })

  it('gives up on a connection that is never accepted, after its timeout', async () => {
    const socket = new net.Socket()
    const destroy = vi.spyOn(socket, 'destroy')
    vi.spyOn(net, 'connect').mockReturnValue(socket)
    const started = Date.now()
    expect(await reachable('/nowhere', 50)).toBe(false)
    expect(Date.now() - started).toBeLessThan(1_000)
    expect(destroy).toHaveBeenCalled()
  })

  it.skipIf(process.platform === 'win32')('is true for an endpoint that accepts, and false for one that refuses', async () => {
    const dir = tempDir('r-')
    const endpoint = path.join(dir, 'a.sock')
    const server = net.createServer(socket => socket.on('error', () => {}))
    server.listen(endpoint)
    await once(server, 'listening')
    cleanup.push(() => new Promise(resolve => server.close(resolve)))
    expect(await reachable(endpoint)).toBe(true)
    expect(await reachable(path.join(dir, 'none.sock'))).toBe(false)
  })
})

// Runs the real host: `cd pty && cargo +stable build`, then
// HARNESS_PTY_BIN=$(pwd)/../pty/target/debug/harness-pty npx vitest run src/lib/ptyHost/launch.spec.ts
describe.skipIf(!process.env.HARNESS_PTY_BIN)('ensurePtyHost with the real harness-pty', () => {
  it('starts the host in a temporary home, lists no panes, and reports a pane\'s exit after its create', async () => {
    const dir = tempDir('h-')
    const target = targetHost({ runtimeDir: tempDir('rt-') })
    if (!target) throw new Error('the real harness-pty did not say its version')
    cleanup.push(() => {
      const pid = readInstanceDiscovery(dir, target.instance)?.pid
      if (pid) try { process.kill(pid, 'SIGKILL') } catch { /* already gone */ }
    })
    const client = await clientOf(await ensurePtyHost(dir, { target }))
    expect(client.instance).toBe(target.instance)
    expect(client.features).toEqual(target.features)
    expect(await client.call({ op: 'inventory' })).toEqual({ state: 'ok', value: { panes: [] } })

    // A command that exits at once: its exit notice may overtake the create reply.
    const exits: Array<string> = []
    const known = new Set<string>()
    client.onEvent(e => { if (e.event === 'exit') exits.push(`${known.has(e.pane) ? 'known' : 'unknown'} ${e.pane} ${e.status}`) })
    const command = process.platform === 'win32' ? ['cmd.exe', '/d', '/c', 'exit 3'] : ['/bin/sh', '-c', 'exit 3']
    const created = await client.call({ op: 'create', command, cols: 80, rows: 24, owner: 'test', hold: false })
    if (created.state !== 'ok') throw new Error(JSON.stringify(created))
    known.add(created.value.pane)
    await expect.poll(() => exits, { timeout: 5_000 }).toEqual([`known ${created.value.pane} 3`])

    const stream = await client.openStream()
    expect(stream).not.toBeNull()
    stream!.destroy()
  })
})