Repository navigation
Description
Carried over from the review of pull request 2150 — a precondition for this issue
The Gemini tier snapshot and history are built from token-usage artifacts collected across the organisation. Those artifacts are untrusted: a pull request run from a fork in a public repository can upload one. Today that is harmless, because the snapshot is informational only. The moment anything gates or defers dispatch on it (which is what this issue starts to do), forged gemini_attempt records or malformed token counts could mark a tier exhausted or unavailable and deny Gemini to the fleet.
Before any dispatch decision reads gq_tier_can_run or the snapshot, records must be traceable to trusted runs (default branch, not a fork), and anything else must be ignored. Treat that as the first acceptance criterion here.
Decision this implements
Maintainer decision (2026-10-09): when the Claude budget breaker trips, pausing the fleet is the primary control, and Gemini is only a small trickle for cheap work. Spend on Gemini may be increased later, so the size of the trickle must be set by data (the caps file), never by code. This supersedes the earlier note on #1565 that the fleet would "degrade to Gemini".
Why this is not a config change
AGENTS_PAUSED=true is a hard stop. It is honoured in .github/workflows/dev-lead-reusable.yml, .github/workflows/pr-review.yml, .github/workflows/engine-token-liveness.yml and scripts/validate-engines.sh, where a pause sets CLAUDE_AVAILABLE, GEMINI_AVAILABLE and COPILOT_AVAILABLE all to false and skips availability probes. A trickle therefore needs an explicit, narrow exemption to the pause, not just a different engine order.
Constraints
- Default off. A new Actions variable
GEMINI_TRICKLE_ENABLED(defaultfalse, absent means false). Merging the code must change no behaviour until the maintainer sets it. Same arming pattern as the dry-run poller. - Only a budget pause can be exempted. The exemption applies only when
AGENTS_PAUSE_SOURCEmarks the pause as automation-set by the budget breaker. A pause a human set by hand (no source, or a human source) is never exempted: a manual pause means stop. - Cheap work only, by data. The allowed tiers come from a data file, default
triageonly (tier_for_intentinscripts/engine.sh: triage =human-pr,fix-bot-comment; action =fix-reviews,fix-ci,rebase; deep =fix-issue,human). Deep, audit and single work never run on Gemini under a pause. Widening the list later is a data change. - Only when capacity exists. A tier runs on Gemini under a pause only if the tier view from Gemini availability per task tier: show remaining capacity per model, key and day so a capped model is visible before the work fails #2041 reports it
availableordegraded(neverunavailable), computed from the caps file (Fill the Gemini caps file: self-imposed Free Tier limits for all four keys (Pro excluded), so the Gemini gate starts enforcing #2146). If no Gemini capacity is left, the work is deferred exactly as it is under a plain pause, with no attempt and no failed call. - Gemini only. Under the exemption the engine chain is Gemini only. Claude and Copilot stay unavailable. No fallback onto Claude.
- No new credential and no new Gemini API calls for measurement. Capacity comes from the existing ledger-based metering.
Scope
- The variable, the tier allowlist data file, and the exemption logic in one shared helper (not copied into each workflow) used by
validate-engines.sh,dev-lead-reusable.ymlandpr-review.yml. - A single log line per run stating that the pause is exempted for a named tier on Gemini, and why work was deferred when it is not, so a budget pause that is quietly doing a little work is legible.
- Fleet monitor: count of items processed under the exemption per day, next to the pause reason.
AGENTS.mddocuments the variable, the allowlist, how to widen it, and how to turn it off.
Acceptance criteria
- With the variable unset or false, a pause behaves byte-for-byte as today (a test asserts all three engines unavailable).
- A pause with no
AGENTS_PAUSE_SOURCE, or a human-set source, is not exempted even with the variable true. - A budget-source pause with the variable true exempts only Gemini and only the allowlisted tiers; a deep-tier item is deferred.
- When the tier view reports
unavailable, nothing is attempted and the deferral is logged. - Claude and Copilot remain unavailable under the exemption (asserted).
- The helper is the single implementation: a test fails if the exemption logic is duplicated in a workflow.
- Shellcheck clean; existing tests pass unchanged; no live network in tests.
Blocked by
#2041 (tier view and rotation that drops a cap-0 key), #2146 (the caps file filled), and the budget breaker actually being armed (#1565, which itself waits for a dry-run window of the poller, #2029). Do not start until the first two have merged; the maintainer adds the dev-lead label then.
Activity
github-actions commentedon Oct 9, 2026
Thanks for the detailed write-up and for spelling out the constraints so clearly. The design already looks well scoped (default off, budget-source pauses only, data-driven tier allowlist, Gemini only). One question to settle before work starts: when the exemption is active and the tier view reports
degradedfor an allowlisted tier, should the trickle run at the full capped rate, or should it be throttled further than the caps file implies? That would tell us whetherdegradedneeds its own data setting or can share theavailablebehaviour.don-petry commentedon Oct 11, 2026
dev-lead is withholding action on this item.
It is labeled
dev-lead:hands-off(deliberately kept off-limits to dev-lead (e.g. changes to the dev-lead automation itself)), so dev-lead will not pick it up while that label is present. This notice is posted once so the withhold is visible rather than looking like a stalled run.To re-enable automated pickup: remove the
dev-lead:hands-offlabel.don-petry commentedon Oct 11, 2026
Status 2026-10-11: the precondition is in review; the trickle itself is stopped on three findings
In review: the first acceptance criterion (records traceable to trusted runs) as #2305. It adds the trust rule, a provenance stamp on every collected record, and a fail-closed reader for future dispatch decisions. Nothing calls that reader yet.
Not built: the exemption. Designing it against the code found three things that the issue as written does not account for.
1. The Copilot credential cannot be withheld from a dev-lead job
Constraint 5 says Claude and Copilot stay unavailable under the exemption. For Claude that can be enforced: its credential is handed to individual steps and can be withheld by expression, or never named in a separate job. For Copilot it cannot. In
dev-lead-reusable.ymlthe Copilot credential is the acting token:GH_TOKENis set for the whole job from the maintainer PAT (line 180),COPILOT_GITHUB_TOKENis the same secret,copilot_chatfalls back toGH_TOKEN, and the writer session inheritsGH_TOKEN. A job that must push and comment as the maintainer cannot be denied that token. Copilot can only be excluded by configuration (AI_ENGINES=gemini), which is a setting, not a guarantee.2. The ledger the capacity check would read is almost entirely test fixtures
About 8 of 1,819 request-counting Gemini records in four days of artifacts were real calls. The rest were written by this repository's engine tests, run by agent sessions that inherit the real ledger path. They come from trusted runs, so no provenance rule removes them. Filed as #2304. Until that is fixed at the source, "the tier view reports capacity" (constraint 4) is a statement about test fixtures.
3. Capacity is not knowable when a job starts, and the caps file does not bound the fleet
A job's own ledger starts empty, so a job-local tier view always reads
available. The only cross-job view is the tier snapshot, written once a day. And the caps file is enforced inside one job's rotation plan: across jobs, the bound under a wrong "go" is the provider's real limits and the prepaid credit, not the caps. (The recent samples also include Gemini answering HTTP 402, "prepayment credits are depleted", four times on 2026-10-10 and 11.)Smaller points that change the design
fix-bot-comment, and it is a writer run that can push commits, not a read-only classification.human-pris intier_for_intentbut nothing emits it.success, notskipped, so it cannot look exactly like a plain pause; the canary promotion gate counts a success as a health sample.status=rate-limitedmarker the budget breaker counts, with no engine in it. Three just before a resume would re-trip the breaker. Preventing that means posting no marker under the trickle.scripts/validate-engines.shhonours the pause only on paper: no workflow passes it the variable.What would unblock it
The full design (gate form, verdict table, kill switch) is ready to reuse when those are settled. The decision whether to continue is with the maintainer.
don-petry commentedon Oct 11, 2026
Maintainer decision, 2026-10-11: parked. The exemption is not being built. Pause stays the only control during a budget pause. What continues: the trusted-records precondition (#2305) and the ledger fix (#2304), both of which stand on their own. Reopen the design here only if the three conditions above are met and the trickle is still wanted.
fix(gemini-ledger): count a failed run look-up and a malformed record…
fix(gemini-ledger): an artifact whose run the listing does not name i…
fix(gemini-ledger): hand the tier report only records traceable to tr…