fix(gateway): classify planned service restarts

[dorukardahan]

Summary

Classifies service-managed gateway restarts as planned service restarts instead of unexpected external kills or --replace takeovers:

• adds a dedicated .gateway-planned-service-restart.json marker
• validates marker PID + process start time to avoid PID-reuse false positives
• consumes/clears stale or matched markers so they cannot affect later unrelated signals
• surfaces the marker in shutdown forensics
• preserves takeover marker semantics for actual --replace flows

Root cause

v0.18.0 has restart/takeover markers, but a normal service-manager restart sends the same SIGTERM shape as an unexpected external kill. Reusing the takeover marker makes operator logs misleading; having no marker misclassifies planned service restarts.

Related open issues

• Relates to fix(gateway): ExecStop should write planned-stop marker instead of inferring signal source #42517 and [Bug]: gateway exits code 1 (→ unit 'failed') on systemctl stop; planned stops should exit 0 #41631 around planned stop/restart marker semantics. This PR keeps the change focused on service-managed restart classification and shutdown forensics; it does not change adapter startup/shutdown ordering.

Related merged precedent

• fix(gateway): abort startup during restart #55565, fix(gateway): guard stale /restart redelivery when dedup marker is missing #56107, and fix(gateway): revive gateway on /restart under system-scope + Restart=on-failure units #56362 show the gateway restart/shutdown path is accepted when the PR is small, marker/freshness semantics are explicit, and tests cover stale/malformed cases.

Scope / risk

• Best-effort marker only; restart proceeds even if the marker cannot be written.
• Marker TTL and process start-time check bound stale/PID-reuse risk.
• Does not change adapter startup/shutdown ordering.

Verification

• python -m pytest tests/gateway/test_status.py
• python -m py_compile gateway/status.py gateway/run.py gateway/shutdown_forensics.py tests/gateway/test_status.py
• git diff --check
• GitHub: all required checks pass on current head 878298a27f59

[teknium1]

Thanks for the careful PID/start-time and stale-marker handling. The current patch is incomplete, however.

Problems

• The new marker is never written by production code. gateway/status.py adds write_planned_service_restart_marker(), and gateway/run.py consumes it, but gh pr diff 57419 contains no call to the writer. The planned-service-restart branch therefore cannot run.
• The added tests cover helper serialization/consumption only; they do not exercise a restart initiator and the signal-handler classification together.
• Current main has changed restart mechanics: hermes_cli/gateway.py:3299-3356 first attempts SIGUSR1/exit-75 restart handling and falls back to systemctl restart. The salvage needs to integrate with that live flow rather than only adding a signal-handler marker consumer.

Suggested changes

• Write the marker immediately before the applicable current SIGTERM/service-restart operation, using its target PID.
• Add an end-to-end unit-level test for writer → signal handler classification, including the current fallback path.

Automated hermes-sweeper review.

[dorukardahan]

Refreshed onto current main at 3be565fbdee3115ab5b9338551768b8e5e655c56 and closed the missing producer path from the earlier review.

The planned-service-restart marker is now written immediately before the existing forced service-restart operations:

• systemd fallback after the graceful SIGUSR1 restart does not complete
• launchd fallback before terminating the running gateway

The focused integration test exercises the real systemd initiator order and verifies that the marker consumer classifies the target as planned before systemctl restart; the launchd test asserts marker-before-SIGTERM ordering.

Validation on candidate 618dd7c185126423abe7b0ca9c49d217f6ad4801:

• 195 passed across test_status.py, test_shutdown_forensics.py, test_gateway_shutdown.py, and test_gateway_service.py
• new focused integration tests: 2 passed
• Ruff, py_compile, and PR-delta git diff --check: clean