PR #20126: fix(gateway): skip home-channel shutdown ping when idle (#20103)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/20126

Description (problem / solution / changelog)

Summary

• Skip the home-channel shutdown broadcast when no session was active and the shutdown is not a user-initiated /restart.
• Preserves the existing /restart behaviour: home channels are still notified even when idle (existing test enshrines this for ops-watcher heartbeat reasons).
• Mirrors the symmetric startup gate at _send_home_channel_startup_notifications (gateway/run.py:3332), which only fires when /restart was pending.

The bug

_notify_active_sessions_of_shutdown broadcasts \"⚠️ Gateway shutting down — Your current task will be interrupted.\" to every configured home channel unconditionally. For deployments with a daily systemd-timed reboot of an idle gateway, this produced a spurious daily ping in every home channel — there was no task to interrupt, so the warning carried no signal.

The reporter (#20103) hits this on a Weixin home-channel deployment with a 4 AM systemd reboot.

The fix

In gateway/run.py:_notify_active_sessions_of_shutdown, after the active-session loop and before the home-channel loop, skip the home-channel broadcast when:

• active == {} (no running agents) and
• self._restart_requested is False (plain shutdown, not /restart)

if not active and not self._restart_requested:
    logger.info(
        \"No active sessions at shutdown — skipping home-channel notification\"
    )
    return

The /restart path is intentionally preserved because:

• An existing test (tests/gateway/test_restart_resume_pending.py::test_restart_notifies_home_channel_even_without_active_sessions) explicitly asserts the home channel is notified even with no active sessions on /restart.
• /restart is user-initiated; ops watchers depend on the heartbeat to know the gateway will be back.

This matches the issue reporter's recommended Option A: a one-shot guarded early-return, no new config knobs.

Test plan

• Two new tests in tests/gateway/test_restart_notification.py:
  • test_plain_shutdown_skips_home_channel_when_idle — asserts adapter.send is not called when _restart_requested=False and _running_agents={}.
  • test_shutdown_still_pings_home_channel_when_active — asserts the home channel is still notified when at least one session is active in a different chat (regression guard for the home-channel loop entry).
• Existing test test_restart_notifies_home_channel_even_without_active_sessions still passes — the /restart path is unchanged.
• Adjacent suites pass: tests/gateway/test_restart_notification.py (23), tests/gateway/test_gateway_shutdown.py, tests/gateway/test_shutdown_cache_cleanup.py, tests/gateway/test_restart_drain.py, tests/gateway/test_restart_resume_pending.py — 114 passed.
• Regression guard verified: stashing the production fix causes only test_plain_shutdown_skips_home_channel_when_idle to fail with the exact bug behaviour (`adapter.send` called once with the home-channel ping); restoring the fix passes both tests.

Related

• Fixes #20103

Sibling code paths that may need the same fix: none. The startup-side already gates home-channel notifications on restart_notification_pending or delivered_restart_target is not None (gateway/run.py:3332); this PR brings the shutdown side into the same shape. Happy to widen if any other gateway broadcast sites need the same idle-skip treatment.

Changed files

• gateway/run.py (modified, +15/-0)
• tests/gateway/test_restart_notification.py (modified, +65/-0)