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

hive-ag3nt/src/login_session.rs

@@ -48,6 +48,11 @@ impl LoginSession {
     /// `HYPERHIVE_LOGIN_CMD` (single string, shell-split into argv); by
     /// default we run `claude auth login`. Failing to spawn returns an error
     /// before any state is registered.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if spawning the login command fails, or if the child's
+    /// stdio handles cannot be acquired.
     pub fn start() -> Result<Self> {
         let (cmd, args) = resolve_command();
         tracing::info!(%cmd, ?args, "spawning login session");
@@ -82,6 +87,11 @@ impl LoginSession {
     /// Write `code` (plus a newline) to the child's stdin. Returns an error
     /// if the stdin has already been closed (e.g. after the child exited or
     /// after a prior submission consumed it).
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the login stdin is already closed, or if writing
+    /// to or flushing the stdin pipe fails.
     pub async fn submit_code(&self, code: &str) -> Result<()> {
         let mut guard = self.stdin.lock().await;
         let stdin = guard.as_mut().context("login stdin already closed")?;
@@ -100,18 +110,34 @@ impl LoginSession {
         let _ = self.stdin.lock().await.take();
     }
 
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
+    #[must_use]
     pub fn output(&self) -> String {
         self.state.lock().unwrap().output.clone()
     }
 
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
+    #[must_use]
     pub fn url(&self) -> Option<String> {
         self.state.lock().unwrap().url.clone()
     }
 
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
+    #[must_use]
     pub fn finished(&self) -> bool {
         self.state.lock().unwrap().finished
     }
 
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
+    #[must_use]
     pub fn exit_note(&self) -> Option<String> {
         self.state.lock().unwrap().exit_note.clone()
     }
@@ -119,6 +145,10 @@ impl LoginSession {
     /// Best-effort: poll the child once and update `finished`/`exit_note`.
     /// Called by the web UI on each render so the state stays fresh without
     /// running a dedicated reaper task.
+    ///
+    /// # Panics
+    ///
+    /// Panics if an internal lock is poisoned.
     pub fn poll(&self) {
         let mut child = self.child.lock().unwrap();
         match child.try_wait() {
@@ -137,6 +167,10 @@ impl LoginSession {
     }
 
     /// Kill the child if it's still running. Idempotent.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     pub fn kill(&self) {
         if let Err(e) = self.child.lock().unwrap().start_kill() {
             tracing::warn!(error = ?e, "kill login child");
@@ -217,6 +251,10 @@ fn extract_url(line: &str) -> Option<String> {
 
 /// Helper used by the web UI to gate "is there a session running right now"
 /// without holding both this module's mutex and the `AppState`'s at once.
+///
+/// # Panics
+///
+/// Panics if the internal lock is poisoned.
 pub fn drop_if_finished(slot: &Mutex<Option<Arc<LoginSession>>>) {
     let mut guard = slot.lock().unwrap();
     if let Some(s) = guard.as_ref() {