[RaviTharuma]

Summary

• CLIProxyAPI stamps the selected credential on X-CPA-TRACE-ID. This PR stores that opaque auth_index on usage_history for the success, streaming, and error paths. A later completed attempt backfills the column when the first write missed the header.
• The human-readable account label is resolved at read time from the sanitized account-health projection (feat(services): expose sanitized CLIProxyAPI account health #11314). Emails, paths, tokens, and raw management payloads are dropped and are never written to the column.
• A missing header or an unrecognized shape stays unattributed. It does not fail the request.

Related Issues

• Closes feat(providers): correlate X-CPA-TRACE-ID auth_index with account health #11725
• Related to feat(services): expose sanitized CLIProxyAPI account health #11314 and feat(providers): consume CLIProxyAPI /v0/management for account-aware routing and quota display #6342

Validation

Choose the change type and focused loop from the
Contribution Golden Path. The full unit suite,
Vitest, the 60% coverage gate, and the production build all run in CI on this PR (#8329):

• Change type: DB
• Focused tests and category gates from the golden path: node --import tsx/esm --test tests/unit/cpa-trace-auth-index.test.ts tests/unit/cpa-auth-index-usage.test.ts tests/unit/db/migration-185-cpa-auth-index.test.ts tests/unit/chatcore-failure-usage.test.ts (12 passed); npm run check:migration-numbering; npm run check:file-size; npm run check:docs-counts; node scripts/check/check-docs-sync.mjs
• npm run lint — ESLint on the touched TypeScript files (the same command lint-staged runs). The full eslint . suite still runs in CI.
• Reconciled with the current active release base release/v3.8.51 (9f4d3b0ab8); focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR
• SonarQube is temporarily opt-in while the private project has no quota; it is not a PR gate.

Tests Added Or Updated

• tests/unit/cpa-trace-auth-index.test.ts — opaque parse, JSON and auth_index= forms, rejection of emails/paths/secrets, header rebuild, sanitized label join
• tests/unit/cpa-auth-index-usage.test.ts — persist plus dedup backfill on a fresh database
• tests/unit/db/migration-185-cpa-auth-index.test.ts — upgrade from a prior usage_history and idempotent re-run when the column already exists
• tests/unit/chatcore-failure-usage.test.ts — existing failure-usage characterization, still passing with the extra field

Coverage Notes

• open-sse/handlers/chatCore/cpaTraceAuthIndex.ts, the usage-history write/read, and migration 185 are covered by the tests above.
• open-sse/handlers/chatCore.ts only threads readCpaAuthIndex(providerResponse) into the three existing usage writers (failure, non-streaming, streaming). The parser and the label join live in leaves under the file-size cap. The frozen ceiling moves 6400 → 6402 because Prettier keeps the failure-usage property and the import on their own lines.

Reviewer Notes

• This follows the scope accepted on feat(providers): correlate X-CPA-TRACE-ID auth_index with account health #11725 (2026-08-29): extract and defensively parse X-CPA-TRACE-ID in the CLIProxyAPI executor, thread the opaque auth_index into usage_history.cpa_auth_index, and resolve the label at read time. It is not a credential-selection input and it does not reimplement session affinity.
• fix(resilience): classify CLIProxyAPI model_cooldown 429 errors as quota_exhausted #14190 classifies CLIProxyAPI model_cooldown 429s. It does not read this header.
• Migration 185_usage_history_cpa_auth_index.sql is nullable. The documented migration count moves from 178 to 182 so README, AGENTS.md, and llm.txt match the files on this branch (the tip was already ahead of that prose).
• The index is not copied onto the dashboard by itself. getUsageDb / getUsageHistory return cpaAuthIndex and cpaAccountLabel.