Summary
When Agent Alpha @mentions Agent Beta and Beta is offline (stopped/not running), the mention is silently lost. No warning is shown to Alpha, to the channel, or to any human observer. Beta never wakes up or catches the missed mention.
Agent-Side Impact
From the sending agent's perspective, this is a silent black hole. The agent has no way to:
- Check if the target is online before mentioning
- Detect that the mention was not delivered after sending
- Set a timeout or retry — there is no delivery receipt or acknowledgment protocol
This means any agent workflow that delegates to another agent via @mention is inherently fragile when the target may be offline. The sending agent will wait indefinitely with no recourse.
Steps to Reproduce
- Have a channel with two agents — e.g. Agent Alpha and Agent Beta
- Stop/ensure Agent Beta is not running
- Have Agent Alpha send a message that @mentions Beta (includes a
p tag with Beta's pubkey)
- Observe: no response from Beta, no warning or indicator anywhere
- Wait indefinitely — no timeout, no system notice, no feedback
Expected Behavior
At minimum one of:
- A visible warning appears in the channel ("Agent Beta is offline and may not see this mention")
- The system auto-starts Agent Beta when it receives an @mention directed at it
- The sender receives a delivery-failure or offline notice
- Agent Beta processes missed @mentions when it comes back online
Actual Behavior
Nothing. The message is stored and relayed normally but Agent Beta never processes it. The mention silently disappears from Beta's perspective because it has no active WebSocket subscription. The sending agent receives a successful send confirmation and has no way to know the message was not delivered.
In the observed case, a 30+ minute silent stall occurred before a human noticed and manually started the offline agent.
Root Cause (technical)
The relay's fan-out path (dispatch_persistent_event_inner in crates/buzz-relay/src/handlers/event.rs:351-416) delivers events only to active WebSocket subscribers via sub_registry.fan_out_scoped(). When an agent is offline, it has no subscriber, so the event is never delivered to its harness.
The presence infrastructure already exists and works correctly (crates/buzz-pubsub/src/presence.rs — get_presence() / get_presence_bulk()), but it is never consulted during event ingestion or fan-out.
The ACP harness (crates/buzz-acp/src/filter.rs) only processes events while running and subscribed. It subscribes with a since timestamp from connection time. There is no catch-up mechanism for missed mentions at startup — anything sent while the harness was down and outside the reconnect window is permanently lost from that agent's perspective.
The desktop app tracks agent status (ManagedAgent.status: "running" | "stopped") and can start agents on attach (channelAgents.ts:attachManagedAgentToChannel), but nothing triggers a start or warning at mention time.
Affected Code
| Location |
Role |
crates/buzz-relay/src/handlers/event.rs:351-416 |
Fan-out only reaches live WS connections |
crates/buzz-pubsub/src/presence.rs |
Presence API exists but unused at dispatch |
crates/buzz-acp/src/filter.rs:match_event() |
Harness only fires when running; no catch-up |
desktop/src/shared/api/types.ts:411 |
ManagedAgent.status not consulted at mention time |
Proposed Solutions (non-exclusive)
Option 1: Relay-side presence check + system notice (most reliable)
When the relay stores a message containing a p-tag whose recipient has no active WS subscription (checked via get_presence()), emit a system notice event back into the channel indicating the agent is offline. Works regardless of client type.
Option 2: ACP harness startup catch-up
When buzz-acp reconnects, extend the since-filter to replay missed @mentions that occurred while the harness was down. Requires verifying the current reconnect window actually covers mentions sent during downtime.
Option 3: Desktop UX inline warning (most visible)
When the desktop detects a message @mentioning a managed agent whose status is not "running", show an inline warning: "Agent Beta is offline and may not see this."
Option 4: Auto-start on mention (desktop)
Extend the desktop's agent lifecycle management to auto-start a stopped managed agent when it is @mentioned, similar to how direct human mentions already trigger agent startup.
Option 5: Delivery receipts / acknowledgment events
The mentioned agent's harness emits a lightweight ack event (e.g. kind:21xxx) when it processes a mention. If the sender doesn't see an ack within N seconds, it can surface a warning or retry. More complex but enables agent-to-agent reliability without requiring the relay to understand agent lifecycle.
Severity
P1 / High — This breaks agent-to-agent delegation entirely when the target is offline, with no fallback or error handling possible at the agent layer. The 30-minute silent stall observed is the best case (a human noticed). In an unattended workflow this could block indefinitely.
Related Work
Test Gap
No existing test covers the offline-mention scenario. filter.rs tests cover rule matching but not the "harness not running" case. No integration test checks relay behavior when a p-tagged recipient has no active subscription.
Summary
When Agent Alpha @mentions Agent Beta and Beta is offline (stopped/not running), the mention is silently lost. No warning is shown to Alpha, to the channel, or to any human observer. Beta never wakes up or catches the missed mention.
Agent-Side Impact
From the sending agent's perspective, this is a silent black hole. The agent has no way to:
This means any agent workflow that delegates to another agent via @mention is inherently fragile when the target may be offline. The sending agent will wait indefinitely with no recourse.
Steps to Reproduce
ptag with Beta's pubkey)Expected Behavior
At minimum one of:
Actual Behavior
Nothing. The message is stored and relayed normally but Agent Beta never processes it. The mention silently disappears from Beta's perspective because it has no active WebSocket subscription. The sending agent receives a successful send confirmation and has no way to know the message was not delivered.
In the observed case, a 30+ minute silent stall occurred before a human noticed and manually started the offline agent.
Root Cause (technical)
The relay's fan-out path (
dispatch_persistent_event_innerincrates/buzz-relay/src/handlers/event.rs:351-416) delivers events only to active WebSocket subscribers viasub_registry.fan_out_scoped(). When an agent is offline, it has no subscriber, so the event is never delivered to its harness.The presence infrastructure already exists and works correctly (
crates/buzz-pubsub/src/presence.rs—get_presence()/get_presence_bulk()), but it is never consulted during event ingestion or fan-out.The ACP harness (
crates/buzz-acp/src/filter.rs) only processes events while running and subscribed. It subscribes with asincetimestamp from connection time. There is no catch-up mechanism for missed mentions at startup — anything sent while the harness was down and outside the reconnect window is permanently lost from that agent's perspective.The desktop app tracks agent status (
ManagedAgent.status: "running" | "stopped") and can start agents on attach (channelAgents.ts:attachManagedAgentToChannel), but nothing triggers a start or warning at mention time.Affected Code
crates/buzz-relay/src/handlers/event.rs:351-416crates/buzz-pubsub/src/presence.rscrates/buzz-acp/src/filter.rs:match_event()desktop/src/shared/api/types.ts:411ManagedAgent.statusnot consulted at mention timeProposed Solutions (non-exclusive)
Option 1: Relay-side presence check + system notice (most reliable)
When the relay stores a message containing a
p-tag whose recipient has no active WS subscription (checked viaget_presence()), emit a system notice event back into the channel indicating the agent is offline. Works regardless of client type.Option 2: ACP harness startup catch-up
When
buzz-acpreconnects, extend thesince-filter to replay missed @mentions that occurred while the harness was down. Requires verifying the current reconnect window actually covers mentions sent during downtime.Option 3: Desktop UX inline warning (most visible)
When the desktop detects a message @mentioning a managed agent whose
statusis not"running", show an inline warning: "Agent Beta is offline and may not see this."Option 4: Auto-start on mention (desktop)
Extend the desktop's agent lifecycle management to auto-start a stopped managed agent when it is @mentioned, similar to how direct human mentions already trigger agent startup.
Option 5: Delivery receipts / acknowledgment events
The mentioned agent's harness emits a lightweight ack event (e.g.
kind:21xxx) when it processes a mention. If the sender doesn't see an ack within N seconds, it can surface a warning or retry. More complex but enables agent-to-agent reliability without requiring the relay to understand agent lifecycle.Severity
P1 / High — This breaks agent-to-agent delegation entirely when the target is offline, with no fallback or error handling possible at the agent layer. The 30-minute silent stall observed is the best case (a human noticed). In an unattended workflow this could block indefinitely.
Related Work
Test Gap
No existing test covers the offline-mention scenario.
filter.rstests cover rule matching but not the "harness not running" case. No integration test checks relay behavior when ap-tagged recipient has no active subscription.