Skip to content

hermes update via gateway leaves launchd service unrestarted on macOS #28135

@ucsdsu

Description

@ucsdsu

Environment: macOS, hermes installed as a launchd user agent (~/Library/LaunchAgents/ai.hermes.gateway.plist).

Symptom: Triggering hermes update from within the gateway (e.g. via Telegram chat command) shuts down the gateway but does not bring it back. Manual hermes gateway start is required to recover. Status afterward shows LastExitStatus = 0.

Root cause: Two pieces of code disagree about the exit-code contract.

  1. The generated plist (hermes_cli/gateway.py:2846-2850) uses:
    <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
    i.e. only relaunch on a non-zero exit.
  2. launchd_restart() (hermes_cli/gateway.py:3021) prefers a graceful SIGUSR1-driven self-restart via _request_gateway_self_restart(). That path lets the gateway exit cleanly (status 0). launchd reads exit 0 as "success, do not relaunch" and leaves the service down.

Comparison: a SIGTERM-based restart leaves LastExitStatus = 15, which launchd does relaunch. So the "fallback" path works; the "graceful" path silently breaks recovery. The code comment at gateway.py:211 references RestartForceExitStatus=75 for systemd — the launchd side has no equivalent.

Suggested fixes (either is sufficient):

  • Have the graceful SIGUSR1 shutdown path exit with a non-zero status (e.g. 75) so it matches the systemd contract, or
  • Change the plist template to <key>KeepAlive</key><true/> (always relaunch unless explicitly bootout'd).

Repro: macOS, gateway installed as launchd agent, send update to gateway via Telegram. Then hermes gateway status → service not loaded.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium — degraded but workaround existscomp/cliCLI entry point, hermes_cli/, setup wizardcomp/gatewayGateway runner, session dispatch, deliverytype/bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions