Repository navigation
π fix(fork-guard): keep a fork PR waiting on a maintainer-run check with the maintainer across heads - #16814
Conversation
β¦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>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
There was a problem hiding this comment.
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, β¦):
- index β
nil; 2. record still saysfork-guard:Canary(written by the previous carry); 3. lane reason isrequired-check-failing:Canaryβ carry fires again; 4.ForkGuardStagere-recordsfork-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-67returnsnilonly 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
|
Hive status β updated in place; edits do not notify. Full history is in the Activity Monitor. Review findings from Correctness review (head 1. The carried guard is self-sustaining: once a PR is recorded
So after the first carried observation writes the record with reason The PR body notes this exact hazard for 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 2. Body claim "All automerge update paths go through this function" is not quite true. (low)
|
There was a problem hiding this comment.
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
#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>
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: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)
stage 085-needs-decision reason fork-guard:Canaryautomerge update-branch reason=behindβ hive merge commit 08b9e69stage 072-returned-to-contributor reason required-check-failing:Canary(no fork-guard entry for the new head yet)contributor nudged β¦ reason required-check-failing:CanaryCanaryrefuses pull requests from a fork, so neither the author nor the hive can turn it green"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
fork-guard:<check>; no nudgebehindthe baserequired-check-failing:<check>abc1234as the repository requires)"How
automerge_fork_guard_carry.go(new):carriedForkGuardreads the stage record'sfork-guard:<checks>reason. It applies when the head is from a fork and the lane's red check (required-check-failing:,check-failing:oroptional-check-failing:) is one of those checks.ForkGuardStagestill 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 sameForkGuardChecks.updateBranchAndSkip: a fork head whose index shows a fork-guarded check is not updated. All automerge update paths go through this function.stagelabels/human.go: the fork-guard ask names the head (ShortSHA).Tests
TestForkGuardCarriesAcrossHeadsWithoutNudgeApplyStageLabels: indexed head β 085; new unindexed head β 085, no nudge; other red check β 072 + nudgeTestLaneRedCheckAndCarriedForkGuardTestUpdateBranchSkipsForkGuardedHeadTestRouteHumanForkGuard(updated)go testautomerge, stagelabels, stageengine/..., github, writebackcheck-docs-citations.py src/docs, writeback ratchet, gofmt, vetNotes
fork_guard.go). No new config key is needed for these repos, because the Canary annotation already matches.mergelane) is untouched; a fork-guarded PR is "left out of every train" (needs-decision).origin/v6..origin/v5has nothing in these files.π€ Generated with Claude Code
https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1