hermes-agent: brew upgrade leaves gateway launchd service pointing at removed keg

What were you trying to do (and why)?

Upgrade the Homebrew-installed hermes-agent with brew upgrade while retaining a working, previously configured Hermes messaging gateway.

What happened (include all command output)?

The gateway has repeatedly broken after Homebrew upgrades. In the investigated failure, its launchd service retained absolute paths into a previous version's Cellar directory, earlier gateway logs recorded a missing CA bundle in that same directory, and launchd could no longer start the gateway. This suggests the old installation was removed while still referenced by the gateway; the precise timing of removal relative to the running process was not captured.

The installed formula is now hermes-agent 2026.9.14, but ~/Library/LaunchAgents/ai.hermes.gateway.plist still contained:

<key>ProgramArguments</key>
<array>
    <string>/opt/homebrew/Cellar/hermes-agent/2026.8.31_1/libexec/bin/python</string>
    <string>-m</string>
    <string>hermes_cli.stderr_timestamp</string>
    <string>--error-log</string>
    <string>~/.hermes/logs/gateway.error.log</string>
    <string>--</string>
    <string>/opt/homebrew/Cellar/hermes-agent/2026.8.31_1/libexec/bin/python</string>
    <string>-m</string>
    <string>hermes_cli.main</string>
    <string>gateway</string>
    <string>run</string>
    <string>--external-supervisor</string>
</array>

The log path above is abbreviated for privacy; the actual plist used an absolute home-directory path.

VIRTUAL_ENV and the first entry of PATH also pointed to 2026.8.31_1/libexec.

The gateway's scheduled agent job reported:

RuntimeError: Failed to initialize OpenAI client: certifi points to a missing CA bundle: /opt/homebrew/Cellar/hermes-agent/2026.8.31_1/libexec/lib/python3.13/site-packages/certifi/cacert.pem
Repair: run `hermes doctor --fix` (auto-reinstalls certifi), or manually: python -m pip install --force-reinstall certifi openai httpx

Messaging also returned an unexpected-error response. At investigation time, launchctl print gui/501/ai.hermes.gateway reported:

state = spawn scheduled
program = /opt/homebrew/Cellar/hermes-agent/2026.8.31_1/libexec/bin/python
last exit code = 78: EX_CONFIG
job state = spawn failed

Meanwhile, hermes --version successfully started the current installation:

Hermes Agent v0.21.3 (2026.9.14)
Install directory: /opt/homebrew/Cellar/hermes-agent/2026.9.14/libexec/lib/python3.13/site-packages
Install method: unknown
Python: 3.13.15
OpenAI SDK: 2.24.0

Diagnosis and verified repair

The installed formula has no post_install gateway-refresh step and no service definition. Hermes generates its own launchd plist using the current Python virtualenv's absolute path.

Running hermes gateway install with the current package repaired the existing service:

↻ Repairing outdated launchd service at: [home]/Library/LaunchAgents/ai.hermes.gateway.plist
↻ Updated gateway launchd service definition to match the current Hermes install
✓ Service definition updated

Afterward:

✓ Service definition matches the current Hermes install
✓ Gateway is supervised by launchd (PID 96896)

The gateway log then confirmed healthy Telegram polling and a connected platform. Separately, the current package's Python successfully located its CA bundle, created an SSL context, and initialized an OpenAI client without making a model request. No certifi reinstall was needed. An end-to-end user message/model response has not yet been verified.

This repairs the current failure, but does not make subsequent brew upgrade operations refresh the gateway.

What did you expect to happen?

An upgrade should provide a supported way to transition an already-installed gateway to the new package without leaving a running process or launchd service dependent on the removed version.

Could the formula integrate gateway refresh/restart for existing services, or provide an appropriate Homebrew-managed service? If automatic integration is not appropriate, please document the required upgrade procedure in the formula caveats. A stable startup path alone does not address a still-running Python process whose old package files are removed.

This should not create or enable a gateway for users who have not configured one.

Step-by-step reproduction instructions (by running brew commands)

The following describes the observed upgrade workflow, not a second destructive downgrade/upgrade test:

1. Install an older hermes-agent through Homebrew.
2. Configure a messaging gateway and run hermes gateway install.
3. Upgrade hermes-agent through brew upgrade; allow the old keg to be removed.
4. Check whether the existing launchd plist still references the old version and whether launchd can start it. In the investigated installation, the plist was stale, launchd reported a spawn failure, and earlier gateway logs referenced a missing CA bundle in the old keg. The hypothesized running-process failure during cleanup was not separately reproduced.
5. Run hermes gateway install again with the new package: the stale service is refreshed and messaging transport reconnects.

Verification

• My brew doctor output says Your system is ready to brew. and am still able to reproduce my issue.
• I ran brew update and am still able to reproduce my issue.
• I have resolved all warnings from brew doctor and that did not fix my problem.
• I searched for recent similar issues at https://github.com/Homebrew/homebrew-core/issues?q=is%3Aissue and found no duplicates.
• My issue is not about a failure to build a formula from source.
• I did not use AI/LLM to create this issue, or I disclosed the tool and model used; I will answer maintainer questions myself without AI/LLM.

AI disclosure: investigation and report drafting were assisted by kent.sh using model gpt-6-astra. Submitted at the account owner's explicit request.

brew config AND brew doctor output OR brew gist-logs <formula> link

brew config

HOMEBREW_VERSION: 7.0.2-15-g72b0644
ORIGIN: https://github.com/Homebrew/brew
HEAD: 72b0644718f8adfc48f4c42d1490191bcdb39666
Last commit: 2 hours ago
Branch: main
Core tap: N/A
Core cask tap: N/A
HOMEBREW_PREFIX: /opt/homebrew
Homebrew Ruby: 4.0.7 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/4.0.7/bin/ruby
CPU: 18-core 64-bit arm_sotra
Clang: 21.0.0 build 2100
Git: 2.55.0 => /opt/homebrew/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 27.0-arm64
CLT: 27.0.0.0.1787197235
Xcode: 27.0
Metal Toolchain: N/A
Rosetta 2: false

brew doctor

Updated after fixing the unrelated qBittorrent tap deprecation on September 16, 2026. The Command Line Tools warning remains:

Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: A newer Command Line Tools release is available.
Update them from Software Update in System Settings.

If that doesn't show you any updates, run:
  sudo rm -rf /Library/Developer/CommandLineTools
  sudo xcode-select --install

Alternatively, manually download them from:
  https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 27.0.
This is a Tier 2 configuration:
  https://docs.brew.sh/Support-Tiers#tier-2
You can report issues with Tier 2 configurations to Homebrew/* repositories!
  https://docs.brew.sh/Troubleshooting
Read the above document before opening any issues or PRs.