fix(mcp-oauth): resilient config resolution + reduce config_source spawn amplification + cache OAuth discovery (TASK-326)

[Shooksie]

TASK-326: OAuth-bridging robustness

Fixes a failure cascade seen under bulk animus mcp call bursts:

a burst of mcp calls each spawned the animus-mcp-proxy, and each proxy spawn resolved config 3× and ran a live .well-known OAuth discovery. That saturated the config_source plugin (DB overload). The swallowing loader degraded the transient source failure into an empty base (BuiltinFallback), so resolve_server_url saw an empty mcp_servers map and reported the server as "not defined" / returned servers: [] — even though the server was configured and the token was valid. The OAuth discovery throttling separately surfaced as NoAuthorizationSupport ("No authorization support detected").

The three changes

• (d) Resilient config resolution — a new non-swallowing loader try_load_workflow_config returns a distinct three-way outcome (Loaded / NoSource / SourceUnavailable) instead of collapsing every failure into an empty builtin base. Credential/OAuth resolvers route through it, so a transient config_source outage surfaces as a distinct retryable "config source unavailable" error rather than silently emptying mcp_servers and misreporting the server as "not defined". This holds even when --url is supplied (a --url overrides only the endpoint, not the oauth flow/block).

• (c) Reduce config_source spawn amplification — the proxy now trusts the already-resolved --url passed by the daemon/CLI contract and skips re-resolving config on connect. This drops config_source spawns from 3× → 1× per mcp call. The URL is bound into the keychain key (security control retained), so a repointed server still fails closed.

• (a) Cache OAuth discovery metadata — discovered RFC 8414/9728 .well-known metadata is cached per (server, url) under the scoped state root (24h TTL, best-effort, non-secret) so repeated proxy spawns reuse it instead of re-hitting the throttled upstream discovery endpoint on every connect.

Unauthenticated-priming gate

Discovery priming is now gated on a stored token existing: connect_with_store checks the credential store's load first and only primes/discovers when a token is present. An unauthenticated server (no stored token) skips the network discovery and takes the normal fast-fail path — restoring fast startup instead of regressing it into a needless .well-known round-trip. Covered by a new unauthenticated_server_skips_discovery_priming integration test.

Scope

ao-cli only — no plugin/runner pin bumps, no protocol changes.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
animus-docs	Ready	Preview, Comment	Jul 12, 2026 1:40pm