Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-adoption-close-first.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Supersede adoption is close-first: the hive closes the contributor's original in the same pass that opens its copy (one note naming the copy and why, `hive/superseded`), so an issue never shows two active PRs; a copy that is closed unmerged or red at two heads reopens the original (`adoption-copy-failed`, at most once per 24h). `governor.labels.stage.adoption.supersede.close_first: false` keeps the original open until the copy merges (#15135).
1 change: 1 addition & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy
AdoptionStrictAttribution: stage.Adoption.StrictAttributionEnabled(),
AdoptionAutoMerge: stage.Adoption.AutoMergeEnabled(),
AdoptionMaintainerPolicy: stage.Adoption.EffectiveMaintainerPolicy(),
AdoptSupersedeCloseFirst: stage.Adoption.Supersede.CloseFirstEnabled(),
HiveID: cfg.HiveID,
AuthorKindLabels: cfg.Governor.Labels.Author.Names(),
RelayKnown: contributorRelayKnown,
Expand Down
4 changes: 2 additions & 2 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -682,7 +682,7 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p

**Adoption pill (072).** A nudged `author/clanker` pull request at `stage/072-returned-to-contributor` carries `adoption{author, due, blocked_by, since, nudges, author_online, author_registered, author_last_seen, author_maintainer, policy, action, text}` — the nudge count and first-nudge time from the stage record, the author's live hub presence (the same lookup the contributor-offline adoption itself consults), and, when the adoption engine judged adoption due and held it, why (`blocked_by: author-is-maintainer`). The row's caption and an amber pill say it in plain words instead of a bare "Returned to contributor": `waiting on @hanthor (maintainer, offline 26h) — adopt?` under `governor.labels.stage.adoption.maintainer_policy: ask`, `waiting on @zoe (offline 40m, 2 nudges)` while the default `adopt` policy's clock runs, `… — not adopted: maintainer_policy is never` under `never` ([hivecommons/hive#14524](https://github.com/hivecommons/hive/pull/14524): the PR sat 26h at 072 with its author's hive gone and nothing on screen saying why). When `action` is `decide:adopt` the row also carries `decision_needed` (question "@hanthor maintains this repository and has been offline for 26h; adopt the PR?", `blocker_reason: adoption:author-is-maintainer`, options Adopt then Hold/Release), so the lit 072 chevron and the `adopt?` pill open the Needs-human popover, and the row menu and the selection bar offer **Adopt (hive takes over)** — same action-id vocabulary as the other `decide:*` entries — which, after an in-app confirm, POSTs `{"decision":"adopt"}` to the item's decision endpoint: the hive posts an attributed note, sets `adoption/supersede` (the owner-delegate's request label) and the next sweep adopts the head on the existing adopt/supersede path; the toast reads `adoption-queued`. Write access required; the action is absent when nothing is the owner's to decide.

**Adopted → #N (074 / 085).** An adopted pull request names the hive's superseding copy in its detour word (`adopted_by`). When that copy was closed without merging (hivecommons/hive#15052) the row does not fall back to *Needs human decision*: `adopted_by_state: "closed"` renders "Adopted → #N (closed) · recovering" while the hive opens a fresh copy from the same head, and the caption says so in plain words; once the new copy is on record the word reads "Adopted → #M". If two copies are closed within an hour the hive stops (`adopted_by_state: "closed-twice"`, park reason `adoption-child-closed-twice`): the row reads "Adopted → #N (closed twice) · needs a person" and the popover question asks you to reopen the last copy, give direction, or close the PR.
**Adopted → #N (074 / 085).** An adopted pull request names the hive's superseding copy in its detour word (`adopted_by`). When that copy was closed without merging (hivecommons/hive#15052) the row does not fall back to *Needs human decision*: `adopted_by_state: "closed"` renders "Adopted → #N (closed) · recovering" while the hive opens a fresh copy from the same head, and the caption says so in plain words; once the new copy is on record the word reads "Adopted → #M". If two copies are closed within an hour the hive stops (`adopted_by_state: "closed-twice"`, park reason `adoption-child-closed-twice`): the row reads "Adopted → #N (closed twice) · needs a person" and the popover question asks you to reopen the last copy, give direction, or close the PR. With close-first supersession (the default, hivecommons/hive#15135) the original is closed in the adopting pass and has **no row** while its copy is open — the copy is the one active PR for the issue, and the original's record is superseded (no chevron, no *Needs human decision*). A copy that then fails (closed unmerged, or red at two heads) reopens the original: `adopted_by_state: "copy-failed"` renders "Adopted → #N (copy failed) · reopened, needs a person" at 085 with the caption "The hive's copy #N failed; this PR was reopened and needs a person".

**Blocked pill.** An issue wearing `blocked` because the hive parked it on a pull request — its body carries `<!-- hive:blocked-on pr=owner/repo#N -->` (the review backlog's spin-off issues, `hive-open-issue comment --blocked-on-pr`) — names that PR: the payload carries `blocked_on_pr: {repo, number, url, state}`, the pill reads `blocked on #N` and links to the PR, its tooltip says `Blocked on PR owner/repo#N (open) — lifts when it merges; re-triage if closed unmerged`, the caption reads `Blocked on PR #N — lifts when it merges` instead of `No stage recorded yet`, and the row's title and chevron tooltip carry the blocker too ([#14952](https://github.com/hivecommons/hive/issues/14952): #14863 showed a bare grey pill and "blocked · since 7h" with nothing to say what it waited on). The state (`open`, `merged`, `closed`, or absent when nothing knows) comes only from what the hive already holds — the status snapshot's open PRs, the ForgeState cache, the recent-merge ring — never a GitHub call from the tracker build; a merged or closed-unmerged blocker says so (`merged; the blocked sweep lifts the label next` / `closed unmerged; the blocked sweep re-triages it next`). The server reads the marker from the issue body when it has one, else from the enumeration's `blocked on owner/repo#N` reason, so sidelined rows (which carry only the reason) name it too. A `blocked` issue with neither (a human-applied label) keeps the bare pill. This is distinct from `blocked_on`, the open GitHub "blocked by" dependencies of a sequenced sub-issue ([#14765](https://github.com/hivecommons/hive/issues/14765)); when a row has both, the chevron tooltip lists them together.

Expand Down Expand Up @@ -769,7 +769,7 @@ The glyph is drawn for **every** row on the gate, so two rows in the same state

**Setting.** `decisions.delegate.enabled` (default **true** — the same default as the other "let the hive do it" switches); `decisions.delegate.repos.<owner/repo>.enabled` (or the bare repository name) overrides per repository. `decisions.delegate.llm.enabled` (default **false**) adds the LLM step described below. `decisions.delegate.effect_timeout` (default **30m**, a Go duration) is how long a recorded decision may go without its expected effect before a repeat click reports it as stuck. When the delegate is off the menu entry stays visible but the endpoint answers 403 naming the setting. See [operator-reference.md](operator-reference.md).

**Orphaned adoption.** A PR the hive adopted in supersede mode whose hive copy was closed unmerged is not "already decided": the delegate detects the dead `superseded_by`, re-runs the adoption (a fresh copy from the same head, a new `hive:adopted` marker) and answers *applied* with "Re-adopting: hive's earlier copy #N was closed by mistake; opening a fresh copy." If copies were closed twice within an hour (`adoption-child-closed-twice`) it keeps the park and recommends a person decide rather than opening a third copy.
**Orphaned adoption.** (Keep-open supersession, `close_first: false`; a close-first original whose copy closed is reopened by the lane instead, see above.) A PR the hive adopted in supersede mode whose hive copy was closed unmerged is not "already decided": the delegate detects the dead `superseded_by`, re-runs the adoption (a fresh copy from the same head, a new `hive:adopted` marker) and answers *applied* with "Re-adopting: hive's earlier copy #N was closed by mistake; opening a fresh copy." If copies were closed twice within an hour (`adoption-child-closed-twice`) it keeps the park and recommends a person decide rather than opening a third copy.

**What this release decides mechanically.** The decider is rules-first: the cases above that are mechanically decidable (dedupe, owner-only, flaky, CI ratchet, design proposal, review backlog, contributor-offline, sentinel-trusted, small-low-risk, reporter-trust, hive-policy) are decided from the item itself; anything else falls to the reversible default (approve direction on an issue; release a green hive PR; ask for the fix first when the head is red or conflicting). Competing-PR detection and a real adopt-supersede trigger are tracked in a follow-up issue linked from the PR that added this action.

Expand Down
49 changes: 43 additions & 6 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,8 @@ stateDiagram-v2
s074 --> s080: in-place fix green and approved (adoption outranks 050/060; the merge gate takes it)
s074 --> s095: lane admits the hive's head, soak running
s074 --> s100: lane admits the hive's head, soak complete
s074 --> [*]: superseder merged (original closed)
s074 --> [*]: superseder merged (original closed); close_first (default) closes the original in the adopting pass instead
s074 --> s085: close-first copy closed unmerged or red at two heads → original reopened, adoption-copy-failed
s074 --> s072: superseder closed unmerged, or contributor pushed over an in-place adoption (handed back; 050 if that head is green)
s074 --> s085: adopted head unchanged past the dwell with CI idle and a real blocker the hive cannot push past (adoption-stalled:<reason>; a red optional check alone never counts), or the re-home failed
s085 --> s074: the adoption-stalled reason cleared (CI re-ran, check green, verdict landed); escalation released
Expand Down Expand Up @@ -1097,10 +1098,45 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
carries the original's `Closes/Fixes/Resolves` lines and instructs the
fix agent to rebase on the base and fix CI **on that branch** without
opening another PR;
- posts ONE `<!-- hive:adopted by=<hive-id> reason=<r> mode=supersede
superseded_by=M head=<sha> -->` comment on the original and moves it to
`stage/074-adopted-by-hive` (its linked issue mirrors the stage). The
hub drops the PR from the contributor's fix queue (either mode).
- **close-first** (`governor.labels.stage.adoption.supersede.close_first`,
default on; hivecommons/hive#15135 — the operator saw two active PRs
for one issue, #15029 and its copy #15123, and had not asked for
either): in the same pass, right after the copy opens, posts ONE
`<!-- hive:adopted by=<hive-id> reason=<r> mode=supersede
superseded_by=M head=<sha> close_first=true -->` comment reading
"Superseded by hive: re-authored as #M with the same commits and
sign-off because <the author's clanker is offline / an operator asked
for it / CI stayed red and the author was unavailable>. This PR is
closed; if #M fails, hive reopens it.", applies `hive/superseded`, and
**closes the original**. The order is push branch → open copy → note →
label → close, never with a sweep between, so the note names the copy
and the Activity Monitor never shows the original as active once the
copy exists: the stage record is superseded (no row, no chevron, no
needs-human) and the copy is the one PR for the issue. A close GitHub
refuses (403/404) leaves the original open with the note, superseded
all the same. `close_first: false` restores the keep-open behaviour
below: the note has no `close_first` field, the original moves to
`stage/074-adopted-by-hive` (its linked issue mirrors the stage) and
closes only when the copy merges. The hub drops the PR from the
contributor's fix queue in every mode.
- **Reopen on failure** (close-first only). The hive polls the copy from
the stage store at most every 10 minutes (a closed original is in no
lane's listing). Copy merged → done. Copy closed unmerged, or its
required checks red at **two** distinct copy heads (the fixer's one
repair push did not take; the same loop cap as the rebase/adoption
guard) → the original is **reopened**, gets ONE
`<!-- hive:adoption-copy-failed superseded_by=M head=<sha> why=copy-closed|copy-red-twice -->`
note ("Hive's copy #M failed (<why>); reopening this PR; needs a
person"), loses `hive/superseded`, and parks at `stage/085` with reason
`adoption-copy-failed` (tracker word "Adopted → #M (copy failed) ·
reopened, needs a person"; the park holds until a person acts, an
`adoption/supersede` request re-runs the takeover from the same head).
**Ping-pong guard:** one reopen per original per 24h — a second failed
copy inside the window leaves the original closed with a `held=true`
note saying so. The orphan recovery below never runs for a close-first
original (its copy being closed is a failure, not an orphan); the
`hive:adoption-copy-failed` note is a settled marker, so the marker scan
never re-adopts a reopened original on its own.
The superseding PR is App-authored and red with the same failures, so the
existing machinery takes over: it lands in `ci-failing.json` and the
scanner's FIX-BEFORE-NEW kick (the route every red hive-authored PR takes,
Expand All @@ -1111,7 +1147,8 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
superseded PR is never re-homed again. One adoption attempt per
contributor head, whatever the outcome — the DCO re-home likewise records
its attempt before touching GitHub, so a failed `hive/adopt-<n>` push is
not retried on the next sweep. While in 074 the hive polls the superseder at most
not retried on the next sweep. While in 074 (keep-open mode,
`close_first: false`) the hive polls the superseder at most
every 10 minutes: merged → one `<!-- hive:adopted-merged -->` note and the
original is closed; closed unmerged → the adoption is **orphaned** and the
hive recovers it rather than leaving the original parked
Expand Down
13 changes: 11 additions & 2 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -703,8 +703,17 @@ not consulted, because the hive owns an adopted head
(`governor.labels.stage.adoption.auto_merge`, default on; `false` leaves an
untrusted contributor's adopted PR waiting for a maintainer `/lgtm`). If the hive cannot push in place, it
pushes `hive/adopt-<n>` at the contributor head, opens a superseding App PR
that preserves the author's commits, moves the original to 074 and closes it
once the superseder merges. Whether that rework reaches each agent is visible per row
that preserves the author's commits, and — in the same pass — **closes the
original** with one note naming the copy and why ("Superseded by hive:
re-authored as #M … This PR is closed; if #M fails, hive reopens it."),
labelled `hive/superseded`, so one issue never shows two active PRs
(`governor.labels.stage.adoption.supersede.close_first`, default on;
hivecommons/hive#15135). If the copy is closed unmerged or its required
checks are red at two heads, the hive reopens the original, removes
`hive/superseded`, and parks it at `stage/085` with `adoption-copy-failed`
("needs a person"); at most one reopen per original per 24h. `close_first:
false` keeps the earlier behaviour: the original moves to 074 and closes
only once the superseder merges. Whether that rework reaches each agent is visible per row
on Operations → Connected contributor agents: the relay's parallel capacity
(`capacity N · spawn|preempt`, or *not advertised*), one line per in-flight
item tagged **NEW** / **REWORK** with its stage label, and a red *N PRs
Expand Down
4 changes: 4 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,10 @@ governor:
# after_offline: 15m # default 15m; registered relay offline, measured from the later
# # of its last heartbeat and the first stage/072 nudge
# after_unregistered: 15m # default 15m; no contributor profile, wait after the nudge with no new head
# supersede:
# close_first: true # default true; close the original (hive/superseded, one note naming the
# # copy) in the pass that opens the copy; reopened if the copy fails.
# # false: original stays stage/074 and closes when the copy merges

# Optional: read actionable work from Linear instead of GitHub Issues.
# Secrets should come from env interpolation, not literal values.
Expand Down
29 changes: 29 additions & 0 deletions src/pkg/config/adoption_close_first_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
package config

import (
"strings"
"testing"

"gopkg.in/yaml.v3"
)

// governor.labels.stage.adoption.supersede.close_first (hivecommons/hive#15135):
// on by default; false keeps the original open until the copy merges.
func TestStageAdoptionSupersedeCloseFirst(t *testing.T) {
if !(StageAdoptionConfig{}).Supersede.CloseFirstEnabled() {
t.Fatal("close_first default is not true")
}
for in, want := range map[string]bool{
"supersede: {}\n": true,
"supersede:\n close_first: true\n": true,
"supersede:\n close_first: false\n": false,
} {
var cfg StageAdoptionConfig
if err := yaml.NewDecoder(strings.NewReader(in)).Decode(&cfg); err != nil {
t.Fatalf("%q: %v", in, err)
}
if got := cfg.Supersede.CloseFirstEnabled(); got != want {
t.Errorf("%q: CloseFirstEnabled = %v, want %v", in, got, want)
}
}
}
20 changes: 20 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -2836,6 +2836,26 @@ type StageAdoptionConfig struct {
// AdoptionMaintainerPolicyNever is the pre-#14524 rule: the hive never
// takes a maintainer's PR over and releases any adoption of one.
MaintainerPolicy string `yaml:"maintainer_policy,omitempty"`
// Supersede tunes supersede-mode adoption (the hive-authored copy from
// hive/adopt-<n>).
Supersede StageAdoptionSupersedeConfig `yaml:"supersede,omitempty"`
}

// StageAdoptionSupersedeConfig is governor.labels.stage.adoption.supersede.
type StageAdoptionSupersedeConfig struct {
// CloseFirst closes the original PR as soon as the hive's copy is open
// (hivecommons/hive#15135): one `hive/superseded` note names the copy,
// and the hive reopens the original if the copy is closed unmerged, its
// required checks stay red across two heads, or the adoption branch
// cannot be pushed. nil = true. False keeps the pre-#15135 behaviour:
// the original stays open at 074 until the copy merges.
CloseFirst *bool `yaml:"close_first,omitempty"`
}

// CloseFirstEnabled reports whether a supersede adoption closes the
// original as soon as the copy exists (default on).
func (c StageAdoptionSupersedeConfig) CloseFirstEnabled() bool {
return c.CloseFirst == nil || *c.CloseFirst
}

// Values for governor.labels.stage.adoption.maintainer_policy.
Expand Down
5 changes: 4 additions & 1 deletion src/pkg/config/testdata/agent_runtime_golden.json
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,10 @@
"InPlace": null,
"StrictAttribution": null,
"AutoMerge": null,
"MaintainerPolicy": ""
"MaintainerPolicy": "",
"Supersede": {
"CloseFirst": null
}
},
"Stalled": {
"RequireQuiet": null
Expand Down
Loading
Loading