Skip to content

🐛 [v6] contributor-first: a relay that is holding work does not cover a lane - #17233

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/v6-relay-hold-not-cover
Nov 8, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/v6-relay-hold-not-cover

Conversation

@Danathar

@Danathar Danathar commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Summary

A contributor-first lane can be left with nobody working it. The hub counts every connected relay acting as a role as "covering" that role, including a relay that has stopped taking work. On 2026-11-08 the only scanner relay on hive-wild-mole had its quota guard holding all work, but the governor still withheld scanner's resident kicks. This PR stops counting a relay in standby mode or with a quota hold as cover. It adds a small quota_hold_v1 capability so the relay can tell the hub when a hold starts and ends. In a second commit, it also logs the "covering" line when an owner switches contributor_first on for a lane a relay already covers. Today that order logs nothing.

Refs #16518, #16772

What went wrong

Part 2: a held relay still counted as cover. Observed on hive-wild-mole (v6 d8d61f9) between 12:31 and 12:34Z:

  • The relay connected as scanner. Its quota guard was holding all work: the Claude weekly window had 15% left against a 20% reserve.
  • The governor reported governor.covered_lanes = {"scanner": {"contributors": ["Danathar"]}} and withheld scanner's kicks.
  • Nobody worked the lane.

RoleCoverage checks the role, a fresh pong, the login, the failure-streak pause and hub.contribute_suspended. While held, the relay only withholds ready at the sendTo choke point and declines pushed work. The hub had no per-connection state that said "holding".

A small correction to the original diagnosis: the hold in this incident was the contributor quota guard (contributorQuotaPaused, #6951), not quotaHoldActive(), which is the provider-exhaustion hold (#6541). Both have the same effect on the hub, so this PR reports both. The relay already treats the two together as quota-held in relayReadiness.

Standby has the same problem. A relay started with just contribute-standby stays connected, never asks for ordinary work (requestWork returns early in standby mode), and only takes what an owner dispatches to it by hand. It was counted as cover too. This includes a relay whose standby declaration was rejected because its configuration is suspended. That relay records no lanes, but it is still in standby mode.

Part 3: no log line when the flag goes on. The governor records coverage for every role, flagged or not. The covering line was logged only when a role was first seen. The usual order is: relay already covering, then the owner flips the General-tab toggle from #16772. In that order the record already exists, so the line never appeared. In the pilot, cover began at 12:30:45Z, the flag was saved at 12:31:18Z, and the hive log had no cover line.

What changes

  • Hub: RoleCoverage skips a connection that has declared standby (accepted or rejected) or has reported a quota hold. A relay busy on a task is still skipped while held or in standby, because it will not take the lane's next item.
  • New capability quota_hold_v1: the hub advertises it and accepts {"type":"quota_hold","state":"held"|"released","reason":...}. The relay sends held when the guard or the provider hold starts, and released when both end. released goes out before the ready that follows. The relay sends each transition once per connection, and restates a live hold after auth_ok.
  • Compatibility: the relay sends the frame only to a hub that advertises the token. A hub treats a relay that never sends it as not held. Old relays and old hubs keep today's behaviour.
  • Governor: coverageRecord remembers whether the covering line was logged for the current cover. The line is logged once on the first evaluation that sees the lane both flagged and covered. The gate logic is unchanged.
  • Docs: the coverage rules in agent-configuration.md "Contributor-first lanes", a new quota_hold_v1 section in contributor-relay.md, and the RoleCoverage and governor doc comments.

Why a new capability and not standby_declare

I read handleStandbyDeclare and every reader of conn.standby. Standby does not mean "connected but not requesting work". It means "offer me for donated work on these lanes":

  • pickStandbyCandidate picks standby connections for the owner's manual standby dispatch.
  • QualifiedStandbyCounts counts them in the standby tiles.
  • Each declaration is checked against the standby outcome ledger, so a suspended configuration is refused.

If a quota-held relay reused it, the relay would be offered donated work it would then decline, would show up in the standby tiles, and would be refused whenever its standby key was suspended. A separate, tiny message has none of those side effects.

Files

  • src/pkg/dashboard/contribute_coverage.go: the skip, plus the doc comment
  • src/pkg/dashboard/contribute_ws.go: standbyDeclared and quotaHeld on the connection, handleQuotaHold, and the standby handlers set or clear the flag
  • src/pkg/dashboard/contribute_protocol.go: capQuotaHoldV1, added to serverCapabilities()
  • bin/contributor-relay.js: reportQuotaHold, called from writeRelayStatus (every hold transition already ends there) and from auth_ok
  • src/pkg/governor/contributor_first.go: the announced flag
  • src/docs/agent-configuration.md, src/docs/contributor-relay.md, changelog.d/fixed-relay-hold-not-cover.md

Tests

Each test below fails on v6 tip d8d61f9 and passes on this branch, with one exception, which is noted.

  • TestRoleCoverage_StandbyRelayDoesNotCover: tip reports quality: [alice bob]. Released standby covers again.
  • TestRoleCoverage_RejectedStandbyDeclarationDoesNotCover: tip reports quality: [bob].
  • TestRoleCoverage_QuotaHeldRelayDoesNotCover: the live case. Tip reports scanner: [Danathar] while held. Released covers again. It ran on tip with a test-only shim that ignores the frame, as an old hub does.
  • TestServerCapabilities_AdvertisesQuotaHold: fails on tip because the token is missing.
  • TestContributorFirst_FlagSwitchedOnForCoveredLaneLogsOnce: tip logs the line 0 times, this branch logs it exactly once. Further evaluations log nothing more.
  • Relay quota_hold_v1: the quota guard hold is reported, and released before the relay asks again: fails on tip.
  • Relay quota_hold_v1: the provider quota hold is reported, restated on reconnect, and released: fails on tip.
  • Relay quota_hold_v1: a hub that does not advertise the token never sees the frame: a compatibility guard, so it passes on tip by design.

go test ./pkg/dashboard/... ./pkg/governor/... passes, and so do go vet, the docs citation and link checks, and the changelog fragment check. node --test bin/contributor-relay.test.js has 66 failures on this machine. Tip has the same 66 host-specific failures, by name, and there are no new ones.

Not in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

Danathar and others added 2 commits November 8, 2026 07:48
RoleCoverage counted any connected relay with a fresh heartbeat as
covering its role. A relay in standby mode, or one whose quota guard or
provider quota hold was withholding `ready`, stayed connected and kept
the governor withholding the resident agent's kicks, so nobody worked
the lane. Seen on hive-wild-mole on 2026-11-08: the scanner relay was
held at 15% of its weekly window (reserve 20%) while
governor.covered_lanes still showed scanner covered.

- RoleCoverage skips a connection that has declared standby (accepted
  or rejected) or has reported a quota hold.
- New hub capability quota_hold_v1 and a quota_hold message
  (state held/released). The relay sends it on every hold transition
  and restates a live hold after auth_ok, only to hubs that advertise
  the token. standby_declare is not reused: it enrols the relay for
  donated standby dispatch, which is wrong for a quota-held relay.
- Docs: the coverage rules in agent-configuration.md and a new
  quota_hold_v1 section in contributor-relay.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
The "contributor relay covering a contributor-first lane" line was
logged only when a role was first seen. The governor records coverage
for every role whether or not contributor_first is set, so when an
owner switches the flag on for a lane a relay already covers (the usual
order with the General-tab toggle) the record already exists and the
line never appears. In the 2026-11-08 pilot, cover began 12:30:45Z, the
flag was saved 12:31:18Z, and the hive log had no cover line.

coverageRecord now remembers whether the line was logged for the
current cover (cleared while the lane is unflagged), and
SetContributorCoverage logs it once on the first evaluation that sees
the lane flagged and covered. No gate behaviour changes.

Also brings the package header comment in line with RoleCoverage's
standby and quota-hold rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 8, 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/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v6

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

PR Title Relation Files
#17226 🐛 [v6] contribute-hive: forward HIVE_AGENT_ROLE and the quota-guard switches into the contributor container same files src/docs/contributor-relay.md

@hivecommons-hive
hivecommons-hive Bot merged commit 9f50d74 into hivecommons:v6 Nov 8, 2026
69 of 70 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Evidence bundle `#172338fae40c` sha256:f9346b6243f3a4b470d43c8ce6af343c9e8e9b7856a412403d4e128ace5336a7 — download from the dashboard or `hivectl review evidence #17233`.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @Danathar holds role owner and GitHub permission maintain on repo; CI green at 8fae40c.

hivecommons-hive Bot added a commit that referenced this pull request Nov 8, 2026
…lane (#17268)

RoleCoverage counted a relay as covering its role even when task
selection refused it work because its identity had used up its tier's
max_per_hour or max_per_day. The relay stays connected and is refused
every ready with hourly_limit / daily_limit until the window rolls, so
the governor kept the resident agent's kicks withheld while nobody
worked the lane. Same class as the standby / quota-hold gaps #17233
handled.

- Factor the hourly/daily rule out of selectTaskPass into
  tierRateLimitReached (hub.tier_limits[tier], caps <= 0 unlimited,
  hourly checked first). Selection keeps its log lines, decision text
  and refusal reasons.
- RoleCoverage skips a candidate whose identity is at either cap, using
  the same function, after h.mu is released (rateMu only; no selectMu).
- Docs: RoleCoverage comment, governor contributor-first header, and
  the contributor-first coverage list in agent-configuration.md.


Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

Signed-off-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: hivecommons-hive[bot] <280983584+hivecommons-hive[bot]@users.noreply.github.com>
hivecommons-hive Bot added a commit that referenced this pull request Nov 8, 2026
…ing work does not cover a lane (#17284)

RoleCoverage counted a relay as covering its role when the hub would not
hand it work (revoked, or its trust tier in hub.disabled_tiers) and when
every ready it sent was answered no_matching_work. Both stay connected,
so the governor kept the resident agent's kicks withheld while nobody
worked the lane. Seen on hive-wild-mole on 2026-11-08: a relay covered
scanner while selection answered no_matching_work every 30 s. Same class
as #17233 and #17268.

- Factor revoked / disabled tier into tierAccessGateReason (disabled half:
  tierDisabled). resumeGateReason keeps its reasons and order; fresh
  selection's disabled_tiers loop now calls tierDisabled. RoleCoverage
  reads the tier under c.mu and evaluates with h.mu released.
- Record the idle run on the connection: lastIdleReasonSince beside
  lastIdleReason, set on task_unavailable in the ready and yank paths,
  no_matching_work and repo_unmintable folded into one run. Cleared on the
  selection commit, standby dispatch, resume adoption and sendFixTask.
- RoleCoverage skips a relay holding no task that has been answered
  no_matching_work / repo_unmintable for coverageNoWorkWindow (2 min from
  the first answer; the relay retries every 30 s and the governor still
  applies contributor_first_grace on top).
- Docs: RoleCoverage comment, agent-configuration.md coverage list,
  governor header, one drifted citation; changelog fragment.


Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

Signed-off-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Danathar <Danathar@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: hivecommons-hive[bot] <280983584+hivecommons-hive[bot]@users.noreply.github.com>
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/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant