[DOCS] Remote Control troubleshooting missing "stuck on reconnecting" entry for OAuth token refresh race during session resume

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/remote-control

Section/Topic

"Troubleshooting" section under Remote Control, plus the "Survive interruptions" bullet in the introduction and the "Limitations" section. There is no troubleshooting entry for a Remote Control session that hangs on the "reconnecting" indicator after a session resume.

Current Documentation

The Remote Control page currently documents reconnect behavior at a high level in two places:

In the introduction:

* Survive interruptions: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online

In the "Limitations" section:

* Extended network outage: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run claude remote-control again to start a new session.

The Troubleshooting section ends with ### "Remote credentials fetch failed" and does not list a scenario where the client stays on the "reconnecting" indicator indefinitely after resuming a session. The page also does not mention OAuth token refresh at all, even though the underlying credentials are short-lived OAuth tokens per the "Connection and security" section:

The connection uses multiple short-lived credentials, each scoped to a single purpose and expiring independently.

What's Wrong or Missing?

A. No troubleshooting entry for the "stuck on reconnecting" symptom

A user whose Remote Control session is frozen on the "reconnecting" indicator after resuming via claude --resume or reconnecting from claude.ai/code has no documented recovery path. The Troubleshooting section lists error-string scenarios (e.g. "Remote credentials fetch failed", "Remote Control requires a full-scope login token") but does not cover the "stuck on reconnecting" UI state.

B. Reconnect behavior is documented as automatic without acknowledging the OAuth refresh race

The "Survive interruptions" bullet and the "Connection and security" section imply that reconnect is fully automatic, but they do not mention that an OAuth token refresh happening at the same time as the resume can leave the session in a stuck state until the fix from v2.1.169 is applied. Users running older versions have no signal from the docs that this is a known condition and that upgrading resolves it.

C. Limitations section is silent on the OAuth refresh window

The "Limitations" section enumerates the 10-minute network outage window and the local-process constraint, but it does not mention that OAuth token rotation during resume is another failure mode the user can hit.

Suggested Improvement

Add a new troubleshooting entry to https://code.claude.com/docs/en/remote-control between the "Remote credentials fetch failed" entry and the "Choose the right approach" section, modeled on the existing troubleshooting style:

### "Remote Control is stuck on 'reconnecting'" The session indicator stays on "reconnecting" indefinitely after a resume from claude --resume, the claude.ai/code page, or the Claude mobile app. This happens when the connection's OAuth token expires at the same moment the client tries to reattach. Run the session with claude remote-control --verbose (or claude --remote-control --verbose for an interactive session) to confirm the retry loop in the logs. The condition is fixed in Claude Code v2.1.169. Upgrade with claude update and reconnect. If you cannot upgrade immediately, stop the session with claude remote-control and start it again — the new host process acquires a fresh short-lived credential and reconnects cleanly.

Also tighten the "Survive interruptions" bullet so users understand the recovery path is not just network/sleep but also covers the credential refresh case. Suggested wording:

* Survive interruptions: if your laptop sleeps, your network drops, or the connection's OAuth token rotates during a resume, the session reconnects automatically when your machine comes back online

And add a corresponding line to the "Limitations" list:

* OAuth token refresh during resume: on versions before v2.1.169, a session resume that races an OAuth token refresh can hang on the "reconnecting" indicator. Upgrade to v2.1.169 or later to avoid this.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/remote-control | Primary documentation — missing troubleshooting entry, generic "Survive interruptions" wording, no Limitations mention of OAuth refresh |
| https://code.claude.com/docs/en/troubleshooting | Top-level troubleshooting index — does not currently list a Remote Control "stuck on reconnecting" entry |

Total scope: 1 page affected (with a cross-reference from the top-level troubleshooting index).

Changelog reference: The fix is recorded in the 2.1.169 entry of the Claude Code changelog as:

Fixed Remote Control getting stuck on "reconnecting" after resuming a session when an OAuth token refresh happened at the same time

Related fix in the same release for context: Fixed enterprise managed MCP policies ... not being enforced on reconnect — the v2.1.169 release ships multiple reconnect-path fixes, which strengthens the case for a dedicated troubleshooting entry that covers the reconnect family of issues rather than only the OAuth refresh symptom.