@bitkyc08/opencodex 2.29.0 → 2.31.0-preview.20260822

package/src/responses/namespace-tool-compat.ts

@@ -268,9 +268,8 @@ export function rewriteRoutedNamespaceToolsForUpstream(body: unknown): {
   const groups = collectResponsesToolGroups(body);
   const plan = buildRewritePlan(groups);
 
-  // Deliberately not gated on the plan being non-empty: a turn whose catalog is gone still replays
-  // call items carrying a private `namespace`, and the routed compaction turn strips the whole tool
-  // surface before this runs.
+  // Deliberately not gated on the plan being non-empty: a turn whose catalog is absent can still
+  // replay call items carrying a private `namespace`.
   const emitted = new Set<string>();
   const tools = Array.isArray(body.tools) ? rewriteToolList(body.tools, plan, emitted) : body.tools;
 

package/src/router.ts

@@ -366,6 +366,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
       && registryEntry.supportsOpenAiWebSearchToolFields !== undefined
       ? { supportsOpenAiWebSearchToolFields: registryEntry.supportsOpenAiWebSearchToolFields }
       : {}),
+    ...(provider.supportsResponsesCustomTools === undefined && registryEntry.supportsResponsesCustomTools !== undefined
+      ? { supportsResponsesCustomTools: registryEntry.supportsResponsesCustomTools }
+      : {}),
     ...(provider.preserveResponsesReasoningContent === undefined && registryEntry.preserveResponsesReasoningContent !== undefined
       ? { preserveResponsesReasoningContent: registryEntry.preserveResponsesReasoningContent }
       : {}),

package/src/server/chat-completions.ts

@@ -258,6 +258,10 @@ async function handleChatCompletionsWithBudget(
     abortSignal: req.signal,
     // Body is Responses-shaped by now, but the client spoke Chat Completions.
     inboundWire: "chat",
+    // Terminal vision-describe marker (roadmap 180): the bridge rebuilds
+    // headers from the FORWARD_HEADERS allowlist, which would drop the raw
+    // header — so the fact is detected here and carried as an option flag.
+    ...(req.headers.get("x-opencodex-vision-describe") === "1" ? { visionDescribeTerminal: true } : {}),
     translatorBudget,
     ...(logIds ? { onFirstOutput: () => recordFirstOutput(logCtx, logIds.start) } : {}),
     onNativePassthroughTerminal: status => finalizeNativeLog(httpStatusForRequestLogTerminal(status, logCtx), { terminalStatus: status, closeReason: "terminal" }),

package/src/server/chat-native.ts

@@ -11,6 +11,7 @@ import type { AdmissionLease } from "../lib/admission";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { redactSecretString } from "../lib/redact";
 import { resolveClientRetryAfter } from "../lib/retry-after";
+import { isModelTextOnly } from "../vision";
 import {
   applyUpstreamRecoveryInit,
   fetchWithResetRetry,
@@ -61,6 +62,12 @@ export function isNativeChatRouteEligible(route: RouteResult, rawBody: Rec): boo
   if (rawBody.store === true || rawBody.background === true) return false;
   if (typeof rawBody.previous_response_id === "string" && rawBody.previous_response_id.length > 0) return false;
   if (rawBody.compaction_trigger !== undefined) return false;
+  // Vision sidecar coverage (roadmap 180): a text-only routed model with an
+  // image-bearing body must go through the Responses pipeline, whose plan
+  // site describes or strips the image. The native fast path has no vision
+  // handling, so letting it keep such a request forwards raw pixels to a
+  // model the operator declared blind.
+  if (isModelTextOnly(provider, route.modelId) && chatBodyCarriesImage(rawBody)) return false;
   if (Array.isArray(rawBody.tools)) {
     for (const tool of rawBody.tools) {
       if (!isRec(tool)) continue;
@@ -72,6 +79,19 @@ export function isNativeChatRouteEligible(route: RouteResult, rawBody: Rec): boo
   return true;
 }
 
+/** Any messages[].content[] part of type image_url. */
+function chatBodyCarriesImage(rawBody: Rec): boolean {
+  const messages = rawBody.messages;
+  if (!Array.isArray(messages)) return false;
+  for (const message of messages) {
+    if (!isRec(message) || !Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (isRec(part) && part.type === "image_url") return true;
+    }
+  }
+  return false;
+}
+
 function chatCompletionJson(value: unknown): Rec | null {
   if (!isRec(value) || !Array.isArray(value.choices) || value.choices.length === 0) return null;
   return value;

package/src/server/management/agent-settings-routes.ts

@@ -1073,13 +1073,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const section = body[field];
       if (section === undefined || section === null) continue;
       if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
-      // The widened union applies to the WEB-SEARCH override only (roadmap 060).
-      // Vision keeps its two-backend contract — accepting a wider id there would
-      // persist a backend the vision resolver reads as unset, silently activating
-      // a backend the operator never chose (review F1).
+      // Both overrides now speak their full unions (roadmap 060 web, 170
+      // vision revised). Vision's third arm is "routed" (loopback through the
+      // proxy's own router), never exa: exa is not an LLM, and accepting an
+      // unknown literal would persist a backend the vision resolver reads as
+      // unset (review F1's failure mode).
       const allowedBackends = field === "webSearchSidecar"
         ? ["openai", "anthropic", "xai", "gemini", "exa"]
-        : ["openai", "anthropic"];
+        : ["openai", "anthropic", "routed"];
       if (section.backend !== undefined && section.backend !== null
         && !allowedBackends.includes(section.backend as string)) {
         return jsonResponse({ error: `${field}.backend must be ${allowedBackends.join(", ")}, or null` }, 400);
@@ -1094,8 +1095,18 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         const requested = section.model;
         const candidates = await visionCandidateRows(config);
         const hint = section.backend === "anthropic" || section.backend === "openai"
+          || section.backend === "routed"
           ? section.backend
           : config.claudeCode?.visionSidecar?.backend;
+        // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
+        const effectiveBackend = hint ?? "openai";
+        const namespaced = requested.includes("/");
+        if (namespaced && effectiveBackend !== "routed") {
+          return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
+        }
+        if (!namespaced && effectiveBackend === "routed") {
+          return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
+        }
         if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
           return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
         }

package/src/server/management/config-routes.ts

@@ -113,8 +113,14 @@ async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
   // Match the runtime's one selected Anthropic executor for both backend fallback
   // and catalog reachability; resolving it once prevents the two projections drifting.
   const anthropicSidecar = findAnthropicVisionProvider(config);
-  const backend = resolveVisionBackend(vs.backend, anthropicSidecar);
-  const model = resolveEffectiveVisionModel(config, backend);
+  // The routed backend reports its own namespaced model verbatim: it is the
+  // dispatched value, and collapsing it through the legacy resolver would
+  // display a describer the runtime is not using (roadmap 190).
+  const routedActive = vs.backend === "routed" && !!vs.model && vs.model.includes("/");
+  const backend = routedActive ? "routed" as const : resolveVisionBackend(vs.backend, anthropicSidecar);
+  const model = routedActive && vs.model
+    ? vs.model
+    : resolveEffectiveVisionModel(config, backend === "routed" ? resolveVisionBackend(undefined, anthropicSidecar) : backend);
   const reasoning = normalizeVisionReasoningForModel(model, vs.reasoning) ?? "low";
   const models = await visionModelOptionsFor(config, anthropicSidecar);
   // Display-only grandfather: a persisted id stays selectable, but the write gate
@@ -592,8 +598,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       return jsonResponse({ error: "webSearch.streamRoutedModelOutput must be a boolean" }, 400);
     }
     if (body.vision && body.vision.backend !== undefined
-      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic") {
-      return jsonResponse({ error: "vision.backend must be openai, anthropic, or null" }, 400);
+      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic"
+      && body.vision.backend !== "routed") {
+      return jsonResponse({ error: "vision.backend must be openai, anthropic, routed, or null" }, 400);
     }
     if (body.vision && body.vision.maxDescriptionsPerTurn !== undefined
       && (typeof body.vision.maxDescriptionsPerTurn !== "number"
@@ -621,8 +628,20 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       const requested = body.vision.model;
       const candidates = await visionCandidateRows(config);
       const hint = body.vision.backend === "anthropic" || body.vision.backend === "openai"
+        || body.vision.backend === "routed"
         ? body.vision.backend
         : config.visionSidecar?.backend;
+      // Coherence (roadmap 170 r2): the forward/OAuth executors POST the model
+      // string VERBATIM, so a namespaced id on those backends persists a wire
+      // id they cannot run; and "routed" without a namespace cannot route.
+      const effectiveBackend = hint ?? "openai";
+      const namespaced = requested.includes("/");
+      if (namespaced && effectiveBackend !== "routed") {
+        return jsonResponse({ error: `vision.model "${requested}" is provider-namespaced; it requires vision.backend "routed"` }, 400);
+      }
+      if (!namespaced && effectiveBackend === "routed") {
+        return jsonResponse({ error: `vision.backend "routed" requires a provider-namespaced vision.model ("provider/model"); got "${requested}"` }, 400);
+      }
       if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
         return jsonResponse(visionDescriberRejection("vision.model", requested, config, candidates), 400);
       }
@@ -736,7 +755,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         else config.visionSidecar.model = body.vision.model;
       }
       if (body.vision.backend === null) delete config.visionSidecar.backend;
-      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic") {
+      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic"
+        || body.vision.backend === "routed") {
         config.visionSidecar.backend = body.vision.backend;
       }
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {

package/src/server/management/vision-sidecar-options.ts

@@ -9,6 +9,7 @@
  */
 import type { OcxConfig } from "../../types";
 import { findAnthropicVisionProvider, type AnthropicVisionProvider } from "../../vision";
+import { VISION_BACKENDS } from "../../vision/backends";
 import {
   modelAcceptsImageInput,
   visionEligibleModelOptions,
@@ -16,30 +17,44 @@ import {
   type VisionModelOption,
   type VisionSidecarBackend,
 } from "../../vision/eligibility";
-import { listOpenAiForwardSidecarCandidates } from "../../providers/openai-sidecar";
 import { pickerVisibleSidecarCandidates } from "../../sidecar/candidates";
 import { resolveSidecarAuth } from "../../sidecar/auth";
 
 /**
- * Backends whose executor could actually run: openai forward, anthropic OAuth.
+ * Backends whose executor could actually run (#2188 roadmap 170): openai
+ * forward, anthropic OAuth, xai OAuth, Antigravity OAuth — resolved by the
+ * VISION_BACKENDS descriptor table so this module and the options path cannot
+ * drift on what "active" means.
  *
  * `anthropicSidecar` is REQUIRED rather than defaulted. `findAnthropicVisionProvider`
  * reads the OAuth account store from disk, and a default argument made every helper
  * in this chain re-resolve it whenever a caller passed an explicit `undefined` —
  * which is exactly the no-executor case. Passing it in keeps one read per request.
+ * The descriptor table re-derives the anthropic flag from the shared auth
+ * module; asserting the caller's resolution stays consistent with it is the
+ * job of the shared module, not this file.
  */
 export function enabledVisionBackends(
   config: OcxConfig,
   anthropicSidecar: AnthropicVisionProvider | undefined,
 ): VisionSidecarBackend[] {
-  const backends: VisionSidecarBackend[] = [];
-  // The OpenAI describer needs a CANONICAL ChatGPT forward provider, not merely a
-  // provider keyed "openai" — same predicate the runtime sidecar resolver uses.
-  if (listOpenAiForwardSidecarCandidates(config).length > 0) backends.push("openai");
-  if (anthropicSidecar) backends.push("anthropic");
-  // Neither side resolvable (fresh install, no login): fall back to both so the
-  // picker is populated rather than empty, matching the permissive-unknown rule.
-  return backends.length > 0 ? backends : ["openai", "anthropic"];
+  const auth = resolveSidecarAuth(config);
+  // Preserve the caller's resolution for the anthropic side: the descriptor
+  // reads the shared auth module, but a caller that already resolved "no
+  // executor" must not see anthropic options it cannot dispatch. The filter
+  // applies to the ACTIVE set only — the fresh-install fallback below stays
+  // both universal sides, exactly the pre-widening behavior (test 6 pins it).
+  const active = VISION_BACKENDS
+    .filter(descriptor => descriptor.isActive(auth, config))
+    .map(descriptor => descriptor.backend)
+    .filter(backend => backend !== "anthropic" || anthropicSidecar !== undefined);
+  // "routed" is active by construction, so the fresh-install fallback keys on
+  // the UNIVERSAL sides: when neither resolves, both are offered so the picker
+  // stays populated (permissive-unknown rule; test 6 pins it).
+  if (!active.includes("openai") && !active.includes("anthropic")) {
+    return ["openai", "anthropic", ...active];
+  }
+  return active;
 }
 
 /**
@@ -93,10 +108,16 @@ export async function visionModelOptionsFor(
  * When no catalog row matches, the caller's `backend` is only a HINT, never the
  * authority. Trusting it let a client launder a known-blind OpenAI model past the
  * gate by claiming `backend: "anthropic"`, since the id is absent from the
- * Anthropic table and absence reads as "unknown". Both families are therefore
- * consulted and any positive text-only verdict wins. That is safe precisely
- * because the two vendor tables share no bare model id, so they can never
- * disagree about one.
+ * Anthropic table and absence reads as "unknown".
+ *
+ * A NAMESPACED id ("provider/model", the routed-backend option shape) names
+ * its provider outright, so that provider's config row and metadata family
+ * are probed directly. A BARE id probes ALL configured provider families and
+ * any positive text-only verdict wins (roadmap 170: a bare `grok-4` is
+ * provably text-only in the xai vendor table and must not slip through a
+ * two-family probe). That is safe precisely because the vendor tables share
+ * no bare model id (collision scan in roadmap 160: openai 48, anthropic 26,
+ * xai 32, google 43, zero overlaps), so they can never disagree about one.
  */
 export function visionDescriberIsProvablyBlind(
   config: OcxConfig,
@@ -109,11 +130,25 @@ export function visionDescriberIsProvablyBlind(
   if (candidates.some(candidate => candidate.id === requested
     && modelAcceptsImageInput(config, candidate) === false)) return true;
 
-  const hinted: VisionSidecarBackend = backendHint === "anthropic" ? "anthropic" : "openai";
-  const probed: VisionSidecarBackend[] = hinted === "anthropic"
-    ? ["anthropic", "openai"]
-    : ["openai", "anthropic"];
-  return probed.some(provider => modelAcceptsImageInput(config, { provider, id: requested }) === false);
+  // Namespaced routed id: the provider is named, probe it directly (config
+  // row enrichment + its metadata family both flow through the predicate).
+  const sep = requested.indexOf("/");
+  if (sep > 0) {
+    const provider = requested.slice(0, sep);
+    const id = requested.slice(sep + 1);
+    if (modelAcceptsImageInput(config, { provider, id }) === false) return true;
+    // A namespaced candidate row (value shape) may also carry the proof.
+    return candidates.some(candidate => candidate.provider === provider && candidate.id === id
+      && modelAcceptsImageInput(config, candidate) === false);
+  }
+
+  // Bare id: probe the base vendor families plus every configured provider —
+  // a positive text-only verdict from any source wins.
+  const families = new Set(["openai", "anthropic", "xai", "google-antigravity", ...Object.keys(config.providers ?? {})]);
+  const ordered = backendHint === "anthropic"
+    ? ["anthropic", ...[...families].filter(family => family !== "anthropic")]
+    : ["openai", ...[...families].filter(family => family !== "openai")];
+  return ordered.some(provider => modelAcceptsImageInput(config, { provider, id: requested }) === false);
 }
 
 /** The 400 body both routes return, so the two errors cannot diverge either. */

package/src/server/responses/compact.ts

@@ -461,7 +461,6 @@ export async function handleResponsesCompact(
       }
       compactHostAdmissionLease = null;
     };
-    const compactThreadId = req.headers.get("x-codex-parent-thread-id");
     const connectMs = config.connectTimeoutMs ?? 200_000;
     // Takes its context explicitly: the alternate-account flow below records a rejection
     // against A while promoting B, then records B's own outcome. A closure over a single
@@ -478,7 +477,7 @@ export async function handleResponsesCompact(
       if (!usesCodexForwardPoolAuth(ctx, route.provider)) return;
       recordCodexUpstreamOutcome(config, ctx.accountId, outcome, {
         ...meta,
-        threadId: compactThreadId,
+        threadId: ctx.kind === "pool" || ctx.kind === "main-pool" ? ctx.affinityKey : undefined,
         fixedAccount: ctx.fixedAccount,
         modelId: selectedModelId,
         probeLeaseId: codexProbeLeaseId(ctx),

package/src/server/responses/core.ts

@@ -111,6 +111,7 @@ import { describeImagesInPlace, isModelTextOnly, planVisionSidecar, resolveOpenA
 import { createAdapterEventQueue, preflightAdapterEvents, type AdapterEventQueue } from "../../adapters/run-turn-queue";
 import {
   applyCodexAuthContextToProvider,
+  codexPoolAffinityKey,
   CodexAccountCooldownError,
   codexMainProfileDrainingResponse,
   cooldownErrorResponse,
@@ -139,6 +140,7 @@ import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "../../codex/catalog/native-m
 import { captureCodexAffinityDiagnostic } from "../../codex/affinity-debug";
 import {
   computeQuotaCooldown,
+  codexQuotaScopeForModel,
   formatCodexProviderForLog,
   previewCodexAccountForRequest,
   recordCodexUpstreamOutcome,
@@ -328,11 +330,10 @@ export function adapterNeedsForcedContinuation(name: string): boolean {
 export function sidecarOutcomeRecorder(
   config: OcxConfig,
   authCtx: CodexAuthContext,
-  threadId?: string | null,
 ): ((outcome: CodexUpstreamOutcome) => void) | undefined {
   return authCtx.kind === "pool" || authCtx.kind === "main-pool"
     ? outcome => recordCodexUpstreamOutcome(config, authCtx.accountId, outcome, {
-      threadId,
+      threadId: authCtx.affinityKey,
       fixedAccount: authCtx.fixedAccount,
       probeLeaseId: authCtx.probeLeaseId,
       probeQuotaScope: authCtx.probeQuotaScope,
@@ -946,7 +947,7 @@ async function retryCodexPoolOnAlternateAccount(
   const recordFirstOutcome = (): void => {
     recordCodexUpstreamOutcome(config, firstAuthCtx.accountId, outcomeStatus, {
       ...quotaMeta,
-      threadId: req.headers.get("x-codex-parent-thread-id"),
+      threadId: firstAuthCtx.affinityKey,
       modelId: route.modelId,
       probeLeaseId: codexProbeLeaseId(firstAuthCtx),
       probeQuotaScope: codexProbeQuotaScope(firstAuthCtx),
@@ -1081,7 +1082,6 @@ export function codexForwardTerminalOutcomeRecorder(
   provider: OcxProviderConfig,
   modelId?: string,
   logCtx?: RequestLogContext,
-  threadId?: string | null,
 ): ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined {
   if (!usesCodexForwardPoolAuth(authCtx, provider)) return undefined;
   return (status, httpStatusOverride) => {
@@ -1090,7 +1090,7 @@ export function codexForwardTerminalOutcomeRecorder(
       // request. Don't penalize account health; record success to clear any
       // prior soft-avoid so a healthy account isn't stuck avoided.
       recordCodexUpstreamOutcome(config, authCtx.accountId, 200, {
-        threadId,
+        threadId: authCtx.affinityKey,
         fixedAccount: authCtx.fixedAccount,
         modelId,
         probeLeaseId: codexProbeLeaseId(authCtx),
@@ -1112,7 +1112,7 @@ export function codexForwardTerminalOutcomeRecorder(
       ? 200
       : (httpStatusOverride ?? logCtx?.terminalHttpStatus ?? 502);
     recordCodexUpstreamOutcome(config, authCtx.accountId, outcome, {
-      threadId,
+      threadId: authCtx.affinityKey,
       fixedAccount: authCtx.fixedAccount,
       modelId,
       probeLeaseId: codexProbeLeaseId(authCtx),
@@ -1227,6 +1227,15 @@ export interface HandleResponsesOptions {
   onConsumedComboFailure?: (failure: ConsumedComboFailure) => void;
   /** Caller-owned for Chat/Claude replay; omitted only at genuine Responses ingress. */
   translatorBudget?: TranslatorBudget;
+  /**
+   * Terminal vision-describe marker (roadmap 180): true when the inbound
+   * request IS the vision sidecar's own loopback describe call. The plan site
+   * then STRIPS images instead of planning another describe — a depth cap of 1
+   * that holds under predicate drift and combo re-resolution. The Chat surface
+   * detects the raw `x-opencodex-vision-describe` header before its bridge
+   * rebuilds headers and carries the fact through this flag.
+   */
+  visionDescribeTerminal?: boolean;
 }
 
 
@@ -2177,6 +2186,27 @@ async function handleResponsesInner(
     if (inboundClientThreadId) {
       parsed._clientThreadId = inboundClientThreadId;
       parsed._reasoningReplayScope = { clientThreadId: inboundClientThreadId };
+    } else if (
+      options.inboundWire === "anthropic"
+      && options.promptCacheKeyIsSharedCohort !== true
+      && typeof parsed.options.promptCacheKey === "string"
+      && parsed.options.promptCacheKey.trim().length > 0
+    ) {
+      // Claude Code has no Codex parent-thread header, but its metadata.user_id is
+      // translated into a stable per-session prompt_cache_key. Use it as the replay
+      // thread identity so Gemini thought signatures are remembered by call_id for
+      // Anthropic Messages clients too (#1735/#1926). Keep `_clientThreadId` unset so
+      // existing provider session-id derivation (first-user-text fallback) is unchanged.
+      // Normalize through anthropicSessionKeyFromParts so overlong keys are hashed and
+      // trimming matches the affinity/session-key path exactly (no raw >128-char ids).
+      const normalizedCacheKey = anthropicSessionKeyFromParts({
+        promptCacheKey: parsed.options.promptCacheKey,
+        // The enclosing branch already proves this is not the shared cohort.
+        promptCacheKeyIsSharedCohort: false,
+      });
+      if (normalizedCacheKey) {
+        parsed._reasoningReplayScope = { clientThreadId: normalizedCacheKey };
+      }
     }
   } catch (err) {
     if (isTranslatorBudgetExceededError(err)) {
@@ -2278,6 +2308,7 @@ async function handleResponsesInner(
   let subagentFallbackPreviewAccountId: string | null | undefined;
   let subagentQuotaFailureModel = parsed.modelId;
   const parentThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() ?? null;
+  const poolAffinityKey = codexPoolAffinityKey(req.headers) ?? null;
 
   try {
     if (
@@ -2293,12 +2324,15 @@ async function handleResponsesInner(
   // Preview the preferred Codex account without acquiring a probe lease or refreshing
   // tokens — auth is resolved only after the final route is selected.
   if (threadSpawn && !options.comboAttempt && route.codexAccountId === undefined) {
-    const threadId = req.headers.get("x-codex-parent-thread-id");
+    // The final resolveCodexAuthContext binds under codexQuotaScopeForModel(route.modelId),
+    // so the preview must read the same scope slot — an undefined scope would map to the
+    // "legacy" affinity bucket and never find a binding made under "shared" or a native
+    // model scope, making the preview diverge from the account that actually authenticates.
     const previewAccountId = previewCodexAccountForRequest(
-      threadId,
+      poolAffinityKey,
       config,
       Date.now(),
-      undefined,
+      codexQuotaScopeForModel(route.modelId),
       previewSelectionOptions,
     );
     subagentFallbackPreviewAccountId = previewAccountId;
@@ -2725,7 +2759,15 @@ async function handleResponsesInner(
   // Vision sidecar: the routed model can't see images (provider.noVisionModels). Describe each
   // attached image through the selected sidecar backend and replace it with text BEFORE the main
   // call, so the text-only model can reason about it.
-  const visionPlan = planVisionSidecar(config, route.provider, route.modelId, parsed, openAiSidecar);
+  // Terminal describe fence (roadmap 180): the sidecar's OWN loopback describe
+  // call must never plan another describe. The flag arrives from the Chat
+  // surface (whose bridge rebuilds headers) or as the raw header for native
+  // Responses callers. Marked + text-only routed model → strip, depth cap 1.
+  const visionDescribeTerminal = options.visionDescribeTerminal === true
+    || req.headers.get("x-opencodex-vision-describe") === "1";
+  const visionPlan = visionDescribeTerminal
+    ? undefined
+    : planVisionSidecar(config, route.provider, route.modelId, parsed, openAiSidecar);
   const recordSidecarOutcome = openAiSidecar?.recordOutcome;
   if (visionPlan) {
     await describeImagesInPlace(
@@ -3005,7 +3047,7 @@ async function handleResponsesInner(
       }
       if (usesCodexForwardPoolAuth(authCtx, route.provider)) {
         recordCodexUpstreamOutcome(config, authCtx.accountId, outcome, {
-          threadId: req.headers.get("x-codex-parent-thread-id"),
+          threadId: authCtx.affinityKey,
           fixedAccount: authCtx.fixedAccount,
           modelId: route.modelId,
           probeLeaseId: codexProbeLeaseId(authCtx),
@@ -3388,7 +3430,6 @@ async function handleResponsesInner(
       route.provider,
       route.modelId,
       logCtx,
-      req.headers.get("x-codex-parent-thread-id"),
     );
     const terminalBodyWillRecord = !!terminalRecorder && upstreamResponse.ok && isEventStream;
     // Capture quota from upstream response for multi-account tracking
@@ -3429,7 +3470,7 @@ async function handleResponsesInner(
       )) {
         recordCodexUpstreamOutcome(config, authCtx.accountId, upstreamResponse.status, {
           ...quotaMeta,
-          threadId: req.headers.get("x-codex-parent-thread-id"),
+          threadId: authCtx.affinityKey,
           fixedAccount: authCtx.fixedAccount,
           modelId: route.modelId,
           probeLeaseId: codexProbeLeaseId(authCtx),