Mail & Counters
The badge counts what's still waiting, not whether mail exists
A pane hosting an agent shows a small tray badge in its header once anything is queued for that agent. It renders a number, not a checkmark or a boolean dot — a boolean "you have mail" hides the one thing that actually decides whether you act now or wait for the agent's next run anyway: how much is backed up. The badge saturates once the count passes a small threshold, showing something like "9+" rather than letting a long number push the rest of the header out of shape, and it disappears entirely once nothing is waiting — there is no "0" state shown.
The count is read straight from the mailbox each time it renders rather than being incremented as messages arrive, so the badge cannot drift out of agreement with the queue it describes.
The queue belongs to the agent, not to a terminal
Pending mail is keyed by agent. The same queue opens from an agent's pane header and from its node in the Room, and it opens for a peer that has no local session at all — there is no separate per-session inbox that could disagree with it.
Opening it
Opening the badge — or choosing Pending Mail (n)… from an agent's context menu in the Room — shows what is queued for that agent, oldest to newest. Entries render in one of two shapes:
- A delegated task shows its current state, its context id, its objective, and the acceptance command that decides whether it is done, on an
Accept when:line. See Task Envelopes for what those fields mean. - A plain transport message shows its sender and the message text. These are queued exactly like tasks, so they appear here rather than being counted by the badge and then hidden by the surface that badge points at.
A single Run now action takes the agent's next turn on everything queued. There is no per-entry action, and nothing here types text into the agent's shell on your behalf: the surface will not ask a human to ghost-write an agent's message. If nothing is waiting, the popover says so plainly rather than presenting an empty list.
A mailbox has a limit
NEXUS does not queue an unbounded number of messages for an agent that never comes back to check. Once a mailbox is full, further messages are dropped rather than silently accepted and never delivered — and the drop is counted and surfaced, alongside whatever is still actually waiting, rather than disappearing without a trace. If you're seeing a dropped-message count climb, the fix is upstream of the mailbox: the recipient isn't taking enough turns to keep up with what's being sent to it.
What an agent itself can see
None of this is available to a connected agent as a documented tool call. The agent_* family lists reachable peers, originates tasks, and returns results; nothing in it lets an agent query its own queued mail depth over MCP. The badge and the pending-mail popover are surfaces for a human watching the workspace, not something a connected agent can introspect about itself through nexus-mcp.
Where to go next
- Delivery Semantics — why the count exists at all: delivery is next-turn, never immediate.
- Task Envelopes — the contract a delegated task carries, and the states it can move through.
- Sending Messages — the two ways a message gets into this mailbox in the first place.