@bitkyc08/opencodex 2.88.0 → 2.89.0

package/src/oauth/account-auto-pause.ts

@@ -0,0 +1,171 @@
+import { captureAccountAutoPauseFence, accountAutoPauseFenceIsLocal, accountAutoPauseFenceMatchesDisk } from "../config/account-auto-pause-revisions";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { OAuthAccessSnapshot } from "./index";
+import type { CodexAuthContext } from "../codex/auth-context";
+import type { AccountPauseReason } from "../types/account-auto-pause";
+import { credentialGeneration, getAccountSet, setAccountPaused } from "./store";
+import { mutatePersistedConfig } from "../config";
+import { isCodexAccountGenerationLive, readCodexAccountRecord } from "../codex/account-store";
+import { captureMainQuotaDispatch, isMainQuotaDispatchLive } from "../codex/main-account-cache";
+import { isCodexAccountPaused, setCodexAccountPaused } from "../codex/account-pause";
+import { apiKeyPoolEntryId } from "../providers/api-keys";
+import { resolveProviderApiKey } from "../providers/api-key-resolve";
+import { createHash } from "node:crypto";
+import { setProviderApiKeyPaused } from "../providers/api-key-pause";
+import { AccountRefusalStreaks, autoPauseThreshold, permanentAccountRefusal } from "./account-auto-pause-policy";
+import { clearThreadAccountMapForAccount, reconcileCodexActiveAfterExclusion } from "../codex/routing";
+import { isNonReplayableResponse } from "../lib/upstream-retry";
+import { hasUpstreamRewriters, upstreamRewriterEpoch } from "../plugins/upstream-hooks";
+
+const streaks = new WeakMap<OcxConfig, AccountRefusalStreaks>();
+export { wasAccountAutoPaused, wasPermanentAccountRefusal } from "../lib/account-auto-pause-response";
+import { markAccountAutoPaused, markPermanentAccountRefusal } from "../lib/account-auto-pause-response";
+export interface AccountAutoPauseBinding {
+  config: OcxConfig;
+  oauth?: OAuthAccessSnapshot;
+  codex?: CodexAuthContext;
+}
+
+/** Capture before transport. A later response cannot acquire authority over a newer login/resume. */
+export type AccountAutoPauseObserver = ((response: Response) => Promise<Response>) & {
+  /** Final-send report: only a response whose wire credential and destination match is counted. */
+  physical: (sameDestination: boolean, headers: Headers) => void;
+};
+const CREDENTIAL_HEADERS = ["authorization", "x-api-key", "x-goog-api-key", "api-key"] as const;
+const CODEX_SELECTOR_HEADERS = ["openai-organization", "openai-project"] as const;
+// Nested capture sites (a providerFetch observer around a dispatchOverride's own observer) see the
+// same physical response. It counts once per account, and a response whose final send was reported
+// to any observer is never attributed by an observer that received no report.
+const countedResponses = new WeakMap<Response, Set<string>>();
+const reportedResponses = new WeakSet<Response>();
+export function captureAccountAutoPauseAttempt(name: string, provider: OcxProviderConfig, binding?: AccountAutoPauseBinding, headers?: Headers):
+  AccountAutoPauseObserver | undefined {
+  if (!binding) return;
+  const { config, oauth, codex } = binding;
+  const threshold = autoPauseThreshold(config.providers[name]?.accountAutoPause);
+  if (!threshold) return;
+  const configured = config.providers[name];
+  if (!configured || configured.disabled) return;
+  const fence = captureAccountAutoPauseFence(config, name);
+  if (!fence) return;
+  const route = JSON.stringify([configured.baseUrl, configured.adapter, configured.authMode]);
+  const policyCurrent = () => accountAutoPauseFenceIsLocal(name, fence) && !config.providers[name]?.disabled
+    && autoPauseThreshold(config.providers[name]?.accountAutoPause) === threshold
+    && JSON.stringify([config.providers[name]?.baseUrl, config.providers[name]?.adapter, config.providers[name]?.authMode]) === route;
+  let key: string, incarnation: string, current: () => boolean, owns: (wire: Headers) => boolean;
+  let pause: (reason: AccountPauseReason) => Promise<boolean>;
+  if (provider.authMode === "oauth") {
+    if (!oauth || oauth.provider !== name || headers?.get("authorization") !== `Bearer ${oauth.accessToken}` || headers.has("x-api-key")) return;
+    const row = getAccountSet(name)?.accounts.find(a => a.id === oauth.accountId);
+    if (!row || row.paused || credentialGeneration(row.credential) !== oauth.generation) return;
+    const revision = row.pauseRevision;
+    owns = wire => wire.get("authorization") === `Bearer ${oauth.accessToken}` && !wire.has("x-api-key");
+    key = `${name}\0oauth\0${oauth.accountId}`;
+    incarnation = `${row.loginId ?? row.addedAt ?? oauth.accountId}\0${revision ?? ""}`;
+    current = () => {
+      const live = getAccountSet(name)?.accounts.find(a => a.id === oauth.accountId);
+      return !!live && !live.paused && live.pauseRevision === revision && credentialGeneration(live.credential) === oauth.generation;
+    };
+    pause = async reason => (await setAccountPaused(name, oauth.accountId, true, {
+      generation: oauth.generation, pauseRevision: revision, isCurrent: policyCurrent,
+      assertPolicyBeforePersist: () => { if (!accountAutoPauseFenceMatchesDisk(name, fence)) throw new Error("Account auto-pause policy changed before persistence"); }, details: { reason, pausedAt: Date.now() },
+    })).status === "updated";
+  } else if (provider.authMode === "forward") {
+    if (!codex || codex.kind !== "pool" && codex.kind !== "main-pool") return;
+    const { accountId } = codex;
+    // The bearer and the workspace together name the Codex account; organization/project selectors
+    // must stay as captured, so a rewrite that keeps the bearer cannot redirect the refusal.
+    const selectors = CODEX_SELECTOR_HEADERS.map(header => headers?.get(header) ?? null);
+    const codexOwns = (wire: Headers) => wire.get("authorization") === `Bearer ${codex.accessToken}`
+      && wire.get("chatgpt-account-id") === codex.chatgptAccountId
+      && CODEX_SELECTOR_HEADERS.every((header, index) => wire.get(header) === selectors[index]);
+    if (!headers || !codexOwns(headers)) return;
+    owns = codexOwns;
+    const revision = config.codexAccountPauseState?.[accountId]?.revision;
+    const mainDispatch = codex.kind === "main-pool" ? captureMainQuotaDispatch(codex.accessToken, codex.chatgptAccountId, codex.writerGeneration) : undefined;
+    const credentialCurrent = () => codex.kind === "pool"
+      ? isCodexAccountGenerationLive(accountId, codex.generation)
+      : !!mainDispatch && isMainQuotaDispatchLive(mainDispatch);
+    key = `${name}\0codex\0${accountId}`;
+    incarnation = `${codex.kind === "pool" ? readCodexAccountRecord(accountId)?.quotaHistoryIdentity ?? codex.generation : mainDispatch?.credentialGeneration}\0${revision ?? ""}`;
+    current = () => !isCodexAccountPaused(config, accountId)
+      && config.codexAccountPauseState?.[accountId]?.revision === revision && credentialCurrent();
+    pause = async reason => {
+      let pauseState: OcxConfig["codexAccountPauseState"];
+      const outcome = mutatePersistedConfig(fresh => {
+        if (!policyCurrent() || !accountAutoPauseFenceMatchesDisk(name, fence, fresh) || !credentialCurrent() || isCodexAccountPaused(fresh, accountId)
+          || fresh.codexAccountPauseState?.[accountId]?.revision !== revision
+          || autoPauseThreshold(fresh.providers[name]?.accountAutoPause) !== threshold) return { changed: false, value: false };
+        setCodexAccountPaused(fresh, accountId, true, { reason, pausedAt: Date.now() });
+        pauseState = structuredClone(fresh.codexAccountPauseState);
+        return { changed: true, value: true };
+      });
+      if (outcome.status !== "committed" || !outcome.value) return false;
+      config.pausedCodexAccountIds = [...new Set([...(config.pausedCodexAccountIds ?? []), accountId])];
+      config.codexAccountPauseState = pauseState;
+      clearThreadAccountMapForAccount(accountId);
+      reconcileCodexActiveAfterExclusion(config, accountId);
+      return true;
+    };
+  } else {
+    const selection = provider._apiKeyAttempt;
+    if (!headers || !provider.apiKey || ![headers.get("authorization"), headers.get("x-api-key"), headers.get("x-goog-api-key")].some(value => value === provider.apiKey || value === `Bearer ${provider.apiKey}`)) return;
+    const entry = configured.apiKeyPool?.find(e => e.id === selection?.entryId && e.key === selection.reference)
+      ?? (!configured.apiKeyPool?.length && configured.apiKey ? { id: apiKeyPoolEntryId(configured.apiKey), key: configured.apiKey, disabled: false, pauseRevision: undefined } : undefined);
+    if (!entry || entry.disabled || !selection) return;
+    const { id, key: reference, pauseRevision } = entry;
+    key = `${name}\0key\0${id}`;
+    const resolvedKey = provider.apiKey;
+    owns = wire => {
+      const sent = CREDENTIAL_HEADERS.map(header => wire.get(header)).filter((value): value is string => value !== null);
+      return sent.length > 0 && sent.every(value => value === resolvedKey || value === `Bearer ${resolvedKey}`);
+    };
+    incarnation = `${createHash("sha256").update(resolvedKey).digest("hex")}\0${pauseRevision ?? ""}`;
+    current = () => {
+      const configured = config.providers[name];
+      const live = configured?.apiKeyPool?.find(e => e.id === id) ?? (!configured?.apiKeyPool?.length && configured?.apiKey === reference ? entry : undefined);
+      return !!live && !live.disabled && live.key === reference && live.pauseRevision === pauseRevision && resolveProviderApiKey(reference) === resolvedKey;
+    };
+    pause = async reason => setProviderApiKeyPaused(config, name, id, true, {
+      selection, pauseRevision, resolvedKey, fence, details: { reason, pausedAt: Date.now() },
+    });
+  }
+  incarnation += `\0${fence.diskRevision}\0${fence.localGen}`;
+  let tracker = streaks.get(config);
+  if (!tracker) { tracker = new AccountRefusalStreaks(); streaks.set(config, tracker); }
+  const observed = new WeakSet<Response>();
+  // undefined: no HTTP final-send report (Codex WebSocket). Such a send is attributable only when
+  // no rewriter was registered at capture and none was registered or removed before the response,
+  // so no plugin could have rewritten the dial in between.
+  const rewriterEpoch = hasUpstreamRewriters() ? undefined : upstreamRewriterEpoch();
+  let wireOwned: boolean | undefined;
+  const observer = (async (response: Response) => {
+    if (observed.has(response) || isNonReplayableResponse(response)) return response;
+    observed.add(response);
+    if (wireOwned !== undefined) reportedResponses.add(response);
+    else if (reportedResponses.has(response)) return response;
+    if (!(wireOwned ?? (rewriterEpoch !== undefined && upstreamRewriterEpoch() === rewriterEpoch))) return response;
+    const counted = countedResponses.get(response) ?? new Set<string>();
+    if (counted.has(key)) return response;
+    countedResponses.set(response, counted.add(key));
+    try {
+      const verdict = permanentAccountRefusal(response).then(reason => {
+        if (reason) markPermanentAccountRefusal(response);
+        return reason;
+      });
+      const paused = await tracker.observe(key, incarnation, threshold, verdict, response.ok,
+        () => policyCurrent() && current(), pause);
+      if (paused) {
+        markAccountAutoPaused(response);
+        // Fixed codes only. Never print the upstream body, provider label, or account identifier.
+        console.warn(`[account-auto-pause] paused after ${threshold} consecutive permanent account refusals`);
+      }
+    } catch {
+      // Optional persistence must preserve the original provider response.
+      console.warn("[account-auto-pause] could not persist account pause; upstream response preserved");
+    }
+    return response;
+  }) as AccountAutoPauseObserver;
+  observer.physical = (sameDestination, wire) => { wireOwned = sameDestination && owns(wire); };
+  return observer;
+}

package/src/oauth/account-quota-rank.ts

@@ -153,7 +153,8 @@ export function accountResetTimestamp(
   const quota = getCachedProviderAccountQuota(provider, accountId);
   if (!quota) return null;
   const family = classifyModelFamilyForQuota(provider, requestedModelId);
-  const windows = (quota.customWindows ?? []).filter(w => !family || windowMatchesFamily(w.label, family));
+  // Model-attributed rows are diagnostics; one must never become the account's reset time.
+  const windows = (quota.customWindows ?? []).filter(w => w.modelId === undefined && (!family || windowMatchesFamily(w.label, family)));
   const weekly = windows.find(w => /week/i.test(w.label));
   let rawReset = weekly?.resetAt ?? quota.weeklyResetAt;
   if (rawReset === undefined && provider !== "google-antigravity" && provider !== "anthropic") {

package/src/oauth/anthropic-account-refusal.ts

@@ -1,3 +1,4 @@
+import { wasAccountAutoPaused } from "./account-auto-pause";
 import { anthropicModelFamily } from "./anthropic-model-quota";
 /** Narrow pre-output account recovery, fenced to the bearer that physically sent the turn. */
 import { readBoundedResponseBody } from "../lib/bounded-body";
@@ -117,6 +118,11 @@ export async function rotateAnthropicAccountOnResponseForInstance(
   const { pauseAnthropicRateAdmission, anthropicRatePauseUntil } = anthropicRatePolicyFor(instance);
   const { recordAnthropicAccountRefusal, rotateAnthropicAccountOnRefusal,
     hasAnthropicFailoverQuorum, isAnthropicAccountPoolEnabled, pickAlternateAnthropicAccount } = routing;
+  if (wasAccountAutoPaused(response)) {
+    if (!options.canRetry || options.signal?.aborted) return null;
+    return pickAlternateAnthropicAccount(options.config, sent.accountId, Date.now(),
+      options.currentDecision ? options.currentDecision() : options.decision ?? null, options.model, options.excludedAccountIds);
+  }
   const ownedCurrent = () => {
     if (configuredAnthropicInstance(options.config, instance) !== instance
       || !anthropicPhysicalSendOwnershipIsCurrent(sent)) return undefined;

package/src/oauth/anthropic-model-family.ts

@@ -0,0 +1,8 @@
+/** Pure family identity shared by existing hard policy and loaded-only advisory evidence. */
+export type AnthropicModelFamily = "Fable" | "Opus" | "Sonnet";
+/** Return the Anthropic model family (Fable, Opus or Sonnet) named by a model id, or undefined for other models. */
+export function anthropicModelFamily(model?: string): AnthropicModelFamily | undefined {
+  return /(?:^|[/])claude-fable-5(?:-|$)/i.test(model ?? "") ? "Fable"
+    : /(?:^|[/])claude-opus-/i.test(model ?? "") ? "Opus"
+      : /(?:^|[/])claude-sonnet-/i.test(model ?? "") ? "Sonnet" : undefined;
+}

package/src/oauth/anthropic-model-quota.ts

@@ -6,12 +6,8 @@ import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
 import type { GenerationContext } from "../lib/state-store-sweeper";
 
 export const ANTHROPIC_PASSIVE_FAMILY_MAX_AGE_MS = 30 * 60_000;
-export type AnthropicModelFamily = "Fable" | "Opus" | "Sonnet";
-export function anthropicModelFamily(model?: string): AnthropicModelFamily | undefined {
-  return /(?:^|[/])claude-fable-5(?:-|$)/i.test(model ?? "") ? "Fable"
-    : /(?:^|[/])claude-opus-/i.test(model ?? "") ? "Opus"
-      : /(?:^|[/])claude-sonnet-/i.test(model ?? "") ? "Sonnet" : undefined;
-}
+import { anthropicModelFamily } from "./anthropic-model-family";
+export { anthropicModelFamily, type AnthropicModelFamily } from "./anthropic-model-family";
 
 export function anthropicModelPercents(quota: ProviderQuota | null, model?: string): number[] {
   const family = anthropicModelFamily(model);

package/src/oauth/api-key-pool-preserve.ts

@@ -0,0 +1,37 @@
+import type { OcxProviderConfig } from "../types";
+import { sanitizeApiKeyValue } from "../providers/api-keys";
+import { accountPauseDetailsSchema } from "../config/schema/account-auto-pause";
+
+/** Runtime guards: provider config is intentionally passthrough, so persisted fields may be malformed. */
+export function preservableApiKeyPool(value: unknown): NonNullable<OcxProviderConfig["apiKeyPool"]> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const pool: NonNullable<OcxProviderConfig["apiKeyPool"]> = [];
+  const ids = new Set<string>();
+  const keys = new Set<string>();
+  for (const entry of value as unknown[]) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const candidate = entry as Record<string, unknown>;
+    const id = typeof candidate.id === "string" ? candidate.id.trim() : "";
+    const key = sanitizeApiKeyValue(candidate.key);
+    if (!id || !key || ids.has(id) || keys.has(key)) continue;
+    const label = typeof candidate.label === "string" ? candidate.label : undefined;
+    const addedAt = typeof candidate.addedAt === "number" && Number.isFinite(candidate.addedAt)
+      ? candidate.addedAt
+      : undefined;
+    const details = accountPauseDetailsSchema.safeParse(candidate.pauseDetails);
+    ids.add(id);
+    keys.add(key);
+    pool.push({
+      id,
+      key,
+      ...(label !== undefined ? { label } : {}),
+      ...(addedAt !== undefined ? { addedAt } : {}),
+      ...(typeof candidate.disabled === "boolean" ? { disabled: candidate.disabled } : {}),
+      ...(typeof candidate.pauseRevision === "string" ? { pauseRevision: candidate.pauseRevision } : {}),
+      ...(details.success ? { pauseDetails: details.data } : {}),
+    });
+  }
+  // Retain paused slots too: their metadata and credentials are needed for explicit resume.
+  return pool.length > 0 ? pool : undefined;
+}
+

package/src/oauth/index.ts

@@ -55,6 +55,7 @@ import { loginOrcaRouter, orcaRouterInferenceBaseUrl, refreshOrcaRouterKey } fro
 import { ANTIGRAVITY_DISCOVERY_UA } from "../adapters/google-antigravity-wire";
 import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers/derive";
 import { apiKeyPoolEntryId, sanitizeApiKeyValue } from "../providers/api-keys";
+import { preservableApiKeyPool } from "./api-key-pool-preserve";
 import { effectiveGoogleMode, getProviderRegistryEntry, mergeRegistryStaticHeaders, providerMatchesRegistryTransport } from "../providers/registry";
 import { providerModelsUrl, resolveProviderModelDiscoveryUrl } from "../providers/model-discovery";
 import { resolveProviderTransport } from "../providers/xai-transport";
@@ -1513,36 +1514,6 @@ export function reconcileOAuthProviders(config: OcxConfig, persist = true): bool
   return true;
 }
 
-/** Runtime guards: provider config is intentionally passthrough, so persisted fields may be malformed. */
-function preservableApiKeyPool(value: unknown): NonNullable<OcxProviderConfig["apiKeyPool"]> | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const pool: NonNullable<OcxProviderConfig["apiKeyPool"]> = [];
-  const ids = new Set<string>();
-  const keys = new Set<string>();
-  for (const entry of value as unknown[]) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-    const candidate = entry as Record<string, unknown>;
-    const id = typeof candidate.id === "string" ? candidate.id.trim() : "";
-    const key = sanitizeApiKeyValue(candidate.key);
-    if (!id || !key || ids.has(id) || keys.has(key)) continue;
-    const label = typeof candidate.label === "string" ? candidate.label : undefined;
-    const addedAt = typeof candidate.addedAt === "number" && Number.isFinite(candidate.addedAt)
-      ? candidate.addedAt
-      : undefined;
-    ids.add(id);
-    keys.add(key);
-    pool.push({
-      id,
-      key,
-      ...(label !== undefined ? { label } : {}),
-      ...(addedAt !== undefined ? { addedAt } : {}),
-    });
-  }
-  // `apiKey` remains the routing source of truth. Keep valid alternate slots even when a
-  // hand-edited config left the pool out of sync, rather than deleting usable credentials.
-  return pool.length > 0 ? pool : undefined;
-}
-
 const OAUTH_LOGIN_OWNED_PROVIDER_FIELDS = [
   "adapter",
   "baseUrl",
@@ -1597,11 +1568,10 @@ export function upsertOAuthProvider(config: OcxConfig, provider: string): void {
     // Shared sanitizeApiKeyValue trim / no-CRLF checks from api-key pool writes.
     let storedApiKey = sanitizeApiKeyValue(existing.apiKey);
     const storedApiKeyPool = preservableApiKeyPool(existing.apiKeyPool);
-    // Unsafe/blank active key with a usable pool: promote the first safe pool entry so
-    // key billing keeps working instead of falling back to oauth while pool keys remain.
-    if (storedApiKey === undefined && storedApiKeyPool && storedApiKeyPool.length > 0) {
-      storedApiKey = storedApiKeyPool[0]!.key;
-    }
+    // Retain all-paused pools without activating any paused credential during login.
+    if (storedApiKeyPool?.some(entry => entry.key === storedApiKey && entry.disabled)) storedApiKey = undefined;
+    if (storedApiKey === undefined) storedApiKey = storedApiKeyPool?.find(entry => !entry.disabled)?.key;
+    if (storedApiKeyPool) next.apiKeyPool = storedApiKeyPool;
     if (storedApiKey !== undefined) {
       const pool = storedApiKeyPool ? [...storedApiKeyPool] : [];
       // Keep routing and listProviderApiKeys in sync: never leave a hidden active key that

package/src/oauth/store.ts

@@ -19,6 +19,8 @@
  *   distinct one. Kimi extracts JWT `user_id`/`sub` as accountId; Cursor extracts JWT `sub` —
  *   both append distinct identified accounts under multiauth.
  */
+import { notifyAuthStoreLoaded } from "../lib/decision-quota-sink";
+import { accountPauseDetailsSchema } from "../config/schema/account-auto-pause";
 import { normalizeOAuthPlan, mergeOAuthPlan } from "./plan";
 import { normalizeAnthropicIdentity, matchesAnthropicImport, mergeAnthropicIdentity } from "./anthropic-identity";
 import { findKiroAccountForLogin, withRetainedKiroUser } from "./kiro-account-identity";
@@ -354,17 +356,23 @@ export function credentialGeneration(cred: OAuthCredentials): string {
   return createHash("sha256").update(JSON.stringify([cred.refresh, cred.access, cred.expires])).digest("hex");
 }
 
+/** Load and normalize the OAuth auth store with hardened permissions, and hand the result to the opt-in decision-quota slot (a no-op unless JEV quota signals are active). */
 function loadAuthStoreInternal(): { store: AuthStore; hadLegacy: boolean } {
   const path = getAuthStorePath();
   hardenConfigDir();
   hardenExistingSecret(path);
-  if (!existsSync(path)) return { store: {}, hadLegacy: false };
+  if (!existsSync(path)) { notifyAuthStoreLoaded({}); return { store: {}, hadLegacy: false }; }
+  let result: { store: AuthStore; hadLegacy: boolean };
   try {
-    return normalizeAuthStore(JSON.parse(readFileSync(path, "utf-8")));
+    result = normalizeAuthStore(JSON.parse(readFileSync(path, "utf-8")));
   } catch {
     backupInvalidConfig(path);
+    notifyAuthStoreLoaded({});
     return { store: {}, hadLegacy: false };
   }
+  // Outside the parse try: roster publication is advisory and must never route a loaded store into the invalid-config backup path.
+  notifyAuthStoreLoaded(result.store);
+  return result;
 }
 
 export function loadAuthStore(): AuthStore {
@@ -403,6 +411,7 @@ export function peekAuthStore(): AuthStore {
   return snapshot.kind === "ready" ? snapshot.store : {};
 }
 
+/** Atomically write the auth store with owner-only permissions, then hand it to the opt-in decision-quota slot. */
 function persist(store: AuthStore): void {
   const dir = getConfigDir();
   assertNotRealHomeUnderTest(dir);
@@ -413,6 +422,7 @@ function persist(store: AuthStore): void {
   }
   hardenConfigDir();
   atomicWriteFile(getAuthStorePath(), JSON.stringify(store, null, 2) + "\n");
+  notifyAuthStoreLoaded(store);
 }
 
 export class OAuthFileLockError extends Error { readonly code = "OAUTH_FILE_LOCK_UNAVAILABLE"; constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "OAuthFileLockError"; } }
@@ -638,7 +648,12 @@ function normalizeAccount(value: unknown): ProviderAccount | null {
   if (candidate.refreshAttentionGeneration === credentialGeneration(credential)) {
     account.refreshAttentionGeneration = candidate.refreshAttentionGeneration;
   }
-  if (candidate.paused === true) account.paused = true;
+  if (candidate.paused === true) {
+    account.paused = true;
+    const details = accountPauseDetailsSchema.safeParse(candidate.pauseDetails);
+    if (details.success) account.pauseDetails = details.data;
+  }
+  if (typeof candidate.pauseRevision === "string") account.pauseRevision = candidate.pauseRevision;
   const threshold = parseAnthropicAccountThreshold(candidate.autoSwitchThresholdOverride);
   if (threshold !== null) account.autoSwitchThresholdOverride = threshold;
   if (candidate.needsReauth === true && candidate.needsReauthReason === "verify_account") {
@@ -801,7 +816,7 @@ function serializeMutation<T>(work: () => Promise<T>, retainedValues: readonly u
   drainOAuthMutations();
   return result;
 }
-export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number; assertBeforePersist?: () => void; scrubLegacyBackup?: (result: T) => readonly string[]; finalizeResult?: (result: T, store: AuthStore) => void; afterPersist?: (result: T) => void }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
+export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValues: readonly unknown[] = [], options?: { waitMs?: number; assertBeforePersist?: () => void; scrubLegacyBackup?: (result: T) => readonly string[]; finalizeResult?: (result: T, store: AuthStore) => void; afterPersist?: (result: T) => void; withConfigLock?: boolean }):Promise<T>{return serializeMutation(async()=>{const guard=await createOAuthFileLock({path:getAuthStoreLockPath(),staleAfterMs:30000}).acquire();try{
     const { store, hadLegacy } = loadAuthStoreInternal();
     if (hadLegacy) backupLegacyOnce();
     const selections = new Map(Object.entries(store).map(([provider, set]) => [provider, {
@@ -814,7 +829,7 @@ export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValue
     // Only providers whose credentials this mutation actually removed leave the downgrade
     // backup; a no-op removal names none. The result decides, so it is read here.
     const scrubbedProviders = options?.scrubLegacyBackup?.(result) ?? [];
-    options?.assertBeforePersist?.();
+    if (!options?.withConfigLock) options?.assertBeforePersist?.();
     const changedProviders: string[] = [];
     for (const provider of new Set([...selections.keys(), ...Object.keys(store)])) {
       const before = selections.get(provider);
@@ -837,7 +852,8 @@ export function mutateStore<T>(fn:(store:AuthStore)=>T|Promise<T>, retainedValue
     // Receipt-producing mutations need the revision assigned by the bookkeeping above, not the
     // provisional value visible inside their callback. Finalization cannot await or mutate disk.
     options?.finalizeResult?.(result, store);
-    persist(store);
+    const publish = () => { if (options?.withConfigLock) options.assertBeforePersist?.(); persist(store); };
+    if (options?.withConfigLock) withConfigMutationLockSync(publish); else publish();
     if (scrubbedProviders.length > 0) scrubLegacyBackup(scrubbedProviders);
     // A committed observer may establish ordering before the generic selection
     // publication, but its failure can never turn a durable write into a reported failure.
@@ -1388,17 +1404,23 @@ export async function setAccountPaused(
   provider: string,
   accountId: string,
   paused: boolean,
+  automatic?: { generation: string; pauseRevision?: string; details: import("../types/account-auto-pause").AccountPauseDetails; isCurrent?: () => boolean; assertPolicyBeforePersist?: () => void },
 ): Promise<SetAccountPausedResult> {
   const result = await mutateStore(store => {
     const set = store[provider];
     const account = set?.accounts.find(candidate => candidate.id === accountId);
     if (!set || !account) return { status: "not-found" } as const;
-    if ((account.paused === true) === paused) {
+    if (automatic && (automatic.isCurrent?.() === false || credentialGeneration(account.credential) !== automatic.generation
+      || account.pauseRevision !== automatic.pauseRevision)) return { status: "not-found" } as const;
+    if (paused && account.paused === true) {
       return { status: "unchanged", activeAccountId: set.activeAccountId, activeAccountChanged: false } as const;
     }
 
     if (paused) account.paused = true;
     else delete account.paused;
+    account.pauseRevision = randomUUID();
+    if (automatic) account.pauseDetails = automatic.details;
+    else delete account.pauseDetails;
     // Pause is part of selection eligibility even when the operator changes a non-active
     // account. Bump the provider selection revision so observers receive the existing
     // post-persistence roster invalidation and stale automatic proposals cannot commit.
@@ -1432,7 +1454,10 @@ export async function setAccountPaused(
       activeAccountId: set.activeAccountId,
       activeAccountChanged,
     } as const;
-  }, [provider, accountId, paused]);
+  }, [provider, accountId, paused], { withConfigLock: !!automatic, assertBeforePersist: () => {
+    automatic?.assertPolicyBeforePersist?.();
+    if (automatic?.isCurrent?.() === false) throw new Error("Account auto-pause policy changed before persistence");
+  } });
   if (result.status === "updated") publishOAuthAccountPauseChange(provider);
   return result;
 }
@@ -1485,6 +1510,8 @@ export async function replaceProviderAccountSet(
         ...(account.needsReauth ? { needsReauth: true } : {}),
         ...(account.refreshAttentionGeneration ? { refreshAttentionGeneration: account.refreshAttentionGeneration } : {}),
         ...(account.paused ? { paused: true } : {}),
+        ...(account.pauseDetails ? { pauseDetails: account.pauseDetails } : {}),
+        ...(account.pauseRevision ? { pauseRevision: account.pauseRevision } : {}),
         ...(account.autoSwitchThresholdOverride !== undefined ? { autoSwitchThresholdOverride: account.autoSwitchThresholdOverride } : {}),
         ...(account.needsReauthReason === "verify_account" ? { needsReauthReason: account.needsReauthReason } : {}),
         ...(account.addedAt !== undefined ? { addedAt: account.addedAt } : {}),

package/src/oauth/types.ts

@@ -96,6 +96,8 @@ export interface ProviderAccount {
   refreshAttentionGeneration?: string;
   /** Operator exclusion from generic OAuth account selection until explicitly resumed. */
   paused?: boolean;
+  pauseDetails?: import("../types/account-auto-pause").AccountPauseDetails;
+  pauseRevision?: string;
   /** Anthropic-only usage-switch override; absent inherits its pool default, zero disables it. */
   autoSwitchThresholdOverride?: number;
   /**

package/src/plugins/upstream-hooks.ts

@@ -31,13 +31,20 @@ interface Registration {
 }
 
 const registrations: Registration[] = [];
+// Changes on every registration and removal, so an observer can tell that no rewriter could
+// have touched a send between two points even when the slot is empty at both.
+let registrationEpoch = 0;
 
 export function registerUpstreamRewriter(name: string, rewrite: UpstreamRewriter): () => void {
   const registration: Registration = { name, rewrite, disabled: false };
   registrations.push(registration);
+  registrationEpoch += 1;
   return () => {
     const index = registrations.indexOf(registration);
-    if (index >= 0) registrations.splice(index, 1);
+    if (index >= 0) {
+      registrations.splice(index, 1);
+      registrationEpoch += 1;
+    }
   };
 }
 
@@ -45,6 +52,11 @@ export function hasUpstreamRewriters(): boolean {
   return registrations.length > 0;
 }
 
+/** Monotonic registration epoch; equal values bracket a window with no registration change. */
+export function upstreamRewriterEpoch(): number {
+  return registrationEpoch;
+}
+
 /**
  * Run every active rewriter over one send. Returns the input untouched (same objects) when
  * no rewriter is registered, so the common path allocates nothing.
@@ -116,4 +128,5 @@ export function rewriteWebSocketDial(
 
 export function resetUpstreamRewritersForTests(): void {
   registrations.length = 0;
+  registrationEpoch += 1;
 }

package/src/providers/api-key-pause.ts

@@ -0,0 +1,32 @@
+import { accountAutoPauseFenceMatchesDisk, type AccountAutoPauseFence } from "../config/account-auto-pause-revisions";
+import { randomUUID } from "node:crypto";
+import type { OcxConfig } from "../types";
+import type { ProviderApiKeySelection } from "../types/provider";
+import type { AccountPauseDetails } from "../types/account-auto-pause";
+import { apiKeyPoolEntryId } from "./api-keys";
+import { resolveProviderApiKey } from "./api-key-resolve";
+import { commitProviderApiKeySelection } from "./api-key-selection";
+
+export function setProviderApiKeyPaused(config: OcxConfig, name: string, id: string, paused: boolean,
+  automatic?: { fence: AccountAutoPauseFence; selection: ProviderApiKeySelection; pauseRevision?: string; resolvedKey?: string; details: AccountPauseDetails }): boolean {
+  const result = commitProviderApiKeySelection(config, name, provider => {
+    if (automatic && !accountAutoPauseFenceMatchesDisk(name, automatic.fence)) return { changed: false, value: false };
+    const pool = provider.apiKeyPool?.length ? provider.apiKeyPool
+      : provider.apiKey ? [{ id: apiKeyPoolEntryId(provider.apiKey), key: provider.apiKey }] : [];
+    const entry = pool.find(e => e.id === id);
+    if (!entry || automatic && (entry.disabled || entry.key !== automatic.selection.reference || entry.pauseRevision !== automatic.pauseRevision
+      || provider.accountAutoPause?.enabled !== true || resolveProviderApiKey(entry.key) !== automatic.resolvedKey)) return { changed: false, value: false };
+    provider.apiKeyPool = pool;
+    entry.disabled = paused;
+    entry.pauseRevision = randomUUID();
+    if (automatic) entry.pauseDetails = automatic.details;
+    else delete entry.pauseDetails;
+    if (paused && provider.apiKey === entry.key) {
+      const next = provider.apiKeyPool?.find(e => !e.disabled);
+      if (next) provider.apiKey = next.key;
+      else delete provider.apiKey;
+    } else if (!paused && !provider.apiKey) provider.apiKey = entry.key;
+    return { changed: true, selectionChanged: true, value: true };
+  }, automatic?.selection);
+  return result.status === "committed" && result.value;
+}

package/src/providers/api-key-resolve.ts

@@ -16,6 +16,7 @@
  * Policy: a reference that cannot be resolved fails closed (no key) and is warned once per
  * account; nothing ever rewrites plaintext into config or its backups.
  */
+import { invalidateDecisionKeyQuotas, observeDecisionKeyCredential } from "../lib/decision-quota-sink";
 import { resolveEnvValue } from "../config/proxy-env";
 import { loadKeyringBinding } from "../lib/keyring-native";
 import { isGcpCredentialMaterial } from "../lib/gcp-credential-input";
@@ -52,6 +53,7 @@ export function providerKeyResolutionGeneration(): number {
 /** Test seam: swap the OS entry for an in-memory one and drop caches. */
 export function setProviderKeychainEntryFactoryForTests(factory: ProviderKeychainEntryFactory | null): void {
   entryFactory = factory ?? defaultEntryFactory;
+  invalidateDecisionKeyQuotas();
   resolvedCache.clear();
   resolutionGeneration++;
   warnedAccounts.clear();
@@ -59,6 +61,7 @@ export function setProviderKeychainEntryFactoryForTests(factory: ProviderKeychai
 
 /** Write-path seam: a store/restore mutated secrets, so cached reads and warnings are stale. */
 export function invalidateResolvedProviderKeyCache(): void {
+  invalidateDecisionKeyQuotas();
   resolvedCache.clear();
   resolutionGeneration++;
   warnedAccounts.clear();
@@ -114,15 +117,18 @@ function readKeychain(account: string, quiet = false): string | undefined {
  */
 export function resolveProviderApiKey(value: string | undefined): string | undefined {
   if (!value) return undefined;
-  if (isKeychainReference(value)) return readKeychain(keychainAccount(value));
-  return resolveEnvValue(value);
+  const resolved = isKeychainReference(value) ? readKeychain(keychainAccount(value)) : resolveEnvValue(value);
+  observeDecisionKeyCredential(value, resolved);
+  return resolved;
 }
 
 /** The same resolution without the unreadable-reference warning, for observe-only callers. */
 export function resolveProviderApiKeyQuietly(value: string | undefined): string | undefined {
   if (!value) return undefined;
-  if (isKeychainReference(value)) return readKeychain(keychainAccount(value), true);
-  return resolveEnvValue(value);
+  const resolved = isKeychainReference(value) ? readKeychain(keychainAccount(value), true) : resolveEnvValue(value);
+  // A quiet read still sees a replaced secret; advisory key evidence published under the old one must not outlive it.
+  observeDecisionKeyCredential(value, resolved);
+  return resolved;
 }
 
 export type ProviderKeyStoreKind = "keychain" | "env" | "file" | "none";

package/src/providers/api-key-selection.ts

@@ -13,6 +13,9 @@ import { captureProviderApiKeySelection } from "./api-key-selection-capture";
 export { captureProviderApiKeySelection } from "./api-key-selection-capture";
 
 function matchesSelection(provider: OcxProviderConfig, expected: ProviderApiKeySelection): boolean {
+  if (expected.distributed) return provider.apiKeySelectionRevision === expected.revision
+    && provider.requestPacing?.enabled === true && provider.requestPacing.keySelection === "round-robin"
+    && !!provider.apiKeyPool?.some(entry => !entry.disabled && entry.id === expected.entryId && entry.key === expected.reference);
   const current = captureProviderApiKeySelection(provider);
   return current.entryId === expected.entryId && current.reference === expected.reference
     && current.revision === expected.revision;
@@ -24,10 +27,12 @@ function currentKeyProvider(config: OcxConfig, name: string, selection?: Provide
   let row = configured;
   if (selection?.distributed) {
     const entry = configured.apiKeyPool?.find(key => key.id === selection.entryId && key.key === selection.reference);
-    if (!entry || (!allowCooling && isKeyInCooldown(name, entry.id)) || configured.apiKeySelectionRevision !== selection.revision
+    if (!entry || entry.disabled || (!allowCooling && isKeyInCooldown(name, entry.id)) || configured.apiKeySelectionRevision !== selection.revision
       || !configured.requestPacing?.enabled || configured.requestPacing.keySelection !== "round-robin") return null;
     row = { ...configured, apiKey: entry.key, _apiKeyAttempt: selection };
   }
+  if (row.apiKeyPool?.some(entry => entry.disabled && entry.key === row.apiKey)
+    || row.apiKeyPool?.length && row.apiKeyPool.every(entry => entry.disabled)) return null;
   const current = routedProviderConfig(name, { ...row, _apiKeyAttempt: selection?.distributed ? selection : undefined });
   if (current.authMode === "oauth" || current.authMode === "forward") return null;
   if (current.authMode === "key" && !current.keyOptional && !current.apiKey?.trim()) return null;