vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fold forge_cursor into hyperhive-harness.json + prose comments (mara/argus review)

Browse source
This commit is contained in:
damocles 2026-07-01 18:48:23 +02:00 • committed by mara
commit f6d9ca7f99
4 changed files with 153 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/forge.md
View file

@ -100,20 +100,24 @@ Each poll prunes it to the threads still in the unread set. A failed
wake delivery is left unread **and** out of the cursor, so it
resurfaces next tick.
The cursor is **persisted** to
`$HYPERHIVE_STATE_DIR/forge-notify-cursor.json` (atomic tmp+rename,
flushed only when it changed) and reloaded on boot, so a container
rebuild/restart doesn't re-deliver the whole currently-unread backlog
(#2106 — previously the in-memory-only cursor was lost on restart and
every old still-unread thread re-fired a wake). This is safe because a
The cursor is **persisted** as the `forge_cursor` field of the
harness's consolidated `hyperhive-harness.json` state file (atomic
tmp+rename, flushed only when it changed) and reloaded on boot, so a
container rebuild/restart doesn't re-deliver the whole currently-unread
backlog (#2106 — previously the in-memory-only cursor was lost on
restart and every old still-unread thread re-fired a wake). The poller
runs in the same harness process that owns that file, so it's one
daemon → one state file rather than a second json; both writers
(turn-loop fields + this cursor) go read-modify-write under a shared
lock so neither clobbers the other's fields. This is safe because a
thread is recorded **after** a successful broker delivery, and the
broker inbox is durable sqlite — so a persisted "delivered" entry can
never swallow a wake the agent never received. Crucially the cursor
file is a private dedup mirror, **not** forge's read-state: it does
not reintroduce the read-before-comment coupling that ruled out the
old mark-read-on-delivery approach. A missing (first boot) or corrupt
cursor file degrades to empty — re-deliver the unread set once — never
an abort.
never swallow a wake the agent never received. Crucially the cursor is
a private dedup mirror, **not** forge's read-state: it does not
reintroduce the read-before-comment coupling that ruled out the old
mark-read-on-delivery approach. A missing (first boot) or malformed
cursor degrades to empty — re-deliver the unread set once — never an
abort.
Self-echo notifications (the agent's own writes, see below) are the
one path still marked-read directly (no read-before-comment value).

13
docs/persistence.md
View file

@ -129,7 +129,7 @@ Consolidated harness state file written atomically (`.tmp` + rename) by
Shape:
```json
{ "rate_limited": false, "needs_login": false }
{ "rate_limited": false, "needs_login": false, "active_model": "…", "forge_cursor": { "42": "2026-07-01T18:00:00Z" } }
```
- `rate_limited` — set when the harness detects a 429 from the Claude
@ -138,6 +138,17 @@ Shape:
- `needs_login` — set when a turn hits 401 (expired OAuth credentials);
cleared by `"online"` status (re-auth completed). Drives the
`needs_login` flag alongside the `claude_has_session` check.
- `active_model` — the resolved Claude model for the dashboard badge.
- `forge_cursor` — the `forge_notify` delivery-dedupe cursor
(notification thread id → last-delivered `updated_at`), so a
rebuild/restart doesn't re-deliver the whole currently-unread forge
backlog. See [`forge.md`](forge.md).
Multiple harness tasks write this file (the turn loop for the first
three fields, the `forge_notify` poller for `forge_cursor`), so every
writer goes read-modify-write under a shared in-process lock — each
preserves the fields it doesn't own rather than reconstructing the file
from scratch.
hive-c0re reads this file on each `build_all` sweep (~10s) via
`container_view::read_harness_flags`. Falls back to the legacy individual