Skip to content

🐛 [v6] contribute-hive: forward HIVE_AGENT_ROLE and the quota-guard switches into the contributor container - #17226

Merged
hivecommons-hive[bot] merged 4 commits into
hivecommons:v6from
Danathar:fix/v6-forward-agent-role
Nov 8, 2026
Merged

hivecommons-hive[bot] merged 4 commits into
hivecommons:v6from
Danathar:fix/v6-forward-agent-role

Conversation

@Danathar

@Danathar Danathar commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Three settings that contributors are told to set before just contribute-hive did nothing in the default container mode or in krun mode, because they never reached the relay inside the container:

  • HIVE_AGENT_ROLE, the spoke-agent lane the relay asks for. The relay connected with no role, so a contributor-first lane was never covered.
  • HIVE_CONTRIBUTOR_QUOTA_GUARD. The guard's hold banner says "Set HIVE_CONTRIBUTOR_QUOTA_GUARD=off at launch to opt out", and that did nothing.
  • HIVE_CONTRIBUTOR_QUOTA_POOL_DIR. The banner's just contribute-quota continue-once and the other scoped controls need it, and they did nothing either.

This PR passes all three into the container. The pool directory is mounted, not just named, so the host's just contribute-quota and the relay in the container really share it. In the pilot, the only thing that worked was adding export ...=off lines to contributor.env by hand.

What went wrong

  • contribute-hive in container mode starts the container with an explicit list of -e variables. None of the three were on it. PROVIDER_ENV_ARGS only carries provider credentials.
  • Inside the container, bin/contributor-agent.sh sources contributor.env without set -a, so a plain NAME=value line there was not exported to the relay either.
  • Local mode already worked for all three. The recipe sources contributor.env under set -a and starts the relay as a child process, so the relay inherits them.

For the role: the landing page (contribute_landing.go) and src/docs/contributor-relay.md ("Acting as a spoke agent role") both say to export HIVE_AGENT_ROLE. The relay reads it and sends it as auth_response.role.

The quota guard

Two things were broken on top of the missing -e entries:

  1. The container cannot use the host's path. just contribute-quota … runs on the host and writes an override file into HIVE_CONTRIBUTOR_QUOTA_POOL_DIR. The relay reads overrides from its own HIVE_CONTRIBUTOR_QUOTA_POOL_DIR. Passing the host path into the container would point the relay at a directory that does not exist in there.
  2. just contribute-quota dropped contributor.env. It sources the file without set -a, so the node control never saw a pool dir set there (it refused: "HIVE_CONTRIBUTOR_QUOTA_POOL_DIR is not set"). It also never saw AGENT_BACKEND, which is part of the pool key. With the pool dir exported in the shell, it wrote under the empty-backend key (6e340b9c…) while a codex relay reads d6316145…, so the override was silently ignored.

Choice: mount the directory (option a), not just a banner warning (option b). The change is small and uses the existing mount pattern, and without it the banner sends container users to a command that cannot work. What the recipe does now:

  • When HIVE_CONTRIBUTOR_QUOTA_POOL_DIR is set, it creates the directory, resolves it to an absolute path (docker would treat a relative one as a named volume), mounts it at /home/dev/.hive-quota-pool, and passes that path to the relay with -e. The in-container quota publisher reads the same variable, so it writes its reading where the relay looks.
  • Docker gets no volume suffix, like the other docker mounts. Podman, and krun (which goes through podman), get the shared :z SELinux label rather than the private :Z the other mounts use. The pool is meant to be shared by every relay on the account, and a second container's :Z relabel would lock the first container out.
  • HIVE_CONTRIBUTOR_QUOTA_POOL_ACCOUNT is also part of the pool key, so it is forwarded too. It is passed by name only (-e NAME), so the account value stays out of the runtime argv, the same way provider keys are passed.
  • contributor-agent.sh keeps the -e mount path when contributor.env names the host path. This uses the same "docker -e wins over contributor.env" pattern the script already uses for AGENT_BACKEND.
  • contribute-quota now sources contributor.env under set -a, so it sees the same pool dir, account and backend as the relay.
  • HIVE_CONTRIBUTOR_QUOTA_GUARD is forwarded with the same ${VAR:+-e VAR=…} pattern as the role.

Nothing changes when these variables are unset: the launch command is byte for byte the same, and the golden argv checks still match.

One limit, documented in contributor-relay.md: the pool key includes the backend. If you launch with a backend argument that differs from AGENT_BACKEND in contributor.env, run the controls as AGENT_BACKEND=<backend> just contribute-quota ….

What changes

  • Justfile, contribute-hive: forwards HIVE_AGENT_ROLE and HIVE_CONTRIBUTOR_QUOTA_GUARD, and adds the pool-dir mount and its -e arguments. krun mode uses the same run command, so it is covered. The only other run is the krun preflight smoke container, which never starts the relay.
  • Justfile, contribute-quota: sources contributor.env under set -a.
  • bin/contributor-agent.sh: the -e pool dir wins over contributor.env. Adds a test hook that prints the result and exits before anything starts, like the existing hub-relocation hook.
  • No change to the relay, the hub, or role validation. The hub still refuses a role the contributor is not allowed (roleClaimAllowed).

Files

  • Justfile: the container launch and contribute-quota, with comments explaining why.
  • bin/contributor-agent.sh, bin/contributor-agent.test.sh: pool-dir precedence and its test.
  • src/deploy/test_contributor_container_resources.sh: the new names in the unset list, plus two new test sections.
  • src/docs/contributor-relay.md: role and quota-guard notes for container and krun mode.
  • src/docs/design/agent-host-confinement.md: corrects a stale contributor-agent.sh line citation.
  • changelog.d/fixed-agent-role-container.md, changelog.d/fixed-quota-guard-container.md: changelog entries.

Tests

test_contributor_container_resources.sh drives the real recipe against the stub runtime.

  • Role section: an exported role, a krun launch, and a role set only in contributor.env are each forwarded. No role means no argument.
  • New quota-guard section:
    • an exported guard mode is forwarded for docker and krun, and an unset one adds nothing;
    • with a pool dir, docker, podman and krun each mount the host directory at /home/dev/.hive-quota-pool (:z for podman and krun) and pass that path, and the directory is created first;
    • a relative pool dir is mounted by its absolute path;
    • the account is passed by name and its value is not in the argv;
    • values set only in contributor.env are forwarded and mounted;
    • just contribute-quota status, with the pool dir and backend only in contributor.env, succeeds and uses the codex relay's pool key.

Before and after:

  • Before this PR (v6 tip): the three role cases fail.
  • Before the quota commit (this PR's first commit): 16 of the new quota cases fail, one for each "set" case (250 passed, 16 failed).
  • After: 266 passed, 0 failed. I ran it locally without the three entrypoint checks for an unknown backend, because my host has a real krun binary on PATH and that check would start it. CI runs the whole script.

The new contributor-agent.test.sh case (section 7) checks that the -e mount path wins over a contributor.env host path, and that the contributor.env value still applies when there is no -e value. Without the precedence fix, the first check gets /host/side/quota-pool; with it, it gets /home/dev/.hive-quota-pool.

Other checks:

  • test_contributor_claude_staging.sh passes (50/0).
  • The rootless-Podman contract check passes.
  • bash -n passes on every touched script, and shellcheck reports the same findings as before.
  • The docs citation and link checks pass.
  • The relay is untouched. node --test bin/contributor-relay.test.js gave the same results with and without the role commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…iner

The /contribute landing page and contributor-relay.md tell contributors to
`export HIVE_AGENT_ROLE=scanner` before `just contribute-hive`, and the relay
sends that value as auth_response.role. But the default container launch
passes an explicit -e list that did not include HIVE_AGENT_ROLE, and
contributor-agent.sh sources contributor.env without exporting it, so in
container and krun mode the relay always connected with no role and a
contributor-first lane was never covered.

Forward it with ${HIVE_AGENT_ROLE:+-e ...} next to AGENT_MODEL. The recipe
sources contributor.env under set -a, so a value set there is forwarded too.
krun uses the same run command. Local mode already inherits the environment.
The hub still checks the role (roleClaimAllowed).

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 danathar for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

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/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Nov 8, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor
0b6ed29

ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @Danathar, head 0b6ed2956e3b) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

  • sensitive_path — changes 2 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • Justfile
    • src/deploy/test_contributor_container_resources.sh

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

@hivecommons-hive

hivecommons-hive Bot commented Nov 8, 2026 •

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.

Your relay could not take this as a fix-pr task (Hive disabled by contributor); the hive will retry it from your relay fix queue.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Review follow-ups (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line are listed here instead of as issues, one comment per PR, updated in place. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

  • P3 low docs-currency — Direct Compose launch still does not forward HIVE_AGENT_ROLE (src/compose-contributor.yaml:16): The environment: list in src/compose-contributor.yaml (lines 16-25) forwards AGENT_MODEL, AGENT_REASONING_EFFORT and HIVE_SESSION but not HIVE_AGENT_ROLE, so a contributor using the documented dire…

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Deferring to shared CI incident #17228: test (rest 3/4) (and the test/coverage aggregates) is red on this PR because TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI in pkg/github became a time bomb at 2026-11-08T12:00Z — it reloads the ledger with the wall clock and the fixture's settled claims (2026-10-09T12:00Z) just crossed the 30-day settledClaimRetention. The default branch (v5 push run 42480676503 @58f593d) is red on the same test; this PR's diff does not touch that file. No action needed here until the incident closes.


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

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

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Shared CI incident: the red test (rest 3/4) / test / coverage checks on 0b6ed29 are TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI time-bombing on every branch (it also fails on v5 tip 58f593d; this PR does not touch pkg/github). Tracked in #17228, fix for v6 in #17230 — deferred until the baseline recovers; nothing to change here.


🐝 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

@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 recipe, contributor-agent.sh, the relay and the test harness at v6 tip; the fix does what it says and looks correct to me.

What I verified:

  • Justfile:1003-1006 — the recipe sources contributor.env under set -a / set +a, so a HIVE_AGENT_ROLE= line there is exported in the recipe shell and ${HIVE_AGENT_ROLE:+-e …} (new line at Justfile:2318) sees it. That is why the contributor.env-only test case can pass without touching the agent script.
  • bin/contributor-agent.sh:36 — source "$CONFIG_FILE" with no set -a anywhere in the script, so inside the container a contributor.env value is not exported to child processes; the -e on the run command really is the only path for the role to reach the relay.
  • bin/contributor-relay.js:125 — AGENT_ROLE = (process.env.HIVE_AGENT_ROLE || '').trim(), sent at :9590. The relay reads exactly the variable now forwarded.
  • src/pkg/dashboard/contribute_agent_roles.go:62 — roleClaimAllowed still gates the claim hub-side, so forwarding a client-supplied role adds no trust surface.
  • Test harness: run_recipe applies env "${ENV_UNSET[@]}" (test_contributor_container_resources.sh:228) before the trailing VAR=value args, and the PR adds -u HIVE_AGENT_ROLE to that list, so the "no role → no argument" case is hermetic rather than dependent on the CI runner's environment.
  • The ${VAR:+…} form matches the adjacent AGENT_MODEL / AGENT_REASONING_EFFORT lines; an unset or empty role leaves the argv unchanged, consistent with the golden files.

CI note for the maintainer: the red test (rest 3/4) / coverage / test checks come from pkg/github TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI, which this PR (Justfile, a shell test, docs, changelog — no Go) cannot have affected; that failure is unrelated to this change.

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

@hivecommons-hive

hivecommons-hive Bot commented Nov 8, 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):

Read against the v6 tree, not just the diff. The fix is correct and minimal; looks correct to me.

What I verified

  • Justfile:1003-1006 — contribute-hive sources gh-auth.env and contributor.env under set -a before building the run command, so both a shell export and a contributor.env-only HIVE_AGENT_ROLE= line are in the recipe's exported environment when the new ${HIVE_AGENT_ROLE:+-e …} at Justfile:2318 is expanded.
  • bin/contributor-agent.sh:36 — source "$CONFIG_FILE" with no set -a, so inside the container a contributor.env value is a shell variable only and does not reach node "${SCRIPT_DIR}/contributor-relay.js" & at :681. The -e list is indeed the only path; the comment added in the recipe matches the code.
  • bin/contributor-relay.js:125 reads process.env.HIVE_AGENT_ROLE into AGENT_ROLE and sends it at :9590. No relay change needed.
  • ${VAR:+…} form matches the adjacent AGENT_MODEL/AGENT_REASONING_EFFORT lines, so an unset/empty role leaves argv unchanged and the golden argv files stay valid.
  • Test (src/deploy/test_contributor_container_resources.sh): run_recipe at :221-235 passes "$@" as env assignments ahead of just, so run_contributor docker HIVE_AGENT_ROLE=scanner sets it in the recipe's environment; -u HIVE_AGENT_ROLE added to ENV_UNSET keeps the host's value from leaking into the "no role" case. The contributor.env-only case restores the file from contributor.env.orig afterwards, same pattern as the krun block above it.

CI

test (rest 3/4) is red on pkg/github TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI (fails on all three attempts). This PR changes no Go code, so that is not caused by this diff — a maintainer may want to confirm it is already red on v6 before treating this PR as blocked by it.

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

Read the diff against the v6 tree (Justfile, bin/contributor-agent.sh, bin/contributor-relay.js, bin/contributor-quota-control.js) before the PR body. The mechanism the body describes checks out, and the fix looks correct to me.

Verified

  • Justfile:1003-1006: contribute-hive sources contributor.env under set -a, so ${HIVE_AGENT_ROLE:+-e …} / ${HIVE_CONTRIBUTOR_QUOTA_GUARD:+-e …} pick up values from either the shell or the file — the new test case "a role set only in contributor.env is forwarded" exercises exactly that path.
  • bin/contributor-agent.sh:35-38: the container entrypoint sources contributor.env without set -a, so the -e list really was the only way these reached the relay. The new _DOCKER_QUOTA_POOL_DIR save/restore mirrors the existing _DOCKER_BACKEND / _DOCKER_MAX_PARALLEL_FIXES idiom at :29-31.
  • bin/contributor-relay.js:125, :572, :637, :642: the relay reads HIVE_AGENT_ROLE, HIVE_CONTRIBUTOR_QUOTA_GUARD, HIVE_CONTRIBUTOR_QUOTA_POOL_DIR and HIVE_CONTRIBUTOR_QUOTA_POOL_ACCOUNT; derivePoolKey({backend, account}) matches contributor-quota-control.js:48-49, so the set -a added to contribute-quota is what makes the host-side key agree with the relay's.
  • Justfile:1683-1699: krun forces RUNTIME=podman, so the :z branch covers krun too, as the comment claims.
  • Both changelog fragments are single - bullets.

CI: the red test (rest 3/4) / coverage / test on this head is TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI (run 42481884719, started 12:47Z) — the wall-clock retention bug fixed on v6 by #17230 at 12:51Z, nothing in this diff. A rebase or re-run should clear it.

One trade-off worth a sentence in the diff (low, not blocking)

Justfile (new QUOTA_POOL_ARGS block): this adds a read-write host bind mount into the container that the SECURITY (H6 / CWE-668) comment at Justfile:1736-1743 describes as running a bypass-permissions agent. The agent inside can therefore write an override file (continue-once, continue-until-reset) into the pool dir and lift its own quota hold — bounded by the operator's reserve and the override expiry rules in contributor-relay.md, and local mode already has the same exposure since the agent runs as the contributor's uid. rw is needed (the in-container hive-quota-publisher writes readings there), so I don't see a code change; I'd just add the pool mount to the H6 comment's list of what the container can write, so the next reader knows it was considered.

Evidence bundle `#17226d419514` sha256:b5827ef46e746d275dcd0205ba1bea25be418e2a6560033976b0c96d3a1ab9aa — download from the dashboard or `hivectl review evidence #17226`.

…tor container

When the quota guard holds work, the relay tells the operator to set
HIVE_CONTRIBUTOR_QUOTA_GUARD=off at launch, or to run `just contribute-quota
continue-once` (and the other scoped controls) against
HIVE_CONTRIBUTOR_QUOTA_POOL_DIR. In container and krun mode neither did
anything: the recipe's -e list carried neither variable, and
contributor-agent.sh sources contributor.env without exporting it.

- Forward HIVE_CONTRIBUTOR_QUOTA_GUARD like HIVE_AGENT_ROLE.
- Mount HIVE_CONTRIBUTOR_QUOTA_POOL_DIR (created, made absolute) at
  /home/dev/.hive-quota-pool and point the relay there. Podman and krun use
  the shared :z label, since the pool is shared by every relay on the account.
  HIVE_CONTRIBUTOR_QUOTA_POOL_ACCOUNT, part of the pool key, is passed by name.
- contributor-agent.sh keeps the -e mount path when contributor.env names the
  host path.
- contribute-quota sources contributor.env under set -a. A plain source never
  exported the pool dir or AGENT_BACKEND to node, so the control either
  refused or wrote under the empty-backend pool key.

Also corrects a stale contributor-agent.sh line citation in
agent-host-confinement.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>
@kubestellar-prow kubestellar-prow Bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 8, 2026
@Danathar Danathar changed the title 🐛 [v6] contribute-hive: forward HIVE_AGENT_ROLE into the contributor container 🐛 [v6] contribute-hive: forward HIVE_AGENT_ROLE and the quota-guard switches into the contributor container 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.

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

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

Looks correct to me. Read the v6 tree alongside the diff:

  • The red checks are not this PR. test (rest 3/4) fails in close_on_merge_ledger_sweep_test.go:188 (TestCloseOnMergeLedgerSweepSettledClaimsSkipAPI, "want 3 settled skips"), the wall-clock retention bug that #17230 fixed on v6 after this branch was cut; coverage and test are the aggregates of that same shard. A rebase onto current v6 should go green — nothing in this diff touches pkg/github.
  • contributor.env-only values do reach the recipe. Justfile:1003-1005 does set -a; source contributor.env, so the new ${HIVE_AGENT_ROLE:+-e …} / ${HIVE_CONTRIBUTOR_QUOTA_GUARD:+-e …} expansions see a value set only in the file, which is what the "role set only in contributor.env is forwarded" case asserts.
  • krun gets the podman branch. Justfile:1698 sets RUNTIME=podman in krun mode and :1748-1755 keys VOLSUF=":Z" off the same variable, so [[ "$RUNTIME" == "podman" ]] → :z covers krun exactly as the test expects. Using the shared z label for a directory several relays are meant to share (rather than the private Z the other mounts use) is the right call.
  • Mount path matches the image. Other mounts already target /home/dev/... (Justfile:2304-2314), and bin/contributor-relay.js:572,630 / bin/contributor-quota-control.js:44 read HIVE_CONTRIBUTOR_QUOTA_GUARD / HIVE_CONTRIBUTOR_QUOTA_POOL_DIR straight from process.env, so the -e override is what the relay actually consumes.
  • Entry-point override is consistent. bin/contributor-agent.sh captures the -e value before source "$CONFIG_FILE" and re-exports it after, mirroring the existing _DOCKER_BACKEND / _DOCKER_MAX_PARALLEL_FIXES pattern at :29-31; the HIVE_CONTRIBUTOR_AGENT_TEST_QUOTA_POOL_DIR hook follows the shape of the existing _TEST_RELOCATE_HUB / _TEST_RESOLVE_BACKEND hooks (:60, :170).
  • agent-host-confinement.md citation 624-641: tmux new-session is at :627 on base and the diff adds 14 lines above it, so the bump is right (and the citation guard is green).

Two changelog fragments, each a single - bullet, cover both user-visible changes. The body's claims match the diff.

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

Danathar and others added 2 commits November 8, 2026 08:04
@hivecommons-hive
hivecommons-hive Bot merged commit 9150048 into hivecommons:v6 Nov 8, 2026
73 of 74 checks passed
@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 d419514.

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