[AntTheLimey]

What changed

Step 2 of browser sign-in, stacked on #73. It removes the forced re-login when the access token expires.

• Login requests offline_access and keeps Auth0's refresh token in the OS keychain, under its own entry, never in the config file or token cache. With no refresh token or no keychain, login behaves exactly as in feat: browser sign-in for pgedge starfleet #73.
• Renewal happens when a session is near expiry, at first use or mid --wait. The rotated refresh token is saved before the new access token is cached and used. A per-profile lock file serialises renewal across processes. Under the lock, the cache is re-read so a second process uses the first one's renewal instead of reusing a rotated token, which Auth0 would treat as theft and revoke. saas#2043 also adds a 10s reuse leeway.
• A refused renewal (invalid_grant) clears the refresh token, but only if it's still the one sent, and gives the existing exit-5 "sign in again" message. A network or 5xx failure keeps the token and falls back to the current access token while it's valid.
• Logout revokes the refresh token at Auth0 (best-effort), then clears it. A refresh token that a new login or an API-client login replaces is revoked too.
• auth status and doctor report whether a session renews. An expired access token with a refresh token is "renews on next use", exit 0.
• --debug masks the refresh token, the token responses and the revoke token field.
• Docs, llms pages and the starfleet skill say a session renews while in use and ends after a period without use or a fixed maximum.

Checks

• make test passes. Coverage is 90.0% against the 90.0% threshold. make lint, make docs-check and make lint-docs are clean.
• 4 new test functions: rotation order, refused renewal, logout revoke, and two concurrent renewals against a stub Auth0 that treats reuse as theft. Four existing tests were extended.
• Mutation checks, all caught:
  • no rotated save
  • no access-token cache
  • token kept after invalid_grant
  • flag path clearing the session
  • lock removed
  • re-read removed
  • cache written before the keychain
• One independent review: 1 Important finding (concurrent renewal wiping the session) and 4 Minor, all fixed here.

Risks

• Coverage sits exactly at the threshold, so the next change that lowers it fails make test.
• The stale-lock takeover after a crash is untested. The lock is taken over after 45s and waiters give up after 50s.
• Tested against the dev Auth0 with saas#2043 applied. Sign-in requested offline_access and stored the refresh token in the keychain. Two renewals forced 15s apart, beyond the 10s reuse leeway, each returned a new access token and a working managed database list, so each rotated refresh token was saved and used. The account requires MFA, so renewal also confirms MFA is skipped on refresh. Logout removed the cache entry and the keychain entry; the next call failed with exit 5. Prod gets saas#2043 once its deploy passes the integration gate.