PTY leak when enableInteractiveShell=true causes system-wide PTY exhaustion on macOS

[jeffery9]

What happened?

PTY leak when enableInteractiveShell=true causes system-wide PTY exhaustion on macOS

Environment

• Gemini CLI: 0.44.x
• Node.js: 24.x
• macOS: (please fill in exact version)
• Running mode: gemini -r
• MCP enabled (Context7 MCP)
• enableInteractiveShell=true

Summary

After running Gemini CLI for an extended period with interactive shell enabled, the process appears to leak PTY-related resources.

Eventually the entire macOS user session becomes unable to allocate new pseudo-terminals.

At that point, not only Gemini fails, but all PTY consumers fail system-wide.

Symptoms

Gemini starts failing with:

forkpty: Device not configured
posix_openpt failed: Device not configured

Then unrelated tools also fail:

script /tmp/test.log

returns:

script: openpty: Device not configured

Python:

import pty
pty.spawn('/bin/bash')

returns:

OSError: out of pty devices

Even sudo becomes unusable:

sudo lsof

returns:

sudo: unable to allocate pty: Device not configured

Diagnostics

Active TTY usage appears low:

lsof | grep /dev/ttys | wc -l

Output:

58

System tty devices:

ls /dev/ttys* | wc -l

Output:

527

Gemini process:

lsof -p <gemini_pid> | wc -l

Output:

1537

Gemini is holding both the current terminal and an internal PTY:

/dev/ttys009
/dev/ttys238

Observed child processes:

bash
bash
tail -f /dev/null

Reproduction

1. Enable interactive shell
2. Run Gemini in long-lived mode:

gemini -r

3. Use the agent for an extended period

4. Eventually PTY allocation starts failing

5. Failure propagates to:

   • Gemini
   • script
   • python pty.spawn()
   • sudo

Workaround

Disable interactive shell:

{
  "tools": {
    "shell": {
      "enableInteractiveShell": false
    }
  }
}

After disabling interactive shell and restarting the user session, the problem disappears.

Expected behavior

Interactive shell sessions should fully release PTY resources after command completion and should not cause system-wide PTY exhaustion.

Additional notes

This may be related to the recent node-pty issues reported in 0.44.x. The issue becomes significantly more visible when running:

• gemini -r
• MCP servers enabled
• long-lived agent sessions
• Node.js 24.x

What did you expect to happen?

no error, no run out of the resources.

Client information

Client Information

Run gemini to enter the interactive CLI, then run the /about command.

> /about
# paste output here

Login information

No response

Anything else we need to know?

No response

[gemini-cli]

Found possible duplicate issues:

• Pseudo-Terminal (PTY) File Descriptor Leak in Gemini CLI #20804
• [BUG] PTY Master Device Exhaustion (ENXIO) on macOS after prolonged usage in YOLO mode #25583
• System-wide PTY exhaustion due to file descriptor leak #15945
• macOS: PTY File Descriptor Leak When Executing Shell Commands #20810
• Leaking ptys on macos #24796
• PTY file descriptor leak on kill() and post-spawn exception (macOS ptmx_max) #21692

If you believe this is not a duplicate, please remove the status/possible-duplicate label.

[gemini-cli]

This issue involves system-wide PTY exhaustion on macOS linked to node-pty usage, which falls under the 'effort/large' guidelines due to platform-specific complexities and resource management intricacies.

This issue describes a critical PTY resource leak that leads to system-wide exhaustion on macOS when interactive shell is enabled. Due to the high impact on the user's system session, it likely requires P0 escalation. Could you please provide your exact macOS version to help us investigate further?

Effort Analysis:
The ShellExecutionService.ts implementation manages pseudo-terminals (PTYs) using node-pty. While it includes cleanup logic via ptyProcess.destroy() in its onExit handler and cleanupPtyEntry methods, several architectural factors point to high complexity. First, killProcessGroup in packages/core/src/utils/process-utils.ts only invokes pty.kill(), which may not immediately release the master file descriptor on macOS if onExit is delayed or suppressed. Second, the executeWithPty method in ShellExecutionService.ts contains a race condition where the finalize function (responsible for disposing the headlessTerminal and removing the entry from the activePtys static Map) depends on a Promise.race between the processingChain and an abortSignal. If the xterm.js headlessTerminal.write callback hangs, or if an error occurs after spawn but before onExit registration, the resource remains partially allocated. The reported diagnostic of 1537 file descriptors versus only 58 active TTYs strongly suggests a leak of master file descriptors or related pipes for every shell invocation. Resolving this requires cross-platform verification of PTY disposal semantics and potentially refactoring the static state management in ShellExecutionService to ensure deterministic cleanup in all failure modes.

[jeffery9]

uname -a
Darwin jeffery-MBP16.local 25.4.0 Darwin Kernel Version 25.4.0: Thu Mar 19 19:33:50 PDT 2026; root:xnu-12377.101.15~1/RELEASE_ARM64_T6050 arm64

 > /about                                                                                                              
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                     │
│ About Gemini CLI                                                                                                    │
│                                                                                                                     │
│ CLI Version                             0.44.1                                                                      │
│ Git Commit                              b9b7416f8                                                                   │
│ Model                                   Auto                                                                        │
│ Sandbox                                 no sandbox                                                                  │
│ OS                                      darwin                                                                      │
│ Auth Method                             gemini-api-key                                                              │
│                                                                                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[gemini-cli]

This item was marked as needing more information and has not received a response in 14 days. Closing it for now. If you still face this problem, feel free to reopen with more details. Thank you!