Skip to content

✨ [v6] feature: contributor-first lanes — a contributor relay covering a role withholds the resident agent's kicks - #16469

Closed
Danathar wants to merge 4 commits into
hivecommons:v6from
Danathar:feat/v6-contributor-first-kicks
Closed

Danathar wants to merge 4 commits into
hivecommons:v6from
Danathar:feat/v6-contributor-first-kicks

Conversation

@Danathar

@Danathar Danathar commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Executive summary

A contributor who runs a relay "acting as" one of the hive's agent roles can now be that lane's primary worker. Set contributor_first: true on the agent and, while a healthy contributor relay is connected for that role, the governor stops kicking the hive's own agent for that lane. The hive's inference budget is no longer spent on work a contributor is already covering. When the contributor goes away, the resident agent resumes on its normal cadence after a short grace (default 10 minutes). Hives that do not set the flag see no change, and budget pause and standby keep their current meaning.

Target: v6.

What this changes

Today a contributor relay with an agent role works in parallel with the resident agent: the governor does not know the relay is there and keeps kicking the resident agent, so operator budget is still spent on that lane. Standby (RFC #7629) is the opposite order on purpose: it only hands out work after a lane is paused for budget.

With this PR, per agent in hive.yaml:

  • contributor_first: true — while at least one connected contributor relay is acting as the role (fresh heartbeat, not in a failure-streak pause), the governor withholds the resident agent's kicks. Cadence kicks, continuous re-kicks, CEL event kicks and crash-recovery resume kicks all respect it: the same four gates that respect an exhausted budget.
  • contributor_first_grace (default 10m) — how long kicks stay withheld after the last relay disappears, so a routine relay reconnect does not flap the resident agent on and off.
  • The Governor section gets a contributor-first tile: "quality covered by alice, resident kicks withheld", or, during the grace, when the resident agent resumes. /api/status carries the same facts as governor.covered_lanes.
  • Replicas (quality-2) and review heads (quality-fast-1) of a contributor-first lane are withheld together with their base agent: coverage is resolved through the base lane a relay acts as, and the tile shows one entry per lane. (Added after the second hive reviewer's finding, fourth commit.)
  • The load fails if the flag is set on a role contributors may not act as (not in hub.contribute_delegatable_roles and not one of the default scanner / quality / outreach), on supervisor, on an agent whose name is not lower-case (relays claim roles in lower case, so it could never be covered), or with a negative grace. A contributor-first lane nobody may claim would sit inert while the operator believes contributors are taking the load.

What does not change

  • Budget and standby. A covered lane is never reported as paused for budget: suppressed_lanes and lane_pause_reasons stay budget-only, so standby dispatch keeps its meaning. The budget gate is checked first, so a lane that is both out of budget and covered reads as paused for budget exactly as before.
  • Who may act as a role (trust tier, grants, the delegatable list) and which issues a relay may take. The governor only reads the result of the contributor path's own admission.
  • A relay that is busy on a task still counts as covering: it is draining the lane, which is the point.
  • The operator's Suspend contributions switch (hub.contribute_suspended) still pauses only contributors. While it is on, no relay counts as covering, so the resident agent keeps working; pausing contributors never pauses the lane. (Added after the hive reviewer's finding, third commit.)
  • Hives that do not set the flag. No default is written into the file, so an existing hive.yaml round-trips unchanged.

How it works

Once per eval tick, before the governor evaluates, the eval cycle asks the contribute hub which roles connected relays are acting as (the effective role after the owner's "Acting as" assignment, a heartbeat inside the WebSocket timeout, no failure-streak pause) and hands the governor a role → logins map. The governor remembers the last sighting per role and withholds while a relay is present or the grace is still running. Coverage transitions (started, cover ended, grace elapsed) are logged once each, not every tick.

Files

  • crux/config/agent_config.go, crux/config/contributor_first.go: the two keys and the default grace.
  • pkg/config/contributor_first.go, pkg/config/validate.go: load-time validation.
  • pkg/governor/contributor_first.go, pkg/governor/governor.go: coverage memory, the gate at the four kick paths, covered_lanes in state and eval history.
  • pkg/dashboard/contribute_coverage.go: the hub's view of who is acting as which role; server.go and status_builder.go: covered_lanes on the status payload.
  • cmd/hive/contributor_first.go, cmd/hive/main_eval_cycle.go, cmd/hive/eval_cycle_seams.go: the per-tick feed and the resume-kick log line.
  • pkg/dashboard/static-src/js/sidebar.js, governor-view.js, agent-detail.js, and the regenerated static/index.html: the tile.
  • docs/agent-configuration.md, docs/contributor-trust-and-roles.md, hive.yaml.example, pkg/dashboard/settings_parity_allowlist.txt, and a changelog fragment.
  • docs/api-reference.md and docs/api-reference/*.md: line-number citations into server.go resynced with the repo's check-api-reference-citations.sh --fix (second commit; the new status struct moved the route registrations down).

Related issues

None. This is an operator-requested feature; there is no tracking issue.

Tests

New tests:

  • pkg/governor/contributor_first_test.go: a covered lane is not due while an uncovered one still is; the flag off ignores coverage; grace then resume on a fixed clock, including a relay returning inside the grace; default grace; the budget gate still wins (the lane stays budget-suppressed); CEL and resume-kick gates; the continuous-mode blocker; report normalisation; GetState returns a copy; replicas and review heads follow their base lane and resume with it; a mixed-case agent name keeps its own grace.
  • pkg/config/contributor_first_test.go: delegatable, undelegatable, supervisor, mixed-case-name and negative-grace cases; wiring into validate(); default grace.
  • pkg/dashboard/contribute_coverage_test.go: stale, roleless, failure-paused and profile-less connections are excluded; role names normalised; nil hub and server; a suspended contribute queue reports no coverage; status rendering.
  • crux/config/contributor_first_test.go: the grace default helper, so the crux/config coverage floor (90%) holds; it had dipped to 89.9% because the helper was only exercised from pkg/config.
  • cmd/hive/contributor_first_test.go: no dashboard means no coverage.
  • dashboard/test/contributor-first-tile.test.js: the tile renders nothing when empty, names the lane and contributors in both variants, grace wording, sorted and escaped output.

Results on this machine:

  • go test ./pkg/governor ./crux/config ./pkg/dashboard ./cmd/hive (full packages, -count=1): all pass. The first full dashboard run failed TestSettingsDialogReferencesEveryHiveYAMLLeaf, which requires every new hive.yaml key to have a Settings control or an allowlist entry. The two keys are hive.yaml-only in this PR, so they are allowlisted next to the standby keys under the same TODO.
  • golangci-lint run on the five packages: 0 issues.
  • go test ./pkg/config: all new tests pass. The one failure is the pre-existing TestGateFailsClosedWithoutIP6Tables, which expects ip6tables to be missing and this host has it installed (the same note as on 🐛 unpark: keep the "What to reply" commands as the last comment, in a green box #16425; the package is otherwise untouched).
  • go vet is clean on the five packages; gofmt is clean on the touched files.
  • node --test: 42 of 45 dashboard JS tests pass, including the new file. The 3 failures are Cannot find module 'ws' / 'express' in contribute.test.js, contributors-authz.test.js and nous-authz.test.js: dependencies are not installed on this machine, and those files are untouched.
  • make dashboard-gen regenerated index.html; TestIndexHTMLIsGenerated passes.

Not run: a live hive with a connected contributor relay. To verify on one: set contributor_first: true on quality, connect a relay acting as quality, confirm the contributor-first tile appears and the resident quality agent gets no kicks; disconnect the relay and confirm the resident agent resumes after the grace.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w

… kicks while a contributor relay covers the role

A contributor relay acting as an agent role used to work in parallel with
the hive's resident agent: the governor never knew the relay was there, so
the hive's own inference budget kept being spent on a lane a contributor
was already covering. Standby (RFC hivecommons#7629) is the opposite order on purpose
and only fires once a lane is paused for budget.

agents.<name>.contributor_first: true makes the connected relay the lane's
primary worker. While at least one relay is acting as the role (fresh
heartbeat, not failure-paused) the governor withholds the resident agent's
kicks at the same four gates that honour an exhausted budget: cadence,
continuous re-kick, CEL event kick and crash-recovery resume kick. Once no
relay has covered the role for contributor_first_grace (default 10m) the
resident agent resumes its normal cadence.

Budget pause and standby are unchanged: a covered lane is never reported
as paused for budget, and the budget gate is checked first. The load fails
when the flag names a role contributors may not act as, so the setting can
never sit inert. The Governor section shows each covered lane and who
covers it; /api/status carries governor.covered_lanes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 3, 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 kellyaa 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/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 3, 2026
…tus-struct addition

FrontendLaneCoverage and the covered_lanes field moved the route
registrations in pkg/dashboard/server.go down by fourteen lines, so the
pkg/dashboard/server.go:NNNN citations in src/docs/api-reference.md and
src/docs/api-reference/*.md drifted. Rewritten with
`bash src/scripts/check-api-reference-citations.sh --fix` (32 citations);
the checker is clean again.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>

@hivecommons-hive hivecommons-hive Bot left a comment

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.

Read the governor, hub and eval-cycle code at 1b7d95c plus the existing admission path (contribute_ws.go:2936-2950, contribute_agent_roles.go:61-96). The core is sound: the gate sits at the same four kick paths as the budget gate, SuppressedLanes/LanePauseReasons really do stay budget-only, coverage is only ever derived from c.role, which is set exclusively after roleClaimAllowed (delegatable role, tier ≥ trusted, grants) or by the owner's SetAssignedAgentRole (contribute_ws.go:2341) — so no relay can self-assign its way into withholding a lane. go build of the four touched packages is clean.

One verified gap — the operator's "Suspend contributions" switch idles the whole lane.

  • src/pkg/dashboard/contribute_select.go:484-489: when hub.contribute_suspended is true, every connected relay is refused work with contribution_suspended. The relays stay connected and keep heartbeating.
  • src/pkg/dashboard/contribute_coverage.go:44-57: RoleCoverage counts a relay as covering if its role is set, its heartbeat is fresh and it is not in a failure-streak pause. It does not consult Hub.ContributeSuspended.
  • Consequence: an operator who pauses contributions on a contributor_first lane gets neither worker — relays get no tasks, and the governor keeps withholding the resident agent for as long as the relays stay connected. The header comment at src/pkg/governor/contributor_first.go:23 ("connected, non-stale, non-suspended relay") promises exactly the check that is missing. Suggested fix: return nil from RoleCoverage (or from Server.ContributorRoleCoverage) when deps.Config.Hub.ContributeSuspended is set, plus a test next to the stale/failure-paused cases in contribute_coverage_test.go.

Severity: medium — opt-in flag, operator-visible via the new tile, but it silently converts a "pause contributors" action into "pause the lane".

Body matches the diff otherwise (the four gates, grace, validation, covered_lanes). No other findings.

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

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v6

This PR conflicts with v6 itself. Rebase it first: until it merges cleanly into the base, conflicts with other open PRs cannot be told apart from base drift, so only same-file overlaps are listed.

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.

No conflicting open PRs or same-file overlaps were found.

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 3, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

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

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Head a524bf8 resolves both findings from the previous hive review; one new, verified CI break remains — a one-line test-harness fix.

Previously blocking (replicas never withheld) — fixed. pkg/governor/contributor_first.go:155-161 adds coverageLane, which maps a derived agent to its ReplicaOf base; contributorCoveredLocked (:190-195) and coveredLanesLocked (:217-229) key on it, and contributorFirstLocked/contributorFirstGraceLocked (:232-243) resolve the lane through baseAgentForLaneLocked (:168-186), which also folds case — so the previous low finding (mixed-case agent name) is covered too. TestContributorFirst_ReplicasAndReviewHeadsFollowTheBaseLane (contributor_first_test.go:259-292) pins the replica and review-head cases.

New, blocking: build-and-test fails because of this diff (correctness, high).
standby_tile_visible.test.js:9-14 rebuilds renderGovernor by grabbing exactly two functions from static/index.html — ['standbyPauseFactsHtml', 'renderGovernor'] — and supplies every other helper via the stubs object (:16-42). This PR adds ${contributorFirstFactsHtml(gov, 'stat')} and ${contributorFirstFactsHtml(gov)} inside renderGovernor (governor-view.js:722, 769), but neither the grab list nor stubs knows that name, so tests 101 and 102 throw ReferenceError: contributorFirstFactsHtml is not defined (run 41731491010, "Dashboard helper tests"). Fix: add 'contributorFirstFactsHtml' to the grab list at :14 (the function lives in the same index.html), or contributorFirstFactsHtml: () => '' to stubs. The PR's own dashboard/test/contributor-first-tile.test.js is unaffected.

Also verified: the hub only reports a lane as covered from c.role (contribute_coverage.go:48), which the previous review traced to roleClaimAllowed/owner assignment, and short-circuits on contributionsSuspended() (:35) — a relay cannot self-assign its way into withholding a lane. The governor gate sits after the budget gate (governor.go:1016-1026) so SuppressedLanes keeps its budget-only meaning for standby. Changelog fragment, hive.yaml.example, agent-configuration.md and contributor-trust-and-roles.md cover the new keys.

Housekeeping: the PR is CONFLICTING with v6 (needs-rebase), so CI is currently running on the stale merge-base; a rebase is needed before the fix above can be confirmed green.

Fork PR — comment only; nothing pushed.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the final delta f24a477 → a524bf8 against the tree, re-ran the red suite locally, and checked the merge against v6. The code is correct; two mechanical items stand between this head and green.

1. build-and-test is red because of this diff, and the fix is one line in a test fixture. pkg/dashboard/standby_tile_visible.test.js:14 builds renderGovernor from index.html by grabbing only ['standbyPauseFactsHtml', 'renderGovernor'] and stubbing every other global explicitly (:16-41). The new call at governor-view.js:722 (${contributorFirstFactsHtml(gov, 'stat')}) is neither grabbed nor stubbed, so the harness throws ReferenceError: contributorFirstFactsHtml is not defined for both standby tests. Verified locally: adding the function to the grab list makes all 3 tests pass (contributorFirstFactsHtml in sidebar.js:142-157 ends with the 4-space } the grab regex requires):

--- a/src/pkg/dashboard/standby_tile_visible.test.js
+++ b/src/pkg/dashboard/standby_tile_visible.test.js
-const src = ['standbyPauseFactsHtml', 'renderGovernor'].map(grab).join('\n');
+const src = ['standbyPauseFactsHtml', 'contributorFirstFactsHtml', 'renderGovernor'].map(grab).join('\n');

2. The v6 conflict is only the citation resync. git merge-tree origin/v6 a524bf8 conflicts in exactly five files: docs/api-reference.md and docs/api-reference/{auth,dashboard-misc,health-status-events,snapshots-and-style}.md — the line-number citations commit 1b7d95c regenerated, which v6 has since moved again. Every .go/.js file auto-merges. After rebasing, re-run bash scripts/check-api-reference-citations.sh --fix and take its output rather than hand-resolving.

The replica fix in a524bf8 closes the earlier blocking finding. coverageLane (pkg/governor/contributor_first.go:155-161) folds a derived agent to ReplicaOf, which pkg/config/config.go:366 sets on every derived agent (replicas and review heads alike), so quality-2/quality-fast-1 now hit the same g.coverage["quality"] record the hub writes (contribute_coverage.go:48,86). baseAgentForLaneLocked (:168-183) prefers the base agent and falls back to a derived one for grace/flag lookup, and coveredLanesLocked (:218-230) keys output by lane so the tile shows one entry. The mixed-case case is now rejected at load (pkg/config/contributor_first.go:34-36) rather than silently expiring. Every Go shard and coverage passed at this head in CI; go test is not runnable from this host, so that is the evidence I relied on.

Fork PR — comment only; nothing pushed. Since clubanderson has asked the hive to adopt this PR, whoever carries the adoption copy should fold item 1 into it (item 2 falls out of the rebase).

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness re-review of a524bf8 (delta since f24a477).

Previous findings: replicas never withheld — fixed in the governor (coverageLane/baseAgentForLaneLocked, governor/contributor_first.go:155-185, test TestContributorFirst_ReplicasAndReviewHeadsFollowTheBaseLane); mixed-case grace — fixed (case-folded lane match at governor/contributor_first.go:170-172 plus the loader rejection at config/contributor_first.go:34-36).

One new in-scope problem, in the fix itself:

The config loader still rejects any contributor-first lane that has replicas or review heads, so the new governor replica support is unreachable.
Load calls ExpandAgentReplicas before validateWithOptions (pkg/config/load.go:117-121). Expansion copies the whole base struct into quality-2 / quality-fast-1, including ContributorFirst=true (pkg/config/config.go:359-366, pkg/config/review_heads.go:74-91). validateContributorFirst then iterates every agent in c.Agents (pkg/config/contributor_first.go:19), and for the derived entry IsContributeRoleDelegatable("quality-2") is an exact-name set lookup (pkg/config/hub_config.go:610-629), so the load fails with agent quality-2: contributor_first is true but "quality-2" is not a role contributors may act as. The governor test builds its agent map by hand and never goes through Load, which is why it passes.

Suggested fix — validate the flag once, on the base entry (the lane), and skip derived agents:

		if !agent.ContributorFirst {
			continue
		}
		if agent.ReplicaOf != "" {
			// Replicas and review heads copy the base's flag; the base entry
			// is validated on its own under the lane name.
			continue
		}
		role := strings.ToLower(strings.TrimSpace(name))

and add a config test that sets Replicas: 2 (and a review head) on a contributor-first agent, runs ExpandAgentReplicas() and then validateContributorFirst(), expecting no error.

…; cover the crux grace helper

Review finding on hivecommons#16469: with hub.contribute_suspended set, the hub
refuses work to every relay while their sockets stay up, so RoleCoverage
kept reporting the connected relays as covering the lane and the governor
kept withholding the resident agent. Pausing contributors became pausing
the lane. RoleCoverage now returns no coverage while contributions are
suspended, mirroring the task-selection gate, with a test next to the
stale and failure-paused cases.

The crux/config coverage floor (90%) tripped at 89.9% because the new
ContributorFirstGraceOrDefault helper was only exercised from pkg/config;
it now has its own table test in crux/config (90.3%).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
@Danathar

Danathar commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, the suspend-switch gap was real. Addressed in f24a477:

  • RoleCoverage now returns no coverage while hub.contribute_suspended is set, mirroring the task-selection gate in contribute_select.go, so pausing contributors never pauses the lane. Test: TestRoleCoverage_SuspendedContributionsCoverNothing, next to the stale and failure-paused cases.
  • The governor header comment now says what the gate actually checks (fresh heartbeat, no failure-streak pause, contributions not suspended).
  • Same push also restores the crux/config coverage floor (89.9% → 90.3%) with a table test for the grace default helper, which the first run's coverage gate flagged.

PR body updated to match.

…ir base lane; case-insensitive agent lookup

Second review finding on hivecommons#16469: replicas (quality-2) and review heads
(quality-fast-1) copy the base agent's contributor_first flag, but the hub
reports coverage under the BASE role a relay acts as while the gate looked
the record up by each agent's own name. Only replica 1 was ever withheld,
and the tile still claimed the lane was covered. The gate now resolves
every agent to its coverage lane through ReplicaOf, so a covered lane
withholds all of its derived agents, and covered_lanes publishes one entry
per lane rather than per replica.

Third finding: SetContributorCoverage looked the lane's grace up by the
lower-cased role while agents are keyed by their raw YAML name, so a
mixed-case agent name expired on the default grace instead of its own.
Agent lookups are now case-insensitive, and the loader additionally
rejects a mixed-case contributor_first name, because relays claim roles in
lower case and such an agent could never be covered at all.

Tests: a replica/review-head lane test and a mixed-case grace test in
pkg/governor, and the new load-error case in pkg/config.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>

@hivecommons-hive hivecommons-hive Bot left a comment

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.

Delta re-review (correctness) of 1b7d95c → f24a477: the suspend-switch gate is correct — RoleCoverage short-circuits on contributionsSuspended() (contribute_coverage.go:34, 92-95), which mirrors the existing unsynchronized read in contribute_select.go:346-347, and TestRoleCoverage_SuspendedContributionsCoverNothing covers both the suspended and resumed paths. No new defects in the delta.

Still present (blocking): replicas of a contributor-first lane are never withheld. The delta does not touch the gate. pkg/config/config.go:361 still does derived := agent (so quality-2, quality-3 inherit ContributorFirst, with derived.ReplicaOf = name at :366), while the hub keys coverage by role ("quality", contribute_coverage.go:48) and the gate keys by the agent's own name:

rec, ok := g.coverage[strings.ToLower(strings.TrimSpace(agentName))]  // pkg/governor/contributor_first.go:160

So only replica 1 is withheld; the others are kicked on cadence while CoveredLanes reports the lane as covered. Suggested fix — resolve replicas to their base lane in the three lookups:

--- a/src/pkg/governor/contributor_first.go
+++ b/src/pkg/governor/contributor_first.go
@@ func (g *Governor) contributorCoveredLocked(agentName string) (LaneCoverage, bool) {
 	ac, ok := g.agents[agentName]
 	if !ok || !ac.ContributorFirst {
 		return LaneCoverage{}, false
 	}
-	rec, ok := g.coverage[strings.ToLower(strings.TrimSpace(agentName))]
+	rec, ok := g.coverage[coverageKey(agentName, ac)]
 	if !ok {
 		return LaneCoverage{}, false
 	}
@@
+// coverageKey is the role the hub reports coverage under: the base lane for a
+// replica (quality-2 → quality), the agent's own name otherwise.
+func coverageKey(agentName string, ac config.AgentConfig) string {
+	if ac.ReplicaOf != "" {
+		return strings.ToLower(strings.TrimSpace(ac.ReplicaOf))
+	}
+	return strings.ToLower(strings.TrimSpace(agentName))
+}

contributorFirstLocked/contributorFirstGraceLocked (:196-206) take the lower-cased role, so they need to consider any agent whose coverageKey matches (base lane or its replicas) rather than g.agents[role] alone — otherwise the "covering a contributor-first lane" log/grace still only sees the base agent. A replicas: 2 case in contributor_first_test.go (currently no replica coverage, contributor_first_test.go:11-28) would pin it.

Still present (low): mixed-case agent name expires its record after the default grace — SetContributorCoverage looks up g.agents[role] with role lower-cased (contributor_first.go:103, 141, 201-205) while g.agents is keyed by the raw YAML name; the same coverageKey normalisation, or rejecting mixed-case names in validateContributorFirst, closes it.

Fork PR — comment only; nothing pushed.

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

@Danathar

Danathar commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Both of reviewer-2's findings addressed in a524bf8:

  1. Replicas and review heads. The gate now resolves each agent to its coverage lane through ReplicaOf (coverageLane in pkg/governor/contributor_first.go), so quality-2 and quality-fast-1 are withheld with quality, and covered_lanes publishes one entry per lane rather than per replica. Test: TestContributorFirst_ReplicasAndReviewHeadsFollowTheBaseLane (withheld together, CEL gate on the replica, resume together after the lane's grace).
  2. Mixed-case agent names. Agent lookups for the lane's flag and grace are now case-insensitive (baseAgentForLaneLocked), so a Quality agent with contributor_first_grace: 30m keeps 30m (TestContributorFirst_MixedCaseAgentNameKeepsItsGrace). The loader also now rejects a mixed-case contributor_first name outright, since relays claim roles in lower case and such an agent could never be covered (same class as the undelegatable-role check; new case in TestValidateContributorFirst).

PR body updated. The overlap with #16378 is only the api-reference citation files, which the citation fixer regenerates; whichever lands second re-runs check-api-reference-citations.sh --fix.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • check-failure

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

build-and-test at a524bf8 is PR-local (v6 head is green on the same check — run 41730306074). The failure is in the pre-existing standby-tile test, not in your new dashboard/test/contributor-first-tile.test.js:

not ok 101 - a paused lane renders a visible standby tile in the Governor section
not ok 102 - no paused lane renders no standby tile
  error: 'contributorFirstFactsHtml is not defined'  (ReferenceError)

Cause: src/pkg/dashboard/standby_tile_visible.test.js assembles renderGovernor with new Function(...) from an explicit list of grabbed sources + stubs (src/pkg/dashboard/standby_tile_visible.test.js:14-42). The new ${contributorFirstFactsHtml(gov, 'stat')} call you added next to standbyPauseFactsHtml in governor-view.js:722 is therefore unresolved inside that sandbox.

Smallest fix — add it to the stub map so the standby test stays focused on the standby tile:

--- a/src/pkg/dashboard/standby_tile_visible.test.js
+++ b/src/pkg/dashboard/standby_tile_visible.test.js
@@ -34,6 +34,7 @@ const stubs = {
   fleetRunStatHtml: () => '',
+  contributorFirstFactsHtml: () => '',
   formatGovernorNextRun: () => '',

(Alternative, if you'd rather exercise the real tile alongside standby: ['standbyPauseFactsHtml', 'contributorFirstFactsHtml', 'renderGovernor'].map(grab) on line 14 — works as long as the new function closes with the same 4-space } the grab regex expects.)

Fork branch, so I can't push this; flagging for you to apply with your next push.


🐝 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 github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 3, 2026
@hivecommons-hive hivecommons-hive Bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 3, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson asked the hive to adopt this pull request now, without waiting for its author's hive. The hive opens its own PR carrying the author's commits and sign-off unchanged on the pass now running; this PR closes when that copy merges.

@hivecommons-hive hivecommons-hive Bot added adoption/supersede Owner-delegate request: adopt now in supersede mode and removed adoption/supersede Owner-delegate request: adopt now in supersede mode labels Nov 3, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersede failed: the hive could not open a fresh PR with these commits. Merging v6 into the copy branch hive/adopt-16469 (at a524bf8c9127) stopped on a git conflict, so no superseding PR was opened and this PR stays open.

Rebase this branch onto v6 (or push a merge of it) and the lane re-evaluates the new head; a new adoption/supersede label then retries the supersede. Reason: supersede-conflict.

1 similar comment
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersede failed: the hive could not open a fresh PR with these commits. Merging v6 into the copy branch hive/adopt-16469 (at a524bf8c9127) stopped on a git conflict, so no superseding PR was opened and this PR stays open.

Rebase this branch onto v6 (or push a merge of it) and the lane re-evaluates the new head; a new adoption/supersede label then retries the supersede. Reason: supersede-conflict.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Superseded by hive: re-authored as #16518 with the same commits and sign-off because CI stayed red and the author was unavailable. This PR is closed; if #16518 fails, hive reopens it.

@hivecommons-hive hivecommons-hive Bot added the hive/superseded Closed by Hive: a different merged PR already landed this change label Nov 4, 2026
@hivecommons-hive hivecommons-hive Bot closed this Nov 4, 2026
hivecommons-hive Bot pushed a commit that referenced this pull request Nov 4, 2026
…; cover the crux grace helper

Review finding on #16469: with hub.contribute_suspended set, the hub
refuses work to every relay while their sockets stay up, so RoleCoverage
kept reporting the connected relays as covering the lane and the governor
kept withholding the resident agent. Pausing contributors became pausing
the lane. RoleCoverage now returns no coverage while contributions are
suspended, mirroring the task-selection gate, with a test next to the
stale and failure-paused cases.

The crux/config coverage floor (90%) tripped at 89.9% because the new
ContributorFirstGraceOrDefault helper was only exercised from pkg/config;
it now has its own table test in crux/config (90.3%).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
hivecommons-hive Bot pushed a commit that referenced this pull request Nov 4, 2026
…ir base lane; case-insensitive agent lookup

Second review finding on #16469: replicas (quality-2) and review heads
(quality-fast-1) copy the base agent's contributor_first flag, but the hub
reports coverage under the BASE role a relay acts as while the gate looked
the record up by each agent's own name. Only replica 1 was ever withheld,
and the tile still claimed the lane was covered. The gate now resolves
every agent to its coverage lane through ReplicaOf, so a covered lane
withholds all of its derived agents, and covered_lanes publishes one entry
per lane rather than per replica.

Third finding: SetContributorCoverage looked the lane's grace up by the
lower-cased role while agents are keyed by their raw YAML name, so a
mixed-case agent name expired on the default grace instead of its own.
Agent lookups are now case-insensitive, and the loader additionally
rejects a mixed-case contributor_first name, because relays claim roles in
lower case and such an agent could never be covered at all.

Tests: a replica/review-head lane test and a mixed-case grace test in
pkg/governor, and the new load-error case in pkg/config.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
hivecommons-hive Bot added a commit that referenced this pull request Nov 4, 2026
…g a role withholds the resident agent's kicks (#16518)

* ✨ [v6] feature: contributor-first lanes withhold the resident agent's kicks while a contributor relay covers the role

A contributor relay acting as an agent role used to work in parallel with
the hive's resident agent: the governor never knew the relay was there, so
the hive's own inference budget kept being spent on a lane a contributor
was already covering. Standby (RFC #7629) is the opposite order on purpose
and only fires once a lane is paused for budget.

agents.<name>.contributor_first: true makes the connected relay the lane's
primary worker. While at least one relay is acting as the role (fresh
heartbeat, not failure-paused) the governor withholds the resident agent's
kicks at the same four gates that honour an exhausted budget: cadence,
continuous re-kick, CEL event kick and crash-recovery resume kick. Once no
relay has covered the role for contributor_first_grace (default 10m) the
resident agent resumes its normal cadence.

Budget pause and standby are unchanged: a covered lane is never reported
as paused for budget, and the budget gate is checked first. The load fails
when the flag names a role contributors may not act as, so the setting can
never sit inert. The Governor section shows each covered lane and who
covers it; /api/status carries governor.covered_lanes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>

* 🐛 fix(contributor-first): a suspended contribute queue covers nothing; cover the crux grace helper

Review finding on #16469: with hub.contribute_suspended set, the hub
refuses work to every relay while their sockets stay up, so RoleCoverage
kept reporting the connected relays as covering the lane and the governor
kept withholding the resident agent. Pausing contributors became pausing
the lane. RoleCoverage now returns no coverage while contributions are
suspended, mirroring the task-selection gate, with a test next to the
stale and failure-paused cases.

The crux/config coverage floor (90%) tripped at 89.9% because the new
ContributorFirstGraceOrDefault helper was only exercised from pkg/config;
it now has its own table test in crux/config (90.3%).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>

* 🐛 fix(contributor-first): withhold replicas and review heads with their base lane; case-insensitive agent lookup

Second review finding on #16469: replicas (quality-2) and review heads
(quality-fast-1) copy the base agent's contributor_first flag, but the hub
reports coverage under the BASE role a relay acts as while the gate looked
the record up by each agent's own name. Only replica 1 was ever withheld,
and the tile still claimed the lane was covered. The gate now resolves
every agent to its coverage lane through ReplicaOf, so a covered lane
withholds all of its derived agents, and covered_lanes publishes one entry
per lane rather than per replica.

Third finding: SetContributorCoverage looked the lane's grace up by the
lower-cased role while agents are keyed by their raw YAML name, so a
mixed-case agent name expired on the default grace instead of its own.
Agent lookups are now case-insensitive, and the loader additionally
rejects a mixed-case contributor_first name, because relays claim roles in
lower case and such an agent could never be covered at all.

Tests: a replica/review-head lane test and a mixed-case grace test in
pkg/governor, and the new load-error case in pkg/config.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WcWm7sQjJ5QDk9LVqL115w
Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>

* test: stub contributorFirstFactsHtml in standby tile isolation test

Hive-Fix-Attempt: 1/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 📖 docs: resync api-reference source citations after rebase onto v6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* chore: retrigger CI after proxy.golang.org stream flake in build-hub (linux/amd64)

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

---------

Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: Douglas Baggett <doug.baggett@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@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. hive/superseded Closed by Hive: a different merged PR already landed this change needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant