[hivecommons-hive]

Supersedes #14710 (adopted in place, re-homed for DCO repair; original commits by @Karibhou preserved).

Fixes #14678

This branch is #14710's head 591ce65fdfa7 as pushed by @Karibhou (fork Karibhou/hive), unchanged. Last lane reason on the original: dco-missing.

Hive fix agent: rebase this branch on v5, 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.

DCO repair required: this adoption has unsigned non-merge commits and the hive cannot repair them by amending the contributor branch. Re-home the work onto a hive-owned branch from v5: cherry-pick each original commit with git cherry-pick -s (or squash with git commit --author preserving the original author), ensure every replacement commit has Signed-off-by, push the DCO-clean branch, open/keep one superseding PR with the same title, then comment on and close #14710. Suggested replacement commit message:

🐛 fix: pack agents follow the hive's inference gateway

Supersedes #14710 (adopted; re-pushed with DCO sign-off, original authorship preserved).
Fixes #14678

Credit: original work by @Karibhou.

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

• OWNERS

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

[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.

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

[hivecommons-hive]

Style review — no blockers; advisory only.

• src/pkg/dashboard/api_packs.go:1176-1183 — the first sentence of the hiveGatewayBackend doc comment does not parse ("the one inference backend or configured gateway that every operator-picked backend among the enabled agents other than except names, when…"). This is the function whose rule a future maintainer will most need to re-derive; suggest splitting into: (1) which operator-owned backends are considered, (2) the unanimity condition, (3) the majority bar.
• src/pkg/dashboard/api_packs.go:150-151 — "judged on their agents alone" contradicts the function's own doc (:1192-1195): pack-placed agents on the gateway do count toward the majority. The snapshot is about pre-apply state, not operator-only agents; reword to avoid misleading the next reader.
• changelog.d/fixed-pack-agent-follows-hive-gateway.md:1 — a single 132-word sentence, far longer than any sibling fragment (10–89 words). Consider two or three sentences: what changed, the majority/unanimity rule, what is left alone.

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

[hivecommons-hive]

Reviewed (correctness) — no in-scope blocker at 591ce65.

Traced applyPack existing-agent branch (src/pkg/dashboard/api_packs.go:209-241): the gateway move runs before onForeignGateway is computed, so the subsequent model handling sees the new backend, clears the pack model, and the later deny-list branch (:300-312) is a no-op because hiveGatewayBackend already requires BackendAllowed(shared) (:1206). BackendOwner stays pack, so a second apply is idempotent (covered by TestApplyPackMovesPackOwnedAgentOntoHiveGateway). Majority arithmetic checks out for every test roster, including the :1211-1221 exclusion of the agent being placed.

Advisory (not blocking):

• api_packs.go:214 only redirects an agent still on the pack CLI (EqualFold(existing.Backend, packBackend)). Pack-owned agents already moved onto gateway A will not follow a later operator migration to gateway B, even though they are still pack-owned. Documented intent in the comment at :1178-1197, so fine for #14678, but worth a follow-up if "follow" is meant to be ongoing.
• Open question: #14678 says the gateway was set in "the dashboard's overall configuration". The fix keys off per-agent operator-owned backends (api_packs.go:1160-1172, stamped by cliPinValue at api_agent_config.go:514-515). If the reporter's agents reach LiteLLM via an empty/hive-default backend rather than per-agent picks, hiveGatewayBackend returns "" (:1180-1184) and this PR would not change the reviewer's placement. I could not confirm which path the reporter used.

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

[hivecommons-hive]

Hive filed review findings that do not block this PR as backlog items:

• Review backlog (correctness): Repair path cannot move two or more late-added pack-owned CLI agents #14721 (folded into an existing issue) — Review backlog (correctness): Pack-owned agents follow the gateway only from the pack CLI, not across a later gateway change (Review backlog (correctness): Repair path cannot move two or more late-added pack-owned CLI agents #14721)

Cap: 10 backlog item(s) per PR per day.

[hivecommons-hive]

Reviewed — no findings from this perspective.

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

[hivecommons-hive]

docs-currency (read head 591ce65 against its real merge-base 4d8bd73; the supplied merge-base b835abd was stale)

Operator docs do not describe the new placement rule — src/pkg/dashboard/api_packs.go:216-223 (move an existing pack-owned CLI agent onto the hive gateway on the next apply) and :390-395 (create new pack agents on the gateway with model cleared) change what a pack apply does to an operator's roster at every restart, but the only prose describing it is the changelog fragment and the Go doc comment on hiveGatewayBackend (api_packs.go:1176-1196: operator-owned votes, strict-majority bar, pack CLI agents follow). src/docs/agent-configuration.md:655 documents the directly analogous rule for the backends: allow/deny list ("A pack-owned agent already on a now-disallowed backend is moved the same way on the next apply. Backends an operator explicitly chose (operator-owned) are left alone."), and :780 still says pack apply only "fills blanks" — an operator seeing supervisor/brainstorm jump from copilot to LiteLLM after an upgrade has nowhere to look it up. Requested: add a bullet alongside agent-configuration.md:655 (or in the ACMM section at :780) stating the rule — when every operator-picked backend is one inference gateway and the agents on it are a majority of the other enabled agents, pack-owned CLI agents are created on / moved to that gateway with the gateway default model; operator-picked backends are never moved — with the #14678 link.

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

[hivecommons-hive]

Reviewed — no findings from this perspective.

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

[hivecommons-hive]

Delta re-review (docs-currency) — read 591ce65…a28696b.

• Fixed: src/docs/agent-configuration.md:656 now documents the gateway-follow rule (unanimity of operator-owned backends, >½ majority, pack-owned only, no redirect when the pack names a gateway or backends: replaced it); checked against src/pkg/dashboard/api_packs.go:1206-1235 and :1243-1248. The ACMM section (:781) cross-links it and the anchor #disabling-a-backend-spoke-wide exists (:643).
• Still present: src/docs/operations.md:71 — "ACMM packs additionally set backend: copilot, model: claude-sonnet-4-6 …" is unconditional. With this PR a gateway hive places the pack's operations agent on the gateway with no model (api_packs.go:219-227, :396). Suggested: "… set backend: copilot, model: claude-sonnet-4-6 … (on a hive whose agents run on one inference gateway the pack agent follows that gateway instead, with its default model — see agent-configuration)".
• Minor (advisory): the new bullet says a moved agent gets "no model:", but on the move path an operator-owned model is kept (api_packs.go:224-226); "a pack-owned model: is cleared" would be exact.

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

[hivecommons-hive]

Reviewed (style, delta 591ce65…a28696b) — prior findings re-checked at a28696b:

• api_packs.go:1182 hiveGatewayBackend doc comment — fixed, now parses and matches the two-pass logic.
• api_packs.go:150 snapshot comment — fixed, no longer claims the gateway is judged "on their agents alone".
• changelog.d/fixed-pack-agent-follows-hive-gateway.md:1 — improved (one sentence → three) but still ~150 words in a single bullet; advisory only.

One advisory on the rewritten text: the new hiveGatewayBackend comment (api_packs.go:1182-1191) enumerates every "" outcome yet omits the !s.deps.Config.BackendAllowed(shared) return at api_packs.go:1219. Non-blocking.

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

[hivecommons-hive]

Correctness (delta re-review, head a28696b)

Previous finding api_packs.go:214 (follow only from the pack CLI, not across a later gateway change) is partially fixed: the move condition is now existing.BackendIsPackOwned() && !EqualFold(existing.Backend, gw) (src/pkg/dashboard/api_packs.go:220), so a pack-owned agent on an old gateway is a candidate. But the gateway the hive "moved to" is still gated by hiveGatewayBackend's majority bar, which counts every other candidate — including pack-owned agents still sitting on the old gateway — in the denominator (api_packs.go:1226-1235: others++ for all non-except agents, onGateway*2 <= others → "").

Consequence on the real L3+ roster (packs/level-3.yaml: scanner/quality/guide operator-picked, supervisor/brainstorm/reviewer/ci-maintainer pack-owned): after an earlier apply moved the four pack agents onto litellm, the operator moves their three onto vllm. Each pack agent sees 3 on vllm among 6 others → 3*2 <= 6 → "", nothing moves, and because hiveBackends is a pre-apply snapshot (api_packs.go:153) the next restart sees the same roster — permanently stuck on the gateway the hive left. The new TestApplyPackFollowsGatewayChange (pack_gateway_model_test.go:186-209) only passes because it uses the L2 roster (3 pack-owned → 3 of 5). The new changelog line ("a pack-owned agent … on a gateway the hive has since moved off — is moved there on the next restart") and agent-configuration.md:656 state this unconditionally.

This contradicts the stated design at api_packs.go:1196-1198 ("the pack's own … placements cannot veto the move they are the subject of"). Requested fix: in the majority count, skip candidates that are pack-owned and sit on a gateway other than shared (an earlier apply's placement that would itself follow), and add an L3-roster variant of TestApplyPackFollowsGatewayChange. The pack-CLI-minority rule (TestApplyPackKeepsPackBackendWhenOperatorPicksAreMinority) is unaffected by that change.

Prior open question (api_packs.go:1180, hive-default gateway not detected) is unchanged by the delta; advisory only.

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

[hivecommons-hive]

Conclusion: the placement logic looks correct to me; what still blocks this PR is DCO, not code.

What I read at head a28696b:

• hiveGatewayBackend (src/pkg/dashboard/api_packs.go:1198-1232): unanimity over operator-owned backends excluding except, then a strict majority (onGateway*2 <= others → "") over all candidates. Checked the cases the comment promises: one operator-moved agent out of three → 1*2 <= 2 → no move; two of three → 4 > 3 → move. No operator-owned backends at all → shared == "" → no move, so a pack-only hive is untouched.
• gatewayPlacement (:1239-1244) only redirects a CLI pack backend (config.IsCLIBackend, defined in src/crux/config/gateways.go) and leaves allow/deny-replaced placements alone, so it cannot fight packAgentBackend.
• The existing-agent move at :220-229 guards on existing.BackendIsPackOwned() and is persisted by the pre-existing if changed { s.deps.Config.Agents[pa.Name] = existing; … UpdateConfig } at :320-321, so the struct-copy is written back. BackendOwner stays pack, so a later operator pick still wins.
• hiveBackends is snapshotted once before the loop (:153) as the comment says, so agents moved earlier in the same apply do not shift the bar mid-apply.

Blocker: 3 of the 8 commits have no Signed-off-by (38cd38c6, 591ce65f, a28696b3) — the re-home the PR body asks for has not happened yet. Once the branch is DCO-clean this reads as mergeable to me; I have not approved anything.

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

[hivecommons-hive]

Read the full applyPack path at this head, not just the hunks. The change looks correct to me; one open question for the maintainer below, not a defect.

What I verified

• src/pkg/dashboard/api_packs.go:150 snapshots hiveAgentBackends() once before the loop, so an agent this apply moves cannot swing the majority for the next one — the comment matches the code.
• The move on existing agents (api_packs.go:218-227) runs before onForeignGateway is computed at :229, so after the move agentOnForeignGatewayBackend(gw, packBackend) is true and the existing model-clearing block at :243-249 cannot re-apply a pack model. Order is right.
• BackendOwner stays FieldOwnerPack after a move (not re-stamped), which is what lets TestApplyPackFollowsGatewayChange work and keeps the operator-owned guard at :277-290 untouched.
• hiveGatewayBackend checks BackendAllowed(shared), so a gateway the spoke's backends: deny list blocks is never chosen; and the existing "move off denied backend" branch at :287 would otherwise undo it the same apply. No oscillation.
• All 9 commits carry Signed-off-by; #14710 is closed. Sign-off survives the squash shows CANCELLED only on superseded runs.

Open question (not verified either way) — hiveGatewayBackend lets only operatorOwned backends vote (api_packs.go, if … !vote.operatorOwned { continue }). BackendOwner is stamped only by the dashboard API paths (api_agent_config.go:515, :993, api_agent_control.go:207). An agent whose backend: litellm was set by a hand-edited overlay YAML, or through the dashboard before owner stamping existed, has no owner — it counts in others for the majority bar but never establishes shared. In a hive where all gateway agents are in that state (plausibly the #14678 reporter's, on v5.186.4-439 with agents moved "weeks ago"), shared stays "" and the reviewer still lands on copilot. Whether that is the intended conservative boundary ("legacy unowned is never moved" is documented; "legacy unowned does not vote" is not) is a call for @clubanderson or @Karibhou. If it is intended, a one-line note in the agent-configuration.md:656 paragraph would save the next reader the trace.

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

[hivecommons-hive]

Evidence bundle `#147775d76820` sha256:df04f5910e898046f1c4e4e2512249d0cbe4ea42d087c120492046fb6d2aa3e9 — download from the dashboard or `hivectl review evidence #14777`.

[github-actions]

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

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