@bitkyc08/opencodex 2.14.0 → 2.14.2

package/src/providers/registry.ts

@@ -6,6 +6,7 @@ import {
   QWEN_CLOUD_BASE_URL_CHOICES, QWEN_CLOUD_TOKEN_PLAN_BASE_URL,
   ALIBABA_INTL_BASE_URL_CHOICES, ALIBABA_INTL_TOKEN_PLAN_BASE_URL,
   ALIBABA_CODING_BASE_URL_CHOICES, ALIBABA_CODING_INTL_BASE_URL,
+  MOONSHOT_BASE_URL_CHOICES, MOONSHOT_INTL_BASE_URL,
 } from "./base-url-choices";
 import {
   CURSOR_STATIC_MODELS,
@@ -950,8 +951,8 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // devlog/model_update/260709_model_refresh/001_xai_lineup.md.
     // grok-4.20-multi-agent-0309 is intentionally absent: the OAuth chat-completions
     // transport returns 400 ("Multi Agent requests are not allowed on chat completions").
-    // 260813: grok-4.6 added per the new docs.x.ai/developers/grok-4-6 page; specs mirrored
-    // from grok-4.5 until the official capability/pricing tables settle.
+    // 260813: grok-4.6 added per docs.x.ai/developers/grok-4-6. Context/vision still match
+    // grok-4.5; the reasoning ladder does not — 4.6 adds the documented xhigh rung.
     models: ["grok-4.6", "grok-4.5", "grok-4.3", "grok-4.20-0309-reasoning", "grok-4.20-0309-non-reasoning", "grok-build-0.1", "grok-composer-2.5-fast"],
     defaultModel: "grok-4.5",
     // Vision lineup per docs.x.ai model-capabilities/images/understanding: the grok-4.x chat
@@ -973,8 +974,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // (docs.x.ai prompt-caching/multi-turn, verified 2026-07-13 — devlog/_plan/260713_grok_caching).
     // Models that never emit reasoning simply have no thinking parts to replay (no-op).
     preserveReasoningContentModels: ["grok-4.6", "grok-4.5", "grok-4.3", "grok-4.20-0309-reasoning"],
-    // grok-4.5 reasoning is always-on with low/medium/high control (no off tier upstream).
-    modelReasoningEfforts: { "grok-4.6": ["low", "medium", "high"], "grok-4.5": ["low", "medium", "high"] },
+    // grok-4.5 reasoning is always-on with low/medium/high (no off tier, no xhigh).
+    // grok-4.6 adds xhigh per docs.x.ai/developers/model-capabilities/text/reasoning;
+    // xAI documents high as the upstream default.
+    modelReasoningEfforts: { "grok-4.6": ["low", "medium", "high", "xhigh"], "grok-4.5": ["low", "medium", "high"] },
+    modelDefaultReasoningEfforts: { "grok-4.6": "high" },
     modelContextWindows: {
       "grok-4.6": 500_000,
       "grok-4.5": 500_000,
@@ -1300,10 +1304,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: CLINE_PASS_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: CLINE_PASS_MODEL_INPUT_MODALITIES,
     noVisionModels: CLINE_PASS_TEXT_ONLY_MODELS,
-    // Only low and the `reasoning: { enabled, effort }` request shape have been accepted by a live
-    // ClinePass request. Neither wire detail is currently documented, so clamp higher Codex
-    // requests to the verified tier until the gateway documents or is live-probed more broadly.
-    reasoningEfforts: ["low"],
+    // Live-probed 2026-08-13 across every static ClinePass model: the gateway accepts and
+    // validates low/medium/high/xhigh/max, and rejects an invalid sentinel. Preserve the
+    // caller's requested tier and let ClinePass own any backend-specific normalization.
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
     reasoningWireFormat: "gateway-object",
     preserveCustomDestination: true,
     note: "ClinePass subscription API. Uses a Cline API key and the full cline-pass/<model> upstream slug; quota is shared across the account's rolling 5-hour, weekly, and monthly limits.",
@@ -1789,7 +1793,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     liveModels: true,
     preserveCustomDestination: true,
     // /v1/models is documented as callable authenticated or unauthenticated, so a 2xx catalog
-    // response cannot prove the supplied Bearer key is valid.
+    // response cannot prove that the supplied Bearer key is valid.
     apiKeyValidation: "unknown",
     // Featherless documents tool calling, but not a provider-wide parallel tool-call contract.
     parallelToolCalls: false,
@@ -1870,7 +1874,9 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     note: "Model data frozen pending Tier-2 entitlement proof",
   },
   {
-    id: "moonshot", label: "Moonshot (Kimi API)", baseUrl: "https://api.moonshot.ai/v1", adapter: "openai-chat", authKind: "key",
+    id: "moonshot", label: "Moonshot (Kimi API)", baseUrl: MOONSHOT_INTL_BASE_URL, adapter: "openai-chat", authKind: "key",
+    allowBaseUrlOverride: true,
+    baseUrlChoices: MOONSHOT_BASE_URL_CHOICES,
     dashboardUrl: "https://platform.moonshot.ai/console/api-keys", defaultModel: "kimi-k2.7-code", jawcodeBundle: "moonshot",
     models: KIMI_API_MODELS,
     modelContextWindows: KIMI_API_MODEL_CONTEXT_WINDOWS,
@@ -1882,6 +1888,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     noPenaltyModels: KIMI_API_MODELS,
     autoToolChoiceOnlyModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     preserveReasoningContentModels: KIMI_API_MODELS,
+    note: "International default (api.moonshot.ai). China accounts: choose China (.cn) or Custom for api.moonshot.cn.",
   },
   { id: "huggingface", label: "Hugging Face", baseUrl: "https://router.huggingface.co/v1", adapter: "openai-chat", authKind: "key", dashboardUrl: "https://huggingface.co/settings/tokens" },
   // 260715 NIM hardening (issue #126, devlog/_plan/260715_issue126_nim_kimi):

package/src/responses/spill-store.ts

@@ -34,6 +34,7 @@ export interface ResponseSpillPayload {
   version: 1;
   responseId: string;
   createdAt: number;
+  clientThreadId?: string;
   items: unknown[];
   providers?: OcxProviderContinuationState;
 }
@@ -260,9 +261,11 @@ function validPayload(value: unknown, responseId: string): value is ResponseSpil
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const payload = value as Record<string, unknown>;
   const keys = Object.keys(payload);
-  if (keys.some(key => !["version", "responseId", "createdAt", "items", "providers"].includes(key))) return false;
+  if (keys.some(key => !["version", "responseId", "createdAt", "clientThreadId", "items", "providers"].includes(key))) return false;
   if (payload.version !== 1 || payload.responseId !== responseId) return false;
   if (typeof payload.createdAt !== "number" || !Number.isFinite(payload.createdAt)) return false;
+  if (payload.clientThreadId !== undefined
+    && (typeof payload.clientThreadId !== "string" || payload.clientThreadId.trim().length === 0)) return false;
   if (!Array.isArray(payload.items)) return false;
   if (payload.providers !== undefined) {
     if (!payload.providers || typeof payload.providers !== "object" || Array.isArray(payload.providers)) return false;
@@ -284,6 +287,7 @@ export function writeResponseSpillDurably(
       version: 1,
       responseId,
       createdAt: state.createdAt,
+      ...(state.clientThreadId ? { clientThreadId: state.clientThreadId } : {}),
       items: state.items,
       ...(state.providers ? { providers: state.providers } : {}),
     };

package/src/responses/state.ts

@@ -37,6 +37,7 @@ const MAX_SNAPSHOT_REWRITE_ATTEMPTS = 4;
 interface ResidentResponseState {
   kind: "resident";
   createdAt: number;
+  clientThreadId?: string;
   items: unknown[];
   providers?: OcxProviderContinuationState;
   sizeBytes: number;
@@ -45,6 +46,7 @@ interface ResidentResponseState {
 interface SpilledResponseState {
   kind: "spill";
   createdAt: number;
+  clientThreadId?: string;
   providers?: OcxProviderContinuationState;
   spill: ResponseSpillRef;
   sizeBytes: number;
@@ -65,6 +67,7 @@ export type PreviousResponseReplayFailure = {
 };
 
 const states = new Map<string, StoredResponseState>();
+const replayScopeMismatches = new WeakSet<object>();
 let storedResponseBytes = 0;
 let residentResponseBytes = 0;
 let oldestResidentId: string | undefined;
@@ -80,6 +83,7 @@ const spillCounters = { writes: 0, writeFailures: 0, readFailures: 0 };
  * snapshot files refused before parse.
  */
 const admissionCounters = { directSpills: 0, oversizedDrops: 0, snapshotOversizedRefusals: 0 };
+let replayScopeMismatchDrops = 0;
 
 /** Test-only: admission-boundary counters (proves the new paths fire). */
 export function responseAdmissionCountersForTests(): Readonly<typeof admissionCounters> {
@@ -124,6 +128,7 @@ function measureResidentEntry(id: string, entry: ResidentInput): ResidentRespons
   const sizeBytes = serializedBytes({
     responseId: id,
     createdAt: entry.createdAt,
+    ...(entry.clientThreadId ? { clientThreadId: entry.clientThreadId } : {}),
     items: entry.items,
     ...(entry.providers ? { providers: entry.providers } : {}),
   });
@@ -224,6 +229,7 @@ function swapResidentForSpill(id: string, expected: ResidentResponseState, ref:
   const base: Omit<SpilledResponseState, "sizeBytes"> = {
     kind: "spill",
     createdAt: expected.createdAt,
+    ...(expected.clientThreadId ? { clientThreadId: expected.clientThreadId } : {}),
     ...(expected.providers ? { providers: expected.providers } : {}),
     spill: ref,
   };
@@ -244,12 +250,14 @@ function replaceSpillEntryAtomically(
   try {
     const ref = writeResponseSpillDurably(id, {
       createdAt: candidate.createdAt,
+      ...(candidate.clientThreadId ? { clientThreadId: candidate.clientThreadId } : {}),
       items: candidate.items,
       ...(candidate.providers ? { providers: candidate.providers } : {}),
     });
     const base: Omit<SpilledResponseState, "sizeBytes"> = {
       kind: "spill",
       createdAt: candidate.createdAt,
+      ...(candidate.clientThreadId ? { clientThreadId: candidate.clientThreadId } : {}),
       ...(candidate.providers ? { providers: candidate.providers } : {}),
       spill: ref,
     };
@@ -322,6 +330,7 @@ function admitOversizedCandidate(
   try {
     const ref = writeResponseSpillDurably(id, {
       createdAt: candidate.createdAt,
+      ...(candidate.clientThreadId ? { clientThreadId: candidate.clientThreadId } : {}),
       items: candidate.items,
       ...(candidate.providers ? { providers: candidate.providers } : {}),
     });
@@ -337,6 +346,7 @@ function admitOversizedCandidate(
     const base: Omit<SpilledResponseState, "sizeBytes"> = {
       kind: "spill",
       createdAt: candidate.createdAt,
+      ...(candidate.clientThreadId ? { clientThreadId: candidate.clientThreadId } : {}),
       ...(candidate.providers ? { providers: candidate.providers } : {}),
       spill: ref,
     };
@@ -385,6 +395,7 @@ function snapshotPath(): string {
 
 interface LegacySnapshotState {
   createdAt?: unknown;
+  clientThreadId?: unknown;
   items?: unknown;
   providers?: OcxProviderContinuationState;
   conversationId?: unknown;
@@ -405,11 +416,15 @@ function loadSnapshotEntry(id: string, value: unknown): void {
   if (!value || typeof value !== "object" || Array.isArray(value)) return;
   const rec = value as LegacySnapshotState & { kind?: unknown; spill?: unknown };
   if (typeof rec.createdAt !== "number" || !Number.isFinite(rec.createdAt)) return;
+  const clientThreadId = typeof rec.clientThreadId === "string" && rec.clientThreadId.trim().length > 0
+    ? rec.clientThreadId.trim()
+    : undefined;
   if (rec.kind === "spill") {
     if (!isSpillRef(rec.spill)) return;
     const base: Omit<SpilledResponseState, "sizeBytes"> = {
       kind: "spill",
       createdAt: rec.createdAt,
+      ...(clientThreadId ? { clientThreadId } : {}),
       ...(rec.providers ? { providers: rec.providers } : {}),
       spill: rec.spill,
     };
@@ -434,6 +449,7 @@ function loadSnapshotEntry(id: string, value: unknown): void {
     : undefined);
   const resident = measureResidentEntry(id, {
     createdAt: rec.createdAt,
+    ...(clientThreadId ? { clientThreadId } : {}),
     items: rec.items,
     ...(providers ? { providers } : {}),
   });
@@ -747,6 +763,7 @@ function pruneResponses(at = now()): void {
     try {
       const ref = writeResponseSpillDurably(oldestId, {
         createdAt: entry.createdAt,
+        ...(entry.clientThreadId ? { clientThreadId: entry.clientThreadId } : {}),
         items: entry.items,
         ...(entry.providers ? { providers: entry.providers } : {}),
       });
@@ -788,6 +805,7 @@ export function evictOldestResponseContinuationForBudget(): number {
   try {
     const ref = writeResponseSpillDurably(id, {
       createdAt: entry.createdAt,
+      ...(entry.clientThreadId ? { clientThreadId: entry.clientThreadId } : {}),
       items: entry.items,
       ...(entry.providers ? { providers: entry.providers } : {}),
     });
@@ -828,6 +846,7 @@ function materializeEntry(
   }
   const state = measureResidentEntry(id, {
     createdAt: result.payload.createdAt,
+    ...(result.payload.clientThreadId ? { clientThreadId: result.payload.clientThreadId } : {}),
     items: result.payload.items,
     ...(result.payload.providers ? { providers: result.payload.providers } : {}),
   });
@@ -840,7 +859,16 @@ function materializeEntry(
   return { ok: true, state };
 }
 
-export function expandPreviousResponseInput(body: unknown): unknown {
+function normalizedClientThreadId(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function withoutPreviousResponseId(request: Record<string, unknown>): Record<string, unknown> {
+  const { previous_response_id: _previousResponseId, ...freshRequest } = request;
+  return freshRequest;
+}
+
+export function expandPreviousResponseInput(body: unknown, clientThreadId?: string): unknown {
   if (!body || typeof body !== "object" || Array.isArray(body)) return body;
   const request = body as Record<string, unknown>;
   const previousId = typeof request.previous_response_id === "string" ? request.previous_response_id : undefined;
@@ -854,6 +882,16 @@ export function expandPreviousResponseInput(body: unknown): unknown {
     replayFailures.set(request, materialized.failure);
     return body;
   }
+  const requestThreadId = normalizedClientThreadId(clientThreadId);
+  const storedThreadId = normalizedClientThreadId(materialized.state.clientThreadId);
+  // A Codex task must never inherit another task's continuation, nor a legacy unscoped entry.
+  // Unscoped callers retain backward-compatible replay only with other unscoped entries.
+  if (requestThreadId !== storedThreadId) {
+    const freshRequest = withoutPreviousResponseId(request);
+    replayScopeMismatches.add(freshRequest);
+    replayScopeMismatchDrops += 1;
+    return freshRequest;
+  }
   const expanded = {
     ...request,
     input: [...materialized.state.items, ...inputItems(request.input)],
@@ -873,6 +911,11 @@ export function previousResponseReplayPrefixLength(body: unknown): number {
   return replayedInputPrefixLengths.get(body) ?? 0;
 }
 
+/** True when a stale or foreign previous_response_id was removed from this exact request body. */
+export function previousResponseScopeMismatch(body: unknown): boolean {
+  return !!body && typeof body === "object" && replayScopeMismatches.has(body as object);
+}
+
 export function previousResponseConversationId(responseId: string | undefined): string | undefined {
   return previousResponseProviderState(responseId)?.cursor?.conversationId;
 }
@@ -898,6 +941,7 @@ export interface ResponseStateMetrics {
   spillWrites: number;
   spillWriteFailures: number;
   spillReadFailures: number;
+  replayScopeMismatchDrops: number;
 }
 
 /**
@@ -940,6 +984,7 @@ export function responseStateMetrics(): ResponseStateMetrics {
     spillWrites: spillCounters.writes,
     spillWriteFailures: spillCounters.writeFailures,
     spillReadFailures: spillCounters.readFailures,
+    replayScopeMismatchDrops,
   };
 }
 
@@ -972,7 +1017,7 @@ export function rememberResponseState(
   requestBody: unknown,
   response: { id?: unknown; output?: unknown; status?: unknown; incomplete_details?: unknown },
   providerState?: OcxProviderContinuationState | string,
-  opts?: { force?: boolean },
+  opts?: { force?: boolean; clientThreadId?: string },
 ): void {
   if (!requestBody || typeof requestBody !== "object" || Array.isArray(requestBody)) return;
   const request = requestBody as Record<string, unknown>;
@@ -998,8 +1043,10 @@ export function rememberResponseState(
       return !!item && typeof item === "object" && (item as { type?: unknown }).type === "function_call";
     });
   }
+  const clientThreadId = normalizedClientThreadId(opts?.clientThreadId);
   setResidentEntry(response.id, {
     createdAt: now(),
+    ...(clientThreadId ? { clientThreadId } : {}),
     items: [...inputItems(request.input), ...response.output],
     // Always preserve the Cursor conversation id so the next tool-result turn can continue the SAME
     // Cursor conversation (multi-turn continuation). Separately track whether Cursor's own
@@ -1045,6 +1092,7 @@ export function clearResponseStateMemoryForTests(): void {
   spillCounters.writes = 0;
   spillCounters.writeFailures = 0;
   spillCounters.readFailures = 0;
+  replayScopeMismatchDrops = 0;
   persistAttemptHookForTests = null;
   loaded = false;
 }

package/src/router.ts

@@ -267,6 +267,14 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
   const modelReasoningEffortMap = mergeNestedRecord(registryEntry.modelReasoningEffortMap, provider.modelReasoningEffortMap);
   const modelReasoningEfforts = mergeStringArrayRecord(registryEntry.modelReasoningEfforts, provider.modelReasoningEfforts);
   const modelDefaultReasoningEfforts = mergeRecordFill(registryEntry.modelDefaultReasoningEfforts, provider.modelDefaultReasoningEfforts);
+  // Key-login used to persist this exact low-only ClinePass capability seed. Once the gateway's
+  // wider input ladder was live-verified, leaving that generated row untouched would keep old
+  // installs clamped forever. This branch is reached only after canonical transport matching, so
+  // same-named custom destinations and every other explicit ladder still retain user precedence.
+  const repairLegacyClinePassReasoningEfforts = providerName === "cline-pass"
+    && provider.reasoningWireFormat === "gateway-object"
+    && provider.reasoningEfforts?.length === 1
+    && provider.reasoningEfforts[0] === "low";
   const modelContextWindows = providerName === OPENAI_API_PROVIDER_ID
     ? mergePositiveNumberCaps(registryEntry.modelContextWindows, provider.modelContextWindows)
     : mergeRecordFill(registryEntry.modelContextWindows, provider.modelContextWindows);
@@ -342,7 +350,10 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.project === undefined && registryEntry.project !== undefined ? { project: registryEntry.project } : {}),
     ...(provider.location === undefined && registryEntry.location !== undefined ? { location: registryEntry.location } : {}),
     ...(provider.contextWindow === undefined && registryEntry.contextWindow !== undefined ? { contextWindow: registryEntry.contextWindow } : {}),
-    ...(provider.reasoningEfforts === undefined && registryEntry.reasoningEfforts !== undefined ? { reasoningEfforts: registryEntry.reasoningEfforts } : {}),
+    ...((provider.reasoningEfforts === undefined || repairLegacyClinePassReasoningEfforts)
+      && registryEntry.reasoningEfforts !== undefined
+      ? { reasoningEfforts: [...registryEntry.reasoningEfforts] }
+      : {}),
     ...(provider.escapeBuiltinToolNames === undefined && registryEntry.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: registryEntry.escapeBuiltinToolNames } : {}),
     ...(provider.keyOptional === undefined && registryEntry.keyOptional !== undefined ? { keyOptional: registryEntry.keyOptional } : {}),
     ...(provider.modelSuffixBracketStrip === undefined && registryEntry.modelSuffixBracketStrip !== undefined ? { modelSuffixBracketStrip: registryEntry.modelSuffixBracketStrip } : {}),

package/src/server/index.ts

@@ -53,6 +53,7 @@ import { loadLabAutomationPolicy } from "../lab/automation/persistence";
 import { createProductionLabRouteExecutor } from "../lib/lab-live-route-production";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { runAlibabaRegionStartupMigration } from "../providers/alibaba-region-startup";
+import { runModelRenameStartupMigration } from "../providers/model-rename-startup";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerContextCap } from "../providers/context-cap";
 import { providerCodexAccountMode } from "../providers/registry";
@@ -485,12 +486,12 @@ export function warnAgentTaskRecoveryStartup(config: {
   if (config.agentTaskRecovery?.enabled !== true) return;
   console.warn("⚠️  Experimental encrypted V2 task recovery is enabled.");
   console.warn("   A scoped cache miss may send an additional authenticated request to ChatGPT and may consume quota or add latency; concurrent misses can share one request.");
-  console.warn("   Recovered model output is retained only in a bounded in-memory cache; exact fidelity is not guaranteed and the path depends on undocumented backend behavior.");
+  console.warn("   Recovered plaintext assignment data is retained only in a bounded, process-local in-memory cache; exact fidelity is not guaranteed and the path depends on undocumented backend behavior.");
 }
 
 export function startServer(port?: number, deps: StartServerDeps = {}): Server<WsData> {
   const localAttestationSecret = deps.localAttestationSecret ?? createLocalAttestationSecret();
-  const config = runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig()));
+  const config = runModelRenameStartupMigration(runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig())));
   warnAgentTaskRecoveryStartup(config);
   setLiveStateStoreConfig(config);
   applyProxyEnv(config);

package/src/server/management/api-key-usage.ts

@@ -1,7 +1,7 @@
 import {
   currentUsageLogRevision,
   readUsageSnapshotForManagement,
-  usageLogRevisionKey,
+  usageLogIdentityKey,
   type PersistedUsageEntry,
 } from "../../usage/log";
 
@@ -110,7 +110,7 @@ export function rollupApiKeyUsage(
  * create/rename/delete. The compact rollup is a handful of counters per key, so
  * caching it costs nothing; a new row changes the revision and invalidates it.
  */
-let rollupCache: { revisionKey: string; expiresAt: number; snapshot: ApiKeyUsageSnapshot } | null = null;
+let rollupCache: { revisionKey: string; expiresAt: number; lastSeenSize?: number; snapshot: ApiKeyUsageSnapshot } | null = null;
 
 /**
  * The rollup is a function of the log AND of the clock: a request ages out of
@@ -136,6 +136,29 @@ export function clearApiKeyUsageCacheForTests(): void {
  * `attributionSince`. Key management working matters more than usage numbers
  * being present, and the GUI already treats an absent field as "no data".
  */
+export function cacheApiKeyUsageFromSnapshot(
+  entries: PersistedUsageEntry[],
+  configuredIds: string[],
+  identityKey: string,
+  lastSeenSize: number,
+  truncated: boolean,
+  maxReadBytes: number | undefined,
+  now: number = Date.now(),
+): ApiKeyUsageSnapshot {
+  const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
+  const rolled = {
+    ...rollupApiKeyUsage(entries, configuredIds, now),
+    ...(truncated ? { historyTruncated: true as const } : {}),
+  };
+  rollupCache = {
+    revisionKey: `${identityKey}|${idsKey}`,
+    expiresAt: now + ROLLUP_CACHE_TTL_MS,
+    lastSeenSize,
+    snapshot: rolled,
+  };
+  return rolled;
+}
+
 export async function readApiKeyUsageRollup(configuredIds: string[], maxReadBytes?: number): Promise<ApiKeyUsageSnapshot> {
   // JSON rather than a joined string: ids are only validated as non-empty
   // strings, so `["a\0b","c"]` and `["a","b\0c"]` join to the same value and one
@@ -143,8 +166,10 @@ export async function readApiKeyUsageRollup(configuredIds: string[], maxReadByte
   const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
   const now = Date.now();
   try {
-    const observedKey = `${usageLogRevisionKey(currentUsageLogRevision())}|${idsKey}`;
-    if (rollupCache?.revisionKey === observedKey && now < rollupCache.expiresAt) {
+    const observed = currentUsageLogRevision();
+    const observedKey = `${usageLogIdentityKey(observed)}|${idsKey}`;
+    const observedSize = observed?.size ?? 0;
+    if (rollupCache?.revisionKey === observedKey && now < rollupCache.expiresAt && observedSize >= (rollupCache.lastSeenSize ?? 0)) {
       return rollupCache.snapshot;
     }
 
@@ -154,8 +179,9 @@ export async function readApiKeyUsageRollup(configuredIds: string[], maxReadByte
       ...(snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated ? { historyTruncated: true as const } : {}),
     };
     rollupCache = {
-      revisionKey: `${usageLogRevisionKey(snapshot.revision)}|${idsKey}`,
+      revisionKey: `${usageLogIdentityKey(snapshot.revision)}|${idsKey}`,
       expiresAt: now + ROLLUP_CACHE_TTL_MS,
+      lastSeenSize: snapshot.revision?.size ?? 0,
       snapshot: rolled,
     };
     return rolled;

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

@@ -54,7 +54,16 @@ import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../../reasoning-effort";
 import { normalizeVisionReasoningForModel } from "../../vision/reasoning";
-import { findAnthropicVisionProvider, resolveEffectiveVisionModel, resolveVisionBackend } from "../../vision";
+import {
+  findAnthropicVisionProvider,
+  isValidVisionTimeoutMs,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+  resolveEffectiveVisionModel,
+  resolveMaxDescriptionsPerTurn,
+  resolveVisionBackend,
+  resolveVisionTimeoutMs,
+} from "../../vision";
 import {
   visionCandidateRows,
   visionDescriberIsProvablyBlind,
@@ -108,6 +117,21 @@ async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
   return { model, reasoning, models };
 }
 
+function publicVisionSidecarSettings(
+  config: OcxConfig,
+  vision: Awaited<ReturnType<typeof sidecarVisionResponseSettings>>,
+) {
+  const vs = config.visionSidecar ?? {};
+  return {
+    enabled: vs.enabled !== false,
+    model: vision.model,
+    backend: vs.backend,
+    reasoning: vision.reasoning,
+    maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(vs.maxDescriptionsPerTurn),
+    timeoutMs: resolveVisionTimeoutMs(vs.timeoutMs),
+  };
+}
+
 export async function handleConfigRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
   if (url.pathname === "/api/config" && req.method === "GET") {
@@ -407,7 +431,6 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
 
   if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
     const ws = config.webSearchSidecar ?? {};
-    const vs = config.visionSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       webSearch: {
@@ -415,12 +438,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
       },
-      vision: {
-        model: vision.model,
-        backend: vs.backend,
-        reasoning: vision.reasoning,
-        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
-      },
+      vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
     });
   }
@@ -435,7 +453,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
     const body = raw as {
       webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown };
-      vision?: { model?: unknown; backend?: unknown; reasoning?: unknown; maxDescriptionsPerTurn?: unknown };
+      vision?: {
+        model?: unknown;
+        backend?: unknown;
+        reasoning?: unknown;
+        maxDescriptionsPerTurn?: unknown;
+        enabled?: unknown;
+        timeoutMs?: unknown;
+      };
     };
     if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
       && body.webSearch.backend !== "openai" && body.webSearch.backend !== "anthropic") {
@@ -455,6 +480,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         || body.vision.maxDescriptionsPerTurn <= 0)) {
       return jsonResponse({ error: "vision.maxDescriptionsPerTurn must be a positive integer" }, 400);
     }
+    if (body.vision && body.vision.enabled !== undefined && typeof body.vision.enabled !== "boolean") {
+      return jsonResponse({ error: "vision.enabled must be a boolean" }, 400);
+    }
+    if (body.vision && body.vision.timeoutMs !== undefined && !isValidVisionTimeoutMs(body.vision.timeoutMs)) {
+      return jsonResponse({
+        error: `vision.timeoutMs must be an integer from ${MIN_VISION_TIMEOUT_MS} to ${MAX_VISION_TIMEOUT_MS}`,
+      }, 400);
+    }
     if (body.vision?.reasoning !== undefined && !isVisionReasoningEffort(body.vision.reasoning)) {
       return jsonResponse({ error: `vision.reasoning must be ${VISION_REASONING_EFFORTS.join(", ")}` }, 400);
     }
@@ -517,6 +550,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {
         config.visionSidecar.maxDescriptionsPerTurn = body.vision.maxDescriptionsPerTurn;
       }
+      if (typeof body.vision.enabled === "boolean") {
+        // `true` is the default — drop the key so disable/re-enable does not rewrite the file.
+        if (body.vision.enabled) delete config.visionSidecar.enabled;
+        else config.visionSidecar.enabled = false;
+      }
+      if (typeof body.vision.timeoutMs === "number") {
+        config.visionSidecar.timeoutMs = body.vision.timeoutMs;
+      }
       if (visionReasoningTouched) {
         if (normalizedVisionReasoning === undefined) delete config.visionSidecar.reasoning;
         else config.visionSidecar.reasoning = normalizedVisionReasoning;
@@ -524,7 +565,6 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     }
     saveConfigPreservingClaudeCode(config);
     const ws = config.webSearchSidecar ?? {};
-    const vs = config.visionSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       ok: true,
@@ -533,12 +573,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
       },
-      vision: {
-        model: vision.model,
-        backend: vs.backend,
-        reasoning: vision.reasoning,
-        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
-      },
+      vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
     });
   }