fix(events-shim): stop wake hooks from taking posts meant for another session

Merged
KH
6d ago
+463-36

Problem

On a Mac running Agent Relay Desktop, the inbox was linked to an open Muse session (link_relay_wake, via events-shim serve). The link check reached the session, but none of the posts after it did. Unrelated Claude Code sessions got them instead.

Evidence from the inbox (get_webhook_events by id) and the Claude Code transcripts:

postreceivedstatetakenwhere it went
#803:14:36.9Zread+5.7 sa Claude Code session in another project (Stop-hook rewake)
#903:19:21.7Zread+3.5 sanother Claude Code session
#1003:36:56.8Zread+4.2 sa third Claude Code session
#11 (after removing the hooks)03:45:13.1Zwoken+7.3 sthe Muse session (receipt in its journal; Desktop activity injected)

Root cause. setup --claude installs async SessionStart/Stop hooks running listen --hook in ~/.claude/settings.json, so they run in every Claude Code session on the machine. All of them share the one inbox from webhooks.json. listenAsSessionOwner calls wait_for_webhook, which claims pending posts as read (mcp.ts handOver) and polls every second.

The relay forward is atomic: claimPending is one FOR UPDATE SKIP LOCKED statement, so a post is never delivered twice. But it claims only after the post request has finished reservePost, touch and appendEvent (service.ts). On the hosted store that took 3–7 s, and the post sat in pending the whole time. A hook listener almost always claimed it first. The link check was not affected because link_relay_wake sends it directly, not through the inbox.

Fix

  • Opt-in: listen --hook listens only in a session whose transcript (transcript_path from the hook input) shows a call to a webhooks MCP tool (mcp__webhooks__watch_webhooks|link_relay_wake|wait_for_webhook|get_webhook_events). The skill's first step is watch_webhooks, so a session that asked to watch opts in on its next Stop hook. A marker file (optin-<digest>) remembers this, so later turns do not re-read the transcript. Sessions that never used the inbox no longer take its posts.
  • Stand down: before each wait, listenAsSessionOwner (Claude Code and the Copilot/Gemini/Droid/Cursor/Amp turn-end hooks) calls watch_webhooks. If the inbox has a working relay wake link, it exits without claiming. If the inbox cannot be reached, the listener keeps its old behaviour.
  • Server side: wait_for_webhook takes no posts while a relay wake link works. It waits out its timeout and returns wake: "linked" with next steps, so an older listener that calls again at once does not spin. get_webhook_events still reads posts by id. Hosted Cloud gets this when it bumps @agent-relay/events-shim (it pins 18.3.0). The client changes apply as soon as hooks pick up @latest.

No change is needed to make the forward claim atomic. A follow-up could close the append→claim window completely by storing the post already claimed (sending) when a live link exists. That would change the EventsShimStore contract here and in Cloud's store.

Tests

  • listen --hook listens only in a session that opted in to the inbox, and remembers it: a session that has not opted in exits 0 and leaves the post pending; an opted-in one exits 2 with it and writes the marker.
  • listen --hook stands down while the inbox forwards posts through a relay wake link.
  • wait_for_webhook does not take posts while a relay wake link delivers them: the post ends woken (forwarded), not read; after unlink_relay_wake the wait returns posts again.
  • The existing listen --hook tests now give an opted-in transcript.
  • Mutation check: disabling either guard makes the matching new test fail.
  • vitest run packages/events-shim/src: 114 passed; tsc --noEmit and prettier are clean.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.