feat(keepalive): add amq-keepalive, a terminal-session wake supervisor for macOS

[ohade]

This adds amq-keepalive as a second binary (cmd/amq-keepalive + internal/keepalive/*): a supervisor that keeps wake delivery attached to explicitly registered terminal sessions on macOS. It implements the Supervisor recipes contract from COOP.md, meaning the OS supervises it (user LaunchAgent), it never parses AMQ mailbox, lock, presence, or target files, and it talks to AMQ only through the public CLI (target-aware amq wake, amq env --json).

What it adds over the raw launchd recipe: a registry of attached terminal targets with Ghostty and cmux adapters (exact terminal-id targeting, fail-closed injection), reattach after reboot or sleep, SessionStart reattach hooks for Claude Code and Codex (install-hook), and a doctor command.

I know the repo is deliberately daemon-free, so to be upfront about it: I read this as staying inside that boundary (launchd owns the lifecycle, this is just the CLI it supervises plus a registry). If you'd rather not take a supervisor into the tree at all, no hard feelings, close it, but I wanted to offer the real thing rather than just a docs pointer.

Scope notes:

1. Runtime behavior is macOS-oriented (launchd, Ghostty AppleScript, cmux JSON RPC). It compiles on all four GOOS targets your CI cross-builds (linux, darwin, windows, freebsd) and vets clean. The one platform-specific call is the registry advisory lock (syscall.Flock), which is behind a //go:build unix file with a compile-only no-op fallback for Windows; the in-process mutex still serializes access within a process there.
2. Not touched: goreleaser/Homebrew packaging and the release manifest. If you take this, shipping the second binary in releases can be a follow-up.
3. The sample SessionStart hook script lives at scripts/amq-keepalive-session-start.sh with a drift test keeping it in sync with the embedded copy.

Verification: make ci green locally (check-skills, fmt-check, vet, golangci-lint 0 issues, full go test, smoke). The ported packages bring 70 tests of their own; adapters are tested through a deterministic file adapter.

[avivsinai]

Thanks for building this — and for the honesty in the PR body about the philosophy call. We did a deep pass (independent Claude + Codex reviews, cross-checked, findings runtime-verified). Verdict up front:

Not in-tree. Keep amq-keepalive in your repo, and reopen #244 — I'll take the docs link. Closing #244 as "keep it simple" was the wrong simplification; it's the right shape.

Why external is the answer

• It's the layer AMQ explicitly disclaims. CLAUDE.md: "Long-running wake/monitor supervision belongs to launchd, systemd, or another layer above daemon-free AMQ." This is that layer. Your launchd-owns-the-lifecycle argument is technically true, but the boundary in question isn't daemon-free — it's which repo owns the supervision layer, and that's already carved out.
• Your own architecture proves the seam. internal/keepalive imports zero AMQ internals and talks to AMQ only by exec-ing the public CLI (amq env --json, amq wake ...). That's exactly right — and it means in-tree buys you nothing except blessing. It would build verbatim as a standalone module.
• In-tree as-is doesn't even ship. .goreleaser.yaml builds only ./cmd/amq and the Homebrew formula installs only amq. Merged as-is, users still can't install amq-keepalive from a release — +5,580 LOC, a second cross-build target, and two third-party adapter surfaces (Ghostty AppleScript, cmux RPC) for zero delivered distribution.
• Precedent. amq-squad stayed external for a less invasive scope. keepalive additionally rewrites ~/.claude/settings.json and Codex hook config and manages LaunchAgents — a generic transport shouldn't own editing other products' configs.

Two contract failures (blocking regardless of placement)

1. retire-session calls a command that doesn't exist. internal/keepalive/amq/runner.go:129 invokes amq wake retire -json .... There is no retire subcommand — it was deliberately deferred out of #232 pending #235's identity-safety work. Runtime-verified against a fresh amq build: the invocation parses as a plain foreground wake and exits 1 ("amq wake requires a real terminal…"). The suite can't see this because runner_test.go:91 / app_test.go:300 stub amq with a fake that prints {"status":"retired"}.
2. Exact-target reattach doesn't exist in AMQ. supervisor.go:54-58 assumes --accept-existing-wake accepts only the exact live target, but the reuse path in internal/cli/wake_unix.go never compares the requested target/TargetDigest against the persisted lock. Reattaching terminal A→B can mark B active in your registry while the live wake keeps injecting into A — wrong-terminal delivery of message-derived text. TestWrongExistingTargetFailsClosedInsteadOfMarkingActive fabricates the fail-closed sentinel in a fake runner; the real path can't produce it.

Credit where due — the security review came back clean

osascript gets the payload as argv (never spliced into script source), cmux params are json.Marshal-built with no shell anywhere, hook edits are parse→modify→atomic 0600 write with backups, registry is 0700/0600 with correct flock+tempfile+rename atomicity, and the "never parses AMQ internals" claim verified true. Genuinely well built.

Worth fixing wherever it lives: uninstall removes the LaunchAgent but never removes the installed Claude/Codex hooks (one-way persistence); CLI.RepairWake is dead code; context.Background() in main means the supervise loop's ctx.Done() can never fire.

The part that does belong upstream

If the --inject-via contract has gaps for external supervisors, file a focused issue — stabilizing/documenting that as a versioned surface helps every terminal adapter, not just this one. wake retire is wanted but blocked on #235; keepalive's retire path should track that issue rather than assume the command.

So: reopen #244 and I'll merge the link. And thank you — this is the most rigorous external contribution this repo has had.

[avivsinai]

Re-reviewed against current main (post v0.45.0), and I owe you a good-news update: both blocking findings from my earlier review are now resolved by AMQ's own hardening work, so the contract amq-keepalive builds on is now stable and released.

• amq wake retire now exists (shipped in v0.45.0 via feat(wake): add amq wake retire for identity-safe inject-via stop #256, tracked by Wake-lifecycle signal safety: stable process capability, tri-state inspection, atomic lock lifecycle (prereq for wake retire) #235). Your RetireWake invocation already matches its contract shape — --inject-via plus ordered inject <adapter> <target> fixed args — so the runtime-1-exit I hit is gone against a released amq.
• The exact-target reuse gap is closed. The --accept-existing-wake path now runs through requireWakeLockUsable, which compares sameWakeInjectorIdentity = injector path plus the full fixed argv. Because your adapters carry the terminal id as a fixed inject-arg, a reattach A→B now fails closed (existing inject-via wake … uses a different injector path or fixed arguments) instead of the wrong-terminal delivery I flagged. That was fix(wake): close cooperative-stop duplicate-injection window and harden Darwin lifecycle #260, post-Wake-lifecycle signal safety: stable process capability, tri-state inspection, atomic lock lifecycle (prereq for wake retire) #235.

So the two correctness blockers weren't really about your code — they were AMQ contract gaps, and we've now filled them.

The placement call is unchanged, and it's the one that governs: this is the supervision layer AMQ explicitly disclaims ("belongs to launchd, systemd, or another layer above daemon-free AMQ"), and your own clean seam (zero AMQ internals, public-CLI-only) proves it needs no in-tree blessing. So I'm keeping it external, exactly as you generously offered.

Closing this, and I've taken the docs link myself — #263 adds the COOP.md pointer to ohade/amq-keepalive, using your wording from #244, credited to you. Thank you again; this remains the most rigorous external contribution the repo has had.