Coordination Between Sessions and Agents

A message arrives while Claude works on something else, and nothing stops. If Claude's session was launched with the Claude Code channel enabled, its own nexus MCP server announces a reference to the message, never its body, and never takes the message itself. That reference also wakes this same prompt's drain hook, which usually claims, acks and renders the body right here, before Claude's turn: Claude acts on it and claims nothing. Only a session without the plugin's hooks claims the reference itself with tuple_in, then answers with tuple_ack, or, if it cannot act on the message, tuple_nack, or tuple_release if it is only deferring. If the channel was never enabled, or nothing claims the row in time, the drain hook still claims, acks and shows whatever is waiting at Claude's next prompt, so a message reaches Claude either way.

The channel is opt-in, a Claude Code research preview: launching with --channels plugin:conexus@nexus-plugins skips the confirmation dialog once the plugin is on Claude Code's channel allowlist (the allowedChannelPlugins managed setting), and --dangerously-load-development-channels server:nexus confirms once, at a one-keystroke dialog, on every launch. Once it's live, the session's own nexus MCP server asks the engine at every wake for the mailbox rows that are due. It announces each row the engine hands back, at most one reference per mailbox per wake, and it never claims anything. The engine decides which row is due. A row nobody has announced is due at once. A row already announced is due again 150 seconds later if nobody holds a claim on it, up to five announcements in all. The engine stamps the announce time and count on the row in the same statement that returns it. After the fifth announcement, the row waits silently for the drain hook at Claude's next prompt. A second message right behind the first gets its own reference one wake apart, not gated on the first's ack. This is a rate limit, not a hard cap: it bounds how often an idle session is woken, not how many messages are in flight. A message whose write committed late is still announced, because the engine re-reads every claimable row each time and keeps the count itself. So the session keeps no cursor for its mail. A board topic keeps none either: a post is never claimed, so the engine stamps each post once per subscribing session and announces it to each of them once. The waiter stops on an engine that predates this announce mode, and the nx doctor channel row names that as the reason.

A notification names only what the server already controls: the subspace and the tuple id, so no sender's content ever rides along unread, and no claim rides along either. That same notification wakes the drain hook for this prompt, which usually claims, acks and renders the body here, and Claude acts on it, claiming nothing. Only a session without the plugin's hooks claims the message itself with tuple_in, the deliberate step a pull-based read always took, then calls tuple_ack, with a reply if one is due, and the engine writes the reply and consumes the message in one transaction. A tuple_nack returns the message to the mailbox for another try and counts as one failed attempt, the same as a lease that lapses with nobody renewing it. A claim only deferred, not failed, goes back with tuple_release instead, which counts nothing: nacking it by mistake risks dead-lettering the message after three.

The drain hook is the safety net. At each prompt it takes and acks up to ten waiting messages and shows their bodies to Claude, whether or not the channel ever reached Claude first. A message the channel already pointed to and shows up here again is the same message rendered in full, never a second one.

The hooks and the channel keep every session reachable by id and by name, even when a session clears or resumes.

At every start, resume, clear, and compact, the session-start hook gives Claude the session id, its main mailbox address, and a one-line subscribe instruction. It also writes a marker file, which the session's own MCP server later reads to learn that its session has changed. Claude calls ListAgents to learn the session's name, which the harness chooses. Then it calls tuple_subscribe("mailbox/<name>").

The subscribed mailbox set covers mailbox/<session id> (from the start) and mailbox/<name> (once subscribed). Subscribing also publishes directory/<name> with the session id and renews the entry every minute, so peers can find the session by name. An entry lasts five minutes, which means a name points only at a live session and is free again soon after the session ends.

Nexus ready (session: 5b354c36-d317-4a00-aa15-f567e65a7209).
…
MAILBOX SUBSCRIBE: call tuple_subscribe("mailbox/<name>") once, with <name> from a fresh ListAgents call…

ListAgents
This session is nexus-4a [102a61] — the name other sessions use to message it

/clear and /resume give the conversation a new session id. On /clear, the hook records the old session id and then writes the marker for the new id. The new session's own MCP server loads a fresh, empty subscription set for the new id. Claude then calls ListAgents for the current name and subscribes again. At each prompt, the drain hook also drains the old session's mailbox into the new session, so mail for the old id still arrives.

• Lease. A take operation gives a message to one reader for at most fifteen minutes. A reader that needs more time calls tuple_renew.
• Failed reader. A reader that stops before its ack does not lose the message: its lease ends, and the next reader gets it. A reply commits with its ack, so a crash cannot leave a request answered but still waiting.
• Dead letter. A nack counts as one failed attempt. A lease that ends without an ack also counts as one. After three attempts, the message becomes a dead letter that stays visible to every session. The drain hook shows a dead letter once, as UNDELIVERABLE.
• Schema. The engine refuses a tuple for a subspace that has no template, and a tuple with an undeclared, missing, or disallowed key or dimension.
• Retention. A message lasts at most seven days. Ledger records last 90 days, and nobody can take them.
• Size. A message body is at most 4096 bytes. Each key or dimension value is at most 256 bytes.
• Parking. A take operation on an empty mailbox can park for up to 25 seconds. A session using the channel seldom needs this.
• Directory. An entry lasts five minutes, and the subscription renews it every minute. mailbox_send refuses a name with no live holder or with two holders. nx tuple directory <name> shows the holders.
• Channel. It announces each mailbox row the engine marks as due, at most one reference per mailbox per wake, never claiming one itself. The engine offers a row nobody holds a claim on again every 150 seconds, up to five announcements in all, then leaves it for the drain hook.
• Drain hook. The drain hook takes at most ten messages at one prompt and uses at most six seconds.
• Ledger writes. The dispatch file belongs to one session, and the ledger is the copy every session can read. A failed ledger write never stops the agent.
• Sweep. Every six hours, the engine returns claims whose lease ended and removes expired rows.
• /branch. /branch runs no session-start hook, so the drain hook moves the marker at the branch's first prompt, and the old session's channel push stops.
• Health. nx doctor shows six tuple rows. Lesson 5 lists them.

hook, channel, engine, and harness steps run by themselves. Claude, agent, and peer steps are tool calls that a model makes.