[shiny-code-app]

Why

OpenAI granted about 60,000 usage credits per account that expire at the end of December 2026. Context Panel showed the balance but no deadline, so nothing said whether the credits will be wasted. The weekly waste number could not count them either.

What OpenAI reports

No usage-credit expiry anywhere Context Panel reads.

• The usage response's credits object has has_credits, unlimited and balance. Codex's own backend schema (codex-backend-openapi-models, CreditStatusDetails) adds only message estimates. No date.
• Codex session logs: 198 recent credits objects across this Mac's Codex homes all have exactly those three keys. Only key names were read.
• The rate-limit-reset-credits sibling has expires_at, but for banked resets, not usage credits. It is already used for those.

So the date comes from Settings.

What changed

• Settings > Usage credits. Shown for a provider that reports a credit balance. Chris checks "OpenAI usage credits expire" and picks the day once. It is saved in the account setup file as usageCreditExpiries, per provider. All three grants share one date, so per provider is the simpler fit. No date is hardcoded.
• Provider date wins. If a balance ever reports its own expiresAt, that is used instead, and the source says so.
• Mac app. The provider view's credits line now reads, for example: "OpenAI has 179,745 usage credits left. They expire Dec 31 (date entered in Settings). At this pace none will be spent: credits are used only once an account's weekly quota reaches 0%, so all 179,745 will expire unused." The diagnostics row says "expire Dec 31 (entered)" in place of "expiry not reported".
• Agent snapshot. providers[].unusedAtPace gains usageCreditsExpireAt, usageCreditsExpirySource (provider or entered) and usageCreditsAtRisk. At risk is every credit left while no account is at 0%. It is null while an account is spending them, because one reading can't say how many will be left. All three are null when no future expiry is known.
• Weekly waste. The balance an account still held at the expiry (reported or entered) counts in usageCreditsExpiredUnused that week. The entered day is saved as its start, so credits left when Dec 31 begins count. This no longer subtracts the balance after the expiry, so a new grant cannot hide expired credits.
• Docs: agent snapshot fields and the credits wording in docs/provider-usage-access.md.
• Companions show no credit balance, so no companion change.

Closes #1099

Verification

• swift build: clean (only existing saveAccounts() warnings).
• swift test --filter ContextPanelCoreTests: 1366 passed.
• New tests from fixtures: expiry shown with the entered label and all credits at risk; spending leaves at risk unclaimed; unknown or passed expiry omits it; provider date wins in the line and in waste; credits left at the entered day count as wasted that week, and not without it; the entered day survives a settings save and load and reaches the agent snapshot JSON.
• Each was checked to fail by breaking its rule (9 mutations, all caught).
• JetBrains inspection: UNKNOWN. No worker covers Swift or Markdown here.

Removed: the balance-after subtraction at a credit expiry, and the fixed "expiry not reported" label.
Net lines: Sources +133, Tests +98, docs +15.

[shiny-code-app]

Ready for the merge train

Head: cf5abd6

[shiny-code-app]

Launchplane completed the merge-train step for this pull request.

• Repository: cbusillo/context-panel
• Base branch: main
• Pull request: Show when usage credits expire #1100
• Controller action: land_batch
• Controller record: merge-train-batch-landing-plan-20261109T020313Z-d99130a7a54234e2

Launchplane finished the merge-train step for this pull request.

Launchplane manages this comment and will update it as the train moves.