[P2] Token refresh robustness (contract, headless rotation, single-flight, 401 surfacing)

[Bccorb]

Severity: P2 — Bug/Fragility

Where: src/core/authClient.ts:91-139, src/core/keychain.ts:95-98

Problem

• tokensFromAuthResponse wipes the session unless /refresh echoes BOTH access and refresh tokens — brittle if the server rotates only the access token.
• Headless SEAMLESS_REFRESH_TOKEN always returns the env value; a server-rotated token is written to the keychain but the next run re-reads the (consumed) env var → ReauthRequired after first rotation.
• No single-flight guard: concurrent 401s fire parallel /refresh that can invalidate each other under rotation.
• A second 401 after refresh is returned verbatim instead of raising ReauthRequiredError, so callers show opaque errors.

Suggested fix
Accept access-only refresh responses; add a refresh mutex; surface persistent 401 as ReauthRequired; document headless rotation behavior.

Filed from an internal code audit (2026-07). File references are against main at audit time.