Review — end-to-end ✅ (clean approve, behavioural harness validates noise filter and routing)

P1 fix for issue #1458 (Bug #1 only). Adds --foreground flag and supervisor-env auto-detection so bootstrap.py replaces its process image with server.py via os.execv under launchd/systemd/supervisord, instead of double-forking and exiting (which causes supervisor KeepAlive/Restart=always to respawn bootstrap.py while the orphaned server still holds port 8787 — the loop the issue describes).

Bugs #2 (state.db FD leak) and #3 (HTTP-unhealthy wedge) explicitly remain open under #1458 awaiting diagnostic data — correct scope discipline per the maintainer's pickup-comment.

What this ships

• bootstrap.py (+121/-9): --foreground argparse flag, _SUPERVISOR_ENV_VARS tuple, _is_real_supervisor_value() XPC noise filter, _detect_supervisor(), and a two-path main() that exec's vs. Popens.
• docs/supervisor.md (new, +237 LOC): runnable launchd plist + systemd .service + supervisord conf + diagnostic lsof/ppid recipe.
• .gitignore: allowlist docs/supervisor.md (matches !docs/docker.md precedent).
• tests/test_bootstrap_foreground.py (new, +455 LOC): 44 regression tests.

Traced against upstream hermes-agent

bootstrap.py is webui-only — verified by grepping the fresh tarball: agent-side bootstrap references are unrelated (launchctl bootstrap subcommand calls in hermes_cli/gateway.py). The CLI does not import or invoke webui's bootstrap.py. No cross-tool regression surface.

End-to-end trace

Entry points:

• bash start.sh --foreground → exec "${PYTHON}" bootstrap.py --no-browser --foreground (start.sh:25) — exec replaces the shell, then bootstrap exec's into server.py. Result: same PID lineage from shell → server.
• launchd plist with KeepAlive=true → spawns bash start.sh --foreground → same chain.
• systemd Type=simple with ExecStart=...start.sh --foreground → bash exec'd by systemd, then bash exec's python, then bootstrap exec's server.py. Same lineage.

Routing decision at bootstrap.py:321:

foreground_reason = "--foreground" if args.foreground else _detect_supervisor()
if foreground_reason:
    # chdir → executability guard → os.execv (never returns)
else:
    # legacy: Popen + wait_for_health → return 0

Foreground path (bootstrap.py:322-347):

1. Log starting message naming the trigger reason
2. os.chdir(server_cwd) with OSError → RuntimeError translation
3. os.access(python_exe, os.X_OK) guard — without this, a missing python would loop the supervisor (the exact failure mode the PR fixes)
4. os.execv(python_exe, [python_exe, server_path]) — the argv[0] == argv[1] repetition is correct CPython convention
5. Unreachable RuntimeError after execv

Env propagation (bootstrap.py:307-312): os.environ is mutated directly (instead of a local env dict copy). This is required for os.execv since execv inherits os.environ — a local copy would be lost. The legacy Popen path now uses env=os.environ.copy() (bootstrap.py:358) which captures the same final state. Net effect for legacy path: identical to before.

Security audit

• ✅ No XSS, no SQL, no path traversal — bootstrap is local-only, no untrusted input.
• ✅ os.execv(python_exe, ...) argument comes from discover_launcher_python() which respects HERMES_WEBUI_PYTHON env, then probes for venv/bin/python under known dirs. No user-supplied input reaches execv beyond local config.
• ✅ The pre-execv os.access check is informational/defensive — there's no security boundary; this is just to convert silent loop into visible error.
• ✅ No new endpoints, no auth changes, no config.yaml writes.

Race / state analysis

• ✅ Pure synchronous code, no shared dicts, no locks. os.environ mutation is single-threaded at startup (before any subprocess or thread spawns).
• ✅ Idempotent: os.environ.setdefault("HERMES_WEBUI_STATE_DIR", ...) doesn't override an externally provided value, but state_dir was computed from that same env var, so the value is consistent either way.

Behavioural harness — XPC noise filter

✅ XPC_SERVICE_NAME='0'                                      → False (Mac launchd descendant noise)
✅ XPC_SERVICE_NAME='application.com.apple.Terminal.UUID'    → False (Terminal.app)
✅ XPC_SERVICE_NAME=''                                       → False (empty)
✅ XPC_SERVICE_NAME='com.example.foo'                        → True  (real Label)
✅ XPC_SERVICE_NAME='application'                            → True  (no dot prefix — passes; theoretical edge)
✅ XPC_SERVICE_NAME='applicationCo.foo'                      → True  (no dot — passes; theoretical edge)
✅ INVOCATION_ID='0'                                         → True  (no narrowing for non-XPC vars)
✅ INVOCATION_ID=''                                          → False (empty)
✅ NOTIFY_SOCKET='/run/systemd/notify'                       → True

The filter correctly rejects Apple's known Terminal/IDE noise values. The "exactly application (no dot)" and "applicationCo.foo" cases are theoretical — Apple's actual noise always uses application.<bundle-id> form. Acceptable.

Edge-case matrix

Tests

• tests/test_bootstrap_foreground.py — 44/44 pass:
  • TestForegroundFlag (3): argparse recognition + default + help text mentions all 3 supervisors
  • TestDetectSupervisor (15): clean env, each of 5 supervisor vars, 7 truthy + 7 falsy explicit-opt-in values, precedence
  • TestXPCServiceNameNoiseFilter (8): 4 noise values rejected, 3 real Labels accepted, mixed-env fallthrough
  • TestMainForegroundRouting (8): default→Popen, --foreground→execv, each supervisor var auto-promotes, explicit-opt-in auto-promotes
  • TestForegroundEnvAndCwd (3): chdir to agent_dir, exports resolved env to os.environ, skips wait_for_health
  • TestForegroundExecutabilityGuard (1): non-executable python raises RuntimeError before execv
• Existing test_bootstrap_dotenv.py continues to pass.
• Full suite: 3767 passed, 55 skipped, 3 xpassed, 0 failed in 18.84s on the PR branch (PR description claims 3811/3820; counting drift is consistent with prior batches and not blocking).
• CI: 3.11 / 3.12 / 3.13 all green.

Other audit — things that are correct already

• ✅ argv[0] == argv[1] for os.execv([python, [python, server.py]]) is correct CPython convention.
• ✅ start.sh already uses exec "${PYTHON}" ... "$@" so --foreground passes through with the bash process replaced (clean PID lineage).
• ✅ Legacy Popen path env=os.environ.copy() is a snapshot taken AFTER the os.environ mutations, so the resolved values still flow to the child.
• ✅ _detect_supervisor() short-circuits on --foreground flag — no double-evaluation cost or precedence ambiguity.
• ✅ _load_repo_dotenv() runs at import time before DEFAULT_HOST/DEFAULT_PORT are read; tests freshly re-import bootstrap to avoid module-level state bleed.
• ✅ The clean_env fixture strips HERMES_WEBUI_HOST/PORT/AGENT_DIR after the agent-flagged leak — verified at tests/test_bootstrap_foreground.py:73-83.

Minor observations (non-blocking)

• Executability guard converts loop to error, but supervisor still restarts on RuntimeError → SystemExit(1). The improvement is observability (the stderr message points at HERMES_WEBUI_PYTHON), not loop prevention — the supervisor will still respawn until the user fixes the python path. A one-time loud failure is much better than silent flapping, but the comment "Convert to a single visible error" slightly oversells: it's a single clearer error per restart. Worth a tiny doc tweak in supervisor.md ("if you see this error in journald, fix HERMES_WEBUI_PYTHON — the supervisor will keep restarting until you do") but not blocking.

• XPC_SERVICE_NAME filter accepts application (no dot) and applicationCo.foo. The value.startswith("application.") check requires a literal dot, so the bare word "application" or words starting with "applicationXxx" would pass through as if they were real Labels. In practice Apple always uses application.<bundle-id> form — no observed false negative. Could tighten to value == "application" or value.startswith("application.") but the value is bounded by what launchd actually emits.

• No equivalent of HERMES_WEBUI_FOREGROUND for forcing OFF. If a user is in a weird env that auto-detects (say, a Docker container that happened to inherit INVOCATION_ID) and wants to force the legacy Popen path, the only escape is unset INVOCATION_ID && bash start.sh. A HERMES_WEBUI_FOREGROUND=0 doesn't currently force-disable detection (the falsy values fall through to env probing — by design per the test suite). Consider adding a HERMES_WEBUI_NO_FOREGROUND=1 override later if anyone hits this. Documented in supervisor.md anti-recipe section is sufficient for now.

• PR description test count off by ~50 (3811/3820 claimed vs 3767 local). Same drift pattern as prior batches.

• docs/supervisor.md runit/daemontools recommendation is sound — those supervisors don't set any of our detected env vars, so the explicit HERMES_WEBUI_FOREGROUND=1 instruction is correct.

Recommendation

✅ Approved. The fix correctly converts the supervisor double-fork loop into a clean os.execv replacement so KeepAlive/Restart=always work as intended. The XPC noise filter prevents auto-promotion on every Mac dev machine — a real regression risk caught in pre-merge review. The executability guard converts a silent restart loop into a visible error, which is the right tradeoff. Behavioural harness on the noise filter and 44/44 regression tests confirm structural correctness; live PID-lineage verification in the PR description proves end-to-end behavior.

Bugs #2 and #3 explicitly out of scope per maintainer guidance — correct discipline.

Parked at approval — ready for the release agent's merge/tag pipeline.