hive-agent: trim narrative comment bloat in doc comments (#3901)

hive-agent/src/events.rs

@@ -99,11 +99,10 @@ pub enum LiveEvent {
     /// Must be a struct variant (not `Note(String)`): internally-tagged
     /// enums can't flatten a tag onto a primitive newtype, and serde
     /// fails serialization at runtime — silently, because the SSE
-    /// handler's `filter_map(... .ok()? ...)` swallows the error. From
+    /// handler's `filter_map(... .ok()? ...)` swallows the error, so a
-    /// 2025-08 through 2026-05 every `Note` emission was a no-op + the
+    /// regression here goes unnoticed until the sqlite history shows
-    /// sqlite history persisted them as the literal string `"null"`.
+    /// `"null"` rows. The web UI's `note` renderer already reads
-    /// The web UI's `note` renderer already reads `ev.text`, so the
+    /// `ev.text`, so the wire shape matches without a JS change.
-    /// wire shape matches without a JS change.
     Note { text: String },
     /// Turn finished. `ok=false` means claude exited non-zero or the
     /// harness hit a transport error.

hive-agent/src/harness_state.rs

@@ -87,10 +87,9 @@ fn harness_json_path() -> PathBuf {
 // writer merges into the existing object rather than reconstructing it,
 // so a future second writer preserves fields it doesn't own; the lock
 // closes the lost-update window between a writer's read and its rename.
-// (The forge poller used to be that second writer, for a delivery-dedupe
+// (No second writer today — the forge poller that once shared this file
-// cursor. It no longer persists one — forge's own read-state is the
+// now keeps its own delivery-dedupe state and runs as a separate process
-// durable record — and it is a separate process now, which an
+// anyway, which an in-process mutex couldn't have serialised.)
-// in-process mutex could not have serialised anyway.)
 static HARNESS_JSON_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
 
 /// Read the consolidated state file as a JSON object, or an empty object

hive-agent/src/paths.rs

@@ -42,26 +42,19 @@ pub fn harness_dir() -> PathBuf {
 
 /// Consolidated harness-local state db — todos + reminders, one table
 /// each — mutable per-agent state the harness owns, kept out of the
-/// append-only `hyperhive-events.sqlite` sink. Per mara's call ("not yet
+/// append-only `hyperhive-events.sqlite` sink. Each store's `open()` only
-/// another sqlite! todos, reminders, questions should be like three tiny
+/// applies its own `CREATE TABLE IF NOT EXISTS` against this same path
-/// tables in one 500kb sqlite"), this file is the shared home for the
+/// (see their call sites), so distinct table names keep them from
-/// loose-ends-v2 stores; each store's `open()` only applies its own
+/// colliding without needing a per-store path wrapper here.
-/// `CREATE TABLE IF NOT EXISTS`, so opening multiple stores against the
-/// same path is safe (distinct table names, no schema collision). Both
-/// stores (todos, reminders) open this same path directly (see their
-/// `open()` call sites) — distinct table names mean no schema collision,
-/// so there's no need for per-store path wrapper fns here.
 ///
-/// ⚠️ A pre-existing harness may still carry a third table here, `questions`
+/// ⚠️ A pre-existing harness may still carry an inert `questions` table
-/// — the mirror this file's own doc comment used to describe as one of
+/// here from the now-removed ask/answer mechanism — nothing opens or
-/// three. It's gone now that the ask/answer mechanism itself has been
+/// writes it, and any rows in it are harmless leftovers, not a store to
-/// removed: nothing opens or writes it any more, so any rows already in
+/// migrate or clean up.
-/// it are inert, harmless leftovers, not a store to migrate or clean up.
 ///
-/// Before the todos/reminders consolidation, they lived in their own
+/// A one-time boot migration (`db_migrate::run`) folds the older
-/// `hyperhive-todos.sqlite` / `hyperhive-reminders.sqlite` files; a
+/// `hyperhive-todos.sqlite` / `hyperhive-reminders.sqlite` files into this
-/// one-time boot migration (`db_migrate::run`) folds those into this path
+/// path on first boot after an upgrade.
-/// the first time a harness boots after the upgrade.
 #[must_use]
 pub fn state_db() -> PathBuf {
     harness_dir().join("hyperhive-state.sqlite")

hive-agent/src/web_ui/auth.rs

@@ -115,10 +115,9 @@ pub(super) async fn post_logout(State(state): State<AppState>) -> Response {
 /// Human-readable summary of a [`crate::login::ClearedSession`] outcome for
 /// the `/api/logout` response + note. Deliberately distinguishes "nothing to
 /// delete" from "something's there but we couldn't delete it" — both leave
-/// `wiped` empty, but only the former is actually "already logged out".
+/// `wiped` empty, but only the former is actually "already logged out";
-/// These two used to be conflated, so a stuck undeletable `.credentials.json`
+/// conflating them would report a stuck undeletable `.credentials.json` as
-/// got reported as "already logged out" in the same breath as a warning
+/// "already logged out" in the same breath as a delete-failed warning.
-/// saying the delete failed.
 fn wipe_summary(cleared: &crate::login::ClearedSession) -> String {
     if !cleared.wiped.is_empty() {
         format!("wiped {}", cleared.wiped.join(", "))