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

[briandevans]

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.

[Copilot]

Pull request overview

This PR reduces noisy gateway shutdown notifications by skipping the home-channel broadcast on plain shutdown when there are no active sessions, while preserving the existing /restart behavior (home channels still get pinged even when idle).

Changes:

• Add an early-return in GatewayRunner._notify_active_sessions_of_shutdown() to skip home-channel shutdown notifications when active == {} and _restart_requested is false.
• Add tests to ensure (a) idle plain shutdown does not ping home channels and (b) shutdown with at least one active session still pings both the active chat and the home channel.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
gateway/run.py	Adds an idle + non-restart guard to suppress home-channel shutdown broadcasts when nothing is running.
tests/gateway/test_restart_notification.py	Adds regression tests for idle-skip behavior and confirms home-channel notifications still occur when sessions are active.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[briandevans]

Rebased onto current origin/main (839cdd1b0) — picked up an additive merge conflict with #20103-adjacent test test_shutdown_notifications_use_cached_live_thread_source_when_origin_missing and the defensive list(self.adapters.items()) snapshot guard. Resolution preserves both the new HEAD test and the idle-skip + regression-guard tests, plus keeps the snapshot-iteration safety. Focused suite green: tests/gateway/test_restart_notification.py 27/27 passing including the three relevant scenarios.

[briandevans]

Closing to keep the queue clean — branch is several hundred commits behind main and never picked up a review. Happy to reopen if the underlying fix is still useful.