feat(diagnostics): explain account-pool readiness and routing imbalance #5788

Summary

Provide a supported diagnostic report that answers which accounts can serve a requested model, why another account is excluded or receiving less work, and what action would restore normal operation. Combine existing runtime, quota, renewal, affinity, and usage evidence into a coherent human-readable and machine-readable result without requiring raw credential inspection or manual log correlation.

Problem to solve

Investigating a 25% versus 5% weekly usage split required an external account-usage application, SSH to a second host, service-process inspection, allowlisted credential metadata extraction, request-ID correlation, source inspection, and manual aggregation of new bindings separately from follow-up requests. A responding model-list endpoint and two credential files were insufficient to establish a healthy two-account pool. The same outward symptom could mean an old cooldown, failed future renewal, long sticky sessions, unequal request cost, or an older executable still running.

CLIProxyAPI already exposes useful components: auth status, success/failure counts, recent requests, passive quota observations, retry deadlines, request usage records, and running build headers. The requested improvement is an integrated explanation with evidence freshness and coverage, not a claim that account telemetry or attribution is entirely absent.

Proposed behavior

Expose a local or appropriately authorized read-only pool diagnostic for a selected provider/model and time interval. Show intended logical accounts separately from active physical credential records, current eligibility with specific reasons, observed renewal health, access-expiry deadlines when known, quota observations with timestamps, and the next scheduled recovery or operator action. Distinguish process liveness, catalog availability, credential eligibility, and recently observed completed inference.

Explain observed allocation using separate counts for new bindings, affinity reuse, reselection/failover, upstream attempts, and completed requests. Include model and observed token usage where available, but never equate token counts or HTTP counts with exact subscription allowance consumption. Report missing telemetry, retention gaps, restarts, and observation age instead of manufacturing a complete historical account.

Identify the responding instance and running build. For a multi-host investigation, allow sanitized reports from independently authorized instances to be compared by the operator or existing tooling without copying credentials or assuming identical runtime state from identical configuration. Recommend a narrowly targeted next action, clearly separating read-only diagnosis from any state-changing recovery.

Acceptance criteria

• A controlled two-account pool with one account in a long cooldown reports the affected model/account, exclusion reason, recorded deadline, and evidence timestamp while recognizing that the other account can still serve requests.
• A still-usable account with recorded terminal renewal failure is distinguishable from a fully renewable account, and the relevant access expiry and required human action are visible when that evidence is available.
• Equal new-binding counts with unequal follow-up volume are explained as affinity/workload effects; an account excluded from all new bindings is not misreported as ordinary round-robin variance.
• The report distinguishes a quota observation from a scheduler cooldown. Fresh available-looking quota alongside an active cooldown is presented as conflicting evidence for investigation, not silently cleared by the report.
• HTTP 200 on a streaming response is not labeled complete inference without the relevant terminal completion evidence. Any optional active check is separately requested and has bounded cost and account attribution.
• Read-only inspection does not select a credential, extend an affinity TTL, reset quotas, trigger login, or consume telemetry needed by another observer. Repeated reads leave operational routing decisions unchanged.
• A recent process restart or a limited retention window is reflected in count coverage. Missing data is reported as unknown, including when a plugin owns scheduling and native state is not authoritative.
• The default export omits tokens, API keys, request/response bodies, account emails, physical credential paths, and OAuth callback data. It remains useful through a supported local access path or narrowly scoped existing access without requiring public management exposure.
• Two sanitized instance reports make differing running builds and account eligibility evident without implying that a shared round-robin counter or a fleet-wide credential store exists.

Affected area

Read-only operational diagnostics built on existing runtime account state, routing evidence, usage accounting, and instance identity. This feature can explain failures before automatic recovery or new routing policies are implemented; those repairs are not blocking dependencies.

Non-goals

• Changing credential eligibility, migrating sessions, resetting cooldowns, restarting services, or reauthenticating accounts during diagnosis.
• Requiring CodexBar, a specific desktop application, a central multi-host service, or unrestricted management credentials.
• Promising exact billing or quota calculations from incomplete request/token telemetry.
• Replacing existing usage sinks or exposing raw usage records wholesale.

Supporting context

For September 12, 2026 at 07:46:07–20:38:55 PDT, one instance had 80 versus zero new binding events and 1,331 versus zero attributable request IDs. The second instance had 44 versus 41 new bindings and 674 versus 481 attributable requests. The first pattern was explained by prior quota exclusion; the second was compatible with sticky sessions and unequal work. This difference was only established through manual reconstruction.

At inspected commit ac02da6c05e18f465aa7e3ed5b0a65a2f060917d, auth-file management output already provides status, counters, passive quota observations, and retry metadata. Its quota payload deliberately separates observations from scheduler state. Usage records already carry account attribution and token detail, but also contain sensitive fields unsuitable for an unfiltered diagnostic export. Reuse appropriate existing evidence while respecting those distinctions.

Issue #5604 discusses native affinity observation; current source already includes supported affinity lookup functionality. Open, unmerged PR #4519 proposes a Codex integration doctor focused on client configuration and model catalogs. Coordinate with those capabilities; this request's closure is an account-pool readiness and allocation explanation rather than another model-catalog integration.