fix(update): terminate stray venv holder processes on unattended Windows update

[Dolverin]

What does this PR do?

Fixes a permanent dead-end of unattended Windows updates at the venv-process guard.

Today the update flow pauses gateways and then refuses (exit 2) when any other process runs from the install venv. On a busy install that refusal is effectively unconditional: cron job runs spawn pythonw from venv\Scripts at all hours, and abandoned CLI sessions linger. The desktop one-click handoff exits cleanly and launches the updater, the updater dies at the guard, and the next retry simply collides with the next job — the update can never converge without manual process hunting.

Key observation: once _pause_windows_gateways_for_update() has run, the in-gateway cron ticker is stopped too, so nothing spawns replacements. The remaining holders are strays that nothing supervises — killing them is safe, and that is exactly what an unattended update should do instead of dead-ending.

This PR teaches hermes update to converge on unattended runs:

• When holders are detected and --yes is set (the desktop bootstrap updater always passes --yes), terminate them gracefully (psutil terminate(), wait up to 20 s, then kill()), logging each PID + cmdline, then re-scan.
• The refusal still fires when holders persist or reappear (e.g. a supervised desktop backend that respawned) — the re-scan is authoritative, so the safety property of the guard is unchanged.
• Interactive runs (no --yes) keep the plain refusal; the message now hints that --yes clears strays automatically.
• --force-venv semantics are untouched, and the new code path is Windows-gated (_is_windows()), no-op without psutil.

Scope note / related PRs: #61515 reaps gateway-spawned venv children inside the gateway pause (complementary — this PR covers everything the pause legitimately can't: cron job runs, stray CLIs). #62445 kills external holders from the desktop handoff (desktop path only; this PR fixes it in the update flow itself, so plain hermes update CLI runs converge too). #63318 surfaces blockers in the UI (orthogonal).

Related Issue

No tracking issue; reproduction and a live run are included below.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• hermes_cli/main.py
  • new _terminate_venv_python_holders() (graceful → force, bounded waits, never raises)
  • guard wiring: --yes runs terminate strays and re-scan before refusing
  • refusal message gains the --yes hint; _detect_venv_python_processes docstring updated to match the new contract
• tests/hermes_cli/test_update_venv_health.py
  • harness now returns mocks for the detect/terminate helpers
  • new cases: --yes + strays cleared → past guard; holders persist → still exit 2; interactive → never terminates; terminate → force-kill only survivors
  • two older venv-health tests made host-aware (they built a POSIX-layout fake venv without patching _is_windows, so they could only pass off-Windows)

How to Test

1. Start a stray holder: venv\Scripts\pythonw.exe -c "import time; time.sleep(600)"
2. Run hermes update --yes --force --branch main
3. The log shows → Terminating venv holder PID …, the holder is gone, and the update proceeds instead of exiting 2.

Unit: pytest tests/hermes_cli/test_update_venv_health.py -q → 22 passed.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate (see scope note above: fix(update): reap gateway venv children so the Windows venv guard self-clears #61515, fix(desktop): kill external windows venv holders #62445, fix(desktop): surface external venv update blockers #63318)
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run the affected tests (pytest tests/hermes_cli/test_update_venv_health.py -q — 22 passed; full suite not run locally)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Windows 11 (26100), Python 3.11

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A — docstrings updated; no user-facing docs affected
• I've updated cli-config.yaml.example if I added/changed config keys — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — new behavior is Windows-gated; other platforms unchanged
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Screenshots / Logs

Live unattended update on an install that had been dead-ended for two days (stray holder planted deliberately):

→ Stopping Windows gateway process(es) before updating Hermes...
  ✓ Paused gateway profile(s): default
→ Clearing stray Hermes venv process(es) before the dependency sync…
  → Terminating venv holder PID 59476 (pythonw.exe): C:\...\hermes-agent\venv\Scripts\pythonw.exe -c import time; time.sleep(1800)
→ Fetching updates...
→ Found 43 new commit(s)
...
✓ Update complete!
  ✓ Restarting Windows gateway profile(s): default

[alt-glitch]

This was generated by AI during triage.

Related to #61515 and #62445: this targets the hermes update --yes post-pause lifecycle, while those repair gateway-child and Desktop-handoff holder paths. The termination-policy scope needs a maintainer choice.

[teknium1]

Thanks for isolating the post-pause venv-holder path. Current main does retain the reported refusal at hermes_cli/main.py:9847-9851.

Problems

• hermes_cli/main.py:9916 terminates every detector match, but the detector includes the Desktop serve backend (hermes_cli/main.py:9262-9276). Current main deliberately refuses that backend because it is supervised and can respawn (hermes_cli/main.py:9836-9845). The sole immediate re-scan at hermes_cli/main.py:9917 can be clean before a later respawn, reopening the .pyd-lock race the guard protects against. The new test at tests/hermes_cli/test_update_venv_health.py:376-381 covers only a holder still present at that immediate scan.
• This makes --yes process-destructive, while the unchanged parser help (hermes_cli/subcommands/update.py:47-51) and updating guide (website/docs/getting-started/updating.md:105) describe it as prompt automation and instruct users to close holders or use --force-venv.

Suggested changes

• Preserve refusal for Desktop-supervised/external holders, or add a tested stable-quiescence lifecycle before update mutation.
• Document any approved destructive --yes behavior.

Automated hermes-sweeper review.

[teknium1]

_detect_venv_python_processes() includes the Desktop serve backend, while current main explicitly treats killing that supervised process as a race because it can respawn. A single immediate re-scan can be clean before the supervisor restarts it. Exclude supervised/external holders or add a bounded, tested quiescence check before allowing dependency mutation.

[Dolverin]

Closing this PR because the current implementation broadens --yes into terminating every detected venv holder, including the Desktop-supervised serve backend. The immediate re-scan does not prove stable quiescence before mutation, so it can reopen the lock race the existing fail-closed guard prevents. The safer contract remains: refuse supervised/external holders, use the external Desktop handoff, and require the explicit --force-venv override when the operator accepts that risk. Any future automatic-quiescence work should be a separate, lifecycle-proven design.