Skip to content
Merged
1 change: 1 addition & 0 deletions changelog.d/fixed-readiness-first-preparation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Allow independently proven, CI-ready pull requests to prepare past a completed refresh awaiting CI, without displacing unresolved mutations or bypassing dependency, review, fresh-base, or serialized-merge gates.
52 changes: 52 additions & 0 deletions docs/readiness-preparation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Readiness-first preparation

Preparation admission is not merge approval. A caller must pass its normal
lane gates on the exact head before requesting a base refresh. An unresolved
refresh, ambiguous mutation outcome, or active repair retains exclusive
preparation ownership.

A completed refresh can yield while its new head has a known pending CI or
review verdict.
Observed `status-pending`/`check-pending` on an explicitly unprotected base
is a known pending verdict too; missing required contexts, absent evidence,
stale conclusions and failed API reads cannot establish readiness.
Configured fallback requirements do not establish the authoritative required
set for overtaking; ordinary merge-gate fallback behavior is unchanged.
Completion requires a changed live head containing both the pinned
pre-refresh head and the authoritative refresh-target base commit. Legacy
attempts without authoritative base evidence remain exclusive. The former
owner keeps its ticket, original priority, and head/base attempt deduplication;
pending CI/review observations do not erase that ticket or trigger another
refresh. Once ready, it cannot be overtaken by another caller.

Overtaking requires complete changed-file evidence, including rename sources,
disjoint closing claims, explicit native issue dependency summaries reporting
no open blockers, and divergent head ancestry. An extra unclassified reference,
shared claim, supersession, stacked head, incomplete pagination, changed
metadata, missing required evidence, or failed read preserves FIFO. File
disjointness alone is not independence. This is a conservative rule using
repository-declared relationships, not semantic inference across packages.
At most three predecessors are checked for overtaking in one admission;
larger or ambiguous fronts retain FIFO instead of spending unbounded API work.

Final sweep admission and merge calls share a per-repository/base guard with
the GitHub merge-request relay. Production uses stable flock inodes under
`/data/destination-merges`, shared by writers using the same durable volume;
isolated test engines use process-local locks. Across sweep lanes, contention returns
`base-preparation:merge-guard` with `ErrDestinationMergeBusy`, not a `fetch-pr`
failure; the caller retries on a later sweep rather than retaining stale
evidence while waiting. Unrelated fetch failures keep their existing reasons.
Locks are released on return or process death, and retargeting cannot borrow another
destination's lease. No new parallel merge dispatch is introduced.

The guard serializes Hive writers sharing that volume, not independent human
or external GitHub clients. GitHub still performs atomic protected-base
updates and enforces configured checks. Its REST merge API has an expected
head condition, not an expected base condition: universal serialization
against external writers requires server-side up-to-date protection or a
merge queue. This change does not alter those policies.

Budgets, runner concurrency, review authority, merge methods, and sweep cadence
are unchanged. Admission reads remain paced by existing GitHub API controls.
Fixtures and CI can establish correctness, but deployed before/after
PR-to-merge measurements are still required to establish latency improvement.
1 change: 1 addition & 0 deletions src/cmd/hive/boot_agents_deps.go
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ func defaultBootAgentsDeps() bootAgentsDeps {
github.StartTokenAccessAuditWatcher(ctx, logger)
},
startRequestRelays: func(ctx context.Context, c *github.Client, r requestRelays) <-chan struct{} {
github.ConfigureDestinationMerges(automerge.DefaultDestinationMergeDirectory())
if r.mergePolicy != nil {
c.SetMergeRequestPolicyGate(r.mergePolicy(c))
}
Expand Down
18 changes: 12 additions & 6 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,17 +417,23 @@ existing mutation-reconciliation TTL it can retry only with an authoritative,
still-identical head and the API's expected-head guard. Accepted updates must
complete their normal current-head gates; no approval is transferred.
Release occurs on merge, closed/missing/retargeted/draft/conflicting/held heads,
failed checks, rejected review, or lost admission. Expected pending CI/review
keeps ownership, bounded by the existing review-pending dwell (its default when
stall detection is disabled), so a genuinely hung owner yields to successors.
Waiting tickets are removed when their head changes or stops qualifying.
failed checks, rejected review, or lost admission. An unresolved refresh or active
repair keeps exclusive ownership. A completed refresh whose new head has known
pending CI/review can yield to an independently ready successor under the
[readiness-first preparation gates](../../docs/readiness-preparation.md); the
former owner retains its ticket, original priority and attempt deduplication.
Pending ownership remains bounded by the existing review-pending dwell (its
default when stall detection is disabled), so a genuinely hung owner yields to
successors.
Ordinary waiting tickets are removed when their head changes or stops qualifying;
yielded owners retain their tickets through pending CI/review observations.
Admission provenance prevents a different lane's non-admission from revoking
the owning lane's reservation or FIFO ticket. An old waiting ticket reserves
order only: its head must qualify afresh in its lane before becoming owner.

Audit logs use `automerge base preparation selected`, `refresh claimed`,
`waiting` and `released`, with repository, base, PR, head/base SHA where relevant,
and release/skip reason. `automerge update-branch` and the sweep's
`waiting`, `released` and `completed owner yielded`, with repository, base, PR,
head/base SHA where relevant, and release/skip reason. `automerge update-branch` and the sweep's
`updated_branches` count actual successful refresh effects; queued/preparing
reasons do not consume the branch-update budget. Ready-only train seating and
reviewer dispatch scheduling are separate policies.
Expand Down
7 changes: 6 additions & 1 deletion src/pkg/dashboard/api_repo_item_decision_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ type repoItemDecisionMock struct {
prNoMaintainerEdits bool
workflowPath string
prMergeState string
prHeadSHA string
updates int
prRedCI bool
prNoCI bool
Expand Down Expand Up @@ -151,8 +152,12 @@ func newRepoItemDecisionServer(t *testing.T, m *repoItemDecisionMock) *Server {
if m.prFork {
headRepo = "someone/testrepo"
}
headSHA := m.prHeadSHA
if headSHA == "" {
headSHA = "feedfacefeedfacefeedfacefeedfacefeedface"
}
_ = json.NewEncoder(w).Encode(map[string]any{"number": n, "state": "open", "body": m.prBody, "labels": prLabels, "user": author, "mergeable": mergeState != "dirty", "mergeable_state": mergeState, "maintainer_can_modify": !m.prNoMaintainerEdits,
"head": map[string]any{"sha": "feedfacefeedfacefeedfacefeedfacefeedface", "repo": map[string]any{"full_name": headRepo}},
"head": map[string]any{"sha": headSHA, "repo": map[string]any{"full_name": headRepo}},
"base": map[string]any{"ref": "main", "repo": map[string]any{"full_name": "testorg/testrepo"}}})
case r.Method == http.MethodGet && strings.Contains(path, "/compare/"):
files := []map[string]string{}
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/rebase_merge_followthrough_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ func TestRepoItemDecisionMergeNowOnDirtyPRArmsRebaseThenMerge(t *testing.T) {
// fails with the files and the two options, and the PR gets the note.
func TestDriveRebaseMergeGreenMergesAndConflictFails(t *testing.T) {
store := useRebaseMergeStore(t)
mock := &repoItemDecisionMock{prForeign: true, commitBy: map[string]string{"0123456789abcdef0123456789abcdef01234567": "hive[bot]"}}
mock := &repoItemDecisionMock{prForeign: true, prHeadSHA: "0123456789abcdef0123456789abcdef01234567", commitBy: map[string]string{"0123456789abcdef0123456789abcdef01234567": "hive[bot]"}}
srv := newRepoItemDecisionServer(t, mock)
srv.operatorActionStore = newOperatorActionStore(filepath.Join(t.TempDir(), "ops.json"))
now := time.Date(2026, 10, 29, 9, 0, 0, 0, time.UTC)
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/github/automerge/automerge_adoption_recovery_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,11 @@ func TestAdoptedRecoveryPreparationWaitDoesNotConsumeAttempt(t *testing.T) {
h.e.basePreparation = NewBasePreparationStore("")
h.adopt.compareBehind = 2
h.adopt.baseChecks = map[string]string{"coverage": "success"}
h.adopt.superseders[7] = map[string]any{
"number": 7, "state": "open",
"head": map[string]string{"sha": "aaa"},
"base": map[string]string{"ref": "v5", "sha": "base1"},
}
front, head, wantReason := 8, "head8", preparationQueued(8)
if duplicate {
front, head, wantReason = 7, "aaa", basePreparationReady
Expand Down
90 changes: 80 additions & 10 deletions src/pkg/github/automerge/automerge_base_preparation.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,13 @@ func (c *Engine) preparationInvalid(ctx context.Context, owner, repo, base strin
if err != nil {
return "", err
}
if why := c.preparationInvalidPR(pr, base, repair); why != "" {
return why, nil
}
if expectedHead != "" && pr.GetHead().GetSHA() != expectedHead {
return "head-changed-before-preparation", nil
}
return c.preparationInvalidPR(pr, base, repair), nil
return "", nil
}

func (c *Engine) preparationInvalidPR(pr *gh.PullRequest, base string, repair bool) string {
Expand Down Expand Up @@ -99,6 +102,7 @@ func preparationQueued(front int) string {
// durable owner is not a ready merge-train seat.
func (c *Engine) admitBasePreparation(ctx context.Context, owner, repo, base string, number int, head, lane string, repair bool) (string, error) {
reason := ""
yieldedOwner := preparationCandidate{}
now := c.now()
key := preparationKey(owner, repo, base)
err := c.preparationStore().change(key, func(st *basePreparation) error {
Expand All @@ -125,24 +129,66 @@ func (c *Engine) admitBasePreparation(ctx context.Context, owner, repo, base str
} else {
st.Waiting[i].Head = head
}
candidate, _, err := c.gh.PullRequests.Get(ctx, owner, repo, number)
if err != nil {
return err
}
if candidate.GetHead().GetSHA() != head || c.preparationInvalidPR(candidate, base, repair) != "" {
reason = basePreparationPrefix + "snapshot-changed"
return nil
}
var yielded preparationCandidate
if st.Owner.Number != 0 {
front, _, err := c.gh.PullRequests.Get(ctx, owner, repo, st.Owner.Number)
if err != nil {
return err
}
if st.Owner.Repair || repair || !c.preparationCompleted(ctx, owner, repo, front, st.Attempts[st.Owner.Number]) ||
!c.preparationMayPass(ctx, owner, repo, base, candidate, front, lane, st.Owner.Lane) {
reason = preparationQueued(st.Owner.Number)
return nil
}
yielded = st.Owner
ticket := yielded
ticket.Head = front.GetHead().GetSHA()
ticket.Yielded = true
st.Waiting = append([]preparationCandidate{ticket}, st.Waiting...)
st.Owner = preparationCandidate{}
}
if st.Owner.Number == 0 {
for len(st.Waiting) > 0 {
next := st.Waiting[0]
passed := 0
for index := 0; index < len(st.Waiting); {
next := st.Waiting[index]
why, err := c.preparationInvalid(ctx, owner, repo, base, next.Number, next.Head, next.Repair)
if err != nil {
return err
}
if why != "" || now.Sub(next.Since) >= c.preparationWindow() {
st.Waiting = st.Waiting[1:]
if why == "head-changed-before-preparation" && next.Yielded {
reason = preparationQueued(next.Number)
break
}
if why != "" || (!next.Yielded && now.Sub(next.Since) >= c.preparationWindow()) {
st.Waiting = slices.Delete(st.Waiting, index, index+1)
continue
}
if next.Number != number {
// Only the caller has just passed its lane's gates.
// Never turn an old FIFO ticket into a sticky owner.
if passed >= preparationMaxPredecessors {
reason = preparationQueued(next.Number)
break
}
front, _, err := c.gh.PullRequests.Get(ctx, owner, repo, next.Number)
if err != nil {
return err
}
if !repair && !next.Repair && c.preparationMayPass(ctx, owner, repo, base, candidate, front, lane, next.Lane) {
passed++
index++
continue
}
reason = preparationQueued(next.Number)
break
}
st.Waiting = st.Waiting[1:]
st.Waiting = slices.Delete(st.Waiting, index, index+1)
next.Since = now
next.Lane = lane
next.Repair = repair
Expand All @@ -151,6 +197,14 @@ func (c *Engine) admitBasePreparation(ctx context.Context, owner, repo, base str
break
}
}
if yielded.Number != 0 && st.Owner.Number != number {
// A later ambiguous predecessor prevented admission; do not
// relinquish a completed owner's durable priority for nothing.
st.Owner = yielded
st.Waiting = slices.DeleteFunc(st.Waiting, func(w preparationCandidate) bool { return w.Number == yielded.Number })
} else if yielded.Number != 0 {
yieldedOwner = yielded
}
if st.Owner.Number != number {
if reason == "" {
reason = preparationQueued(st.Owner.Number)
Expand All @@ -163,6 +217,9 @@ func (c *Engine) admitBasePreparation(ctx context.Context, owner, repo, base str
}
return nil
})
if err == nil && yieldedOwner.Number != 0 {
c.info("automerge base preparation completed owner yielded", "repo", owner+"/"+repo, "base", base, "pr", number, "head", head, "former_owner", yieldedOwner.Number, "former_since", yieldedOwner.Since)
}
return reason, err
}

Expand All @@ -175,7 +232,12 @@ func (c *Engine) claimBasePreparationUpdate(ctx context.Context, owner, repo str
if err != nil {
return err
}
base, baseSHA := pr.GetBase().GetRef(), pr.GetBase().GetSHA()
base := pr.GetBase().GetRef()
branch, _, err := c.gh.Repositories.GetBranch(ctx, owner, repo, base, 0)
if err != nil {
return err
}
baseSHA := branch.GetCommit().GetSHA()
if head == "" || pr.GetHead().GetSHA() != head || base == "" || baseSHA == "" {
return &preparationWait{basePreparationPrefix + "snapshot-changed"}
}
Expand All @@ -197,7 +259,7 @@ func (c *Engine) claimBasePreparationUpdate(ctx context.Context, owner, repo str
wait = basePreparationReady
return nil
}
st.Attempts[number] = preparationAttempt{Head: head, Base: baseSHA, At: c.now()}
st.Attempts[number] = preparationAttempt{Head: head, Base: baseSHA, At: c.now(), AuthoritativeBase: true}
c.info("automerge base preparation refresh claimed", "repo", owner+"/"+repo, "base", base, "pr", number, "head", head, "base_sha", baseSHA)
return nil
})
Expand Down Expand Up @@ -259,7 +321,15 @@ func (c *Engine) observeBasePreparation(lane, owner, repo string, pr *gh.PullReq
}
// Waiting is not preparation yet: a changed or now-pending waiting
// head loses its admission ticket and must qualify again.
for i := range st.Waiting {
if st.Waiting[i].Yielded && st.Waiting[i].Number == pr.GetNumber() && keep {
st.Waiting[i].Head = pr.GetHead().GetSHA()
}
}
st.Waiting = slices.DeleteFunc(st.Waiting, func(w preparationCandidate) bool {
if w.Yielded && keep && !merged {
return false
}
return w.Lane == lane && w.Number == pr.GetNumber() && (w.Head != pr.GetHead().GetSHA() || !strings.HasPrefix(reason, basePreparationPrefix))
})
if !keep && st.Owner.Lane == lane && st.Owner.Number == pr.GetNumber() {
Expand Down
Loading
Loading