feat(quota-cooldown): handle xAI free usage exhaustion

[lost9999]

Summary

Extend the existing CPAMP-owned quota cooldown worker to xAI/Grok's exact subscription:free-usage-exhausted HTTP 429 signal. Matching auth files are temporarily disabled and automatically restored after the documented rolling 24-hour recovery window, while manual disables remain untouched.

Scope

• Frontend panel
• Manager Server
• CPA panel mode
• Full Docker mode
• Native packages / release
• Docs / Wiki
• CI / build / tooling

Changes

• Normalize xai, x-ai, and grok provider keys and match only the exact free-usage exhaustion code, including nested JSON error payloads.
• Reuse the existing quota cooldown persistence and CPA Management API actions with a dedicated cpamp_xai_free_usage owner.
• Preserve CPAMP ownership boundaries: only CPAMP-disabled files are restored; pre-existing manual disables are skipped.
• Update quota policy copy and English/Chinese operations documentation.
• Add regression coverage for exact matching, negative errors, provider aliases, persisted ownership, end-to-end disable/recovery, and manual-disable protection.

User Impact

When quota cooldown is enabled, exhausted xAI/Grok free credentials leave the CPA selection pool after their first exact quota failure and return automatically after 24 hours. Regional permission errors, auth errors, generic rate limits, 5xx responses, and timeouts do not trigger this path.

Compatibility / Runtime Notes

• CPA panel mode: No behavior change; the worker is a Manager Server feature.
• Manager Server mode: Uses the existing USAGE_QUOTA_COOLDOWN_ENABLED / Configuration switch. The feature remains disabled by default.
• Full Docker / native packages: No schema migration or new service is required. Existing Codex cooldown behavior remains compatible.

Data / Security Notes

No auth tokens, raw error bodies, or credentials are persisted by this change. The existing quota_cooldowns table stores auth file identity, provider, recovery time, owner, and prior disabled state. Actions continue to use CPA Management API authentication. No auth JSON fields are added or modified directly.

Risk / Rollback

Risk level: Low

Rollback notes:

• Disable USAGE_QUOTA_COOLDOWN_ENABLED or the matching Configuration switch to stop new automatic actions.
• Revert this PR; no database migration or cleanup is required.
• Existing cooldown rows with owner cpamp_xai_free_usage remain auditable and can be handled by the pre-existing quota cooldown API.

Verification

• Type check
• Lint
• Tests
• Build
• Manual UI check
• Docs/link check
• Not applicable, docs-only

Commands / evidence:

npm run type-check
npm run lint
npm test
  Test Files 86 passed (86)
  Tests 728 passed (728)
npm run build
npm run docs:build

go test ./... -count=1
go test -race ./internal/worker -count=1
  all packages passed

docker build --no-cache -f Dockerfile.manager-server -t cpamp-xai-guardian:final-test .
  exit 0

docker run ... cpamp-xai-guardian:final-test
curl http://127.0.0.1:18318/health
  {"ok":true,"service":"cpa-manager-plus"}

git diff --check
  exit 0

Screenshots / Recordings

N/A. The existing Configuration card is retained; only its localized description changes to include xAI.

Docs

• README updated
• Wiki updated
• Release notes needed
• Not needed

Related

Closes #334. Supersedes the closed exploratory PR #330.

[lost9999]

All local merge-readiness gates are green (Manager Server full tests, worker race test, 728 web tests, type-check, lint, web/docs builds, clean Docker build, and container health smoke test). GitHub currently marks all workflows as action_required with zero jobs because this is a fork contribution awaiting maintainer workflow approval. Please approve the workflow runs when convenient; I will follow up on any CI or review feedback.

[lost9999]

Follow-up pushed: 14f8828 fixes the Auth Files UI gap found in independent review. xAI cooldown records now render on xAI auth cards; a focused regression test passes alongside TypeScript type-check and lint. This does not change the automatic recovery behavior: xAI has no supported post-recovery quota probe in this slice, so recovery refreshes the auth list without invoking Codex-only quota APIs.