[benfriebe]

Closes #370

Problem

Every terminal Kelpi ends leaves a /dev/ptmx (a whole pty pair) and a kqueue open in the process that spawned it. macOS has 511 ptys for the whole machine. Since #274 that process is the terminal host, which survives daemon restarts and handoffs, so the leak builds up over weeks until New Pane, and every other terminal app on the Mac, can't open a pty.

Cause

Two bugs in node-pty 1.1.0's macOS native code, both fixed upstream:

• fix: /dev/ptmx leak on macOS microsoft/node-pty#882: pty_posix_spawn opens low_fds[0] with posix_openpt on every spawn, and its cleanup loop never closes index 0.
• fix: close kqueue fd in SetupExitCallback on macOS microsoft/node-pty#931: SetupExitCallback opens a kqueue per terminal to wait for its exit and never closes it.

1.2.0-beta.15 has both. 1.1.0 is still npm's latest.

Change

• node-pty is pinned to 1.2.0-beta.15 (exact, so it can't float to a later beta). For Kelpi, nothing else in the bump matters:
  • The native-module lookup and the spawn-helper path are unchanged, and so are the dependencies and install scripts.
  • resize() gains an optional pixel-size argument.
  • Spawn failures give real error messages instead of posix_spawnp failed..
• New packages/daemon/src/host/pty-release.test.ts:
  • It runs an in-process terminal host on the real spawner, warms it up, then ends 10 shells: 5 hung up (what closing a pane does) and 5 by typing exit.
  • It then checks with lsof that every /dev/ptmx and kqueue fd opened since the baseline has closed.
  • It compares fd numbers, not counts, so a close elsewhere can't hide a leak.
  • It runs on macOS only, in a file of its own so its process holds no other test's terminals.
• scripts/node-pty-exec-bit.mjs is deleted (A fresh worktree's pnpm install leaves node-pty's spawn-helper non-executable: 22 test failures, and dev-instance terminal panes die on creation #36). The beta ships spawn-helper as 0755, and the script's own header asked to be deleted once that happened. That removes the root postinstall, the --check step in pnpm test, and the pre-flight in dev-instance.mjs. The host runtime copy and stage-payload.mjs still set the bit on their copies; only their comments changed.
• docs/terminal-host.md: §11 now says that only a full stop or its own idle exit retires a host. §12 lists the new test.

Hosts already running

No code change here, by choice. An in-app update or kelpi daemon restart hands every terminal to the host already running. That host keeps node-pty 1.1.0, and keeps leaking, until one full stop: kelpi daemon stop (or kelpid stop), then reopen. The full stop ends every shell, and it also frees the ptys that host has already leaked. Two ways to do this automatically, neither done here:

• Bump the host protocol H. The first boot ends the old host, which kills every shell once on update.
• Drain. New terminals go to a new host while the old one keeps its terminals until they end (§11's future upgrade path).

Testing

• The new test on node-pty 1.1.0 (origin/main) fails: all 10 ptmx and all 10 kqueue fds stay open. On this branch it passes.
• A standalone node-pty probe: 10 shells on 1.1.0 left +10 ptmx and +10 kqueue. On the beta: 0 and 0.
• A fresh install with --ignore-scripts gets spawn-helper as -rwxr-xr-x straight from the tarball.
• pnpm check: root 643 files / 10291 tests passed, shell 57 files / 1057 tests passed.
• node scripts/verify.mjs --full: typecheck, root tests, shell tests, bundles, the full audit and the packaged smoke all passed. The packaged smoke loaded node-pty from inside the bundle, ran a real PTY, and kept the shell's pid and scrollback across a SIGUSR2 handoff.
• The scenario lane failed:
  • plugin-pane-chrome, plugin-pane-search and terminal-link-hover were red in the full lane and green when re-run alone.
  • plugin-settings-presenter was red alone too, on its last check: the cleanup leaves the Settings overlay open ("closed":false). The same check fails the same way on unmodified origin/main, so the red was there before this change.

Reviewer notes

A fresh Claude session and Codex reviewed the branch. Codex found nothing to act on; it also staged the daemon payload and spawned a PTY from it. Claude raised three low-severity points, all fixed:

• The new doc paragraph said nothing but a full stop retires a host; the host's idle exit was missing.
• The test compared counts; it now compares fd numbers.
• The test ran lsof by bare name; it now uses /usr/sbin/lsof.

Not covered

• No hand test in the app yet.
• Automatic retirement of hosts that are already running (above).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PzEkyw1X9oNR7zXuTPuCz2