Skip to content

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

Merged
hivecommons-hive[bot] merged 6 commits into
v6from
hive/adopt-16469
Nov 4, 2026
Merged

hivecommons-hive[bot] merged 6 commits into
v6from
hive/adopt-16469

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersedes #16469 (adopted after CI went red and the contributor was unavailable; original commits by @Danathar preserved).

This branch is #16469's head a524bf8c9127 as pushed by @Danathar (fork Danathar/hive), unchanged. Last lane reason on the original: label:needs-rebase.

Hive fix agent: rebase this branch on v6, fix the failing checks / review asks, and push to THIS branch. Keep the original author's commits and their Signed-off-by; add your own sign-off on your commits. Do not open another PR.

Conflicts with v6: the contributor head could not be replayed onto the base, so this copy opened as it is and the hive's fixer is resolving the conflicts on this branch (rebase-resolve episode, two attempts). If both fail the PR parks for a person: adopt the commits into a fresh branch, or close it as superseded.

@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 clubanderson 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 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. labels Nov 4, 2026
@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) labels Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 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
#16524 🌱 chore: v5 → v6 top-up (2026-11-03) CONFLICT src/docs/api-reference.md
src/docs/api-reference/health-status-events.md
src/docs/api-reference/snapshots-and-style.md

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Security perspective (read at head a524bf8, plus merge-base contribute_agent_roles.go / contribute_failure_streak.go / contribute_ws.go).

Medium — an idle relay holds a contributor-first lane indefinitely; the hold is available to contributor-tier identities with no grant.

src/pkg/dashboard/contribute_coverage.go:49-66 counts a connection as covering a role when its role is set, its pong is fresh, and it is not in a failure-streak pause. Nothing requires the relay to have claimed or finished any work. Dispatch is pull-based (contribute_ws.go:2550 ready), and the streak only arms on hub-timed task_failed (contribute_failure_streak.go:13-28), so a relay that authenticates with HIVE_AGENT_ROLE=quality and simply never sends ready is "covering" forever — the governor then withholds the resident agent at every gate (governor.go:1024, :1206, :1282, :1410) and the grace in contributor_first.go:199 only ever starts once the socket drops.

Pre-PR, the lowest tier that can claim scanner/quality/outreach is contributor with no operator grant (contribute_agent_roles.go:10-13, :95-99). This PR gives that tier a new lever over hive-owned capacity: one connected-but-inactive relay per lane silences the resident agent. Opt-in and visible on the tile, but the docs (src/docs/agent-configuration.md, "Who may act as the role") say a busy relay counts and do not say an idle one does.

Requested change (pick one, first preferred): in RoleCoverage, require evidence of work — e.g. c.currentTask != nil or a last ready/task_complete within contributor_first_grace — before a connection counts; or gate coverage on trusted-or-above / an explicit contributor_first grant. Either way, add a test for the connected-never-claims case and state the behaviour in the docs.

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

@hivecommons-hive

hivecommons-hive Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor Author

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

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

Correctness review @ a524bf8 (contributor head, pre-rebase)

contributor_first: true fails config load for any agent with replicas > 1 or review_heads.

Load runs ExpandAgentReplicas() before validateWithOptions() (src/pkg/config/load.go:117–121). Expansion copies the whole base struct into every derived agent — derived := agent (src/pkg/config/config.go:361; same in expandReviewHeads, src/pkg/config/review_heads.go:74) — so quality-2 / quality-fast-1 carry ContributorFirst: true. The new validateContributorFirst then iterates all of c.Agents with no ReplicaOf skip (src/pkg/config/contributor_first.go:19–41) and calls c.Hub.IsContributeRoleDelegatable("quality-2"), which is an exact-name set lookup (src/pkg/config/hub_config.go:610–630) → the load fails with "…"quality-2" is not a role contributors may act as…".

This contradicts the PR's own design: coverageLane / baseAgentForLaneLocked exist precisely so replicas and review heads are withheld together with their base (src/pkg/governor/contributor_first.go:148–182), and TestContributorFirst_ReplicasAndReviewHeadsFollowTheBaseLane asserts that — but it hand-builds the replica AgentConfig, so the load-time rejection is never exercised. TestValidateContributorFirst has no Replicas/ReviewHeads case either.

Fix: in validateContributorFirst, continue when agent.ReplicaOf != "" (the base agent is the one validated; derived agents inherit), and add a Replicas: 2 case to TestValidateContributorFirst that goes through ExpandAgentReplicas() + validate().

(CI red / merge conflict are already being handled by the fixer per the PR body; not re-reported.)

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

Intent-alignment review (head a524bf8c, the unchanged copy of #16469).

The core feature matches the PR body: the four kick gates (governor.go:1016-1026, :1203-1208, :1277-1284, :1407-1412), coverage memory with grace (pkg/governor/contributor_first.go), the hub feed excluding stale / roleless / failure-paused relays and a suspended queue (pkg/dashboard/contribute_coverage.go), and the per-tick wiring (cmd/hive/main_eval_cycle.go:866-871) are all present.

One claim in the body is not deliverable through config load — replicas / review heads of a contributor-first lane.

The body says replicas (quality-2) and review heads (quality-fast-1) are withheld together with their base agent, and the governor code supports it via coverageLane (pkg/governor/contributor_first.go). But such a config never loads:

  • ExpandAgentReplicas runs before validateWithOptions (pkg/config/load.go:117-123), and derived agents are struct copies of the base (pkg/config/config.go:361-369, review_heads.go:75-90), so quality-2 / quality-fast-1 carry ContributorFirst: true.
  • validateContributorFirst (pkg/config/contributor_first.go:18-44) iterates every agent with no ReplicaOf skip and calls c.Hub.IsContributeRoleDelegatable(role) with the derived name. That is an exact set lookup (pkg/config/hub_config.go:628-630), so "quality-2" → false → agent quality-2: contributor_first is true but "quality-2" is not a role contributors may act as.

Net effect: contributor_first: true is only usable on an agent with replicas: 1 and no review_heads; the replica/head behaviour the body advertises (and pkg/governor/contributor_first_test.go exercises by constructing agent maps directly) is unreachable in practice. pkg/config/contributor_first_test.go has no replica case, so nothing caught it.

Requested change: in validateContributorFirst, continue when agent.ReplicaOf != "" (the base agent is validated; derived agents inherit the verdict), and add a replicas: 2 / review_heads case to TestValidateContributorFirst that loads cleanly. Everything else in this perspective reads as aligned with the stated intent.

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

The governor/hub logic reads correct to me; the red build-and-test is caused by this diff and has a one-line fix.

Finding (medium, correctness/test adequacy) — src/pkg/dashboard/static/index.html:11791 + src/pkg/dashboard/standby_tile_visible.test.js:7-42

renderGovernor now calls ${contributorFirstFactsHtml(gov)} (index.html:11791, metric variant; the 'stat' variant at :26947). The pre-existing isolation test standby_tile_visible.test.js evaluates renderGovernor with new Function('document', ...names, src + '; return renderGovernor;') (line 29) and supplies every helper it calls from the stubs object (lines 7-42: fleetRunStatHtml, renderBudgetBar, renderCadenceMatrix, …). contributorFirstFactsHtml is not in that list and this PR does not touch the file, so the two tests at :102 and :113 die with ReferenceError: contributorFirstFactsHtml is not defined — that is exactly what CI run 41731491010 ("Dashboard helper tests", subtests 101/102) reports.

Fix: add contributorFirstFactsHtml: () => '', to the stubs object next to fleetRunStatHtml. The new dashboard/test/contributor-first-tile.test.js is unaffected (it extracts the function and injects its own esc), and it exercises the tile itself.

What I verified and found sound

  • pkg/governor/contributor_first.go: coverage is keyed by coverageLane (base of ReplicaOf, case-folded) so replicas/review heads are withheld with their base; grace is tracked in SetContributorCoverage via lastSeen and the record is deleted only after contributorFirstGraceLocked elapses; since survives a within-grace return.
  • governor.go:1016-1026: the gate runs after the budget gate and does not write SuppressedLanes/LanePauseReasons, so standby's "paused for budget" meaning is preserved as the header comment promises. The same gate is applied to the continuous blocker (:1206), CEL event kicks (:1280) and crash-recovery resume (:1410), so no kick path bypasses it.
  • pkg/dashboard/contribute_coverage.go: c.role is the effective role (contribute_ws.go:2341, c.role = effectiveRole), freshness uses the same wsHeartbeatTimeout (90s) as contribute_fleet.go:82, and the failure-streak ledger is consulted with h.mu released. contributionsSuspended returning nil coverage is the right call — a suspended hub covers nothing.
  • pkg/config/contributor_first.go rejects mixed-case names, supervisor, non-delegatable roles and negative grace at load, so the flag can never be silently inert.

Separately, the branch is CONFLICTING with v6 (the adoption body says the fixer is on it); nothing above depends on the rebase.

hive/awaiting-ci: pushed an empty signed commit to retrigger CI after the proxy.golang.org stream flake in build-hub (linux/amd64) exhausted the merge request on abf3c95. 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

Evidence bundle `#165186163d9e` sha256:d7d982a830aeacc32fb843713d322fa18396f65a996be4e7f506cebe4b2edf34 — download from the dashboard or `hivectl review evidence #16518`.

Danathar and others added 4 commits November 3, 2026 22:03
… 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>
…; 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>
…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>
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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 4, 2026
@github-actions github-actions Bot added copilot conflicts-with-open-pr Open PR has a merge conflict with another open PR labels Nov 4, 2026
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 4, 2026
@hivecommons-hive hivecommons-hive Bot added the stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it label Nov 4, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Scanner triage at abf3c95: the only red check, build-hub (linux/amd64), failed inside the Docker go build step with golang.org/x/text@v0.43.0: read https://proxy.golang.org/...: stream error: INTERNAL_ERROR; received from peer (run 41764928359). That is a module-proxy transport failure, not a diff cause — the arm64 build-hub and every other build lane on the same SHA passed. No code change to make; deferring for a fresh run. 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

…(linux/amd64)

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 4, 2026
@hivecommons-hive
hivecommons-hive Bot merged commit 84e2e63 into v6 Nov 4, 2026
88 of 93 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the hive/adopt-16469 branch November 4, 2026 07:38
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

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

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

@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) labels Nov 4, 2026
hivecommons-hive Bot pushed a commit that referenced this pull request Nov 5, 2026
…_first_grace (#16772)

The contributor-first lane keys (#16518) were hive.yaml-only, so on a
hub-hosted spoke only the hub operator could switch a lane. The agent's
General tab now has a Contributor-first toggle and a Contributor-first
grace field.

- config: the per-agent body of validateContributorFirst is exported as
  ValidateContributorFirstAgent (validateContributorFirst calls it), plus
  ContributorFirstDelegatable for the panel. The load and the API refuse
  with the same message.
- API: GET general carries contributorFirst, contributorFirstGrace
  (seconds, 0 when unset) and contributorFirstDelegatable. PUT general
  accepts the two keys, validates the copy before anything persists, and
  answers 400 with the load's message on a refusal. 0 clears the grace to
  the 10m default; omitted keys are left alone.
- UI: the toggle is disabled for a role contributors may not act as, with
  one muted line naming the fix; both controls carry help marks and YAML
  hints. Not shown when creating an agent.
- The two TODO #11854 parity allowlist lines are removed; docs and a
  changelog fragment say the tab exposes both keys.

No governor change: the save already calls Governor.UpdateAgents, and a
test shows a covered lane is withheld on the next evaluation.


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

Signed-off-by: Douglas Baggett <doug.baggett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR conflicts-with-open-pr Open PR has a merge conflict with another open PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. 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