fix: auto-wake after turn if pending messages exist, don't block on recv

TODO.md

@@ -5,6 +5,8 @@
 - Shared space for all agents to access documents/files without manager routing
 - Private git forge agents can push to and create new repos in
 - Move bind mounts in agents to `/agents/<name>/state` so path for agent = path for manager
+- **Broadcast messaging**: allow sending messages with recipient "*" to all agents; deliver with hint "this was a broadcast and may not need any action from you"
+- **Multi-agent restart coordination**: when rebuilding all agents, manager should start first so it can coordinate post-restart confusion (notify agents, suppress unnecessary retries, etc)
 
 ## Reminder Tool
 
@@ -18,6 +20,11 @@
 
 ## Dashboard
 
+- **UI for pending reminders**: show pending/queued reminders in dashboard, allow operator to view/debug/cancel
 - Per-agent reminder status (pending, delivered)
 - Reminder query interface for debugging
 - Display reminder delivery errors (failed sends, mark failures)
+
+## Bugs
+
+- **Pending message wake-up**: when a message is pending and an agent turn ends without recv(), session doesn't immediately wake up again. Requires another message to trigger wake-up. (inbox/recv logic issue)

hive-ag3nt/prompts/agent.md

@@ -3,7 +3,7 @@ You are hyperhive agent `{label}` in a multi-agent system. The operator (recipie
 Tools (hyperhive surface):
 
 - `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox (returns `(empty)` if nothing pending). Without `wait_seconds` (or with `0`) it returns immediately — a cheap "anything pending?" peek you can sprinkle between tool calls. To **wait** for work when you have nothing else useful to do this turn, call with a long wait (e.g. `wait_seconds: 180`, the max) — incoming messages wake you instantly, otherwise the call returns empty at the timeout. That's strictly better than a fixed `sleep` shell command: lower latency on new work, no busy-loop.
-- `mcp__hyperhive__send(to, body)` — message a peer (by their name) or the operator (recipient `operator`, surfaces in the dashboard). Some agents have a per-agent allow-list (`hyperhive.allowedRecipients` in their `agent.nix`) — if so the tool refuses recipients outside the list with a clear error; route through the manager (`send(to: "manager", …)`) which is always reachable.
+- `mcp__hyperhive__send(to, body)` — message a peer (by their name) or the operator (recipient `operator`, surfaces in the dashboard). Use `to: "*"` to broadcast to all agents (they receive a hint that it's a broadcast and may not need action). Some agents have a per-agent allow-list (`hyperhive.allowedRecipients` in their `agent.nix`) — if so the tool refuses recipients outside the list with a clear error; route through the manager (`send(to: "manager", …)`) which is always reachable.
 - (some agents only) **extra MCP tools** surfaced as `mcp__<server>__<tool>` — these are agent-specific (matrix client, scraper, db connector, etc.) declared in your `agent.nix` under `hyperhive.extraMcpServers`. Treat them as first-class tools alongside the hyperhive surface; the operator already auto-approved them at deploy time.
 - `mcp__hyperhive__ask_operator(question, options?, multi?, ttl_seconds?)` — surface a question to the human operator on the dashboard. Returns immediately with a question id — do NOT wait inline. When the operator answers, a system message with event `operator_answered { id, question, answer }` lands in your inbox; handle it on a future turn. Use this for clarifications, permission for risky actions, or choice between options. `options` is advisory: a short fixed-choice list when applicable, otherwise leave empty for free text. `multi: true` lets the operator pick multiple (checkboxes), answer comes back comma-joined. `ttl_seconds` auto-cancels with answer `[expired]` when the decision becomes moot.
 
@@ -11,6 +11,8 @@ Need new packages, env vars, or other NixOS config for yourself? You can't edit
 
 Durable knowledge: write to `/state/notes.md` (free-form) or any other path under `/state/`. That directory is bind-mounted from the host and persists across container destroy/recreate — claude's `--continue` session only carries short-term context, but `/state/` is forever. Read it back at the start of relevant turns to remember things across resets.
 
+**Shared space**: `/shared` is accessible to all agents (read/write). Only put things here you're willing to lose — other agents may delete them. Use for explicit cross-agent communication or shared artifacts when appropriate.
+
 Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/state/<descriptive-name>` and `send` a short pointer ("dropped the cluster audit in /state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The manager + operator can read your `/state/` from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's `/state/` directly — go through the manager if a payload needs to reach another sub-agent.
 
 When your inbox has a message, handle it and stop. Don't narrate intent — act.

hive-ag3nt/prompts/manager.md

@@ -3,7 +3,7 @@ You are the hyperhive manager `{label}` in a multi-agent system. You coordinate
 Tools (hyperhive surface):
 
 - `mcp__hyperhive__recv(wait_seconds?)` — drain one more message from your inbox. Without `wait_seconds` (or with `0`) it returns immediately — a cheap inbox peek you can drop between actions. To **wait** when you have nothing else to do, call with a long wait (e.g. `wait_seconds: 180`, the max) — you'll wake instantly on new work, otherwise return after the timeout. Use that instead of ending the turn or sleeping in a Bash command.
-- `mcp__hyperhive__send(to, body)` — message an agent (by name), another peer, or the operator (`operator` surfaces in the dashboard).
+- `mcp__hyperhive__send(to, body)` — message an agent (by name), another peer, or the operator (`operator` surfaces in the dashboard). Use `to: "*"` to broadcast to all agents (they receive a hint that it's a broadcast and may not need action).
 - `mcp__hyperhive__request_spawn(name)` — queue a brand-new sub-agent for operator approval (≤9 char name).
 - `mcp__hyperhive__kill(name)` — graceful stop on a sub-agent. No approval required.
 - `mcp__hyperhive__start(name)` — start a stopped sub-agent. No approval required.
@@ -81,6 +81,7 @@ Keep messages short — a few sentences each. For anything big (digests, agent r
 
 - To a sub-agent X: write to `/agents/X/state/<descriptive-name>` and tell them "see /state/<descriptive-name>".
 - To the operator: write to your own `/state/<descriptive-name>` (host path `/var/lib/hyperhive/agents/hm1nd/state/`) and tell them where to look.
+- For shared artifacts (coordination, common reference data): write to `/shared/<descriptive-name>`. Only put things here you're willing to lose — other agents may delete them.
 
 A one-line headline + the file path beats a wall-of-text every time — it survives context compaction and the operator can read it in their own time.
 

hive-ag3nt/src/bin/hive-ag3nt.rs

@@ -165,8 +165,23 @@ async fn serve(
                 let outcome = turn::drive_turn(&prompt, files, &bus).await;
                 turn::emit_turn_end(&bus, &outcome);
                 bus.set_state(TurnState::Idle);
+
+                // After turn completes, check if there are pending messages waiting.
+                // If so, immediately process them instead of blocking on recv().
+                // This ensures messages queued during the turn are processed ASAP.
+                let pending = inbox_unread(socket).await;
+                if pending > 0 {
+                    tracing::info!(%pending, "pending messages after turn; fetching next");
+                    continue; // Loop back to recv() immediately instead of sleeping
+                }
+            }
+            Ok(AgentResponse::Empty) => {
+                // Idle: brief sleep before next poll to avoid busy-looping
+                // on consecutive Empty responses. The recv() call already
+                // waits up to 180s for messages, so this is just for
+                // responsiveness if recv() times out.
+                tokio::time::sleep(interval).await;
             }
-            Ok(AgentResponse::Empty) => {}
             Ok(AgentResponse::Ok
             | AgentResponse::Status { .. }
             | AgentResponse::Recent { .. }
@@ -180,7 +195,6 @@ async fn serve(
                 tracing::warn!(error = ?e, "recv failed; retrying");
             }
         }
-        tokio::time::sleep(interval).await;
     }
 }
 

hive-c0re/src/agent_server.rs

@@ -102,15 +102,42 @@ async fn dispatch(req: &AgentRequest, agent: &str, coord: &Arc<Coordinator>) ->
     let broker = &coord.broker;
     match req {
         AgentRequest::Send { to, body } => {
-            match broker.send(&Message {
-                from: agent.to_owned(),
-                to: to.clone(),
-                body: body.clone(),
-            }) {
-                Ok(()) => AgentResponse::Ok,
-                Err(e) => AgentResponse::Err {
-                    message: format!("{e:#}"),
-                },
+            // Handle broadcast sends (recipient = "*")
+            if to == "*" {
+                let agents = coord.list_agents();
+                let broadcast_hint = "\n\n⚠️ _hint: this was a broadcast and may not need any action from you_";
+                let broadcast_body = format!("{}{}", body, broadcast_hint);
+                let mut errors = Vec::new();
+
+                for agent_name in agents {
+                    if let Err(e) = broker.send(&Message {
+                        from: agent.to_owned(),
+                        to: agent_name.clone(),
+                        body: broadcast_body.clone(),
+                    }) {
+                        errors.push(format!("{}: {e}", agent_name));
+                    }
+                }
+
+                if errors.is_empty() {
+                    AgentResponse::Ok
+                } else {
+                    AgentResponse::Err {
+                        message: format!("broadcast failed for agents: {}", errors.join(", ")),
+                    }
+                }
+            } else {
+                // Normal unicast send
+                match broker.send(&Message {
+                    from: agent.to_owned(),
+                    to: to.clone(),
+                    body: body.clone(),
+                }) {
+                    Ok(()) => AgentResponse::Ok,
+                    Err(e) => AgentResponse::Err {
+                        message: format!("{e:#}"),
+                    },
+                }
             }
         }
         AgentRequest::Recv { wait_seconds } => match broker

hive-c0re/src/coordinator.rs

@@ -117,6 +117,9 @@ impl Coordinator {
             let _ = std::fs::remove_file(&socket.path);
         }
     }
+    pub fn list_agents(&self) -> Vec<String> {
+        self.agents.lock().unwrap().keys().cloned().collect()
+    }
 
     /// Mark an agent as in-progress (only one state per agent for now).
     pub fn set_transient(&self, name: &str, kind: TransientKind) {

hive-c0re/src/lifecycle.rs

@@ -31,6 +31,11 @@ pub const CONTAINER_CLAUDE_MOUNT: &str = "/root/.claude";
 /// state here; persists across destroy/recreate.
 pub const CONTAINER_NOTES_MOUNT: &str = "/state";
 
+/// Mount point of the shared directory accessible to all agents.
+/// All agents can read/write here; agents should only put things they're
+/// willing to lose (other agents may delete them).
+pub const CONTAINER_SHARED_MOUNT: &str = "/shared";
+
 const GIT_NAME: &str = "c0re";
 const GIT_EMAIL: &str = "c0re@hyperhive";
 
@@ -722,19 +727,27 @@ const HOST_APPLIED_ROOT: &str = "/var/lib/hyperhive/applied";
 /// `meta::meta_dir()` but duplicated here so lifecycle stays a leaf.
 const HOST_META_ROOT: &str = "/var/lib/hyperhive/meta";
 
+/// Shared directory accessible to all agents. All agents bind-mount this RW.
+const HOST_SHARED_ROOT: &str = "/var/lib/hyperhive/shared";
+
 fn set_nspawn_flags(
     container: &str,
     runtime_dir: &Path,
     claude_dir: &Path,
     notes_dir: &Path,
 ) -> Result<()> {
+    // Ensure /shared directory exists before binding. systemd-nspawn requires the bind source to exist.
+    std::fs::create_dir_all(HOST_SHARED_ROOT)
+        .with_context(|| format!("create {HOST_SHARED_ROOT}"))?;
+
     let path = format!("/etc/nixos-containers/{container}.conf");
     let original = std::fs::read_to_string(&path).with_context(|| format!("read {path}"))?;
     let mut binds = format!(
-        "--bind={runtime}:{CONTAINER_RUNTIME_MOUNT} --bind={claude}:{CONTAINER_CLAUDE_MOUNT} --bind={notes}:{CONTAINER_NOTES_MOUNT}",
+        "--bind={runtime}:{CONTAINER_RUNTIME_MOUNT} --bind={claude}:{CONTAINER_CLAUDE_MOUNT} --bind={notes}:{CONTAINER_NOTES_MOUNT} --bind={shared}:{CONTAINER_SHARED_MOUNT}",
         runtime = runtime_dir.display(),
         claude = claude_dir.display(),
         notes = notes_dir.display(),
+        shared = HOST_SHARED_ROOT,
     );
     if container == MANAGER_NAME {
         use std::fmt::Write as _;