docs: add missing #[must_use], # Errors, # Panics across public api

hive-ag3nt/src/mcp.rs

@@ -114,6 +114,7 @@ impl From<hive_sh4re::ManagerResponse> for SocketReply {
 /// Format helper for "send-like" tools (anything that expects an `Ok`).
 /// `tool` and `ok_msg` only appear in the result string; they don't change
 /// behavior.
+#[must_use]
 pub fn format_ack(resp: Result<SocketReply, anyhow::Error>, tool: &str, ok_msg: String) -> String {
     match resp {
         Ok(SocketReply::Ok) => ok_msg,
@@ -131,6 +132,7 @@ pub fn format_ack(resp: Result<SocketReply, anyhow::Error>, tool: &str, ok_msg:
 /// and `---` separators between bodies so the model can tell where
 /// one ends and the next begins; per-message redelivery banners
 /// included.
+#[must_use]
 pub fn format_recv(resp: Result<SocketReply, anyhow::Error>) -> String {
     use std::fmt::Write as _;
     let messages = match resp {
@@ -171,6 +173,7 @@ pub const REDELIVERY_HINT: &str =
 /// of pending approvals + questions + reminders. Empty list collapses
 /// to a clear marker so claude doesn't go hunting for a payload that
 /// isn't there.
+#[must_use]
 pub fn format_loose_ends(resp: Result<SocketReply, anyhow::Error>) -> String {
     use std::fmt::Write as _;
     let loose_ends = match resp {
@@ -259,6 +262,7 @@ fn loose_end_kind_label(kind: hive_sh4re::CancelLooseEndKind) -> &'static str {
 /// Format helper for `whoami`: renders the identity block as a short
 /// human-readable string. Skips fields that are `None` so the output
 /// doesn't carry dead placeholders.
+#[must_use]
 pub fn format_whoami(resp: Result<SocketReply, anyhow::Error>) -> String {
     match resp {
         Ok(SocketReply::Whoami {
@@ -294,6 +298,7 @@ where
 /// from "c0re flickered and the harness rode it out" — without the
 /// hint, a tool result that took 30s to come back looks identical to a
 /// content failure and the model would burn a turn retrying it.
+#[must_use]
 pub fn annotate_retries(mut s: String, retries: u32) -> String {
     if retries > 0 {
         use std::fmt::Write as _;
@@ -660,6 +665,11 @@ impl AgentServer {
 impl ServerHandler for AgentServer {}
 
 /// Run the agent MCP server over stdio. Returns when the client disconnects.
+///
+/// # Errors
+///
+/// Returns an error if the MCP server fails to initialize or the transport
+/// encounters a fatal error.
 pub async fn serve_agent_stdio(socket: PathBuf) -> Result<()> {
     let server = AgentServer::new(socket);
     let service = server.serve(stdio()).await?;
@@ -668,6 +678,11 @@ pub async fn serve_agent_stdio(socket: PathBuf) -> Result<()> {
 }
 
 /// Run the manager MCP server over stdio. Same idea, different tool surface.
+///
+/// # Errors
+///
+/// Returns an error if the MCP server fails to initialize or the transport
+/// encounters a fatal error.
 pub async fn serve_manager_stdio(socket: PathBuf) -> Result<()> {
     let server = ManagerServer::new(socket);
     let service = server.serve(stdio()).await?;