Problem statement

The dashboard chat runs the real TUI through PtyBridge. After extended dashboard use, child helper processes such as tui_gateway.slash_worker can survive chat teardown. Those orphaned helpers accumulate and eventually exhaust available PTY devices, causing new dashboard chats to fail with:

Chat failed to start: out of pty devices

This primarily affects long-running local dashboard users who open/close or reconnect chat sessions over time.

Root cause

PtyBridge.close() only sent teardown signals to the PTY leader process via self._proc.kill(sig). The TUI can spawn helper children under the same process group, and killing only the leader does not reliably terminate those descendants. The process tree outlives the dashboard chat session, leaking PTY-backed resources.

Fix approach

• Capture the child process group id with os.getpgid(self._proc.pid).
  • Identifies the PTY subtree that should receive terminal-close signals.
• Send SIGHUP, then SIGTERM, then SIGKILL to the full process group with os.killpg(pgid, sig).
  • Preserves the existing escalation behavior while including helper children.
• Fall back to the existing single-process kill path if the process group cannot be resolved.
  • Preserves previous behavior for races where the process is already gone or group lookup fails.
• Add focused unit coverage using fake process objects.
  • Verifies group signaling without depending on timing-sensitive real subprocess trees.

Test coverage

Added tests in tests/hermes_cli/test_pty_bridge.py:

• test_close_signals_child_process_group
  • Verifies close() uses os.killpg() when a process group is available and does not fall back to single-process kill().
• test_close_falls_back_to_single_process_signal_when_group_unknown
  • Verifies the existing self._proc.kill() path is still used if os.getpgid() fails.

Targeted test command:

scripts/run_tests.sh tests/hermes_cli/test_pty_bridge.py

Risk assessment

Low-to-moderate risk. The PTY bridge is already POSIX-only, and process-group teardown is the correct lifecycle boundary for an embedded terminal session. The main compatibility risk is that any child process intentionally meant to survive the dashboard TUI will now be terminated; for dashboard chat teardown, that is the desired behavior because helper descendants are session-owned. Fallback preserves the previous behavior if process-group lookup is unavailable.