hyperhive/hive-forge-notify

hive-forge-notify

Per-agent Forgejo notification poller: a long-running daemon (hive-forge-notify) that watches the agent's unread notification list and turns each thread into a todo the harness surfaces in get_loose_ends. This is why an agent wakes up when someone comments on its issue or requests its review.

When to use it

Look here when changing what a forge notification says when it reaches an agent, or when it reaches one at all: the poll cadence, the self-echo filter, the comment / review / new-item / state-change wrapper formats, body-excerpt truncation, and the assigned-issue rollup all live in notify.rs. The behaviour contract — activation gates, filtering rules, the review-request override — is documented in docs/2-handbook/swarm/forge.md, "Notification poller".

Shape

One bin, three modules:

• main.rs — argument-free entry point. Reads HIVE_AGENT_SOCKET, initialises tracing, hands off to notify::run.
• notify.rs — the poller: forge client setup, the 30s loop, the formatters, mark-read, and the in-process delivery-dedupe map.
• todo_client.rs — one-shot JSON-line client for the harness's in-agent socket. No retry schedule of its own; see the module doc.

Why it is a separate process

It used to be a tokio::spawn inside the hive-agent serve loop. It never needed anything from the serve loop except a socket path, and running it in-process meant a harness restart also took forge notifications down, and linked the whole forge/HTTP dependency tree (forgejo-api, reqwest, time, url) into the serve-loop binary. It is now a sibling daemon alongside hive-bash-daemon and hive-matrix-daemon, with the same contract: it talks to the harness over the in-agent todo socket and nowhere else.

Forge's own read-state is the durable, cross-rebuild record of what has been delivered — there is no persisted cursor to migrate or corrupt. A restarted poller re-scans only the genuinely-still-unread set, which is tiny by construction because delivery marks the thread read.