Wait - Block Until Messages Arrive

Wait for messages on specific topics, enabling synchronization between agents and coordinated handoff workflows.

When to Use

• Waiting for another agent to complete work
• Coordinating handoff between agents
• Blocking until a response or acknowledgment arrives
• Synchronizing at specific points in distributed workflows

How It Works

The hive msg sub --wait command polls the specified topic every 500ms until:

• A message arrives (success, exit 0)
• The timeout is reached (prints JSON status, exit 1)

Default timeout is 24h for --wait mode. Messages are NOT acknowledged unless --ack is used.

Commands

Wait for Single Message

hive msg sub --wait --topic <topic>

Examples:

# Wait for handoff message (24h default timeout)
hive msg sub --wait --topic agent.abc.inbox

# Wait for build completion
hive msg sub --wait --topic build.main.status

Wait with Custom Timeout

hive msg sub --wait --topic <topic> --timeout <duration>

Timeout format: s (seconds), m (minutes), h (hours)

# Short timeout for quick checks
hive msg sub --wait --topic notifications --timeout 5s

# Moderate timeout for typical handoffs
hive msg sub --wait --topic agent.abc.inbox --timeout 2m

# Long timeout for slow operations
hive msg sub --wait --topic build.production --timeout 10m

Wait and Acknowledge

hive msg sub --wait --topic <topic> --ack

Mark the received message as read so it won't appear in unread queries.

Wait with Wildcard Topics

# Wait for any agent to respond
hive msg sub --wait --topic "agent.*.response"

# Wait for any build event
hive msg sub --wait --topic "build.*.status"

Monitor Continuously

Use --listen mode for continuous message monitoring (outputs ALL messages until timeout):

hive msg sub --listen --topic notifications --timeout 1h

Key difference: --wait returns after ONE message. --listen continues polling and outputs ALL messages.

Inbox Wait Shorthand

hive msg inbox --wait
hive msg inbox --wait --timeout 2m --ack

Equivalent to hive msg sub --wait --topic agent.<id>.inbox but auto-detects the inbox topic.

Output Format

All output is JSON Lines on stdout. On timeout, a JSON status line is printed:

{"status":"timeout","topic":"agent.abc.inbox","duration":"30s"}

Exit code is 1 on timeout.

Timeout Guidelines

| Duration | Use Case | |----------|----------| | 5-30s | Quick handoffs between active agents | | 1-5m | Normal agent handoffs, human review | | 10m-1h | Build/test operations, background processing | | 1-24h | Overnight jobs, asynchronous collaboration |

Common Workflows

Coordinate Agent Handoff

# Complete work, notify, and wait for acknowledgment
hive msg pub --topic agent.bob.inbox -m "Feature X ready. Branch: feat/x"
hive msg sub --wait --topic agent.bob.inbox.ack --timeout 2m

Handle Request-Response

# Send request
hive msg pub --topic coordinator.requests -m "Need assignment: task-type-X"

# Wait for response
hive msg sub --wait --topic agent.myself.inbox --timeout 1m

Handle Timeouts

if hive msg sub --wait --topic agent.bob.inbox --timeout 30s; then
    echo "Message received"
else
    echo "Timeout: no message received"
fi

Additional Resources

For advanced patterns and troubleshooting, see:

• references/troubleshooting.md - Common issues and solutions

Related Skills

• /hive:inbox - Check inbox for messages
• /hive:publish - Send messages to other agents
• /hive:session-info - Get session details and inbox topic