Requirement
Make the multi-auth pool represent distinct Codex accounts rather than distinct auth files. The current runtime ID is derived from the relative file path, so duplicate files can add unintended weight and persisted references can silently point at a different account after file replacement.
Decisions
- Multi-auth remains a supported core capability.
- Multiple files for the same Codex account represent one auth, not multiple weighted slots.
- Prefer
account_id as the stable credential identity.
- When
account_id is missing, recover a stable account claim from id_token or the access token where possible.
- Fall back to a normalized relative auth path only when no stable account identity is available.
- A path-identified compatibility auth may continue serving proxy traffic, but it is reported as
unidentified and remains read-only through account-targeted management APIs until a real account ID can be recovered.
- Reparse refreshed identity tokens so account ID and email metadata remain current.
- Coordinate runtime reloads by account identity rather than file path.
- Token content changes for the same account preserve session bindings, clear credential-related
401/invalid_grant state, and preserve unexpired quota/429 cooldowns.
- Moving or renaming a file without changing its account identity does not change the logical auth.
- Replacing a path with credentials for a different account is an old-auth removal plus a new-auth addition; persisted references to the old account cannot attach to the replacement.
- External
disabled changes update new-request eligibility without deleting bindings or terminating active connections.
- Adding a valid auth file is detected without process restart.
- When all files for an account disappear, stop new selection and reconcile the account's persisted runtime state.
- Keep the last successfully parsed representation through a short parse-error grace period so an editor's partial write does not make an auth disappear transiently. A persistently invalid file must eventually be reported and excluded.
- Keep the implementation Codex-specific and single-process; do not introduce CPA's generic provider scheduler.
Acceptance Criteria
- Auth loading deduplicates files that resolve to the same Codex account.
- Round-robin selection cannot assign extra weight merely because an account is present in multiple files.
- Auth ordering and identity are deterministic across reloads and process restarts when account metadata is stable.
- File rename, same-account token replacement, account replacement at one path, disable changes, file addition, file removal, and temporary malformed writes follow the documented reconciliation rules.
- Replacing or removing an auth file cannot silently preserve an invalid persisted identity mapping.
- Missing or malformed identity claims degrade to the documented path fallback without panicking or exposing token contents.
- An unidentified compatibility auth remains selectable but cannot receive account-targeted management mutations.
- Reconciliation emits safe state changes consumed by session affinity, credential error clearing, cooldown state, model capability, and management status.
- Tests cover duplicate account files, account-ID fallback, unidentified management behavior, refreshed identity metadata, all hot-reload cases, and parse-error grace expiry.
Non-goals
- Configurable per-auth weights.
- Multiple active proxy processes sharing one auth directory.
- Alternate auth storage backends.
- A generic file-watcher framework; existing request-time reload behavior may be reused.
Dependencies
None. This establishes the identity and reconciliation contract used by #4, #5, #6, #8, and #9.
Verification
gofmt -w .
go test ./...
go build -o test-output ./cmd/server && rm test-output
Requirement
Make the multi-auth pool represent distinct Codex accounts rather than distinct auth files. The current runtime ID is derived from the relative file path, so duplicate files can add unintended weight and persisted references can silently point at a different account after file replacement.
Decisions
account_idas the stable credential identity.account_idis missing, recover a stable account claim fromid_tokenor the access token where possible.unidentifiedand remains read-only through account-targeted management APIs until a real account ID can be recovered.401/invalid_grantstate, and preserve unexpired quota/429cooldowns.disabledchanges update new-request eligibility without deleting bindings or terminating active connections.Acceptance Criteria
Non-goals
Dependencies
None. This establishes the identity and reconciliation contract used by #4, #5, #6, #8, and #9.
Verification
gofmt -w .go test ./...go build -o test-output ./cmd/server && rm test-output