Skip to content
1 change: 1 addition & 0 deletions changelog.d/changed-issue-side-comment-churn.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Issue-side comment churn is cut by editing in place instead of re-posting ([#16433](https://github.com/hivecommons/hive/issues/16433)): `hive:claim` / `hive:release` transitions now maintain one per-issue claim-ledger comment (`<!-- hive:issue-claim-ledger -->`, current state plus the last 8 transitions; `github.notifications.claim_ledger`, default on, `false` restores one comment per transition) that every existing claim reader still parses; a PR re-entering a needs-decision stage has its entry comment rewritten with an `Updated <ts>` line; a new push rewrites the hive's existing `hive-sentinel` comment for the new head; and in quiet mode a reviewer-lane review that narrates "no findings" with an approving, finding-free verdict is recorded and folded into the `hive:status` comment instead of being submitted as a review.
69 changes: 58 additions & 11 deletions src/cmd/hive/claimswire.go
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,9 @@ func githubClaimHooks(ctx context.Context, cfg *config.Config, client func() *gi
}
comment := cfg.Governor.Claims.CommentEnabled()
label := cfg.Governor.Claims.LabelEnabled()
// The ledger folds every transition into one edited comment per issue
// (hivecommons/hive#16433); off, each transition is its own comment.
ledgerMode := cfg.GitHub.Notifications.ClaimLedgerEnabled()
queue := &claimEffectQueue{}
attempt := func(fn func(ctx context.Context, gh *github.Client) error, gh *github.Client) error {
cctx, cancel := context.WithTimeout(ctx, claimsGitHubTimeout)
Expand All @@ -265,13 +268,44 @@ func githubClaimHooks(ctx context.Context, cfg *config.Config, client func() *gi
logger.Warn("issue-claims: GitHub side effect failed", "what", what, "issue", c.Key(), "attempts", 1, "error", err)
}
}
// ledger edits the issue's claim ledger comment for event, posting the
// one notifying comment a human owed one gets. The edit is retried: a
// PATCH that lands twice is the same body, unlike a POST.
ledger := func(what string, event claims.LedgerEvent, notice func(previous string) string) {
run(what, event.Claim, func(ctx context.Context, gh *github.Client) error {
res, err := gh.EditIssueMarkerComment(ctx, event.Claim.Repo, event.Claim.Issue, claims.LedgerMarker, func(previous string) string {
return claims.LedgerComment(previous, event)
})
if err != nil {
return err
}
if notice == nil || !res.Found {
// A freshly created ledger already notified: it carries the
// same @-mention the standalone comment did.
return nil
}
if body := notice(res.Previous); body != "" {
return gh.CreateIssueCommentBudgeted(ctx, event.Claim.Repo, event.Claim.Issue, body)
}
return nil
})
}
return claims.Hooks{
OnClaimed: func(c claims.Claim, outcome claims.Outcome) {
queue.run(c.Key(), func() {
if comment && outcome == claims.OutcomeClaimed {
runOnce("claim comment", c, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueCommentBudgeted(ctx, c.Repo, c.Issue, claims.ClaimComment(c))
})
if ledgerMode {
ledger("claim ledger", claims.LedgerEvent{Claim: c, At: c.ClaimedAt}, func(previous string) string {
if claims.LedgerNotifiesHuman(previous, c) {
return claims.LedgerNoticeComment(c)
}
return ""
})
} else {
runOnce("claim comment", c, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueCommentBudgeted(ctx, c.Repo, c.Issue, claims.ClaimComment(c))
})
}
}
if label {
// The stage is a fact for the engine (ADR-0025): a live
Expand All @@ -296,9 +330,17 @@ func githubClaimHooks(ctx context.Context, cfg *config.Config, client func() *gi
OnTakenOver: func(now, previous claims.Claim) {
queue.run(now.Key(), func() {
if comment {
runOnce("takeover comment", now, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueComment(ctx, now.Repo, now.Issue, claims.TakeoverComment(now, previous))
})
if ledgerMode {
ledger("takeover ledger", claims.LedgerEvent{Claim: now, Previous: previous, At: now.ClaimedAt}, func(string) string {
// The displaced person must hear it; an edit
// tells them nothing.
return claims.LedgerDisplacedNotice(now, previous)
})
} else {
runOnce("takeover comment", now, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueComment(ctx, now.Repo, now.Issue, claims.TakeoverComment(now, previous))
})
}
}
if label {
run("claimed stage", now, func(ctx context.Context, gh *github.Client) error {
Expand Down Expand Up @@ -345,8 +387,9 @@ func githubClaimHooks(ctx context.Context, cfg *config.Config, client func() *gi
})
}
// Every early release needs a marker: the πŸ”’ comment is
// never edited, and issueclaim.Latest otherwise reads the
// hold as live until until=. This includes relay disconnect,
// never edited (the ledger rewrites it to carry the release
// marker instead), and issueclaim.Latest otherwise reads
// the hold as live until until=. This includes relay disconnect,
// revoke and lease-expiry releases: omitting them starved
// hive agents while relays flapped (hivecommons/hive#13579).
// TTL expiry needs no marker: until= has already lapsed.
Expand All @@ -356,9 +399,13 @@ func githubClaimHooks(ctx context.Context, cfg *config.Config, client func() *gi
// SetIssueClaimLedgerHive still prevents this hive from
// believing its own stale hold.
if comment && reason != claims.ReasonExpired {
runOnce("release comment", c, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueCommentBudgeted(ctx, c.Repo, c.Issue, claims.ReleaseComment(c, reason))
})
if ledgerMode {
ledger("release ledger", claims.LedgerEvent{Claim: c, Released: true, Reason: reason, At: time.Now()}, nil)
} else {
runOnce("release comment", c, func(ctx context.Context, gh *github.Client) error {
return gh.CreateIssueCommentBudgeted(ctx, c.Repo, c.Issue, claims.ReleaseComment(c, reason))
})
}
}
})
},
Expand Down
7 changes: 6 additions & 1 deletion src/cmd/hive/claimswire_budget_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ func TestClaimHooks_LeaseRevokedSharesClaimCommentBudget(t *testing.T) {
t.Run(name, func(t *testing.T) {
posted := make(chan string, 1)
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widgets/issues/7/comments" {
// The claim ledger looks for its comment before writing.
_, _ = w.Write([]byte(`[]`))
return
}
if r.Method != http.MethodPost || r.URL.Path != "/repos/acme/widgets/issues/7/comments" {
t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
http.NotFound(w, r)
Expand Down Expand Up @@ -77,7 +82,7 @@ func TestClaimHooks_LeaseRevokedSharesClaimCommentBudget(t *testing.T) {
t.Fatalf("missing lease release marker: %s", body)
}
case message := <-failed:
if !exhausted || !strings.Contains(message, github.ErrIssueCommentBudget.Error()) || !strings.Contains(message, "release comment") {
if !exhausted || !strings.Contains(message, github.ErrIssueCommentBudget.Error()) || !strings.Contains(message, "release ledger") {
t.Fatalf("unexpected hook failure: %s", message)
}
case <-time.After(5 * time.Second):
Expand Down
104 changes: 104 additions & 0 deletions src/cmd/hive/claimswire_relaunch_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package main

import (
"context"
"encoding/json"
"io"
"log/slog"
"net/http"
Expand Down Expand Up @@ -89,6 +90,11 @@ func TestClaimHooks_RelaunchReleasePostsReleaseMarker(t *testing.T) {
_, _ = w.Write([]byte(`{"number":7,"labels":[{"name":"stage/020-claimed"},{"name":"hive/claimed-by-scanner"}]}`))
})
mux.HandleFunc("/repos/acme/widgets/issues/7/comments", func(w http.ResponseWriter, r *http.Request) {
if r.Method == http.MethodGet {
// The claim ledger looks for its comment before writing.
_, _ = w.Write([]byte(`[]`))
return
}
body, _ := io.ReadAll(r.Body)
mu.Lock()
comments = append(comments, string(body))
Expand Down Expand Up @@ -125,3 +131,101 @@ func TestClaimHooks_RelaunchReleasePostsReleaseMarker(t *testing.T) {
t.Fatalf("release comment:\n%s", got[0])
}
}

// With the claim ledger on (the default), an issue's claim, release and
// re-claim are one comment: the first claim creates it, every later
// transition PATCHes it, and the body always carries exactly one machine
// marker β€” the current state β€” above the history (hivecommons/hive#16433).
// With the ledger off, each transition is its own comment as before.
func TestClaimHooks_ClaimLedgerEditsOneCommentPerIssue(t *testing.T) {
for _, ledgerOn := range []bool{true, false} {
name := "ledger"
if !ledgerOn {
name = "legacy"
}
t.Run(name, func(t *testing.T) {
var mu sync.Mutex
var posted, edited []string
var existing []byte
mux := http.NewServeMux()
mux.HandleFunc("/repos/acme/widgets/issues/7/comments", func(w http.ResponseWriter, r *http.Request) {
mu.Lock()
defer mu.Unlock()
if r.Method == http.MethodGet {
if existing == nil {
_, _ = w.Write([]byte(`[]`))
return
}
_, _ = w.Write([]byte(`[{"id":41,"body":` + string(existing) + `,"user":{"login":"hive[bot]"}}]`))
return
}
var body struct {
Body string `json:"body"`
}
_ = json.NewDecoder(r.Body).Decode(&body)
posted = append(posted, body.Body)
existing, _ = json.Marshal(body.Body)
w.WriteHeader(http.StatusCreated)
_, _ = w.Write([]byte(`{"id":41}`))
})
mux.HandleFunc("/repos/acme/widgets/issues/comments/41", func(w http.ResponseWriter, r *http.Request) {
var body struct {
Body string `json:"body"`
}
_ = json.NewDecoder(r.Body).Decode(&body)
mu.Lock()
edited = append(edited, body.Body)
existing, _ = json.Marshal(body.Body)
mu.Unlock()
_, _ = w.Write([]byte(`{"id":41}`))
})
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte(`[]`)) })
srv := httptest.NewServer(mux)
defer srv.Close()
gh := github.NewClientForTest(srv.URL, "acme", []string{"widgets"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
gh.SetAppBotLogin("hive[bot]")
cfg := &config.Config{}
cfg.Governor.Claims.Label = boolPtr(false)
cfg.Governor.Claims.Comment = boolPtr(true)
cfg.GitHub.Notifications.ClaimLedger = boolPtr(ledgerOn)
hooks := githubClaimHooks(context.Background(), cfg, func() *github.Client { return gh }, nil)
at := time.Date(2026, 11, 3, 9, 0, 0, 0, time.UTC)
claim := claims.Claim{Repo: "acme/widgets", Issue: 7, Holder: "scanner", HolderID: "scanner", Kind: claims.KindAgent, ClaimedAt: at, ExpiresAt: at.Add(time.Hour)}

hooks.OnClaimed(claim, claims.OutcomeClaimed)
hooks.OnReleased(claim, claims.ReasonHolderRelaunched)
claim.ClaimedAt = at.Add(2 * time.Minute)
hooks.OnClaimed(claim, claims.OutcomeClaimed)
wantPosted, wantEdited := 1, 2
if !ledgerOn {
wantPosted, wantEdited = 3, 0
}
testutil.Eventually(t, 5*time.Second, func() bool {
mu.Lock()
defer mu.Unlock()
return len(posted) == wantPosted && len(edited) == wantEdited
}, "claim transitions never settled")
mu.Lock()
defer mu.Unlock()
if len(posted) != wantPosted || len(edited) != wantEdited {
t.Fatalf("posted=%d edited=%d, want %d/%d", len(posted), len(edited), wantPosted, wantEdited)
}
if !ledgerOn {
return
}
if !strings.HasPrefix(posted[0], claims.LedgerMarker) || !strings.Contains(posted[0], "<!-- hive:claim who=scanner kind=agent") {
t.Fatalf("first claim must create the ledger with the claim marker:\n%s", posted[0])
}
if !strings.Contains(edited[0], "hive:release who=scanner kind=agent reason=holding_agent_relaunched at=") || strings.Contains(edited[0], "<!-- hive:claim ") {
t.Fatalf("release must rewrite the ledger to carry only the release marker:\n%s", edited[0])
}
final := edited[1]
if strings.Count(final, "<!-- hive:claim ")+strings.Count(final, "<!-- hive:release ") != 1 || !strings.Contains(final, "<!-- hive:claim who=scanner kind=agent") {
t.Fatalf("re-claim must leave exactly one machine marker, the claim:\n%s", final)
}
if history := claims.ParseLedgerHistory(final); len(history) != 3 || !strings.Contains(history[1], "released by `scanner`") {
t.Fatalf("history = %q", history)
}
})
}
}
1 change: 1 addition & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,7 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).PostNoteOrFold` | `status` | passthrough wrapper; attributed to its caller |
| `github.(*Client).SweepLegacyFleetReportIssues` | `status` | |
| `github.(*Client).UpsertIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller |
| `github.(*Client).EditIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller |
| `automerge.(*engineStatusForge).CreateComment` | `status` | passthrough wrapper shared by normal-mode stage notes and the quiet-mode status-comment forge under `prstatus.Write`; attributed to its caller |
| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (status-comment forge under `prstatus.Write`); attributed to its caller |
| `github.(*Client).PostIssueNote` | `status` | passthrough wrapper (issue status card, `attention_pilot`); attributed to its caller |
Expand Down
72 changes: 66 additions & 6 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -539,12 +539,19 @@ not what it records:
The comment is created the first time a note is due and PATCHed for every
later note; only the creation sends email.
- **No "no findings" reviews.** A reviewer whose whole body is the clean
acknowledgement has its verdict recorded through the relay and the
evidence bundle, and no GitHub review is submitted (the reviewer prompts
also stop asking for the line, whatever `review.acknowledge_no_findings`
says). Only perspectives with findings post, and a head carries at most
one hive review: a later perspective's findings for the same head are
folded into the status comment instead of becoming a second review.
acknowledgement β€” or whose body says it has no findings while its verdict
report approves with an empty findings list, as the plain `reviewer`
lanes narrate ("Read the tree at … Looks correct to me. No findings.") β€”
has its verdict recorded through the relay and the evidence bundle, and
no GitHub review is submitted (the reviewer prompts also stop asking for
the line, whatever `review.acknowledge_no_findings` says). The verdict
and the reviewer's notes land in the status comment as a
`review-findings:<agent>` section instead. A body that asks for a
decision, carries a hive marker, or rides a non-approving verdict is a
real review and still posts. Only perspectives with findings post, and a
head carries at most one hive review: a later perspective's findings for
the same head are folded into the status comment instead of becoming a
second review.
- **@-mentions once per cause.** The 071 note mentions the author the first
time a cause class appears (conflict, red CI, changes requested) and is
silent for further heads with the same cause; a new cause mentions again.
Expand Down Expand Up @@ -586,6 +593,59 @@ already present), so the effect of the mode can be charted from the logs.
`normal` restores the previous behaviour: every note is its own comment,
every perspective's verdict its own review, every new head its own mention.

Three issue-side comments are edited in place in either mode, because a
re-post never carried information the previous comment lacked:

- **Needs-decision entry** (`<!-- hive:stage-needs-decision -->` and the
other stage entry markers): a PR that re-enters the stage after a decision
cycle has its existing entry comment rewritten, with an `Updated <ts>`
line, instead of receiving a new one. Only the hive's own comment is
reused; a stranger's comment carrying the marker is ignored.
- **Sentinel alert** (`<!-- hive-sentinel --> <head>`): a new push rewrites
the hive's existing sentinel comment for the new head rather than
stamping the PR again. The label is what blocks; one explanation per PR
is enough. A hive that cannot verify its own account (no App login and
no resolvable identity) still posts a fresh comment rather than edit a
comment the PR author may have forged.
- **Claim ledger** (`github.notifications.claim_ledger`, default `true`):
see below.

### Claim ledger (`github.notifications.claim_ledger`)

**Why:** every `hive:claim` and `hive:release` the fleet posted was a new
comment, and a relaunch or lease revocation appends a release+claim pair
each time. Over 48 hours that was 334 comments β€” a quarter of everything
the hive wrote β€” on issues whose holder, as far as a reader cared, had not
changed.

```yaml
github:
notifications:
claim_ledger: true # default; false restores one comment per claim/release
```

With the ledger on, an issue carries **one** claim comment marked
`<!-- hive:issue-claim-ledger -->` that is PATCHed on every transition. It
shows the current state β€” the same `hive:claim` / `hive:release` /
`hive:preempt` machine marker and text the separate comments carried β€” and
a collapsed `Claim history` list of the last 8 transitions (timestamp,
agent, kind, release reason). The first claim on an issue creates the
comment; later claims, takeovers and releases edit it, and only the
creation sends email.

The ledger is written so that every reader of the old comments keeps
working without change: it carries exactly one machine marker, for the
current state, so `issueclaim.Latest` (claim recovery after a restart, the
`claimed-by` label sweep, the contributor lane's "is it free" check and the
dashboard's claims view) reads the ledger the way it read the newest
separate comment. A legacy claim comment on the same issue is superseded
by the ledger's later `at=` the same way a later comment superseded it.

A human is still told, in a fresh comment, the two things only a new
comment can tell them: that an agent took over an issue they held, and
that they displaced an agent (so they know to drop the `claimed-by` label
when done). Everything else goes into the ledger.

`github.notifications.shadow: true` (default off) adds would-notify
instrumentation without changing any write: every new comment, review,
review request and @-mention is classified by producer and class, repeats of
Expand Down
Loading
Loading