@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/server/management/usage-aggregate-cache.ts

@@ -15,6 +15,10 @@ import {
 } from "../../usage/summary";
 import { userCostOverlayVersion } from "../../usage/user-cost-overlays";
 import type { UsageTimeWindow } from "../../usage/time-range";
+import {
+  createJevStatsAccumulator,
+  type JevStatsAccumulator,
+} from "../../usage/jev-stats";
 
 import {
   cacheApiKeyUsageFromRollup,
@@ -34,6 +38,19 @@ interface RetainedUsageAggregate {
   retainedAt: number;
 }
 
+interface RetainedJevStatsAggregate {
+  accumulator: JevStatsAccumulator;
+  usageIncomplete: boolean;
+  revision: UsageLogRevision | null;
+  identityKey: string;
+  revisionKey: string;
+  processedThroughBytes: number;
+  processedThroughDigest: string;
+  retainedAt: number;
+}
+
+type RetainedAggregateState = RetainedUsageAggregate | RetainedJevStatsAggregate;
+
 export interface UsageAggregateResult {
   accumulator: UsageSummaryAccumulator;
   usageIncomplete: boolean;
@@ -50,6 +67,14 @@ export interface UsageAggregateOptions {
   managementUsageMaxReadBytes?: number;
 }
 
+export interface JevStatsAggregateResult {
+  accumulator: JevStatsAccumulator;
+  usageIncomplete: boolean;
+  revision: UsageLogRevision | null;
+  processedThroughBytes: number;
+  update: "unchanged" | "append" | "rebuild";
+}
+
 export interface UsageAggregateRetainedStats {
   count: number;
   bytes: number;
@@ -62,11 +87,15 @@ const MAX_REBUILD_ATTEMPTS = 2;
 const MAX_RETAINED_FILTERED_AGGREGATES = 4;
 
 let retainedAggregate: RetainedUsageAggregate | null = null;
-const pinnedAggregates = new Set<RetainedUsageAggregate>();
+const pinnedAggregates = new Set<RetainedAggregateState>();
 let baseFlight: Promise<UsageAggregateResult> | null = null;
 const filteredFlights = new Map<string, Promise<UsageAggregateResult>>();
 const retainedFilteredAggregates = new Map<string, RetainedUsageAggregate>();
 const MAX_CONCURRENT_FILTERED_AGGREGATES = 4;
+const retainedJevStatsAggregates = new Map<string, RetainedJevStatsAggregate>();
+const jevStatsFlights = new Map<string, Promise<JevStatsAggregateResult>>();
+const MAX_RETAINED_JEV_STATS_AGGREGATES = 4;
+const MAX_CONCURRENT_JEV_STATS_AGGREGATES = 4;
 
 function currentTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -418,10 +447,171 @@ async function refreshFilteredAggregate(
   return appendFilteredAggregate(key, state, filter, window);
 }
 
+function jevStatsResultFrom(
+  state: RetainedJevStatsAggregate,
+  update: JevStatsAggregateResult["update"],
+): JevStatsAggregateResult {
+  return {
+    accumulator: state.accumulator,
+    usageIncomplete: state.usageIncomplete,
+    revision: state.revision,
+    processedThroughBytes: state.processedThroughBytes,
+    update,
+  };
+}
+
+function trimRetainedJevStatsAggregates(): void {
+  while (retainedJevStatsAggregates.size > MAX_RETAINED_JEV_STATS_AGGREGATES) {
+    const oldest = [...retainedJevStatsAggregates]
+      .filter(([, state]) => !pinnedAggregates.has(state))
+      .sort(([, left], [, right]) => left.retainedAt - right.retainedAt)[0];
+    if (!oldest) return;
+    retainedJevStatsAggregates.delete(oldest[0]);
+  }
+}
+
+function publishJevStatsAggregate(
+  key: string,
+  state: RetainedJevStatsAggregate,
+  update: JevStatsAggregateResult["update"],
+): JevStatsAggregateResult {
+  retainedJevStatsAggregates.set(key, state);
+  trimRetainedJevStatsAggregates();
+  enforceAppOwnedMemoryBudget();
+  return jevStatsResultFrom(state, update);
+}
+
+function retainedJevStatsState(
+  accumulator: JevStatsAccumulator,
+  scan: Awaited<ReturnType<typeof scanUsageLedgerCooperatively>>,
+  priorIncomplete = false,
+): RetainedJevStatsAggregate {
+  return {
+    accumulator,
+    usageIncomplete: priorIncomplete || scan.oversizedRows > 0,
+    revision: scan.revision,
+    identityKey: usageLogIdentityKey(scan.revision),
+    revisionKey: usageLogRevisionKey(scan.revision),
+    processedThroughBytes: scan.processedThroughBytes,
+    processedThroughDigest: scan.processedThroughDigest,
+    retainedAt: Date.now(),
+  };
+}
+
+async function rebuildJevStatsAggregate(
+  key: string,
+  comboId: string | null,
+  since: number | null,
+): Promise<JevStatsAggregateResult> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_REBUILD_ATTEMPTS; attempt += 1) {
+    // A rebuild-required result means the opened ledger changed underneath the
+    // scan. Start from a fresh accumulator so no partially observed row can be
+    // returned or retained.
+    const accumulator = createJevStatsAccumulator({ comboId, since });
+    try {
+      const scan = await scanUsageLedgerCooperatively({ onEntry: entry => accumulator.add(entry) });
+      return publishJevStatsAggregate(key, retainedJevStatsState(accumulator, scan), "rebuild");
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof UsageLedgerRebuildRequiredError) || attempt + 1 >= MAX_REBUILD_ATTEMPTS) {
+        throw error;
+      }
+    }
+  }
+  throw lastError ?? new Error("JEV stats aggregate rebuild did not settle");
+}
+
+function jevStatsRequiresRebuild(
+  state: RetainedJevStatsAggregate,
+  observed: UsageLogRevision | null,
+): boolean {
+  if (state.identityKey !== usageLogIdentityKey(observed)) return true;
+  if (!state.revision || !observed) return state.revision !== observed;
+  if (observed.size < state.revision.size) return true;
+  return observed.size === state.revision.size && usageLogRevisionKey(observed) !== state.revisionKey;
+}
+
+async function appendJevStatsAggregate(
+  key: string,
+  state: RetainedJevStatsAggregate,
+  comboId: string | null,
+  since: number | null,
+): Promise<JevStatsAggregateResult> {
+  pinnedAggregates.add(state);
+  let rebuildAfterUnpin = false;
+  try {
+    const candidate = state.accumulator.clone();
+    const scan = await scanUsageLedgerCooperatively({
+      startAtBytes: state.processedThroughBytes,
+      expectedIdentityKey: state.identityKey,
+      expectedProcessedThroughDigest: state.processedThroughDigest,
+      onEntry: entry => candidate.add(entry),
+    });
+    const next = retainedJevStatsState(candidate, scan, state.usageIncomplete);
+    return publishJevStatsAggregate(key, next, "append");
+  } catch (error) {
+    if (retainedJevStatsAggregates.get(key) === state) retainedJevStatsAggregates.delete(key);
+    if (error instanceof UsageLedgerRebuildRequiredError) rebuildAfterUnpin = true;
+    else throw error;
+  } finally {
+    pinnedAggregates.delete(state);
+    trimRetainedJevStatsAggregates();
+  }
+  if (rebuildAfterUnpin) return rebuildJevStatsAggregate(key, comboId, since);
+  throw new Error("JEV stats aggregate append did not settle");
+}
+
+async function refreshJevStatsAggregate(
+  key: string,
+  comboId: string | null,
+  since: number | null,
+): Promise<JevStatsAggregateResult> {
+  const state = retainedJevStatsAggregates.get(key);
+  if (!state) return rebuildJevStatsAggregate(key, comboId, since);
+  const observed = currentUsageLogRevision();
+  if (jevStatsRequiresRebuild(state, observed)) {
+    retainedJevStatsAggregates.delete(key);
+    return rebuildJevStatsAggregate(key, comboId, since);
+  }
+  if (state.revisionKey === usageLogRevisionKey(observed)) {
+    state.retainedAt = Date.now();
+    return jevStatsResultFrom(state, "unchanged");
+  }
+  return appendJevStatsAggregate(key, state, comboId, since);
+}
+
+/**
+ * Return one checkpointed JEV projection for a combo and fixed calendar range.
+ * Concurrent readers share a flight; later polls scan only a verified append
+ * suffix, and unchanged ledgers perform no file read.
+ */
+export async function getJevStatsAggregate(options: {
+  comboId?: string | null;
+  since?: number | null;
+} = {}): Promise<JevStatsAggregateResult> {
+  const comboId = options.comboId ?? null;
+  const since = options.since ?? null;
+  const key = JSON.stringify([comboId, since]);
+  const existing = jevStatsFlights.get(key);
+  if (existing) return existing;
+  if (jevStatsFlights.size >= MAX_CONCURRENT_JEV_STATS_AGGREGATES) {
+    throw new Error("too many concurrent JEV stats aggregates");
+  }
+  const flight = refreshJevStatsAggregate(key, comboId, since);
+  jevStatsFlights.set(key, flight);
+  try {
+    return await flight;
+  } finally {
+    if (jevStatsFlights.get(key) === flight) jevStatsFlights.delete(key);
+  }
+}
+
 export function usageAggregateRetainedStats(): UsageAggregateRetainedStats {
   const states = [
     ...(retainedAggregate ? [retainedAggregate] : []),
     ...retainedFilteredAggregates.values(),
+    ...retainedJevStatsAggregates.values(),
   ];
   if (states.length === 0) {
     return { count: 0, bytes: 0, evictableBytes: 0, pinnedBytes: 0, oldestAt: null };
@@ -449,19 +639,27 @@ export function usageAggregateRetainedStats(): UsageAggregateRetainedStats {
 }
 
 export function discardRetainedUsageAggregate(): number {
-  const candidates: Array<{ key: string | null; state: RetainedUsageAggregate }> = [
+  const candidates: Array<{
+    kind: "base" | "filtered" | "jev";
+    key: string | null;
+    state: RetainedAggregateState;
+  }> = [
     ...(retainedAggregate && !pinnedAggregates.has(retainedAggregate)
-      ? [{ key: null, state: retainedAggregate }]
+      ? [{ kind: "base" as const, key: null, state: retainedAggregate }]
       : []),
     ...[...retainedFilteredAggregates]
       .filter(([, state]) => !pinnedAggregates.has(state))
-      .map(([key, state]) => ({ key, state })),
+      .map(([key, state]) => ({ kind: "filtered" as const, key, state })),
+    ...[...retainedJevStatsAggregates]
+      .filter(([, state]) => !pinnedAggregates.has(state))
+      .map(([key, state]) => ({ kind: "jev" as const, key, state })),
   ];
   const oldest = candidates.sort((left, right) => left.state.retainedAt - right.state.retainedAt)[0];
   if (!oldest) return 0;
   const released = oldest.state.accumulator.estimatedBytes;
-  if (oldest.key === null) retainedAggregate = null;
-  else retainedFilteredAggregates.delete(oldest.key);
+  if (oldest.kind === "base") retainedAggregate = null;
+  else if (oldest.kind === "filtered") retainedFilteredAggregates.delete(oldest.key!);
+  else retainedJevStatsAggregates.delete(oldest.key!);
   return released;
 }
 
@@ -471,4 +669,6 @@ export function resetUsageAggregateCacheForTests(): void {
   baseFlight = null;
   filteredFlights.clear();
   retainedFilteredAggregates.clear();
+  jevStatsFlights.clear();
+  retainedJevStatsAggregates.clear();
 }

package/src/server/management-api.ts

@@ -80,6 +80,7 @@ import { handleClaudeDesktopPickerRoutes } from "./management/claude-desktop-pic
 import { handleCursorIntegrationRoutes } from "./management/cursor-integration-routes";
 import type { ManagementContext } from "./management/context";
 import type { ManagementPrincipal, ManagementSessionControl } from "./management-auth";
+import type { ManagementRequestIngress } from "./management/context";
 export type { ManagementApiDeps } from "./management/context";
 import { fetchAllModels } from "./management/shared";
 import { CatalogGatherBusyError } from "../codex/catalog/provider-fetch";
@@ -155,6 +156,16 @@ async function handleWorkflowBudgetRoutesOnDemand(ctx: ManagementContext): Promi
   return handleWorkflowBudgetRoutes(ctx);
 }
 
+/**
+ * Lazy like the Lab and routing-profile handlers: the protocol planner reaches the router and
+ * the ingress eligibility rules, which no other dashboard request needs.
+ */
+async function handleProtocolRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/protocols")) return null;
+  const { handleProtocolRoutes } = await import("./management/protocol-routes");
+  return handleProtocolRoutes(ctx);
+}
+
 async function handleGrokCouponRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
   if (!pathInManagementNamespace(ctx.url.pathname, "/api/grok/reset-coupons", true)) return null;
   const { handleGrokCouponRoutes } = await import("./management/grok-coupon-routes");
@@ -184,6 +195,12 @@ async function handleRemoteWorkspaceRoutesOnDemand(ctx: ManagementContext): Prom
   return handleRemoteWorkspaceRoutes(ctx);
 }
 
+async function handleLinkRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/link")) return null;
+  const { handleLinkRoutes } = await import("./management/link-routes");
+  return handleLinkRoutes(ctx);
+}
+
 export async function handleManagementAPI(
   req: Request,
   url: URL,
@@ -191,6 +208,7 @@ export async function handleManagementAPI(
   deps: ManagementApiDeps = {},
   principal?: ManagementPrincipal,
   sessionControl?: ManagementSessionControl,
+  requestIngress: ManagementRequestIngress = { trustedLoopback: false },
 ): Promise<Response | null> {
   if (!isAllowedManagementOrigin(req, config)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
@@ -273,10 +291,16 @@ export async function handleManagementAPI(
       }
     } catch { /* best-effort */ }
   }
-  const ctx: ManagementContext = { req, url, config, deps, version: VERSION, principal, sessionControl, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
+  const ctx: ManagementContext = {
+    req, url, config, deps, version: VERSION, principal, sessionControl,
+    trustedLoopbackIngress: requestIngress.trustedLoopback,
+    guiSessionIssuance: requestIngress.guiSessionIssuance ?? null,
+    convergeCodexCatalog, syncClaudeAgentDefsBestEffort,
+  };
   let routed: Response | null | undefined;
   try {
     routed = handleSessionRoutes(ctx)
+    ??     (await handleLinkRoutesOnDemand(ctx))
     ??     (await handleRemoteWorkspaceRoutesOnDemand(ctx))
     ??     (await handleConfigRoutes(ctx))
     ??     (await handleStorageLogGuardRoutes(ctx))
@@ -284,6 +308,7 @@ export async function handleManagementAPI(
     ??     (await handleRequestHistoryRoutes(ctx))
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
+    ??     (await handleProtocolRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
     ??     (await handleAnthropicResetGrantRoutesOnDemand(ctx))
     ??     handleMetricsRoutes(ctx)

package/src/server/management-auth.ts

@@ -71,6 +71,7 @@ import {
   type GuiSessionRecord,
   type GuiSessionRequestContext,
 } from "./gui-session";
+import { hasLocalDesktopSnapshotCapability } from "./local-desktop-snapshot-auth";
 export type { GuiSessionBootstrap, GuiSessionRequestContext } from "./gui-session";
 
 const LOCAL_READ_REPLAY_LIMIT = 256;
@@ -260,6 +261,17 @@ export function issueGuiSession(
   return issueGuiSessionFromState(req, config, state, context);
 }
 
+/** Returns the recorded issuance for the session that authorized this request. */
+export function managementSessionIssuance(
+  req: Request,
+  state: ManagementAuthState,
+): import("./gui-session").GuiSessionIssuance | null {
+  if (!state.available) return null;
+  const credential = requestManagementCredential(req);
+  if (!credential || equalSecret(credential, state.token)) return null;
+  return state.sessions.get(credential)?.issuance ?? null;
+}
+
 export interface ManagementSessionControl {
   revokeCurrent(req: Request): boolean;
   /** Revalidate a long-lived request against current authority, without cached admission or renewal. */
@@ -315,8 +327,8 @@ export function createManagementSessionControl(state: ManagementAuthState): Mana
  * per-session CSRF token match. Consent-bearing routes must key off this value
  * rather than off request headers, which the token holder can forge freely.
  * The capability principals are process-scoped HMACs bound to the current process
- * PID and listening port. Local reads are accepted only for two exact GET paths;
- * restart and provider reload remain separate wire contracts for their exact POSTs.
+ * PID and listening port. Local reads are accepted only for allowlisted GET paths;
+ * snapshot, restart and provider reload use separate contracts for their exact POSTs.
  */
 export type ManagementPrincipal =
   | "admin-token"
@@ -324,6 +336,7 @@ export type ManagementPrincipal =
   | "gui-session"
   | "gui-pair-capability"
   | "local-read-capability"
+  | "local-desktop-snapshot-capability"
   | "local-provider-reload-capability"
   | "local-aside-sync-capability"
   | "system-restart-capability";
@@ -375,8 +388,6 @@ function hasLocalReadCapability(
   } catch {
     return false;
   }
-  // Do not let a future query-bearing variant silently inherit this narrow grant.
-  if (url.search !== "") return false;
   const expectedPid = parseExpectedLocalManagementPid(
     req.headers.get(LOCAL_MANAGEMENT_EXPECTED_PID_HEADER),
   );
@@ -391,7 +402,9 @@ function hasLocalReadCapability(
     local.attestationSecret,
     req.headers.get(LOCAL_MANAGEMENT_NONCE_HEADER),
     req.method,
-    url.pathname,
+    // The query is signed into the capability, so a grant for one range cannot be replayed
+    // against another — the grant stays exactly as narrow as the request it was minted for.
+    url.pathname + url.search,
     local.pid,
     local.port,
     expiresAt,
@@ -550,6 +563,7 @@ function resolveManagementAdmission(
   if (hasSystemRestartCapability(req, local)) principal = "system-restart-capability";
   else if (hasLocalAsideSyncCapability(req, local)) principal = "local-aside-sync-capability";
   else if (hasLocalProviderReloadCapability(req, local)) principal = "local-provider-reload-capability";
+  else if (hasLocalDesktopSnapshotCapability(req, local)) principal = "local-desktop-snapshot-capability";
   else if (hasLocalReadCapability(req, local)) principal = "local-read-capability";
   else if (hasGuiPairCapability(req, local)) principal = "gui-pair-capability";
   else if (state.available) {

package/src/server/messages-native-eligibility.ts

@@ -0,0 +1,161 @@
+/**
+ * Whether a settled Messages route may take the managed native Messages lane (PF-08).
+ *
+ * PURE: reads the route, the body's structure and config, and nothing else. The Messages ingress,
+ * `count_tokens` and the protocol planner (`src/protocols/plan-snapshot.ts`) all ask here, so a
+ * preview, a count and the real send cannot disagree about the lane.
+ */
+import { anthropicBodyElidesBlockedSkill } from "../claude/inbound";
+import { isClaudeWebSearchToolName } from "../claude/outbound";
+import { isAnthropicAccountPoolEnabled } from "../oauth/anthropic-routing";
+import type { ProtocolReasonCode } from "../protocols/contract";
+import { featuresFromMessagesBody } from "../protocols/features";
+import { credentialDomainFor } from "../protocols/opaque-state";
+import { resolveProtocolSettings } from "../protocols/settings";
+import type { RouteResult } from "../router";
+import type { OcxConfig } from "../types";
+import { requiresVisionPreprocessing } from "../vision";
+import { resolvePinnedEffort } from "./effort-policy";
+
+/** Why the managed native Messages lane declines a route, as a protocol reason code. */
+export type NativeMessagesDeclineReason = Extract<
+  ProtocolReasonCode,
+  | "rollout-disabled"
+  | "cross-wire-ir"
+  | "auth-mode-not-native"
+  | "oauth-account-pool"
+  | "combo-or-policy-route"
+  | "effort-row"
+  | "fast-row"
+  | "vision-preprocessing"
+  | "bridge-only-policy"
+>;
+
+/** Request facts the body cannot carry. */
+export interface NativeMessagesSelector {
+  /** A synthetic effort row was requested. */
+  effortRow?: boolean;
+  /** A synthetic fast row was requested. */
+  fastRow?: boolean;
+  /** The model id the bridge would parse (the translated body's `model`), for the effort pin. */
+  routeSelector?: string;
+  /** The Claude settings this ingress reads (intercept bindings applied); defaults to config's. */
+  claudeCode?: OcxConfig["claudeCode"];
+  /**
+   * Runtime fact, supplied by a caller that is about to send: two or more usable Anthropic OAuth
+   * accounts are stored, so the bridge would rotate accounts on a 429
+   * (`hasAnthropicFailoverQuorum`). It reads the account store, so the planner never supplies it
+   * and judges OAuth from config alone.
+   */
+  oauthFailoverQuorum?: boolean;
+}
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Whether the bridge could hand this request to the web-search sidecar: a `web_search*` server
+ * tool the tool choice does not exclude, with the sidecar not disabled in the Claude replay config
+ * (`buildClaudeReplayConfig` merges `claudeCode.webSearchSidecar` over the global block). Whether
+ * a backend credential then exists is decided at dispatch and is not read here, so this errs
+ * toward the bridge, which is today's behavior for every such request.
+ */
+function webSearchSidecarMayEngage(body: Readonly<Rec>, config: OcxConfig): boolean {
+  const sidecar = { ...config.webSearchSidecar, ...config.claudeCode?.webSearchSidecar };
+  if (sidecar.enabled === false) return false;
+  if (!Array.isArray(body.tools)) return false;
+  const declared = body.tools.some(tool => isRec(tool) && typeof tool.type === "string" && tool.type.startsWith("web_search"));
+  if (!declared) return false;
+  const choice = body.tool_choice;
+  if (isRec(choice)) {
+    if (choice.type === "none") return false;
+    if (choice.type === "tool") return typeof choice.name === "string" && isClaudeWebSearchToolName(choice.name);
+  }
+  return true;
+}
+
+/**
+ * Operator policy the translated path applies and the native lane would skip: a pinned
+ * reasoning effort for the route, a blocked-skill bundle the translator would elide, or the
+ * web-search sidecar. Any of them keeps the request on the bridge.
+ */
+function bridgeOnlyPolicyApplies(
+  route: RouteResult,
+  body: Readonly<Rec>,
+  config: OcxConfig,
+  selector: NativeMessagesSelector,
+): boolean {
+  if (resolvePinnedEffort(route, selector.routeSelector, config) !== undefined) return true;
+  if (anthropicBodyElidesBlockedSkill(body, selector.claudeCode ?? config.claudeCode)) return true;
+  return webSearchSidecarMayEngage(body, config);
+}
+
+/**
+ * The credential rule. A proxy-managed key is native since PF-08. An Anthropic OAuth account
+ * is native only with `managedMessagesNativeOAuth` on (itself effective only with
+ * `managedMessagesNative`), only for the `anthropic` provider the OAuth store serves, and only
+ * to `api.anthropic.com`. A pooled account set declines: rotation, session affinity and quota
+ * ranking live in the Responses pipeline's transport and are not replicated here. `forward`
+ * belongs to the caller.
+ */
+function credentialDeclineReason(
+  route: RouteResult,
+  config: OcxConfig,
+  selector: NativeMessagesSelector,
+): NativeMessagesDeclineReason | undefined {
+  const provider = route.provider;
+  if (provider.authMode === undefined || provider.authMode === "key") return undefined;
+  if (provider.authMode !== "oauth") return "auth-mode-not-native";
+  if (!resolveProtocolSettings(config).rollout.managedMessagesNativeOAuth) return "auth-mode-not-native";
+  if (route.providerName !== "anthropic") return "auth-mode-not-native";
+  if (!credentialDomainFor(provider)?.firstPartyAnthropic) return "auth-mode-not-native";
+  if (isAnthropicAccountPoolEnabled(config) || selector.oauthFailoverQuorum === true) return "oauth-account-pool";
+  return undefined;
+}
+
+/**
+ * The first rule that keeps a Messages request off the managed native lane, or `undefined` when
+ * the route is eligible.
+ *
+ * - the `protocols.rollout.managedMessagesNative` switch is off;
+ * - the final adapter is not `anthropic`;
+ * - the credential is neither a proxy-managed key nor an eligible Anthropic OAuth account
+ *   (`credentialDeclineReason`); a pooled OAuth account set is `oauth-account-pool`;
+ * - a combo or policy route owns multi-candidate execution in the Responses pipeline;
+ * - a synthetic effort or fast row needs the adapter that owns its wire rewrite;
+ * - an image would reach a model the operator declared unable to read it;
+ * - operator policy only the bridge applies would engage (pinned effort, blocked-skill elision,
+ *   the web-search sidecar).
+ */
+export function nativeMessagesDeclineReason(
+  route: RouteResult,
+  body: Readonly<Record<string, unknown>>,
+  config: OcxConfig,
+  selector: NativeMessagesSelector = {},
+): NativeMessagesDeclineReason | undefined {
+  if (!resolveProtocolSettings(config).rollout.managedMessagesNative) return "rollout-disabled";
+  const provider = route.provider;
+  if (provider.adapter !== "anthropic") return "cross-wire-ir";
+  const credentialDecline = credentialDeclineReason(route, config, selector);
+  if (credentialDecline) return credentialDecline;
+  if (route.combo || route.routeKind === "combo" || route.routeKind === "policy") return "combo-or-policy-route";
+  if (selector.effortRow) return "effort-row";
+  if (selector.fastRow) return "fast-row";
+  if (featuresFromMessagesBody(body).has("request.images")
+    && requiresVisionPreprocessing(config, provider, route.modelId, route.providerName)) {
+    return "vision-preprocessing";
+  }
+  if (bridgeOnlyPolicyApplies(route, body, config, selector)) return "bridge-only-policy";
+  return undefined;
+}
+
+export function isNativeMessagesRouteEligible(
+  route: RouteResult,
+  body: Readonly<Record<string, unknown>>,
+  config: OcxConfig,
+  selector?: NativeMessagesSelector,
+): boolean {
+  return nativeMessagesDeclineReason(route, body, config, selector) === undefined;
+}