PR #15640: fix(gateway): macOS launchd plist registers Login Item as "hermes" not "python"

• Repository: NousResearch/hermes-agent
• Author: serejaris
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15640

Description (problem / solution / changelog)

What

Make generate_launchd_plist() produce a plist whose ProgramArguments[0] is the venv's hermes console script instead of …/venv/bin/python -m hermes_cli.main. Falls back to the previous python -m hermes_cli.main form when the console script is missing.

Why

macOS Background Task Management uses basename(ProgramArguments[0]) as the display name in System Settings → General → Login Items & Extensions and in the system notification banner that fires after hermes gateway install:

"python" is an item that can run in the background. You can manage this in Login Items & Extensions.

Users cannot tell which background item belongs to Hermes — especially when other Python-based launch agents are installed — and disabling the entry from System Settings is opaque. With this change, macOS displays the entry as "hermes", which matches the binary the user invoked, the plist Label, and the pattern already used elsewhere in the project (the proposed hindsight memory plugin plist in #8973 invokes ${HERMES_VENV}/bin/hindsight-embed for the same reason).

The runtime behavior is identical: <venv>/bin/hermes is a Python entry-point script with a shebang pointing at the same <venv>/bin/python3, so the same interpreter loads hermes_cli.main either way.

This pattern is the documented best practice; see macblog.org — Manage and enforce custom Login and Background items in macOS Ventura:

I've seen some launchd configurations that use the ProgramArguments array to first specify the path to an interpreter, then the path to a script… That's wrong, and it causes macOS to attribute the interpreter as the launched process.

Don't do this. You should set the path to the script's interpreter in its shebang, then make the script itself executable.

Fixes #15636.

How to test

Automated

pytest tests/hermes_cli/test_gateway_service.py -k launchd_plist -v

Two new tests cover both branches:

• test_launchd_plist_uses_hermes_console_script_when_present — when <venv>/bin/hermes exists, ProgramArguments[0] is the script and there is no python -m hermes_cli.main invocation.
• test_launchd_plist_falls_back_to_python_module_when_console_script_missing — when the console script is absent, the original python -m hermes_cli.main form is preserved.

Existing test_launchd_plist_includes_profile continues to pass (profile arg still threaded through ProgramArguments).

Manual (macOS)

hermes gateway uninstall          # if previously installed
hermes gateway install
hermes gateway status

Expected:

• Notification banner reads "hermes is an item that can run in the background."
• System Settings → General → Login Items & Extensions lists the entry as hermes.
• hermes gateway status reports ✓ Service installed and loaded and does not report "Service definition is stale".
• Telegram/Discord/cron functionality unchanged.

Platforms tested

• macOS 15.7.1 (Sequoia, Apple Silicon), Python 3.11.14 in venv. Telegram gateway and cron jobs verified working post-install.
• Linux/systemd path is untouched by this change (the fix is scoped to generate_launchd_plist()).

Related issues

• Fixes #15636 — the bug report this PR addresses.
• Aligns with #8973 — the hindsight plist already uses the named-binary pattern proposed here.
• Narrower than #6350 — that issue requests fully customizable scripts; this PR doesn't require that, just the correct binary name.
• Compatible with #8125 — launchd_plist_is_current() will continue to detect drift correctly because both the generator and the comparison use the same fresh output.

Changed files

• hermes_cli/gateway.py (modified, +17/-6)
• tests/hermes_cli/test_gateway_service.py (modified, +48/-0)

PR #15885: fix(gateway): use venv/bin/hermes in launchd ProgramArguments so Login Item shows "hermes" (#15636)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15885

Description (problem / solution / changelog)

Summary

• generate_launchd_plist() switched from python -m hermes_cli.main to venv/bin/hermes as ProgramArguments[0]
• macOS now shows hermes (not python) in System Settings → Login Items & Extensions
• Removes the now-unused python_path local variable

The bug

macOS derives the Login Item display name from ProgramArguments[0]. The old plist started with the Python interpreter path (/path/to/venv/bin/python3), so the notification banner and System Settings listed the agent as python — indistinguishable from any other Python script running as a Login Item.

The fix

venv/bin/hermes is the setuptools console-script entry-point installed by pip install -e .. Its shebang is the same venv Python; at runtime it calls hermes_cli.main:main() identically to the old -m hermes_cli.main form. The existing PATH, VIRTUAL_ENV, and HERMES_HOME environment variables in the plist already ensure the correct virtualenv is active.

Existing installations with the old plist will have launchd_plist_is_current() return False on next gateway start, triggering refresh_launchd_plist_if_needed() to update the on-disk plist automatically.

Test plan

• Before: test_plist_uses_hermes_binary_not_python fails — old ProgramArguments[0] is the Python interpreter path, endswith("/hermes") is False; -m and hermes_cli.main appear in the array
• After: 42/42 tests in test_update_gateway_restart.py pass
• Regression guard: reverted the fix → observed AssertionError: Expected first ProgramArgument to end with '/hermes', got: '/path/to/venv/bin/python3'; restored → 0 failures
• Baseline verified: test_systemd_start_refreshes_outdated_unit fails on clean origin/main (macOS: no D-Bus/systemd); unrelated to this change
• Adjacent suite: tests/hermes_cli/ — 1061 passed, 2 skipped, 1 pre-existing baseline, 0 new failures

Related

• Fixes #15636

🤖 Generated with Claude Code

Changed files

• hermes_cli/gateway.py (modified, +4/-4)
• tests/hermes_cli/test_update_gateway_restart.py (modified, +36/-0)