From b8d3b9564160260ec9467ae797aa6949a58413a9 Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 2 Sep 2026 01:21:47 +0200 Subject: [PATCH] hive-agent: trim narrative comment bloat in doc comments (#3901) --- hive-agent/src/events.rs | 9 ++++----- hive-agent/src/harness_state.rs | 7 +++---- hive-agent/src/paths.rs | 29 +++++++++++------------------ hive-agent/src/web_ui/auth.rs | 7 +++---- 4 files changed, 21 insertions(+), 31 deletions(-) diff --git a/hive-agent/src/events.rs b/hive-agent/src/events.rs index c4f35fe6..a273f8d0 100644 --- a/hive-agent/src/events.rs +++ b/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 - /// 2025-08 through 2026-05 every `Note` emission was a no-op + the - /// sqlite history persisted them as the literal string `"null"`. - /// The web UI's `note` renderer already reads `ev.text`, so the - /// wire shape matches without a JS change. + /// handler's `filter_map(... .ok()? ...)` swallows the error, so a + /// regression here goes unnoticed until the sqlite history shows + /// `"null"` rows. The web UI's `note` renderer already reads + /// `ev.text`, so the 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. diff --git a/hive-agent/src/harness_state.rs b/hive-agent/src/harness_state.rs index 1684964f..6ef30968 100644 --- a/hive-agent/src/harness_state.rs +++ b/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 -// cursor. It no longer persists one — forge's own read-state is the -// durable record — and it is a separate process now, which an -// in-process mutex could not have serialised anyway.) +// (No second writer today — the forge poller that once shared this file +// now keeps its own delivery-dedupe state and runs as a separate process +// anyway, which an in-process mutex couldn't have serialised.) static HARNESS_JSON_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); /// Read the consolidated state file as a JSON object, or an empty object diff --git a/hive-agent/src/paths.rs b/hive-agent/src/paths.rs index dad8007f..e97cd92c 100644 --- a/hive-agent/src/paths.rs +++ b/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 -/// another sqlite! todos, reminders, questions should be like three tiny -/// tables in one 500kb sqlite"), this file is the shared home for the -/// loose-ends-v2 stores; each store's `open()` only applies its own -/// `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. +/// append-only `hyperhive-events.sqlite` sink. Each store's `open()` only +/// applies its own `CREATE TABLE IF NOT EXISTS` against this same path +/// (see their call sites), so distinct table names keep them from +/// colliding without needing a per-store path wrapper here. /// -/// ⚠️ A pre-existing harness may still carry a third table here, `questions` -/// — the mirror this file's own doc comment used to describe as one of -/// three. It's gone now that the ask/answer mechanism itself has been -/// removed: nothing opens or writes it any more, so any rows already in -/// it are inert, harmless leftovers, not a store to migrate or clean up. +/// ⚠️ A pre-existing harness may still carry an inert `questions` table +/// here from the now-removed ask/answer mechanism — nothing opens or +/// writes it, and any rows in it are harmless leftovers, not a store to +/// migrate or clean up. /// -/// Before the todos/reminders consolidation, they lived in their own -/// `hyperhive-todos.sqlite` / `hyperhive-reminders.sqlite` files; a -/// one-time boot migration (`db_migrate::run`) folds those into this path -/// the first time a harness boots after the upgrade. +/// A one-time boot migration (`db_migrate::run`) folds the older +/// `hyperhive-todos.sqlite` / `hyperhive-reminders.sqlite` files into this +/// path on first boot after an upgrade. #[must_use] pub fn state_db() -> PathBuf { harness_dir().join("hyperhive-state.sqlite") diff --git a/hive-agent/src/web_ui/auth.rs b/hive-agent/src/web_ui/auth.rs index 514f2730..e9485ab4 100644 --- a/hive-agent/src/web_ui/auth.rs +++ b/hive-agent/src/web_ui/auth.rs @@ -115,10 +115,9 @@ pub(super) async fn post_logout(State(state): State) -> 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". -/// These two used to be conflated, so a stuck undeletable `.credentials.json` -/// got reported as "already logged out" in the same breath as a warning -/// saying the delete failed. +/// `wiped` empty, but only the former is actually "already logged out"; +/// conflating them would report a stuck undeletable `.credentials.json` as +/// "already logged out" in the same breath as a delete-failed warning. fn wipe_summary(cleared: &crate::login::ClearedSession) -> String { if !cleared.wiped.is_empty() { format!("wiped {}", cleared.wiped.join(", "))