[brianKing88]

Problem

After ~2.5 days of normal use, nothing on the host could open a terminal any more — not the plugin, not the user's own emulator:

# Ghostty
Your system cannot allocate any more pty devices.

# Terminal.app
[forkpty: Device not configured]

The plugin server was holding 508 /dev/ptmx handles with zero live children:

$ lsof /dev/ptmx | awk 'NR>1{print $1}' | sort | uniq -c | sort -rn
 508 node        # cloudcli-plugin-terminal/dist/server.js, up 2d10h
   2 Claude
   1 zed

$ ls /dev/ttys* | wc -l      # 527
$ sysctl -n kern.tty.ptmx_max # 511

Zero children, 508 master fds: the shells were long gone, the fds were not.

Cause

killSession() tears a session down with pty.kill(), which on POSIX is process.kill(pid, SIGHUP) and nothing else:

UnixTerminal.prototype.kill = function (signal) {
  try { process.kill(this.pid, signal || 'SIGHUP'); } catch (e) { /* swallow */ }
};

node-pty closes the master fd from its own exit handler, so the fd comes back only if the shell actually dies from that SIGHUP. A shell that traps the signal, or that sits in a foreground job outliving the session, keeps the fd for the lifetime of the plugin server. Every detached-and-reaped session strands one.

PTYs are a fixed machine-wide resource (kern.tty.ptmx_max on macOS, 511 by default; /proc/sys/kernel/pty/max on Linux), so this is not a slow memory creep — it eventually takes the whole machine's terminal capability down with it.

destroy() is the API that actually releases the fd: it closes the socket first and signals afterwards, which is safe on both a live and an already-exited shell.

Fix

Teardown goes through a new disposePty() that prefers destroy() and falls back to kill() on a node-pty that does not expose it. destroy() is declared optional on PtyProcess because node-pty's public typings omit it, although both UnixTerminal and WindowsTerminal implement it.

The onExit path calls it too — node-pty's close chain has only a timeout fallback there, and destroy() is a no-op once the socket is down, so the insurance is free.

Measurements

20 sessions, each a shell that traps SIGHUP (trap '' HUP; sleep 300), torn down the way killSession() does it. fds stranded per session:

node-pty	kill()	destroy()
1.1.0 (currently pinned)	3	2
1.2.0-beta.18	1	0

Repro, if you want to confirm it independently:

import { execSync } from 'node:child_process';
import pty from 'node-pty';

const mode = process.argv[2];                       // kill | destroy
const count = () => execSync(`lsof -p ${process.pid}`).toString()
  .split('\n').filter((l) => /\/dev\/(ptmx|ttys)/.test(l)).length;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const before = count();
for (let i = 0; i < 20; i++) {
  const p = pty.spawn('/bin/sh', [], { cols: 80, rows: 24, encoding: 'utf8' });
  p.onData(() => {}); p.onExit(() => {});
  p.write("trap '' HUP\nsleep 300\n");
  await sleep(120);
  try { mode === 'destroy' ? p.destroy() : p.kill(); } catch {}
}
await sleep(2000);
console.log(`${mode}: ${(count() - before) / 20} fd per session`);

Relationship to the open PRs

• fix: bump node-pty to ^1.2.0-beta.12 so the plugin works on Linux #15 (bump node-pty to the 1.2.0-beta line) — the table above is independent evidence for that bump: 1.1.0 leaks regardless of how teardown is done, so this change alone takes it from 3 to 2 fds per session, and only reaches 0 on top of fix: bump node-pty to ^1.2.0-beta.12 so the plugin works on Linux #15. Happy to rebase or drop anything here if fix: bump node-pty to ^1.2.0-beta.12 so the plugin works on Linux #15 lands first.
• Fix "posix_spawnp failed" by restoring node-pty spawn-helper execute bit #12 (spawn-helper execute bit) — unrelated to the leak and already covered there; deliberately left out of this PR. For what it is worth, I hit that one too on a fresh install (prebuilds/darwin-arm64/spawn-helper unpacked as 0644, every spawn failing posix_spawnp failed, 9 of 24 tests red), so it is still reproducible on main.

Verification

• npm run typecheck — clean
• npm test — 21/24, the same 3 failures as main with this patch stashed, so no regression. They are pre-existing and environmental: one asserts a cwd path that macOS resolves through the /var → /private/var symlink, two time out matching shell output.
• Ran the patched plugin under CloudCLI for the session that produced this report: 0 PTY fds held, pool back to 10/511.

🤖 Generated with Claude Code