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).