fix(gateway): correct macOS gateway-pid detection (#15225) by briandevans · Pull Request #15318 · NousResearch/hermes-agent

briandevans · 2026-04-24T20:00:15Z

What does this PR do?

Fixes `#15225`. `hermes cron list` falsely reports "Gateway is not running" on macOS even when launchd has the service loaded and cron jobs fire correctly.

Two independent bugs in `hermes_cli/gateway.py` each drop the macOS PID-detection path into an empty-result state. Fixing either alone clears the warning; both are real and both are worth fixing — the detector is the source for several other views (`cron list` warning, secondary `gateway status` check, `hermes update`'s broad sweep) and each should be resilient.

Bug 1 — `_get_service_pids()` mis-parses `launchctl list `

macOS `launchctl list` has two output formats:

Invocation	Format
`launchctl list` (no label)	tab-separated table: `PID\tStatus\tLabel`
`launchctl list `	plist-dict dump: `"PID" = 855;`, `"Label" = "ai.hermes.gateway";`, …

The old code always called `launchctl list ` but parsed with `string.split()` expecting the tab-separated format. On a real macOS install that means `parts[2]` on the label line is `'"ai.hermes.gateway";'` (quoted, semicolon'd) — so `parts[2] == label` never matched and no PID was ever extracted, even though the service was actively running.

Fix: extracted a `_parse_launchd_list_output(stdout, label)` helper that tries the plist-dict `"PID" = N;` regex first and falls back to the tab-separated path when no plist matches are found. Handles both formats so a future change to the caller can't silently re-break detection.

Regex anchored to `"PID"` key — sibling fields like `LastExitStatus` can't match.
PID 0 rejected — downstream `os.kill(0, …)` would affect the whole process group.
Whitespace-tolerant (`"PID" =`, `"PID"=`, `"PID" = `, leading tabs all match) — launchd's plist dumper is not a stable format across Apple releases.

Bug 2 — `_scan_gateway_pids()` passes `eww` to `ps`

Old: `["ps", "-A", "eww", "-o", "pid=,command="]`

Darwin: rejects `eww` as "illegal argument", exits 1. Empty `stdout`, no PIDs extracted ([Bug]: hermes cron list falsely reports "Gateway is not running" on macOS (two-stage detection failure in find_gateway_pids) #15225).
FreeBSD: accepts `eww` but the embedded `e` attaches environment variables to the command column. `split(None, 1)` then picks up the first env var as the command ([Bug]: hermes cron list: Gateway process detection fails on FreeBSD due to ps eww output format #9069). Env vars can include API keys — leaking them into any log line that echoes the command.

Fix: replaced with `["ps", "-A", "-ww", "-o", "pid=,command="]` — portable across Linux (procps), Darwin, FreeBSD, busybox. Drops env-var leakage as a side benefit.

Related Issue

Fixes #15225

Related: #9069 (same function, different FreeBSD failure mode), #9723 (same function, Docker, fixed via `c483b4c` for that narrower case).

Type of Change

🐛 Bug fix (non-breaking change that fixes an issue)
✅ Tests (adding or improving test coverage)

Test plan

19 new tests in `tests/hermes_cli/test_gateway_pid_detection_macos.py` — all green on py3.11 venv
1 pre-existing test in `test_gateway.py` updated to match the portable `-ww` invocation (explicit `# Note: since [Bug]: hermes cron list falsely reports "Gateway is not running" on macOS (two-stage detection failure in find_gateway_pids) #15225` comment for future readers)
Full `tests/hermes_cli/test_gateway.py` suite still green (21 tests)
Verified regression guards: temporarily reverted Bug 1 and Bug 2 independently; the relevant test classes correctly failed with clear messages pointing at the regressed invariant. Restored fix → all 39 tests green.

Test coverage detail

`TestParseLaunchdListOutput` (8 cases) — exercises the new helper directly:

plist-dict output from the real [Bug]: hermes cron list falsely reports "Gateway is not running" on macOS (two-stage detection failure in find_gateway_pids) #15225 repro → extracts PID 855
tab-separated `launchctl list` (no label) format → extracts correct PID, skips other services
unloaded-service `-\t0\tlabel` row → no PID extracted (no `int("-")` crash)
empty stdout → empty set (no crash)
defensive: both formats concatenated → plist-dict wins (label-scoped is more trustworthy)
PID 0 rejected
other-label row in tab-separated output → filtered out
4 whitespace variants of the plist PID key

`TestGetServicePidsMacOS` (3 cases) — end-to-end macOS branch with mocked `subprocess.run`:

returns `{855}` for a running service (the [Bug]: hermes cron list falsely reports "Gateway is not running" on macOS (two-stage detection failure in find_gateway_pids) #15225 repro state)
nonzero launchctl exit → empty set
missing `launchctl` binary → empty set (no `FileNotFoundError` propagation)

`TestPsInvocationPortability` (4 cases) — captures exact argv:

`"eww"` never on the command line (the core regression guard)
pins `["ps", "-A", "-ww", "-o", "pid=,command="]` shape
parses realistic Darwin-style ps output end-to-end, extracts gateway PID
nonzero returncode path returns `[]` without crashing

Not in scope

A broader refactor to pass the launchctl plist through a proper plist parser rather than a regex — the regex is narrow, anchored, and tolerant; bigger tooling is unnecessary for two well-defined keys.
Fixing the `gateway status` secondary check that shares this helper — it already reports correctly via a different code path (`launchctl list` in `gateway/status.py`). The detector fix clears the warning everywhere as a side effect.

Copilot

Pull request overview

Fixes macOS gateway PID detection so hermes cron list (and other callers of find_gateway_pids()) no longer incorrectly warns that the Gateway isn’t running when it is managed by launchd.

Changes:

Add a launchd output parser that correctly handles both launchctl list output shapes (plist-dict vs tabular).
Replace the non-portable ps ... eww ... invocation with a portable ps -A -ww ... form.
Add targeted regression tests for the macOS launchctl parsing and the portable ps invocation (and update an existing test expectation).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`hermes_cli/gateway.py`	Fixes launchctl parsing via a new helper and updates the `ps` invocation for portability/security.
`tests/hermes_cli/test_gateway_pid_detection_macos.py`	Adds regression tests covering both launchctl output formats and the corrected `ps` argv.
`tests/hermes_cli/test_gateway.py`	Updates an existing test to expect the new portable `ps` invocation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-24T20:03:12Z

+    pids: set = set()
+    if not stdout:
+        return pids


The local variable annotation uses an unparameterized set. Since this set is intended to contain integer PIDs, consider annotating it as set[int] for consistency with other PID collections in this module.

Copilot · 2026-04-24T20:03:13Z

+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from hermes_cli import gateway


patch is imported but not used in this test module. Removing the unused import will keep the file clean and avoid unused-import warnings in environments that run linting or stricter test settings.

Copilot · 2026-04-24T20:03:13Z

+def _parse_launchd_list_output(stdout: str, label: str) -> set:
+    """Extract PIDs for ``label`` from ``launchctl list`` output.


Type annotations here are less specific than the rest of this module: the helper returns a set of PIDs, so the return type should be set[int] (consistent with e.g. seen: set[int] = set() in this file) to improve readability and static analysis.

briandevans · 2026-04-24T21:26:32Z

Thanks @copilot — all three nits addressed in 0344959d:

_parse_launchd_list_output return type → tightened to set[int] (also the local pids annotation), matching the seen: set[int] = set() style already used elsewhere in this module.
_get_service_pids return type → same parameterization; that was actually pre-existing code on origin/main, but worth tightening as a drive-by since you flagged it on the diff.
Unused patch import → removed. The tests rely on monkeypatch exclusively, so the unittest.mock.patch import was dead.

39/39 tests still pass locally — no behaviour change.

``hermes cron list`` falsely reports "Gateway is not running" on macOS even when launchd has the service loaded and cron jobs fire correctly. Two independent bugs in ``find_gateway_pids()`` each drop macOS into an empty-result path; fixing either alone would clear the warning, but both are real and both are worth fixing. ### Bug 1 — ``_get_service_pids()`` mis-parses ``launchctl list <label>`` ``launchctl list`` returns two different formats depending on whether a label is passed: * No label → tab-separated table ``PID\\tStatus\\tLabel`` * With label → plist-dict dump, e.g. ``"PID" = 855;`` The old code always called ``launchctl list <label>`` (the plist-dict path) but parsed with ``string.split()`` expecting the tab-separated format. ``parts[2]`` on ``"Label" = "ai.hermes.gateway";`` is ``'"ai.hermes.gateway";'`` — quoted, semicolon'd — so the ``== label`` comparison never matched and no PID was ever extracted. Fix: extracted a ``_parse_launchd_list_output(stdout, label)`` helper that tries the plist-dict ``"PID" = N;`` regex first and falls back to the tab-separated path when no plist matches were found. Handles both formats so a future change to the caller (passing or not passing the label) can't re-break detection. Regex anchored to the ``"PID"`` key so sibling fields like ``LastExitStatus`` can't match; PID 0 rejected so downstream ``os.kill(0, ...)`` never sees it. ### Bug 2 — ``_scan_gateway_pids()`` passes ``eww`` to ``ps`` The old invocation ``ps -A eww -o pid=,command=`` has two problems: * **Darwin** rejects ``eww`` as "illegal argument" and exits 1 — ``stdout`` is empty, the parse loop iterates nothing, and no PID is extracted (NousResearch#15225). * **FreeBSD** accepts ``eww`` but the ``e`` attaches environment variables to the command column, so ``split(None, 1)`` picks up the first env var as the command (NousResearch#9069). The env vars can include API keys and tokens, which also leaked them into any log line that echoed the command. Fix: replaced with ``ps -A -ww -o pid=,command=`` — portable across Linux (procps), Darwin, FreeBSD, and busybox. Drops env-var leakage as a side benefit. ### Tests (19 new + 1 updated, all passing) ``tests/hermes_cli/test_gateway_pid_detection_macos.py``: * **``TestParseLaunchdListOutput``** (8 cases) — exercises the new helper directly with the exact plist-dict output from the NousResearch#15225 repro, the tab-separated format, the dash-PID unloaded case, mixed-shape defensive input, PID=0 rejection, and 4 whitespace-variant tolerance cases for the PID regex (``"PID" =``, ``"PID"=``, ``"PID" = ``, leading tabs). * **``TestGetServicePidsMacOS``** (3 cases) — end-to-end macOS branch with ``subprocess.run`` patched to return the plist-dict payload; asserts the single-PID set is returned, a non-zero launchctl exit returns empty, and a missing ``launchctl`` binary (FileNotFoundError) falls through cleanly. * **``TestPsInvocationPortability``** (4 cases) — captures the exact argv the production code passes to ``ps``, asserts ``"eww"`` is never on the command line, pins the ``["ps", "-A", "-ww", "-o", "pid=,command="]`` shape, parses a realistic Darwin-style ps sample end-to-end, and exercises the nonzero-returncode fallback. Also updated ``test_find_gateway_pids_falls_back_to_pid_file_when_process_scan_fails`` in ``tests/hermes_cli/test_gateway.py`` to match the new portable ``-ww`` invocation; added an inline comment pointing at NousResearch#15225 history. **Verified tests are real regression guards**: temporarily reverted Bug 1 and Bug 2 independently; the relevant test classes correctly failed with clear messages pointing at the regressed invariant. Closes NousResearch#15225 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three minor cleanups from Copilot's review on NousResearch#15318: 1. ``_parse_launchd_list_output`` return type: ``set`` → ``set[int]`` (matches the ``seen: set[int] = set()`` style elsewhere in the module). 2. ``_get_service_pids`` return type + local: same parameterization; was bare ``set`` before this branch existed, but Copilot flagged the pre-existing annotation while reviewing the diff so worth tightening as a drive-by. 3. ``unittest.mock.patch`` was imported in ``test_gateway_pid_detection_macos.py`` but never called — the tests use ``monkeypatch`` exclusively. Removed the unused import. No behaviour change. 39/39 tests still pass locally. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

briandevans · 2026-05-18T08:15:27Z

Closing to keep the queue clean — 17 days idle and now conflicting on hermes_cli/gateway.py. Happy to reopen if this is still useful.

Copilot AI review requested due to automatic review settings April 24, 2026 20:00

Copilot started reviewing on behalf of briandevans April 24, 2026 20:00 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

alt-glitch added type/bug Something isn't working P2 Medium — degraded but workaround exists comp/cli CLI entry point, hermes_cli/, setup wizard comp/gateway Gateway runner, session dispatch, delivery labels Apr 24, 2026

briandevans and others added 2 commits April 30, 2026 08:18

briandevans force-pushed the fix/macos-gateway-pid-detection branch from 0344959 to 7555352 Compare April 30, 2026 15:18

briandevans closed this May 18, 2026

GottZ mentioned this pull request Aug 3, 2026

fix(cron): suppress false "Gateway is not running" warning when desktop ticker is alive #67828

Open

19 tasks

Navigation Menu

Uh oh!

fix(gateway): correct macOS gateway-pid detection (#15225) - #15318

fix(gateway): correct macOS gateway-pid detection (#15225)#15318
briandevans wants to merge 2 commits into
NousResearch:mainfrom
briandevans:fix/macos-gateway-pid-detection

briandevans commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

briandevans commented Apr 24, 2026

Uh oh!

briandevans commented May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		def _parse_launchd_list_output(stdout: str, label: str) -> set:
		"""Extract PIDs for ``label`` from ``launchctl list`` output.

Uh oh!

Conversation

briandevans commented Apr 24, 2026

What does this PR do?

Bug 1 — `_get_service_pids()` mis-parses `launchctl list `

Bug 2 — `_scan_gateway_pids()` passes `eww` to `ps`

Related Issue

Type of Change

Test plan

Test coverage detail

Not in scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

briandevans commented Apr 24, 2026

Uh oh!

briandevans commented May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants