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
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **An owner's claim now releases a live contributor lease and stops the contributor lane.** The ledger always ranked a person over a contributor, but a claim made outside it (the assignee an owner or maintainer sets, a `/claim` comment, `hive/claimed-by-human` applied by hand) never displaced one: on #18866 the owner claimed at 03:21Z and the contributor still opened #18870 at 03:32Z. The contributor claim's admission check now reads those signals (the operator dispatcher's `gh issue edit --add-assignee` plus a plain "Claimed; fix in progress." comment counts); a renewal that meets one releases the claim at once and the five-minute release tick catches the rest, with release reason `human claim: assigned by <login>`. The relay task is yanked (a disconnected relay's lease is revoked), the lane is handed other work, the person is recorded as the ledger holder, a fresh contributor claim is refused while the claim stands, and the hive no longer adopts a contributor PR for an issue a person holds (tracker row: "an owner or maintainer has claimed the issue"; stage record `human-claim`). `/claim` and `/unclaim` are documented in the maintainer commands. ([#18899](https://github.com/hivecommons/hive/issues/18899), part of [#18890](https://github.com/hivecommons/hive/issues/18890)).
81 changes: 81 additions & 0 deletions src/cmd/hive/claims_admission_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -331,3 +331,84 @@ func TestContributorClaimRefusedInsideOwnerGrace(t *testing.T) {
t.Fatalf("claim after the grace = %+v, %v; want claimed", res, err)
}
}

// hivecommons/hive#18899: the operator's dispatcher claims with an assignee
// plus a plain comment and no ledger entry. A contributor's live lease is
// released on the release tick with the human-claim reason, a renewal and a
// fresh claim are refused, and the contributor's own assignment is not a claim
// against it.
func TestContributorLeaseReleasedByOutOfLedgerHumanClaim(t *testing.T) {
var assigned atomic.Bool
api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/repos/o/r/issues/9":
if assigned.Load() {
fmt.Fprint(w, `{"number":9,"state":"open","assignees":[{"login":"andy"}],"labels":[]}`)
return
}
fmt.Fprint(w, `{"number":9,"state":"open","assignees":[],"labels":[]}`)
case "/repos/o/r/issues/9/timeline":
fmt.Fprint(w, `[{"event":"assigned","assignee":{"login":"andy"},"actor":{"login":"andy"}}]`)
case "/repos/o/r/issues/9/comments":
if assigned.Load() {
fmt.Fprint(w, `[{"user":{"login":"andy"},"author_association":"MEMBER","body":"Claimed; fix in progress."}]`)
return
}
fmt.Fprint(w, `[]`)
case "/repos/o/r/collaborators/andy/permission":
fmt.Fprint(w, `{"permission":"admin","role_name":"admin","user":{"login":"andy"}}`)
default:
http.NotFound(w, r)
}
}))
defer api.Close()
logger := slog.New(slog.NewTextHandler(io.Discard, nil))
client := github.NewClientForTest(api.URL, "o", []string{"r"}, logger)
var released atomic.Value
ledger, err := claims.New(filepath.Join(t.TempDir(), "claims.json"), claims.DefaultPolicy(), claims.Hooks{
OnReleased: func(c claims.Claim, reason string) { released.Store(reason) },
})
if err != nil {
t.Fatal(err)
}
installClaimAdmissionCheck(context.Background(), ledger, func() *github.Client { return client })

req := claims.Request{Repo: "o/r", Issue: 9, Holder: "karibhou", HolderID: "c-1", Kind: claims.KindContributor}
if res, err := ledger.Claim(req); err != nil || res.Outcome != claims.OutcomeClaimed {
t.Fatalf("claim before the owner acts = %+v, %v; want claimed", res, err)
}
if n := ledger.ReleaseBlocked(); n != 0 {
t.Fatalf("released %d claims with no human claim on the forge", n)
}

// The owner assigns the issue and posts "Claimed; fix in progress.".
assigned.Store(true)
// The verdict cache would still answer "no claim" for a minute in
// production; this client has not asked since, but use a fresh one so the
// test does not depend on that window.
client = github.NewClientForTest(api.URL, "o", []string{"r"}, logger)
res, err := ledger.Claim(req)
if err != nil || res.Outcome != claims.OutcomeRefused {
t.Fatalf("renewal after the owner claimed = %+v, %v; want refused", res, err)
}
if login, ok := claims.ParseHumanClaimReason(res.Reason); !ok || login != "andy" {
t.Fatalf("renewal refusal reason = %q, want a human-claim reason naming andy", res.Reason)
}
if n := ledger.ReleaseBlocked(); n != 1 {
t.Fatalf("release tick released %d claims, want 1", n)
}
if reason, _ := released.Load().(string); !strings.HasPrefix(reason, claims.ReasonHumanClaim) {
t.Fatalf("release reason = %q, want the human-claim reason", reason)
}
if _, held := ledger.Lookup("o/r", 9); held {
t.Fatal("contributor claim survived the release tick")
}
// A fresh contributor claim is refused while the person's claim stands.
if res, err := ledger.Claim(claims.Request{Repo: "o/r", Issue: 9, Holder: "other", HolderID: "c-2", Kind: claims.KindContributor}); err != nil || res.Outcome != claims.OutcomeRefused {
t.Fatalf("fresh contributor claim = %+v, %v; want refused", res, err)
}
// The person's own ledger claim is unaffected.
if res, err := ledger.Claim(claims.Request{Repo: "o/r", Issue: 9, Holder: "andy", Kind: claims.KindHuman}); err != nil || res.Outcome != claims.OutcomeClaimed {
t.Fatalf("human claim = %+v, %v; want claimed", res, err)
}
}
36 changes: 26 additions & 10 deletions src/cmd/hive/claimswire.go
Original file line number Diff line number Diff line change
Expand Up @@ -220,19 +220,35 @@ func installClaimAdmissionCheck(ctx context.Context, ledger *claims.Ledger, clie
// claims do not — the holder's own PR is the open PR. A hive
// agent's own dispatch (Holder is the agent name) also refuses an
// issue that agent filed for outside help (hivecommons/hive#17299).
if _, held := ledger.Lookup(req.Repo, req.Issue); !held && !req.PRStarted {
if req.Kind == claims.KindAgent {
return gh.IssueStartBlockReason(ctx, req.Repo, req.Issue, req.Holder)
}
_, held := ledger.Lookup(req.Repo, req.Issue)
var reason string
var err error
switch {
case !held && !req.PRStarted && req.Kind == claims.KindAgent:
reason, err = gh.IssueStartBlockReason(ctx, req.Repo, req.Issue, req.Holder)
case !held && !req.PRStarted && req.Kind == claims.KindContributor:
// A contributor's fresh claim also waits out the owner grace on
// an issue an owner, maintainer or this hive filed moments ago
// (hivecommons/hive#18898).
if req.Kind == claims.KindContributor {
return gh.IssueContributorDispatchBlockReason(ctx, req.Repo, req.Issue)
}
return gh.IssueDispatchBlockReason(ctx, req.Repo, req.Issue)
}
return gh.IssueClaimBlockReason(ctx, req.Repo, req.Issue)
reason, err = gh.IssueContributorDispatchBlockReason(ctx, req.Repo, req.Issue)
case !held && !req.PRStarted:
reason, err = gh.IssueDispatchBlockReason(ctx, req.Repo, req.Issue)
default:
reason, err = gh.IssueClaimBlockReason(ctx, req.Repo, req.Issue)
}
if err != nil || reason != "" || req.Kind != claims.KindContributor {
return reason, err
}
// A person's claim outside the ledger (assignee, `/claim` comment,
// hand-applied hive/claimed-by-human) outranks a contributor: it
// refuses a fresh claim and a renewal, and the release tick then
// drops the live lease and yanks the task (hivecommons/hive#18899).
// A lookup failure keeps the claim held: unknown is not a verdict.
human, herr := gh.IssueHumanClaimReason(ctx, req.Repo, req.Issue, req.Holder)
if herr != nil {

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.

On a lookup error this returns allowed. For a renewal that keeps the existing claim, but for a fresh contributor claim (held == false) it admits the claim over a possible human claim. This contradicts the PR body's 'a lookup error keeps the claim held'. Either document it as fail-open for fresh claims or refuse on error.

return "", nil
}
return human, nil
})
}

Expand Down
1 change: 1 addition & 0 deletions src/docs/contributor-relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -1533,6 +1533,7 @@ A resume that is genuinely refused — an operator yanked the task, or the relay
- **Repeated drops put the issue in contributor cool-off.** The hub counts disconnect releases per issue; at `governor.claims.contributor_flap_threshold` drops (default 3) inside `contributor_flap_window_s` (default 2h) the issue is withheld from *every* contributor — `selectTask` skips it and a `task_progress` resume of its lease is refused with `task_revoke` — for `contributor_flap_cooloff_s` (default 6h). Hive agents are not withheld; the work detail says `contributor cool-off: 3 drops in 2h0m0s; hive agents may claim it`, and one INFO line names the issue and the cool-off deadline when it trips. In-memory: a hub restart forgets the drops (the claim release is the durable half). A negative threshold turns the cool-off off.
- **Contributor claims cannot starve hive agents.** An issue continuously withheld from hive agents by contributor claims for `contributor_starvation_s` (default 4h; negative turns it off) with no PR evidence on the claim stops being withheld: the claim becomes advisory, the issue stays actionable with the reason `Contributor claim by <login> is advisory: contributor claims have withheld this issue from hive agents for 4h0m with no PR`, and a hive agent may claim it (the ledger's takeover hook then stops the relay). Agent, human and external claims are never overridden.
- **An issue the owner filed moments ago is the owner's to claim first.** An issue whose author is an owner or maintainer (author association `OWNER`, `MEMBER` or `COLLABORATOR`) or this hive's own App/bot is withheld from the contributor lane for `governor.claims.contributor_grace_s` (default 900 = 15m; negative turns it off) after it is filed ([#18898](https://github.com/hivecommons/hive/issues/18898), child of [#18890](https://github.com/hivecommons/hive/issues/18890): #18866 and #18880 each grew a contributor PR because the lane claimed the issue seconds after filing, before the owner or the owner's dispatcher could). Inside the window `selectTask` and the Ready queue skip the issue (Withheld reason `owner_grace`), and a contributor's fresh ledger claim is refused with `owner grace: filed by <login> 3m ago; contributor claims wait 15m unless a person adds `help wanted``. A person adding the `help wanted` label after filing (a timeline `labeled` event whose actor is not a bot) waives the grace at once, because that is the owner opening the issue to outside help. Only a *fresh* claim waits: a lease already live is not touched, hive agents are never held off, and an issue filed by an outside reporter is not delayed.
- **A person's claim outside the ledger releases the contributor and yanks the task.** An owner or maintainer who assigns the issue (the operator's dispatcher runs `gh issue edit --add-assignee` plus a plain "Claimed; fix in progress." comment), comments `/claim`, or applies `hive/claimed-by-human` by hand outranks a live contributor lease even though none of it goes through the ledger ([#18899](https://github.com/hivecommons/hive/issues/18899), child of #18890: the owner claimed #18866 at 03:21Z and the contributor opened #18870 at 03:32Z). The contributor claim's admission check reads those signals: a renewal meeting one releases the claim at once and the five-minute release tick catches the rest, with release reason `human claim: assigned by <login>`; the relay task is yanked like a takeover (or a disconnected relay's lease is revoked so a reconnect cannot resume it), the lane is handed other work, and the person is recorded as the ledger holder. While the claim stands a fresh contributor claim is refused and the hive does not adopt a contributor PR for the issue (stage tracker: "an owner or maintainer has claimed the issue"). The contributor's own assignment or comment never counts against it; the claim lifts when the person unassigns, removes the label or comments `/unclaim`. See [maintainer commands](maintainer-commands.md#claiming-an-issue).

**Not every task has a lease, and one of them is the relay's own.** After every fifth completion the relay runs a *PR review cycle*: it stops taking new issues and asks its agent to look over the open PRs it has filed, so review comments get answered. That task is built locally — a `pr-review-…` id, `number: 0`, no `task_assign`, no lease — and for a long time the reconnect path above did not know the difference. It re-asserted the review to a hub that had never heard of it, the hub refused under exactly the server-issued-lease rule described above, and the relay treated the resulting revoke as terminal: stop the agent, relaunch the CLI, ask for fresh work ([#5715](https://github.com/hivecommons/hive/issues/5715)). The tell was in the log line itself — `Reconnected while working on kubestellar/hive#0 — resuming`, naming an issue number that does not exist. On a hive where 1006 closes are routine (29 in under four hours in the report) a review that takes a couple of minutes almost never survived to finish, so PR review coverage silently did not happen.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -1017,7 +1017,7 @@ Retired ([#12683](https://github.com/hivecommons/hive/issues/12683)): nothing wr

**Applies to:** Issues. **Kind:** Display-only.

A claim is a comment; the `claimed` label is a mirror Hive keeps in sync. Go claim gates use comments/assignees/ledger, not these labels.
A claim is a comment; the `claimed` label is a mirror Hive keeps in sync. Go claim gates use comments/assignees/ledger, not these labels. The one exception is a `hive/claimed-by-human` applied by hand (not by the hive App): the contributor claim gate reads it as a person's claim, like a human assignee or `/claim` comment, and releases a live contributor lease for it ([#18899](https://github.com/hivecommons/hive/issues/18899)).

**Who applies it:** Hive/claim flows.

Expand Down
14 changes: 14 additions & 0 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -1425,6 +1425,20 @@ comment and the dashboard claim detail (`@login` next to the claim).
| A relay contributor or external bot | `kind=contributor` / `kind=external`, `who=<login>` | `hive/claimed-by-human` |
| A hive agent with no human principal | `kind=agent who=<agent>` | `hive/claimed-by-<agent>` (e.g. `hive/claimed-by-scanner`) |

**A person outranks a contributor, ledger entry or not.** The ledger ranks
`kind=human` over `kind=contributor`, but an owner's claim made outside it
(the assignee set by an owner or maintainer, a `/claim` comment, or
`hive/claimed-by-human` applied by hand rather than by the hive) used to leave
a live contributor lease untouched (#18866: the owner claimed at 03:21Z and the
contributor still opened a PR at 03:32Z). Since
[#18899](https://github.com/hivecommons/hive/issues/18899) the contributor
claim's admission check reads those signals, so the next renewal or the
five-minute release tick releases the lease (reason `human claim: ...`), yanks
the relay task and records the person as the claim holder; see
[Maintainer commands](../maintainer-commands.md#claiming-an-issue). The hive's
own `hive/claimed-by-human` label (applied for a person's or a contributor's
ledger claim) is never read as a person's claim; only a hand-applied one is.

A backend or model name (`copilot`, `claude`, `codex`, `gemini`, `pi`) is
**never** a suffix: it names the tool, not who answers for the work. A
hive-agent claim whose name is a backend falls back to
Expand Down
12 changes: 12 additions & 0 deletions src/docs/maintainer-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,18 @@ https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md
| `/area <area>` | Validates or requests an area label. The Hive label helper reports invalid values and lists the accepted area names; repositories may also have Prow or other automation that applies valid labels. | Any non-bot commenter accepted by the label-helper workflow, subject to any repository label automation that applies the label. | Issues and pull requests. | GitHub Actions on the new comment. | The helper itself changes no labels for valid `/area` comments; companion repository automation may add `area/<area>` or equivalent labels. |
| `/assign` | Assigns the commenter where the repository's assignment automation supports slash-command assignment. The Hive assignment helper deliberately ignores the exact command because Prow handles it, but it points natural-language assignment requests to this command. | Repository assignment automation decides; the helper response is available to non-bot issue commenters. | Issues. | Repository assignment automation or GitHub Actions helper on the new comment. | Assignment state changes, not labels. |
| `/unassign` | Removes the commenter's assignment where the repository's assignment automation supports it. | Repository assignment automation decides; the helper response is available to non-bot issue commenters. | Issues. | Repository assignment automation or GitHub Actions helper on the new comment. | Assignment state changes, not labels. |
| `/claim` | Says "I am working this issue": a contributor-lane lease on the issue is released and its relay task yanked, no new contributor claim is accepted on it and the hive will not adopt a contributor PR for it unless you release it ([#18899](https://github.com/hivecommons/hive/issues/18899)). It is read from the forge by the claim gate, not parsed by a sweep and not written to the ledger by itself: to register a claim in the ledger use the dashboard or `hivectl claim owner/repo#N`. | A commenter with author association `OWNER`, `MEMBER` or `COLLABORATOR`; bots and the contributor holding the lease are ignored. | Open issues. | The contributor claim's next lease renewal or the five-minute claim release tick. | Applies `hive/claimed-by-human` and `stage/020-claimed` when the claim is recorded in the ledger. |
| `/unclaim` | Withdraws your own `/claim` comment. | The same commenter. | Open issues. | Same as `/claim`. | None. |

## Claiming an issue

A person's claim outranks the contributor lane. Any of these on an open issue, made by an owner or maintainer (a person with `write`, `maintain` or `admin` repository permission, never a bot or the hive's own App), counts as a human claim even though none of them goes through the claim ledger ([#18899](https://github.com/hivecommons/hive/issues/18899), child of [#18890](https://github.com/hivecommons/hive/issues/18890)):

- **Assigning the issue.** This is what an operator's dispatcher does: `gh issue edit --add-assignee` plus a plain "Claimed; fix in progress." comment. The assignment is the claim; the comment is courtesy. An assignee who is the contributor holding the lease is not a claim against that contributor (a maintainer handing the issue to them).
- **A `/claim` comment** (or a plain comment opening with "Claimed") from an `OWNER`, `MEMBER` or `COLLABORATOR`, until the same person comments `/unclaim`.
- **Applying `hive/claimed-by-human` by hand.** The same label applied by the hive is the ledger speaking and is not a claim.

What a human claim does: a live contributor lease on the issue is released (release reason `human claim: assigned by <login>`, `human claim: /claim comment by <login>` or `human claim: hive/claimed-by-human label by <login>`), its relay task is yanked so the lane moves on, and the person is recorded as the ledger claim holder. While it stands a contributor's fresh claim and renewal are refused, and the hive does not adopt a contributor PR whose `Fixes #N` names the issue (the tracker row reads "an owner or maintainer has claimed the issue"). It lifts when the person unassigns, removes the label or comments `/unclaim`. The supported way to register a claim in the ledger is the dashboard or `hivectl claim owner/repo#N`; the three forge signals above are detected, not ledger entries of their own.

## Eligibility rules

Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:5369-5379`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5375-5385`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes → refactors/docs → tests).
Expand Down
Loading
Loading