Skip to content

πŸ› Bound review-slot handoff for active base preparation heads - #15886

Merged
clubanderson merged 4 commits into
v5from
fix/preparation-owner-review-handoff
Oct 30, 2026
Merged

clubanderson merged 4 commits into
v5from
fix/preparation-owner-review-handoff

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Problem and verified runtime evidence

Fixes #15883. Focused runtime follow-up to #15836; not a new reviewer engine or merge-train policy.

At 20:22Z on 2026-10-30, durable trusted-author preparation owner #15868 received one accepted refresh to 8b9884135e2366741efc63cbf9a2c906ed3d8a59, surviving the 20:26 binary roll. By 20:36 its required CI passed, but the refreshed exact head owed review (review-gate:no-review-bundle / contributor-lane:no-verdict). At 20:39:55 the planner reported no-free-reviewer for it and fourteen others while four review kicks went elsewhere. It subsequently merged at 20:46:06Z, releasing ownership at 20:46:14.509, with #15851 front by 20:46:19: this was a long convoy, not permanent deadlock.

Design

  • Reuse existing review dispatch priority bands, three-cycle starvation promotion, normal reviewer/model/author exclusions, parallel budgets and confirmed dispatch history.
  • Give the active, unexpired durable preparation owner's exact current CI-green/mergeable head that still owes a verdict bounded next-slot preference (base-preparation), without requiring a ready-only train seat. Normal planner admission remains authoritative.
  • Validate live PR terminal gates and recorded identity outside preparation locks; a refresh head needs both exact attempted merge parents and the existing fail-closed same-patch proof against the immutable attempted base SHA. An author push/amended merge cannot inherit priority. Recheck persisted ownership/attempt after remote reads to reject release races.
  • After confirmed owner service, an existing aged, non-pending waiter gets base-preparation-fairness precedence. Only confirmed aged service clears that obligation; unrelated deliveries do not. This survives restarts through the existing dispatch history, and planned/undelivered kicks consume no turn. Free incompatible slots can still serve others; valid busy reviews are never interrupted.
  • Observe once per canonical repo/base per planning pass, outside critical sections. No-owner/policy-off behavior remains unchanged.
  • Provide a tiny shared, network-free Engine.BasePreparationSnapshot over the same read-only state reader/hash/decode: copied original owner/waiter tickets, expiry timestamps, explicit missing/empty/unavailable distinction. This is persisted lifecycle evidence, not live readiness or merge eligibility. UI/orchestration agents may explicitly cherry-pick only shared commits b1834c4b0cd17d876cd1c180a4b6cd6166e87264 and 0bc72451b759a4e1001ba58e2ffb0ee4c4d6de1d; neither full implementation depends on another unmerged PR. No UI or orchestration policy is changed here.

Gates and limits

No CI, DCO, hold, authorization, labels, trust, current-head review or current-base requirement is weakened; no approval is carried by this change. Preparation remains outside ready merge-train seats and already fully eligible successors retain the #15836 bypass. No preemption, reviewer/pool increase, memory/recycle/configuration/rules change, native-queue activation, deployment or merge is performed. Priority cannot create unavailable compatible review capacity or prevent human/external base changes.

Regression coverage and review

  • Actual convoy: owner outranks a CI-green sibling/aged waiter for one free slot, binds the refreshed exact head despite an old-head bundle, and does not interrupt busy valid reviews.
  • Confirmed-vs-undelivered service, successive owners/aged fairness, unrelated delivery and equal-timestamp batch ordering, default/pending-CI behavior.
  • Planner wiring: no owner, policy off, pending/running CI, changed head, label admission, exact current bundle versus stale bundle, one observation per destination.
  • Persisted owner lifecycle/restart: admitted/refreshed, author push, amended merge, wrong base parent, held/closed/retargeted/expired/released, concurrent release, unreadable state; raw copies and missing/empty/error/read-only behavior.
  • Independent code review completed; addressed both findings (parent-only identity proof and unrelated-delivery fairness reset) before the final implementation commit.
  • gofmt and git diff --check completed. No local Go suites/build/vet/lint/docs guards run per AGENTS. CI is the sole verdict; latest-head results will be updated here.

Rollout / audit

Requires the changed Hive binary; no rollout performed. Existing review swarm kick planned exposes priority=base-preparation / priority=base-preparation-fairness; priority summaries include both. review preparation observation unavailable explicitly records read/proof errors; ordinary no-free-reviewer / no-parallel-slot diagnostics and preparation selection/release logs remain authoritative.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 30, 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 hanthor 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/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Oct 30, 2026
@clubanderson

Copy link
Copy Markdown
Member Author

Additional authoritative runtime evidence reported by the parent at ~21:01Z: next durable preparation owner #15851, exact head 483c323fbb94171fb6cc9c1cbc053933f5e03f01, has all required checks SUCCESS (gh pr checks --required). At 2026-10-30T21:00:15.390474204Z its self-authored sweep still held with no-review-bundle. The 20:54:06 review plan recorded no-free-reviewer for it while five assignments went to #15871 (three perspectives), #15819 and #15880. At least ten preparation waiters were observed at 20:58–21:00. This independently reproduces the second-owner convoy and reinforces this bounded-priority scope; no gate bypass or extra source scope is needed.

Implementation head: d8716ebdb7311119919ddd399a584b3ef8d7dc28. CI has started; DCO currently SUCCESS and other jobs queued/running (not failures). No deployment/merge performed.

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#15885 ✨ Add integration-aware orchestration above preparation and native queues same files src/cmd/hive/main_sweeps.go
src/pkg/github/automerge/base_preparation_snapshot.go
src/pkg/github/automerge/base_preparation_snapshot_test.go
src/pkg/github/automerge/base_preparation_store.go
#15887 πŸ› Show current preparation backlog without fabricating a ready train same files src/pkg/github/automerge/base_preparation_snapshot.go
src/pkg/github/automerge/base_preparation_snapshot_test.go
src/pkg/github/automerge/base_preparation_store.go
#15748 πŸ› [reviewer] park PRs at 085 Needs decision when the fixer exhausted its attempts same files src/cmd/hive/main_sweeps.go
src/docs/hive-merge.md
#15879 πŸ› fix: create base-preparation state files without group write same files src/pkg/github/automerge/base_preparation_store.go
#15876 πŸ› Fold hive PR notes into one edited status comment and stop no-findings review spam same files src/cmd/hive/main_sweeps.go

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • build-and-test

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Another agent tried to open a PR from scanner/fix-15883, but this PR already closes #15883. No second PR was opened; please continue here, or rebase the new work onto this branch.

@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 tree, not just the diff. Looks correct to me; notes for the maintainer below.

What I verified

  • base_preparation_store.go: the new lock-free ownerSnapshot on the file-backed path is safe because change() still writes to path+".next" and os.Renames over path+".json", so a reader never sees a torn file. In-memory path copies Waiting before it escapes the lock.
  • base_preparation_observation.go: a head that differs from the admitted head is only accepted when it is a two-parent merge of exactly Attempt.Head+Attempt.Base and ReviewHeadsSamePatch agrees; a transport without that method fails closed. The second ownerSnapshot after the GitHub reads catches concurrent release.
  • review_preparation.go: reviewPreparationObserver builds a fresh automerge.New(...), which I confirmed reads the same process-wide store as the sweep (automerge_base_preparation.go:25 sharedBasePreparation, :39-44 preparationStore()), so the observation is not inert in production.
  • priority_order.go: the yield band is only populated when a preparation owner is present and a starved PR exists, so the toggle cannot push a non-starved PR ahead; lastReviewWasPreparation reads confirmed Recent (pruned by pruneRecentReviews), and same-batch prep+yield confirmations cancel as the comment says.

Relationship to #15887 β€” not a duplicate, but worth knowing: both PRs carry the same two groundwork commits (base_preparation_snapshot.go, base_preparation_snapshot_test.go, and the base_preparation_store.go refactor are byte-identical across the two heads), then diverge into different consumers (review-slot ordering here, Activity Monitor backlog there). Whichever lands second will merge cleanly against the shared files; it just needs its CI rerun on the new base.

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

@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 tree at e229634, built ./cmd/hive ./pkg/review ./pkg/github/automerge clean. Looks correct to me; no defects found.

What I verified:

  • Lockless snapshot reads are safe. BasePreparationStore.ownerSnapshot (base_preparation_store.go:98-123) reads <key>.json without the flock, but change writes via .next + os.Rename (base_preparation_store.go:167-185), so a reader sees either the old or the new complete file, never a torn one. A decode error is surfaced as unavailable (BasePreparationSnapshot returns err, ActiveBasePreparation returns err), not as "queue empty" β€” matching the doc comment at base_preparation_snapshot.go:29-30.
  • Fail-closed on refreshed heads. ActiveBasePreparation (base_preparation_observation.go:57-77) requires the live head to be a 2-parent merge of exactly Attempt.Head Γ— Attempt.Base and passes ReviewHeadsSamePatch. The production transport is *github.Client, which implements it (src/pkg/github/review_head_move.go:73), so the !ok branch cannot silently disable priority in prod; the re-read at :79-86 rejects a release race.
  • Ordering. orderByReviewPriority (priority_order.go:41-81) only puts a PR in the preparation band when PreparationOwner && MergeReady && !CIPending, and main_sweeps.go:2455-2457 already requires the same plus reviewPreparationOwesVerdict. The yield band fires only when a preparation owner is present in the same pass and lastReviewWasPreparation is true, so with no owner the pre-#15823 order is unchanged. RecentReview.Priority is carried through ConfirmDelivered β†’ upsertRecentReview (dispatch.go:1680), so the yield obligation survives restarts as the body says.
  • Overlap with #15887. base_preparation_snapshot.go, its test, and base_preparation_store.go are byte-identical in both PRs (same sha1 for all three), and git merge-tree of the two heads reports zero conflicts. The conflicts-with-open-pr label on #15887 is a false alarm for this pair: whichever lands first, the other rebases to a no-op on those files.

One suggestion, not a defect: lastReviewWasPreparation reads plan.State.Recent, which pruneRecentReviews trims at RecentDispatchTTL. If a preparation kick is confirmed and no starved waiter appears before the TTL expires, the fairness obligation is forgotten. Bounded and probably intended, but worth a sentence in priority_order.go:88-90 so the next reader doesn't think it is durable forever.

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

@clubanderson
clubanderson merged commit f2156dd into v5 Oct 30, 2026
73 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the fix/preparation-owner-review-handoff branch October 30, 2026 21:33
@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@clubanderson

Copy link
Copy Markdown
Member Author

Verified source merge / CI receipt

Owner explicitly authorized administrative source merge at 2026-10-30T21:04:15Z after green immutable-head CI, without waiting for another Hive review bundle. No approval labels or quality checks were manipulated.

Source only: postmerge image-publication workflow was still pending at verification; runtime rollout remains the owner's action. No deployment, live settings, pool, memory/recycle, rules/labels, or native activation changed. Local/remote feature branch and owned clean worktree removed; origin/v5 refreshed.

Audit review swarm kick planned for priority=base-preparation / priority=base-preparation-fairness. Capacity exhaustion remains an honest wait, and an unverified refreshed-head proof falls back to normal priority rather than carrying approval or bypassing any gate.

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/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

πŸ› Give the active base-preparation head bounded review-slot service

1 participant