Bug: OAuth Session Expired Cannot Be Refreshed

[malys]

Summary

The application sometimes loses authentication and displays:

Failed to authenticate: OAuth session expired and could not be refreshed

The user must manually reauthenticate even though the application should ideally refresh the session automatically.

Environment

• Claude Code Studio: v7.x
• Authentication: OAuth
• Provider: [provider name if known]

Current Behavior

The application displays:

Failed to authenticate: OAuth session expired and could not be refreshed

Actions requiring authentication stop working until the user manually reconnects.

Expected Behavior

When an OAuth access token expires:

1. The refresh token should be used automatically.
2. The session should remain active.
3. The user should only be prompted to log in again if refresh has genuinely failed.

Suggestions

• Display the root cause of the refresh failure.
• Log OAuth refresh attempts.
• Indicate whether:
  • the refresh token is missing,
  • the refresh token is expired,
  • the provider rejected the refresh request,
  • the network request failed.
• Provide a "Reconnect" button directly from the error message.

Impact

• Interrupted workflows.
• Long-running tasks may stop unexpectedly.
• Users must manually reauthenticate.

Priority

High

[Lexus2016]

Fixed in #87 (merged, v7.16.1). Thank you for the report — the visible symptom turned
out to be hiding a worse one.

What was actually happening. An auth failure is not subtype:'success', so all
three agent loops auto-continued it. Every continue failed instantly with the identical
error, the whole auto-continue budget emptied in seconds, and the run then ended as a
generic agent_incomplete that named nothing. A chain task retried twice more on top of
that. So "work stops and I am not told why" was the visible half; the silently burnt
budget was the rest.

What now happens. auth-errors.js classifies the stop and the run breaks
immediately — no auto-continue, no chain retry. You get:

• a chat notice naming the root cause and the action (claude login, and on the remote
  host for an SSH project),
• a auth-failure log line carrying the root-cause kind,
• a 🔐 badge on the Kanban card with a parseable auth_error:<kind> reason, so an auth
  stop is no longer indistinguishable from an ordinary failure on the board.

Three root-cause buckets are separated: an OAuth refresh that failed, a rejected API key,
and a CLI that was never logged in — each with its own next step.

On "the session should refresh automatically" — declined, with a reason. Studio
cannot do that, and shouldn't be able to. The OAuth tokens belong to the claude CLI's
own credentials store; the refresh exchange needs a refresh token and client credentials
this server has never held and must not hold. Refreshing is the CLI's job — and the
message you saw is the CLI reporting that its own refresh failed. The only correct move
on this side is to stop at once and say exactly what a human has to do, which is what
this change does. If the refresh keeps failing for you after claude login, that one
belongs upstream in the CLI.

One related note: the preflight authenticated flag can't catch this either. It checks
that ~/.claude/.credentials.json exists, and an expired token's file exists too —
telling a live token from a dead one needs a network round trip. So the stop is caught
reactively, mid-turn.

Please pull v7.16.1 and reopen if an auth stop still goes unexplained.