feat(proxy): add opportunistic traffic class

[Komzpa]

Summary

• Add API-key traffic_class with foreground default and opportunistic routing.
• Add Codex opportunistic admission preflight at /backend-api/codex/opportunistic/admission.
• Return OpenAI-style 429 denials with Retry-After when the opportunistic burn window is closed.
• Add dynamic opportunistic burn floors for burn_first, normal, and preserve accounts.
• Route real opportunistic Codex requests through the existing Codex proxy path while keeping Fixer-style preflight as a scheduling hint.

Stack

• Depends on feat(accounts): add manual routing policy #553 for manual account routing policies and additional-quota routing policy overrides.
• Spark/additional-quota UI and the default codex_spark = burn_first policy are intentionally in feat(accounts): add manual routing policy #553 now, so this PR stays focused on traffic class and admission control.

Tests

• uv run ty check
• /home/kom/proj/codex-lb/.venv/bin/python -m ruff check app/core/balancer app/db/models.py app/db/alembic/versions/20260509_000000_add_api_key_traffic_class.py app/modules/api_keys app/modules/proxy/api.py app/modules/proxy/load_balancer.py app/modules/proxy/service.py tests/unit/test_api_keys_service.py tests/unit/test_load_balancer.py
• openspec validate add-opportunistic-traffic-class --strict --no-interactive
• /home/kom/proj/codex-lb/.venv/bin/python -m pytest tests/unit/test_load_balancer.py tests/unit/test_api_keys_service.py tests/integration/test_load_balancer_integration.py tests/integration/test_settings_api.py tests/integration/test_additional_usage_flow.py tests/integration/test_migrations.py -q
• /home/kom/proj/codex-lb/.venv/bin/python -m ruff format --check app/core/balancer app/db/models.py app/db/alembic/versions/20260509_000000_add_api_key_traffic_class.py app/modules/api_keys app/modules/proxy/api.py app/modules/proxy/load_balancer.py app/modules/proxy/service.py tests/unit/test_api_keys_service.py tests/unit/test_load_balancer.py && git diff --check

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c21f58874b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Treat preserve capacity as foreground in zero-burn eligibility

The zero-burn guard for normal/burn-first accounts only counts preserve peers when _preserve_allows_opportunistic_burn(...) returns true. That conflates “foreground capacity exists” with “preserve is also opportunistically burnable”: a preserve account at its opportunistic floor can still retain foreground reserve, but this code treats it as unavailable and blocks draining expendable accounts to zero. As a result, opportunistic admission can close earlier than intended whenever the only remaining foreground reserve is on preserve accounts.

Useful? React with 👍 / 👎.