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

hive-ag3nt/src/turn.rs

@@ -97,6 +97,10 @@ pub struct TurnFiles {
 impl TurnFiles {
     /// Write all three files into the per-agent runtime dir alongside
     /// `socket`. Idempotent — overwrites whatever was there.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if any of the config files cannot be written to disk.
     pub async fn prepare(socket: &Path, label: &str, flavor: mcp::Flavor) -> Result<Self> {
         Ok(Self {
             mcp_config: write_mcp_config(socket).await?,
@@ -112,6 +116,10 @@ impl TurnFiles {
 /// as `--socket <path>`); `binary_subcommand` is e.g. `"mcp"` for sub-agents
 /// or `"mcp"` for the manager (both binaries name their MCP subcommand the
 /// same — the differentiator is which binary `/proc/self/exe` resolves to).
+///
+/// # Errors
+///
+/// Returns an error if the config file cannot be written.
 pub async fn write_mcp_config(socket: &Path) -> Result<PathBuf> {
     let parent = socket.parent().unwrap_or_else(|| Path::new("/run/hive"));
     tokio::fs::create_dir_all(parent).await.ok();
@@ -128,6 +136,10 @@ pub async fn write_mcp_config(socket: &Path) -> Result<PathBuf> {
 /// Drop the static `--settings` JSON next to the MCP config so we can
 /// pass a path (`--settings <file>`) instead of an ever-growing inline
 /// blob — the CLI argv has a finite length budget.
+///
+/// # Errors
+///
+/// Returns an error if the settings file cannot be written.
 pub async fn write_settings(socket: &Path) -> Result<PathBuf> {
     let parent = socket.parent().unwrap_or_else(|| Path::new("/run/hive"));
     tokio::fs::create_dir_all(parent).await.ok();
@@ -142,6 +154,10 @@ pub async fn write_settings(socket: &Path) -> Result<PathBuf> {
 /// `--system-prompt-file`, replacing claude's default system prompt with
 /// the role + tools instructions. Per-turn prompts become much smaller
 /// (just the wake message body).
+///
+/// # Errors
+///
+/// Returns an error if the system prompt file cannot be written.
 pub async fn write_system_prompt(
     socket: &Path,
     label: &str,
@@ -399,6 +415,10 @@ pub fn emit_turn_end(bus: &Bus, outcome: &TurnOutcome) {
 /// Block until the bound `~/.claude/` dir contains a session, polling
 /// `claude_dir` on a `poll_ms` interval (min 2s). Flips `state` to
 /// `Online` when login lands; caller resumes its serve loop.
+///
+/// # Panics
+///
+/// Panics if the internal login-state lock is poisoned.
 pub async fn wait_for_login(
     claude_dir: &Path,
     state: Arc<Mutex<LoginState>>,
@@ -442,6 +462,11 @@ pub async fn run_turn(prompt: &str, files: &TurnFiles, bus: &Bus) -> TurnOutcome
 /// surface, same system prompt, same allowed-tools — so the post-
 /// compact state matches a normal turn's. Only the prompt over stdin
 /// differs (`/compact` vs the wake-up payload).
+///
+/// # Errors
+///
+/// Returns an error if the `claude --print /compact` invocation fails
+/// (non-zero exit or I/O error).
 pub async fn compact_session(files: &TurnFiles, bus: &Bus) -> Result<()> {
     bus.emit(LiveEvent::Note {
         text: "context overflow — running /compact on the persistent session".into(),