diff --git a/changelog.d/fixed-14705-review-verdict-wake.md b/changelog.d/fixed-14705-review-verdict-wake.md new file mode 100644 index 0000000000..7acd8a2166 --- /dev/null +++ b/changelog.d/fixed-14705-review-verdict-wake.md @@ -0,0 +1 @@ +- Recording a review head's dispatched verdict now wakes the governor for an early cached-snapshot eval cycle, so the next head or the decision kick is dispatched right away instead of waiting for an unrelated webhook or `governor.eval_interval_webhook_s`; a burst of verdicts is coalesced to at most one wake per `governor.webhook_wake_min_gap_s` ([#14705](https://github.com/hivecommons/hive/issues/14705)). diff --git a/src/cmd/hive/boot.go b/src/cmd/hive/boot.go index e1728bbdf6..2110d29067 100644 --- a/src/cmd/hive/boot.go +++ b/src/cmd/hive/boot.go @@ -259,6 +259,10 @@ type boot struct { // carries its wakes to the governor loop (hivecommons/hive#11091). reviewEvents *eventdispatch.Dispatcher reviewWake chan struct{} + // verdictWaker turns dispatched review verdicts the relay records into + // early eval cycles, at most one per governor.webhook_wake_min_gap_s + // (hivecommons/hive#14705). + verdictWaker *webhookWaker // webhookWaker coalesces cache-invalidating GitHub webhooks into early // eval cycles and evalLoop is the pacing block /api/status reports. diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index a1a58ac668..4c690fc89f 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -387,6 +387,9 @@ func (b *boot) applyGitHubClientDashboardHooks(client *github.Client) { // claims ledger is on. recordStarted(b.dashSrv, b.cfg.Project.Org, agentName, repo, issue, signal) }) + // hivecommons/hive#14705: a recorded dispatched verdict frees its head, + // so the governor re-plans now instead of at the next eval cycle. + client.SetReviewVerdictHook(b.wakeForReviewVerdict) // PR follow-up session resume (#9583, default off): remember which live // CLI session authored this PR, and the PR's handoff note, so its // follow-ups can resume that conversation or brief a fresh one. The diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 7524750460..23b30286fb 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -6369,6 +6369,13 @@ func (b *boot) runLoopWith(deps runLoopDeps) { tick(evalSourceCached) armContinuousWake() armWebhookHealthRecheck() + case batch := <-b.verdictWakeChan(): + b.logger.Info("review verdict wake: running an early eval cycle from the cached snapshot", + "pr", batch.Reason, "last_pr", batch.LastRe, "verdicts", batch.Count, + "coalesced", batch.Coalesced.Round(time.Millisecond).String()) + tick(evalSourceCached) + armContinuousWake() + armWebhookHealthRecheck() case batch := <-b.webhookWakeChan(): now := healthNow() // Apply the delivery's targeted re-reads first so this cycle diff --git a/src/cmd/hive/review_event_dispatch.go b/src/cmd/hive/review_event_dispatch.go index 841d608197..711d2feb32 100644 --- a/src/cmd/hive/review_event_dispatch.go +++ b/src/cmd/hive/review_event_dispatch.go @@ -1,8 +1,10 @@ package main import ( + "fmt" "sort" "sync/atomic" + "time" "github.com/hivecommons/hive/pkg/review" "github.com/hivecommons/hive/pkg/review/eventdispatch" @@ -22,6 +24,12 @@ func (b *boot) installReviewEvents() { if b.reviewWake == nil { b.reviewWake = make(chan struct{}, 1) } + if b.verdictWaker == nil { + b.verdictWaker = newWebhookWaker( + func() time.Duration { return 0 }, + func() time.Duration { return b.cfg.WebhookWakeMinGap() }, + ) + } activeReviewEvents.Store(b.reviewEvents) } @@ -48,6 +56,29 @@ func (b *boot) wakeForReviewEvents(batch []eventdispatch.Entry) { } } +// wakeForReviewVerdict is the github.ReviewVerdictHook: the relay recorded a +// verdict bound to a review dispatch, so the head that wrote it is free and +// the PR may be ready for its next head or its decision kick. Without this +// the next kick waited for an unrelated webhook or the eval cadence +// (hivecommons/hive#14705). The first verdict wakes the loop at once; later +// ones inside governor.webhook_wake_min_gap_s fold into one wake at the end +// of the gap, so a burst of verdicts costs one cycle. +func (b *boot) wakeForReviewVerdict(repo string, number int) { + if b == nil || b.verdictWaker == nil { + return + } + b.verdictWaker.Request(fmt.Sprintf("%s#%d", repo, number)) +} + +// verdictWakeChan is the loop's receive side; nil when the waker is not +// installed so the select case never fires. +func (b *boot) verdictWakeChan() <-chan webhookWakeBatch { + if b.verdictWaker == nil { + return nil + } + return b.verdictWaker.out +} + // prioritizeEventPRs moves PRs whose current head a review webhook fired for // to the front, keeping order otherwise. PlanDispatch walks the list in order // and still applies every gate, so this changes who is first, not who is diff --git a/src/cmd/hive/review_event_dispatch_test.go b/src/cmd/hive/review_event_dispatch_test.go index 10469b8d0c..a52bb6c9d1 100644 --- a/src/cmd/hive/review_event_dispatch_test.go +++ b/src/cmd/hive/review_event_dispatch_test.go @@ -63,8 +63,12 @@ func TestInstallReviewEventsIsIdempotent(t *testing.T) { if d == nil || wake == nil || activeReviewEvents.Load() != d { t.Fatal("dispatcher not installed") } + verdicts := b.verdictWaker + if verdicts == nil { + t.Fatal("verdict waker not installed") + } b.installReviewEvents() - if b.reviewEvents != d || b.reviewWake != wake { + if b.reviewEvents != d || b.reviewWake != wake || b.verdictWaker != verdicts { t.Fatal("reinstall replaced the dispatcher") } t.Cleanup(func() { activeReviewEvents.Store(nil) }) @@ -140,3 +144,69 @@ func TestRunLoopWithRunsAnEarlyCycleOnReviewWake(t *testing.T) { t.Fatalf("log = %s", log.String()) } } + +// hivecommons/hive#14705: the first recorded verdict wakes the loop at once; +// the verdicts that follow inside governor.webhook_wake_min_gap_s fold into +// one wake at the end of the gap. +func TestWakeForReviewVerdictCoalescesInsideMinGap(t *testing.T) { + w, f := newTestWebhookWaker(0, 30*time.Second) + b := &boot{verdictWaker: w} + + b.wakeForReviewVerdict("o/r", 1) + if len(f.delays) != 1 || f.delays[0] != 0 { + t.Fatalf("first verdict should wake at once, armed %v", f.delays) + } + f.fire(t) + if got := <-b.verdictWakeChan(); got.Count != 1 || got.Reason != "o/r#1" { + t.Fatalf("first wake = %+v", got) + } + + f.now = f.now.Add(5 * time.Second) + b.wakeForReviewVerdict("o/r", 2) + b.wakeForReviewVerdict("o/r", 3) + if len(f.delays) != 2 || f.delays[1] != 25*time.Second { + t.Fatalf("verdicts inside the gap should arm one timer for the rest of it, armed %v", f.delays) + } + select { + case got := <-b.verdictWakeChan(): + t.Fatalf("woke inside the min gap: %+v", got) + default: + } + f.fire(t) + if got := <-b.verdictWakeChan(); got.Count != 2 || got.Reason != "o/r#2" || got.LastRe != "o/r#3" { + t.Fatalf("coalesced wake = %+v", got) + } +} + +func TestWakeForReviewVerdictWithoutWakerIsNoop(t *testing.T) { + var nilBoot *boot + nilBoot.wakeForReviewVerdict("o/r", 1) + b := &boot{} + b.wakeForReviewVerdict("o/r", 1) + if b.verdictWakeChan() != nil { + t.Fatal("uninstalled waker should leave the loop case nil") + } +} + +func TestRunLoopWithRunsAnEarlyCycleOnVerdictWake(t *testing.T) { + b, log, cancel := newLoopBoot(t, 60, 0) + b.verdictWaker, _ = newTestWebhookWaker(0, 30*time.Second) + gov := newFakeTicker() + h := &loopHarness{startupOK: true, pending: []*fakeTicker{gov}, persisted: make(chan struct{}, 8)} + done := runLoopAsync(b, h.deps()) + <-h.persisted // first cycle done + + b.verdictWaker.out <- webhookWakeBatch{Reason: "o/r#1", LastRe: "o/r#2", Count: 2} + <-h.persisted // early cycle done + gov.fire() + <-h.persisted // cadence cycle still runs + cancel() + waitDone(t, done) + + if len(h.evals) != 3 { + t.Fatalf("evals = %d, want first + verdict + cadence", len(h.evals)) + } + if !strings.Contains(log.String(), "review verdict wake") || !strings.Contains(log.String(), "verdicts=2") { + t.Fatalf("log = %s", log.String()) + } +} diff --git a/src/docs/operator-reference.md b/src/docs/operator-reference.md index 7970cbcb2a..f5da073492 100644 --- a/src/docs/operator-reference.md +++ b/src/docs/operator-reference.md @@ -1220,6 +1220,17 @@ v5 and v6 spokes) tracking one repo all stay on webhook mode. `review_requested` deliveries also queue an early review dispatch when `review.event_driven` is on; see [Event-driven dispatch](review-swarm.md#event-driven-dispatch). +- **A recorded review verdict also wakes the governor loop.** When the + relay records a verdict bound to a review dispatch, the head that wrote it + is free and the PR may be ready for its next head or its decision kick, so + the loop runs a cached-snapshot cycle now instead of waiting for an + unrelated delivery or `governor.eval_interval_webhook_s`. Advisory verdicts + do not wake it. The first verdict wakes at once; later ones inside + `governor.webhook_wake_min_gap_s` fold into one wake at the end of the gap. + `governor.webhook_wake_debounce_s` does not apply to this wake (its + debounce is fixed at 0, so a verdict is never held back), and the spoke logs `review verdict wake: running an early eval cycle from + the cached snapshot` + ([#14705](https://github.com/hivecommons/hive/issues/14705)). - Every status publish (cadence or wake) invalidates the `/api/stage-tracker` cache and sends a `stage-tracker` event on `/api/events`, so the dashboard's activity monitor refetches at once instead of waiting out diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index 4074105726..92e0db2f76 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:4676-4693`, descending `AgeMinutes`). + (`RankActionableIssues`, `src/pkg/github/client.go:4679-4696`, descending `AgeMinutes`). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/docs/webhooks.md b/src/docs/webhooks.md index 3529558f1e..1a42425872 100644 --- a/src/docs/webhooks.md +++ b/src/docs/webhooks.md @@ -59,7 +59,7 @@ These are the acceptance criteria of #13373 and the tests that hold them. | `governor.eval_interval_webhook_s` | `900` | the base tick in webhook mode; `0` disables webhook mode (always poll) | | `governor.eval_interval_max_s` | `1800` | cap on either tick after the API-budget stretch | | `governor.webhook_wake_debounce_s` | `10` | a delivery and its check fan-out coalesce into one wake cycle | -| `governor.webhook_wake_min_gap_s` | `30` | minimum spacing between webhook-triggered cycles | +| `governor.webhook_wake_min_gap_s` | `30` | minimum spacing between webhook-triggered cycles, and between the cycles recorded review verdicts trigger | | `forgestate.reconcile_interval_s` | `900` | ForgeState's own full-list interval per repo, shortened while drift is high | | `forgestate.freshness_bound_s` | `60` | maximum item age before merge/close/claim/kick re-reads it | | `forgestate.drift_threshold` | `0.05` | fraction of items a reconcile may find wrong before the interval shortens | diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index ea7f9c15a1..a125ad2993 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -304,6 +304,9 @@ type Client struct { // agentStartHook is told when an agent's own relay request shows it // working an issue (#10527). See agent_start_hook.go. agentStartHook atomic.Pointer[AgentStartHook] + // reviewVerdictHook is told when the relay records a verdict bound to a + // review dispatch (review_verdict_hook.go). + reviewVerdictHook atomic.Pointer[ReviewVerdictHook] // mergeAuthz gates merge requests from the merge-request watcher against the // per-agent ACMM merge-policy (CanMerge) + forge-resistance AND the merge // TARGET (pinned SHA + governor merge-eligible membership; see diff --git a/src/pkg/github/review_verdict_hook.go b/src/pkg/github/review_verdict_hook.go new file mode 100644 index 0000000000..724f2076a4 --- /dev/null +++ b/src/pkg/github/review_verdict_hook.go @@ -0,0 +1,33 @@ +package github + +// ReviewVerdictHook is told that the relay recorded at least one verdict +// bound to a review dispatch for PR number in repo. The head that wrote it +// is free again, and the PR may now be ready for its next head or its +// decision kick, so the hive uses it to wake the governor loop rather than +// leave the reviewers idle until the next eval cycle +// (hivecommons/hive#14705). +type ReviewVerdictHook func(repo string, number int) + +// SetReviewVerdictHook installs (or with nil, removes) the verdict hook. +// Safe to call before or after the watchers start. +func (c *Client) SetReviewVerdictHook(fn ReviewVerdictHook) { + if c == nil { + return + } + if fn == nil { + c.reviewVerdictHook.Store(nil) + return + } + c.reviewVerdictHook.Store(&fn) +} + +// notifyReviewVerdict reports a recorded dispatched verdict to the installed +// hook, if any. +func (c *Client) notifyReviewVerdict(repo string, number int) { + if c == nil { + return + } + if hook := c.reviewVerdictHook.Load(); hook != nil && *hook != nil { + (*hook)(repo, number) + } +} diff --git a/src/pkg/github/review_verdict_hook_test.go b/src/pkg/github/review_verdict_hook_test.go new file mode 100644 index 0000000000..b3cae147bb --- /dev/null +++ b/src/pkg/github/review_verdict_hook_test.go @@ -0,0 +1,94 @@ +package github + +import ( + "context" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/review" +) + +type verdictHookCall struct { + repo string + number int +} + +func recordingVerdictHook(c *Client) *[]verdictHookCall { + var calls []verdictHookCall + c.SetReviewVerdictHook(func(repo string, number int) { + calls = append(calls, verdictHookCall{repo, number}) + }) + return &calls +} + +// A recorded dispatched verdict frees its head, so the hook fires: once per +// request, even when a combined review answered several perspectives +// (hivecommons/hive#14705). +func TestRecordReviewVerdictCallsHookOnceForDispatchedVerdicts(t *testing.T) { + c := &Client{logger: testLogger()} + calls := recordingVerdictHook(c) + withVerdictDispatchState(t, review.DispatchState{Pending: []review.PendingReview{ + pendingVerdict("o/r", 7, "correctness", "reviewer"), + pendingVerdict("o/r", 7, "security", "reviewer"), + }}) + raw := "[" + strings.Join([]string{ + validVerdictJSON(t, "o/r", 7, "correctness", "approve"), + validVerdictJSON(t, "o/r", 7, "security", "approve"), + }, ",") + "]" + + c.recordReviewVerdict(context.Background(), ReviewRequest{Repo: "o/r", Number: 7, Agent: "reviewer", Report: raw}, t.TempDir()) + + if len(*calls) != 1 || (*calls)[0] != (verdictHookCall{"o/r", 7}) { + t.Fatalf("hook calls = %+v, want one for o/r#7", *calls) + } +} + +// An advisory verdict binds no dispatch, so no head was freed and nothing +// wakes. +func TestRecordReviewVerdictDoesNotCallHookForAdvisoryVerdict(t *testing.T) { + c := &Client{logger: testLogger()} + calls := recordingVerdictHook(c) + withVerdictDispatchState(t, review.DispatchState{Pending: []review.PendingReview{ + pendingVerdict("o/r", 2, review.PerspectiveSecurity, "reviewer"), + }}) + raw := validVerdictJSONWithHead(t, "o/r", 1, "security", "approve", "abc123") + + got := c.recordReviewVerdict(context.Background(), ReviewRequest{Repo: "o/r", Number: 1, Agent: "reviewer", Report: raw}, t.TempDir()) + + if len(got) != 1 { + t.Fatalf("advisory verdict was not recorded: %+v", got) + } + if len(*calls) != 0 { + t.Fatalf("advisory verdict called the hook: %+v", *calls) + } +} + +// A refused verdict records nothing and wakes nothing. +func TestRecordReviewVerdictDoesNotCallHookForRefusedVerdict(t *testing.T) { + c := &Client{logger: testLogger()} + calls := recordingVerdictHook(c) + withVerdictDispatchState(t, review.DispatchState{}) + raw := validVerdictJSON(t, "o/r", 1, "correctness", "approve") + + got := c.recordReviewVerdict(context.Background(), ReviewRequest{Repo: "o/r", Number: 1, Agent: "reviewer", Report: raw}, t.TempDir()) + + if len(got) != 0 { + t.Fatalf("refused verdict was recorded: %+v", got) + } + if len(*calls) != 0 { + t.Fatalf("refused verdict called the hook: %+v", *calls) + } +} + +func TestSetReviewVerdictHookNilClears(t *testing.T) { + c := &Client{logger: testLogger()} + calls := recordingVerdictHook(c) + c.SetReviewVerdictHook(nil) + c.notifyReviewVerdict("o/r", 1) + if len(*calls) != 0 { + t.Fatalf("cleared hook still called: %+v", *calls) + } + var nilClient *Client + nilClient.SetReviewVerdictHook(func(string, int) {}) + nilClient.notifyReviewVerdict("o/r", 1) +} diff --git a/src/pkg/github/review_verdict_relay.go b/src/pkg/github/review_verdict_relay.go index b186ce7dbf..f04c724e96 100644 --- a/src/pkg/github/review_verdict_relay.go +++ b/src/pkg/github/review_verdict_relay.go @@ -92,6 +92,7 @@ func (c *Client) recordReviewVerdict(ctx context.Context, req ReviewRequest, dir prSnapshot := c.reviewedPRSnapshotFunc(ctx, req) prHead := func() string { return prSnapshot().Head } var recorded []review.PerspectiveReport + wake := false for _, report := range reports { if decisionRequested { report.DecisionRequested = true @@ -100,10 +101,18 @@ func (c *Client) recordReviewVerdict(ctx context.Context, req ReviewRequest, dir report.Verdict = review.VerdictRequiresHuman } report.PermissionsTighteningOnly = tightening - if written, ok := c.writeOneVerdict(ctx, req, report, dir, prHead, prSnapshot); ok { + if written, ok, dispatched := c.writeOneVerdict(ctx, req, report, dir, prHead, prSnapshot); ok { recorded = append(recorded, written) + wake = wake || dispatched } } + // One wake per request, however many perspectives a combined review + // answered: the head that wrote them is free, and the PR may be ready + // for its next head or its decision kick. An advisory verdict freed no + // dispatch slot, so it wakes nothing (hivecommons/hive#14705). + if wake { + c.notifyReviewVerdict(req.Repo, req.Number) + } return recorded } @@ -339,8 +348,9 @@ func maintainerCallQuestion(body string) string { // will find it. One file per perspective, which is what the collector has // always read — a combined review changes how verdicts arrive, not how they // are stored, so nothing downstream needs to know the difference. It returns -// the report as stored and whether it was. -func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report review.PerspectiveReport, dir string, prHead func() string, prSnapshot func() reviewedPRSnapshot) (review.PerspectiveReport, bool) { +// the report as stored, whether it was, and whether it was bound to a review +// dispatch rather than admitted as advisory. +func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report review.PerspectiveReport, dir string, prHead func() string, prSnapshot func() reviewedPRSnapshot) (review.PerspectiveReport, bool, bool) { // The verdict must be about the PR that was actually reviewed. Without this // an agent authorized to comment on one PR could record a binding // requires_human/reject verdict against any other PR in the fleet. @@ -349,7 +359,7 @@ func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report slog.String("reviewed", fmt.Sprintf("%s#%d", req.Repo, req.Number)), slog.String("claimed", fmt.Sprintf("%s#%d", report.Repo, report.Number)), slog.String("agent", req.Agent)) - return report, false + return report, false, false } // Bind to a real dispatch record. A combined review answers one kick with // several verdicts, so each element is checked on its own: the dispatch is @@ -362,7 +372,7 @@ func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report slog.String("perspective", string(report.Perspective)), slog.String("agent", req.Agent), slog.String("reason", auth.Reason)) - return report, false + return report, false, false } // A dispatched verdict is stored under the head its dispatch record names, // whatever the reviewer wrote: the match above already proved the two @@ -429,7 +439,7 @@ func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report if err != nil { c.logger.Warn("review-request watcher: could not serialize verdict", slog.String("perspective", string(report.Perspective)), slog.String("error", err.Error())) - return report, false + return report, false, false } // One file per perspective, and per review head when the perspective was @@ -454,20 +464,20 @@ func (c *Client) writeOneVerdict(ctx context.Context, req ReviewRequest, report if err := os.WriteFile(tmp, raw, 0o644); err != nil { c.logger.Warn("review-request watcher: could not write verdict", slog.String("path", path), slog.String("error", err.Error())) - return report, false + return report, false, false } if err := os.Rename(tmp, path); err != nil { _ = os.Remove(tmp) c.logger.Warn("review-request watcher: could not commit verdict", slog.String("path", path), slog.String("error", err.Error())) - return report, false + return report, false, false } c.logger.Info("review-request watcher: verdict recorded", slog.String("repo", report.Repo), slog.Int("number", report.Number), slog.String("perspective", string(report.Perspective)), slog.String("verdict", string(report.Verdict)), slog.String("path", path)) - return report, true + return report, true, auth.Dispatched } // verdictAuthorization is what admitting a verdict establishes about it: