fix: kill entire process tree on Windows to prevent GUI program hang (#54201)

[Sahil-SS9]

Fixes #54201

Description

On Windows, running GUI .exe programs through the terminal tool causes the session to hang indefinitely. The root cause is twofold:

1. _kill_process only calls proc.terminate() on Windows, which kills the bash wrapper but not its children. GUI programs launched from bash inherit the stdout pipe and keep it open even after bash exits, causing the drain thread in _wait_for_process to block forever.

2. No documentation warns users about this behavior or provides the workaround.

Changes

• tools/environments/local.py: Replace proc.terminate() on Windows with taskkill /F /T /PID to kill the entire process tree rooted at bash. Falls back to proc.terminate() if taskkill fails.

• tools/terminal_tool.py: Add documentation note about Windows GUI programs and the PowerShell Start-Process workaround.

Verification

• Compile check passed for both modified files
• No secrets or personal references leaked
• Conventional commit format
• Only fix files changed, no unrelated modifications

[alt-glitch]

This was generated by AI during triage.

Duplicate of #49460 — both replace the Windows branch of _kill_process in tools/environments/local.py (proc.terminate() -> taskkill /T /F /PID), the same code site and mechanism. #49460 is the earlier, cleaner version (uses windows_hide_flags() + stdin=DEVNULL). This PR additionally adds a terminal_tool.py docstring note about the Start-Process workaround. Cross-linking to the target issue #54201 and sibling #43499; a maintainer should pick the canonical fix.

[tonydwb]

Code Review Summary

Verdict: Approved

Fix for Windows process tree kill (2 files, +53/-1). Uses taskkill /F /T /PID instead of proc.terminate() to kill the entire process tree on Windows, preventing GUI programs from hanging the drain thread.

Strengths:

• Falls back to proc.terminate() if taskkill fails (3s timeout)
• Good documentation in the tool description about Windows GUI program behavior
• Addresses a real issue (#54201) where inherited stdout pipes cause indefinite blocking

Notes:

• The subprocess.run with capture_output=True and 3s timeout is appropriate
• The fallback pattern is correct -- taskkill failure should not crash the session

No security concerns. The fix is scoped to Windows-only code paths.

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: LGTM

Kills the entire process tree on Windows using taskkill /F /T instead of proc.terminate() which only kills the bash wrapper. Falls back to proc.terminate() if taskkill fails. Also adds a helpful docstring note about GUI program hangs on Windows.

Reviewed by Hermes Agent

[teknium1]

Thanks for documenting the Windows GUI-process failure mode. This automated hermes-sweeper review verified that the requested process-tree cleanup is already implemented on current main.

• Commit e5253d852b24f87af91d77b66141cc5c0b9e6f69 (merged through fix(desktop): tree-kill Windows terminal descendants #55547) changed tools/environments/local.py:1133-1143 to route Windows cleanup through terminate_pid(proc.pid, force=True).
• gateway/status.py:98-125 implements that operation with taskkill /PID <pid> /T /F, including the wrapper's descendants.
• tools/environments/base.py:740-756 calls this cleanup path after terminal-command timeout, and tests/tools/test_local_interrupt_cleanup.py:100-123 covers the Windows branch.
• The current PR diff contains only the two-line terminal-tool description note; the production fix it describes has already landed.

Closing as implemented on main.