feat(claude): renovar el token OAuth sin tener que abrir Claude Code #188

Pre-flight checks

• Busqué en las issues existentes y en el roadmap (Roadmap ODD de Quorb #45): sin duplicados. La más cercana es feat: detectar renovación de sesiones CLI y distinguir cuentas #39 (cerrada), que detecta la renovación hecha por el CLI y muestra «Renovar sesión», pero declara expresamente que Quorb no renueva tokens.
• Entiendo que esta propuesta requiere revisión de producto antes de implementarse.

Problem to solve

El anillo de Claude depende de que Claude Code renueve el access token de ~/.claude/.credentials.json. Quorb nunca lo renueva (src-tauri/src/providers/claude.rs:7-9): cuando caduca (is_expired, claude.rs:264) o el endpoint devuelve 401/403 (claude.rs:222), el proveedor pasa a NeedsLogin y la única salida es «Renovar sesión», que abre Claude Code.

Esto se nota mucho cuando Claude Code no es el cliente del día a día. Yo trabajo desde Pi/gentle-shell con la extensión pi-claude-bridge, que lanza el binario de Claude Code vía Agent SDK y por tanto comparte ~/.claude/.credentials.json: cuando uso Claude por el bridge, el token se renueva y Quorb se recupera. Pero alterno con otros proveedores (z.ai, Codex…) durante horas, y en ese tiempo nada renueva el token.

Evidencia de mi máquina (Windows):

• El access token dura 7 h (expiresAt 7 h después de la escritura del archivo); el refresh token, ~15 días (refreshTokenExpiresAt). Es decir, Quorb pierde el anillo aunque la sesión siga perfectamente renovable.
• En history.json de Quorb, las muestras de Claude se cortan siempre ~7 h después de la última renovación y vuelven solas en cuanto algo renueva. Ejemplo: sin muestras de Claude del 26/10 07:07 al 27/10 01:55 (hora de Madrid) mientras el resto de proveedores seguía registrando (197 muestras en el hueco). Ese día mis sesiones usaron solo z.ai. Las muestras vuelven a las 01:55:48, 13 s después de que el bridge reescribiera .credentials.json (01:55:35).
• En las dos últimas semanas hay 10 huecos de este tipo, de 2,5 h a varios días.

Resultado: cada vez que vuelvo a mirar el widget tengo que abrir Claude Code (o lanzar una petición a Claude) solo para que Quorb vuelva a leer el uso.

Proposed solution

Que Quorb renueve el token él mismo, compartiendo el mismo almacén de credenciales con el CLI en vez de tener uno propio. Así se evita el riesgo que motivó la decisión original: el refresh token rota en cada uso y, si Quorb se quedara con el par nuevo, el CLI se quedaría con un refresh token inválido y se cerraría su sesión.

1. Cuándo: solo si el access token ya caducó (o está a punto, con el mismo margen que is_expired) o si el endpoint de uso devolvió 401. Nunca de forma preventiva mientras sea válido.
2. Releer antes de renovar: volver a leer .credentials.json justo antes de la petición. Si expiresAt cambió desde la última lectura, el CLI ya renovó: usar ese token y no renovar.
3. Renovar: llamar al endpoint OAuth de refresh con el refreshToken (el mismo flujo grant_type=refresh_token que usa Claude Code).
4. Escribir de vuelta de forma atómica: guardar accessToken, refreshToken y expiresAt nuevos en el mismo archivo (temporal + rename), conservando el resto de campos tal cual (scopes, subscriptionType, claves desconocidas). En macOS, actualizar la entrada del Keychain «Claude Code-credentials» en vez del archivo.
5. Fallo controlado: si la renovación devuelve invalid_grant o algo inesperado, no reintentar en bucle: caer al comportamiento actual (NeedsLogin + «Renovar sesión»).
6. Interruptor: opción en Ajustes («Renovar automáticamente la sesión de Claude»), activada por defecto o no según decida el mantenedor, para quien prefiera que solo el CLI toque sus credenciales.

Piezas: src-tauri/src/providers/claude.rs (refresh + escritura atómica + reintento de la consulta), config.rs / Settings.tsx (interruptor) y tests deterministas sin red: archivo releído con expiresAt nuevo (no renueva), escritura que conserva campos desconocidos, invalid_grant vuelve a NeedsLogin sin tocar el archivo.

Affected area

Application behavior

Scope and non-goals

• Scope: cuenta principal de Claude y cuentas adicionales con credentials_path explícita, en Windows y Linux (archivo). macOS (Keychain) en la misma propuesta si es viable, o como fase aparte.
• Non-goals: guardar una copia propia de las credenciales; renovar mientras el token sea válido; renovar tokens de otros proveedores (Codex, Gemini) en esta issue, aunque el mismo patrón podría aplicarse después.

Alternatives considered

• Comportamiento actual (abrir Claude Code): funciona, pero obliga a intervenir a mano cada pocas horas a quien no usa el CLI a diario.
• Lanzar Claude Code en segundo plano para que renueve él: el dueño del token sigue siendo el CLI, pero depende de cómo se comporte ante una ejecución sin ventana, puede gastar cuota y es más frágil que una petición HTTP.
• Solo avisar antes de que caduque: reduce la sorpresa, pero sigue haciendo falta abrir Claude Code.

Riesgo conocido: si el CLI (o cualquier cliente que lance su binario, como el Agent SDK) y Quorb renuevan exactamente a la vez, uno de los dos puede quedarse con un refresh token ya usado. El paso 2 (releer antes de renovar) y renovar solo con el token caducado reducen mucho esa ventana, pero no la eliminan del todo sin un bloqueo compartido con el CLI, que no existe. En el peor caso se vuelve a la situación actual: hacer login otra vez en Claude Code.