#2009 fix(install): also install the short `relay` launcher

Problem

The npm package exposes both agent-relay and relay bins, and the docs, quickstart and relay init's own output tell users to run relay init, relay agent register, etc. But install.sh (the recommended installer) only wrote $BIN_DIR/agent-relay, so after curl ... install.sh | bash, relay is "command not found".

Change

• install.sh writes $BIN_DIR/relay with the same body as the agent-relay launcher (same env lines; standalone and node/source variants), via a new write_launchers helper.
• Both launchers now carry a marker line: # agent-relay launcher (written by the Agent Relay installer). (There was no marker before; install.sh only knew its launcher by path.)
• Same transaction: an existing installer-written relay is backed up before the standalone install and restored by undo_cli on any rollback (rejected/unavailable broker, INT/TERM/HUP), or removed if it did not exist before. A failed install leaves both launchers untouched; a successful one updates both.
• Foreign relay: if $BIN_DIR/relay exists without the marker, it is never backed up, replaced or removed (including on rollback), and the installer warns once: ... was not installed by Agent Relay; leaving it alone. Use \agent-relay` instead of `relay`.It never fails the install. npm's ownrelay symlink (.../node_modules/agent-relay/...) is left alone with an info line instead of the warning. If our relaycannot be backed up, onlyrelay` is skipped (install proceeds).
• verify_installation warns if another relay comes earlier on the original PATH; the usage footer lists both launchers.
• agent-relay uninstall (core-maintenance.ts) now also removes ~/.local/bin/relay, but only when it carries the marker. install.sh itself has no uninstall path.
• Standalone CLI invoked through relay: the launcher execs the binary by path, so argv[0]/program name is unchanged (help shows Usage: agent-relay ..., same as npm's relay bin).

Tests

• scripts/test-install-atomic.sh: both launchers created and identical, relay --version runs the new CLI; upgrade replaces our older relay; rejected broker restores both launchers byte-identical (and removes both on a fresh install); foreign relay preserved byte-identical with a single warning on success and on rollback, install still exits 0; npm relay symlink left alone without the warning; relay backup failure skips only relay; every signal-window case (TERM/INT/HUP during broker download, smoke test, between copies, read-back hash) now also asserts the relay launcher is byte-identical; source launcher also writes relay. 252 pass; the only failure is the pre-existing sha256_of falls back to shasum only (no shasum on the test machine; fails on main too).
• core.test.ts: uninstall removes our relay launcher, keeps a foreign one.
• install-script.test.ts: both launcher variants carry the marker; install.sh's LAUNCHER_MARKER matches the constant uninstall checks.
• shellcheck: no new findings beyond one more SC2329 note of the existing kind (indirectly invoked test override).
• E2E in node:22 docker with this branch's install.sh against the current release (v14.0.0): relay --version → 14.0.0, agent-relay --version → 14.0.0, relay --help works; re-run updates both; with a foreign relay in ~/.local/bin, it is kept and the warning is printed.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

Agent Relay sessions

• claude session a70137ea · opened via gh pr create · last active 2026-10-27
• claude session 5a4f854b · contributor · ran gh pr commands · last active 2026-10-28