Skip to content

πŸ› fix(fork-guard): keep a fork PR waiting on a maintainer-run check with the maintainer across heads - #16814

Merged
hivecommons-hive[bot] merged 2 commits into
hivecommons:v6from
Danathar:fix/fork-canary-routing
Nov 5, 2026
Merged

hivecommons-hive[bot] merged 2 commits into
hivecommons:v6from
Danathar:fix/fork-canary-routing

Conversation

@Danathar

@Danathar Danathar commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Executive summary

Some fork PRs wait on a check only a maintainer can run for that exact head. On projectbluefin/utah-packages, that check is the fork Canary: a maintainer dispatches it for one exact head. The hive already parks such PRs at 085 as fork-guard:<check> (#14273). Two things kept undoing that park:

  • New heads were nudged to the author. A new head read as an ordinary red check until the next enumeration read the check's annotation, so the PR dropped to 072 and the author was nudged to fix something only a maintainer can.
  • The branch kept being updated. The contributor lane updated the branch whenever it was behind, and each merge of the base discarded the exact-head run the PR was waiting for.

This PR carries the recorded fork guard onto a new head while the same check is red. It also stops branch updates while the head waits on a fork-guarded check. The 085 ask now names the head the maintainer must run the check for.

Evidence (projectbluefin hive log, 2026-11-05)

Time (Z) projectbluefin/utah-packages#869
18:03:09 head 7bcc81b: stage 085-needs-decision reason fork-guard:Canary
18:04:01 contributor lane: automerge update-branch reason=behind β†’ hive merge commit 08b9e69
18:05:32 head 08b9e69: stage 072-returned-to-contributor reason required-check-failing:Canary (no fork-guard entry for the new head yet)
18:05:40 contributor nudged … reason required-check-failing:Canary
18:09:15 back at 085: "check Canary refuses pull requests from a fork, so neither the author nor the hive can turn it green"
18:15:05 the author's own push 466f81f, nudged again

The Canary annotation itself says so: "a fork pull request cannot publish the canary image, and no maintainer-run Canary has passed on . This is expected, not something the author can fix".

projectbluefin/utah-packages#862 shows the same cycle. The hive made 13 merge-of-main commits on it between 10-31 and 11-02, and on most heads it nudged the author and then returned to 085, even though the author had asked three times for maintainer routing. projectbluefin/utah-packages#877 and #878 got the same Canary nudge.

What

Situation (fork PR, fork-guarded check red) Before After
New head, annotation not read yet 072, author nudged, back to 085 minutes later Stays 085 fork-guard:<check>; no nudge
New head, a different check red 072, nudged 072, nudged (unchanged)
Head is behind the base Branch updated (new head, maintainer's run lost) Not updated; the lane reports required-check-failing:<check>
Check turned green after the maintainer's run β€” Guard drops; branch updates resume before merge
085 ask "…(or approve the run as the repository requires)" "…(or run or approve it for head abc1234 as the repository requires)"

How

  • automerge_fork_guard_carry.go (new):
    • carriedForkGuard reads the stage record's fork-guard:<checks> reason. It applies when the head is from a fork and the lane's red check (required-check-failing:, check-failing: or optional-check-failing:) is one of those checks.
    • ForkGuardStage still requires a red CI reason and every red optional check in the list, so any other failure goes to the author as before.
  • recordStage: uses the carried guard only when the per-head index (StageLabelPolicy.ForkGuard) has none. The legacy pass and the engine mirror read the same ForkGuardChecks.
  • updateBranchAndSkip: a fork head whose index shows a fork-guarded check is not updated. All automerge update paths go through this function.
    • Only the per-head index is consulted here, never the record. A remembered guard may already be green, and skipping on it would keep the PR parked on a check that passed.
  • stagelabels/human.go: the fork-guard ask names the head (ShortSHA).

Tests

Test Covers
TestForkGuardCarriesAcrossHeadsWithoutNudge #869 shape through ApplyStageLabels: indexed head β†’ 085; new unindexed head β†’ 085, no nudge; other red check β†’ 072 + nudge
TestLaneRedCheckAndCarriedForkGuard fork vs same-repo, record reason, check in or out of the list, optional prefix
TestUpdateBranchSkipsForkGuardedHead guarded fork head not updated; unguarded fork head and same-repo head updated
TestRouteHumanForkGuard (updated) the ask names the head
Mutants 9/9 caught (one equivalent guard removed instead)
go test automerge, stagelabels, stageengine/..., github, writeback pass
check-docs-citations.py src/docs, writeback ratchet, gofmt, vet pass

Notes

  • Already in v6, so not changed here: a reviewer re-run on a merge-only delta. An approve carries across the hive's own base-sync merge (✨ feat(review): carry an approve across the hive's own base-sync mergeΒ #15046), and across a head whose PR diff is empty (πŸ› fix: keep merge queue position visible during sweepsΒ #15499). With no merge-of-main heads while the PR waits, those re-runs stop anyway.
  • Not changed:
    • The fork guard is still detected from the check's annotation text (fork_guard.go). No new config key is needed for these repos, because the Canary annotation already matches.
    • The merge train's own update (mergelane) is untouched; a fork-guarded PR is "left out of every train" (needs-decision).
  • No duplicate: no open PR covers this, and origin/v6..origin/v5 has nothing in these files.

πŸ€– Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…ith the maintainer across heads

projectbluefin/utah-packages#869 and hivecommons#862: a new head on a fork PR parked
at 085 fork-guard:Canary read as an ordinary red check until the next
enumeration read its annotation, so it dropped to 072 and the author was
nudged; and the contributor lane updated the branch whenever it was behind
(13 merge-of-main heads on hivecommons#862), each discarding the exact-head run the
PR waited for.

- recordStage carries the record's fork-guard:<checks> reason onto a new
  fork head while the lane's red check is one of them.
- updateBranchAndSkip does not update a fork head the per-head index shows
  waiting on a fork-guarded check.
- the 085 ask names the head the maintainer must run the check for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 5, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign nicholasjackson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 5, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Security perspective β€” one in-scope finding (head 7054dd0).

Carried fork guard never drops on a genuine red of the guarded check β€” the 085 ask keeps telling a maintainer the failure is expected

carriedForkGuard (src/pkg/github/automerge/automerge_fork_guard_carry.go:62-74) is consulted whenever the per-head index returns nothing (automerge_stage_labels.go:519-523). But the index cannot tell "head not read yet" from "head read, and the check failed for a real reason": src/cmd/hive/stage_shared_ci.go:48-50 stores an entry only when incident > 0 || baseRed || forkGuard, and stageForkGuard (stage_shared_ci.go:84-89) returns nil for both cases. ForkGuardChecksFor (src/pkg/github/fork_guard.go:43-63) returns nil as soon as the annotation is not a fork-guard phrase.

So after a maintainer runs Canary for the exact head and it fails on the fork's content (build error, policy violation, …):

  1. index β†’ nil; 2. record still says fork-guard:Canary (written by the previous carry); 3. lane reason is required-check-failing:Canary β†’ carry fires again; 4. ForkGuardStage re-records fork-guard:Canary (stageengine/derive_pr_classify.go:751-765). The loop only exits when Canary goes green or a different check goes red. Neither the author nor the hive is told the check actually failed, and the 085 entry text (src/pkg/stagelabels/human.go:515-521) keeps asserting the red is a fork refusal and that "a maintainer must push this branch to the repository" β€” for a fork head whose maintainer-run check just rejected it. The PR body's "What" table only covers the green case ("guard drops"); the genuinely-red case is unaddressed and no test covers an indexed head with a non-guard annotation (automerge_fork_guard_carry_test.go:62-67 returns nil only for unindexed heads).

Suggested fix β€” make nil mean unknown and an empty non-nil slice mean read, not a guard, and carry only on unknown:

--- a/src/cmd/hive/stage_shared_ci.go
+++ b/src/cmd/hive/stage_shared_ci.go
@@ stageSharedCIEntry
 	forkGuard []string
+	// forkRed is set when the PR is from a fork and has failing checks, so a
+	// lookup can tell "read, not a guard" from "not read yet".
+	forkRed bool
@@ index build
 				e.forkGuard = pr.ForkGuardChecks()
-				if e.incident > 0 || len(e.baseRed) > 0 || len(e.forkGuard) > 0 {
+				e.forkRed = pr.FromFork && len(pr.FailingChecks) > 0
+				if e.incident > 0 || len(e.baseRed) > 0 || len(e.forkGuard) > 0 || e.forkRed {
 					idx[stageSharedCIKey(pr.Repo, pr.Number)] = e
 				}
@@ func stageForkGuard
 	e, ok := stageSharedCILookup(repo, number, head)
-	if !ok || len(e.forkGuard) == 0 {
+	if !ok {
 		return nil
 	}
+	if len(e.forkGuard) == 0 {
+		if e.forkRed {
+			return []string{} // read for this head: red, but not a fork guard
+		}
+		return nil
+	}
 	return append([]string(nil), e.forkGuard...)
--- a/src/pkg/github/automerge/automerge_stage_labels.go
+++ b/src/pkg/github/automerge/automerge_stage_labels.go
@@ recordStage
-	if len(obs.ForkGuardChecks) == 0 {
+	if obs.ForkGuardChecks == nil {
 		rec, ok := c.stageStoreOrShared().Get(stageKey(owner, repo, obs.Number))
 		obs.ForkGuardChecks = carriedForkGuard(rec, ok, obs)
 	}

(ForkGuardStage already treats an empty slice as "no guard" via len(...) == 0, so the head is then handed back to the author as before.) Please also add a test: indexed head whose Canary is red with a non-guard annotation β†’ 072 + nudge, not 085.

Everything else from this perspective is fine: the carried reason is read only from the hive's own stage store (stagelabels.Record.Reason, written by the tracker, not from PR labels/comments), the carry can only park at 085 (Human: true) and never admits a merge, and updateBranchAndSkip consults the index alone (automerge_sweep_trusted.go:887-895), so a stale record cannot block updates once the check is green.

β€” hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Hive status β€” updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review (head 7054dd0)

1. The carried guard is self-sustaining: once a PR is recorded fork-guard:<check>, a later head where that check is red for a real reason never returns to the author. (medium, in-scope)

recordStage falls back to the record whenever the per-head index is empty (src/pkg/github/automerge/automerge_stage_labels.go:520-523). But the index is empty in two indistinguishable cases: the head has not been enumerated yet, and the head was enumerated and ForkGuardChecks() came back empty β€” publishStageSharedCIIncidents only stores an entry when incident/baseRed/forkGuard is non-empty (src/cmd/hive/stage_shared_ci.go:48-51), and stageForkGuard returns nil for both !ok and an empty list (stage_shared_ci.go:84-89; the policy doc at automerge_stage_labels.go:163-170 says "nil = unknown (no park)").

So after the first carried observation writes the record with reason fork-guard:Canary (asserted by TestForkGuardCarriesAcrossHeadsWithoutNudge, automerge_fork_guard_carry_test.go:95-97), every subsequent head goes: lane says required-check-failing:Canary β†’ index nil β†’ carriedForkGuard matches the record β†’ ForkGuardStage β†’ 085 β†’ record stays fork-guard:Canary. The annotation for the new head is never consulted again. If Canary now fails for something the author owns (the fork-refusal annotation is gone), the PR is parked on a maintainer indefinitely instead of dropping to 072 β€” the inverse of #14273's "a fork PR with any other red check is handed back as usual" (stage-labels.md:378). The Detail.RedChecks βŠ† ForkGuardChecks test in ForkGuardStage (derive_pr_classify.go:758-762) does not help here because the one red check is the carried name.

The PR body notes this exact hazard for updateBranchAndSkip ("A remembered guard may already be green…") but the stage path has the same shape. The missing test is: head indexed (enriched) with no fork guard, Canary red β†’ expect 072 + nudge.

Suggested fix β€” let the index say whether it has read the head, and carry only while it has not:

--- a/src/cmd/hive/stage_shared_ci.go
+++ b/src/cmd/hive/stage_shared_ci.go
@@ publishStageSharedCIIncidents
 				e.forkGuard = pr.ForkGuardChecks()
-				if e.incident > 0 || len(e.baseRed) > 0 || len(e.forkGuard) > 0 {
-					idx[stageSharedCIKey(pr.Repo, pr.Number)] = e
-				}
+				// Store every enriched head so the stage can tell "not read yet"
+				// from "read, no guard" (the fork-guard carry depends on it).
+				idx[stageSharedCIKey(pr.Repo, pr.Number)] = e
@@
+// stageForkGuardRead answers StageLabelPolicy.ForkGuardRead: the index has
+// CI-enriched this exact head, so an empty ForkGuard means "no guard".
+func stageForkGuardRead(repo string, number int, head string) bool {
+	_, ok := stageSharedCILookup(repo, number, head)
+	return ok
+}
--- a/src/pkg/github/automerge/automerge_stage_labels.go
+++ b/src/pkg/github/automerge/automerge_stage_labels.go
@@ type StageLabelPolicy
 	ForkGuard func(repo string, number int, head string) []string
+	// ForkGuardRead reports whether the index has enriched this head; nil =
+	// unknown. The recorded fork guard is carried onto a head only until then.
+	ForkGuardRead func(repo string, number int, head string) bool
@@ recordStage
-	if len(obs.ForkGuardChecks) == 0 {
+	if len(obs.ForkGuardChecks) == 0 && !(policy.ForkGuardRead != nil && policy.ForkGuardRead(owner+"/"+repo, obs.Number, obs.HeadSHA)) {
 		rec, ok := c.stageStoreOrShared().Get(stageKey(owner, repo, obs.Number))
 		obs.ForkGuardChecks = carriedForkGuard(rec, ok, obs)
 	}

(plus wiring ForkGuardRead: stageForkGuardRead where ForkGuard: stageForkGuard is set, and the test above.)

2. Body claim "All automerge update paths go through this function" is not quite true. (low)

automerge_merge_train.go:916 calls executeUpdateBranchEffect directly for a behind train member, bypassing the new skip in updateBranchAndSkip (automerge_sweep_trusted.go:887-895). I could not confirm within this review whether a fork-guarded PR can be a train member; if it cannot, this is only a doc nit, otherwise the same exact-head run is still discarded there.

Evidence bundle `#16814f044fc6` sha256:ab58bf7d1c1778ba0c41714537cbf414fdfa6cbdba3ee6e5fdf4ee6802eae8ed β€” download from the dashboard or `hivectl review evidence #16814`.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the new carry, recordStage, updateBranchAndSkip and its seven callers, stageForkGuard β†’ ForkGuardChecksFor, and ForkGuardStage at head 7054dd0. The mechanism does what the body says for the #869 shape: a fork head with required-check-failing:Canary and a record at fork-guard:Canary stays at 085 and is not nudged, and a fork head whose index shows the guard is no longer branch-updated. go build of the touched packages is clean; the targeted tests read as covering those three paths.

One thing I think is worth fixing before this lands:

The carry cannot tell "index has not read this head yet" from "index read it and the check is not a fork guard" β€” and it is self-sustaining. stageForkGuard returns nil in both cases (src/pkg/github/automerge/automerge_stage_sharedci.go:59-64; ForkGuardChecksFor returns nil when the excerpt does not match, src/pkg/github/fork_guard.go:43-62). The carry at src/pkg/github/automerge/automerge_stage_labels.go:520-523 fires on len(obs.ForkGuardChecks) == 0, and ForkGuardStage then rewrites the record's reason to fork-guard:<check> (src/pkg/stageengine/derive_pr_classify.go:765 via ForkGuardReason), so next tick carriedForkGuard (automerge_fork_guard_carry.go:60-72) matches again. Consequence: once a fork PR has ever parked on fork-guard:Canary, any later head where a check named Canary is red for a real reason (the maintainer's exact-head run was dispatched and genuinely failed, with a non-fork annotation) still reads as fork-guard:Canary β€” the PR stays at 085 asking a maintainer to "run it for head X" they already ran, and the author is never handed the failure. On utah-packages today the stub annotation never changes so this is latent, not observed; but the detector is generic across repos. Suggested fix: let the policy signal presence (e.g. ForkGuard returns (checks, read bool) or a separate "head indexed" lookup) and carry only while the head is unread. The existing TestForkGuardCarriesAcrossHeadsWithoutNudge would then want a fourth case: indexed head, Canary red, excerpt not a guard β†’ 072 + nudge.

Minor, no action required: updateBranchAndSkip (automerge_sweep_trusted.go:887-894) consults only the per-head index, which by this PR's own account lags a new head by one enumeration. So the very first tick after a new head can still update the branch once before the skip engages. Carrying through carriedForkGuard there would need the observation, and you have a stated reason for not reading the record in that path, so I only note it.

Docs row and changelog fragment match the behaviour change. No duplicate in the open queue touches these files.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit c1a79e5 into hivecommons:v6 Nov 5, 2026
67 of 68 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @Danathar holds role owner and GitHub permission maintain on repo; CI green at f044fc6.

hivecommons-hive Bot added a commit that referenced this pull request Nov 9, 2026
#17373)

A fork PR parked at 085 on a fork-guarded check (the fork Canary) keeps its
park across new heads since #16814, but the entry comment was written once
per stage visit and never for a new head within it. On
projectbluefin/utah-packages#917 the maintainer's Canary passed on 8d7a655,
the author rebased the byte-identical patch onto a newer main (82ef790),
and the comment still asked for a run on an earlier head.

The comment is now rewritten in place (no notification) for each new head
while the fork-guard park stands, and the ask says a run on an earlier head
does not cover this one even with the same patch, because a rebase or a
merge of the base changes the code the check runs. Whether an earlier run
carries over stays the repository's decision (its Canary workflow); the
hive does not carry it.


Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

Signed-off-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: hivecommons-hive[bot] <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant