Supervise the RFC #122 bridge as a LaunchAgent

[evansenter]

The bridge merged in #135 with no install target — it ran only as a foreground uv run agent-event-bus-bridge, so it died with its shell and never survived a reboot. The bus has had a LaunchAgent all along (which is why it has been up continuously); the bridge simply never had one.

Adds com.evansenter.agent-event-bus-bridge.plist, install/uninstall scripts, and make install-bridge / make uninstall-bridge.

Design decisions worth reviewing

A separate unit, not an addition to install-server. A bus host doesn't have to run a bridge, and the bridge is experimental while the bus isn't. Bundling them would make every bus install start a daemon most machines don't want.

Boot ordering needs no launchd machinery. launchd has no dependency ordering, so the bridge can start before the bus is listening — but register_with_retry already backs off 1s→30s until the bus answers rather than exiting, and its docstring anticipates exactly the "same supervisor launches both" case. A cold boot in the wrong order self-corrects. That's why the installer prints registered: false as a status line, not an error.

KeepAlive is safe with the singleton lock. flock releases when the dead process's fd closes, so the replacement acquires it cleanly instead of refusing to start, and the startup sweep reclaims the webhook row the dead instance left registered. ThrottleInterval is stated explicitly rather than left to the default because it's load-bearing here — it bounds how fast a crash loop rewrites the log.

--backend spool is pinned in the unit. tmux additionally needs wake/panes.json maintained by something session-side, which doesn't exist. AGENT_EVENT_BUS_URL is deliberately left unset so the bridge's loopback default applies — correct on the machine hosting the bus, and the comment explains what changes if the bus moves off-box.

Documented caveat, not a silent one

The bridge logs via basicConfig (stderr only), so launchd's capture is its log — and launchd truncates that on every process start. A crash loop overwrites the evidence of earlier iterations. ThrottleInterval keeps the surviving window useful. Giving the bridge its own append-mode file handler, like the bus has, is the follow-up that removes this properly; I kept it out of here to keep the diff focused on supervision.

Verification

The suite mocks launchd entirely, so guide.md gains a four-item manual checklist — and two of them check claims this unit's own comments make rather than taking them on trust:

1. Crash restart — kill -9; launchd respawns within ThrottleInterval. Proves the flock actually releases and the sweep reclaims the row instead of duplicating it.
2. Boot order — unload the bus, load the bridge (registered: false), then load the bus; it should flip to true within ~30s unaided.
3. Reboot — the actual requirement.
4. Clean unload — webhook row gone, port 8082 free.

What none of it covers: whether a session actually wakes. The spool line lands, but nothing drains it until #134.

make check green: 576 passed. Plist parses via plistlib; both scripts pass bash -n.

Also: three #137 follow-ups

Deferred at that merge with a note that they'd ride the next PR:

• Hoisted the session-id env scrub from test_cli.py to conftest.py, so test_structured_payload.py and test_signal_levels.py are protected by construction rather than by the accident of what they currently assert.
• Generalized _session_id_from_env's docstring off the specific ~/.exports / ~/.zshrc paths this repo doesn't own, keeping the durable half (rc files are interactive-only).
• Added CLAUDE_CODE_SESSION_ID to the CLAUDE.md env-var table — the one consulted name that will never carry the AGENT_EVENT_BUS_ prefix.

Not taken, from the same review: defaulting --client-id in register/unregister from the same helper. The gap needs a SessionStart hook that omits --client-id, which isn't the current setup (dotfiles session-start.sh:74 passes it), and auto-adopting the session id as client_id would change registration semantics — the (machine, client_id) dedupe means a manual register would resume the real session rather than mint a new one. That deserves its own change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AFp3uCezpvbeyAMYnNrQ4R

---

Generated by Claude Code

[claude]

[Important] This check is correctly anchored with $ — but the three pre-existing probes for the bus label are not, and the new label is a superstring of the old one:

• Makefile:149 (make restart) — launchctl list | grep -q "com.evansenter.agent-event-bus"
• scripts/install-launchagent.sh:29,48 — grep -q "$LABEL", LABEL="com.evansenter.agent-event-bus"
• scripts/dev.sh:15 — same unanchored $LABEL

launchctl list prints the label at end-of-line, so a loaded com.evansenter.agent-event-bus-bridge row matches all of them.

Fails when: the bridge LaunchAgent is loaded and the buss launchctl loaddoes not leave a job registered (invalid plist after a badsedsubstitution,Load failed: 5, or the bus plist absent) → make restartandinstall-launchagent.sh:48match the *bridge* row, printService restarted successfully/Agent Event Bus installed and running!, fire the success notification, and exit 0 while the bus is down — the exact failure those checks exist to catch. Same root cause in dev.sh: on a bridge-only box it prints Stopping LaunchAgent for dev mode..., sets SERVICE_WAS_RUNNING=true, and on exit launchctl load`s a bus that was never running (or errors if the plist does not exist).

Fix is the $ you already used here, applied to those three sites.

[claude]

[Suggestion] guide.md:660-664 (further down, outside this diff) still reads:

Supervision is deliberately out of scope for the v1 prototype: there is no make install-bridge, launchd plist, or systemd unit yet - run the bridge in a terminal (or your own supervisor) while experimenting.

That now directly contradicts the section added here. Since guide.md is the canonical agent-event-bus://guide resource an agent reads to decide what exists, the stale paragraph is the one it may hit first. Worth trimming it to the still-true half (no systemd unit yet; tmux still needs panes.json).

[claude]

[Suggestion] make uninstall (documented in CLAUDE.md as "Remove everything") does not touch the bridge unit, so after make install-bridge; make uninstall the bridge LaunchAgent stays loaded, KeepAlive keeps respawning it, and it backs off forever against a bus that no longer exists — while uninstall-cli.sh has just removed the agent-event-bus-cli that the bridge teardown notes tell you to verify with. Either invoke uninstall-bridge-launchagent.sh from uninstall when the bridge plist is present, or add a line to uninstall output pointing at make uninstall-bridge.

[claude]

[Suggestion] Logs: points at StandardOutPath, but the bridge own records are not there: main() calls logging.basicConfig(...) with no stream=, which defaults to stderr, so every logger.info/logger.debug from bridge.py lands in ...-bridge.err. The .log file receives only uvicorn access lines. The failure paths in this script already say "check $BRIDGE_ERR_FILE", which is right — but a reader following Logs: will tail the file without the bridge messages in it. Consider labelling them Access log: / Bridge log:, which also makes the plist comment caveat concrete at install time.

[claude]

[Suggestion] On a re-install over a live bridge, launchctl unload returns as soon as SIGTERM is delivered, so the outgoing process may still hold the singleton flock and port 8082 when launchctl load starts the replacement. The replacement then exits on the lock — correctly, since that ordering is exactly what protects the webhook row — and KeepAlive retries only after ThrottleInterval, i.e. up to ~10s later. The fixed sleep 2 lands inside that window, so a perfectly healthy idempotent re-install can report /health did not answer yet. Polling /health for ~15s instead of a flat sleep would let the probe report what actually happened.

Related, same area: install-bridge does not uv sync, so a stale .venv missing a bridge dependency produces an import crash-loop — the one case where the documented log-truncation caveat bites hardest, since each respawn wipes the traceback from the previous one.

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review — Round 1

Summary

A well-argued supervision unit. The plist mirrors the bus unit closely, and the design claims check out against the code: AGENT_EVENT_BUS_BRIDGE_BACKEND=spool is genuinely read by build_parser (bridge.py:1516), python -m agent_event_bus.bridge resolves through the existing __main__ guard, and the KeepAlive-is-safe-with-the-flock argument holds for a reason stronger than stated — main() unregisters the webhook row in its finally before closing the singleton fds, so a replacement cannot register ahead of the outgoing instance cleanup even if launchd is quick. registered: false-as-a-status-line is the right call given register_with_retry. The 137 follow-ups are clean; hoisting the session-id scrub to conftest.py is ordered correctly relative to the patch.dict/monkeypatch.setenv tests that set those names deliberately.

Findings

• 1 Important — the new label com.evansenter.agent-event-bus-bridge is a superstring of the bus label, and the three pre-existing launchctl list | grep probes for the bus are unanchored. install-bridge-launchagent.sh anchors its own check with $; Makefile:149, scripts/install-launchagent.sh:29,48, and scripts/dev.sh:15 did not need that until this PR, and now do.
• 4 Suggestions — make uninstall leaves the bridge supervised; guide.md:660-664 still says make install-bridge does not exist; the installer Logs: label points at the file that does not carry the bridge own records; the unload-then-load handoff can make a healthy re-install look unhealthy inside the 2s probe.

Verdict

REQUEST_CHANGES - the bridge label silently satisfies the bus own did-it-start checks, so make restart and install-launchagent.sh can report success and exit 0 while the bus is down. Everything else is non-blocking.

---

Automated review by Claude Code

[claude]

[Suggestion] The preflight imports agent_event_bus.bridge, but uvicorn is imported lazily inside main() (src/agent_event_bus/bridge.py:2129), not at module scope — so the one dependency whose absence would produce exactly the KeepAlive import-crash-loop this check exists to prevent is the one it cannot see. starlette / anyio / requests are module-level and are covered.

In practice uvicorn>=0.30.0 is a direct entry in [project.dependencies], so a venv that can import starlette almost certainly has it — which is why this is a Suggestion rather than a defect. Widening the check costs nothing: add , uvicorn to the -c import list.

[claude]

[Suggestion] The poll breaks on the first successful /health, which on a re-install over a live bridge is answered by the outgoing process.

launchctl unload returns once SIGTERM is delivered; the old bridge still holds port 8082 through the shielded stop-join-unregister in its lifespan. So iteration 1 gets a 200 from the instance that is about to die, HEALTH is set, the loop breaks, the launchctl list check below (which reports only whether the job is loaded, not whether a process is alive) passes, and the script prints "Bridge installed and running" plus the outgoing registered: value — while the replacement has in fact just exited on the singleton flock and will not exist for another ~ThrottleInterval.

End state is still correct (KeepAlive brings it back), so this is reporting accuracy rather than breakage. But the comment above the loop presents the poll as covering the handoff window, and breaking on the first response cannot tell the two instances apart. Telling them apart needs something instance-specific in /health (a start timestamp, or the pid), or a short unconditional wait past ThrottleInterval before the first probe.

[claude]

[Suggestion] /tmp/bridge-import-check.$$ is a predictable path in a world-writable sticky directory, and the 2> redirect follows symlinks — a pre-planted /tmp/bridge-import-check.<pid> symlink would be truncated as the installing user. The file also leaks if the script is interrupted between creation and the rm -f.

mktemp plus a trap ... EXIT handles both, and lines up with the $TMPDIR-aware convention CLAUDE.md already documents for the bridge hook-lock dir.

[claude]

[Suggestion] These two new H3 sections sit between the backend code block (lines 337-340) and the - **spool**: / - **tmux**: bullet list that documents those backends (line 392 onward). The bullets now read as a continuation of "Verifying supervision" rather than of the backend intro they belong to — and the spool bullet is the longest, most load-bearing block in the section, so the misattachment is noticeable read top-to-bottom.

Moving "Running it supervised" and "Verifying supervision" to after the backend bullet list would keep the backend prose contiguous.

[claude]

[Suggestion] _BRIDGE_LOG and _BRIDGE_ERR are listed alongside _BRIDGE_PORT, _BRIDGE_BACKEND, and the rest, but they are a different kind of variable: every other _BRIDGE_* name is read by bridge.py at runtime, whereas these two are read only by scripts/install-bridge-launchagent.sh:16-17 and baked into the plist at install time. Setting them in the environment of a running bridge does nothing.

The Operations section already carries exactly this warning for the bus _LOG / _ERR pair (they must be in the environment of make install-server itself); the bridge pair needs the same note against make install-bridge.

Related: the installer runs mkdir -p "$DATA_DIR" only, so an AGENT_EVENT_BUS_BRIDGE_LOG pointing outside the data directory leaves launchd unable to open StandardOutPath. A mkdir -p "$(dirname "$BRIDGE_LOG_FILE")" would cover it.

[claude]

[Suggestion] This line was correctly de-staled (dropping "That lands with the supervision story"), but the same claim survives verbatim in src/agent_event_bus/bridge.py:28-30:

(from the repo checkout - the console script lives in the project venv;
nothing puts it on PATH yet, that lands with the supervision story)

The supervision story is this PR. Worth pointing that module docstring at make install-bridge alongside the uv run form, since it is the first thing a reader of bridge.py sees.

Same class of leftover, non-blocking: tests/test_cli.py:1017 still names ~/.exports / ~/.zshrc in a docstring — the exact repo-specific paths this PR just generalized out of _session_id_from_env.

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review — Round 2

Summary

The single blocking finding from round 1 is fully resolved. Every launchctl list | grep probe for the bus label is now anchored — Makefile:154, scripts/install-launchagent.sh:33,53, scripts/dev.sh:15, and the new installer bus check at install-bridge-launchagent.sh:44 — and I checked the rest of the tree for stragglers: scripts/uninstall-launchagent.sh never used that pattern, so the sweep is complete.

I also re-verified the two design claims the unit comments make, at the source rather than on trust. KeepAlive is safe with the singleton lock: _acquire_singleton_locks(config) runs at bridge.py:2158, before uvicorn.run and therefore before the lifespan registration sweep. That ordering is what makes a crash-looping replacement harmless — it exits on the flock upstream of any bus mutation, so it cannot sweep away a live instance webhook row. Clean handoff: main() unregisters in its finally before closing the singleton fds, so cleanup by an outgoing instance cannot be overtaken by a new registration.

Previously Addressed (Filtered)

• [Important] Unanchored launchctl list | grep probes for the bus label — implemented.
• [Suggestion] make uninstall leaving the bridge supervised; stale guide.md:660 supervision note; installer Logs: label pointing at the file without bridge records; flat 2s health probe — all four implemented.

Findings

6 Suggestions, none blocking, posted inline. The most substantive: the installer import preflight cannot see uvicorn, which is imported lazily inside main() — the one dependency whose absence produces exactly the KeepAlive import-crash-loop that preflight exists to prevent. Narrow in practice, since uvicorn is a direct [project.dependencies] entry, so a venv that imports starlette will have it. The rest: the health poll answering from the outgoing instance on re-install (reporting accuracy, correct end state), a predictable /tmp path, guide.md section placement orphaning the backend bullet list, install-time-only env vars documented as runtime ones, and a stale bridge.py module docstring.

Also confirmed as non-issues: the conftest autouse scrub is ordered correctly relative to the patch.dict and monkeypatch.setenv tests that set those names deliberately, and pytest is still used in test_cli.py after the fixture moved out.

Verdict

APPROVE - No blocking findings. The supervision unit works for its stated purpose and its comments hold up against the code.

---

Automated review by Claude Code