[FEATURE]: Support multiple API keys/credentials with round-robin rotation per provider #29085

Problem

Currently, each provider in opencode.json only accepts a single apiKey string:

{
  "provider": {
    "openrouter": {
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-v1-xxx"
      }
    }
  }
}

Users managing multiple API keys for high availability, team-level key distribution, or gradual key rotation must use external tools, or custom rotation proxies. This adds unnecessary complexity and latency.

Proposed Solution

Allow apiKey (and auth-dir/auth files) to accept an array of credentials with built-in round-robin rotation and automatic failover.

API Key Array (Simple Case)

{
  "provider": {
    "openrouter": {
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": [
          "sk-or-v1-key1",
          "sk-or-v1-key2",
          "sk-or-v1-key3"
        ]
      }
    }
  }
}

Auth File/Directory Array

For providers that use file-based auth (e.g. OAuth tokens, cookie files):

{
  "provider": {
    "copilot": {
      "options": {
        "authFile": [
          "/path/to/auth1.json",
          "/path/to/auth2.json",
          "/path/to/auth3.json"
        ]
      }
    }
  }
}

Expected Behavior

1. Round-robin distribution: Requests are distributed across credentials in sequence (key1 → key2 → key3 → key1 → ...), spreading load evenly for high availability.
2. Automatic failover: When a credential returns 429/5xx, automatically retry with the next credential before failing the request.
3. Session affinity (optional): Option to pin a session to one credential to avoid inconsistent responses.
4. Cooldown: Temporarily skip credentials that have been rate-limited recently.

Use Cases

• High availability: Redundant API keys so a single key revocation doesn't break workflows.
• Team key management: Distribute requests across multiple team or department keys with separate billing.
• Gradual key rotation: Roll over API keys without downtime by adding the new key first, then removing the old one.
• Regional distribution: Use region-specific keys for better latency in multi-region deployments.

Related: #16038 (fallback only, does not cover round-robin or auth file arrays)