fix(gateway): use via_service for macOS restart to avoid KeepAlive race

[drzeast-png]

Problem

On macOS launchd, KeepAlive=true restarts the gateway on any exit (same semantics as systemd Restart=always). However, the in-chat /restart path was hardcoded to use detached=True, which spawns a shell watcher that:

1. Polls the old PID
2. After the old gateway exits, runs hermes gateway restart

This races with launchd's KeepAlive:

• Watcher starts → old gateway is dying
• KeepAlive (which is faster) launches a new gateway first
• Watcher sees old PID gone, thinks it's safe to run hermes gateway restart
• New gateway gets SIGTERM → dies
• KeepAlive restarts again → another watcher spawns
• → kill loop that eventually unloads the launchd job

Solution

Make Darwin match systemd by using via_service=True so the gateway exits cleanly and launchd restarts it natively. No watcher, no hermes gateway restart CLI, no racing.

Diff (1 line, in gateway/run.py)

- if _under_service or _in_container:
+ if _under_service or _in_container or sys.platform == "darwin":
      self.request_restart(detached=False, via_service=True)

Behavior comparison

Scenario	Before (detached=True)	After (via_service=True)
Linux systemd restart	✅ via_service (correct)	✅ via_service
Linux Docker restart	✅ via_service (correct)	✅ via_service
macOS launchd restart	❌ detached watcher → race	✅ via_service
Manual restart (no supervisor)	✅ detached watcher (correct)	✅ detached watcher

Test plan

• Trigger /restart from WeChat on macOS — gateway restarts cleanly, no kill loop
• launchd launchctl list | grep hermes shows new PID after restart
• No 'detached helper' log lines after restart
• Companion PR (drop _HERMES_GATEWAY guard) unblocks the restart path itself

[liuhao1024]

I found an issue that looks worth fixing before merge.

gateway/run.py:10627

The change if _under_service or _in_container or sys.platform == "darwin" unconditionally treats every macOS process as service-managed. When via_service=True, the gateway exits with code 75 (SystemExit(75) at line 19276) — this only works when a service manager (launchd's KeepAlive) is watching. A bare macOS Terminal process (hermes gateway) would exit 75 with nothing to restart it.

Why it matters: Any macOS user running the gateway from Terminal (not under a launchd plist) would lose their gateway on /restart — it exits 75 and stays dead.

Suggested fix: Detect actual launchd management instead of blanket-darwin. PR #37094 (same issue, same file) does this correctly by checking XPC_SERVICE_NAME:

_under_launchd = sys.platform == "darwin" and os.environ.get(
    "XPC_SERVICE_NAME", "0"
) not in ("", "0")

launchd sets XPC_SERVICE_NAME to the job label (e.g. ai.hermes.gateway-alex) for managed jobs and "0" for shell-launched processes. This is the same signal used by the systemd INVOCATION_ID check two lines above.

[liuhao1024]

I found an issue with the scope of this fix.

gateway/run.py:10627 — the condition sys.platform == "darwin" applies via_service=True (exit 0) to all macOS processes, including bare shell-launched ones that are NOT managed by launchd. For a shell-launched gateway, exiting 0 means nothing relaunches it — the gateway stays dead until manual recovery.

The comment says "Launchd on macOS has KeepAlive=true which restarts the gateway on any exit" — but this is only true for launchd-managed jobs. A bare python gateway/run.py process on macOS has no KeepAlive; the via_service=True path would silently kill it.

There's a more precise fix in PR #37094 that checks XPC_SERVICE_NAME (which launchd sets to the job label for managed processes, and "0" for shell-launched ones):

_under_launchd = sys.platform == "darwin" and os.environ.get(
    "XPC_SERVICE_NAME", "0"
) not in ("", "0")

This correctly detects launchd-managed processes without affecting bare shell-launched ones. I'd recommend closing this in favor of #37094.

[austinpickett]

✅ Approved

Three complementary fixes in one coherent PR from the same author:

1. via_service=True on macOS (gateway/run.py): launchd KeepAlive restarts the gateway on ANY exit (same semantics as Restart=always). Adding sys.platform == "darwin" to the existing _under_service or _in_container gate routes Darwin through request_restart(via_service=True) — clean exit, no detached watcher shell racing with KeepAlive. Correct fix.

2. Remove _HERMES_GATEWAY blanket guard (hermes_cli/gateway.py): With via_service now used on macOS, the guard is no longer needed there. On Linux/systemd the INVOCATION_ID path already handles it. The guard was incorrectly blocking legitimate in-chat hermes gateway restart from messaging platforms.

3. WeChat _is_stale_session_ret hardening: ret=-3 is exclusive to stale-session (never rate-limiting), so removing the errmsg gate for it is correct. Explanatory docstring added.

Note: See my comment on #37057 (companion PR) — recommend closing that in favor of this one which is the complete fix.

[teknium1]

Thanks for the macOS restart investigation. The title fix is now implemented on current main through a more precise launchd probe.

Problems

• The PR’s blanket Darwin condition would route interactive macOS gateways through the service path. Current main checks XPC_SERVICE_NAME at gateway/slash_commands.py:1302-1309; tests/gateway/test_restart_service_detection.py:57-64 verifies that XPC_SERVICE_NAME="0" stays on detached restart.
• Commit abc3662bf6076045e4d4dc1e14a74cb35d69b86e (/restart bricks a launchd-managed gateway on macOS — exits 0, KeepAlive.SuccessfulExit=false won't revive it #43475) already delivers the launchd behavior and coverage, after this handler moved out of gateway/run.py.
• The Weixin and _HERMES_GATEWAY guard changes are separate concerns and are not covered by the superseding macOS fix.

Suggested changes

• Re-scope any salvage to independently justified Weixin behavior with focused regression tests; do not retain the superseded blanket-Darwin hunk.
• Evaluate the guard removal separately against current main’s restart-loop protections.

Automated hermes-sweeper review.