[kartojal]

Coalesces refresh consumers and keeps logout safe during token rotation, including retry backoff after an uncertain refresh outcome.

Fresh-token requests and late 401 recovery await the accepted shared rotation. Logout closes local consumers, retains the latest started rotation outcome for revocation, and does not adopt or persist logout-only credentials. A possibly consumed refresh token is not resubmitted. Valid-bearer revocation, cancellation isolation and deterministic timer cleanup are preserved.

Rebased onto #438, retaining automatic L2 migration, plain bearer credentials and signer-only restoration from #437. Resolved the logout documentation conflict without reintroducing obsolete L2-client behavior.

Inherits #437's setup-failure session revocation and deferred new-session credential notifications. The stack was rebased with regression coverage for routed wallet deployment failures and #441's rotation-aware logout.

Stack: #442 → #481 → #437 → #463 → #438 → #441.

Restacked on 2026-11-02 with the current retry/transport ancestry and #463 Gateway routing corrections. Existing plain bearer credentials, automatic migration and signer-only restoration are retained.

Combined stack validation on 2026-11-02: build, lint, workspace typecheck, browser bundle check, 415 bindings tests and 1,159 client tests passed (1,574 total, no type errors). Failure-path coverage uses controlled responses. Live production checks additionally passed for an existing Deposit Wallet: signed login, automatic saved-L2 migration without signing, authenticated order/trade/notification/trading-status/balance-allowance reads, bearer restoration/refresh, and logout with rejected refresh reuse. No trading, transfers, approvals or wallet deployment were performed.

Gateway heartbeat compatibility remains blocked as documented in #463. Human approval and outstanding review threads have not been resolved automatically.

---

Note

High Risk
Changes core session token rotation and logout semantics, including refresh-token reuse rules and race handling that affect every authenticated client lifecycle.

Overview
Auth session refresh and logout are tightened so concurrent callers share one rotation and logout stays safe when a refresh is in flight or in retry backoff.

ready() and recover() now join an active refresh (including while the access token is still fresh), and refresh() installs the shared promise before the refresh callback runs so synchronous re-entry cannot start a second rotation. Each network attempt is tracked via #refreshRequest so logout can await the in-flight result for revocation only—without adopting tokens, firing onCredentialsChanged, or re-submitting a refresh that may already have consumed the refresh token.

Logout closes local consumers immediately (#stop(false)) instead of aborting rotation up front, then chooses revoke vs one explicit refresh for expired_access_token based on whether further refresh is still allowed after uncertain or definite failures. close() still aborts in-flight renewal; closing before #renew runs skips the callback entirely.

The authentication migration doc logout section is updated to describe drain-on-logout, uncertain-outcome behavior, and immediate local shutdown. session.test.ts adds regression coverage for coalescing, logout drain, no replay during backoff/uncertainty, and revocation after a failed refresh attempt.

^{Reviewed by Cursor Bugbot for commit 791cf76. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fa3daee. Configure here.}