fix(events-shim): stop wake hooks from taking posts meant for another session
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:
| post | received | state | taken | where it went |
|---|---|---|---|---|
| #8 | 03:14:36.9Z | read | +5.7 s | a Claude Code session in another project (Stop-hook rewake) |
| #9 | 03:19:21.7Z | read | +3.5 s | another Claude Code session |
| #10 | 03:36:56.8Z | read | +4.2 s | a third Claude Code session |
| #11 (after removing the hooks) | 03:45:13.1Z | woken | +7.3 s | the 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 --hooklistens only in a session whose transcript (transcript_pathfrom 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 iswatch_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) callswatch_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_webhooktakes no posts while a relay wake link works. It waits out its timeout and returnswake: "linked"with next steps, so an older listener that calls again at once does not spin.get_webhook_eventsstill 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 endswoken(forwarded), notread; afterunlink_relay_wakethe wait returns posts again.- The existing
listen --hooktests 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 --noEmitand prettier are clean.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.