@bitkyc08/opencodex 2.37.0 → 2.39.0-preview.20260901

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 {

package/src/oauth/store.ts

@@ -19,7 +19,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, copyFileSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { getConfigDir, atomicWriteFile, backupInvalidConfig, hardenConfigDir, hardenExistingSecret } from "../config";
+import { getConfigDir, atomicWriteFile, backupInvalidConfig, hardenConfigDir, hardenExistingSecret, withConfigMutationLockSync } from "../config";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { MAX_PENDING_OAUTH_MUTATIONS } from "../lib/translator-budget";
@@ -67,23 +67,93 @@ export function getAuthRefreshIntentLockPath(provider: string, accountId: string
 export function getAuthRefreshIntentPath(provider: string, accountId: string): string {
   return `${getAuthRefreshIntentLockPath(provider, accountId)}.json`;
 }
-export interface OAuthRefreshIntent { version: 1; provider: string; accountId: string; generation: string; createdAt: number; flightId?: string; staleOwner?: true; uncertain?: true }
+export type OAuthRefreshIntentCleanupPending = "pre-dispatch" | "definitive-rejection";
+export interface OAuthRefreshIntent {
+  version: 1;
+  provider: string;
+  accountId: string;
+  generation: string;
+  createdAt: number;
+  attemptId?: string;
+  flightId?: string;
+  staleOwner?: true;
+  uncertain?: true;
+  cleanupPending?: OAuthRefreshIntentCleanupPending;
+}
+
+export class OAuthRefreshIntentIOError extends Error {
+  readonly code = "OAUTH_REFRESH_INTENT_IO";
+  constructor(
+    readonly operation: "write-intent" | "mark-cleanup-pending" | "clear-cleanup-pending" | "resume-cleanup",
+    cause?: unknown,
+    readonly refreshError?: unknown,
+  ) {
+    super(`OAuth refresh intent ${operation} failed`, cause ? { cause } : undefined);
+    this.name = "OAuthRefreshIntentIOError";
+  }
+}
+
+// Both compare-and-swap sites in this file — the OAuth file lock and the refresh-intent
+// file — must agree on what "the same file" means, so they share one snapshot shape and
+// one identity check (`snapshot`/`sameSnapshot` below) rather than two copies that can drift.
+type OAuthRefreshIntentFileSnapshot = LockSnapshot;
+
+export interface OAuthRefreshIntentMutationHooks {
+  beforeMarkCommit?: () => void;
+  beforeClearRecheck?: () => void;
+}
+
+class OAuthRefreshIntentChangedError extends Error {}
+
+function uncertainOAuthRefreshIntent(provider: string, accountId: string): OAuthRefreshIntent {
+  return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+}
+
 function parseOAuthRefreshIntent(
   provider: string,
   accountId: string,
   raw: string,
 ): OAuthRefreshIntent {
-  const value = JSON.parse(raw) as Partial<OAuthRefreshIntent>;
+  const parsed: unknown = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return uncertainOAuthRefreshIntent(provider, accountId);
+  }
+  const value = parsed as Partial<OAuthRefreshIntent>;
   if (
     value.version !== 1
     || value.provider !== provider
     || value.accountId !== accountId
     || typeof value.generation !== "string"
+    || !/^[0-9a-f]{64}$/.test(value.generation)
     || typeof value.createdAt !== "number"
-    || (value.flightId !== undefined && typeof value.flightId !== "string")
+    || !Number.isFinite(value.createdAt)
+    || !Number.isInteger(value.createdAt)
+    || value.createdAt < 0
+    || (
+      value.attemptId !== undefined
+      && (typeof value.attemptId !== "string" || value.attemptId.length === 0 || value.attemptId.length > 128)
+    )
+    || (
+      value.flightId !== undefined
+      && (typeof value.flightId !== "string" || value.flightId.length === 0 || value.flightId.length > 128)
+    )
     || (value.staleOwner !== undefined && value.staleOwner !== true)
+    || (value.uncertain !== undefined && value.uncertain !== true)
+    || (
+      value.cleanupPending !== undefined
+      && value.cleanupPending !== "pre-dispatch"
+      && value.cleanupPending !== "definitive-rejection"
+    )
+    || (
+      value.cleanupPending !== undefined
+      && (
+        value.attemptId === undefined
+        || value.uncertain === true
+        || value.staleOwner === true
+      )
+    )
   ) {
-    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+    return uncertainOAuthRefreshIntent(provider, accountId);
   }
   return value as OAuthRefreshIntent;
 }
@@ -96,7 +166,7 @@ export function readOAuthRefreshIntent(provider: string, accountId: string): OAu
     return parseOAuthRefreshIntent(provider, accountId, readFileSync(path, "utf8"));
   } catch (error) {
     if (errorCode(error) === "ENOENT") return undefined;
-    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+    return uncertainOAuthRefreshIntent(provider, accountId);
   }
 }
 
@@ -107,27 +177,159 @@ export function peekOAuthRefreshIntent(provider: string, accountId: string): OAu
     return parseOAuthRefreshIntent(provider, accountId, readFileSync(path, "utf8"));
   } catch (error) {
     if (errorCode(error) === "ENOENT") return undefined;
-    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+    return uncertainOAuthRefreshIntent(provider, accountId);
   }
 }
-export function writeOAuthRefreshIntent(provider: string, accountId: string, generation: string, createdAt = Date.now(), flightId?: string): void {
+export function writeOAuthRefreshIntent(provider: string, accountId: string, generation: string, createdAt = Date.now(), flightId?: string): OAuthRefreshIntent {
   const dir = getConfigDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
   hardenConfigDir();
-  const intent: OAuthRefreshIntent = { version: 1, provider, accountId, generation, createdAt, ...(flightId ? { flightId } : {}) };
-  atomicWriteFile(getAuthRefreshIntentPath(provider, accountId), `${JSON.stringify(intent)}\n`);
+  const intent: OAuthRefreshIntent = {
+    version: 1,
+    provider,
+    accountId,
+    generation,
+    createdAt,
+    attemptId: randomUUID(),
+    ...(flightId ? { flightId } : {}),
+  };
+  return withConfigMutationLockSync(() => {
+    if (readOAuthRefreshIntent(provider, accountId) !== undefined) {
+      throw new OAuthRefreshIntentIOError(
+        "write-intent",
+        new Error("An OAuth refresh intent already exists; refusing to overwrite its replay guard"),
+      );
+    }
+    atomicWriteFile(getAuthRefreshIntentPath(provider, accountId), `${JSON.stringify(intent)}\n`);
+    return intent;
+  });
+}
+
+function sameOAuthRefreshIntentAttempt(current: OAuthRefreshIntent, expected: OAuthRefreshIntent): boolean {
+  return current.provider === expected.provider
+    && current.accountId === expected.accountId
+    && current.generation === expected.generation
+    && current.createdAt === expected.createdAt
+    && current.attemptId === expected.attemptId
+    && current.flightId === expected.flightId;
+}
+
+function exactOAuthRefreshIntentFile(
+  provider: string,
+  accountId: string,
+): { intent: OAuthRefreshIntent; snapshot: OAuthRefreshIntentFileSnapshot } | undefined {
+  const path = getAuthRefreshIntentPath(provider, accountId);
+  try {
+    hardenConfigDir();
+    hardenExistingSecret(path);
+    const file = snapshot(path);
+    let intent: OAuthRefreshIntent;
+    try { intent = parseOAuthRefreshIntent(provider, accountId, file.bytes); }
+    catch { intent = uncertainOAuthRefreshIntent(provider, accountId); }
+    return { intent, snapshot: file };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export function markOAuthRefreshIntentCleanupPending(
+  provider: string,
+  accountId: string,
+  expected: OAuthRefreshIntent,
+  cleanupPending: OAuthRefreshIntentCleanupPending,
+  hooks: OAuthRefreshIntentMutationHooks = {},
+): OAuthRefreshIntent | undefined {
+  return withConfigMutationLockSync(() => {
+    const path = getAuthRefreshIntentPath(provider, accountId);
+    const observed = exactOAuthRefreshIntentFile(provider, accountId);
+    const current = observed?.intent;
+    if (
+      !observed
+      || !current
+      || expected.attemptId === undefined
+      || current.uncertain
+      || current.staleOwner
+      || !sameOAuthRefreshIntentAttempt(current, expected)
+      || (current.cleanupPending !== undefined && current.cleanupPending !== cleanupPending)
+    ) return undefined;
+    const marked: OAuthRefreshIntent = { ...current, cleanupPending };
+    try {
+      atomicWriteFile(path, `${JSON.stringify(marked)}\n`, undefined, {
+        beforeRename: hooks.beforeMarkCommit,
+        validateBeforeRename: targetPath => {
+          let latest: OAuthRefreshIntentFileSnapshot;
+          try { latest = snapshot(targetPath); }
+          catch (error) {
+            throw new OAuthRefreshIntentChangedError("OAuth refresh intent changed before marker commit", { cause: error });
+          }
+          if (!sameSnapshot(observed.snapshot, latest)) {
+            throw new OAuthRefreshIntentChangedError("OAuth refresh intent changed before marker commit");
+          }
+        },
+      });
+    } catch (error) {
+      if (error instanceof OAuthRefreshIntentChangedError) return undefined;
+      throw error;
+    }
+    return marked;
+  });
 }
+
+export function clearOAuthRefreshIntentIfMatch(
+  provider: string,
+  accountId: string,
+  expected: OAuthRefreshIntent,
+  hooks: OAuthRefreshIntentMutationHooks = {},
+): boolean {
+  return withConfigMutationLockSync(() => {
+    const path = getAuthRefreshIntentPath(provider, accountId);
+    const observed = exactOAuthRefreshIntentFile(provider, accountId);
+    if (!observed) return true;
+    const current = observed.intent;
+    if (
+      current.uncertain
+      || expected.uncertain
+      || current.attemptId === undefined
+      || expected.attemptId === undefined
+      || current.uncertain !== expected.uncertain
+      || current.staleOwner !== expected.staleOwner
+      || current.cleanupPending !== expected.cleanupPending
+      || !sameOAuthRefreshIntentAttempt(current, expected)
+    ) return false;
+    hooks.beforeClearRecheck?.();
+    let latest: OAuthRefreshIntentFileSnapshot;
+    try { latest = snapshot(path); }
+    catch (error) {
+      if (errorCode(error) === "ENOENT") return true;
+      throw error;
+    }
+    if (!sameSnapshot(observed.snapshot, latest)) return false;
+    try { unlinkSync(path); return true; }
+    catch (error) { if (errorCode(error) === "ENOENT") return true; throw error; }
+  });
+}
+
 export function markOAuthRefreshIntentStaleOwner(provider: string, accountId: string, generation: string, flightId: string): boolean {
-  const current = readOAuthRefreshIntent(provider, accountId);
-  if (current?.uncertain || current?.generation !== generation || current.flightId !== flightId) return false;
-  atomicWriteFile(getAuthRefreshIntentPath(provider, accountId), `${JSON.stringify({ ...current, staleOwner: true })}\n`);
-  return true;
+  return withConfigMutationLockSync(() => {
+    const current = readOAuthRefreshIntent(provider, accountId);
+    if (
+      current?.uncertain
+      || current?.cleanupPending
+      || current?.generation !== generation
+      || current.flightId !== flightId
+    ) return false;
+    atomicWriteFile(getAuthRefreshIntentPath(provider, accountId), `${JSON.stringify({ ...current, staleOwner: true })}\n`);
+    return true;
+  });
 }
 export function clearOAuthRefreshIntent(provider: string, accountId: string, generation: string): boolean {
-  const current = readOAuthRefreshIntent(provider, accountId);
-  if (!current || current.generation !== generation) return false;
-  try { unlinkSync(getAuthRefreshIntentPath(provider, accountId)); return true; }
-  catch (error) { if (errorCode(error) === "ENOENT") return false; throw error; }
+  return withConfigMutationLockSync(() => {
+    const current = readOAuthRefreshIntent(provider, accountId);
+    if (!current || current.generation !== generation) return false;
+    try { unlinkSync(getAuthRefreshIntentPath(provider, accountId)); return true; }
+    catch (error) { if (errorCode(error) === "ENOENT") return false; throw error; }
+  });
 }
 export function credentialGeneration(cred: OAuthCredentials): string {
   return createHash("sha256").update(JSON.stringify([cred.refresh, cred.access, cred.expires])).digest("hex");