From 4a109fa038d14fb5e710687a9d8d6f1b768ee975 Mon Sep 17 00:00:00 2001 From: atlas Date: Sun, 15 Nov 2026 20:17:45 +0100 Subject: [PATCH] hive-forge: state the read-state contract in the guard docs --- docs/4-implementation/agent-tools/forge.md | 7 ++++--- hive-forge/src/notify.rs | 18 ++++++++---------- hive-forge/src/verbs/comment.rs | 6 ++++-- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/4-implementation/agent-tools/forge.md b/docs/4-implementation/agent-tools/forge.md index 49c42e676..39083d05a 100644 --- a/docs/4-implementation/agent-tools/forge.md +++ b/docs/4-implementation/agent-tools/forge.md @@ -260,9 +260,10 @@ to discover valid label names before triaging or to audit the label set. - **Read-before-comment guard:** `comment` refuses to post when forge still - has an unread notification for the thread (that is, someone commented since - you last read it). This prevents accidentally replying to old activity without - seeing the new context. Read the thread with `hive-forge view ` or + has an unread notification for the thread. `hive-forge-notify` marks a + thread read when it delivers it as a todo, so the guard catches only + activity newer than the last delivery (one 30 s poll) and threads whose + delivery failed. Read the thread with `hive-forge view ` or `hive-forge comments ` (which mark the notification read and clear the block), or pass `--force` to skip the guard. - `comment --body "..."` with backticks in the body: always use diff --git a/hive-forge/src/notify.rs b/hive-forge/src/notify.rs index 3542b8b5e..600939091 100644 --- a/hive-forge/src/notify.rs +++ b/hive-forge/src/notify.rs @@ -1,16 +1,14 @@ //! Read-before-comment guard backed by forge's own notification //! read-state — no local mirror (which drifts across restarts). //! -//! When someone comments on an issue/PR the caller participates in, -//! forge raises an unread notification for that thread; once the agent -//! actually reads the thread (`comments` / `view`) we mark it read via -//! the notifications API. So "is there unread activity here?" is just -//! "does forge still have an unread notification for this thread?" — -//! forge is the single source of truth, nothing to lose on restart. -//! -//! (This pairs with the `forge_notify` harness change that stops -//! marking notifications read on wake *delivery* — issue tracker -//! `forge cli: agents keep commenting without reading prev comments`.) +//! `hive-forge-notify` marks a thread read on forge as soon as it delivers +//! the thread to the agent as a todo, so the todo carries the news and +//! forge's unread flag does not wait for the agent to open the thread. +//! "Unread activity here" is therefore "forge still has an unread +//! notification for this thread": activity newer than the last delivery +//! (the poll interval, about 30 s) and threads whose delivery failed. +//! Reading a thread (`comments` / `view`) also marks its notification +//! read, so the guard clears for a thread the agent opens itself. use anyhow::Result; use forge_client::NotificationThread; diff --git a/hive-forge/src/verbs/comment.rs b/hive-forge/src/verbs/comment.rs index 01a278c91..2b738dba6 100644 --- a/hive-forge/src/verbs/comment.rs +++ b/hive-forge/src/verbs/comment.rs @@ -2,8 +2,10 @@ //! issue or PR. //! //! Read-before-comment guard: before posting, refuse when forge still -//! has an unread notification for the thread — i.e. someone commented -//! since the caller last read it. Reading the thread +//! has an unread notification for the thread. `hive-forge-notify` marks +//! a thread read when it delivers it as a todo, so this only catches +//! activity newer than the last delivery (about one 30 s poll) and +//! threads whose delivery failed. Reading the thread //! (`hive-forge comments ` / `view `) marks the notification read //! and clears the block; `--force` overrides. The unread signal is //! forge's own notification read-state, not a local mirror — see