@bitkyc08/opencodex 2.80.0 → 2.81.0

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

@@ -1,4 +1,4 @@
-import { rotateAnthropicAccountOnResponse } from "../../oauth/anthropic-account-refusal";
+import { rotateAnthropicAccountOnResponseForInstance } from "../../oauth/anthropic-account-refusal";
 import type { ResponsesRequestContext } from "./core-options";
 import type { PreparedResponsesRequest } from "./request-prepare";
 import type { ResponsesTransport } from "./request-transport";
@@ -24,20 +24,22 @@ import {
   isGenericOAuthFailoverEnabled,
   rotateGenericOAuthAccountOn429,
   rotateGenericOAuthAccountOnRefusal,
+  rotateAntigravityAccountOnAuthRefusal,
   quarantineKiroSuspendedAccount,
   failoverAccountSnapshot,
 } from "../../oauth/generic-account-failover";
 import { classifyKiroRefusal } from "../../adapters/kiro-refusal";
+import { isNonReplayableResponse } from "../../lib/upstream-retry";
 import { noteKiroMonthlyRefusal, noteKiroServedSuccess } from "../../providers/kiro-usage";
 import { persistKiroAccountState } from "../../providers/kiro-account-state-disk";
 import { readDisplaySafeErrorText } from "./core-errors";
 import {
   ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST,
-  getAnthropicPoolAccessSnapshot,
+  anthropicRoutingFor,
   formatAnthropicProviderForLog,
 } from "../../oauth/anthropic-routing";
 import { resolveWireProtocolOverride } from "../adapter-resolve";
-import { bindRouteReasoningReplayScope, adapterNeedsForcedContinuation } from "./core-replay";
+import { bindRouteReasoningReplayScope, adapterNeedsForcedContinuation, adapterNeedsToolCallContinuation } from "./core-replay";
 import { namespacedToolName } from "../../types";
 import { providerFetch } from "./fetch-helpers";
 import type { AttemptRecoveryKind } from "../../usage/log";
@@ -45,6 +47,7 @@ import { recordAdapterReasoning, recordAdapterTier } from "../request-log";
 import { normalizeLogConversationId } from "../request-log-conversation";
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
+import { isAntigravityRawValidationRefusal } from "./antigravity-validation-refusal";
 
 /** One responsibility of the Responses request pipeline; state owners are explicit. */
 export async function executeResponsesSidecars(
@@ -67,6 +70,8 @@ export async function executeResponsesSidecars(
     | "genericFailoverLimit"
     | "replayOAuthCredentialSnapshot"
     | "applyFailoverSnapshot"
+    | "anthropicInstance"
+    | "currentAnthropicRouteDecision"
     | "anthropicRouteDecision"
     | "anthropicPoolAccountId"
     | "anthropicPoolFailovers"
@@ -85,11 +90,15 @@ export async function executeResponsesSidecars(
     | "notifyResponseComplete"
     | "cancelResponseCompletion"
   >,
-  sendBudgetState: Pick<ResponsesSendBudget, "reserveCredentialHop">,
+  sendBudgetState: Pick<ResponsesSendBudget, "reserveCredentialHop" | "refundableAdapterDispatchBudget" | "pendingHopPermit" | "noteAdapterPhysicalSend">,
 ) {
   const { config, options, logCtx } = requestContext;
+  const antigravityPoolActivated = requestState.route.providerName === "google-antigravity"
+    && isGenericOAuthFailoverEnabled(config, requestState.route.providerName);
   const {
     applyFailoverSnapshot,
+    anthropicInstance,
+    currentAnthropicRouteDecision,
     anthropicSessionKey,
     commitResolvedOAuthSelection,
     resolveSelectionAdapter,
@@ -182,13 +191,29 @@ export async function executeResponsesSidecars(
     || (logCtx.activeAttempt?.deliverySummary?.semanticBytes ?? 0) > 0
     || (logCtx.activeAttempt?.deliverySummary?.sideEffectEvents ?? 0) > 0;
   const noteSidecarOutput = () => { sidecarOutputStarted = true; options.onFirstOutput?.(); };
+  // 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;
   const rotateSidecarProviderOn429 = async (
     retryAfter: string | null,
     responseHeaders?: Headers,
     retryParsed?: OcxParsedRequest,
     originalResponse?: Response,
   ): Promise<{ adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind } | null> => {
-    if (route.providerName !== "kiro" && !(route.providerName === "anthropic" && originalResponse?.status === 403) && originalResponse && originalResponse.status !== 429) return null;
+    const antigravityValidationResponse = canRunWebSearch && route.providerName === "google-antigravity"
+      && route.provider.authMode === "oauth" && originalResponse?.status === 403;
+    if (route.providerName !== "kiro" && !(anthropicInstance && originalResponse?.status === 403)
+      && !antigravityValidationResponse && originalResponse && originalResponse.status !== 429) return null;
+    let antigravityVerification = false;
+    if (antigravityValidationResponse) {
+      if (transportState.adapter.name !== "google" || !antigravityPoolActivated
+        || options.abortSignal?.aborted || isNonReplayableResponse(originalResponse)
+        || antigravityValidationRotationAttempted
+        || transportState.genericFailovers >= transportState.genericFailoverLimit
+        || sidecarHasCommittedOutput()) return null;
+      antigravityVerification = await isAntigravityRawValidationRefusal(originalResponse, options.abortSignal);
+      if (!antigravityVerification) return null;
+    }
     const refusal = route.providerName === "kiro" && originalResponse
       ? classifyKiroRefusal(originalResponse.status,
         await readDisplaySafeErrorText(originalResponse.clone(), options.abortSignal ?? new AbortController().signal, "")).kind
@@ -205,6 +230,42 @@ export async function executeResponsesSidecars(
     // sidecar loops used to flatten all three to `key-429`, so an account rotation read as a key
     // rotation in the attempt row and in the Logs UI.
     let recoveryKind: AttemptRecoveryKind = "key-429";
+    if (antigravityVerification) {
+      const sent = transportState.replayOAuthCredentialSnapshot;
+      const failedAccountId = transportState.genericFailoverAccountId;
+      if (!sent || !failedAccountId || sent.accountId !== failedAccountId) return null;
+      if (options.abortSignal?.aborted || sidecarHasCommittedOutput()) return null;
+
+      const hop = reserveCredentialHop(
+        "auth-recovery",
+        `${route.providerName}|${route.modelId}|sidecar-oauth-verify`,
+      );
+      if (!hop.allowed) return null;
+      antigravityValidationRotationAttempted = true;
+      const nextAccountId = rotateAntigravityAccountOnAuthRefusal(
+        antigravityPoolActivated, sent.accountId, sent.generation, route.modelId,
+      );
+      if (!nextAccountId) {
+        hop.permit?.release();
+        return null;
+      }
+      try {
+        // Keep the sibling's bearer and its account-matched project together; never inherit the
+        // failed account's identity or project.
+        const snapshot = await failoverAccountSnapshot(route.providerName, nextAccountId);
+        if (options.abortSignal?.aborted || !await applyFailoverSnapshot(snapshot, retryParsed)
+          || transportState.replayOAuthCredentialSnapshot?.accountId !== nextAccountId) {
+          hop.permit?.release();
+          return null;
+        }
+        transportState.genericFailovers += 1;
+      } catch {
+        hop.permit?.release();
+        return null;
+      }
+      recoveryKind = "oauth-account-403";
+      sendBudgetState.pendingHopPermit = hop.permit;
+    }
     const rotated = !originalResponse || originalResponse.status === 429
       ? rotateProviderTransportOn429(config, route.providerName, route.provider, {
       retryAfter,
@@ -212,7 +273,9 @@ export async function executeResponsesSidecars(
       attemptedKey: route.provider.apiKey,
       promptCacheKey: parsed.options.promptCacheKey,
       }) : null;
-    if (rotated) {
+    if (antigravityVerification) {
+      // `applyFailoverSnapshot` has already rebound the route to the sibling identity/project.
+    } else if (rotated) {
       route.provider = rotated;
     } else if (
       // A POSITIVE gate, not an early return. An early `return null` here made every later arm
@@ -225,7 +288,8 @@ export async function executeResponsesSidecars(
     ) {
       // Intersection with the request's shared budget. The sidecar replay is dispatched by the
       // web-search/image loop and never reaches `onSendsConsumed`, so this reservation is the
-      // charge; a refusal returns null and the caller keeps the real 429 it already has.
+      // charge for other sidecars. Antigravity web search hands its reservation to the adapter
+      // physical-send owner instead; a refusal preserves the real 429.
       const hop = reserveCredentialHop(
         "auth-recovery",
         `${route.providerName}|${route.modelId}|sidecar-oauth-429`,
@@ -259,12 +323,13 @@ export async function executeResponsesSidecars(
         return null;
       }
       recoveryKind = "oauth-account-429";
-      hop.permit?.use();
+      if (canRunWebSearch && route.providerName === "google-antigravity") sendBudgetState.pendingHopPermit = hop.permit;
+      else hop.permit?.use();
     } else if (
       // Anthropic's pool is excluded from generic failover, so without this arm a 429 inside a
       // web-search or image-bridge turn was terminal even with the pool fully enabled -- while
       // the very same 429 on the main response path rotated.
-      transportState.anthropicPoolAccountId
+      anthropicInstance && transportState.anthropicPoolAccountId
     ) {
       // Same intersection for the Anthropic roster: its own per-request bound still applies,
       // and the shared budget decides whether this request may spend another send at all.
@@ -272,10 +337,10 @@ export async function executeResponsesSidecars(
         "auth-recovery",
         `${route.providerName}|${route.modelId}|sidecar-anthropic-429`,
       );
-      const nextAccountId = await rotateAnthropicAccountOnResponse(
+      const nextAccountId = await rotateAnthropicAccountOnResponseForInstance(anthropicInstance,
         originalResponse ?? new Response(null, { status: 429, headers: responseHeaders ?? (retryAfter ? { "retry-after": retryAfter } : undefined) }), {
           config, accountId: transportState.anthropicPoolAccountId, sessionKey: anthropicSessionKey,
-          model: route.modelId, requestKey: transportState, decision: transportState.anthropicRouteDecision, signal: options.abortSignal,
+          model: route.modelId, requestKey: transportState, decision: transportState.anthropicRouteDecision, currentDecision: currentAnthropicRouteDecision, signal: options.abortSignal,
           allow429Recovery: !sidecarHasCommittedOutput(), allowAccountRefusal: !sidecarHasCommittedOutput(),
           canRetry: hop.allowed && transportState.anthropicPoolFailovers < ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST,
         });
@@ -289,12 +354,12 @@ export async function executeResponsesSidecars(
         // carries none, and getAnthropicPoolAccessToken is what enforces its fail-closed
         // local-cli credential rule. Both existing Anthropic rotation sites apply the token the
         // same way.
-        const admitted = await commitResolvedOAuthSelection(await getAnthropicPoolAccessSnapshot(nextAccountId));
+        const admitted = await commitResolvedOAuthSelection(await anthropicRoutingFor(anthropicInstance).getAnthropicPoolAccessSnapshot(nextAccountId));
         if (!admitted) throw new Error("OAuth selection changed during recovery");
         transportState.anthropicPoolAccountId = admitted.accountId;
         transportState.anthropicPoolFailovers += 1;
         route.provider = { ...route.provider, apiKey: admitted.accessToken };
-        logCtx.provider = formatAnthropicProviderForLog("anthropic", admitted.accountId, config);
+        logCtx.provider = formatAnthropicProviderForLog(anthropicInstance, admitted.accountId, config);
       } catch {
         hop.permit?.release();
         return null;
@@ -321,6 +386,7 @@ export async function executeResponsesSidecars(
         providerName: route.providerName,
         provider: route.provider,
         adapterName: rotatedAdapter.name,
+        ...(antigravityVerification ? { oauthCredentialSnapshot: transportState.replayOAuthCredentialSnapshot } : {}),
       });
     }
     bindRouteReasoningReplayScope({
@@ -328,6 +394,7 @@ export async function executeResponsesSidecars(
       providerName: route.providerName,
       provider: route.provider,
       adapterName: rotatedAdapter.name,
+      ...(antigravityVerification ? { oauthCredentialSnapshot: transportState.replayOAuthCredentialSnapshot } : {}),
     });
     return { adapter: rotatedAdapter, recoveryKind };
   };
@@ -440,7 +507,10 @@ export async function executeResponsesSidecars(
           parsed._rawBody,
           response,
           continuationStateForResponse(providerState),
-          responseStateOptions(adapterNeedsForcedContinuation(transportState.adapter.name)),
+          {
+            ...responseStateOptions(adapterNeedsForcedContinuation(transportState.adapter.name)),
+            retainForToolContinuation: adapterNeedsToolCallContinuation(transportState.adapter.name),
+          },
         );
         notifyResponseComplete(response);
       },
@@ -484,6 +554,11 @@ export async function executeResponsesSidecars(
         abortSignal: options.abortSignal,
         translatorBudget,
         providerFetch: routedProviderFetch,
+        ...(route.providerName === "google-antigravity" ? {
+          sendBudget: sendBudgetState.refundableAdapterDispatchBudget,
+          onPhysicalSend: (send: { ordinal: number; recovery?: AttemptRecoveryKind }) =>
+            sendBudgetState.noteAdapterPhysicalSend(logCtx.usageLogInputTokens, send),
+        } : {}),
       },
       backend: wsPlan.backend,
       forwardProvider: wsPlan.forwardSidecar?.provider,
@@ -516,6 +591,13 @@ export async function executeResponsesSidecars(
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       streamRoutedModelOutput: wsPlan.streamRoutedModelOutput,
       on429: rotateSidecarProviderOn429,
+      ...(route.providerName === "google-antigravity" ? { onIterationEnd: () => {
+        // The next Antigravity adapter dispatch claims this permit. If request construction,
+        // admission or cancellation stopped it first, return the unused send allowance.
+        const permit = sendBudgetState.pendingHopPermit;
+        sendBudgetState.pendingHopPermit = undefined;
+        permit?.release();
+      } } : {}),
       retryOn429Policy: route.providerName === "kiro" && isGenericOAuthFailoverEnabled(config, "kiro")
         ? null : rateLimitRetryPolicyFor(route.provider),
       onCompletedResponse: response => {

package/src/server/responses-undeclared-tool-guard.ts

@@ -703,6 +703,7 @@ function failedBlocks(name: string, newline: string): readonly string[] {
  * @param providerExecutedCallTypes - Call types executed by the provider.
  * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
  * @param declaredCustom - Current bare custom declarations eligible for code-mode recovery.
+ * @param enforceDeclaredToolNames - Refuse undeclared calls; normalization remains active when false.
  * @returns An SSE block rewrite function.
  */
 export function createUndeclaredToolCallGuardBlockRewrite(
@@ -711,6 +712,7 @@ export function createUndeclaredToolCallGuardBlockRewrite(
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
   declaredBare?: ReadonlySet<string>,
   declaredCustom?: ReadonlySet<string>,
+  enforceDeclaredToolNames = true,
 ): SseBlockRewrite {
   let tripped = false;
   return (block: string) => {
@@ -723,7 +725,9 @@ export function createUndeclaredToolCallGuardBlockRewrite(
     } catch {
       return [block];
     }
-    const name = undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom);
+    const name = enforceDeclaredToolNames
+      ? undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom)
+      : undefined;
     if (name !== undefined) {
       tripped = true;
       return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");

package/src/server/workflow-refusal.ts

@@ -1,3 +1,4 @@
+import { sharedPoolContinuityDenial } from "../lib/spend-reservation-ledger";
 /**
  * The one place that knows how this proxy refuses a turn on its own workflow budget.
  *
@@ -96,6 +97,22 @@ export function workflowRefusalResponse(
   return refusal;
 }
 
+/** Render the approved conservative-overlay explanation after a dispatch reservation refuses. */
+export function unboundPoolSpendRefusalMessage(
+  logCtx: Pick<RequestLogContext, "spendRefusalDetail">,
+): string | undefined {
+  const detail = logCtx.spendRefusalDetail;
+  if (!detail?.includesUnboundPoolHistory) return undefined;
+  return workflowDenialSummary("workflow-spend-exhausted", detail).message;
+}
+
+/** HTTP form for pre-commit send-budget catches; the tracker already recorded the event. */
+export function unboundPoolSpendRefusalResponse(logCtx: RequestLogContext): Response | undefined {
+  const detail = logCtx.spendRefusalDetail;
+  if (!detail?.includesUnboundPoolHistory) return undefined;
+  return workflowRefusalResponse("workflow-spend-exhausted", logCtx, undefined, undefined, detail);
+}
+
 /**
  * Admit one HTTP turn against its root workflow budget.
  *
@@ -104,8 +121,20 @@ export function workflowRefusalResponse(
  * children. A request that names a parent is treated as that fan-out; a top-level request is
  * the conversation and may use the reserved slots.
  */
+/** Read-only alias validation: keep replay corruption distinct from conflicting pool owners. */
+export function poolContinuityRefusalReason(): WorkflowDenial | undefined {
+  const denial = sharedPoolContinuityDenial();
+  if (!denial) return undefined;
+  return denial.reason === "pool-history-unresolved" ? "workflow-pool-history-unresolved" : "workflow-spend-undurable";
+}
+
 export function admitHttpWorkflowTurn(headers: Headers): WorkflowDecision | undefined {
   const rootId = headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const continuityRefusal = poolContinuityRefusalReason();
+  if (continuityRefusal) {
+    recordWorkflowRefusalEvent(rootId, continuityRefusal);
+    return { admitted: false, reason: continuityRefusal, rootId: rootId ?? "" };
+  }
   const threadId = headers.get("thread-id")?.trim() || undefined;
   const lane: WorkflowLane = rootId !== undefined && threadId !== undefined && threadId !== rootId
     ? "worker"
@@ -132,6 +161,7 @@ export function workflowDecisionRefusalResponse(
       scope: decision.spendScope,
       limit: decision.spendLimit,
       ...(decision.spendProjected !== undefined ? { projected: decision.spendProjected } : {}),
+      ...(decision.spendIncludesUnboundPoolHistory ? { includesUnboundPoolHistory: true } : {}),
     }
     : undefined;
   return workflowRefusalResponse(decision.reason, logCtx, refusalLog, undefined, spend);

package/src/service/ownership-mutation-lease.d.mts

@@ -5,7 +5,7 @@ export interface OwnershipMutationLeaseOptions {
   readonly processAlive?: (pid: number) => boolean;
   readonly beforeRelease?: (lockPath: string) => void;
   readonly joinToken?: string;
-  /** Names the current executable at the recorded PID, identity unverified; defaults to `tasklist` or `ps`. */
+  /** Names the current executable at the recorded PID, identity unverified; uses `ps` on POSIX and omits the default image lookup on Windows. */
   readonly processImage?: (pid: number) => string | null;
 }
 

package/src/service/ownership-mutation-lease.mjs

@@ -112,13 +112,11 @@ function readIncompleteOwner(path) {
 /** The current executable at the recorded PID, identity unverified; null if unreadable within a second. */
 function processImage(pid) {
   try {
-    if (process.platform === "win32") {
-      const listed = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], {
-        encoding: "utf8", timeout: 1_000, windowsHide: true,
-      });
-      const match = /^"([^"]+)","(\d+)"/.exec((listed.stdout ?? "").trim());
-      return listed.status === 0 && match && Number(match[2]) === pid ? match[1] : null;
-    }
+    // This module also runs in the Node npm/pnpm launcher, before Bun is available.
+    // Without a kernel-backed system-directory resolver, omit the optional Windows
+    // image label rather than searching the caller's directory/PATH or trusting env roots.
+    // PID, liveness, age and lease ownership decisions do not depend on this label.
+    if (process.platform === "win32") return null;
     const listed = spawnSync("ps", ["-o", "comm=", "-p", String(pid)], { encoding: "utf8", timeout: 1_000 });
     const command = (listed.stdout ?? "").trim();
     return listed.status === 0 && command ? basename(command) : null;

package/src/sidecar/anthropic-binding.ts

@@ -0,0 +1,79 @@
+import type { OcxConfig } from "../types";
+import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
+import { configuredAnthropicInstance } from "../providers/anthropic-instance";
+import { anthropicRoutingFor } from "../oauth/anthropic-routing";
+import { resolveAnthropicModelRouteForInstance, routeCandidates } from "../oauth/anthropic-model-routes";
+import type { OAuthAccessSnapshot } from "../oauth";
+import { AnthropicHelperUnavailableError } from "./auth";
+import { captureAnthropicPhysicalSendOwnership, anthropicPhysicalSendOwnershipIsCurrent } from "../oauth/anthropic-send-ownership";
+import { recordAnthropicAccountQuotaFromHeadersForInstance } from "../providers/quota/account-cache";
+import { captureConfigGeneration } from "../lib/state-store-sweeper";
+import { getAccountCredentialWithStatus } from "../oauth/store";
+import { bindAnthropicRefusalCredentialForSend } from "../oauth/anthropic-account-refusal";
+
+/** The one Messages URL builder shared by helper executors and the physical-send fence. */
+export function anthropicHelperMessagesUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "")}/v1/messages`;
+}
+
+/**
+ * Select the helper's account the way the legacy sidecar token path does: a read of the pool's
+ * selection for this model route, with no promotion. A helper never moves the active pointer and
+ * never consumes an operator's one-dispatch manual choice; the physical send is still fenced by
+ * the captured target/config, the account's credential generation and its send ownership.
+ */
+export async function resolveAnthropicHelperSnapshot(config: OcxConfig, instance: AnthropicInstanceId, model: string): Promise<OAuthAccessSnapshot> {
+  const target = config.providers[instance]?.baseUrl;
+  const assertConfigured = () => {
+    const provider = config.providers[instance];
+    if (!provider || provider.disabled || provider.authMode !== "oauth" || provider.adapter !== "anthropic"
+      || configuredAnthropicInstance(config, instance) !== instance || provider.baseUrl !== target) {
+      throw new AnthropicHelperUnavailableError(instance);
+    }
+  };
+  assertConfigured();
+  const routing = anthropicRoutingFor(instance);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const route = resolveAnthropicModelRouteForInstance(instance, config, model);
+    if (route.error) throw new AnthropicHelperUnavailableError(instance);
+    const selection = routing.resolveAnthropicAccountForSession(null, config, Date.now(), route.decision, model);
+    if (!selection.accountId) throw new AnthropicHelperUnavailableError(instance);
+    const snapshot = await routing.getAnthropicPoolAccessSnapshot(selection.accountId);
+    assertConfigured();
+    const current = resolveAnthropicModelRouteForInstance(instance, config, model);
+    if (current.error || JSON.stringify(current.decision) !== JSON.stringify(route.decision)) continue;
+    if (snapshot.provider === instance && snapshot.accountId === selection.accountId) return snapshot;
+  }
+  throw new AnthropicHelperUnavailableError(instance);
+}
+
+/** One physical helper send; reset replays call this boundary again with the same snapshot. */
+export async function fetchAnthropicHelper(
+  config: OcxConfig, snapshot: OAuthAccessSnapshot, model: string,
+  capturedTarget: string, url: string, init: RequestInit,
+): Promise<Response> {
+  const instance = snapshot.provider;
+  if (instance !== "anthropic" && instance !== "anthropic2") throw new Error("Invalid Anthropic helper instance");
+  const row = config.providers[instance];
+  const live = getAccountCredentialWithStatus(instance, snapshot.accountId);
+  if (!row || row.disabled || row.authMode !== "oauth" || row.adapter !== "anthropic"
+    || configuredAnthropicInstance(config, instance) !== instance || row.baseUrl !== capturedTarget
+    || url !== anthropicHelperMessagesUrl(capturedTarget) || !live || live.paused || live.needsReauth
+    || new Headers(init.headers).get("authorization") !== `Bearer ${snapshot.accessToken}`) {
+    throw new AnthropicHelperUnavailableError(instance);
+  }
+  const route = resolveAnthropicModelRouteForInstance(instance, config, model);
+  const routing = anthropicRoutingFor(instance);
+  if (route.error || !routeCandidates(routing.getEligibleAnthropicAccounts(Date.now(), model), route.decision).includes(snapshot.accountId)) {
+    throw new AnthropicHelperUnavailableError(instance);
+  }
+  const owner = captureAnthropicPhysicalSendOwnership(snapshot);
+  if (!owner) throw new AnthropicHelperUnavailableError(instance);
+  const writer = captureConfigGeneration();
+  const response = await fetch(url, init);
+  if (anthropicPhysicalSendOwnershipIsCurrent(owner)) {
+    recordAnthropicAccountQuotaFromHeadersForInstance(instance, snapshot.accountId, response.headers, writer, response.status, model);
+    bindAnthropicRefusalCredentialForSend(response, owner);
+  }
+  return response;
+}

package/src/sidecar/auth.ts

@@ -17,6 +17,73 @@ import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { isCodexAccountUsable } from "../codex/account-usability";
 import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../codex/account-id";
 import { getAccountSet } from "../oauth/store";
+import { configuredAnthropicInstance, type AnthropicInstanceId } from "../providers/anthropic-instance";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+
+/**
+ * The parent request's pool for an inheriting helper. A missing or disabled row keeps the parent's
+ * identity, so a pool removed mid-request refuses instead of discovering another pool; only a present
+ * custom row that is not the builtin instance (an unmarked custom `anthropic2`) stops inheritance.
+ */
+export function inheritedAnthropicInstance(config: OcxConfig, parentProviderName: string | undefined): AnthropicInstanceId | undefined {
+  if (!isAnthropicInstanceId(parentProviderName)) return undefined;
+  const row = config.providers?.[parentProviderName];
+  if (!row || row.disabled === true) return parentProviderName;
+  return configuredAnthropicInstance(config, parentProviderName);
+}
+
+export class AnthropicHelperUnavailableError extends Error {
+  readonly code = "anthropic_helper_unavailable";
+  constructor(readonly instance: AnthropicInstanceId) {
+    super(`The selected ${instance} helper account pool is unavailable`);
+    this.name = "AnthropicHelperUnavailableError";
+  }
+}
+export type AnthropicHelperContext = {
+  backendFamily: string;
+  anthropicInstance?: AnthropicInstanceId;
+  parentProviderName?: string;
+};
+
+/**
+ * Availability of one selected pool: the configured builtin row plus at least one stored account the
+ * pool could select. Which account actually sends (model route, cooldown, manual choice) is decided
+ * by snapshot resolution at send time, exactly as the main request path does, so a paused or
+ * reauth-pending ACTIVE account does not make a pool with another usable account unavailable.
+ */
+export function resolveAnthropicSidecarAuth(config: OcxConfig, instance: AnthropicInstanceId):
+  { anthropicProviderName: AnthropicInstanceId; anthropicProvider: OcxProviderConfig } | undefined {
+  const provider = config.providers[instance];
+  if (!provider || provider.disabled || provider.authMode !== "oauth" || provider.adapter !== "anthropic"
+    || configuredAnthropicInstance(config, instance) !== instance) return undefined;
+  if (!getAccountSet(instance)?.accounts.some(row => row.paused !== true && row.needsReauth !== true)) return undefined;
+  return { anthropicProviderName: instance, anthropicProvider: provider };
+}
+
+/**
+ * Explicit target, then the parent's CONFIGURED builtin instance. The parent name alone is not
+ * enough: a custom provider that happens to be named `anthropic2` is not Pool 2 and is never inherited.
+ */
+export function resolveAnthropicHelperInstance(config: OcxConfig, context: AnthropicHelperContext): AnthropicInstanceId | undefined {
+  if (context.backendFamily !== "anthropic") return undefined;
+  const instance = context.anthropicInstance ?? inheritedAnthropicInstance(config, context.parentProviderName);
+  if (instance && !resolveAnthropicSidecarAuth(config, instance)) throw new AnthropicHelperUnavailableError(instance);
+  return instance;
+}
+
+/**
+ * Planner boundary for the typed refusal: an unavailable selected pool means "this helper does not
+ * run", never "fail the main request" and never "discover another pool". Other errors propagate.
+ */
+export function withAnthropicHelperRefusal<T>(surface: string, resolve: () => T): T | undefined {
+  try {
+    return resolve();
+  } catch (error) {
+    if (!(error instanceof AnthropicHelperUnavailableError)) throw error;
+    console.warn(`[${surface}] ${error.message}; the request continues without this helper`);
+    return undefined;
+  }
+}
 
 export interface SidecarAuthState {
   /** ChatGPT login usable: canonical forward provider AND a live stored credential. */
@@ -63,6 +130,10 @@ function findAnthropicAuthProvider(
   config: OcxConfig,
 ): { providerName: string; provider: OcxProviderConfig } | undefined {
   for (const [providerName, provider] of Object.entries(config.providers)) {
+    // Never adds Pool 2 automatically. The OAuth store key `anthropic2` belongs to the builtin pool:
+    // its token path and the token guardian refuse an unmarked row of that name, so offering such a
+    // custom row here would advertise credentials no helper executor will spend.
+    if (providerName === "anthropic2") continue;
     if (provider.disabled === true) continue;
     if (provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
     const set = getAccountSet(providerName);
@@ -72,8 +143,11 @@ function findAnthropicAuthProvider(
   return undefined;
 }
 
-export function resolveSidecarAuth(config: OcxConfig): SidecarAuthState {
-  const anthropic = findAnthropicAuthProvider(config);
+export function resolveSidecarAuth(config: OcxConfig, instance?: AnthropicInstanceId): SidecarAuthState {
+  const exact = instance ? resolveAnthropicSidecarAuth(config, instance) : undefined;
+  if (instance && !exact) throw new AnthropicHelperUnavailableError(instance);
+  const anthropic = exact ? { providerName: exact.anthropicProviderName, provider: exact.anthropicProvider }
+    : findAnthropicAuthProvider(config);
   return {
     isCodexAuth: hasUsableCodexLogin(config),
     isAnthropicAuth: anthropic !== undefined,

package/src/types/anthropic-account-pool.ts

@@ -0,0 +1,33 @@
+/**
+ * Anthropic OAuth account-pool settings. One shape, two locations:
+ * `config.anthropicAccountPool` for the `anthropic` instance and
+ * `config.providers.anthropic2.anthropicAccountPool` for `anthropic2`. Neither inherits from the other.
+ *
+ * Leaf module: `config.ts` and `provider.ts` import these types, never the reverse.
+ */
+export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
+
+export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
+
+export interface AnthropicModelRoute {
+  name: string;
+  match: string;
+  accounts: string[];
+  fallback?: boolean;
+}
+
+export interface AnthropicAccountPoolConfig {
+  enabled?: boolean;
+  /** Preserve native Claude Messages while the pool is enabled. Default true; false selects legacy translation. */
+  nativeMessages?: boolean;
+  /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
+  autoSwitchThreshold?: number;
+  /** New-session rotation strategy. Default quota (today's behaviour). */
+  strategy?: OcxAccountPoolRotationStrategy;
+  /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+  stickyLimit?: number;
+  /** Usage window for quota-based scoring. Default "five-hour" (today's behaviour). */
+  quotaWindow?: OcxAccountPoolQuotaWindow;
+  /** Ordered model allowlists; inactive while the pool is disabled. Stored account IDs only. */
+  routes?: AnthropicModelRoute[];
+}