@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/integrations/writer.ts

@@ -263,7 +263,24 @@ function preflight(input: IntegrationWriteInput) {
   return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
 }
 
-function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: boolean): WriteOutcome {
+/**
+ * How a conflicted document is treated.
+ *
+ * `refuse` is the default and the only behavior that existed: a conflict means
+ * something we did not write occupies our paths, or our own block was edited,
+ * and guessing which one the user meant to keep is how a toggle deletes work.
+ *
+ * `overwrite` is the explicit escape hatch. It is never reached by a plain
+ * apply -- the caller has to ask for it by name -- because the whole value of
+ * the refusal is that it cannot be triggered by accident.
+ */
+type ConflictPolicy = "refuse" | "overwrite";
+
+function applyOrRefreshIntegration(
+  input: IntegrationWriteInput,
+  allowAbsent: boolean,
+  conflictPolicy: ConflictPolicy = "refuse",
+): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
   const { store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
@@ -278,10 +295,20 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }
   if (classified.state === "conflict") {
-    return refuse(clientId, "conflict", "conflict",
-      classified.reason === "foreign-edit"
-        ? `${configPath} changed after opencodex wrote it`
-        : `${configPath} already contains an opencodex block we did not write`);
+    if (conflictPolicy === "refuse") {
+      return refuse(clientId, "conflict", "conflict",
+        classified.reason === "foreign-edit"
+          ? `${configPath} changed after opencodex wrote it`
+          : `${configPath} already contains an opencodex block we did not write`);
+    }
+    /*
+     * The caller asked for the overwrite explicitly, so the merge below runs
+     * against the document as it stands and our block replaces whatever holds
+     * our paths. Everything that makes it recoverable is shared with apply --
+     * the snapshot, the atomic write, the compare-before-commit recheck and the
+     * journal row all come from the same commit() call -- which is why this is a
+     * policy flag on one code path rather than a second implementation.
+     */
   }
   /*
    * `unsafe` from the classifier means the document is not one we may write
@@ -327,7 +354,22 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
    */
   const base = classified.state === "stale" && record
     ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
-    : parsed;
+    : classified.state === "conflict" && record
+      /*
+       * A forced overwrite of a `foreign-edit` conflict drops what the previous
+       * record owned for the same reason a stale refresh does: the replacement
+       * record covers the paths we are about to write, so a path the old record
+       * owned and the new one does not would be stranded forever, unremovable by
+       * any later disable.
+       *
+       * With NO record -- an `unowned-key` conflict -- there is nothing to drop and
+       * the merge runs against the user's document directly. That is correct:
+       * createdContainerPaths then attributes every container they already had to
+       * them, so a later disable removes our leaves and leaves their structure
+       * standing.
+       */
+      ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
+      : parsed;
   // Computed against the document as it stands BEFORE the merge: afterwards
   // every container exists and "did we create this?" is unanswerable.
   const created = createdContainerPaths(base, contribution);
@@ -375,7 +417,16 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
   const snapshot = store.captureSnapshot(clientId, opId, before);
   const at = new Date(io.now()).toISOString();
   const entry: JournalEntry = {
-    opId, clientId, kind: classified.state === "stale" ? "refresh" : "apply", at, configPath,
+    /*
+     * `overwrite` is its own kind rather than reusing `apply`. The rollback list
+     * is the one place a user goes after a mistake, and "applied" is a lie about
+     * an operation that replaced a block somebody else wrote.
+     */
+    opId, clientId,
+    kind: classified.state === "conflict"
+      ? "overwrite"
+      : classified.state === "stale" ? "refresh" : "apply",
+    at, configPath,
     snapshot, resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
   };
   const refreshablePaths = refreshablePathsOf(contribution);
@@ -406,6 +457,23 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   return applyOrRefreshIntegration(input, true);
 }
 
+/**
+ * Apply over a conflicted config, replacing whatever holds our paths.
+ *
+ * Separate from `applyIntegration` and never a flag on it: a caller has to name
+ * this function to get the behavior, so no existing call site can acquire it by
+ * passing a default through.
+ *
+ * What it does NOT relax. `unsafe` still refuses -- a blocked container means the
+ * merge would replace a value it cannot reason about, and a snapshot is not a
+ * licence for that. `not_installed` and `non_loopback` still refuse; neither is a
+ * conflict. And a non-conflict state behaves exactly as apply does, so calling
+ * this on a clean file is not a way to skip any other check.
+ */
+export function overwriteIntegration(input: IntegrationWriteInput): WriteOutcome {
+  return applyOrRefreshIntegration(input, true, "overwrite");
+}
+
 /** Refresh an owned stale block, but never create or reconnect an absent one. */
 export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
   return applyOrRefreshIntegration(input, false);
@@ -698,6 +766,13 @@ export function refreshIntegrationCoordinated(
   return coordinatedWrite(input, refreshIntegration, options);
 }
 
+export function overwriteIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, overwriteIntegration, options);
+}
+
 export function disableIntegrationCoordinated(
   input: IntegrationWriteInput,
   options?: CoordinatedIntegrationOptions,

package/src/lib/process-control.ts

@@ -29,6 +29,24 @@ export interface GracefulStopIo {
   waitExit?: (pid: number, timeoutMs: number) => boolean;
   env?: Record<string, string | undefined>;
   exitTimeoutMs?: number;
+  /**
+   * Nonce of the pending-teardown receipt this caller claimed.
+   *
+   * `ocx stop` sets it because it restores shared client config itself, only after
+   * proving a stopped Task Scheduler did not respawn the proxy (#3008). The nonce is what
+   * makes the deferral an owned obligation rather than a flag anyone can set: the proxy
+   * honours it only when it names the receipt actually on disk. Direct callers omit it
+   * and keep the self-contained behaviour.
+   */
+  deferSharedTeardownNonce?: string;
+  /**
+   * Endpoint the caller already resolved for this pid.
+   *
+   * `ocx stop` records this same snapshot in its pending-teardown receipt. Re-reading the
+   * runtime file here could pick up a different one, which would make the receipt name an
+   * endpoint the stop never contacted — and recovery probes exactly that endpoint.
+   */
+  runtimeEndpoint?: { hostname: string; port: number };
 }
 
 /**
@@ -67,7 +85,7 @@ export class ProxyOwnershipRefusedError extends Error {}
  */
 export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
   const readRuntime = io.readRuntime ?? readRuntimePort;
-  const runtime = readRuntime(pid);
+  const runtime = io.runtimeEndpoint ?? readRuntime(pid);
   if (!runtime?.port) return false;
   const env = io.env ?? process.env;
   const headers: Record<string, string> = {};
@@ -75,7 +93,14 @@ export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}):
   if (token) headers["x-opencodex-api-key"] = token;
   const fetchFn = io.fetchFn ?? fetch;
   try {
-    const res = await fetchFn(`http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`, {
+    // `ocx stop` asks the proxy NOT to restore shared client config: it does that itself,
+    // after verifying a stopped Task Scheduler did not respawn the proxy (#3008). Letting
+    // the child do it means a survivor found seconds later has already lost its config.
+    const stopUrl = `http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`
+      + (io.deferSharedTeardownNonce
+        ? `?deferSharedTeardown=1&teardownNonce=${encodeURIComponent(io.deferSharedTeardownNonce)}`
+        : "");
+    const res = await fetchFn(stopUrl, {
       method: "POST",
       headers,
       // Hung proxies with many CLOSE_WAIT clients can be slow to accept; give them
@@ -107,10 +132,10 @@ function drainDeadlineMs(): number {
 }
 
 /** Graceful-first stop: management-API drain, then the platform kill ladder. */
-export async function stopProxy(pid: number): Promise<void> {
+export async function stopProxy(pid: number, io: GracefulStopIo = {}): Promise<void> {
   if (!isProcessAlive(pid)) return;
-  const runtime = readRuntimePort(pid);
-  const graceful = await stopProxyGracefully(pid);
+  const runtime = io.runtimeEndpoint ?? readRuntimePort(pid);
+  const graceful = await stopProxyGracefully(pid, io);
   if (graceful === "refused") {
     // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
     // config while that service keeps the proxy alive.

package/src/lib/state-store-registrations.ts

@@ -9,6 +9,7 @@ import { reconcileProviderFetchWarnings } from "../codex/catalog/provider-fetch"
 import { reconcileModelCacheGeneration } from "../codex/model-cache";
 import { reconcilePoolRotationState } from "../codex/pool-rotation";
 import { reconcileCodexQuotaAccounts } from "../codex/quota";
+import { reconcileQuotaRecovery, sweepExpiredQuotaRecovery } from "../codex/quota-401-recovery";
 import {
   listLiveCodexAccountIds,
   reconcileCodexRoutingHealth,
@@ -84,6 +85,13 @@ export const STATE_STORE_REGISTRATIONS = [
   },
   { name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
   { name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
+  {
+    name: "codex-quota-401-recovery",
+    // Only backoff windows and abandoned leases expire. A spent fence is durable: expiring
+    // it would grant the same credential lineage a second refresh (#3019).
+    sweepExpired: sweepExpiredQuotaRecovery,
+    reconcileGeneration: context => reconcileQuotaRecovery(context.codexAccountIds),
+  },
   {
     name: "responses-continuation",
     sweepExpired: sweepExpiredResponseStates,

package/src/oauth/index.ts

@@ -1,10 +1,34 @@
 import type { KiroOAuthMetadata, OAuthController, OAuthCredentials } from "./types";
 import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
-import { loadConfig, resolveEnvValue, saveConfig } from "../config";
+import { ConfigMutationLockError, loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../lib/privacy";
 import { KiroTokenRefreshError, environmentKiroRoutingMetadata, loginKiro, refreshKiroToken, settleKiroLoginTransaction } from "./kiro";
-import { getAccountCredential, getAccountCredentialWithStatus, getAccountSet, removeAccount, saveAccountCredential, saveCredential, setActiveAccount, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration, readOAuthRefreshIntent, writeOAuthRefreshIntent, markOAuthRefreshIntentStaleOwner, clearOAuthRefreshIntent, normalizeAuthStoreBuffer, OAuthMutationBusyError } from "./store";
+import {
+  OAuthMutationBusyError,
+  OAuthRefreshIntentIOError,
+  clearOAuthRefreshIntent,
+  clearOAuthRefreshIntentIfMatch,
+  createOAuthRefreshIntentLock,
+  credentialGeneration,
+  getAccountCredential,
+  getAccountCredentialWithStatus,
+  getAccountSet,
+  getCredential,
+  markAccountNeedsReauthIfGeneration,
+  markOAuthRefreshIntentCleanupPending,
+  markOAuthRefreshIntentStaleOwner,
+  mergeAccountCredential,
+  normalizeAuthStoreBuffer,
+  readOAuthRefreshIntent,
+  removeAccount,
+  saveAccountCredential,
+  saveCredential,
+  setActiveAccount,
+  writeOAuthRefreshIntent,
+  type OAuthRefreshIntent,
+  type OAuthRefreshIntentCleanupPending,
+} from "./store";
 import { loginXai, refreshXaiToken, XAI_LOCAL_CLI_DETACH_WARNING, XaiTokenRequestError } from "./xai";
 import { ANTHROPIC_OAUTH_BETA, AnthropicTokenError, loginAnthropic, refreshAnthropicToken } from "./anthropic";
 import { loginKimi, refreshKimiToken } from "./kimi";
@@ -559,9 +583,152 @@ function terminal(error:unknown):boolean{
   // Local durable-write/read/cleanup failures are operational, not credential
   // death: the provider credential was never rejected or consumed. Never mark
   // the account needsReauth for broken local persistence infrastructure.
-  if (error instanceof RefreshIntentIOError) return false;
+  if (error instanceof RefreshIntentIOError || error instanceof OAuthRefreshIntentIOError) return false;
   return isTerminalRefreshError(error);
 }
+
+/**
+ * True when the token endpoint definitively answered and rejected the request.
+ *
+ * The Anthropic adapter attaches an HTTP status only to an explicit non-success response,
+ * which is the retryable rejection this PR handles. Everything else (timeout, dropped
+ * connection, a body that could not be read or parsed, or a local persistence fault) leaves
+ * the outcome unknown: the server may already have rotated the token, and a blind replay
+ * could trip refresh-token-reuse revocation. Those cases must keep the refresh intent.
+ *
+ * Deliberately narrower than `terminal()`, which asks whether the CREDENTIAL is dead.
+ * This asks the different question of whether the ATTEMPT is known to have failed.
+ */
+function definitivelyAnswered(error: unknown): boolean {
+  if (error instanceof AnthropicTokenError) return error.httpStatus !== undefined;
+  return false;
+}
+
+/**
+ * Intent cleanup is secondary to the refresh outcome it protects.
+ *
+ * Once a credential is already durable, cleanup remains secondary and best-effort. A known
+ * failed attempt takes the stricter path below: its retry-safe marker must become durable before
+ * the original provider error can be returned.
+ */
+function clearAnthropicRefreshIntentBestEffort(
+  provider: string,
+  accountId: string,
+  expected: OAuthRefreshIntent,
+): boolean {
+  try {
+    return expected.attemptId
+      ? clearOAuthRefreshIntentIfMatch(provider, accountId, expected)
+      : clearOAuthRefreshIntent(provider, accountId, expected.generation);
+  } catch {
+    console.warn(
+      "[opencodex] Anthropic refresh intent cleanup failed; preserving the durable replay guard.",
+    );
+    return false;
+  }
+}
+
+const ANTHROPIC_INTENT_MARK_RETRY_DELAYS_MS = [10, 25, 50] as const;
+
+function isConfigMutationLockContention(error: unknown): boolean {
+  if (!(error instanceof ConfigMutationLockError)) return false;
+  const cause = error.cause;
+  const code = cause && typeof cause === "object" && "code" in cause
+    ? String((cause as { code?: unknown }).code)
+    : "";
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED";
+}
+
+async function clearAnthropicRefreshIntentForKnownFailure(
+  provider: string,
+  accountId: string,
+  expected: OAuthRefreshIntent,
+  cleanupPending: OAuthRefreshIntentCleanupPending,
+  refreshError: unknown,
+): Promise<boolean> {
+  let marked: OAuthRefreshIntent | undefined;
+  for (let attempt = 0; attempt <= ANTHROPIC_INTENT_MARK_RETRY_DELAYS_MS.length; attempt += 1) {
+    try {
+      marked = markOAuthRefreshIntentCleanupPending(
+        provider,
+        accountId,
+        expected,
+        cleanupPending,
+      );
+      break;
+    } catch (cause) {
+      const retryDelay = ANTHROPIC_INTENT_MARK_RETRY_DELAYS_MS[attempt];
+      if (!isConfigMutationLockContention(cause) || retryDelay === undefined) {
+        throw new OAuthRefreshIntentIOError(
+          "mark-cleanup-pending",
+          cause,
+          refreshError,
+        );
+      }
+      // The provider has definitively answered, so caller cancellation no longer changes the
+      // settlement obligation. Yield briefly while retaining the per-account refresh lock, then
+      // rerun the existing compare-and-swap marker against current disk state.
+      await Bun.sleep(retryDelay);
+    }
+  }
+  if (!marked) {
+    throw new OAuthRefreshIntentIOError(
+      "mark-cleanup-pending",
+      new Error("Anthropic refresh intent changed before safe cleanup"),
+      refreshError,
+    );
+  }
+
+  let cleared: boolean;
+  try {
+    cleared = clearOAuthRefreshIntentIfMatch(provider, accountId, marked);
+  } catch {
+    console.warn(
+      "[opencodex] Anthropic refresh intent cleanup failed; retry-safe cleanup remains pending.",
+    );
+    return false;
+  }
+  if (!cleared) {
+    throw new OAuthRefreshIntentIOError(
+      "clear-cleanup-pending",
+      new Error("Anthropic refresh intent changed during safe cleanup"),
+      refreshError,
+    );
+  }
+  return true;
+}
+
+function resumeAnthropicRefreshIntentCleanup(
+  provider: string,
+  accountId: string,
+  pendingIntent: OAuthRefreshIntent,
+): void {
+  let cleared: boolean;
+  try {
+    cleared = clearOAuthRefreshIntentIfMatch(provider, accountId, pendingIntent);
+  } catch (cause) {
+    throw new OAuthRefreshIntentIOError(
+      "resume-cleanup",
+      cause,
+    );
+  }
+  if (!cleared) {
+    throw new OAuthRefreshIntentIOError(
+      "resume-cleanup",
+      new Error("Pending Anthropic refresh intent changed before cleanup"),
+    );
+  }
+}
+
+function clearObservedAnthropicRefreshIntent(
+  provider: string,
+  accountId: string,
+  pendingIntent: OAuthRefreshIntent,
+): boolean {
+  return pendingIntent.attemptId
+    ? clearOAuthRefreshIntentIfMatch(provider, accountId, pendingIntent)
+    : clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+}
 function authoritative(stored:OAuthCredentials,active:boolean,now:()=>number):OAuthCredentials{if(stored.source!=="local-cli")return stored;const disk=detectGrokCliToken();if(!disk)return stored;const allowed=isSameGrokIdentity(stored,disk)||(active&&!hasComparableGrokIdentity(stored,disk));return allowed&&shouldAdoptGrokGeneration(stored,disk,now(),REFRESH_SKEW_MS)?disk:stored;}
 function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCredentials {
   return {
@@ -647,13 +814,19 @@ export async function refreshAnthropicAccountWithLock(
         afterPrePersistRead: deps.afterPrePersistRead,
       });
       if (outcome.superseded) {
-        if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+        // The disk credential is already durable here, so cleanup is secondary: an unlink
+        // failure must not mask a committed credential by throwing over the return below.
+        if (pendingIntent) clearAnthropicRefreshIntentBestEffort(provider, accountId, pendingIntent);
         if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
         throw new OAuthLoginRequiredError(provider);
       }
-      if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+      if (pendingIntent) clearAnthropicRefreshIntentBestEffort(provider, accountId, pendingIntent);
       return disk.access;
     }
+    if (pendingIntent?.cleanupPending && pendingIntent.generation === generation) {
+      resumeAnthropicRefreshIntentCleanup(provider, accountId, pendingIntent);
+      pendingIntent = undefined;
+    }
     if (!pendingIntent?.uncertain && pendingIntent?.generation === generation) {
       if (pendingIntent.staleOwner) throw new OAuthTokenRefreshStaleError();
       if (deps.replacedStaleFlight && pendingIntent.flightId === deps.replacedStaleFlight.flightId) {
@@ -661,7 +834,9 @@ export async function refreshAnthropicAccountWithLock(
           markOAuthRefreshIntentStaleOwner(provider, accountId, generation, deps.replacedStaleFlight.flightId);
           throw new OAuthTokenRefreshStaleError();
         }
-        clearOAuthRefreshIntent(provider, accountId, generation);
+        if (!clearObservedAnthropicRefreshIntent(provider, accountId, pendingIntent)) {
+          throw new OAuthTokenRefreshStaleError();
+        }
         pendingIntent = undefined;
       }
     }
@@ -669,7 +844,9 @@ export async function refreshAnthropicAccountWithLock(
       await markAccountNeedsReauthIfGeneration(provider, accountId, generation, writerGeneration);
       throw new OAuthLoginRequiredError(provider);
     }
-    if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+    if (pendingIntent && !clearObservedAnthropicRefreshIntent(provider, accountId, pendingIntent)) {
+      throw new OAuthTokenRefreshStaleError();
+    }
     if (account?.needsReauth) {
       throw new OAuthLoginRequiredError(provider);
     }
@@ -677,9 +854,15 @@ export async function refreshAnthropicAccountWithLock(
       return stored.access;
     }
 
+    let refreshMayHaveReachedProvider = false;
+    let attemptIntent: OAuthRefreshIntent | undefined;
     try {
-      writeOAuthRefreshIntent(provider, accountId, generation, now(), deps.flight?.flightId);
+      attemptIntent = writeOAuthRefreshIntent(provider, accountId, generation, now(), deps.flight?.flightId);
       if (deps.signal?.aborted) throw deps.signal.reason;
+      // From this point on, even a synchronous client error is conservatively post-dispatch:
+      // the provider may have received and rotated the refresh token before the caller learned
+      // the outcome.
+      refreshMayHaveReachedProvider = true;
       if (deps.flight) deps.flight.dispatched = true;
       const fresh = merged(await def.refresh(stored.refresh, deps.signal), stored);
       const outcome = await mergeAccountCredential(provider, accountId, fresh, {
@@ -687,17 +870,41 @@ export async function refreshAnthropicAccountWithLock(
         afterPrePersistRead: deps.afterPrePersistRead,
       });
       if (outcome.superseded) {
-        clearOAuthRefreshIntent(provider, accountId, generation);
+        if (attemptIntent) clearAnthropicRefreshIntentBestEffort(provider, accountId, attemptIntent);
         if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
         throw new OAuthLoginRequiredError(provider);
       }
-      clearOAuthRefreshIntent(provider, accountId, generation);
+      // The rotated credential is durable now. A cleanup failure must not turn that committed
+      // success into a refresh failure; the old-generation intent remains a conservative guard.
+      if (attemptIntent) clearAnthropicRefreshIntentBestEffort(provider, accountId, attemptIntent);
       return fresh.access;
     } catch (error) {
-      if (error instanceof OAuthMutationBusyError) throw error;
-      if (!terminal(error)) throw error;
+      if (error instanceof OAuthMutationBusyError || error instanceof OAuthTokenRefreshStaleError) throw error;
+      if (!terminal(error)) {
+        // A non-terminal failure tells the caller to retry, but the intent outlived it, so
+        // the next attempt hit the pending-intent branch above and raised
+        // OAuthLoginRequiredError. One 503 locked the account out of refresh until manual
+        // re-auth even after upstream recovered.
+        //
+        // Only clear the intent when the server DEFINITIVELY answered and rejected the
+        // request. The adapter attaches an HTTP status only to that explicit non-success
+        // response. A timeout, a dropped connection, or an unreadable/unparseable body
+        // carries no status: the server may already have
+        // rotated the token, and replaying it could trip refresh-token-reuse revocation.
+        // Those outcomes keep the intent so the guard still refuses a blind replay.
+        if ((!refreshMayHaveReachedProvider || definitivelyAnswered(error)) && attemptIntent) {
+          await clearAnthropicRefreshIntentForKnownFailure(
+            provider,
+            accountId,
+            attemptIntent,
+            refreshMayHaveReachedProvider ? "definitive-rejection" : "pre-dispatch",
+            error,
+          );
+        }
+        throw error;
+      }
       await markAccountNeedsReauthIfGeneration(provider, accountId, generation, writerGeneration);
-      clearOAuthRefreshIntent(provider, accountId, generation);
+      if (attemptIntent) clearAnthropicRefreshIntentBestEffort(provider, accountId, attemptIntent);
       throw new OAuthLoginRequiredError(provider);
     }
   } finally {