quota-axi: Instructions file for Codex

Project agent memory

This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.

Provider windows, credentials, cache identity, output tiers, and the TUI are owned by README.md. Follow the section named below instead of restating it here.

• VISION.md is the acceptance policy and sits ahead of what ships. Accuracy of the reported number comes first. README Security Posture is what ships today; do not restate VISION.md wording as a current guarantee.
• quota-axi is data only. It reports the local providers named in the README, including Muse and Higgsfield, and must never route, recommend, rank a winner, order providers preferentially, proxy, intercept, log in, import browser cookies, or mint or rotate a credential. The per-scope selection signal is data for the consumer. The generated skill stays a stub that defers to the CLI (README Agent Skill).
• Never exchange a refresh token, and never retain, log, render, cache, or send its value. Delegated refresh checks presence only. Pi brokers may read a stored refresh value only to classify it as a usable literal, then discard it. See README Safety guarantees and README Delegated credential refresh.
• A delegate runs only when the same stored access token is expired, carries a refresh token, and was definitively rejected, and only through src/providers/delegated-refresh.ts. quota-axi never signals that child. A run that outruns the wait is unmeasured or stale, never a sign-out, and never retires the cache. Leaving a provider read-only is always allowed.
• Never read a secret in order to decide cache silence, and never log or render a credential. Cache files are 0600 and hold only normalized non-secret snapshots. Do not cache raw provider responses or credential headers (README Cache).
• Do not invent a quota figure, window, reset, percentage, or cycle the vendor did not supply. Do not treat an inherited bound as exhaustion without the evidence in README Quota windows. A shareOf window never yields a remaining. Demote fields only in the renderer.
• New credential sources follow the checklist in README Provider state. New remote fetches go through src/lib/http.ts. New process-table reads go through currentUserProcessListArgs. Context-scoped cache identity goes through CONTEXT_SCOPED_PROVIDERS.
• Codex stale cache reuse requires a stored account stamp matching a credential identity the current read actually tried; see README Cache.
• Same-subscription coalescing is shared machinery in src/providers/accounts.ts: one report per verified account.accountId or hashed cache subscription stamp, windows never summed, missing or unverified identity stays separate, and every lane keeps its own cache slot. Codex native/Pi lane folding stays in src/providers/codex.ts. Claude lanes exist only when QUOTA_AXI_CLAUDE_PROFILES or QUOTA_AXI_CLAUDE_SWAP opts in; unset, Claude must stay byte-identical to one selected lane. Only the selected profile lane may use the env token or delegated refresh; the claude-swap source runs claude-swap's read-only cswap list --json command, which is not a delegated refresh. Contract in README Multiple accounts.
• --profile-only is fail-closed for one Claude or Codex credential file and bypasses other sources, delegated refresh, and the cache (README Profile-only quota reads). Omitting it keeps ordinary discovery.
• --allow-keychain-prompt is the one-time opt-in for a secure-store value read that can prompt. Relay "Always Allow" when keychain_access_required appears. A missing sqlite3 is sqlite3_unavailable; do not install system packages.
• Provider tests use synthetic stores and mocked Keychain, process, and HTTP boundaries. Never use a live credential, the real security binary, a real refresh, or a provider API. Pass refreshCredentials: false unless the test is about delegation.
• Muse (muse) is a default unscoped provider and stays read-only. Its only quota read is the Muse CLI's own startup request, POST /muse-code/key, whose response also carries the account's Model API key; parse through a key-allowlist reviver so the key never reaches an object. A live 1.4.0 Power Usage mint body may omit subs_usage; that is an empty reading, not a missing allowlist key. Do not expand the allowlist without live usage key paths. On macOS the token lives in the login Keychain item ai.meta.dev.credentials / meta, gated by --allow-keychain-prompt like the Cursor CLI source (src/providers/muse-keychain-credential.ts). auth passes presenceOnly: !allowKeychainPrompt so a leftover grant marker never fetches the bundle. A skipped present Keychain source is never a sign-out, even when a later sibling is rejected: report the blocked read and preserve the cache. An unreadable or malformed Muse auth file with no working fallback is an operational failure, not auth_required. src/providers/muse-read-gate.ts bounds requests to one per credential per MUSE_KEY_READ_INTERVAL_MS via a 0600 ledger of opaque context digests: check and pending claim are one locked step, and a request does not leave without that recorded claim. Inside the interval replay and send nothing. A successful empty reading records a non-secret empty-quota marker on that ledger so interval replay returns the same observation; a cache miss after a windowed quota outcome is not turned into an empty reading. Muse is excluded from --max-age / QUOTA_AXI_MAX_AGE fresh reuse, because a macOS Keychain login switch does not change a traced file; the five-minute ledger remains the bound on vendor calls. Muse snapshots are context-scoped (answering source plus a one-way digest of the credential that answered) through CONTEXT_SCOPED_PROVIDERS. Do not loosen the gate or add a delegate without fresh empirical evidence of the endpoint's rotation behavior. Contract in README Provider notes.