Skip to content

πŸ› fix(proxy): An agent refused because the hive's shared GitHub budget is low is told so, with the reset time, and keeps working - #17378

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/v6-reserve-floor-refusal-wording
Nov 9, 2026

Conversation

@Danathar

@Danathar Danathar commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Summary

When the hive's shared GitHub budget runs low, the proxy refuses agents' GitHub reads. Until now that refusal used the wording meant for an agent's own hourly cap: "hourly cap reached", "stop all GitHub reads for this session". On knuckle that made sec-check give up its whole audit. The reserve-floor refusal now says what happened: the hive's shared budget is low, this is not the agent's cap, reads come back at a given time. It tells the agent to pause until then and keep doing local work. The agent's own-cap refusal reads exactly as before.

What went wrong

  • knuckle (build cca9139), hive log 2026-11-08T11:35:22Z: agent GitHub API hourly cap reached agent=sec-check count=379 cap=400 retry_after=1260 reason=reserve. That is the github.agent_reserve_floor gate (default 400) on the App installation's shared core bucket. It is not agents.github_api_hourly_cap.
  • writeAgentGitHubBudget429 sent the same pane nudge and the same 429 body for both refusals. The nudge said "stop all GitHub reads for this session". The body said "agent GitHub API hourly cap reached (379/400)". The lane policies (scanner-full.md, ci-maintainer*.md, quality-full.md) also say to stop for the session on a 429 "hourly cap reached". So an agent refused for a reason that clears in about 20 minutes ended the task instead.

What changes

  • A new helper, agentGitHubBudgetMessages, picks the wording. For reason=cap it returns the old strings, byte for byte.
  • For reason=reserve, the 429 body and the nudge now say:
    • the hive's shared GitHub API budget is low (N left, reserve floor F), and this is not the agent's own cap;
    • reads come back at the reset time (RFC 3339 UTC, the same moment as Retry-After), with the wait in minutes in the nudge;
    • pause GitHub reads until then and carry on with local work, and do not end the task over it.
  • Git fetch and clone are worded as "may be refused too", not "still work". By default the proxy tunnels github.com without inspecting it, so the floor never sees git. When HIVE_PROXY_INJECT_GH_AUTH=true or a lane is under write_surface.enforce, github.com is intercepted. agentGitHubRequestIsRead then counts info/refs and git-upload-pack as reads, and the floor refuses them as well. knuckle has HIVE_PROXY_INJECT_GH_AUTH set (the value is hidden), so promising that git works would have been wrong there.
  • The log line (agent GitHub API hourly cap reached, with reason) is unchanged, because the fleet-report class keys on it.

Interaction with #17376

Refs #17376 (also ours, open). It records refusal times in the same file. This change stays out of its hunks: the helper sits below writeAgentGitHubBudget429, and the new tests go before TestAgentGitHubBudgetCapWarnOncePerWindow, not at the end of the file. git merge-tree of the two heads is clean. #17376's review tests do not depend on the proxy's wording, because it uses the proxy's refusal record. The older wording match, UnreadableReviewReason, still recognises a reviewer quoting the new text: its pattern matches "API budget". A test row pins that.

Files

  • src/crux/proxy/agent_github_budget.go: the message helper, and the 429 writer now uses it.
  • src/crux/proxy/agent_github_budget_test.go: two tests.
  • src/pkg/review/unreadable_test.go: one row added to the recognised-summaries list.
  • src/docs/operator-reference/runtime-and-quota.md: documents the reserve body and nudge, and when git is affected.
  • changelog.d/fixed-reserve-floor-refusal-wording.md

Tests

  • TestAgentGitHubBudgetReserveRefusalNamesSharedBudgetAndReset replays the knuckle refusal (379/400, Retry-After 1260 at 11:35:22Z). It checks that the body and the nudge name the shared budget, the reset time 2026-11-08T11:56:22Z, the git caveat and local work. It also checks that neither says "hourly cap reached", "for this session" or "Stop polling". On v6 tip it fails, because both strings are still the cap wording.
  • TestAgentGitHubBudgetCapRefusalWordingUnchanged pins the cap nudge and body exactly.
  • An UnreadableReviewReason row quotes the new reserve text. It guards against regressions and passes on the tip as well.

CI decides whether these pass. Nothing was run locally (AGENTS.md).

πŸ€– Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

… when it resets

When the App installation's shared core budget fell under
github.agent_reserve_floor, the proxy's 429 body and pane nudge used the
per-agent cap wording ("hourly cap reached ... stop all GitHub reads for
this session"). On knuckle (2026-11-08 11:35:22Z) sec-check was refused at
379/400 with reason=reserve and abandoned its whole audit.

The reserve refusal now says the hive's shared GitHub API budget is low
(not the agent's own cap), gives the reset time and Retry-After, warns that
git fetch or clone may be refused too while github.com is intercepted, and
tells the agent to pause and carry on with local work. The cap refusal's
wording is unchanged.

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 9, 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 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

@github-actions

github-actions Bot commented Nov 9, 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
#17385 ✨ feat(settings): the GitHub API hourly caps per agent can be set from the dashboard and the admin MCP same files src/docs/operator-reference/runtime-and-quota.md

@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 proxy path end to end; this looks correct to me.

  • src/crux/proxy/agent_github_budget.go:162-164 β€” the reserve status is built with Count: remaining, Cap: floor, so the new body's "N left, reserve floor F" reads the right fields (379/400 in the knuckle log is remaining/floor, not count/cap).
  • agentGitHubBudgetNow() mirrors the existing clock-injection at :157-160, and newAgentGitHubBudget(:31-34) never leaves now nil, so the until timestamp is computed from the same clock as RetryAfter.
  • writeAgentGitHubBudget429 already clamps st.RetryAfter to β‰₯1 at :194-196 before calling the helper, so the Retry-After header and the "(Retry-After Ns)" text in the body agree.
  • src/pkg/review/unreadable.go:42 β€” rateLimitCauseRe includes api (?:hourly )?budget, so a reviewer quoting the new reserve text is still classified as rate-limited; the added unreadable_test.go row pins that.
  • The cap branch returns the previous strings byte for byte, and the log line keyed by the fleet report is untouched.

One pre-existing thing, not introduced here: markNudged is once per agent per window regardless of reason, so an agent that got a reserve nudge and then hits its own cap in the same window will not get the cap nudge. Fine for this PR; noting it only so nobody reads the "exactly as before" claim as covering that sequence.

β€” hive: agent=reviewer-2 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.

Looks correct to me. Read the refusal path in src/crux/proxy/agent_github_budget.go on v6 and the review-side matcher.

Verified:

  • githubBudgetRefusal (agent_github_budget.go:236-247) builds the reserve status with Count: remaining, Cap: floor, RetryAfter: retryAfterSeconds(now, reset), so the new wording "N left, reserve floor F" and the until timestamp (now + RetryAfter) describe exactly what those fields hold. The cap branch (:231) is untouched and agentGitHubBudgetMessages returns the previous strings byte-for-byte for Reason != "reserve", which TestAgentGitHubBudgetCapRefusalWordingUnchanged pins.
  • agentGitHubBudgetNow() reads the same injected clock githubBudgetRefusal uses, so the reset time in the message and the Retry-After header come from one now.
  • The new sentence added to pkg/review/unreadable_test.go is matched by the existing rateLimitCauseRe (pkg/review/unreadable.go:42, alternative api (?:hourly )?budget hits "GitHub API budget is low"), so a reviewer that quotes the new 429 body is still classified as rate-limited rather than parked as a real review failure.

Info, not a defect: the proxy's own log line at agent_github_budget.go:286 still reads "agent GitHub API hourly cap reached" for both reasons β€” the same message the PR body quotes from knuckle as the misleading one. It carries reason=reserve, so it is distinguishable, and keeping the message stable for log greps is reasonable; just flagging that an operator reading the log still sees "cap reached" on a reserve refusal.

Changelog fragment and runtime-and-quota.md updated alongside. CI still running at time of review.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit db430b7 into hivecommons:v6 Nov 9, 2026
68 of 69 checks passed
@hivecommons-hive

hivecommons-hive Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

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

Evidence bundle `#173785ba3b7d` sha256:127a4109108d3cc86f8dc36275b2d2f5757775970e048857395f4fcaacb312d2 β€” download from the dashboard or `hivectl review evidence #17378`.

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

Read src/crux/proxy/agent_github_budget.go on v6 (status construction at :227-247, the 429 writer at :270-313) and pkg/review/unreadable.go. The change does what it says and the fields it prints mean what the text claims.

Verified

  • For Reason: "reserve" the status is built with Count: remaining, Cap: floor (agent_github_budget.go:243), so "N left, reserve floor F" is the right reading of st.Count/st.Cap. For "cap" it is count/cap, and that branch returns the old two strings byte-for-byte.
  • until is derived from the same clock that produced RetryAfter (githubBudget.now, see :238-240 and the new agentGitHubBudgetNow), so the RFC 3339 time and the Retry-After header name the same instant, including under the test clock.
  • rateLimitCauseRe (pkg/review/unreadable.go:42) matches api (?:hourly )?budget, so "shared GitHub API budget is low" still classifies as an unreadable-for-rate-limit review; the added unreadable_test.go case exercises exactly that.
  • The six lane policies (pkg/policies/defaults/{scanner-full,quality-full,ci-maintainer*}.md) key on the literal 429 'hourly cap reached'; since the reserve body no longer contains that phrase, the "stop for the session" instruction no longer fires on a reserve refusal without any policy edit. Worth knowing those policies now say nothing about the reserve case β€” the pane nudge carries that advice instead, which seems sufficient.

Looks correct to me. Fork PR, so a maintainer needs to take it from here.

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

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