fix(kiro): surface a dead refresh token as needing re-auth

docs-site/src/content/docs/guides/providers.md

@@ -448,6 +448,16 @@ token counts may still be estimated, and the credit value does not replace USD c
 Completion fallback requests add their reported credits. An absent value means Kiro did not
 report credit usage; an explicit zero means it reported no spend.
 
+### Kiro refresh attention
+
+If an AWS SSO refresh returns `400 invalid_request` and matching Kiro CLI recovery does not
+succeed, the dashboard shows the affected account as needing re-authentication once its access
+token expires. The active provider then reports `loggedIn: false` from `/api/oauth/status`.
+A still-valid access token remains logged in. You can sign in again through the dashboard;
+a later successful automatic refresh also clears the attention state. This status does not
+classify the refresh grant as revoked or disable future refresh attempts. Network and server
+errors do not trigger this status.
+
 ### Kiro credential import
 
 The dashboard offers native Builder ID, Google, and GitHub device login without Kiro CLI.

scripts/test-layout/layout.json

@@ -1060,7 +1060,7 @@
     "kiro-images.test.ts": "providers/kiro",
     "kiro-leased-responses.test.ts": "providers/kiro",
     "kiro-model-catalog.test.ts": "providers/kiro", "kiro-model-preference.test.ts": "providers/kiro",
-    "kiro-oauth.test.ts": "providers/kiro",
+    "kiro-oauth.test.ts": "providers/kiro", "oauth-kiro-refresh-attention.test.ts": "oauth",
     "kiro-pool-load-settings.test.ts": "providers/kiro",
     "kiro-pool-rank.test.ts": "providers/kiro",
     "kiro-reasoning-roundtrip.test.ts": "providers/kiro",

src/oauth/health.ts

@@ -10,7 +10,7 @@ import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability"
 import { maskAccountId } from "../lib/privacy";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
-import { loadAuthStore, peekAuthStore, peekOAuthRefreshIntent, readOAuthRefreshIntent } from "./store";
+import { accountNeedsReauthForStatus, loadAuthStore, peekAuthStore, peekOAuthRefreshIntent, readOAuthRefreshIntent } from "./store";
 import type { ProviderAccount } from "./types";
 
 export type OAuthAccountHealth =
@@ -210,9 +210,10 @@ export function projectStoredOAuthAccountHealth(
   const anthropicSnap = provider === "anthropic"
     ? getAnthropicAccountHealthSnapshot(account.id, now)
     : null;
+  const needsReauth = accountNeedsReauthForStatus(provider, account, now);
   return projectOAuthAccountHealth({
-    needsReauth: account.needsReauth === true,
-    reauthReason: account.needsReauth === true
+    needsReauth,
+    reauthReason: needsReauth
       ? (account.needsReauthReason ?? "refresh_failed")
       : undefined,
     cooldownUntilMs: anthropicSnap?.cooldownUntil,

src/oauth/index.ts

@@ -16,7 +16,7 @@ import {
   getAccountCredentialWithStatus,
   getAccountSet,
   getCredential,
-  markAccountNeedsReauthIfGeneration,
+  markAccountNeedsReauthIfGeneration, accountNeedsReauthForStatus, markAccountRefreshAttentionIfGeneration,
   markOAuthRefreshIntentCleanupPending,
   markOAuthRefreshIntentStaleOwner,
   mergeAccountCredential,
@@ -1116,6 +1116,10 @@ export async function refreshGenericAccountWithLock(
       return fresh.access;
     } catch (error) {
       if (error instanceof OAuthMutationBusyError) throw error;
+      if (provider === "kiro" && error instanceof KiroTokenRefreshError && error.refreshAttention) {
+        await markAccountRefreshAttentionIfGeneration(provider, accountId, generation, writerGeneration);
+        throw error;
+      }
       if (!terminal(error)) throw error;
       // Nous-specific failure-atomicity: a terminal refresh error that carries
       // an already-issued rotated refresh token (e.g. the access JWT lacked the
@@ -1840,7 +1844,7 @@ export function getLoginStatus(provider: string, maskEmails = true): { loggedIn:
     ...(a.alias ? { alias: a.alias } : {}),
     email: projectEmail(a.credential.email, maskEmails) ?? undefined,
     active: a.id === set.activeAccountId,
-    ...(a.needsReauth ? { needsReauth: true } : {}),
+    ...(accountNeedsReauthForStatus(provider, a) ? { needsReauth: true } : {}),
     ...(a.needsReauth && a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     expiresAt: a.credential.expires,
     // Explicitly null rather than omitted — see OAuthAccountSummary.plan. No OAuth provider
@@ -1852,11 +1856,11 @@ export function getLoginStatus(provider: string, maskEmails = true): { loggedIn:
 
   // A stored credential counts as "logged in" when it exists and is not marked for
   // re-authentication. An expired access token with a valid refresh token is still
-  // logged in: request resolution refreshes expired/near-expiry credentials lazily.
+  // logged in unless refresh-attention evidence applies; refresh eligibility stays internal.
   // Invalid/unknown local-import expiries are handled at parse/adoption time
   // (local-token-detect.ts), never by over-reporting login state here.
-  const activeNeedsReauth = set?.accounts
-    .find(a => a.id === set.activeAccountId)?.needsReauth === true;
+  const activeAccount = set?.accounts.find(a => a.id === set.activeAccountId);
+  const activeNeedsReauth = activeAccount && accountNeedsReauthForStatus(provider, activeAccount);
   return {
     loggedIn: !!cred && !activeNeedsReauth,
     email: projectEmail(cred?.email, maskEmails) ?? undefined,

src/oauth/kiro.ts

@@ -60,6 +60,7 @@ export class KiroTokenRefreshError extends Error {
   constructor(
     readonly httpStatus: number,
     readonly oauthError?: string,
+    readonly refreshAttention = false,
   ) {
     super(`Kiro token refresh failed: ${httpStatus}${oauthError ? ` (${oauthError})` : ""}`);
     this.name = "KiroTokenRefreshError";
@@ -530,17 +531,21 @@ export function resolveKiroRequestProfile(
     : { profileArn: undefined, builderIdFallback: false };
 }
 
-async function kiroTokenRefreshError(response: Response): Promise<KiroTokenRefreshError> {
+async function kiroTokenRefreshError(response: Response, awsSsoRefresh = false): Promise<KiroTokenRefreshError> {
   let oauthError: string | undefined;
+  let refreshAttention = false;
   try {
     const payload = await response.json() as { error?: unknown };
+    // This input-error code is attention evidence only for our AWS SSO refresh request,
+    // never a terminal grant verdict. Do not surface arbitrary upstream descriptions.
+    refreshAttention = awsSsoRefresh && response.status === 400 && payload.error === "invalid_request";
     if (typeof payload.error === "string" && KIRO_TERMINAL_REFRESH_ERRORS.has(payload.error)) {
       oauthError = payload.error;
     }
   } catch {
     // Error bodies are untrusted and intentionally excluded from the surfaced message.
   }
-  return new KiroTokenRefreshError(response.status, oauthError);
+  return new KiroTokenRefreshError(response.status, oauthError, refreshAttention);
 }
 
 async function readTokenResponse(res: Response, oldRefresh: string): Promise<OAuthCredentials> {
@@ -608,7 +613,7 @@ async function refreshAwsSsoOidcToken(
     signal: kiroRefreshSignal(signal),
   });
   const res = await run(refresh);
-  if (!res.ok) throw await kiroTokenRefreshError(res);
+  if (!res.ok) throw await kiroTokenRefreshError(res, true);
   return readTokenResponse(res, refresh);
 }
 
@@ -668,11 +673,19 @@ export async function refreshKiroToken(
     const local = matchingRotatedKiroCliCredential(refresh, credential);
     if (!local) throw error;
     const retryMetadata = metadataForRotatedKiroCliCredential(credential, local);
-    const fresh = await refreshAwsSsoOidcToken(local.refresh, signal, {
-      ...credential,
-      refresh: local.refresh,
-      kiro: retryMetadata,
-    });
-    return { ...fresh, kiro: retryMetadata };
+    try {
+      const fresh = await refreshAwsSsoOidcToken(local.refresh, signal, {
+        ...credential,
+        refresh: local.refresh,
+        kiro: retryMetadata,
+      });
+      return { ...fresh, kiro: retryMetadata };
+    } catch (recoveryError) {
+      // A failed CLI fallback may use the desktop endpoint. Retain the original AWS SSO
+      // attention evidence on another input rejection; transient recovery stays retryable.
+      if (error.refreshAttention && recoveryError instanceof KiroTokenRefreshError
+        && recoveryError.httpStatus === 400 && recoveryError.oauthError === undefined) throw error;
+      throw recoveryError;
+    }
   }
 }

src/oauth/store.ts

@@ -630,6 +630,9 @@ function normalizeAccount(value: unknown): ProviderAccount | null {
   const account: ProviderAccount = { id: candidate.id, credential };
   if (typeof candidate.alias === "string" && candidate.alias.trim()) account.alias = candidate.alias.trim();
   if (candidate.needsReauth === true) account.needsReauth = true;
+  if (candidate.refreshAttentionGeneration === credentialGeneration(credential)) {
+    account.refreshAttentionGeneration = candidate.refreshAttentionGeneration;
+  }
   if (candidate.paused === true) account.paused = true;
   const threshold = parseAnthropicAccountThreshold(candidate.autoSwitchThresholdOverride);
   if (threshold !== null) account.autoSwitchThresholdOverride = threshold;
@@ -892,6 +895,7 @@ export async function saveCredentialWithReceipt(
         set.selectionRevision = previousSelectionRevision;
         delete existing.needsReauth;
         delete existing.needsReauthReason;
+        delete existing.refreshAttentionGeneration;
         accountId = existing.id;
       } else {
         const id = distinctAccountId(safe, set.accounts);
@@ -905,6 +909,7 @@ export async function saveCredentialWithReceipt(
         existing.credential = safe;
         delete existing.needsReauth;
         delete existing.needsReauthReason;
+        delete existing.refreshAttentionGeneration;
         if (existing.paused !== true) set.activeAccountId = existing.id;
         accountId = existing.id;
       } else {
@@ -917,6 +922,7 @@ export async function saveCredentialWithReceipt(
           active.credential = safe;
           delete active.needsReauth;
           delete active.needsReauthReason;
+          delete active.refreshAttentionGeneration;
           accountId = active.id;
         } else {
           const id = distinctAccountId(safe, set.accounts);
@@ -937,6 +943,7 @@ export async function saveCredentialWithReceipt(
         active.credential = safe;
         delete active.needsReauth;
         delete active.needsReauthReason;
+        delete active.refreshAttentionGeneration;
         accountId = active.id;
       } else {
         const id = distinctAccountId(safe, set.accounts);
@@ -1086,6 +1093,7 @@ export async function upsertCredentialByIdentity(
       existing.credential = safe;
       delete existing.needsReauth;
       delete existing.needsReauthReason;
+      delete existing.refreshAttentionGeneration;
       set.activeAccountId ??= existing.id;
       return "updated";
     }
@@ -1189,6 +1197,7 @@ export async function saveAccountCredential(
     if (opts.rotateLoginId) account.loginId = randomUUID();
     delete account.needsReauth;
     delete account.needsReauthReason;
+    delete account.refreshAttentionGeneration;
     // A pause that found no usable fallback leaves the active id on a paused row. Once this
     // reauthentication makes an unpaused account usable, hand the selection to it.
     const active = set.accounts.find(a => a.id === set.activeAccountId);
@@ -1403,6 +1412,7 @@ export async function replaceProviderAccountSet(
         credential: { ...account.credential, ...(account.credential.kiro ? { kiro: { ...account.credential.kiro } } : {}) },
         ...(account.alias ? { alias: account.alias } : {}),
         ...(account.needsReauth ? { needsReauth: true } : {}),
+        ...(account.refreshAttentionGeneration ? { refreshAttentionGeneration: account.refreshAttentionGeneration } : {}),
         ...(account.paused ? { paused: true } : {}),
         ...(account.autoSwitchThresholdOverride !== undefined ? { autoSwitchThresholdOverride: account.autoSwitchThresholdOverride } : {}),
         ...(account.needsReauthReason === "verify_account" ? { needsReauthReason: account.needsReauthReason } : {}),
@@ -1468,7 +1478,28 @@ export async function markAccountNeedsReauth(
   }, [provider, accountId]);
 }
 
-export async function mergeAccountCredential(provider:string,accountId:string,credential:OAuthCredentials,opts:{expectedGeneration?:string;afterPrePersistRead?:()=>void|Promise<void>;assertOwnership?: (store: AuthStore) => void}={}):Promise<{superseded:false}|{superseded:true;stored:OAuthCredentials}>{const safe=normalizeCredential(credential);if(!safe)throw new Error("Refusing to persist invalid OAuth credential");return await mutateStore(async store=>{await opts.afterPrePersistRead?.();const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account)throw new Error(`OAuth account disappeared before persist: ${provider}`);if(opts.expectedGeneration!==undefined&&credentialGeneration(account.credential)!==opts.expectedGeneration)return{superseded:true,stored:account.credential};opts.assertOwnership?.(store);account.credential=safe;if(account.needsReauthReason!=="verify_account"){delete account.needsReauth;delete account.needsReauthReason;}return{superseded:false};},[provider,accountId,safe,opts.expectedGeneration]);}
+export async function mergeAccountCredential(provider:string,accountId:string,credential:OAuthCredentials,opts:{expectedGeneration?:string;afterPrePersistRead?:()=>void|Promise<void>;assertOwnership?: (store: AuthStore) => void}={}):Promise<{superseded:false}|{superseded:true;stored:OAuthCredentials}>{const safe=normalizeCredential(credential);if(!safe)throw new Error("Refusing to persist invalid OAuth credential");return await mutateStore(async store=>{await opts.afterPrePersistRead?.();const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account)throw new Error(`OAuth account disappeared before persist: ${provider}`);if(opts.expectedGeneration!==undefined&&credentialGeneration(account.credential)!==opts.expectedGeneration)return{superseded:true,stored:account.credential};opts.assertOwnership?.(store);account.credential=safe;delete account.refreshAttentionGeneration;if(account.needsReauthReason!=="verify_account"){delete account.needsReauth;delete account.needsReauthReason;}return{superseded:false};},[provider,accountId,safe,opts.expectedGeneration]);}
 // A late refresh failure must not change an operator-paused account's health. Check under
 // the mutation lock, not before awaiting it, so a concurrent pause cannot be overwritten.
 export async function markAccountNeedsReauthIfGeneration(provider:string,accountId:string,generation:string,writerGeneration=captureConfigGeneration(),reason?:"verify_account"):Promise<boolean>{const key=oauthAccountKey(provider,accountId);if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;return await mutateStore(store=>{const account=store[provider]?.accounts.find(x=>x.id===accountId);if(!account?.credential||account.paused||credentialGeneration(account.credential)!==generation)return false;if(writerGeneration<lastReconciledGeneration&&!liveOAuthAccountKeys.has(key))return false;account.needsReauth=true;if(reason==="verify_account")account.needsReauthReason=reason;return true;},[provider,accountId,generation]);}
+
+/** Attention is projected only; refresh selection continues to use the stored terminal flag. */
+export function accountNeedsReauthForStatus(provider: string, account: ProviderAccount, now = Date.now()): boolean {
+  return account.needsReauth === true || (provider === "kiro" && account.credential.expires <= now
+    && account.refreshAttentionGeneration === credentialGeneration(account.credential));
+}
+
+/** Record refresh evidence under the same generation/config/pause fences as terminal health. */
+export async function markAccountRefreshAttentionIfGeneration(
+  provider: string, accountId: string, generation: string, writerGeneration = captureConfigGeneration(),
+): Promise<boolean> {
+  if (provider !== "kiro") return false;
+  const key = oauthAccountKey(provider, accountId);
+  return await mutateStore(store => {
+    const account = store[provider]?.accounts.find(a => a.id === accountId);
+    if (!account || account.paused || credentialGeneration(account.credential) !== generation) return false;
+    if (writerGeneration < lastReconciledGeneration && !liveOAuthAccountKeys.has(key)) return false;
+    account.refreshAttentionGeneration = generation;
+    return true;
+  }, [provider, accountId, generation]);
+}

src/oauth/types.ts

@@ -90,6 +90,8 @@ export interface ProviderAccount {
   credential: OAuthCredentials;
   /** Terminal refresh failure (invalid_grant / reused / revoked) — re-login required. */
   needsReauth?: boolean;
+  /** Kiro SSO refresh input-error evidence; status-only attention after this generation expires. */
+  refreshAttentionGeneration?: string;
   /** Operator exclusion from generic OAuth account selection until explicitly resumed. */
   paused?: boolean;
   /** Anthropic-only usage-switch override; absent inherits its pool default, zero disables it. */

structure/providers-and-adapters.md

@@ -114,6 +114,19 @@ wire type for a known field or a varint longer than ten bytes, keep last-good; a
 with nothing measurable is authoritative-empty. Only Devin's credential host extends its quota
 cache identity; generic OAuth pause still suppresses per-account probes.
 
+Kiro AWS SSO token refresh in `src/oauth/kiro.ts` retains HTTP 400 `invalid_request` as
+refresh-attention evidence separate from terminal grant errors. Matching rotated CLI credentials
+are tried before the failure reaches `src/oauth/index.ts`. `src/oauth/store.ts` persists the
+failed credential generation under its mutation lock, respecting replacement, config reconciliation,
+and operator pause. Once that generation's access token expires, account summaries project
+`needsReauth: true` and the active login projects `loggedIn: false`. `src/oauth/health.ts` uses
+the same generation/expiry predicate with its supplied observation time, so account-list health
+and CLI diagnostics project `reauth_required` with `refresh_failed`; `ocx doctor` warns with a
+login action. The internal terminal flag
+stays clear so a later refresh remains eligible; successful refresh or credential replacement
+clears the evidence. Desktop input errors, network failures, and 5xx responses create no evidence.
+No upstream description or credential metadata enters the status response.
+
 Kiro's account quota cache persists quota and an optional exhaustion verdict under one
 opaque account key and a non-secret login identity. Hydration admits only matching live
 accounts and bounds quota and verdict independently by reset and ten-minute TTL; a failed

tests/fixtures/test-layout-expected.json

@@ -629,7 +629,7 @@
   "kiro-device-social.test.ts": "providers/kiro", "kiro-fallback-error-body.test.ts": "providers/kiro",
   "kiro-images.test.ts": "providers/kiro", "kiro-leased-responses.test.ts": "providers/kiro",
   "kiro-model-catalog.test.ts": "providers/kiro", "kiro-model-preference.test.ts": "providers/kiro",
-  "kiro-oauth.test.ts": "providers/kiro", "kiro-pool-load-settings.test.ts": "providers/kiro",
+  "kiro-oauth.test.ts": "providers/kiro", "oauth-kiro-refresh-attention.test.ts": "oauth", "kiro-pool-load-settings.test.ts": "providers/kiro",
   "kiro-pool-rank.test.ts": "providers/kiro", "kiro-reasoning-roundtrip.test.ts": "providers/kiro",
   "kiro-refusal-failover.test.ts": "providers/kiro", "kiro-refusal.test.ts": "providers/kiro",
   "kiro-remote-image.test.ts": "providers/kiro", "kiro-retry.test.ts": "providers/kiro",