Skip to content

The agent that grows with you

fix(gateway): stamp the planned-restart marker from the CLI restart

Leegenux86a61729d3e8
diff --git a/gateway/restart_notice.py b/gateway/restart_notice.py
new file mode 100644
index 00000000000..db12057e216
--- /dev/null
+++ b/gateway/restart_notice.py
@@ -0,0 +1,39 @@
+"""Planned-restart marker: the CLI stamps it so the next boot says the gateway is back online.
+
+The gateway writes one itself only when the restart is in-band (SIGUSR1 / pause-for-update). A CLI
+``stop`` + ``start`` — always on Windows, which has no SIGUSR1 — is otherwise indistinguishable from
+a plain stop, and the boot pass skips the "Gateway online" home-channel notice
+(``gateway/run_notifications.py::_send_home_channel_startup_notifications``).
+
+The reader is ``gateway/run.py::_planned_restart_notification_path``; the roundtrip test in
+``tests/gateway/test_planned_restart_marker_cli.py`` pins the two together.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from pathlib import Path
+
+from hermes_constants import get_process_hermes_home
+from utils import atomic_json_write
+
+PLANNED_RESTART_MARKER_FILENAME = ".restart_pending.json"
+
+
+def planned_restart_marker_path() -> Path:
+ return get_process_hermes_home() / PLANNED_RESTART_MARKER_FILENAME
+
+
+def write_planned_restart_marker() -> None:
+ """Record that the running gateway is going down FOR A RESTART; never blocks the restart.
+
+ Best-effort like ``gateway.status.write_planned_stop_marker``: an unwritable home costs the
+ notice, not the restart.
+ """
+ with contextlib.suppress(OSError):
+ atomic_json_write(
+ planned_restart_marker_path(),
+ {"requested_at": time.time(), "via_service": False, "detached": False},
+ indent=None,
+ )
diff --git a/hermes_cli/gateway_windows.py b/hermes_cli/gateway_windows.py
index 16640969295..f49d90e3cf2 100644
--- a/hermes_cli/gateway_windows.py
+++ b/hermes_cli/gateway_windows.py
@@ -1862,12 +1862,24 @@ def _wait_for_gateway_absent(timeout_s: float = 30.0, interval_s: float = 0.5) -
return _absent()
+def _mark_planned_restart() -> None:
+ """Stamp the planned-restart marker before ``stop()``.
+
+ Windows has no SIGUSR1, so ``restart()`` is stop + start: the gateway never runs the in-band
+ restart path that stamps this marker itself, and the next boot would read a plain stop and skip
+ the "Gateway online" home-channel notice.
+ """
+ from gateway.restart_notice import write_planned_restart_marker
+ write_planned_restart_marker()
+
+
def restart() -> None:
"""Stop then start. Waits for the old gateway to be authoritatively gone first; otherwise
``start()``'s "already running" guard sees the draining process and no-ops, and nothing
replaces it when it exits (a silent outage). Fails loudly on either side."""
_assert_windows()
+ _mark_planned_restart()
stop()
if not _wait_for_gateway_absent(timeout_s=30.0):
diff --git a/tests/gateway/test_planned_restart_marker_cli.py b/tests/gateway/test_planned_restart_marker_cli.py
new file mode 100644
index 00000000000..0fefddc9feb
--- /dev/null
+++ b/tests/gateway/test_planned_restart_marker_cli.py
@@ -0,0 +1,54 @@
+"""A CLI ``restart`` must stamp the planned-restart marker itself.
+
+The gateway writes ``.restart_pending.json`` only on an in-band restart (SIGUSR1 / pause-for-update).
+``hermes gateway restart`` on Windows is ``stop()`` + ``start()`` — Windows has no SIGUSR1 — so
+without a CLI writer the next boot reads a plain stop and never sends the "Gateway online" notice to
+the configured home channels.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from gateway import run as gateway_run
+
+MARKER = ".restart_pending.json"
+
+
+def hermes_home(tmp_path, monkeypatch):
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+ monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+ return tmp_path
+
+
+def test_writer_stamps_the_marker_the_boot_pass_reads(hermes_home):
+ """Writer and reader must agree on path and payload; a rename on either side fails here."""
+ from gateway.restart_notice import write_planned_restart_marker
+
+ assert gateway_run._planned_restart_notification_pending() is False
+
+ write_planned_restart_marker()
+
+ assert (hermes_home / MARKER).exists()
+ assert gateway_run._planned_restart_notification_pending() is True
+
+
+def test_windows_restart_stamps_the_marker_before_stopping(hermes_home, monkeypatch):
+ """Ordering is the whole fix: ``stop()`` must already see the marker on disk."""
+ from hermes_cli import gateway as gw_facade
+ from hermes_cli import gateway_windows as gw
+
+ seen: dict[str, bool] = {}
+ monkeypatch.setattr(gw, "_assert_windows", lambda: None)
+ monkeypatch.setattr(gw, "_wait_for_gateway_absent", lambda timeout_s=30.0: True)
+ monkeypatch.setattr(gw, "_wait_for_gateway_ready", lambda timeout_s=15.0: True)
+ monkeypatch.setattr(gw_facade, "_wait_for_api_server_port_free", lambda: None)
+ monkeypatch.setattr(
+ gw, "stop", lambda: seen.setdefault("marker_at_stop", (hermes_home / MARKER).exists())
+ )
+ monkeypatch.setattr(gw, "start", lambda: None)
+
+ gw.restart()
+
+ assert seen["marker_at_stop"] is True