[DOCS] [Authentication] No documentation for the v2.1.203 proactive login-expiry warning that prevents background-session interruption

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/authentication

Section/Topic

The "Log in to Claude Code" section, the "OAuth token revoked or expired" troubleshooting entry in the error reference, and the "Dispatch fails with Could not resolve authentication method" troubleshooting entry under agent view. None of these pages describe the new warning Claude Code emits when the saved login is approaching its expiration date.

Current Documentation

From authentication.md (line 27):

To log out and re-authenticate, type /logout at the Claude Code prompt.

From errors.md (lines 475-490), the existing "OAuth token revoked or expired" entry only documents a reactive failure:

Your saved login is no longer valid. A revoked token means you signed out everywhere or an admin removed access; an expired token means the automatic refresh failed mid-session. ``text theme={null} OAuth token revoked · Please run /login OAuth token has expired · Please run /login API Error: 401 ... authentication_error ` **What to do:** * Run /login to sign in again * If the error returns within the same session after re-authenticating, run /logout first to fully clear the stored token, then /login` * For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in Troubleshooting

From agent-view.md (lines 604-614), the existing entry covers the case where the supervisor already failed because no stored credential was available:

### Dispatch fails with Could not resolve authentication method If a background dispatch fails with Could not resolve authentication method while interactive sessions authenticate normally, the worker that received the dispatch didn't pick up credentials. The supervisor supplies a fresh credential snapshot when it assigns a [pre-warmed worker](#the-supervisor-process), so this error means no stored credential was available to the supervisor process itself. Confirm you have run /login or configured an API key, then stop the supervisor

From troubleshoot-install.md (lines 804-808):

### Not logged in or token expired If Claude Code prompts you to log in again after a session, your OAuth token may have expired.

None of these pages mention a warning that fires before the token actually expires, or that the warning is intended specifically to give the user time to re-authenticate without interrupting running background sessions.

What's Wrong or Missing?

A. The new login-expiry warning behavior in v2.1.203 is undocumented

The v2.1.203 changelog records:

Added a warning when your login is about to expire, so you can re-authenticate before background sessions are interrupted

After v2.1.203, Claude Code is expected to surface a preemptive warning before the stored OAuth login reaches its expiration. The purpose of the warning, per the changelog, is to give interactive users time to re-authenticate (/login) before the refresh path fails and background sessions lose their credentials mid-task. None of the following describe that behavior:

• authentication.md only documents /login and /logout as the manual re-authentication controls.
• errors.md "OAuth token revoked or expired" describes the reactive "Please run /login" prompt that appears after the saved login is already invalid, not a pre-expiry heads-up.
• agent-view.md describes the failure mode where background sessions already failed with Could not resolve authentication method, with no guidance about preventing the failure via a pre-expiry warning.
• troubleshoot-install.md "Not logged in or token expired" frames the problem as something the user notices after the fact ("prompts you to log in again"), not something the user is warned about in advance.
• commands.md (the /login row) and the settings reference (settings.md) make no mention of a preemptive warning.

B. The docs still imply background sessions keep running until they fail

A user following the documented background-session flow reads about supervisor reconnection on wake, the awsAuthRefresh retry contract, and the gcpAuthRefresh settings, but nothing tells them that an expiring saved login will silently invalidate every running background session. The v2.1.203 changelog entry exists specifically to call out that re-authenticating earlier avoids that interruption, and the documentation does not yet carry that warning through.

C. There is no documented connection between the warning and /login

The warning is explicitly the prompt for the user to run /login. After v2.1.203 the natural place to describe it is the "Log in to Claude Code" section of authentication.md, alongside the existing /logout and re-authenticate paragraph, plus a cross-reference from agent-view.md so background-session operators learn that the warning is a way to keep their sessions healthy.

Suggested Improvement

Option A: Comprehensive fix

Add a paragraph under the "Log in to Claude Code" heading in authentication.md after the existing /logout line, for example:

{/ min-version: 2.1.203 /}When your saved login is approaching its expiration, Claude Code shows a warning that names the login and tells you to run /login. Re-authenticating before the saved login expires keeps any background sessions you have running from being interrupted when the next refresh fails. If the warning has already appeared and a background session has stopped with an authentication error, see Troubleshoot agent view and run /login from an interactive session, then restart the supervisor with claude daemon stop --any --keep-workers so it picks up the new credential snapshot.

Then, in errors.md, add a new entry directly under "OAuth token revoked or expired" titled something like "Login is about to expire" that links to the authentication page above and to the agent-view troubleshooting. And in agent-view.md, after the "Dispatch fails with Could not resolve authentication method" entry, add a one-line cross-reference to the new authentication-page paragraph so background-session operators learn that the warning is the way to avoid that failure.

Option B: Minimum fix

Add only the one paragraph to authentication.md under "Log in to Claude Code", and add a single "See also" link from agent-view.md to that paragraph. Leave the existing reactive errors.md entry untouched.

Impact

Medium - Makes feature difficult to understand

Additional Context

The v2.1.203 changelog entry is the only place this behavior is currently described. The agent-view page treats Could not resolve authentication method as a recoverable failure rather than one that can be pre-empted by a login warning, so the lack of cross-reference means background-session operators will continue to discover the warning only after it appears, rather than as a planned step before running long background tasks.

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/authentication | Primary documentation location for login//login//logout flow |
| https://code.claude.com/docs/en/errors | "OAuth token revoked or expired" entry only describes the reactive failure; no pre-expiry entry exists |
| https://code.claude.com/docs/en/agent-view | "Dispatch fails with Could not resolve authentication method" entry does not point users at the warning as a preventive step |
| https://code.claude.com/docs/en/troubleshoot-install | "Not logged in or token expired" entry describes the problem as a post-hoc symptom |

Total scope: 4 pages affected.