From 762e3ef514817a95484f5c2daa48a6cdd419bf16 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 17 Nov 2026 22:47:30 -0500 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=90=9B=20Withhold=20the=20contributor?= =?UTF-8?q?=20nudge=20for=20a=20head=20the=20hive=20adopts=20anyway?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #18872 Signed-off-by: Andrew Anderson --- changelog.d/fixed-18872-nudge-then-adopt.md | 1 + src/cmd/hive/merge_eligibility.go | 1 + .../stage-labels.md | 17 ++ src/docs/operator-reference/README.md | 1 + src/pkg/config/config.go | 13 ++ src/pkg/delegatedecision/ladder.go | 25 ++- .../ladder_nudge_agreement_test.go | 42 +++++ .../automerge/automerge_contributor_nudge.go | 47 +++++- .../automerge_nudge_withhold_test.go | 153 ++++++++++++++++++ .../automerge/automerge_stage_labels.go | 6 +- src/pkg/stagelabels/store.go | 20 +++ 11 files changed, 319 insertions(+), 7 deletions(-) create mode 100644 changelog.d/fixed-18872-nudge-then-adopt.md create mode 100644 src/pkg/delegatedecision/ladder_nudge_agreement_test.go create mode 100644 src/pkg/github/automerge/automerge_nudge_withhold_test.go diff --git a/changelog.d/fixed-18872-nudge-then-adopt.md b/changelog.d/fixed-18872-nudge-then-adopt.md new file mode 100644 index 0000000000..c2d15f86f1 --- /dev/null +++ b/changelog.d/fixed-18872-nudge-then-adopt.md @@ -0,0 +1 @@ +- A contributor PR the hive is going to adopt anyway (author relay offline or unregistered, adoption enabled and unblocked) no longer gets a "back in your court" nudge followed by an adoption note 16-39 minutes later: the nudge is recorded (the adoption clock still runs, the relay still gets its task) but its GitHub comment is withheld, so the author gets one notification, and it is posted if the adoption stops being certain; an online author keeps the nudge and the full grace, and the ladder's immediate-supersede rung fires only for an unreachable author, the same condition. `governor.labels.stage.contributor_nudge.withhold_when_adopting: false` restores the old behavior (#18872). diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index a6dabaf73a..ff961c7258 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -116,6 +116,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy Dwell: stage.DwellOverrides(), StalledRequireQuiet: stage.Stalled.IsRequireQuiet(), ContributorNudge: stage.ContributorNudge.IsEnabled(), + NudgeWithholdWhenAdopting: stage.ContributorNudge.IsWithholdWhenAdopting(), RenudgeInterval: nudgeRepeatAfter(cfg), CIFailureCooldown: stage.ContributorNudge.EffectiveCIFailureCooldown(), Adoption: stage.Adoption.IsEnabled(), diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 2cfbfc4d61..1b8ff8376a 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -800,6 +800,23 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human- (default 6h) is folded into the comment too; after the cooldown it counts as a fresh nudge. The ledger lives in the stage-label store, so a restart does not re-nudge. + One outcome per head (hivecommons/hive#18872): a head the hive adopts + anyway gets **no** "back in your court" comment. When the author's relay + is offline or not registered here (live presence is known), adoption is + enabled and nothing blocks it (no hold label, no fork guard, no workflow + path, `maintainer_policy: adopt`), the `AutoAdoption` clock will adopt the + head regardless of what the author does next, so the nudge is only + *recorded* (the clock starts on it, the relay still receives its + `fix-pr` task) and the adoption note is the author's one notification. + An author whose relay is online keeps the nudge and the full online grace + (`contributor_grace_online`); a withheld nudge is posted as soon as the + adoption stops being certain (the relay reconnects, the adoption is held + or blocked). The operator's "Let hive decide" ladder agrees: rung 5 + (`contributor-offline`, supersede now) only fires for an author who is not + reachable, the same condition. This follows the documented rule that a + contributor who has gone quiet is superseded now (#13975). + `governor.labels.stage.contributor_nudge.withhold_when_adopting: false` + restores a nudge for every head. 2. Relay contributors (the author has a contributor profile and a live relay connection) also receive the diagnosis in their relay session as a `fix-pr` task with `priority: interrupt`. Presence = a relay heartbeat diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 1ea3922f00..2fc4646497 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -494,6 +494,7 @@ advanced into the merge path. | `auto_merge.max_merges` | `3` (`DefaultAutoMergeSweepMaxMerges`) when 0/unset | Caps merges per sweep pass. | | `auto_merge.min_head_age` | `3m` | Minimum PR head age before automerge trusts an unknown required-check set. A fresh head pushed more recently than this waits with `pending: head pushed ... ago (< min_head_age)` unless `auto_merge.required_checks` is declared and every required check is complete and successful. Head age is measured from the head commit's committer date (never earlier than the PR's creation), not the PR's `updated_at`, so label and comment activity — including the hive's own — does not restart it. When GitHub's head time is ahead of the host clock (clock skew), age is measured from when the hive first observed the head instead, so the hold lasts one window and then clears (`pending: head time ahead of host clock; head first seen ... ago (< min_head_age)`). | | `auto_merge.nudge_repeat_after` | `72h` | How long a contributor nudge's condition must persist before the hive nudges once more. Nudges are one comment per PR and reason class, edited in place for a new head or changed reason; after this interval with the same condition the comment is re-posted once (cap 2 per reason), then never again. `governor.labels.stage.contributor_nudge.renudge_interval`, when set, overrides it. | +| `governor.labels.stage.contributor_nudge.withhold_when_adopting` | `true` | Withhold the "back in your court" comment for a head the hive adopts anyway (author relay offline or unregistered, adoption enabled and unblocked): the nudge is recorded and the adoption note is the one notification; posted later if the adoption stops being certain (hivecommons/hive#18872). `false` nudges every head. | | `governor.labels.stage.contributor_nudge.ci_failure_cooldown` | `6h` | CI-failure nudges are keyed on the failing-check set: the same set red on a new head, or a check joining the set on the same head, edits the PR's one nudge comment. A *different* set on a new head inside this window is folded into that comment too (count unchanged); after it the hive counts a fresh nudge. | | `auto_merge.required_checks` | unset | Default operator-declared status-check contexts / check-run names (e.g. `["build-gate"]`) that the sweep's green gate requires on repos without a per-repo override. See below. | | `auto_merge.repos..required_checks` | inherits default | Per-repo override for heterogeneous hives. `` may be the bare name from `project.repos` or `owner/repo`; an explicit empty list declares that GitHub has no required contexts, while Hive still requires positive CI evidence from at least one real successful check-run before merge. | diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 2ff04fba8d..c6452e5066 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -3523,6 +3523,19 @@ type ContributorNudgeConfig struct { // comment instead of counting as a fresh nudge // (hivecommons/hive#17328). Default DefaultContributorNudgeCIFailureCooldown (6h). CIFailureCooldown string `yaml:"ci_failure_cooldown,omitempty"` + // WithholdWhenAdopting withholds the "back in your court" comment for a + // head the hive is going to adopt anyway (author relay offline or + // unregistered, adoption enabled and unblocked): the nudge is still + // recorded and the adoption note is the one notification + // (hivecommons/hive#18872). nil = true; false restores a nudge for every + // head. + WithholdWhenAdopting *bool `yaml:"withhold_when_adopting,omitempty"` +} + +// IsWithholdWhenAdopting reports whether the nudge comment is withheld for +// a head the hive adopts anyway (default on). +func (c ContributorNudgeConfig) IsWithholdWhenAdopting() bool { + return c.WithholdWhenAdopting == nil || *c.WithholdWhenAdopting } // DefaultContributorNudgeCIFailureCooldown is diff --git a/src/pkg/delegatedecision/ladder.go b/src/pkg/delegatedecision/ladder.go index 497f058ad7..72d04c786b 100644 --- a/src/pkg/delegatedecision/ladder.go +++ b/src/pkg/delegatedecision/ladder.go @@ -202,7 +202,7 @@ func decideLadder(in Input, ref string) (Decision, bool) { // Rung 4 — return to contributor: their clanker or hive is reachable // (presence, or the rework-pickup signal of hivecommons/hive#15280). - if in.ContributorOnline || in.ReworkPickedUp { + if in.ContributorReachable() { fix := fixList(in) if len(fix) == 0 { return Decision{}, false @@ -222,7 +222,12 @@ func decideLadder(in Input, ref string) (Decision, bool) { } skip(RuleReturnToContributor, in.OfflineWording()) - // Rung 5 — adopt-supersede, the last resort. + // Rung 5 — adopt-supersede, the last resort. Reaching it means the + // author is NOT reachable (rung 4 returned the PR otherwise), and for + // an unreachable author a "back in your court" nudge asks for work + // they will not get to do: the contributor nudge is withheld under the + // same condition (AdoptsImmediately), so the author's one notification + // is the adoption note (hivecommons/hive#18872). if in.AdoptionGraceElapsed { text := "adopt now: the offline grace on " + ref + " has already elapsed; adopt in supersede mode at once, preserving the author's commits and sign-off" d := Decision{ @@ -244,6 +249,22 @@ func decideLadder(in Input, ref string) (Decision, bool) { return Decision{}, false } +// ContributorReachable reports whether the author's clanker or hive is +// connected or has picked the rework up: the condition under which rung 4 +// returns the PR to them and rung 5 never fires. +func (in Input) ContributorReachable() bool { return in.ContributorOnline || in.ReworkPickedUp } + +// AdoptsImmediately reports whether the ladder would adopt this head in +// supersede mode right now, without waiting for the grace. The contributor +// nudge and the ladder must agree on one outcome per head +// (hivecommons/hive#18872): a head for which this is true is not nudged +// ("back in your court") only to be adopted minutes later; and a head that is +// given a real chance (ContributorReachable) is never adopted by rung 5. +func AdoptsImmediately(in Input) bool { + d, ok := decideLadder(in, "this PR") + return ok && d.Verdict == VerdictAdoptSupersede +} + // decideAlreadyFixed is rung 1: close as superseded by the merged closer, // with a courteous note naming it. A paused repo or a person's PR gets a // recommendation instead of a write. diff --git a/src/pkg/delegatedecision/ladder_nudge_agreement_test.go b/src/pkg/delegatedecision/ladder_nudge_agreement_test.go new file mode 100644 index 0000000000..e3d46d174f --- /dev/null +++ b/src/pkg/delegatedecision/ladder_nudge_agreement_test.go @@ -0,0 +1,42 @@ +package delegatedecision + +import "testing" + +// hivecommons/hive#18872: the ladder and the contributor nudge agree on one +// outcome per head. Rung 5 fires exactly when the author is unreachable +// (the nudge is withheld under that condition) and never for a reachable +// author (who keeps the nudge and the real grace). +func TestLadderAndNudgeAgree(t *testing.T) { + base := Input{Repo: "hivecommons/hive", Kind: KindPR, Number: 18561, AuthorTooling: AuthorToolingClanker} + patterns := []struct { + name string + mut func(*Input) + }{ + {"conflicting", func(i *Input) { i.Conflicting = true; i.CIGreen = true }}, + {"check-failing", func(i *Input) { i.CIGreen = false }}, + {"dco-missing", func(i *Input) { i.CIGreen = true; i.DCOMissing = true }}, + {"adoption-stalled", func(i *Input) { i.CIGreen = true; i.AdoptionStalled = true }}, + } + for _, p := range patterns { + t.Run(p.name+"/unreachable", func(t *testing.T) { + in := with(base, p.mut) + if in.ContributorReachable() || !AdoptsImmediately(in) { + t.Fatalf("an unreachable author's head is superseded now (reachable=%v)", in.ContributorReachable()) + } + }) + for _, reach := range []struct { + name string + mut func(*Input) + }{ + {"online", func(i *Input) { i.ContributorOnline = true }}, + {"rework-picked-up", func(i *Input) { i.ReworkPickedUp = true }}, + } { + t.Run(p.name+"/"+reach.name, func(t *testing.T) { + in := with(with(base, p.mut), reach.mut) + if !in.ContributorReachable() || AdoptsImmediately(in) { + t.Fatalf("a reachable author gets a real chance, not rung 5") + } + }) + } + } +} diff --git a/src/pkg/github/automerge/automerge_contributor_nudge.go b/src/pkg/github/automerge/automerge_contributor_nudge.go index 36935fec1c..c037f3658b 100644 --- a/src/pkg/github/automerge/automerge_contributor_nudge.go +++ b/src/pkg/github/automerge/automerge_contributor_nudge.go @@ -11,6 +11,7 @@ import ( gh "github.com/google/go-github/v72/github" "github.com/hivecommons/hive/pkg/advisory" + "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/prstatus" "github.com/hivecommons/hive/pkg/stagelabels" ) @@ -377,9 +378,36 @@ func ciNudgeDue(rec stagelabels.Record, head string, checks []string, repeatAfte return 1, true } +// adoptionBound reports whether the hive is going to adopt this head +// whatever the author does next, so one notification (the adoption note) +// replaces the nudge (hivecommons/hive#18872). It is the nudge-side twin of +// delegatedecision.AdoptsImmediately: an author whose relay is online (or +// who has picked the rework up) is given the real grace and is nudged; an +// author with no reachable relay (registered but offline, or not registered +// here) is adopted on the AutoAdoption clock, which only needs the nudge to +// be recorded, not posted. Anything that could keep the adoption from +// happening (no presence source, a hold label, a fork guard, a workflow +// path, a person's PR, a maintainer policy other than adopt, a recorded +// block) keeps the nudge, so no author is left with no word at all. +func adoptionBound(rec stagelabels.Record, obs stageObservation, policy StageLabelPolicy, presence ContributorPresence, hasPresence bool) bool { + if !policy.NudgeWithholdWhenAdopting || !policy.Adoption || !hasPresence || (presence.Registered && presence.Online) { + return false + } + if obs.HeadSHA == "" || rec.AdoptionBlocked(obs.HeadSHA) != "" || adoptionBlocked(obs.Labels) != "" || adoptionForkGuardOnly(obs) { + return false + } + if policy.maintainerPolicy() != config.AdoptionMaintainerPolicyAdopt || personAuthored(obs, policy) { + return false + } + return !strings.Contains(nonEmpty(obs.Reason, obs.LaneReason), contributorLaneReasonWorkflowPath) +} + // nudgeContributor runs the stage-072 nudge for one observation. It returns -// the number of GitHub comments posted. -func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, now time.Time) (int, error) { +// the number of GitHub comments posted. When the hive is going to adopt the +// head anyway (adoptionBound) the nudge is recorded, so the adoption clock +// runs, and dispatched to the relay, but the GitHub comment is withheld +// (hivecommons/hive#18872); it is posted later if adoption does not happen. +func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, presence ContributorPresence, hasPresence bool, now time.Time) (int, error) { rec, ok := store.Get(key) if !ok || obs.Author == "" { return 0, nil @@ -410,8 +438,14 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, } else { ordinal, due = nudgeDue(rec, obs.HeadSHA, obs.Reason, policy.RenudgeInterval, now) } + bound := adoptionBound(rec, obs, policy, presence, hasPresence) if !due { - return 0, nil + // A withheld nudge is owed to the author as soon as the adoption + // that was to speak for this head is no longer certain. + if bound || rec.NudgeWithheldHead == "" || rec.NudgeWithheldHead != obs.HeadSHA { + return 0, nil + } + ordinal = 0 } // A head-only rewrite (ordinal 0) keeps the class's recorded count in // the marker; the author pushed, so it is not the stall reminder. @@ -447,13 +481,18 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, // is the interrupt. posted := 0 if existing := c.findOwnEntryComment(ctx, obs, ContributorNudgeMarkerPrefix); existing != nil { + store.NoteNudgeWithheld(key, "") if existing.GetBody() != body { if _, _, err := c.gh.Issues.EditComment(ctx, obs.Owner, obs.Repo, existing.GetID(), &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { // writeback:gated c.warn("stage labels: contributor nudge edit failed", "repo", obs.Display, "pr", obs.Number, "error", err) return 0, err } } + } else if bound { + store.NoteNudgeWithheld(key, obs.HeadSHA) + c.info("stage labels: contributor nudge withheld, the hive adopts this head anyway; the adoption note is the one notification", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "reason", obs.Reason, "registered", presence.Registered) } else { + store.NoteNudgeWithheld(key, "") if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "error", err) return 0, err @@ -468,7 +507,7 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, if ciFailure { store.MarkNudgedCIFailure(key, checks, obs.HeadSHA, nonEmpty(out.Mode, "comment"), attempt, ordinal == 1, now) } - c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "posted", posted == 1, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason) + c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "posted", posted == 1, "withheld", bound && posted == 0, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason) return posted, nil } diff --git a/src/pkg/github/automerge/automerge_nudge_withhold_test.go b/src/pkg/github/automerge/automerge_nudge_withhold_test.go new file mode 100644 index 0000000000..498ea10f73 --- /dev/null +++ b/src/pkg/github/automerge/automerge_nudge_withhold_test.go @@ -0,0 +1,153 @@ +package automerge + +import ( + "testing" + "time" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// hivecommons/hive#18872: a contributor got "this PR is back in your court" +// and 16-39 minutes later the hive adopted the same PR. The nudge and the +// adoption now agree on one outcome per head: a head the hive adopts anyway +// (author relay offline or unregistered) is nudged on the record only, so +// the adoption clock runs and the adoption note is the one notification; a +// head with a real chance (relay online) keeps its nudge and is not adopted +// before the grace. + +// withholdPatterns are the four pairs observed on the hive's spoke: +// #18561 contributor-lane, #18628 fork-not-editable, #18514 check-failing, +// #18510 conflicting. +var withholdPatterns = []struct{ name, reason string }{ + {"contributor-lane", contributorLaneReasonChangesRequested}, + {"fork-not-editable", autoMergeReasonForkNotEditable}, + {"check-failing", "required-check-failing:changelog-fragment-guard"}, + {"conflicting", "conflicting"}, +} + +var withholdLabels = []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"} + +func withholdPolicy() StageLabelPolicy { + p := adoptPolicy() + p.NudgeWithholdWhenAdopting = true + return p +} + +func TestNudgeWithheldWhenHiveAdoptsAnyway(t *testing.T) { + for _, pat := range withholdPatterns { + for _, registered := range []bool{true, false} { + name := pat.name + "/unregistered" + if registered { + name = pat.name + "/offline" + } + t.Run(name, func(t *testing.T) { + h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy()) + defer done() + start := h.clock.at + h.sink.presence = &ContributorPresence{Registered: registered} + h.observe(adoptPR(7, "aaa"), pat.reason) + // Invariant 1: no nudge comment for a head that is adopted anyway. + if got := nudgeComments(h.api); len(got) != 0 { + t.Fatalf("nudge posted for a head the hive adopts anyway: %v", got) + } + // The nudge is recorded: the adoption clock is running on it. + rec, ok := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7)) + if !ok || rec.NudgeHead != "aaa" || rec.NudgeCount == 0 || rec.NudgeWithheldHead != "aaa" { + t.Fatalf("withheld nudge not recorded: %+v", rec) + } + // The adoption follows on the AutoAdoption clock, with its note. + h.api.reset() + h.clock.at = start.Add(16 * time.Minute) + h.observe(adoptPR(7, "aaa", withholdLabels...), pat.reason) + if len(adoptionComments(h.api)) != 1 { + t.Fatalf("no adoption note at +16m: %v", h.api.comments) + } + if got := nudgeComments(h.api); len(got) != 0 { + t.Fatalf("a nudge was posted next to the adoption: %v", got) + } + }) + } + } +} + +func TestNudgeKeptAndNoEarlyAdoptionWhenAuthorHasARealChance(t *testing.T) { + for _, pat := range withholdPatterns { + t.Run(pat.name, func(t *testing.T) { + h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy()) + defer done() + start := h.clock.at + h.sink.presence = &ContributorPresence{Registered: true, Online: true} + h.observe(adoptPR(7, "aaa"), pat.reason) + if len(nudgeComments(h.api)) != 1 { + t.Fatalf("an online author is nudged: %v", h.api.comments) + } + // Invariant 2: not adopted before the online grace. + for _, at := range []time.Duration{16 * time.Minute, 31 * time.Minute, time.Hour} { + h.api.reset() + h.clock.at = start.Add(at) + h.observe(adoptPR(7, "aaa", withholdLabels...), pat.reason) + if len(adoptionComments(h.api)) != 0 || len(h.adopt.pulls) != 0 { + t.Fatalf("adopted at +%v before the grace: %v", at, h.api.comments) + } + } + }) + } +} + +func TestWithheldNudgeIsPostedWhenTheAuthorReappears(t *testing.T) { + h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy()) + defer done() + start := h.clock.at + h.sink.presence = &ContributorPresence{Registered: true} + h.observe(adoptPR(7, "aaa"), "conflicting") + if len(nudgeComments(h.api)) != 0 { + t.Fatalf("nudge should be withheld: %v", h.api.comments) + } + // The relay reconnects before the adoption is due: a real chance now. + h.sink.presence = &ContributorPresence{Registered: true, Online: true} + h.clock.at = start.Add(5 * time.Minute) + h.observe(adoptPR(7, "aaa", withholdLabels...), "conflicting") + if len(nudgeComments(h.api)) != 1 { + t.Fatalf("the withheld nudge is owed once the author is reachable: %v", h.api.comments) + } + rec, _ := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7)) + if rec.NudgeWithheldHead != "" { + t.Fatalf("withheld mark not cleared: %+v", rec) + } +} + +func TestNudgeNotWithheldWithoutCertainAdoption(t *testing.T) { + t.Run("config off", func(t *testing.T) { + h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, adoptPolicy()) + defer done() + h.sink.presence = &ContributorPresence{Registered: true} + h.observe(adoptPR(7, "aaa"), "conflicting") + if len(nudgeComments(h.api)) != 1 { + t.Fatalf("withholding is off by default in the engine: %v", h.api.comments) + } + }) + t.Run("no presence source", func(t *testing.T) { + fake := &fakeNudgeSink{outcome: ContributorNudgeOutcome{Mode: "comment"}} + h, done := newAdoptHarnessWith(t, fake, nudgeOnlySink{fake}, withholdPolicy()) + defer done() + h.observe(adoptPR(7, "aaa"), "conflicting") + if len(nudgeComments(h.api)) != 1 { + t.Fatalf("without presence the adoption is not certain: %v", h.api.comments) + } + }) + t.Run("adoption disabled", func(t *testing.T) { + p := withholdPolicy() + p.Adoption = false + rec := stagelabels.Record{} + if adoptionBound(rec, stageObservation{HeadSHA: "aaa"}, p, ContributorPresence{Registered: true}, true) { + t.Fatal("adoption off cannot be certain") + } + }) + t.Run("maintainer policy ask", func(t *testing.T) { + p := withholdPolicy() + p.AdoptionMaintainerPolicy = "ask" + if adoptionBound(stagelabels.Record{}, stageObservation{HeadSHA: "aaa"}, p, ContributorPresence{Registered: true}, true) { + t.Fatal("a held adoption cannot be certain") + } + }) +} diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 628f909a75..9620056681 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -104,6 +104,10 @@ type StageLabelPolicy struct { // Every other contributor-lane gate still applies; the head must be // exactly the one the stage store records as adopted/pushed by the hive. AdoptionAutoMerge bool + // NudgeWithholdWhenAdopting withholds the nudge comment for a head the + // hive adopts anyway (governor.labels.stage.contributor_nudge. + // withhold_when_adopting, default on in the config; hivecommons/hive#18872). + NudgeWithholdWhenAdopting bool // AdoptionMaintainerPolicy is governor.labels.stage.adoption.maintainer_policy // (config.AdoptionMaintainerPolicy*): what adoption does when the PR // author holds admin or maintain on the repository. "" reads as the @@ -1429,7 +1433,7 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) } if kind == authorkind.Clanker { if policy.ContributorNudge && !adoptionRetry { - n, err := c.nudgeContributor(ctx, store, key, obs, policy, now) + n, err := c.nudgeContributor(ctx, store, key, obs, policy, presence, hasPresence, now) result.Comments += n if err != nil && firstErr == nil { firstErr = err diff --git a/src/pkg/stagelabels/store.go b/src/pkg/stagelabels/store.go index d176b8c208..e6099c9b7e 100644 --- a/src/pkg/stagelabels/store.go +++ b/src/pkg/stagelabels/store.go @@ -92,6 +92,12 @@ type Record struct { NudgeReason string `json:"nudge_reason,omitempty"` NudgeReasonCount int `json:"nudge_reason_count,omitempty"` NudgeReasonAt time.Time `json:"nudge_reason_at,omitempty"` + // NudgeWithheldHead is the head whose nudge comment was withheld + // because the hive is going to adopt it anyway (hivecommons/hive#18872): + // the nudge is recorded (the adoption clock runs) but the author hears + // only the adoption note. When adoption turns out blocked or the author + // reappears the withheld nudge is posted. + NudgeWithheldHead string `json:"nudge_withheld_head,omitempty"` // NudgeCIChecks, NudgeCIHead, NudgeCIAt, NudgeCIAttempts and NudgeMode // are the CI-failure nudge ledger (hivecommons/hive#17328): the sorted // failing check names the one nudge comment currently lists, the head @@ -1493,6 +1499,20 @@ func (s *Store) MarkNudged(key, head string, n int, online bool, now time.Time) s.dirty = true } +// NoteNudgeWithheld records that the nudge comment for head was withheld +// (head "" clears the mark). +func (s *Store) NoteNudgeWithheld(key, head string) { + s.mu.Lock() + defer s.mu.Unlock() + r, ok := s.items[key] + if !ok || r.NudgeWithheldHead == head { + return + } + r.NudgeWithheldHead = head + s.items[key] = r + s.dirty = true +} + // MarkNudgedReason records that nudge number n for reason class reason was // posted (or the one nudge comment rewritten) at now. A different class // restarts the count at n; the same class keeps the larger of n and the From f6e3dd05d31a8c9dbbfc52ab3efdaa9f9328d3a5 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 17 Nov 2026 23:00:15 -0500 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=90=9B=20Drop=20the=20withhold=20conf?= =?UTF-8?q?ig=20leaf;=20the=20withholding=20is=20always=20on=20in=20produc?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- changelog.d/fixed-18872-nudge-then-adopt.md | 2 +- src/cmd/hive/merge_eligibility.go | 2 +- src/docs/labels-and-control-signals/stage-labels.md | 2 -- src/docs/operator-reference/README.md | 1 - src/pkg/config/config.go | 13 ------------- src/pkg/github/automerge/automerge_stage_labels.go | 5 +++-- 6 files changed, 5 insertions(+), 20 deletions(-) diff --git a/changelog.d/fixed-18872-nudge-then-adopt.md b/changelog.d/fixed-18872-nudge-then-adopt.md index c2d15f86f1..15e102d387 100644 --- a/changelog.d/fixed-18872-nudge-then-adopt.md +++ b/changelog.d/fixed-18872-nudge-then-adopt.md @@ -1 +1 @@ -- A contributor PR the hive is going to adopt anyway (author relay offline or unregistered, adoption enabled and unblocked) no longer gets a "back in your court" nudge followed by an adoption note 16-39 minutes later: the nudge is recorded (the adoption clock still runs, the relay still gets its task) but its GitHub comment is withheld, so the author gets one notification, and it is posted if the adoption stops being certain; an online author keeps the nudge and the full grace, and the ladder's immediate-supersede rung fires only for an unreachable author, the same condition. `governor.labels.stage.contributor_nudge.withhold_when_adopting: false` restores the old behavior (#18872). +- A contributor PR the hive is going to adopt anyway (author relay offline or unregistered, adoption enabled and unblocked) no longer gets a "back in your court" nudge followed by an adoption note 16-39 minutes later: the nudge is recorded (the adoption clock still runs, the relay still gets its task) but its GitHub comment is withheld, so the author gets one notification, and it is posted if the adoption stops being certain; an online author keeps the nudge and the full grace, and the ladder's immediate-supersede rung fires only for an unreachable author, the same condition. (#18872). diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index ff961c7258..a8056cecdf 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -116,7 +116,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy Dwell: stage.DwellOverrides(), StalledRequireQuiet: stage.Stalled.IsRequireQuiet(), ContributorNudge: stage.ContributorNudge.IsEnabled(), - NudgeWithholdWhenAdopting: stage.ContributorNudge.IsWithholdWhenAdopting(), + NudgeWithholdWhenAdopting: true, RenudgeInterval: nudgeRepeatAfter(cfg), CIFailureCooldown: stage.ContributorNudge.EffectiveCIFailureCooldown(), Adoption: stage.Adoption.IsEnabled(), diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 1b8ff8376a..180fe5e0f0 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -815,8 +815,6 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human- (`contributor-offline`, supersede now) only fires for an author who is not reachable, the same condition. This follows the documented rule that a contributor who has gone quiet is superseded now (#13975). - `governor.labels.stage.contributor_nudge.withhold_when_adopting: false` - restores a nudge for every head. 2. Relay contributors (the author has a contributor profile and a live relay connection) also receive the diagnosis in their relay session as a `fix-pr` task with `priority: interrupt`. Presence = a relay heartbeat diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 2fc4646497..1ea3922f00 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -494,7 +494,6 @@ advanced into the merge path. | `auto_merge.max_merges` | `3` (`DefaultAutoMergeSweepMaxMerges`) when 0/unset | Caps merges per sweep pass. | | `auto_merge.min_head_age` | `3m` | Minimum PR head age before automerge trusts an unknown required-check set. A fresh head pushed more recently than this waits with `pending: head pushed ... ago (< min_head_age)` unless `auto_merge.required_checks` is declared and every required check is complete and successful. Head age is measured from the head commit's committer date (never earlier than the PR's creation), not the PR's `updated_at`, so label and comment activity — including the hive's own — does not restart it. When GitHub's head time is ahead of the host clock (clock skew), age is measured from when the hive first observed the head instead, so the hold lasts one window and then clears (`pending: head time ahead of host clock; head first seen ... ago (< min_head_age)`). | | `auto_merge.nudge_repeat_after` | `72h` | How long a contributor nudge's condition must persist before the hive nudges once more. Nudges are one comment per PR and reason class, edited in place for a new head or changed reason; after this interval with the same condition the comment is re-posted once (cap 2 per reason), then never again. `governor.labels.stage.contributor_nudge.renudge_interval`, when set, overrides it. | -| `governor.labels.stage.contributor_nudge.withhold_when_adopting` | `true` | Withhold the "back in your court" comment for a head the hive adopts anyway (author relay offline or unregistered, adoption enabled and unblocked): the nudge is recorded and the adoption note is the one notification; posted later if the adoption stops being certain (hivecommons/hive#18872). `false` nudges every head. | | `governor.labels.stage.contributor_nudge.ci_failure_cooldown` | `6h` | CI-failure nudges are keyed on the failing-check set: the same set red on a new head, or a check joining the set on the same head, edits the PR's one nudge comment. A *different* set on a new head inside this window is folded into that comment too (count unchanged); after it the hive counts a fresh nudge. | | `auto_merge.required_checks` | unset | Default operator-declared status-check contexts / check-run names (e.g. `["build-gate"]`) that the sweep's green gate requires on repos without a per-repo override. See below. | | `auto_merge.repos..required_checks` | inherits default | Per-repo override for heterogeneous hives. `` may be the bare name from `project.repos` or `owner/repo`; an explicit empty list declares that GitHub has no required contexts, while Hive still requires positive CI evidence from at least one real successful check-run before merge. | diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index c6452e5066..2ff04fba8d 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -3523,19 +3523,6 @@ type ContributorNudgeConfig struct { // comment instead of counting as a fresh nudge // (hivecommons/hive#17328). Default DefaultContributorNudgeCIFailureCooldown (6h). CIFailureCooldown string `yaml:"ci_failure_cooldown,omitempty"` - // WithholdWhenAdopting withholds the "back in your court" comment for a - // head the hive is going to adopt anyway (author relay offline or - // unregistered, adoption enabled and unblocked): the nudge is still - // recorded and the adoption note is the one notification - // (hivecommons/hive#18872). nil = true; false restores a nudge for every - // head. - WithholdWhenAdopting *bool `yaml:"withhold_when_adopting,omitempty"` -} - -// IsWithholdWhenAdopting reports whether the nudge comment is withheld for -// a head the hive adopts anyway (default on). -func (c ContributorNudgeConfig) IsWithholdWhenAdopting() bool { - return c.WithholdWhenAdopting == nil || *c.WithholdWhenAdopting } // DefaultContributorNudgeCIFailureCooldown is diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 9620056681..c6dc780f72 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -105,8 +105,9 @@ type StageLabelPolicy struct { // exactly the one the stage store records as adopted/pushed by the hive. AdoptionAutoMerge bool // NudgeWithholdWhenAdopting withholds the nudge comment for a head the - // hive adopts anyway (governor.labels.stage.contributor_nudge. - // withhold_when_adopting, default on in the config; hivecommons/hive#18872). + // hive adopts anyway (always on in production, see stageLabelPolicyFunc; + // off in the zero policy so older tests keep their nudge; + // hivecommons/hive#18872). NudgeWithholdWhenAdopting bool // AdoptionMaintainerPolicy is governor.labels.stage.adoption.maintainer_policy // (config.AdoptionMaintainerPolicy*): what adoption does when the PR From 3272874e14137ce83a187828f2598881661c6c24 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 17 Nov 2026 23:00:43 -0500 Subject: [PATCH 3/4] =?UTF-8?q?=E2=9C=85=20Name=20the=20zero-policy=20subt?= =?UTF-8?q?est?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/pkg/github/automerge/automerge_nudge_withhold_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pkg/github/automerge/automerge_nudge_withhold_test.go b/src/pkg/github/automerge/automerge_nudge_withhold_test.go index 498ea10f73..3cb98f96b7 100644 --- a/src/pkg/github/automerge/automerge_nudge_withhold_test.go +++ b/src/pkg/github/automerge/automerge_nudge_withhold_test.go @@ -117,7 +117,7 @@ func TestWithheldNudgeIsPostedWhenTheAuthorReappears(t *testing.T) { } func TestNudgeNotWithheldWithoutCertainAdoption(t *testing.T) { - t.Run("config off", func(t *testing.T) { + t.Run("policy flag off", func(t *testing.T) { h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, adoptPolicy()) defer done() h.sink.presence = &ContributorPresence{Registered: true} From a49f06961b2bdaf0dc46c47c08f11db0d9694eef Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 17 Nov 2026 23:09:39 -0500 Subject: [PATCH 4/4] =?UTF-8?q?=E2=9C=85=20Cover=20the=20withheld-nudge=20?= =?UTF-8?q?store=20mark?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/pkg/stagelabels/nudge_withheld_test.go | 28 ++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 src/pkg/stagelabels/nudge_withheld_test.go diff --git a/src/pkg/stagelabels/nudge_withheld_test.go b/src/pkg/stagelabels/nudge_withheld_test.go new file mode 100644 index 0000000000..aed9faeea9 --- /dev/null +++ b/src/pkg/stagelabels/nudge_withheld_test.go @@ -0,0 +1,28 @@ +package stagelabels + +import ( + "testing" + "time" +) + +// hivecommons/hive#18872: a nudge comment withheld because the hive adopts +// the head anyway is remembered per head, and cleared once it is posted. +func TestStoreNoteNudgeWithheld(t *testing.T) { + now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC) + s := NewStore("", func() time.Time { return now }) + s.NoteNudgeWithheld("missing", "aaa") // unknown key: no-op + if _, ok := s.Get("missing"); ok { + t.Fatal("NoteNudgeWithheld created a record") + } + key := Key("acme/widget", 7) + s.Observe(key, ReturnedToContributor, "conflicting") + s.NoteNudgeWithheld(key, "aaa") + if r, _ := s.Get(key); r.NudgeWithheldHead != "aaa" { + t.Fatalf("withheld not recorded: %+v", r) + } + s.NoteNudgeWithheld(key, "aaa") // unchanged: no-op + s.NoteNudgeWithheld(key, "") + if r, _ := s.Get(key); r.NudgeWithheldHead != "" { + t.Fatalf("withheld not cleared: %+v", r) + } +}