fix(events-shim): one inbox wakes one session, and says which
Problem
This was found live. A person made one inbox on the webhook-inbox page and ran setup for both Claude Code and Codex on it, because every agent tab shows the same MCP URL.
servelinked the inbox's relay wake to the Codex session.- A brand-new Claude Code session never woke. Since 18.9.0 (#2194),
listen --hookonly listens in sessions whose transcript shows a webhooks tool call. Every hook listener also stands down while a relay wake link works. - The Claude session then called
watch_webhooks, readwake: "linked"with "each post is injected into this session", and told the person the inbox was linked to it. That was false: the link targets Codex. - Setup still said "Start a new Claude Code session. Each post wakes it by itself".
One inbox wakes exactly one session, but nothing said which one, and the opt-in broke fresh Claude-only sessions.
Change
a. Claude wakes without opt-in, still one session. A per-inbox owner record (claude-owner-<digest>.json) names the Claude Code session that takes posts.
- The SessionStart hook writes it: the most recently started session takes over.
claude -pruns and compactions don't. - A webhooks MCP tool call found in the transcript since the last scan also takes over. This is the explicit way to move posts to an older session.
- When the owner's
claudeprocess has exited, the record is vacant and the next hook to run takes it. - An older listener checks ownership in its loop and every 2 s during a wait. It cuts its wait off (a leased batch is released at once) and exits, so it never takes another post.
Kept from #2190, #2194 and #2211:
- one listener per inbox (the inbox lock is unchanged);
- no hook listener takes posts while a working relay wake link exists (now logged with the target agent);
- leases and acks are untouched.
b. Truthful link reporting. WakeTarget.agent is new and optional.
link_relay_waketakesagentand answerslinked_agent. It also answersreplaced_agentand says "The inbox no longer wakes …" when it moves a link.watch_webhooksreportslinked_agentandlinked_at, and its next steps say "linked to the Agent Relay agent "X" … Compare "X" with your own Agent Relay agent name. If it is not yours, the posts do not come to this session". It no longer says the posts go to this session.- An unnamed link reads
linked_agent: null, with "unless you called link_relay_wake yourself in this conversation, assume the link wakes another session". linkAgent(serve andlink --codex-hook) passes the agent name.- The feed reports
agent.wake_agent. - The skill text tells the agent to compare names.
c. Multi-CLI setup clarity, and per-agent inboxes that actually work.
- Each CLI now keeps its own inbox (
inboxesinwebhooks.json). Before, every hook read the singlemcpUrl, so a second inbox for a second agent on the same machine replaced the first one's. serve,linkanduninstallwork per inbox.- Configs saved before this keep their known CLIs (core kinds, and Claude when its hook is installed) on their old inbox.
- Setup refuses (exit 2, nothing written) to add a waking CLI to an inbox another CLI already uses, or to one linked to another agent. The message names the holder and points to making a separate inbox.
--share-inboxoverrides. - When CLIs share an inbox, setup prints "One inbox wakes one session, not one per agent. Claude Code, Codex share this inbox, so:", says who wins and how it switches, and points to an inbox per agent.
Tests
npx vitest run --root . packages/events-shim/src: 147 pass. Reverting only cli.ts, mcp.ts, types.ts and service.ts fails 11 of them:
- fresh session wakes without a tool call; a non-owner takes nothing;
- a newer session takes over and the older listener exits without a post (two concurrent listeners);
- a closed owner is vacant;
claude -pand compaction don't take over; - a tool call takes over (long transcript, chunked);
watch_webhooks/link_relay_wakename the agent,replaced_agent, and the unnamed-link text;linkpasses the agent;- setup refuses or allows with
--share-inboxand prints who wins; - setup refuses an inbox linked to a named agent;
- Claude and Codex on separate inboxes wake independently;
- legacy config migration;
- the new setup copy.
Typecheck and build are clean.
Hosts
The hosted inbox stores the wake link in fixed columns. It shows linked_agent once it persists WakeTarget.agent (a follow-up in cloud). Until then links read as unnamed, and the tool text never claims the link for the reader.
Companion page PR in agentrelay.com: per-agent inboxes on the page (linked in a comment).
Live verification on a macOS machine: results will be posted as a comment.
🤖 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.