Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

7.2 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import os from 'os'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { IPC } from '../shared/ipc'
import type { PtyDevices } from './pty-devices'
import type { PtyCreateResult } from '../shared/types'

/**
 * THE SPAWN THAT IS NEVER ATTEMPTED.
 *
 * node-pty's darwin spawn path leaks the pty it opened when `posix_spawn` fails: `pty_posix_spawn`
 * (node_modules/node-pty/src/unix/pty.cc) opens the master with `posix_openpt` and the slave with
 * `open()`, and on the error branch `PtyFork` throws without closing either — measured at exactly 2
 * `/dev/ptmx` fds + 1 `/dev/ttys*` fd, i.e. 2 pty DEVICES, per failed spawn.
 *
 * That makes device exhaustion self-amplifying: at the ceiling every spawn fails, every failure
 * eats two more devices, and the ceiling gets further away (a 31-minute-old main held 479 masters
 * against 28 tmux panes). We cannot fix node-pty from here, so the fix is to stop feeding it: when
 * the machine is already out of devices, the spawn is refused BEFORE node-pty is called at all.
 *
 * The refusal is only ever allowed on a MEASURED reading. A wrong block is worse than a leak — it
 * would refuse terminals on a healthy machine — so anything unmeasured spawns as it always did.
 */

/**
 * Every node-pty call is recorded, because "was it called" is the whole subject here. It can also
 * be told to fail, so the one test that needs the CATCH path (proving the arch mock below is real)
 * can have it without a second file.
 */
const spawned: Array<{ file: string }> = []
const nodePty = vi.hoisted(() => ({ throws: false }))
// Pin the persistence backend: `sessionHostSupported()` only asks whether
// out/session-host/host.cjs exists on disk, so whether this suite exercises the mocked
// `node-pty` spawn below or a real session-host shim depended on whether anyone had run
// `npm run build` (or `npm run host:build`). See src/core/__fixtures__/no-session-host.ts.
vi.mock('./session-host-backend', async () =>
  (await import('./__fixtures__/no-session-host')).noSessionHost()
)

vi.mock('node-pty', () => ({
  spawn: (file: string) => {
    spawned.push({ file })
    if (nodePty.throws) throw new Error('posix_spawnp failed.')
    return {
      onData: () => {},
      onExit: () => {},
      write: () => {},
      resize: () => {},
      pause: () => {},
      resume: () => {},
      kill: () => {},
      pid: 4321
    }
  }
}))

/** What the (real) device probe would have measured — set per test. */
const devices = vi.hoisted(() => ({
  current: { ceiling: null, inUse: null } as PtyDevices
}))
vi.mock('./pty-devices', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./pty-devices')>()),
  readPtyDevices: () => devices.current
}))

/**
 * Force `spawnHelperArchMismatch` to find a cross-arch spawn-helper.
 *
 * The arch note OUTRANKS the device note in `spawnFailureHint`, so on an ordinary matching-arch
 * host "the refusal does not mention the architecture" is true no matter what the refusal does —
 * the note is null either way. This makes the note non-null, so the assertion has something to
 * catch. `spawnHelperArchMismatch` is module-private; `./macho-arch` is the seam underneath it.
 */
vi.mock('./macho-arch', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./macho-arch')>()),
  machOArch: () => 'x64' as const,
  archMismatch: () => true
}))

const ALICE = 1

describe('pty create: pre-flight device check', () => {
  let fake: FakePlatform

  beforeEach(async () => {
    spawned.length = 0
    nodePty.throws = false
    devices.current = { ceiling: null, inUse: null }
    fake = fakePlatform()
    initPlatform(fake)
    const { PtyManager } = await import('./pty-manager')
    new PtyManager().registerIpc()
  })
  afterEach(() => resetPlatformForTests())

  const create = (): Promise<PtyCreateResult> =>
    fake.handlers[IPC.ptyCreate](ALICE, {
      cols: 80,
      rows: 24,
      persistKey: 'node-1'
    }) as Promise<PtyCreateResult>

  it('never calls node-pty when the machine is out of pty devices', async () => {
    devices.current = { ceiling: 511, inUse: 515 }

    await expect(create()).rejects.toThrow()

    expect(spawned).toHaveLength(0) // ← the leak's only cure: the fd is never opened
  })

  it('still says exactly what is full, with both numbers', async () => {
    devices.current = { ceiling: 511, inUse: 515 }

    // The same sentence the post-failure diagnosis produces — one wording, one code path.
    await expect(create()).rejects.toThrow(/out of pty devices \(515 of 511/)
    await expect(create()).rejects.toThrow(/kern\.tty\.ptmx_max/)
  })

  // Both of these need `spawnHelperArchMismatch` to actually produce a note, which it only does on
  // darwin (it is a macOS-only diagnostic and returns null everywhere else). Skipped together, so
  // a non-darwin run cannot pass the suppression test vacuously while silently losing its guard.
  const onDarwin = os.platform() === 'darwin'

  it.skipIf(!onDarwin)(
    'proves the arch mock is live: a spawn that DID fail still gets the arch note',
    async () => {
      // The control for the test below. Without it, "the refusal omits the arch note" could pass
      // simply because the mock never took effect and there was no note to omit.
      nodePty.throws = true
      devices.current = { ceiling: 511, inUse: 62 } // healthy: the spawn is attempted, and fails

      await expect(create()).rejects.toThrow(/npm run rebuild/)
      expect(spawned).toHaveLength(1)
    }
  )

  it.skipIf(!onDarwin)('never blames the architecture for a refusal it decided itself', async () => {
    nodePty.throws = true // would fail if it were reached — it must not be
    devices.current = { ceiling: 511, inUse: 515 }

    // Same mismatched helper as the control above, but this spawn is refused before node-pty. The
    // arch note outranks the device note in `spawnFailureHint`, so consulting it here would tell a
    // merely-full machine to rebuild node-pty — advice that cannot help, about a helper this path
    // never exec'd.
    await expect(create()).rejects.toThrow(/out of pty devices/)
    await expect(create()).rejects.not.toThrow(/npm run rebuild/)
    await expect(create()).rejects.not.toThrow(/architecture/)
    expect(spawned).toHaveLength(0)
  })

  it('spawns normally on a machine with devices to spare', async () => {
    devices.current = { ceiling: 511, inUse: 62 }

    const res = await create()

    expect(res.sessionId).not.toBe('')
    expect(spawned).toHaveLength(1)
  })

  it('spawns normally when the devices could not be measured at all (non-darwin)', async () => {
    devices.current = { ceiling: null, inUse: null }

    await expect(create()).resolves.toBeTruthy()
    expect(spawned).toHaveLength(1)
  })

  it('spawns normally when only the ceiling is unknown (sysctl failed, or not primed yet)', async () => {
    // The ceiling is read asynchronously and cached; a spawn racing the very first read sees
    // `null` here. Fail-open: an unprimed cache must never look like a full machine.
    devices.current = { ceiling: null, inUse: 500 }

    await expect(create()).resolves.toBeTruthy()
    expect(spawned).toHaveLength(1)
  })
})