gibby/.opencode/plans/1775725199925-glowing-orchid.md

Plan: make local account state authoritative

Problem

Current accounts.json state is not acting like a real source of truth for /token:

• active_account_id is persisted but not actually used to drive selection
• last_known_usage is mostly treated as a sort hint, then immediately replaced by a live refresh
• /token live-refreshes every candidate it tries, so local limits are not truly trusted
• the persisted snapshot contains duplicate derived fields (used_percent, remaining_percent, exhausted) in addition to canonical window and flag data
• as a result, the file is hard to reason about: some fields look authoritative but are only decorative or transient

Desired behavior

1. accounts.json is the source of truth for /token selection.
2. If active_account_id exists and local state says the active account is usable, /token must try that account first.
3. Only if local state says the active account is blocked or unusable should /token fall back to choosing another account.
4. Fallback selection can keep the current ranking approach: most-used eligible account first.
5. /usage should continue to refresh all accounts live.
6. Persisted usage snapshots should store canonical data only, without duplicated derived fields.

Recommended approach

1. Split /token selection into local selection and live validation

In src/gibby/manager.py:

• Add _find_active_account(state) to resolve state.active_account_id to an AccountRecord
• Add _is_locally_blocked(account, current) to decide from local file state only whether an account can be tried
• Add _build_selection_order(state, current) that:
  • returns the active account first if it exists and is not locally blocked
  • otherwise falls back to the remaining eligible accounts sorted by current saved-usage ranking
  • never duplicates the active account in the fallback list

_is_locally_blocked() should use only persisted local state:

• blocked if cooldown_until > now
• blocked if last_known_usage exists and local usage indicates exhaustion
• otherwise not blocked

This gives the exact behavior the user requested:

• active account is mandatory first choice when nothing local blocks it
• local file decides whether active is allowed before any network call
• live refresh remains only a validation step for the chosen candidate

2. Keep live refresh only for accounts actually attempted

In src/gibby/manager.py:

• keep the current live refresh path (refresh_account_usage) once an account has been selected for an attempt
• if active account passes local checks but fails live validation, persist the updated state and continue to the next candidate
• if active account is locally blocked, skip live refresh for it during that /token call

/usage stays as-is and continues refreshing all accounts live.

3. Clean up the persisted usage snapshot schema

In src/gibby/models.py and src/gibby/store.py:

• stop persisting derived snapshot fields:
  • used_percent
  • remaining_percent
  • exhausted
• keep only canonical persisted snapshot data:
  • checked_at
  • primary_window
  • secondary_window
  • limit_reached
  • allowed

Implementation direction:

• keep UsageSnapshot as the in-memory model for now, but derive:
  • used_percent
  • remaining_percent
  • exhausted from canonical fields when loading/parsing
• update store._snapshot_to_dict() to write only canonical fields
• update store._snapshot_from_dict() to reconstruct the full in-memory UsageSnapshot from canonical persisted fields

This keeps code churn smaller than a full model rewrite while making the file itself cleaner and more honest.

4. Keep cooldown as the persisted local block, but make local exhaustion matter too

Local selection should not depend on a fresh API round-trip.

For /token:

• cooldown_until remains the strongest persisted block
• if cooldown is clear but local last_known_usage still says exhausted, treat the account as locally blocked too
• only accounts that pass local checks are eligible to be attempted live

This changes current behavior in an important way:

• today, an account with expired or missing cooldown can still be live-refreshed even if local snapshot says exhausted
• after the change, local state truly gates the initial decision

5. Preserve existing fallback ranking for non-active accounts

After active account is rejected locally, keep the current fallback sort in manager.py:

• primary window used percent descending
• secondary window used percent descending

That avoids a larger policy change in this pass and isolates the refactor to "trust local state first".

Files to modify

• /home/wzray/AI/gibby/src/gibby/manager.py
  • respect active_account_id
  • add local-only eligibility predicate
  • change selection order to active-first-when-locally-usable
• /home/wzray/AI/gibby/src/gibby/models.py
  • keep canonical usage derivation helpers centralized
  • support reconstructing derived values from canonical fields
• /home/wzray/AI/gibby/src/gibby/store.py
  • write canonical snapshot shape only
  • read canonical snapshot shape into full in-memory model
• /home/wzray/AI/gibby/src/gibby/account_ops.py
  • keep refresh path aligned with canonical snapshot handling
  • reuse a local exhaustion predicate if helpful instead of duplicating logic
• /home/wzray/AI/gibby/tests/test_core.py
  • add and update selection behavior tests
• /home/wzray/AI/gibby/tests/test_account_ops.py
  • update snapshot persistence assumptions if needed
• /home/wzray/AI/gibby/tests/test_app.py
  • adjust fixture shapes only if response expectations change
• /home/wzray/AI/gibby/tests/test_refresh_limits.py
  • ensure live refresh still rewrites canonical local state correctly
• /home/wzray/AI/gibby/tests/test_oauth_helper.py
  • ensure oauth helper stores canonical snapshot shape correctly

Test plan

Selection behavior

Add or update tests in tests/test_core.py for:

• active account is used first when locally allowed, even if another account has higher saved usage
• active account is skipped without live refresh when cooldown_until is still active
• active account is skipped without live refresh when local snapshot says exhausted
• active account passes local checks but fails live refresh, then fallback account is tried
• missing or stale active_account_id falls back cleanly to non-active selection logic
• fallback ordering still prefers higher saved primary usage and uses secondary as tie-breaker

Snapshot/file behavior

Add or update tests to verify:

• accounts.json no longer writes used_percent, remaining_percent, or exhausted
• loading canonical persisted snapshots still reconstructs full in-memory UsageSnapshot
• /usage, refresh_limits.py, and oauth_helper.py still persist refreshed canonical state correctly

Verification

• uv run pytest -q tests/test_core.py tests/test_account_ops.py tests/test_app.py tests/test_refresh_limits.py tests/test_oauth_helper.py
• inspect a real accounts.json after /usage or refresh_limits.py and confirm snapshot entries contain only canonical fields
• manually test /token with:
  • a locally usable active account
  • a locally blocked active account
  • a dangling active_account_id
• verify that active account is not live-refreshed when local file state already blocks it