feat(#2300): recv reports remaining inbox depth so agents know how many messages are left

hive-ag3nt/src/serve_common.rs

@@ -29,23 +29,32 @@ pub fn format_wake_prompt(
     } else {
         String::new()
     };
-    let pending = if unread == 0 {
-        String::new()
-    } else {
-        // Suggested batch size is clamped to the server-side recv cap
-        // so the hint never asks for more than one round-trip can
-        // deliver.
-        let batch = unread.min(u64::from(hive_sh4re::RECV_BATCH_MAX));
-        format!(
-            "\n\n({unread} more message(s) pending in your inbox — call `mcp__hyperhive__recv` \
-             with `max: {batch}` to drain the next batch before acting. If the \
-             backlog is stale/already handled, `ack_until(up_to: <highest [msg #N] seen>)` \
-             clears everything up to that id in one call instead.)"
-        )
-    };
+    let pending = pending_hint(unread);
     format!("{banner}{tag}Incoming message from `{from}`:\n---\n{body}\n---{pending}")
 }
 
+/// Shared "(N more message(s) pending …)" advisory appended after both the
+/// wake prompt body and the `recv` tool result whenever the inbox still has
+/// queued messages once the current message/batch is popped. Returns an empty
+/// string when `remaining == 0`. The leading `\n\n` separates it from the
+/// preceding body/message block, and the suggested `max` is clamped to the
+/// server-side recv cap so the hint never asks for more than one round-trip
+/// can deliver. One builder so the wake prompt and the in-turn recv result
+/// stay identical.
+#[must_use]
+pub fn pending_hint(remaining: u64) -> String {
+    if remaining == 0 {
+        return String::new();
+    }
+    let batch = remaining.min(u64::from(hive_sh4re::RECV_BATCH_MAX));
+    format!(
+        "\n\n({remaining} more message(s) pending in your inbox — call `mcp__hyperhive__recv` \
+         with `max: {batch}` to drain the next batch before acting. If the \
+         backlog is stale/already handled, `ack_until(up_to: <highest [msg #N] seen>)` \
+         clears everything up to that id in one call instead.)"
+    )
+}
+
 /// Field-named args for [`build_row`]. Mirrors the turn-stats row
 /// columns; `outcome` and `bus` borrow for the duration of the call.
 pub struct TurnRowArgs<'a> {