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.9 KB
Raw Blame
import fs from 'fs'
import os from 'os'
import { execFile } from 'child_process'

/**
 * How many pty DEVICES this machine can hand out, and how many exist right now.
 *
 * The limit that bit on 2026-08-11 was neither the app's descriptors nor node-pty's architecture:
 * macOS caps pty devices system-wide at `kern.tty.ptmx_max` (511 by default), and with 62 live app
 * PTYs, 18 tmux sessions and ~19 ssh children there were 515 `/dev/ttys*` entries. Every spawn from
 * then on failed with a bare `posix_spawnp failed.` — the SAME opaque error a cross-arch
 * spawn-helper produces, which is why the old message sent the report chasing an architecture that
 * was fine.
 *
 * `null` means "could not be measured", which is a different statement from zero and is rendered as
 * silence rather than as a number (same rule as `SpawnResources`).
 */
export interface PtyDevices {
  /** `kern.tty.ptmx_max` — the system-wide ceiling. */
  ceiling: number | null
  /** `/dev/ttys*` entries in existence right now. */
  inUse: number | null
}

/**
 * How close to the ceiling counts as "at" it.
 *
 * Opening a terminal takes a device, and a tmux-backed one takes two in quick succession (the app's
 * client plus, on a cold start, the pane) — so the spawn fails a hair before the count is literally
 * equal, and the count itself is a snapshot taken after the failure, by which time a device or two
 * may already have been returned. Small, because unlike the descriptor check this one names a
 * SYSTEM limit: claiming the machine is full when it has room would be a worse sentence than saying
 * nothing.
 *
 * TWO CONSUMERS NOW, and the slack means something different to each:
 *  - the post-mortem hint above — the reading is a snapshot taken after the fact, so the slack
 *    absorbs devices returned between the failure and the count;
 *  - `PtyManager.spawnSession`'s pre-flight, where it is not slack at all but a PRE-EMPTIVE band:
 *    a refusal starts at `ceiling - 4` (507 of 511), while the machine still has four devices.
 *
 * The band is deliberate, and it is the same arithmetic read forwards. A tmux-backed spawn wants
 * two devices, so a create begun at 508 lands ON the wall rather than under it — and a spawn that
 * reaches the wall does not merely fail, it LEAKS two devices doing so (node-pty; see the
 * pre-flight's comment). Refusing inside the band trades at most four devices of capacity, on a
 * machine already at 99% of a system limit, for the guarantee that no failure-with-leak is ever
 * started. Those four are the cheapest possible price for closing the spiral, and the user is told
 * the true numbers either way.
 */
export const PTY_DEVICE_HEADROOM = 4

/**
 * How long a read of `kern.tty.ptmx_max` is trusted.
 *
 * The value effectively never changes — but a user who follows the advice below and raises it with
 * `sysctl -w` must not be told the same wrong thing for the rest of the session, so it expires.
 */
const CEILING_TTL_MS = 60_000

let ceiling: { value: number | null; at: number } | null = null
let refreshing = false

/**
 * Kick an async read of the ceiling (darwin only). Fire-and-forget by design: `execFile` cannot be
 * awaited from the synchronous spawn path this diagnostic serves, so the value is read AHEAD of the
 * failure (PtyManager.init primes it) and re-read in the background when it goes stale. A read that
 * has not landed yet leaves `ceiling: null`, i.e. the hint stays silent rather than guessing.
 */
export function primePtyCeiling(): void {
  if (os.platform() !== 'darwin' || refreshing) return
  refreshing = true
  try {
    execFile('sysctl', ['-n', 'kern.tty.ptmx_max'], { timeout: 5_000 }, (err, stdout) => {
      refreshing = false
      // A failed/odd read is recorded as `null` WITH a timestamp: on a machine where sysctl is
      // unavailable this stops us re-spawning it on every subsequent spawn failure.
      const parsed = err ? NaN : Number.parseInt(String(stdout).trim(), 10)
      ceiling = { value: Number.isFinite(parsed) && parsed > 0 ? parsed : null, at: Date.now() }
    })
  } catch {
    refreshing = false // diagnostics only — never mask the real spawn error
  }
}

/** The cached ceiling, refreshing in the background once it is stale. */
function ptyCeiling(): number | null {
  if (os.platform() !== 'darwin') return null
  if (!ceiling || Date.now() - ceiling.at >= CEILING_TTL_MS) primePtyCeiling()
  // The stale value is still the best answer we have while the refresh is in flight — it is only
  // stale in the sense of "read a minute ago", and a sysctl that changed since is exactly the case
  // the refresh above is for.
  return ceiling?.value ?? null
}

/**
 * Count the pty devices that exist right now.
 *
 * A directory listing, not a subprocess: this runs inside an error path that is already one failed
 * spawn deep, and shelling out to `ls` to count files would need the very resource that just ran
 * out. `/dev/ttys*` is the macOS naming (`ttys000`, `ttys001`, …): entries are created on demand
 * and RECLAIMED when the pty is closed — measured on this host going 492 → 500 → 492 across a batch
 * of terminals opening and closing. Nothing is cached, so every call is a fresh readdir, which is
 * what lets a machine that just freed some devices spawn again immediately instead of staying
 * refused until a restart. (It is also why a LEAKED master is so costly: a device whose master fd
 * is never closed is never reclaimed either, so it counts against the ceiling until the process
 * that leaked it exits.)
 */
function countPtyDevices(): number | null {
  if (os.platform() !== 'darwin') return null
  try {
    return fs.readdirSync('/dev').filter((name) => name.startsWith('ttys')).length
  } catch {
    return null
  }
}

/** Both numbers, measured now. Fail-open in every direction (see `readSpawnResources`). */
export function readPtyDevices(): PtyDevices {
  return { ceiling: ptyCeiling(), inUse: countPtyDevices() }
}

/** True when the machine has no pty device left to hand out. Unmeasured ⇒ false (stay silent). */
export function ptyDevicesExhausted(d: PtyDevices): boolean {
  if (d.ceiling === null || d.inUse === null) return false
  return d.inUse >= d.ceiling - PTY_DEVICE_HEADROOM
}

/**
 * The ONE sentence a spawn failure ends with, chosen from what was actually measured. Pure, so the
 * wording and the precedence can be pinned.
 *
 * The order matters as much as the wording:
 *  1. `archNote` — the only hint derived from reading THIS build's spawn-helper. When the helper
 *     cannot be exec'd at all, nothing else can be the cause.
 *  2. pty devices — the machine is out of them, so no process can open a terminal until some are
 *     returned. Stated INSTEAD of the generic advice, never alongside it: "rebuild node-pty" is
 *     precisely as wrong here as it was in the 2026-08-06 report.
 *  3. the caller's generic text, which is what it has always been — a guess of last resort.
 */
export function spawnFailureHint(
  archNote: string | null,
  devices: PtyDevices,
  generic: string
): string {
  if (archNote) return archNote
  if (!ptyDevicesExhausted(devices)) return generic
  return (
    `This MACHINE is out of pty devices (${devices.inUse} of ${devices.ceiling} allowed by ` +
    `\`kern.tty.ptmx_max\`), so no process can open a terminal until some are returned — close ` +
    `some terminals (a tmux session's pane holds one too), or raise the limit with ` +
    `\`sudo sysctl -w kern.tty.ptmx_max=<bigger>\`. Rebuilding node-pty will not help.`
  )
}

/**
 * Forget the cached ceiling because something just CHANGED it (the "Fix automatically…" button's
 * `sysctl -w`). Without this the TTL would keep serving the pre-fix number for up to a minute — and
 * the pressure banner it feeds would keep saying the machine is full after it was emptied.
 */
export function invalidatePtyCeiling(): void {
  ceiling = null
}

/** Test seam: forget the cached ceiling so a test can pin the read itself. */
export function resetPtyDevicesCacheForTests(): void {
  ceiling = null
  refreshing = false
}