codex-multi-auth 2.9.2 → 2.11.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-multi-auth",
-	"version": "2.9.2",
+	"version": "2.11.0",
   "description": "Install and operate codex-multi-auth for the official @openai/codex CLI with multi-account OAuth rotation, switching, health checks, and recovery tools.",
   "interface": {
     "composerIcon": "./assets/codex-multi-auth-icon.svg"

package/README.md

@@ -329,6 +329,7 @@ The Settings menu now includes an `Experimental` section for staged features:
 - preview-first sync into `oc-chatgpt-multi-auth`
 - named local pool backup export with filename prompt
 - refresh guard toggle and interval controls moved out of Backend Controls
+- context budget guard: pause a session before it hits the model's context window, with independently configurable soft/hard thresholds (default 65% / 69%) — ships disabled; see [Context Budget Guard](docs/features.md#context-budget-guard-experimental)
 
 These flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.
 
@@ -405,7 +406,7 @@ codex-multi-auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v2.9.2.md](docs/releases/v2.9.2.md) — install via `npm i -g codex-multi-auth`
+- Current stable: [docs/releases/v2.11.0.md](docs/releases/v2.11.0.md) — install via `npm i -g codex-multi-auth`
 - Previous stable: [docs/releases/v2.8.3.md](docs/releases/v2.8.3.md)
 - Previous stable: [docs/releases/v2.8.2.md](docs/releases/v2.8.2.md)
 - Previous stable: [docs/releases/v2.7.1.md](docs/releases/v2.7.1.md)

package/config/README.md

@@ -17,7 +17,9 @@ These files are optional model/provider templates for host/plugin configurations
 
 ## Defaults Included
 
-- Current documented OpenAI/Codex model families (`gpt-5.6-sol`/`terra`/`luna`, `gpt-5.5`, `gpt-5.4`, and `gpt-5.3-codex`)
+- Current documented OpenAI/Codex model families: GPT-6 Astra (`gpt-6-astra`, `gpt-6-astra-aeon`), then `gpt-5.6-sol`/`terra`/`luna`, `gpt-5.5`, `gpt-5.4`, and `gpt-5.3-codex`
+- The Astra entries carry `limit.context: 272000`, OpenAI's stable Codex context value at launch. The GPT-5.6 entries still carry the pre-cut `372000` and were left alone here; change them only alongside a deliberate review, since the value feeds a picker rather than the context budget guard (which refuses to estimate either family)
+- The Daybreak cyber models resolve at the code level but are deliberately absent from these templates, matching their hidden visibility in the upstream Codex picker
 - `store: false`
 - `include: ["reasoning.encrypted_content"]`
 - Sensible fallback behavior for unsupported model entitlements

package/config/codex-legacy.json

@@ -15,6 +15,306 @@
         "store": false
       },
       "models": {
+        "gpt-6-astra-low": {
+          "name": "GPT 6 Astra Low (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "low",
+            "reasoningSummary": "auto",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-medium": {
+          "name": "GPT 6 Astra Medium (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "medium",
+            "reasoningSummary": "auto",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-high": {
+          "name": "GPT 6 Astra High (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "high",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-xhigh": {
+          "name": "GPT 6 Astra Extra High (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "xhigh",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-max": {
+          "name": "GPT 6 Astra Max (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "max",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-ultra": {
+          "name": "GPT 6 Astra Ultra (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "ultra",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-low": {
+          "name": "GPT 6 Astra Aeon Low (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "low",
+            "reasoningSummary": "auto",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-medium": {
+          "name": "GPT 6 Astra Aeon Medium (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "medium",
+            "reasoningSummary": "auto",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-high": {
+          "name": "GPT 6 Astra Aeon High (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "high",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-xhigh": {
+          "name": "GPT 6 Astra Aeon Extra High (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "xhigh",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-max": {
+          "name": "GPT 6 Astra Aeon Max (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "max",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
+        "gpt-6-astra-aeon-ultra": {
+          "name": "GPT 6 Astra Aeon Ultra (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "options": {
+            "reasoningEffort": "ultra",
+            "reasoningSummary": "detailed",
+            "textVerbosity": "medium",
+            "include": [
+              "reasoning.encrypted_content"
+            ],
+            "store": false
+          }
+        },
         "gpt-5.6-sol-low": {
           "name": "GPT 5.6 Sol Low (OAuth)",
           "limit": {

package/config/codex-modern.json

@@ -15,6 +15,102 @@
         "store": false
       },
       "models": {
+        "gpt-6-astra": {
+          "name": "GPT 6 Astra (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "variants": {
+            "low": {
+              "reasoningEffort": "low",
+              "reasoningSummary": "auto",
+              "textVerbosity": "medium"
+            },
+            "medium": {
+              "reasoningEffort": "medium",
+              "reasoningSummary": "auto",
+              "textVerbosity": "medium"
+            },
+            "high": {
+              "reasoningEffort": "high",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "xhigh": {
+              "reasoningEffort": "xhigh",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "max": {
+              "reasoningEffort": "max",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "ultra": {
+              "reasoningEffort": "ultra",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            }
+          }
+        },
+        "gpt-6-astra-aeon": {
+          "name": "GPT 6 Astra Aeon (OAuth)",
+          "limit": {
+            "context": 272000,
+            "output": 128000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          },
+          "variants": {
+            "low": {
+              "reasoningEffort": "low",
+              "reasoningSummary": "auto",
+              "textVerbosity": "medium"
+            },
+            "medium": {
+              "reasoningEffort": "medium",
+              "reasoningSummary": "auto",
+              "textVerbosity": "medium"
+            },
+            "high": {
+              "reasoningEffort": "high",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "xhigh": {
+              "reasoningEffort": "xhigh",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "max": {
+              "reasoningEffort": "max",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            },
+            "ultra": {
+              "reasoningEffort": "ultra",
+              "reasoningSummary": "detailed",
+              "textVerbosity": "medium"
+            }
+          }
+        },
         "gpt-5.6-sol": {
           "name": "GPT 5.6 Sol (OAuth)",
           "limit": {

package/config/schema/config.schema.json

@@ -247,6 +247,29 @@
           "type": "number",
           "minimum": 1000
         },
+        "contextBudgetGuardEnabled": {
+          "type": "boolean"
+        },
+        "contextBudgetGuardSoftPercent": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "contextBudgetGuardHardPercent": {
+          "type": "number",
+          "minimum": 10,
+          "maximum": 100
+        },
+        "contextBudgetGuardModelWindowOverrides": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          }
+        },
         "routingMutex": {
           "type": "string",
           "enum": [

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,kBAAkB,CAAC;AAoW5D;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MAuwI/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAoB,CAAC;AAElD,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,kBAAkB,CAAC;AA8W5D;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MA80I/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAoB,CAAC;AAElD,eAAe,iBAAiB,CAAC"}

package/dist/index.js

@@ -30,9 +30,11 @@ import { startLocalOAuthServer } from "./lib/auth/server.js";
 import { checkAndNotify } from "./lib/update-notice.js";
 import { CapabilityPolicyStore } from "./lib/capability-policy.js";
 import { promptAddAnotherAccount, promptLoginMode } from "./lib/cli.js";
-import { getAutoResume, getCodexMode, getEmptyResponseMaxRetries, getEmptyResponseRetryDelayMs, getFallbackToGpt52OnUnsupportedGpt53, getFastSession, getFastSessionMaxInputItems, getFastSessionStrategy, getFetchTimeoutMs, getRateLimitDedupWindowMs, getRateLimitMaxBackoffMs, getRateLimitShortRetryThresholdMs, getRateLimitStateResetMs, getLiveAccountSync, getLiveAccountSyncDebounceMs, getLiveAccountSyncPollMs, getNetworkErrorCooldownMs, getPerProjectAccounts, getPidOffsetEnabled, getPreemptiveQuotaEnabled, getPreemptiveQuotaMaxDeferralMs, getPreemptiveQuotaRemainingPercent5h, getPreemptiveQuotaRemainingPercent7d, getProactiveRefreshBufferMs, getProactiveRefreshGuardian, getProactiveRefreshIntervalMs, getRateLimitToastDebounceMs, getRetryAllAccountsMaxRetries, getRetryAllAccountsMaxWaitMs, getRetryAllAccountsRateLimited, getBackgroundResponses, getResponseContinuation, getServerErrorCooldownMs, getSessionAffinity, getSessionAffinityMaxEntries, getSessionAffinityTtlMs, getSessionRecovery, getStorageBackupEnabled, getStreamStallTimeoutMs, getToastDurationMs, getTokenRefreshSkewMs, getUnsupportedCodexFallbackChain, getUnsupportedCodexPolicy, loadPluginConfig, } from "./lib/config.js";
+import { getAutoResume, getCodexMode, getEmptyResponseMaxRetries, getEmptyResponseRetryDelayMs, getFallbackToGpt52OnUnsupportedGpt53, getFastSession, getFastSessionMaxInputItems, getFastSessionStrategy, getFetchTimeoutMs, getRateLimitDedupWindowMs, getRateLimitMaxBackoffMs, getRateLimitShortRetryThresholdMs, getRateLimitStateResetMs, getLiveAccountSync, getLiveAccountSyncDebounceMs, getLiveAccountSyncPollMs, getNetworkErrorCooldownMs, getPerProjectAccounts, getPidOffsetEnabled, getPreemptiveQuotaEnabled, getPreemptiveQuotaMaxDeferralMs, getPreemptiveQuotaRemainingPercent5h, getPreemptiveQuotaRemainingPercent7d, getContextBudgetGuardEnabled, getContextBudgetGuardSoftPercent, getContextBudgetGuardHardPercent, getContextBudgetGuardModelWindowOverrides, getProactiveRefreshBufferMs, getProactiveRefreshGuardian, getProactiveRefreshIntervalMs, getRateLimitToastDebounceMs, getRetryAllAccountsMaxRetries, getRetryAllAccountsMaxWaitMs, getRetryAllAccountsRateLimited, getBackgroundResponses, getResponseContinuation, getServerErrorCooldownMs, getSessionAffinity, getSessionAffinityMaxEntries, getSessionAffinityTtlMs, getSessionRecovery, getStorageBackupEnabled, getStreamStallTimeoutMs, getToastDurationMs, getTokenRefreshSkewMs, getUnsupportedCodexFallbackChain, getUnsupportedCodexPolicy, loadPluginConfig, } from "./lib/config.js";
 import { ACCOUNT_LIMITS, AUTH_LABELS, CODEX_BASE_URL, DUMMY_API_KEY, LOG_STAGES, PLUGIN_NAME, PROVIDER_ID, } from "./lib/constants.js";
 import { handleContextOverflow } from "./lib/context-overflow.js";
+import { ContextBudgetGuard } from "./lib/context-budget-guard.js";
+import { buildContextBudgetHeaders, createContextBudgetPauseResponse, } from "./lib/context-budget-response.js";
 import { EntitlementCache, resolveEntitlementAccountKey, } from "./lib/entitlement-cache.js";
 import { LiveAccountSync } from "./lib/live-account-sync.js";
 import { clearCorrelationId, initLogger, logDebug, logError, logInfo, logRequest, logWarn, setCorrelationId, } from "./lib/logger.js";
@@ -89,6 +91,7 @@ import { ensureLiveAccountSyncEntry } from "./lib/runtime/live-sync-entry.js";
 import { applyLoaderRuntimeSetup } from "./lib/runtime/loader-setup.js";
 import { buildManualOAuthFlow } from "./lib/runtime/manual-oauth-flow.js";
 import { applyPreemptiveQuotaSettingsFromConfig } from "./lib/runtime/quota-settings.js";
+import { applyContextBudgetGuardSettingsFromConfig } from "./lib/runtime/context-budget-settings.js";
 import { ensureLiveAccountSyncState, ensureRefreshGuardianState, ensureSessionAffinityState, } from "./lib/runtime/runtime-services.js";
 import { getRuntimeObservabilitySnapshot, mutateRuntimeObservabilitySnapshot, } from "./lib/runtime/runtime-observability.js";
 import { applyAccountStorageScopeFromConfig } from "./lib/runtime/storage-scope.js";
@@ -166,6 +169,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
     let sessionAffinityConfigKey = null;
     const entitlementCache = new EntitlementCache();
     const preemptiveQuotaScheduler = new PreemptiveQuotaScheduler();
+    const contextBudgetGuard = new ContextBudgetGuard();
     const capabilityPolicyStore = new CapabilityPolicyStore();
     let accountReloadInFlight = null;
     const exposeAdvancedCodexTools = (process.env.CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS ?? "").trim() === "1";
@@ -359,6 +363,13 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
         getPreemptiveQuotaRemainingPercent7d,
         getPreemptiveQuotaMaxDeferralMs,
     });
+    const applyContextBudgetGuardSettings = (pluginConfig) => applyContextBudgetGuardSettingsFromConfig(pluginConfig, {
+        configure: (options) => contextBudgetGuard.configure(options),
+        getContextBudgetGuardEnabled,
+        getContextBudgetGuardSoftPercent,
+        getContextBudgetGuardHardPercent,
+        getContextBudgetGuardModelWindowOverrides,
+    });
     // Event handler for session recovery and account selection
     const eventHandler = async (input) => handleRuntimeEvent({
         input,
@@ -410,6 +421,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                     ensureSessionAffinity,
                     ensureRefreshGuardian,
                     applyPreemptiveQuotaSettings,
+                    applyContextBudgetGuardSettings,
                 });
                 // Only handle OAuth auth type, skip API key auth
                 if (auth.type !== "oauth") {
@@ -603,6 +615,23 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                     .toString()
                                     .trim() || undefined;
                                 const sessionAffinityKey = threadIdCandidate ?? promptCacheKey ?? null;
+                                // Context budget guard: pause BEFORE spending an upstream
+                                // round-trip on a request the tracked session is already over
+                                // the hard threshold for, rather than waiting on the eventual
+                                // context_length_exceeded 400 that handleContextOverflow below
+                                // only reacts to after the fact. Independent of which account
+                                // ends up serving the request, so it runs ahead of account
+                                // selection entirely rather than inside its retry loop.
+                                const contextBudgetAdvisory = contextBudgetGuard.getAdvisory(sessionAffinityKey ?? "", Date.now(), model);
+                                if (contextBudgetAdvisory.level === "hard") {
+                                    // One-shot: this pause returns before the request is
+                                    // forwarded, so the onUsage hook that would lower the
+                                    // recorded usage never runs. Dropping the snapshot keeps
+                                    // the session recoverable — otherwise the `/compact` turn
+                                    // this message asks for is blocked by the same key.
+                                    contextBudgetGuard.noteHardPauseEmitted(sessionAffinityKey ?? "");
+                                    return createContextBudgetPauseResponse(contextBudgetAdvisory);
+                                }
                                 const sessionAffinityVersion = (sessionAffinityWriteVersion += 1);
                                 const effectivePromptCacheKey = (sessionAffinityKey ?? promptCacheKey ?? "")
                                     .toString()
@@ -1614,7 +1643,22 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                     sessionAffinityStore?.updateLastResponseId(sessionAffinityKey, responseId, Date.now(), sessionAffinityVersion);
                                                     storedResponseIdForSuccess = true;
                                                 },
-                                                onUsage: usageDeferral.onUsage,
+                                                onUsage: (usage) => {
+                                                    usageDeferral.onUsage(usage);
+                                                    // Responses is mostly stateless (store=false): this
+                                                    // turn's input_tokens reflects the full conversation
+                                                    // resent this call, so it doubles as a live read of
+                                                    // the session's current context size. input + output, NOT
+                                                    // total: total_tokens also counts reasoning tokens, which
+                                                    // are not resent as context on the next turn.
+                                                    if (sessionAffinityKey && model) {
+                                                        contextBudgetGuard.update(sessionAffinityKey, {
+                                                            model,
+                                                            contextTokens: usage.inputTokens + usage.outputTokens,
+                                                            updatedAt: Date.now(),
+                                                        });
+                                                    }
+                                                },
                                                 streamStallTimeoutMs,
                                             });
                                             if (!isStreaming && emptyResponseMaxRetries > 0) {
@@ -1723,6 +1767,22 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                             clearPoolExhaustionCooldown();
                                             clearServerBurstCooldown();
                                             syncRuntimeObservability(requestTraceId);
+                                            // Non-blocking: contextBudgetAdvisory reflects usage
+                                            // observed as of the PRIOR turn (this turn's own usage
+                                            // isn't known yet for a streaming body), attached as a
+                                            // header for `codex-multi-auth status` / the statusline
+                                            // rather than altering this response's body.
+                                            if (contextBudgetAdvisory.level === "soft") {
+                                                const headers = new Headers(successResponse.headers);
+                                                for (const [name, value] of Object.entries(buildContextBudgetHeaders(contextBudgetAdvisory))) {
+                                                    headers.set(name, value);
+                                                }
+                                                return new Response(successResponse.body, {
+                                                    status: successResponse.status,
+                                                    statusText: successResponse.statusText,
+                                                    headers,
+                                                });
+                                            }
                                             return successResponse;
                                         }
                                         if (retryNextAccountBeforeFallback) {

package/dist/lib/accounts.d.ts

@@ -147,7 +147,31 @@ export declare class AccountManager {
     recordSuccess(account: ManagedAccount, family: ModelFamily, model?: string | null): void;
     recordRateLimit(account: ManagedAccount, family: ModelFamily, model?: string | null): void;
     recordFailure(account: ManagedAccount, family: ModelFamily, model?: string | null): void;
-    consumeToken(account: ManagedAccount, family: ModelFamily, model?: string | null): boolean;
+    consumeToken(account: ManagedAccount, family: ModelFamily, model?: string | null, options?: {
+        bypassTokenBucket?: boolean;
+    }): boolean;
+    /**
+     * `consumeToken`, but it says which admission gate rejected the request.
+     *
+     * There are two gates and they are not interchangeable to a caller writing
+     * `account_skip_reasons`: the pool-scoring token bucket, and the circuit
+     * breaker's race-safe admission slot. Re-deriving the answer afterwards
+     * with `getManagedAccountRuntimeSkipReason` gets it wrong in both
+     * directions -- that helper reports the FIRST blocker it finds (so a live
+     * cooldown masks a drained bucket), and its `isAvailable()` check answers
+     * true for a half-open breaker whose single probe `canExecute()` just
+     * handed to a concurrent request. Reporting the gate that actually
+     * rejected removes the race and the mis-attribution, and avoids a second
+     * state-mutating evaluation (`clearExpiredRateLimits`) on the hot path.
+     */
+    consumeTokenWithReason(account: ManagedAccount, family: ModelFamily, model?: string | null, options?: {
+        bypassTokenBucket?: boolean;
+    }): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: "token-exhausted" | "circuit-open";
+    };
     /**
      * Refund a token consumed within the refund window (30 seconds).
      * Use this when a request fails due to network errors (not rate limits).