Bug: Quota count resets unexpectedly when background refresh syncs with API

[b3nw]

Bug Description

The local quota request_count can unexpectedly reset to 0 when the background quota refresh syncs with the API and receives remainingFraction: 1.0 (100% remaining).

Observed Behavior

From logs, quota tracking showed:

01:56:52 - quota: 0/400 [100%]  (first request)
01:56:57 - quota: 1/400 [99%]
01:57:06 - quota: 2/400 [99%]
01:57:35 - quota: 3/400 [99%]
01:58:36 - quota: 4/400 [99%]
01:59:37 - quota: 0/400 [100%]  ← UNEXPECTED RESET
02:00:42 - quota: 1/400 [99%]

The quota counter reset from 4 back to 0 mid-session, losing tracking of recent requests.

Root Cause

In src/rotator_library/usage_manager.py, the update_quota_baseline() function unconditionally overwrites the local request_count with the API's value:

# Line ~2214-2216
# Sync local request count to API's authoritative value
model_data["request_count"] = used_requests
model_data["requests_at_baseline"] = used_requests

Where used_requests = int((1.0 - remaining_fraction) * max_requests).

When the background quota refresh runs and the API returns remainingFraction: 1.0 (100% remaining), used_requests becomes 0, and all local tracking is wiped.

Why the API might return 100%:

• API response caching/staleness
• Different quota window timing on server vs local expectations
• Requests not yet reflected in API's quota calculation

Proposed Fixes

Option 1: Only allow API to increase count (simpler)

# Sync local request count to API's authoritative value
# Use max() to prevent API from resetting our count if it returns stale/cached 100%
# The API can only increase our count (if we missed requests), not decrease it
current_count = model_data.get("request_count", 0)
model_data["request_count"] = max(current_count, used_requests)
model_data["requests_at_baseline"] = model_data["request_count"]

Pros: Simple, directly addresses the bug, low risk
Cons: If quota genuinely resets server-side, local count won't decrease until local window reset logic triggers

Option 2: Track requests between syncs (more precise)

# Calculate requests made locally since last baseline
requests_since_baseline = max(0, model_data.get("request_count", 0) - model_data.get("requests_at_baseline", 0))

# New count = API's count + our local requests since last sync  
model_data["request_count"] = used_requests + requests_since_baseline
model_data["requests_at_baseline"] = used_requests

Pros: More accurate, properly accounts for requests made between API fetches
Cons: More complex logic, potential for double-counting edge cases

Environment

• Branch: dev (verified bug exists in upstream dev)
• Affected providers: Antigravity, Gemini CLI (any provider using update_quota_baseline)

Questions for Maintainer

1. Which fix approach is preferred?
2. Are there any edge cases we should consider (e.g., quota group syncing, cross-credential scenarios)?

[mirrobot-agent]

@b3nw Thank you for submitting this issue. I am now beginning my analysis and will report back shortly.

[mirrobot-agent]

Initial Analysis Report

Summary: The update_quota_baseline function in usage_manager.py unconditionally overwrites the local request_count with usage data calculated from API responses, causing resets to 0 when the API returns stale or cached "100% remaining" values.
Issue Validation: Confirmed. Code inspection shows that model_data["request_count"] is updated without checking if the new value is less than the current local count.
Reproducibility Assessment: Reproducible. The logic in src/rotator_library/usage_manager.py (lines 2215-2216 and 2290) directly implements the problematic behavior described in the issue.
Root Cause Analysis:
In src/rotator_library/usage_manager.py, the function update_quota_baseline calculates used_requests from the API's remaining_fraction. It then performs:

model_data["request_count"] = used_requests
model_data["requests_at_baseline"] = used_requests

Because API responses (especially for quota/usage) can be delayed or cached, they may report 100% remaining (used_requests = 0) even after local requests have been made. Blindly syncing to this value wipes out local tracking.

Suggested Labels: bug, high-priority, quota-management.
Proposed Next Steps:
Implement the "Option 1" fix suggested by the author, as it is robust and naturally integrates with the existing estimation logic.
Specifically:

1. Modify src/rotator_library/usage_manager.py to use max(current_count, used_requests) when updating request_count.
2. Apply the same logic to the grouped model sync loop to ensure consistency across quota groups.
3. Keep requests_at_baseline = used_requests (the API value) as it is correctly used by the estimation logic in antigravity_quota_tracker.py to calculate local requests since the last sync.

Proposed Code Change:

# src/rotator_library/usage_manager.py

# Replace:
model_data["request_count"] = used_requests
# With:
current_count = model_data.get("request_count", 0)
model_data["request_count"] = max(current_count, used_requests)

Missing Information (if any): None. The issue provides excellent logs and a clear root cause analysis.

This analysis was generated by an AI assistant.