@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/server/responses/request-prepare.ts

@@ -1,4 +1,8 @@
-import type { ResponsesRequestContext, ResponsesAdmissionState, ResponsesDispatchers } from "./core-options";
+import type { HandleResponsesOptions, ResponsesRequestContext, ResponsesAdmissionState, ResponsesDispatchers } from "./core-options";
+import type { PolicyRequestEvidence } from "../../routing/evaluator";
+import type { RequestLogContext } from "../request-log";
+import { markProtocolEntry, protocolMarkFeatures } from "../../protocols/trace";
+import { isAntigravityRoute } from "../antigravity-direct-eligibility";
 import { capturePolicyRequestRoute, assertPolicyNormalizedRoute, recordPolicyPreparedDestination, policyCandidateRefusalResponse } from "./policy-request-scope";
 import {
   agentTaskRecoveryConfig,
@@ -33,6 +37,7 @@ import { resolveContextPrincipal } from "../auth-cors";
 import { resolveSkillsSnapshotScopeKey, snapshotSkillsCatalogInBody } from "./skills-snapshot";
 import {
   isShadowSourceModel,
+  shadowCallPreservesSelectedModel,
   shadowSourceModelPrefix,
   shouldInterceptShadowCall,
 } from "../../lib/shadow-call";
@@ -154,6 +159,48 @@ import {
 
 import { redactHostedImageDisplayPaths } from "../responses-hosted-image-display";
 
+/** Policy-routing evidence. The direct lane's settings-only body has no conversation to scan. */
+function routeEvidence(options: Pick<HandleResponsesOptions, "directRequest">, parsed: OcxParsedRequest): PolicyRequestEvidence {
+  return options.directRequest?.evidence ?? evidenceFromBody(parsed._rawBody);
+}
+
+/**
+ * Leave the Antigravity direct lane for this request: put the bridge conversation back on the
+ * Responses body so every `_rawBody` reader sees what the bridge would have sent, and trace the
+ * request as the bridge. The IR conversation already decoded stays: it equals what
+ * `parseRequest` builds from the restored body (`tests/protocols/chat-ir-parity.test.ts`).
+ */
+function restoreDirectRequestConversation(options: HandleResponsesOptions, body: unknown, logCtx: RequestLogContext): void {
+  const direct = options.directRequest;
+  if (!direct) return;
+  options.directRequest = undefined;
+  if (body && typeof body === "object" && !Array.isArray(body)) Object.assign(body, direct.bridgeConversation());
+  if (options.clientEncoder) options.clientEncoder = { ...options.clientEncoder, requestLane: "bridge" };
+  markProtocolEntry(logCtx, {
+    inbound: direct.protocol,
+    lane: "bridge",
+    reasonCodes: ["not-migrated"],
+    features: protocolMarkFeatures(logCtx) ?? [],
+  });
+}
+
+/**
+ * Leave the direct lane as soon as the route stops being the Antigravity route it was decided
+ * for. Called after every route assignment, so readers that run between a reroute and dispatch
+ * (canonical sanitization, ciphertext stripping, final normalization) see the bridge body.
+ */
+function leaveDirectLaneIfRerouted(
+  options: HandleResponsesOptions,
+  route: Pick<RouteResult, "providerName" | "modelId" | "provider">,
+  parsed: OcxParsedRequest,
+  logCtx: RequestLogContext,
+): void {
+  const direct = options.directRequest;
+  if (!direct) return;
+  if (route.providerName === direct.providerName && route.modelId === direct.modelId && isAntigravityRoute(route)) return;
+  restoreDirectRequestConversation(options, parsed._rawBody, logCtx);
+}
+
 /** Parses, selects, and admits one request without changing the dispatch policy. */
 export async function prepareResponsesRequest(
   requestContext: Pick<ResponsesRequestContext, "options" | "config" | "req" | "logCtx">,
@@ -275,10 +322,11 @@ export async function prepareResponsesRequest(
     }
   }
   let shadowCallIntercepted = false;
-  // A spawned sub-agent turn names its model on purpose; gpt-6-luna is both the helper
-  // slug and a default sub-agent model, so neither intercept site may rewrite that turn.
+  // Luna is also selectable by users/children. Both intercept sites use the same
+  // per-turn provenance; WS frames must not inherit the handshake's classification.
   const threadSpawn = isThreadSpawnRequest(req.headers);
-  if (!concreteSelection && !options.compactionRoutingOverride && !options.internalDecisionCall && !threadSpawn && !memoryModelApplies && body && typeof body === "object" && !Array.isArray(body)) {
+  const preserveShadowModel = shadowCallPreservesSelectedModel(body, req.headers, options.inboundTransport);
+  if (!concreteSelection && !options.compactionRoutingOverride && !options.internalDecisionCall && !preserveShadowModel && !memoryModelApplies && body && typeof body === "object" && !Array.isArray(body)) {
     const shadowIntercept = config.shadowCallIntercept;
     const rawShadowModel = (body as { model?: unknown }).model;
     if (shadowIntercept?.enabled && shadowIntercept.model && typeof rawShadowModel === "string"
@@ -304,6 +352,9 @@ export async function prepareResponsesRequest(
   }
   if (comboId && Object.hasOwn(config.combos ?? {}, comboId)) {
     options.onRequestBodyRead?.();
+    // The Antigravity direct lane is decided for one concrete route; a body that reached a combo
+    // goes through the combo's own child loop with the full bridge conversation.
+    restoreDirectRequestConversation(options, body, logCtx);
     return requestDispatchers.handleComboResponses(req, body, comboId, config, logCtx, {
       ...options,
       // Concrete combo child selectors no longer match the shadow source model. Carry the
@@ -381,6 +432,10 @@ export async function prepareResponsesRequest(
   let toolBridgeMaps: ReturnType<typeof buildToolBridgeMaps>;
   try {
     parsed = parseRequest(body);
+    // Antigravity direct lane: the body carried only the request settings, so the parse above
+    // produced them with an empty conversation; the conversation itself comes straight from the
+    // client body. Inside this try so a decode error answers exactly like a parse error.
+    if (options.directRequest) parsed = options.directRequest.decode(parsed);
     if (options.inboundWire === "anthropic") {
       parsed._nativeReasoningReplay = options.nativeReasoningReplay;
       parsed._nativeReasoningMint = options.nativeReasoningMint;
@@ -580,8 +635,8 @@ export async function prepareResponsesRequest(
       const resolved = concreteSelection
         ? routeConcreteModel(config, modelId)
         : parsed._compactionRequest === true
-          ? routeCompactionModel(config, modelId, evidenceFromBody(parsed._rawBody))
-          : routeModel(config, modelId, evidenceFromBody(parsed._rawBody));
+          ? routeCompactionModel(config, modelId, routeEvidence(options, parsed))
+          : routeModel(config, modelId, routeEvidence(options, parsed));
       // A Pool 2 selector may leave Pool 2 only through an operator-configured cross-provider
       // blocked-model redirect, which the router marks as a credential-domain rewrite. Any other
       // destination means the selector fell through to default resolution, which stays refused.
@@ -613,7 +668,7 @@ export async function prepareResponsesRequest(
     }
     const _sci = config.shadowCallIntercept;
     let shadowRoute: RouteResult | undefined;
-    if (!concreteSelection && !memoryRoute && !options.memoryModelPhase && !options.compactionRoutingOverride && !options.internalDecisionCall && !threadSpawn && _sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
+    if (!concreteSelection && !memoryRoute && !options.memoryModelPhase && !options.compactionRoutingOverride && !options.internalDecisionCall && !preserveShadowModel && _sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
       const sourcePrefix = shadowSourceModelPrefix(parsed.modelId, _sci.sourceModels)!;
       let sourceIdentity = { providerName: OPENAI_CODEX_PROVIDER_ID, modelId: sourcePrefix };
       try {
@@ -652,6 +707,7 @@ export async function prepareResponsesRequest(
     if (parsed._compactionRequest === true || options.compactionRoutingOverride) parsed._cursorIsolateConversation = true;
     route = memoryRoute ?? shadowRoute ?? resolveRoute(options.policyFallbackCandidate
       ? `${options.policyFallbackCandidate.provider}/${options.policyFallbackCandidate.model}` : parsed.modelId);
+    leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
     // Name the phase in the persisted route decision, so the request log says why this turn went to
     // the memory destination instead of leaving it looking like a plain user selection. Set here, on
     // the resolved route, so a combo child's own route carries it too.
@@ -891,8 +947,9 @@ export async function prepareResponsesRequest(
     if (fallback?.to && !slugsEquivalent(fallback.to, route.modelId)) {
       try {
         route = captureInboundRoutePolicy(
-          routeModel(config, fallback.to, evidenceFromBody(parsed._rawBody)),
+          routeModel(config, fallback.to, routeEvidence(options, parsed)),
         );
+        leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
         credentialDomainWasRewritten = true;
         logCtx.routeDecision = route.routeDecision;
         logCtx.policyEligibility = route.policyEligibility;
@@ -1107,8 +1164,9 @@ export async function prepareResponsesRequest(
           if (fallback?.to && !slugsEquivalent(fallback.to, route.modelId)) {
             try {
               route = captureInboundRoutePolicy(
-                routeModel(config, fallback.to, evidenceFromBody(parsed._rawBody)),
+                routeModel(config, fallback.to, routeEvidence(options, parsed)),
               );
+              leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
               credentialDomainWasRewritten = true;
               logCtx.routeDecision = route.routeDecision;
               logCtx.policyEligibility = route.policyEligibility;
@@ -1255,6 +1313,8 @@ export async function prepareResponsesRequest(
   // for streaming clients.
   const clientRequestedStream = parsed.stream;
   const admittedPolicyRoute = { providerName: route.providerName, modelId: route.modelId };
+  // Final guard before normalization may inject guidance into the raw body.
+  leaveDirectLaneIfRerouted(options, route, parsed, logCtx);
   await applyFinalRouteRequestNormalization({
     parsed,
     route,
@@ -1450,6 +1510,11 @@ export async function prepareResponsesRequest(
   commitSkillsSnapshot?.();
   return {
     inboundWire,
+    clientDeclaredEmptyToolCatalog: options.clientDeclaredEmptyToolCatalog === true,
+    // Admission facts later route rewrites must not re-derive: the selector the caller sent and
+    // the key scope as it stood when this request was admitted.
+    inboundSelector,
+    admissionScope,
     translatorBudget,
     parsed,
     toolBridgeMaps,

package/src/server/responses/request-transport.ts

@@ -1,4 +1,5 @@
 import { SendBudgetExhaustedError } from "../../lib/upstream-retry";
+import { anthropicBillingPhysicalFetch } from "../../providers/anthropic-billing-ownership";
 import { rebindPhysicalSend } from "../../lib/request-execution-budget";
 import { anthropicModelQuotaFor } from "../../oauth/anthropic-model-quota";
 import { anthropicRatePolicyFor } from "../../oauth/anthropic-rate-limit-policy";
@@ -55,6 +56,11 @@ import { stampOAuthAccountLabel, usesApiKeyAccount } from "../../providers/label
 import { resolveProviderTransport } from "../../providers/xai-transport";
 import { captureRouteStaticPolicy } from "../../router";
 import { CopilotAutoHttpError, resolveCopilotAuto } from "../../providers/github-copilot-auto";
+import {
+  AdmissionModelDeniedError,
+  admissionModelDeniedResponse,
+  assertRouteAllowedByScope,
+} from "../admission-model-scope";
 import { renameRoutedIdentityInContext } from "../../adapters/identity";
 import { resolveCopilotApiBaseUrl } from "../../oauth/github-copilot";
 import {
@@ -87,7 +93,7 @@ import {
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { bindAttemptDeliveryRecorder } from "../../usage/attempt-delivery";
 import { resolvePassiveRouteSubjectId } from "../passive-route-linker";
-import { clientCancelledResponse } from "./core-errors";
+import { anthropicPoolCooldownResponse, clientCancelledResponse } from "./core-errors";
 import { acquireAccountLease, KIRO_ACCOUNT_WAIT_MS } from "../../oauth/kiro-account-load";
 
 /** Return a renewed Chat wire to the native owner before sending inference. */
@@ -108,6 +114,8 @@ export async function prepareResponsesTransport(
     | "inboundWire"
     | "selectedForwardHeaders"
     | "translatorBudget"
+    | "inboundSelector"
+    | "admissionScope"
   >,
 ) {
   const { config, logCtx, options, req } = requestContext;
@@ -296,6 +304,7 @@ export async function prepareResponsesTransport(
   const copilotRequestedModel = route.modelId;
   /** Project only bounded Copilot refusal metadata; upstream bodies and session tokens never reach the client. */
   const copilotRefusalResponse = (error: unknown): Response | undefined => {
+    if (error instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(error);
     if (!(error instanceof CopilotAutoHttpError) || ![401, 403, 429].includes(error.status)) return;
     const response = formatErrorResponse(error.status, error.status === 429 ? "rate_limit_error" : "authentication_error",
       error.message);
@@ -356,6 +365,13 @@ export async function prepareResponsesTransport(
       replayOAuthCredentialSnapshot = { accountId: refreshed.accountId, generation: refreshed.generation };
       selected = await negotiate();
     }
+    assertRouteAllowedByScope(
+      // The scope captured at admission: a key edited or removed while negotiation was in
+      // flight must not widen this request. The refusal names the caller's own selector.
+      requestState.admissionScope,
+      requestState.inboundSelector,
+      { providerName: route.providerName, modelId: selected.modelId },
+    );
     copilotSessionExpiresAt = selected.expiresAt ?? Infinity;
     route.provider = selected.provider;
     route.modelId = selected.modelId;
@@ -697,7 +713,7 @@ export async function prepareResponsesTransport(
             }
             commitKeyAttemptSend();
             response = await sendWithConnectionPolicy(
-              fetchImpl,
+              anthropicBillingPhysicalFetch(fetchImpl, route.providerName, route.provider),
               destination,
               { ...dispatchInit, redirect: "manual" },
               { providerName: route.providerName, provider: route.provider },
@@ -724,6 +740,7 @@ export async function prepareResponsesTransport(
         let nextAdapter: ProviderAdapter;
         try { nextAdapter = await refreshDispatchAdapter(requestParsed); }
         catch (error) {
+          if (error instanceof AdmissionModelDeniedError) throw error;
           const refusal = copilotRefusalResponse(error);
           if (refusal) return refusal;
           throw error;
@@ -784,12 +801,9 @@ export async function prepareResponsesTransport(
           // Route names may resemble account IDs; log only the matched rule position.
           if (anthropicRouteDecision) console.warn(`[${anthropicInstance}-pool] route:#${anthropicRouteDecision.position} ${selection.reason}; answering locally`);
           if (selection.reason === "all-cooled") {
-            const retryAfterSec = anthropicRouting!.getAnthropicPoolRetryAfterSeconds(Date.now(), anthropicRouteDecision, route.modelId);
-            return formatErrorResponse(
-              429,
-              "rate_limit_error",
-              anthropicRouteDecision ? "Anthropic OAuth accounts for this model route are temporarily rate-limited" : "All Anthropic OAuth accounts are temporarily rate-limited",
-              retryAfterSec !== null ? { retryAfter: String(retryAfterSec) } : undefined,
+            return anthropicPoolCooldownResponse(
+              anthropicRouting!.anthropicPoolCooldownError(Date.now(), anthropicRouteDecision, route.modelId),
+              { comboAttempt: options.comboAttempt, logCtx },
             );
           }
           return formatErrorResponse(401, "authentication_error", anthropicRouteDecision ? "No eligible Anthropic OAuth account for this model route" : "No eligible Anthropic OAuth account available");

package/src/server/responses/run-turn-execution.ts

@@ -23,6 +23,7 @@ import { normalizeLogConversationId } from "../request-log-conversation";
 import { normalizeDeclaredToolName, type AdapterEvent, type OcxProviderContinuationState } from "../../types";
 import { adapterFailureFromMessage, SEND_BUDGET_EXHAUSTED_CODE, SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE, type OcxErrorPayload } from "../../lib/errors";
 import { SendBudgetExhaustedError, markResponseNonReplayable } from "../../lib/upstream-retry";
+import { hasKeyPoolFailover, rotateProviderTransportOn401, rotateProviderTransportOn429 } from "../../providers/key-failover";
 import {
   hasEligibleGenericOAuthFailoverTarget,
   isGenericOAuthFailoverEnabled,
@@ -224,6 +225,11 @@ export async function executeResponsesRunTurn(
     // in-flight; only the latest dispatch may merge adapter-written route
     // state back onto `parsed`, or the superseded attempt would restore the
     // failed account's cursor/continuation over the rotation's rebind.
+    type KeyBinding = Extract<NonNullable<ReturnType<typeof adapterBindings.get>>, { kind: "api-key" }>;
+    const failedKeyBindings = new WeakMap<Extract<AdapterEvent, { type: "error" }>, KeyBinding>();
+    const failedKeys = new Set<string>();
+    const keyAttemptLimit = route.provider.apiKeyPool?.length ?? 0;
+    let lastKeyFailure: Extract<AdapterEvent, { type: "error" }> | undefined;
     let runTurnAttemptSeq = 0;
     const runTurnAttempt = async (
       targetQueue: AdapterEventQueue,
@@ -238,7 +244,9 @@ export async function executeResponsesRunTurn(
       const attemptSeq = ++runTurnAttemptSeq;
       if (attemptSeq === 1 && options.comboInitialSend) options.comboInitialSend.producerOwned = true;
       let pacingSlot = preacquiredSlot;
+      let sentKeyBinding: KeyBinding | undefined;
       const emit = (event: AdapterEvent) => {
+        if (event.type === "error" && sentKeyBinding) failedKeyBindings.set(event, sentKeyBinding);
         options.onCompactionRecoveryAdapterEvent?.(event);
         targetQueue.push(event);
       };
@@ -249,6 +257,12 @@ export async function executeResponsesRunTurn(
           pacingSlot = await waitForProviderRequestSlot(route.providerName, route.provider, route.modelId, runTurnAbort.signal);
         }
         await refreshRunTurnSelection();
+        const selectedBinding = adapterBindings.get(transportState.runTurnAdapter);
+        if (lastKeyFailure && selectedBinding?.kind === "api-key"
+          && failedKeys.has(selectedBinding.provider.apiKey ?? "")) {
+          emit(lastKeyFailure);
+          return;
+        }
         // LOCAL PATCH (runturn-websearch): refreshRunTurnSelection binds route
         // state onto `parsed`; mirror it onto the iteration-local copy the
         // adapter actually receives.
@@ -293,13 +307,14 @@ export async function executeResponsesRunTurn(
             // The only way the request budget reaches a transport the adapter owns. Without it
             // a Cursor turn's inner ladder was three physical sends the cap read as one.
             ...(adapterDispatchBudget ? { sendBudget: adapterDispatchBudget } : {}),
-            onPhysicalSend: send => noteAdapterPhysicalSend(
-              logCtx.usageLogInputTokens,
-              // The attempt's own recovery kind still labels its first send when the adapter
-              // does not supply one of its own.
-              { ...send, ...(send.recovery ?? recovery ? { recovery: send.recovery ?? recovery } : {}) },
-              { includeFirst: reportsOwnSends },
-            ),
+            onPhysicalSend: send => {
+              // Capture once at this attempt's send, before later selection or recovery changes it.
+              const binding = adapterBindings.get(transportState.runTurnAdapter);
+              if (!sentKeyBinding && binding?.kind === "api-key") sentKeyBinding = binding;
+              noteAdapterPhysicalSend(logCtx.usageLogInputTokens,
+                { ...send, ...(send.recovery ?? recovery ? { recovery: send.recovery ?? recovery } : {}) },
+                { includeFirst: reportsOwnSends });
+            },
             onRecoveryWithheld: noteAdapterRecoveryWithheld,
           },
           emit,
@@ -361,6 +376,7 @@ export async function executeResponsesRunTurn(
     const runTurn = async (): Promise<void> => runTurnAttempt(queue, undefined, true, wsFirstParsed, initialPacingSlot);
     const runTurnFailoverArmed = () =>
       route.provider.authMode === "oauth"
+      || (transportState.runTurnAdapter.name === "qoder" && hasKeyPoolFailover(route.provider))
       || !!(transportState.genericFailoverAccountId
         && isGenericOAuthFailoverEnabled(config, route.providerName));
     const dispatchSearchIteration = (iterParsed: PreparedResponsesRequest["parsed"]): AsyncIterable<AdapterEvent> => {
@@ -464,9 +480,51 @@ export async function executeResponsesRunTurn(
         return false;
       }
     };
+    const recoverRunTurnKey = async (
+      error: Extract<AdapterEvent, { type: "error" }>,
+    ): Promise<AttemptRecoveryKind | undefined> => {
+      const binding = failedKeyBindings.get(error);
+      if (error.apiKeyRecovery !== true || (error.status !== 401 && error.status !== 429)
+        || !binding || runTurnAbort.signal.aborted || !hasKeyPoolFailover(route.provider)
+        || failedKeys.size >= keyAttemptLimit) return undefined;
+      const failed = binding.provider;
+      if (!failed.apiKey || !failed._apiKeyAttempt || failedKeys.has(failed.apiKey)) return undefined;
+      const hop = reserveCredentialHop("auth-recovery", `${route.providerName}|${route.modelId}|runturn-key-${error.status}`);
+      if (!hop.allowed) return undefined;
+      failedKeys.add(failed.apiKey);
+      lastKeyFailure = error;
+      try {
+        const rotate = error.status === 401 ? rotateProviderTransportOn401 : rotateProviderTransportOn429;
+        const rotated = rotate(config, route.providerName, failed, {
+          attemptedKey: failed.apiKey, attemptedSelection: failed._apiKeyAttempt,
+          promptCacheKey: parsed.options.promptCacheKey,
+        });
+        if (!rotated || failedKeys.size >= keyAttemptLimit || failedKeys.has(rotated.apiKey ?? "") || runTurnAbort.signal.aborted) {
+          hop.permit?.release();
+          return undefined;
+        }
+        route.provider = rotated;
+        const adapter = await refreshRunTurnAdapter(parsed);
+        if (!adapter.runTurn || failedKeys.has(route.provider.apiKey ?? "") || runTurnAbort.signal.aborted) {
+          hop.permit?.release();
+          return undefined;
+        }
+        bindRouteReasoningReplayScope({ parsed, providerName: route.providerName, provider: route.provider,
+          adapterName: adapter.name, forwardHeaders: requestState.selectedForwardHeaders });
+        sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, adapter.name, logCtx.accountLogLabel);
+        recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, adapter.name);
+        sendBudgetState.pendingHopPermit = hop.permit;
+        return error.status === 401 ? "key-401" : "key-429";
+      } catch {
+        hop.permit?.release();
+        return undefined;
+      }
+    };
     const recoverRunTurnAdapterOnPreflightError = async (
       error: Extract<AdapterEvent, { type: "error" }>,
     ): Promise<AttemptRecoveryKind | undefined> => {
+      const keyRecovery = await recoverRunTurnKey(error);
+      if (keyRecovery) return keyRecovery;
       if (await recoverRunTurnAdapterOnPreflight401(error)) return "oauth-401";
       if (await rotateRunTurnAdapterOnPreflight429(error)) return "oauth-account-429";
       return undefined;
@@ -683,7 +741,11 @@ export async function executeResponsesRunTurn(
       const stallTimeoutSec = wsPlan?.stallTimeoutSec ?? config.stallTimeoutSec;
       // A disabled watchdog (0) is not a zero preflight: it would commit SSE before Devin's first
       // event and deliver a pre-output 429 in-stream. Fall back to the default finite bound.
-      const preflightDeadlineAt = grokDevinPreflight
+      // A key-pool preflight must not outlast the stall budget, or a silent CLI holds the SSE
+      // Response (heartbeats, stall watchdog) hostage; the OAuth preflight wait is unchanged.
+      const keyPoolPreflight = transportState.runTurnAdapter.name === "qoder"
+        && route.provider.authMode !== "oauth" && hasKeyPoolFailover(route.provider);
+      const preflightDeadlineAt = grokDevinPreflight || keyPoolPreflight
         ? Date.now() + (resolveStallTimeoutSec(stallTimeoutSec) || DEFAULT_STALL_TIMEOUT_SEC) * 1_000
         : undefined;
       if (runTurnFailoverArmed()) {

package/src/server/responses/sidecar-execution.ts

@@ -7,6 +7,9 @@ import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
 import { formatErrorResponse } from "../../bridge";
 import { planWebSearch, buildWebSearchTool, runWithWebSearch } from "../../web-search";
+import { createRegisteredAdvisorPlan } from "./advisor-plan-slot";
+import { ADVISOR_TOOL_NAME } from "./advisor-slot";
+import { buildToolBridgeMaps } from "./collaboration";
 import {
   planImageBridge,
   planVideoBridge,
@@ -30,9 +33,11 @@ import {
 } from "../../oauth/generic-account-failover";
 import { classifyKiroRefusal } from "../../adapters/kiro-refusal";
 import { isNonReplayableResponse } from "../../lib/upstream-retry";
+import { unwrapUpstreamRetryEvidenceError } from "../../codex/auth-context";
+import { AdmissionModelDeniedError, admissionModelDeniedResponse } from "../admission-model-scope";
 import { noteKiroMonthlyRefusal, noteKiroServedSuccess } from "../../providers/kiro-usage";
 import { persistKiroAccountState } from "../../providers/kiro-account-state-disk";
-import { readDisplaySafeErrorText } from "./core-errors";
+import { anthropicPoolCooldownResponse, readDisplaySafeErrorText } from "./core-errors";
 import {
   ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST,
   anthropicRoutingFor,
@@ -60,6 +65,7 @@ export async function executeResponsesSidecars(
     | "inboundWire"
     | "selectedForwardHeaders"
     | "translatorBudget"
+    | "toolBridgeMaps"
     | "rememberKiroDeliveredFinalAnswer"
     | "responseStateOptions"
   >,
@@ -169,6 +175,25 @@ export async function executeResponsesSidecars(
     }
   }
 
+  // Advisor sidecar plan (optional subsystem; null when disabled, unconfigured, or when this
+  // request IS an advisor loopback consultation — the recursion fence). The plan carries
+  // request-scoped state only; preflight keeps fixed policy separate from user-role advice
+  // before the worker is dispatched. Registration seam: the core path sees only
+  // `parsed._advisorGuard`; only an activated factory can load the optional implementation.
+  const advisorPlan = options.advisorInternal === true
+    ? null
+    : await createRegisteredAdvisorPlan({
+      config,
+      workerIdentity: `${route.modelId} (provider ${route.providerName})`,
+      workerModelId: route.modelId,
+      abortSignal: options.abortSignal,
+    });
+  // Preflight only on real worker turns: a routed-compaction turn is a summarization request,
+  // and injecting advice into it would pollute the summary Codex replaces its history with.
+  if (advisorPlan && !routedCompaction) {
+    await advisorPlan.preflightInject(parsed);
+  }
+
   // Image / web-search sidecars: plan once, then dispatch with runTurn-aware priority.
   // Routed-compaction turns must NOT hit the image bridge: compaction clears tools/_webSearch but
   // leaves _imageGeneration, so planImageBridge would activate and return a normal Responses
@@ -198,6 +223,20 @@ export async function executeResponsesSidecars(
   // A single request may rotate once for a verification refusal. Keep this separate from the
   // broader OAuth failover count: a sidecar turn can also spend that count on rate-limit recovery.
   let antigravityValidationRotationAttempted = false;
+  // A replacement credential whose Copilot Auto negotiation leaves the key's scope ends the turn.
+  // The loops only see "no rotation" and fail with the original, replayable 429, so the refusal
+  // is held here and answers in place of that failure.
+  let sidecarScopeDenial: AdmissionModelDeniedError | undefined;
+  const noteSidecarScopeDenial = (error: unknown): void => {
+    const refusal = unwrapUpstreamRetryEvidenceError(error);
+    if (refusal instanceof AdmissionModelDeniedError) sidecarScopeDenial ??= refusal;
+  };
+  const sidecarScopeRefusal = (response: Response): Response | undefined => {
+    if (!sidecarScopeDenial || response.ok) return undefined;
+    void response.body?.cancel().catch(() => {});
+    releaseSearchProbeLease();
+    return admissionModelDeniedResponse(sidecarScopeDenial);
+  };
   /** Admit a replacement credential, or leave the loop's original refusal authoritative. */
   const rotateSidecarProviderOn429 = async (
     retryAfter: string | null,
@@ -264,7 +303,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -284,7 +324,10 @@ export async function executeResponsesSidecars(
     } else if (rotated) {
       route.provider = rotated;
       try { await resolveCopilotSelection(retryParsed ?? parsed); }
-      catch { return null; } // Keep the sidecar's original refusal when replacement negotiation fails.
+      catch (error) { // Keep the sidecar's original refusal when replacement negotiation fails.
+        noteSidecarScopeDenial(error);
+        return null;
+      }
     } else if (
       // A POSITIVE gate, not an early return. An early `return null` here made every later arm
       // unreachable: Anthropic never has a genericFailoverAccountId (isGenericFailoverProvider
@@ -326,7 +369,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         if (route.providerName === "kiro") transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -527,6 +571,8 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const imgScopeRefusal = sidecarScopeRefusal(imgResponse);
+    if (imgScopeRefusal) return imgScopeRefusal;
     if (imgResponse.body) {
       const imgTurnAc = new AbortController();
       imgTurnAc.signal.addEventListener("abort", cancelResponseCompletion, { once: true });
@@ -555,7 +601,7 @@ export async function executeResponsesSidecars(
         modelId: route.modelId,
         ...sidecarBudget.fetchOptions(transportState.adapter),
       })(input, init)) as typeof globalThis.fetch;
-    const wsResponse = await runWithWebSearch({
+    const loopResponse = await runWithWebSearch({
       parsed, adapter: transportState.adapter,
       onIterationEnd: sidecarBudget.releaseUnsentHop,
       fetchForRequest: (request, iterParsed, adapter) => providerFetch(route.provider, options.codexWsRuntimeIdentity, {
@@ -622,6 +668,17 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const wsScopeRefusal = sidecarScopeRefusal(loopResponse);
+    if (wsScopeRefusal) return wsScopeRefusal;
+    // A routed Anthropic model whose last pool account refused on spent quota fails the loop's
+    // first iteration with a generic 429 before any search runs. Answer the usage limit instead,
+    // as the main path does (#6991), so Codex stops rather than retrying the whole turn.
+    const poolUsageLimit = loopResponse.status === 429 && anthropicInstance && route.provider.authMode === "oauth"
+      && !options.comboAttempt
+      ? anthropicRoutingFor(anthropicInstance).anthropicPoolUsageLimitAfterRefusal(Date.now(), transportState.anthropicRouteDecision, route.modelId)
+      : null;
+    if (poolUsageLimit) void loopResponse.body?.cancel().catch(() => {});
+    const wsResponse = poolUsageLimit ? anthropicPoolCooldownResponse(poolUsageLimit, { logCtx }) : loopResponse;
     // Register the sidecar stream as an active turn so drainAndShutdown waits for (or aborts)
     // in-flight web-search turns instead of skipping them during graceful shutdown.
     if (wsResponse.body) {
@@ -636,5 +693,32 @@ export async function executeResponsesSidecars(
     return wsResponse;
   }
 
+  // Advisor synthetic tool + stream guard: attach ONLY when this function is about to hand the
+  // request back to the normal translated exchange (no sidecar loop claimed the turn, not a
+  // run-turn adapter, not compaction). The web-search/image loops own their own event handling;
+  // run-turn adapters execute their own loop; both would leak the synthetic tool call they
+  // cannot intercept. Preflight (above) still applies to those paths — only the tool does not.
+  if (advisorPlan && !routedCompaction && !transportState.adapter.runTurn && !wsPlan && !imgPlan && !vidPlan) {
+    // A client-declared tool named "advisor" would collide with the synthetic injection (one
+    // wire name, two schemas); the synthetic runtime owns the name for this turn.
+    parsed.context.tools = [
+      ...(parsed.context.tools ?? []).filter(t => !t.advisor && t.name !== ADVISOR_TOOL_NAME),
+      advisorPlan.tool,
+    ];
+    // The advisor tool joined AFTER prepare computed the bridge maps; recompute so the tool is
+    // declared (undeclared-tool guard, tool_choice mapping, schema repair) on this turn.
+    //
+    // Rebuild WITHOUT the budget: prepare already charged every tool in the catalog, and
+    // buildToolBridgeMaps charges each name it registers, so re-passing the budget would bill the
+    // whole catalog a second time and can trip `translation_buffer_limit` for a large MCP catalog.
+    // Charge only the one entry that is genuinely new — the synthetic advisor tool is a bare
+    // function tool, so it retains its wire name and its bare name (collaboration.ts:187, :233).
+    requestState.toolBridgeMaps = buildToolBridgeMaps(parsed);
+    translatorBudget.chargeRetained(new TextEncoder().encode(ADVISOR_TOOL_NAME).byteLength * 2, {
+      kind: "retained_collectors",
+    });
+    advisorPlan.attachGuard(parsed);
+  }
+
   return undefined;
 }

package/src/server/responses/terminal-guard.ts

@@ -170,7 +170,8 @@ export function isTerminalGuardPassthroughOnly(event: AdapterEvent): boolean {
   return event.type === "heartbeat" || event.type === "tool_call_delta";
 }
 
-function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+/** Merge two reported usages (canonical Responses convention). Shared with the advisor guard. */
+export function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
   if (!first) return second;
   if (!second) return first;
   const sumOptional = (key: keyof OcxUsage): number | undefined => {

package/src/server/responses/ws-upstream.ts

@@ -23,8 +23,9 @@ import { CODEX_RESPONSES_HTTP_URL, CODEX_RESPONSES_WS_URL, CODEX_WS_FRAME_HEADER
 import { codexWsExchange } from "./codex-ws-exchange";
 import { CodexWsSession } from "./codex-ws-session";
 import { codexWsPool, codexWsReuseIdentity } from "./codex-ws-pool";
-import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
+import { codexWsCreateFrameExceedsLimit, type CodexWsPreOutputRefusalHold } from "./codex-ws-wire";
 import { isLoopbackUrl, rewriteWebSocketDial } from "../../plugins/upstream-hooks";
+import { outboundCredentials } from "../../lib/outbound-credential-registry";
 export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
   MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
   isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse, isCodexWsPreludeProjection } from "./codex-ws-wire";
@@ -162,6 +163,8 @@ export async function codexWsUpstreamFetch(
   nativeControl?: NativeResponseControl,
   beforeContinuation?: () => Promise<void>,
   onPhysicalDispatch?: () => void,
+  /** Opt-in pre-output refusal hold (#6969); see codexWsExchange. */
+  preOutputRefusalHold?: CodexWsPreOutputRefusalHold,
 ): Promise<Response> {
   const prepared = prepareCodexWsRequest(url, init);
   if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
@@ -221,6 +224,10 @@ export async function codexWsUpstreamFetch(
     // reused for a different destination or with stale plugin headers.
     const dial = planCodexWsDial(wsUrl, headers, proxy);
     if (!dial) return sseFallback(url, init);
+    // The final dial headers, after plugin rewrites, are what the WebSocket upstream receives; the
+    // per-turn headers planning drops from the upgrade still reach it inside the frame metadata.
+    outboundCredentials().remember(headers);
+    outboundCredentials().remember(dial.headers);
     const identity = control ? null : codexWsReuseIdentity(url, dial.headers, frameText, dial.proxy, dial.url);
     const reuseAcrossTurns = identity !== null && codexWsReuseAcrossTurnsEnabled();
     const pooled = identity
@@ -243,6 +250,7 @@ export async function codexWsUpstreamFetch(
     session, url, init, prepared, sseFallback, onQuota, beforeDispatch,
     nativeControl: control,
     beforeContinuation, onPhysicalDispatch,
+    preOutputRefusalHold,
     bunVersion: typeof runtime === "string" ? runtime : runtime.version,
   });
 }