From c9f537c2e3f6d4c07376099ef1259d4765efc213 Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Fri, 29 May 2026 00:23:46 +0200
Subject: [PATCH] docs: forge_notify.rs file map + wait_for_login mtime
 resumption (follow-up to #544 #545)

---
 CLAUDE.md         | 8 ++++++++
 docs/turn-loop.md | 9 +++++++++
 2 files changed, 17 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8a8c1f26..02ebe01a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -150,6 +150,14 @@ hive-ag3nt/        in-container harness crate; produces TWO binaries
   src/turn.rs           claude --print + stream-json pump; --compact retry;
                          proactive compaction + auto session-reset
   src/mcp.rs            embedded MCP server (rmcp): AgentServer + ManagerServer
+  src/forge_notify.rs   Forgejo webhook subscriber: formats new-issue /
+                         new-PR / comment / review notifications as
+                         broker messages; embeds a body excerpt
+                         (up to BODY_TRUNCATE bytes, ATX headings
+                         escaped) and surfaces any @mention lines that
+                         fell outside the truncation window in a
+                         trailing `mentions (truncated from body):`
+                         block (#539 / #544).
   src/login.rs          probe /root/.claude/ for a valid session
   src/login_session.rs  drives `claude auth login` over stdio pipes
   src/prompt.rs         system prompt renderer: filters the unified
diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index 7509388b..5b5c64b8 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -38,6 +38,15 @@ Each agent harness (`hive-ag3nt serve` or `hive-m1nd serve`) runs:
    the same path used at boot. The operator re-authenticates via
    the per-agent web UI login flow; on success the sentinel is
    cleared and the queued message drives the next turn normally.
+   **Mtime-snapshot resumption** (closes #542): `wait_for_login`
+   snapshots the `~/.claude/` dir (newest file mtime + file count)
+   at entry and only resumes when that snapshot advances — not
+   just when credentials exist on disk. This prevents a silent
+   infinite-401 loop: stale credentials already on disk at the
+   time of the 401 no longer cause an immediate false-resume. The
+   `DirSnapshot` struct tracks both axes; either a mtime advance
+   OR a file-count change triggers resume (the count axis handles
+   filesystems where `modified()` errors on every file).
 7. Emit `LiveEvent::TurnEnd { ok, note }`. Sleep `poll_ms` to avoid
    tight loops on transient failures.