🐛 fix: escalate stalled claims instead of re-claiming after 2 no-progress claims

[hivecommons-hive]

Closes #10527

Builds on @Danathar's branch fix/claim-gate-escalate-10527 (commit 9e93827, cherry-picked with his authorship kept). That commit adds the escalation gate: pkg/claims attempt history (Stall, MarkEscalated, EscalationComment), pkg/github.IssueTimelineSince, cmd/hive/claimescalation.go, and governor.claims.escalate_after_claims (default 2). This PR adds the rest of the maintainer's /hive decision (option A plus the refinement):

1. Kicks list issues; they don't claim them

• recordAgentKickClaims is now recordAgentKickListings. It records a ledger Listing: a 30-minute hold with no GitHub comment, and it is not an Attempt. HeldKeys (relay selectTask) and claimsInflightLookup (other agents' kicks) respect the listing, so other workers still back off while the kick is live.
• A new github.Client.SetAgentStartHook fires on the agent's own authorized start signals: a relay comment/label/claim request on the issue, or a hive-open-pr request naming it in --issues. Each signal goes through Ledger.ClaimOnStart. That records the real agent claim, with the 🔒 comment and label, if a kick listed the issue to that agent within the agent claim TTL. If the agent already holds the claim, it renews it with no second comment. A signal on an issue no kick listed (for example a comment on the agent's own PR) records nothing.

2. The escalation gate counts real claims only. Listings never create attempts, so an issue that just sat in a work list never escalates. The default threshold stays 2: the third no-progress claim is refused, and the issue gets needs-human plus one comment.

3. Verify once (#10509). New cmd/hive/verifyonce.go in-flight gate. It applies to an issue with merged-PR context that is not hive/verified-open. Once an agent claim on the issue postdates the merge (the verification), the issue is withheld from kicks until a person (not a bot or App account) comments, labels, assigns, closes or reopens it. IssueEvent now carries Actor/ActorIsBot for this check. If the timeline can't be read, the issue is offered as before.

Docs (operator-reference.md, contributor-relay.md) and the changelog fragment are updated.

Not covered: a raw git push of a branch is not a start signal by itself. The proxy relays the pack stream without parsing ref updates. The agent's first comment or hive-open-pr request records the claim instead.

Tests: pkg/claims/listing_test.go, cmd/hive/verifyonce_test.go, pkg/github/agent_start_hook_test.go, plus updates to claimswire_test.go, claimescalation_test.go and issue_timeline_test.go. None use time.Sleep. Not run locally (CI is the verdict); gofmt is clean.

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[kubestellar-prow]

[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 danathar 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:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hivecommons-hive]

hive/awaiting-ci: CI pending — sweep will merge when green.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[github-actions]

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
#10533	🐛 fix: refuse automated claims on needs-human issues	CONFLICT	src/cmd/hive/claimswire.go

[hivecommons-hive]

hive/awaiting-ci: merged origin/v5 to resolve the scale-envelope.md citation conflict; CI pending — sweep will merge when green.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[github-actions]

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

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

[hivecommons-hive]

Read the full diff against v5 (e881de45) plus the callers in issue_request_watcher.go, pr_request_watcher.go, issue_unpark_command.go and main.go. The escalation gate, the start-signal hook and verify-once all read correctly to me; CI is green. One design question needs a maintainer before this lands, and it is a judgment call, not a bug.

Open question — a 30-minute fixed hold replaces a 2-hour claim, and a second listing silently drops the first agent's claim.

• src/pkg/claims/claims.go:191 — DefaultListedTTL = 30 * time.Minute is a constant; MarkListed (claims.go:775) sets ExpiresAt: now.Add(DefaultListedTTL). Before this PR the kick took an agent claim, so other agents/contributors backed off for agent_ttl_s (default 2h per operator-reference.md:77). Now they back off for 30 min unless the agent has already produced a start signal.
• MarkListed (claims.go:782) accepts a new listing when prev.Expired(now), overwriting agent A's listing with agent B's once 30 min have passed.
• ClaimOnStart (claims.go:826-827) then requires li.Holder == agent. So if A's first comment / hive-open-pr arrives after B was listed, A's signal matches nothing and returns ok=false — A's claim is never recorded (no 🔒, no Attempt), while B is also working the same issue. That is the #8380 double-dispatch the ledger exists to prevent, and A's run becomes invisible to the escalation gate.

This only bites when a kick runs more than 30 min before the agent's first relay write on the issue, which is common for investigate-then-PR work. The window is also not operator-tunable the way agent_ttl_s was.

For @clubanderson / @Danathar to decide: is a 30-minute, non-configurable listing hold the intended trade (fewer spurious 🔒 comments vs. a shorter back-off and a dropped claim on overlap), or should the hold track agent_ttl_s (or at least be a claims.listed_ttl_s knob)? If 30 min is intended, I'd suggest ClaimOnStart log when a listed-then-overwritten agent's signal is dropped, so the overlap is at least visible.

Verified non-findings, for the record: the escalation comment's "replying /hive approve counts as progress" is true — clearIssueParkingLabels (issue_unpark_command.go:276) removes needs-human, and claimProgress (claimescalation.go) counts that unlabeled event. The start hook fires only after the issue request succeeded (issue_request_watcher.go:577) and after PR-request authorization (pr_request_watcher.go:417), with req.Agent UID-verified, so an agent cannot claim as another.

Scope note: verify-once (#10509) is bundled here but only #10527 is closed; worth stating in the body whether #10509 should close with this or stay open.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88