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/fixed-adoption-orphan-recovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Adoption: when the hive's superseding copy of an adopted PR is closed without merging, the stage-label pass now re-adopts (fresh copy from the same head, new `hive:adopted` marker), reverts the adoption with a `hive:adoption-reverted` note when the head moved or the copy cannot be opened, and parks the PR as `adoption-child-closed-twice` if copies are closed twice within an hour; "Let hive decide" re-adopts instead of answering "no change", and the tracker shows "Adopted β†’ #N (closed) Β· recovering" instead of "Needs human decision" (hivecommons/hive#15052).
4 changes: 4 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -682,6 +682,8 @@ 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.

**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.

**Hive's own unblock is live.** When the blocked sweep or the review-backlog block reconciler lifts `blocked` itself (the tracked PR merged or closed; the `<!-- hive:unblocked -->` note), it takes the same path as an inbound label webhook: the tracker cache is dropped and the issue is queued for the targeted re-read (`ItemPatches` delivery `self:edit`), which patches the status row and the governor's cached snapshot at once. A reconcile enumeration that was already listing when the unblock happened used to overwrite that patch with its pre-unblock copy, and the rows reverted to `blocked` until the next pass (~an hour on the hive's hive); the governor now replays re-reads newer than the listing's start onto the pass's result before publishing it, so a row never moves backwards behind a read it has already made.
Expand Down Expand Up @@ -743,6 +745,8 @@ 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.

**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.

**LLM step for the non-mechanical cases.** With `decisions.delegate.llm.enabled: true` (default **false**), an item the rules leave at the reversible default (rule `default-approve` or `default-release`) is shown to one *owner-delegate decider* turn: the item, its comment thread, sentinel findings, linked issues/PRs, the repository's auto-merge setting, the author's association and reporter-trust state, its labels, and `PolicyText` verbatim. The model answers with a structured `{verdict, text, rationale, actions[]}`; the reply is rejected unless every verdict, action kind and label is in the delegate's closed set and fits the item (no `approve-review` on an issue, no action on a park-keeping verdict, …), and unless the actions carry the verdict out: an acting verdict must include its recording action (`comment-decision`, or `close-as-duplicate` for the close verdicts, plus `approve-review` / `adopt-supersede` where the verdict names them), `labels-remove` can never name `stage/085-needs-decision` (only the recording action lifts the park, with the comment and the marker), and `close-duplicate` closes the newer item in favour of an older one. An accepted reply is recorded under rule `llm-delegate` and goes through the same safety rails and executor as a rule decision; a model error or rejected reply keeps the reversible default and the job's `notes` say why. Rules-first stays authoritative: every case a rule decides, and every item wearing `hold`, never reaches the model. The call uses the governor reviewer endpoint (`governor.trajectory`, falling back to `governor.litellm`); `decisions.delegate.llm.model` overrides the model.
Expand Down
34 changes: 32 additions & 2 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -1091,8 +1091,38 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
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
every 10 minutes: merged β†’ one `<!-- hive:adopted-merged -->` note and the
original is closed; closed unmerged (a maintainer declined) β†’ the adoption
is forgotten and the original returns to 072 (not a regression).
original is closed; closed unmerged β†’ the adoption is **orphaned** and the
hive recovers it rather than leaving the original parked
(hivecommons/hive#15052, where the duplicate-fix sweep closed the hive's
copy and the original sat at 085 with "Let hive decide" answering "no
change"):
- **Re-adopt.** The hive logs `stage labels: adoption orphaned,
re-adopting` (old and new numbers), opens a fresh hive-authored copy
from the same contributor head and posts a new `hive:adopted … mode=supersede
superseded_by=<new>` marker; the original stays 074 and the tracker reads
"Adopted β†’ #old (closed) Β· recovering" until the new copy is on record,
then "Adopted β†’ #new".
- **Revert.** If the head moved (or the original merged meanwhile) or the
fresh copy could not be opened, the adoption is cleared and the original
returns to its pre-adoption stage with one
`<!-- hive:adoption-reverted head=<sha> superseded_by=<old> why=head-moved|readopt-failed -->`
comment that says in plain words why.
- **Loop guard.** If the re-adopted copy is itself closed unmerged within
an hour of the first orphan, the hive stops opening copies: it posts
`<!-- hive:adoption-child-closed-twice -->`, parks the original at
`stage/085-needs-decision` with reason `adoption-child-closed-twice`, and
the tracker shows "Adopted β†’ #N (closed twice) Β· needs a person". Reopen
the last copy, give direction, or close the original; the park is not
escalated or re-adopted by the hive.
- **Marker scan.** A hive restarted (or rolled) after the orphan happened
has no adoption on record, so once per head a PR at 085 wearing
`author/clanker` has its comments scanned for the last unsettled
`hive:adopted … mode=supersede` marker; a merged copy closes the
original the standard way, a closed one takes the recovery above, an
open one is restored to the record. *Let hive decide* on such a PR does
the same recovery instead of answering "no change" β€” its outcome reads
"Re-adopting: hive's earlier copy #N was closed by mistake; opening a
fresh copy" (or, past the loop guard, a recommendation to a person).
If an adopted head is DCO-red, an empty signed commit is never enough.
"Hive-authored" is decided the same way as head attribution above: an
unsigned commit is the hive's own only when GitHub links its author or
Expand Down
18 changes: 16 additions & 2 deletions src/pkg/dashboard/api_repo_item_decide_delegated.go
Original file line number Diff line number Diff line change
Expand Up @@ -473,12 +473,23 @@ func (s *Server) decideDelegatedOne(ctx context.Context, repoFull string, number
return delegatedOutcome{Err: err}
}
d, deciderNotes := s.decideDelegated(ctx, in)
// An adoption whose copy was closed unmerged (hivecommons/hive#15052)
// overrides the policy: the recorded decision no longer stands, so the
// answer is to re-adopt, not "already decided".
var orphan orphanedAdoption
if o, ok := s.delegatedOrphanedAdoption(ctx, repoFull, number, in, time.Now()); ok {
orphan = o
d = o.decision("#" + strconv.Itoa(number))
deciderNotes = append(deciderNotes, fmt.Sprintf("adoption orphaned: hive's copy #%d is closed without merging", o.Dead))
}
// The same rule firing again on an item the hive already decided would
// only repeat the comment: report it as a no-op instead of writing β€”
// unless the recorded decision never took effect, in which case say so
// in plain words with the options (hivecommons/hive#14822), or the
// operator asked to re-run it.
if prior := s.delegatedPriorDecisionState(ctx, repoFull, number, d.Rule); prior.Found && !req.Force {
// operator asked to re-run it. A re-adoption request older than the
// latest adoption marker was carried out and then orphaned again
// (hivecommons/hive#15052): it is not a repeat.
if prior := s.delegatedPriorDecisionState(ctx, repoFull, number, d.Rule); prior.Found && !req.Force && (orphan.Dead == 0 || prior.At.After(orphan.MarkerAt)) {
kind := rowActionTargetIssue
if in.Kind == delegatedecision.KindPR {
kind = rowActionTargetPR
Expand All @@ -501,6 +512,9 @@ func (s *Server) decideDelegatedOne(ctx context.Context, repoFull string, number
notes, execErr := s.executeDelegatedDecision(ctx, in, d, user, mergerRole)
notes = append(deciderNotes, notes...)
result := delegatedRowActionResult(in, d, notes)
if orphan.Dead > 0 && !orphan.Looped && execErr == nil {
result.Outcome = delegatedOrphanOutcome(orphan.Dead)
}
kinds := make([]string, 0, len(d.Actions))
for _, a := range d.Actions {
kinds = append(kinds, string(a.Kind))
Expand Down
92 changes: 92 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_orphan.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
package dashboard

import (
"context"
"fmt"
"strings"
"time"

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/delegatedecision"
"github.com/hivecommons/hive/pkg/github/automerge"
"github.com/hivecommons/hive/pkg/stagelabels"
)

// "Let hive decide" on an orphaned adoption (hivecommons/hive#15052).
//
// The delegate's dedup answers a repeat click with "hive already recorded
// this decision (rule contributor-offline)" when the rule's comment is on
// the PR. On hivecommons/hive#14947 that decision had been carried out β€”
// the hive's copy #14977 opened β€” and then undone by the duplicate-fix
// sweep closing #14977 unmerged; the recorded decision no longer stood, and
// the answer was wrong. The delegate now reads the PR's adoption markers
// first: a supersede marker whose copy is closed without merging is an
// orphan, and the decision is to re-adopt, under its own rule so the dedup
// keys on the fresh copy rather than the dead one.

// Rules the orphan path decides under.
const (
delegatedRuleAdoptionOrphaned = "adoption-orphaned"
delegatedRuleAdoptionLooped = stagelabels.LaneReasonAdoptionChildClosedTwice
)

// orphanedAdoption is what delegatedOrphanedAdoption found.
type orphanedAdoption struct {
Dead int // the closed, unmerged copy
MarkerAt time.Time // when the adoption that opened it was recorded
Looped bool // copies were closed twice within the hour
}

// delegatedOrphanedAdoption reports whether the PR wears a live supersede
// marker naming a copy that is closed without merging. Read failures read
// as "not orphaned": the ordinary delegate path then runs.
func (s *Server) delegatedOrphanedAdoption(ctx context.Context, repoFull string, number int, in delegatedecision.Input, now time.Time) (orphanedAdoption, bool) {
if in.Kind != delegatedecision.KindPR || in.HiveAuthored || s.deps == nil || s.deps.GHClient == nil || s.deps.GHClient.GoGitHub() == nil {
return orphanedAdoption{}, false
}
owner, repoName, _ := strings.Cut(repoFull, "/")
api := s.deps.GHClient.GoGitHub()
comments, _, err := api.Issues.ListComments(ctx, owner, repoName, number, &gh.IssueListCommentsOptions{ListOptions: gh.ListOptions{PerPage: delegatedDecisionGatherLimit}})
if err != nil {
return orphanedAdoption{}, false
}
scan := automerge.ScanAdoptionMarkers(comments)
if !scan.Live {
return orphanedAdoption{}, false
}
sup, _, err := api.PullRequests.Get(ctx, owner, repoName, scan.Marker.SupersededBy)
if err != nil || sup.GetMerged() || !strings.EqualFold(sup.GetState(), "closed") {
return orphanedAdoption{}, false
}
out := orphanedAdoption{Dead: scan.Marker.SupersededBy, MarkerAt: scan.Marker.At, Looped: automerge.AdoptionLoopFromMarkers(scan, now)}
if store := s.stageStoreOrShared(); store != nil {
if rec, ok := store.Get(stagelabels.Key(repoFull, number)); ok && rec.AdoptionChildClosedTwice() {
out.Looped = true
}
}
return out, true
}

// decision is the delegate's answer for the orphan: re-adopt, or β€” when
// the copies keep being closed β€” a recommendation a person must act on.
func (o orphanedAdoption) decision(ref string) delegatedecision.Decision {
if o.Looped {
text := fmt.Sprintf("the hive's copies of %s were closed without merging twice within an hour (last #%d); something keeps closing them, so the hive is not opening a third β€” reopen a copy, close this PR, or say what should happen", ref, o.Dead)
return delegatedecision.Decision{
Verdict: delegatedecision.VerdictRecommendOnly, Rule: delegatedRuleAdoptionLooped, Text: text, KeepsPark: true,
Rationale: "a copy closed twice within the hour is a loop the hive must not feed (hivecommons/hive#15052)",
Actions: []delegatedecision.Action{{Kind: delegatedecision.ActionRecommendOnly, Text: text}},
}
}
text := fmt.Sprintf("re-adopt %s: the hive's earlier copy #%d was closed without merging, so the adoption is re-run from the same head as a fresh copy", ref, o.Dead)
return delegatedecision.Decision{
Verdict: delegatedecision.VerdictAdoptSupersede, Rule: delegatedRuleAdoptionOrphaned, Text: text,
Rationale: "the recorded supersede decision no longer stands once its copy is closed unmerged (hivecommons/hive#15052)",
Actions: []delegatedecision.Action{{Kind: delegatedecision.ActionCommentDecision, Text: text}, {Kind: delegatedecision.ActionAdoptSupersede, Target: o.Dead}},
}
}

// delegatedOrphanOutcome is the row result text for a re-adoption.
func delegatedOrphanOutcome(dead int) string {
return fmt.Sprintf("Re-adopting: hive's earlier copy #%d was closed by mistake; opening a fresh copy.", dead)
}
Loading
Loading