feat(buzz-agent): refresh OAuth bearer per request, not per process

[manuarraya]

The problem

buzz-agent read its bearer from OPENAI_COMPAT_API_KEY once, at startup. An
environment variable cannot be changed from outside a running process, so the only
way to pick up a renewed token was to restart the agent — restarts were the
refresh mechanism, not a maintenance detail.

That makes uptime and credential validity the same variable. Against a provider
whose access tokens live ~6h, a long-running fleet has to be restarted more often
than it runs, and every scheduler bug becomes an auth outage.

One did. A reload unit kept calling systemctl --user after the units had moved to
system scope, so it silently matched nothing. Six agents ran ~10 hours on a token
that died after six. Every unit reported active (running) the whole time: they
accepted work, failed the LLM call, retried, and dropped it.

The change

Add a session-file-backed TokenSource, selected when OPENAI_COMPAT_SESSION_FILE
is set. It re-reads the session on every request and exchanges the refresh_token
when the access token is within 10 minutes of expiry, so validity no longer depends
on process lifetime.

Refresh tokens rotate, so a naive version loses the credential when two agents
refresh at once — the second writes a refresh_token the provider has already
invalidated. Writes take a cross-process O_EXCL lock with stale-steal, and both
entry points re-check under it (the token is usually already fresh, making the
refresh a no-op). Sharing one session file across agents is what makes rotation
safe: N private copies drift until each holds a token that has been rotated away.

Second commit: resolve_provider() required OPENAI_COMPAT_API_KEY for
openai-compat, so an agent authenticating from a session file exited during
config parsing — before build_token_source() could ever select the new source.
The feature was unreachable in exactly the deployment it was written for. A session
file is an alternative credential, not an extra.

Notes for review

• RFC3339 handling is hand-rolled rather than adding chrono for two fields, and
  validates ranges — an earlier version parsed 2026-13-99T99:99:99Z happily and
  would have treated a corrupt session as valid forever.
• Behaviour is unchanged when no session file is configured.
• Covered by tests for skew boundaries, rotation persistence, concurrent refresh
  under the lock, stale-lock recovery, and malformed/out-of-range timestamps.

Testing

cargo test -p buzz-agent — 426 passing.

Two integration tests (steer_folds_into_active_turn_without_cancelling,
cancelled_turn_with_usage_emits_notification_before_response) are flaky under
parallel execution. I confirmed they fail on unmodified origin/main at the same
rate, so they are pre-existing and unrelated to this change.

Also verified in production: with the access token forced to a dead value, an agent
answered a mention in 3s and the session's expires_at advanced — 0 auth errors.

🤖 Generated with Claude Code