Watch
0
0
Fork
You've already forked hyperhive
0

hive-forge: state the read-state contract in the guard docs

This commit is contained in:
atlas 2026-11-15 20:17:45 +01:00 • committed by mara
commit 4a109fa038
3 changed files with 16 additions and 15 deletions

View file

@ -260,9 +260,10 @@ to discover valid label names before triaging or to audit the label set.
<!-- vale write-good.Passive = NO -->
- **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 <n>` 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 <n>` or
`hive-forge comments <n>` (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

View file

@ -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;

View file

@ -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 <n>` / `view <n>`) 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