pi-cache-optimizer 2.6.4 → 2.6.6

package/index.ts

@@ -71,6 +71,8 @@ const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
+const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
+const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
 
 let runtimeOptimizerEnabled = true;
 
@@ -168,6 +170,80 @@ type PersistedRoutedModelRef = {
   name?: string;
 };
 
+type PiRouteSnapshot = {
+  virtualProvider: string;
+  virtualModelId: string;
+  provider: string;
+  modelId: string;
+  api?: string;
+  canonicalModelId?: string;
+  routeLabel?: string;
+  status?: "planned" | "trying" | "selected" | "success" | "failed";
+  sessionIdHash?: string;
+  requestId?: string;
+  timestamp: number;
+};
+
+type PiRouteResolveHint = {
+  sessionIdHash?: string;
+  requestId?: string;
+};
+
+type PiRouterAdapterV1 = {
+  virtualProvider: string;
+  resolveActiveRoute(
+    virtualModelId: string,
+    hint?: PiRouteResolveHint,
+  ): PiRouteSnapshot | undefined;
+  resolveCandidateRoutes?(virtualModelId: string): PiRouteSnapshot[];
+  subscribe?(listener: (event: PiRouteSnapshot) => void): () => void;
+};
+
+type PiRoutingRegistryV1 = {
+  version: 1;
+  registerRouter(adapter: PiRouterAdapterV1): () => void;
+  getRouter(virtualProvider: string): PiRouterAdapterV1 | undefined;
+};
+
+type PiCacheHintsInput = {
+  sessionIdHash?: string;
+  virtualProvider?: string;
+  virtualModelId?: string;
+  upstreamProvider?: string;
+  upstreamModelId?: string;
+  api?: string;
+};
+
+type PiCacheHintsOutput = {
+  systemPrompt?: string;
+  promptCacheKey?: string;
+  cacheRetention?: "long";
+};
+
+type PiCacheHintSnapshot = PiCacheHintsInput & PiCacheHintsOutput & {
+  timestamp: number;
+};
+
+type PiCacheHintsV1 = {
+  version: 1;
+  getHints(input: PiCacheHintsInput): PiCacheHintsOutput | undefined;
+};
+
+type ProtocolGlobal = typeof globalThis & Record<symbol, unknown> & {
+  __piCacheOptimizerRouter?: unknown;
+  __piCacheOptimizerCacheKey__?: unknown;
+};
+
+type ModelRegistryLike = {
+  find?(provider: string, modelId: string): PiModel | undefined;
+  getAvailable?(): PiModel[];
+  getAll?(): PiModel[];
+};
+
+type ContextWithOptionalModelRegistry = Pick<ExtensionContext, "sessionManager"> & {
+  modelRegistry?: ModelRegistryLike;
+};
+
 type CacheStatsState = {
   statsByModel: Record<string, CacheStats>;
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
@@ -636,6 +712,210 @@ function hashSessionId(sessionId: string): string {
   return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
 }
 
+function getProtocolGlobal(): ProtocolGlobal {
+  return globalThis as ProtocolGlobal;
+}
+
+function firstNonEmptyString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (isNonEmptyString(value)) return value.trim();
+  }
+  return undefined;
+}
+
+function sessionHashFromContext(ctx: Pick<ExtensionContext, "sessionManager">): string | undefined {
+  const sessionId = ctx.sessionManager.getSessionId();
+  return sessionId ? hashSessionId(sessionId) : undefined;
+}
+
+function isPiRouterAdapterV1(value: unknown): value is PiRouterAdapterV1 {
+  const record = asRecord(value);
+  return !!record && isNonEmptyString(record.virtualProvider) && typeof record.resolveActiveRoute === "function";
+}
+
+function isRoutingRegistryV1(value: unknown): value is PiRoutingRegistryV1 {
+  const record = asRecord(value);
+  return !!record && record.version === 1 && typeof record.registerRouter === "function" && typeof record.getRouter === "function";
+}
+
+function createRoutingRegistry(): PiRoutingRegistryV1 {
+  const routers = new Map<string, PiRouterAdapterV1>();
+  return {
+    version: 1,
+    registerRouter(adapter: PiRouterAdapterV1): () => void {
+      if (!isPiRouterAdapterV1(adapter)) return () => undefined;
+      const key = adapter.virtualProvider.trim();
+      routers.set(key, adapter);
+      return () => {
+        if (routers.get(key) === adapter) routers.delete(key);
+      };
+    },
+    getRouter(virtualProvider: string): PiRouterAdapterV1 | undefined {
+      return routers.get(virtualProvider);
+    },
+  };
+}
+
+function getRoutingRegistry(): PiRoutingRegistryV1 | undefined {
+  const candidate = getProtocolGlobal()[PI_ROUTING_REGISTRY_SYMBOL];
+  return isRoutingRegistryV1(candidate) ? candidate : undefined;
+}
+
+function ensureRoutingRegistry(): PiRoutingRegistryV1 {
+  const existing = getRoutingRegistry();
+  if (existing) return existing;
+
+  const created = createRoutingRegistry();
+  getProtocolGlobal()[PI_ROUTING_REGISTRY_SYMBOL] = created;
+  return created;
+}
+
+function parseRouteStatus(value: unknown): PiRouteSnapshot["status"] | undefined {
+  return value === "planned" || value === "trying" || value === "selected" || value === "success" || value === "failed"
+    ? value
+    : undefined;
+}
+
+function parseRouteSnapshot(
+  value: unknown,
+  fallbackVirtualProvider?: string,
+  fallbackVirtualModelId?: string,
+): PiRouteSnapshot | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+
+  const virtualProvider = firstNonEmptyString(record.virtualProvider, fallbackVirtualProvider);
+  const virtualModelId = firstNonEmptyString(record.virtualModelId, record.virtualModel, fallbackVirtualModelId);
+  const provider = firstNonEmptyString(record.provider, record.upstreamProvider, record.targetProvider);
+  const modelId = firstNonEmptyString(record.modelId, record.upstreamModelId, record.targetModelId, record.responseModel);
+  if (!virtualProvider || !virtualModelId || !provider || !modelId) return undefined;
+
+  const timestamp = getNumber(record.timestamp) ?? Date.now();
+  return {
+    virtualProvider,
+    virtualModelId,
+    provider,
+    modelId,
+    api: firstNonEmptyString(record.api),
+    canonicalModelId: firstNonEmptyString(record.canonicalModelId),
+    routeLabel: firstNonEmptyString(record.routeLabel, record.label),
+    status: parseRouteStatus(record.status),
+    sessionIdHash: firstNonEmptyString(record.sessionIdHash),
+    requestId: firstNonEmptyString(record.requestId),
+    timestamp,
+  };
+}
+
+function resolveActiveRouteSnapshot(
+  model: PiModel | undefined,
+  ctx?: Pick<ExtensionContext, "sessionManager">,
+): PiRouteSnapshot | undefined {
+  if (!model) return undefined;
+  const hint: PiRouteResolveHint | undefined = ctx ? { sessionIdHash: sessionHashFromContext(ctx) } : undefined;
+
+  const adapter = getRoutingRegistry()?.getRouter(model.provider);
+  if (adapter) {
+    try {
+      const snapshot = parseRouteSnapshot(
+        adapter.resolveActiveRoute(model.id, hint),
+        model.provider,
+        model.id,
+      );
+      if (snapshot) return snapshot;
+    } catch (error) {
+      console.warn(`${LOG_PREFIX}: routing registry adapter failed`, error);
+    }
+  }
+
+  // Temporary migration shim for the prototype global used by early router PRs.
+  // New integrations should use Symbol.for("pi.routing.registry.v1") instead.
+  const legacy = getProtocolGlobal().__piCacheOptimizerRouter;
+  if (!legacy || !lower(model.provider).includes("router")) return undefined;
+  try {
+    if (typeof legacy === "function") {
+      return parseRouteSnapshot(legacy(model.provider, model.id, hint), model.provider, model.id);
+    }
+    const legacyRecord = asRecord(legacy);
+    const resolver = legacyRecord?.resolveActiveRoute;
+    if (typeof resolver === "function") {
+      return parseRouteSnapshot(resolver.call(legacy, model.id, hint), model.provider, model.id);
+    }
+    return parseRouteSnapshot(legacy, model.provider, model.id);
+  } catch (error) {
+    console.warn(`${LOG_PREFIX}: legacy routing global failed`, error);
+    return undefined;
+  }
+}
+
+function routeSnapshotToPiModel(snapshot: PiRouteSnapshot, fallback?: PiModel): PiModel {
+  return {
+    ...(fallback ?? {}),
+    id: snapshot.modelId,
+    name: snapshot.canonicalModelId ?? snapshot.modelId,
+    provider: snapshot.provider,
+    api: snapshot.api ?? fallback?.api ?? "",
+    baseUrl: fallback?.baseUrl ?? "",
+    reasoning: fallback?.reasoning ?? false,
+    input: fallback?.input ?? ["text"],
+    cost: fallback?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: fallback?.contextWindow ?? 0,
+    maxTokens: fallback?.maxTokens ?? 0,
+    compat: fallback?.compat,
+  } as PiModel;
+}
+
+function findModelInRegistry(registry: ModelRegistryLike | undefined, provider: string, id: string): PiModel | undefined {
+  const found = registry?.find?.(provider, id);
+  if (found) return found;
+
+  const available = registry?.getAvailable?.() ?? [];
+  const availableMatch = available.find((candidate) => candidate.provider === provider && candidate.id === id);
+  if (availableMatch) return availableMatch;
+
+  const all = registry?.getAll?.() ?? [];
+  return all.find((candidate) => candidate.provider === provider && candidate.id === id);
+}
+
+function resolveRouteModel(
+  model: PiModel | undefined,
+  ctx?: ContextWithOptionalModelRegistry,
+): PiModel | undefined {
+  const snapshot = resolveActiveRouteSnapshot(model, ctx);
+  if (!snapshot) return undefined;
+
+  return findModelInRegistry(ctx?.modelRegistry, snapshot.provider, snapshot.modelId)
+    ?? routeSnapshotToPiModel(snapshot, model);
+}
+
+function isVirtualRoutingModel(model: PiModel | undefined, ctx?: Pick<ExtensionContext, "sessionManager">): boolean {
+  if (!model) return false;
+  return isRouterModel(model) || !!getRoutingRegistry()?.getRouter(model.provider) || !!resolveActiveRouteSnapshot(model, ctx);
+}
+
+function isCacheHintsServiceV1(value: unknown): value is PiCacheHintsV1 {
+  const record = asRecord(value);
+  return !!record && record.version === 1 && typeof record.getHints === "function";
+}
+
+function getCacheHintsService(): PiCacheHintsV1 | undefined {
+  const candidate = getProtocolGlobal()[PI_CACHE_HINTS_SYMBOL];
+  return isCacheHintsServiceV1(candidate) ? candidate : undefined;
+}
+
+function installCacheHintsService(service: PiCacheHintsV1): () => void {
+  const globals = getProtocolGlobal();
+  const previous = globals[PI_CACHE_HINTS_SYMBOL];
+  globals[PI_CACHE_HINTS_SYMBOL] = service;
+  return () => {
+    if (globals[PI_CACHE_HINTS_SYMBOL] !== service) return;
+    if (previous === undefined) {
+      delete globals[PI_CACHE_HINTS_SYMBOL];
+    } else {
+      globals[PI_CACHE_HINTS_SYMBOL] = previous;
+    }
+  };
+}
+
 /**
  * Build a session-scoped stats key from a session hash + provider/id.
  * Pure function (no closure dependency) for use by tests and internals.
@@ -1403,10 +1683,10 @@ function modelFromAssistantMessage(message: unknown, fallback: PiModel | undefin
   const record = getAssistantRecord(message);
   if (!record) return fallback;
 
-  const id = lower(record.responseModel) || lower(record.model) || fallback?.id;
-  const provider = lower(record.provider) || fallback?.provider;
-  const api = lower(record.api) || fallback?.api;
-  if (!id || !provider || !api) return fallback;
+  const id = firstNonEmptyString(record.responseModel, record.model, fallback?.id);
+  const provider = firstNonEmptyString(record.provider, fallback?.provider);
+  const api = firstNonEmptyString(record.api, fallback?.api) ?? "";
+  if (!id || !provider) return fallback;
 
   return {
     ...(fallback ?? {}),
@@ -1612,7 +1892,7 @@ function hasEffectivePromptCacheKey(record: UnknownRecord): boolean {
   return isNonEmptyString(record.prompt_cache_key) || isNonEmptyString(record.promptCacheKey);
 }
 
-function isNonEmptyString(value: unknown): boolean {
+function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
@@ -1637,9 +1917,6 @@ function describeMissingOpenAIFamilyProxyCompat(model: PiModel): string[] {
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
   if (isOfficialOpenAIBaseUrl(model)) return missing;
 
-  if (compat.supportsLongCacheRetention !== true) {
-    missing.push("supportsLongCacheRetention");
-  }
   if (compat.sendSessionAffinityHeaders !== true) {
     missing.push("sendSessionAffinityHeaders");
   }
@@ -1660,9 +1937,6 @@ function describeMissingOpenAICompatibleProxyCompat(model: PiModel): string[] {
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
   if (isOfficialOpenAIBaseUrl(model)) return missing;
 
-  if (compat.supportsLongCacheRetention !== true) {
-    missing.push("supportsLongCacheRetention");
-  }
   if (compat.sendSessionAffinityHeaders !== true) {
     missing.push("sendSessionAffinityHeaders");
   }
@@ -1670,6 +1944,20 @@ function describeMissingOpenAICompatibleProxyCompat(model: PiModel): string[] {
   return missing;
 }
 
+function describeOptionalOpenAICompatibleProxyCompat(model: PiModel): string[] {
+  const compat = getCompat(model);
+  const optional: string[] = [];
+
+  if (!isOpenAICompatibleProxyApi(model.api)) return optional;
+  if (isOfficialOpenAIBaseUrl(model)) return optional;
+
+  if (compat.supportsLongCacheRetention !== true) {
+    optional.push("supportsLongCacheRetention");
+  }
+
+  return optional;
+}
+
 function buildSafeOpenAIProxyCompatSuggestion(missing: string[]): Record<string, boolean> {
   const suggestion: Record<string, boolean> = {};
   if (missing.includes("sendSessionAffinityHeaders")) {
@@ -1760,21 +2048,22 @@ function appendOpenAIProxyCompatAdviceLines(lines: string[], missing: string[],
       lines.push("Safe default suggestion:");
     }
     lines.push(JSON.stringify(suggestion, null, 2));
-  } else if (missing.includes("supportsLongCacheRetention")) {
-    lines.push("No safe automatic JSON change is recommended for `supportsLongCacheRetention`.");
   }
 
   if (missing.includes("sendSessionAffinityHeaders")) {
     lines.push("- sendSessionAffinityHeaders: recommended for third-party proxies when supported; it helps keep one Pi session on the same upstream/backend.");
   }
-  if (missing.includes("supportsLongCacheRetention")) {
-    lines.push("- supportsLongCacheRetention: optional. Enable only after your endpoint/proxy explicitly supports OpenAI long prompt cache retention.");
-    lines.push(`- ${getPromptCacheRetentionUnsupportedHint()}`);
-  }
-
   appendCredentialSafeProviderGuidance(lines, options, suggestion);
 }
 
+function appendOptionalOpenAIProxyCompatAdviceLines(lines: string[], optional: string[]): void {
+  if (!optional.includes("supportsLongCacheRetention")) return;
+  lines.push("");
+  lines.push("Optional (not required, not auto-fixed):");
+  lines.push("- supportsLongCacheRetention: enable only after your endpoint/proxy explicitly supports OpenAI long prompt cache retention.");
+  lines.push(`- ${getPromptCacheRetentionUnsupportedHint()}`);
+}
+
 /**
  * Build the warning text displayed to users when an OpenAI-family third-party
  * proxy is missing one or more cache/session-affinity compat flags.
@@ -2877,7 +3166,10 @@ function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter
 }
 
 function selectAdapterForAssistantMessage(message: unknown, model: PiModel | undefined): CacheProviderAdapter | undefined {
-  const responseModel = isRouterModel(model) ? modelFromAssistantMessage(message, model) : model;
+  // Assistant message metadata is request-local and authoritative for virtual
+  // routing providers. Use it first for every model; direct providers normally
+  // echo the same provider/model and therefore remain unchanged.
+  const responseModel = modelFromAssistantMessage(message, model);
   return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesAssistantMessage(message, responseModel));
 }
 
@@ -3121,12 +3413,15 @@ function parseCacheStats(value: unknown): CacheStats | undefined {
 
 function parsePersistedRoutedModelRef(value: unknown): PersistedRoutedModelRef | undefined {
   const record = asRecord(value);
-  if (!record || !isNonEmptyString(record.provider) || !isNonEmptyString(record.id)) return undefined;
+  const provider = record?.provider;
+  const id = record?.id;
+  const name = record?.name;
+  if (!isNonEmptyString(provider) || !isNonEmptyString(id)) return undefined;
 
   return {
-    provider: record.provider.trim(),
-    id: record.id.trim(),
-    name: isNonEmptyString(record.name) ? record.name.trim() : record.id.trim(),
+    provider: provider.trim(),
+    id: id.trim(),
+    name: isNonEmptyString(name) ? name.trim() : id.trim(),
   };
 }
 
@@ -3149,7 +3444,7 @@ function buildExactRouterStatusEntry(
   sessionHash: string | undefined,
   statsByModel: Record<string, CacheStats>,
   lastRoutedModel: PersistedRoutedModelRef | undefined,
-): { adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
+): { model: PiModel; adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
   if (!sessionHash || !lastRoutedModel) return undefined;
 
   const model = routedModelRefToPiModel(lastRoutedModel);
@@ -3157,7 +3452,7 @@ function buildExactRouterStatusEntry(
   if (!adapter) return undefined;
 
   const key = makeSessionModelKey(sessionHash, lastRoutedModel.provider, lastRoutedModel.id);
-  return { adapter, stats: statsByModel[key] ?? emptyCacheStats() };
+  return { model, adapter, stats: statsByModel[key] ?? emptyCacheStats() };
 }
 
 function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
@@ -3530,8 +3825,9 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
     provider.includes("openrouter")
   ) {
     const compat = getCompat(model);
-    const hasOnly = !!(compat as Record<string, unknown>)["openRouterRouting"]?.only;
-    const hasOrder = !!(compat as Record<string, unknown>)["openRouterRouting"]?.order;
+    const routing = asRecord((compat as Record<string, unknown>)["openRouterRouting"]);
+    const hasOnly = !!routing?.only;
+    const hasOrder = !!routing?.order;
 
     notes.push(
       "🔀 Router/channel: OpenRouter detected. OpenRouter is a multi-provider router; " +
@@ -3566,8 +3862,9 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
     provider.includes("vercel-ai-gateway")
   ) {
     const compat = getCompat(model);
-    const hasOnly = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.only;
-    const hasOrder = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.order;
+    const routing = asRecord((compat as Record<string, unknown>)["vercelGatewayRouting"]);
+    const hasOnly = !!routing?.only;
+    const hasOrder = !!routing?.order;
 
     notes.push(
       "🔀 Router/channel: Vercel AI Gateway detected. The gateway may route to different " +
@@ -3694,8 +3991,21 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
   const adaptiveThinkingApplicable = isAdaptiveThinkingCompatApplicable(model);
   const deepSeekCompatApplicable = isDeepSeekCompatCheckApplicable(model);
   const missing = describeMissingCacheCompatForModel(model);
+  const optionalOpenAIProxyCompat = (!adaptiveThinkingApplicable && !deepSeekCompatApplicable)
+    ? describeOptionalOpenAICompatibleProxyCompat(model)
+    : [];
+  const fixSug = buildFixSuggestion(model);
+  const safeFixableMissing = fixSug ? Object.keys(fixSug.compatKeys) : [];
+  const advisoryMissing = missing.filter(m => !safeFixableMissing.includes(m));
+
+  if (safeFixableMissing.length > 0) {
+    lines.push(`⚠️  Missing compat flags: ${safeFixableMissing.join(", ")}`);
+  }
+  if (advisoryMissing.length > 0) {
+    lines.push(`ℹ️  Optional: ${advisoryMissing.join(", ")} (enable only if needed)`);
+  }
+
   if (missing.length > 0) {
-    lines.push(`⚠️  Missing compat flags: ${missing.join(", ")}`);
     const key = modelKey(model);
     const slashIdx = key.indexOf("/");
     const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
@@ -3707,9 +4017,11 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
       appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else {
       appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
+      appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     }
   } else if (adaptiveThinkingApplicable || deepSeekCompatApplicable || isCompatCheckApplicable(model)) {
     lines.push("✅ Compat fully configured.");
+    appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
   } else {
     lines.push(...getCompatCheckNotApplicableLines(model));
   }
@@ -3767,7 +4079,8 @@ function buildLowHitDiagnosis(
   const lines: string[] = [];
 
   // 1. Missing compat flags (adapter-aware: DeepSeek has extra reasoning compat)
-  const missingCompat = describeMissingCacheCompatForModel(model);
+  const fixSugLHD = buildFixSuggestion(model);
+  const safeFixableMissingLHD = fixSugLHD ? Object.keys(fixSugLHD.compatKeys) : [];
 
   // 2. Router/channel risk (reuse existing check)
   const routerNotes = describeRouterChannelDiagnostics(model);
@@ -3785,7 +4098,7 @@ function buildLowHitDiagnosis(
   // 5. Today's overall trend from persisted stats
   const todayStats = stats ?? emptyCacheStats();
 
-  const hasMissingCompat = missingCompat.length > 0;
+  const hasMissingCompat = safeFixableMissingLHD.length > 0;
   const hasRouterRisk = routerNotes.length > 0;
   const hasUsageMissing = missingUsageSamples > 0;
 
@@ -3814,7 +4127,7 @@ function buildLowHitDiagnosis(
 
   // Priority 1: missing compat flags
   if (hasMissingCompat) {
-    lines.push(`⚠️  Missing compat flags: ${missingCompat.join(", ")}`);
+    lines.push(`⚠️  Missing compat flags: ${safeFixableMissingLHD.join(", ")}`);
     lines.push("   These flags enable prompt caching and session-affinity routing.");
     lines.push("   Run /cache-optimizer compat for edit instructions.");
   }
@@ -3867,11 +4180,17 @@ function buildLowHitDiagnosis(
 
 function buildCompatDiagnosis(model: PiModel): string | undefined {
   const missing = describeMissingCacheCompatForModel(model);
+  const fixSugC = buildFixSuggestion(model);
+  const safeFixableMissingC = fixSugC ? Object.keys(fixSugC.compatKeys) : [];
+  const advisoryMissingC = missing.filter(m => !safeFixableMissingC.includes(m));
   const adaptiveThinkingApplicable = isAdaptiveThinkingCompatApplicable(model);
   const deepSeekCompatApplicable = isDeepSeekCompatCheckApplicable(model);
+  const optionalOpenAIProxyCompat = (!adaptiveThinkingApplicable && !deepSeekCompatApplicable)
+    ? describeOptionalOpenAICompatibleProxyCompat(model)
+    : [];
   const routerNotes = describeRouterChannelDiagnostics(model);
 
-  if (missing.length === 0 && routerNotes.length === 0) return undefined;
+  if (missing.length === 0 && routerNotes.length === 0 && optionalOpenAIProxyCompat.length === 0) return undefined;
 
   const key = modelKey(model);
   const lines: string[] = [];
@@ -3881,7 +4200,12 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
     const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
     const modelsJsonPath = getModelsJsonDisplayPath();
     lines.push(`Active model: ${key}`);
-    lines.push(`Missing: ${missing.join(", ")}`);
+    if (safeFixableMissingC.length > 0) {
+      lines.push(`Safe-fixable: ${safeFixableMissingC.join(", ")}`);
+    }
+    if (advisoryMissingC.length > 0) {
+      lines.push(`Optional: ${advisoryMissingC.join(", ")} (enable only if needed)`);
+    }
     lines.push("");
     lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat`);
     lines.push(`(at the same level as baseUrl/api/apiKey/models).`);
@@ -3891,16 +4215,18 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
       appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else {
       appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
+      appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     }
   }
 
-  // When compat is fully configured but router notes exist, prefix the status.
-  if (routerNotes.length > 0 && missing.length === 0) {
+  // When compat is fully configured but router/optional notes exist, prefix the status.
+  if ((routerNotes.length > 0 || optionalOpenAIProxyCompat.length > 0) && missing.length === 0) {
     if (adaptiveThinkingApplicable || deepSeekCompatApplicable || isCompatCheckApplicable(model)) {
       lines.push("✅ Compat fully configured.");
       if (isPromptCacheRetention400Applicable(model)) {
         lines.push(getPromptCacheRetentionUnsupportedHint());
       }
+      appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     } else {
       lines.push(...getCompatCheckNotApplicableLines(model));
     }
@@ -4131,8 +4457,10 @@ function stripJsoncComments(text: string): string {
   let i = 0;
   while (i < text.length) {
     const ch = text[i];
+
     if (ch === '"') {
-      // String literal — copy until closing quote (handle escapes)
+      // String literal — copy byte-for-byte until the closing quote.
+      // Escaped quotes/slashes must not be mistaken for comment delimiters.
       out.push(ch);
       i++;
       while (i < text.length) {
@@ -4146,39 +4474,74 @@ function stripJsoncComments(text: string): string {
           break;
         }
       }
-    } else if (ch === '/' && i + 1 < text.length && text[i + 1] === '/') {
-      // Line comment — replace with spaces until newline
-      out.push(' ');
-      i++;
+      continue;
+    }
+
+    if (ch === '/' && i + 1 < text.length && text[i + 1] === '/') {
+      // Line comment — replace BOTH slashes and every comment byte with
+      // spaces, but leave the newline to be copied by the normal path.
+      out.push(' ', ' ');
+      i += 2;
       while (i < text.length && text[i] !== '\n') {
         out.push(' ');
         i++;
       }
-    } else if (ch === '/' && i + 1 < text.length && text[i + 1] === '*') {
-      // Block comment — replace with spaces (preserve newlines)
-      out.push(' ');
-      i++;
-      while (i + 1 < text.length) {
-        if (text[i] === '*' && text[i + 1] === '/') {
-          out.push(' ');
+      continue;
+    }
+
+    if (ch === '/' && i + 1 < text.length && text[i + 1] === '*') {
+      // Block comment — replace every byte with a space except newlines.
+      // This deliberately preserves text.length and all structural offsets.
+      out.push(' ', ' ');
+      i += 2;
+      while (i < text.length) {
+        if (text[i] === '*' && i + 1 < text.length && text[i + 1] === '/') {
+          out.push(' ', ' ');
           i += 2;
           break;
         }
-        if (text[i] === '\n') {
-          out.push('\n');
-        } else {
-          out.push(' ');
-        }
+        out.push(text[i] === '\n' ? '\n' : ' ');
         i++;
       }
-    } else {
-      out.push(ch);
-      i++;
+      continue;
     }
+
+    out.push(ch);
+    i++;
   }
   return out.join('');
 }
 
+/**
+ * Remove JSONC trailing commas from already comment-stripped text.
+ * The returned text stays length-preserving (commas become spaces), which
+ * gives JSON.parse a tolerant JSONC surface without affecting diagnostics.
+ */
+function stripJsoncTrailingCommas(text: string): string {
+  const chars = text.split("");
+  let i = 0;
+  while (i < chars.length) {
+    if (chars[i] === '"') {
+      const str = readJsonStringLiteral(text, i);
+      if (!str) break;
+      i = str.end;
+      continue;
+    }
+
+    if (chars[i] === ',') {
+      let j = i + 1;
+      while (j < chars.length && isJsonWhitespace(chars[j])) j++;
+      if (chars[j] === '}' || chars[j] === ']') chars[i] = ' ';
+    }
+    i++;
+  }
+  return chars.join('');
+}
+
+function parseJsonc(text: string): unknown {
+  return JSON.parse(stripJsoncTrailingCommas(stripJsoncComments(text)));
+}
+
 /**
  * JSONC scanner: locate the provider block and model entry in models.json text.
  * Returns the byte offsets for surgical insertion, or undefined if ambiguous.
@@ -4222,153 +4585,51 @@ function locateModelInJsonc(
   // Clean text of comments first for reliable structural scanning
   const clean = stripJsoncComments(text);
 
-  // Strategy: find `"providers"` key in the root object, then find the
-  // provider key under it, then the `"models"` array, then the array
-  // element whose `"id"` matches. We map via the stripped text (comment
-  // removal replaces comment chars with spaces, preserving offsets).
-
-  const pos = clean.indexOf('"providers"');
-  if (pos < 0) return undefined;
-
-  // Scan from `"providers"` to find the `{` of the provider block
-  let cur = pos + '"providers"'.length;
-  // Skip `:`, whitespace, etc.
-  while (cur < clean.length && clean[cur] !== '{') cur++;
-  if (cur >= clean.length) return undefined;
-  cur++; // Skip `{`
-
-  // Now scan key-value pairs in the providers object to find the matching providerLabel
-  const providerLabelJson = JSON.stringify(providerLabel);
-  let providerBrace = -1;
-  let providerEndBrace = -1;
-
-  while (cur < clean.length) {
-    // Skip whitespace/comments
-    while (cur < clean.length && (clean[cur] === ' ' || clean[cur] === '\n' || clean[cur] === '\r' || clean[cur] === '\t')) cur++;
-    if (cur >= clean.length) break;
-    if (clean[cur] === '}') break; // End of providers
-
-    // Try to read a string key
-    if (clean[cur] !== '"') { cur++; continue; }
-    const keyEnd = clean.indexOf('"', cur + 1);
-    if (keyEnd < 0) return undefined;
-    const key = clean.slice(cur + 1, keyEnd);
-    cur = keyEnd + 1;
-
-    // Skip `:`
-    while (cur < clean.length && clean[cur] !== ':') cur++;
-    if (cur >= clean.length) return undefined;
-    cur++; // Skip `:`
-    while (cur < clean.length && (clean[cur] === ' ' || clean[cur] === '\n' || clean[cur] === '\r' || clean[cur] === '\t')) cur++;
-
-    if (key === providerLabel) {
-      // Found — expect `{` starting the provider object
-      if (clean[cur] !== '{') return undefined;
-      providerBrace = cur;
-      // Find matching closing `}` for the provider object (track depth)
-      let depth = 1;
-      let scan = cur + 1;
-      while (scan < clean.length && depth > 0) {
-        if (clean[scan] === '{') depth++;
-        else if (clean[scan] === '}') depth--;
-        if (depth > 0) scan++;
-      }
-      providerEndBrace = scan;
-      break;
-    }
-
-    // Skip the value
-    if (clean[cur] === '{') {
-      let depth = 1;
-      cur++;
-      while (cur < clean.length && depth > 0) {
-        if (clean[cur] === '{') depth++;
-        else if (clean[cur] === '}') depth--;
-        cur++;
-      }
-    } else if (clean[cur] === '[') {
-      let depth = 1;
-      cur++;
-      while (cur < clean.length && depth > 0) {
-        if (clean[cur] === '[') depth++;
-        else if (clean[cur] === ']') depth--;
-        cur++;
-      }
-    } else if (clean[cur] === '"') {
-      const strEnd = clean.indexOf('"', cur + 1);
-      if (strEnd < 0) return undefined;
-      cur = strEnd + 1;
-    } else {
-      // Number, boolean, etc.
-      while (cur < clean.length && clean[cur] !== ',' && clean[cur] !== '}' && clean[cur] !== '\n') cur++;
-    }
-    // Skip comma
-    if (cur < clean.length && clean[cur] === ',') cur++;
-  }
-
-  if (providerBrace < 0 || providerEndBrace < 0) return undefined;
-
-  // Scan provider object at depth 1 for a provider-level "compat" object.
-  // Depth-aware + string-aware so nested model compat objects are not confused
-  // with the provider-level one.
+  // Strategy: find `"providers"` as a direct root key, then find the
+  // provider key under it, then the provider's direct `"models"` key.
+  // All object/value traversal uses the string-aware primitives above so
+  // braces, brackets, comment markers, or escaped quotes inside strings do
+  // not corrupt offsets.
+  const rootBrace = skipJsonWhitespace(clean, 0);
+  if (clean[rootBrace] !== "{") return undefined;
+
+  const providersKey = findJsonObjectKey(clean, rootBrace, "providers");
+  if (!providersKey) return undefined;
+  const providersBrace = skipJsonWhitespace(clean, providersKey.valueStart);
+  if (clean[providersBrace] !== "{") return undefined;
+  const providersEnd = findMatchingBracket(clean, providersBrace);
+  if (providersEnd === undefined) return undefined;
+
+  const providerKey = findJsonObjectKey(clean, providersBrace, providerLabel);
+  if (!providerKey || providerKey.keyStart > providersEnd) return undefined;
+  const providerBrace = skipJsonWhitespace(clean, providerKey.valueStart);
+  if (clean[providerBrace] !== "{") return undefined;
+  const providerEndBrace = findMatchingBracket(clean, providerBrace);
+  if (providerEndBrace === undefined || providerEndBrace > providersEnd) return undefined;
+
+  // Provider-level compat is a direct provider child only. Nested model
+  // compat objects are intentionally skipped whole by findJsonObjectKey.
   let providerCompatBrace = -1;
   let providerCompatEnd = -1;
-  {
-    let pScan = providerBrace + 1;
-    let pDepth = 1;
-    while (pScan < providerEndBrace && pDepth > 0) {
-      const ch = clean[pScan];
-      if (ch === '"') {
-        // Read the string (key or value) fully
-        const strEnd = clean.indexOf('"', pScan + 1);
-        if (strEnd < 0) break;
-        const str = clean.slice(pScan + 1, strEnd);
-        if (pDepth === 1 && str === 'compat') {
-          // Confirm it's a key: next non-ws char must be ':'
-          let after = strEnd + 1;
-          while (after < providerEndBrace && (clean[after] === ' ' || clean[after] === '\n' || clean[after] === '\r' || clean[after] === '\t')) after++;
-          if (clean[after] === ':') {
-            after++;
-            while (after < providerEndBrace && (clean[after] === ' ' || clean[after] === '\n' || clean[after] === '\r' || clean[after] === '\t')) after++;
-            if (clean[after] === '{') {
-              providerCompatBrace = after;
-              let d = 1;
-              let s = after + 1;
-              while (s < clean.length && d > 0) {
-                if (clean[s] === '"') {
-                  const e = clean.indexOf('"', s + 1);
-                  if (e < 0) break;
-                  s = e + 1;
-                  continue;
-                }
-                if (clean[s] === '{') d++;
-                else if (clean[s] === '}') d--;
-                if (d > 0) s++;
-              }
-              providerCompatEnd = s;
-              pScan = s + 1;
-              continue;
-            }
-          }
-        }
-        pScan = strEnd + 1;
-        continue;
+  const providerCompatKey = findJsonObjectKey(clean, providerBrace, "compat");
+  if (providerCompatKey && providerCompatKey.keyStart < providerEndBrace) {
+    const brace = skipJsonWhitespace(clean, providerCompatKey.valueStart);
+    if (clean[brace] === "{") {
+      const end = findMatchingBracket(clean, brace);
+      if (end !== undefined && end <= providerEndBrace) {
+        providerCompatBrace = brace;
+        providerCompatEnd = end;
       }
-      if (ch === '{' || ch === '[') pDepth++;
-      else if (ch === '}' || ch === ']') pDepth--;
-      pScan++;
     }
   }
 
-  // Now find the `"models"` array within the provider
-  const providerContent = clean.slice(providerBrace + 1, providerEndBrace);
-  const modelsIdx = providerContent.indexOf('"models"');
-  if (modelsIdx < 0) return undefined;
+  const modelsKey = findJsonObjectKey(clean, providerBrace, "models");
+  if (!modelsKey || modelsKey.keyStart > providerEndBrace) return undefined;
 
-  // Find the `[` of the models array
-  let modelsScan = providerBrace + 1 + modelsIdx + '"models"'.length;
-  while (modelsScan < clean.length && clean[modelsScan] !== '[') modelsScan++;
-  if (modelsScan >= clean.length) return undefined;
+  let modelsScan = skipJsonWhitespace(clean, modelsKey.valueStart);
+  if (clean[modelsScan] !== "[") return undefined;
+  const modelsEnd = findMatchingBracket(clean, modelsScan);
+  if (modelsEnd === undefined || modelsEnd > providerEndBrace) return undefined;
   modelsScan++; // Skip `[`
 
   // Scan ALL array elements: collect every model id, and record the target's position
@@ -4379,83 +4640,52 @@ function locateModelInJsonc(
   let compatBrace = -1;
   let compatEndBrace = -1;
 
-  while (modelsScan < clean.length) {
-    // Skip whitespace/comma
-    while (modelsScan < clean.length && (clean[modelsScan] === ' ' || clean[modelsScan] === '\n' || clean[modelsScan] === '\r' || clean[modelsScan] === '\t' || clean[modelsScan] === ',')) modelsScan++;
-    if (modelsScan >= clean.length) break;
-    if (clean[modelsScan] === ']') break; // End of array
-
-    if (clean[modelsScan] !== '{') { modelsScan++; continue; }
+  while (modelsScan < modelsEnd) {
+    modelsScan = skipJsonWhitespace(clean, modelsScan);
+    if (clean[modelsScan] === ',') {
+      modelsScan++;
+      continue;
+    }
+    if (modelsScan >= modelsEnd || clean[modelsScan] === ']') break;
+    if (clean[modelsScan] !== '{') return undefined;
 
-    // Found a model object `{`
     const elementBrace = modelsScan;
+    const elementEnd = findMatchingBracket(clean, elementBrace);
+    if (elementEnd === undefined || elementEnd > modelsEnd) return undefined;
 
-    // Find the matching closing `}` and extract this element's `"id"` at depth 1
-    let depth = 1;
-    let scan = modelsScan + 1;
+    const idKey = findJsonObjectKey(clean, elementBrace, "id");
     let elementId: string | undefined;
-
-    while (scan < clean.length && depth > 0) {
-      if (clean[scan] === '"') {
-        const strEnd = clean.indexOf('"', scan + 1);
-        if (strEnd < 0) break;
-        if (depth === 1 && elementId === undefined && clean.slice(scan, scan + 4) === '"id"') {
-          // Found "id" key — find the colon and the value
-          let afterKey = scan + 4;
-          while (afterKey < clean.length && clean[afterKey] !== ':') afterKey++;
-          if (afterKey < clean.length) {
-            afterKey++; // skip ':'
-            while (afterKey < clean.length && (clean[afterKey] === ' ' || clean[afterKey] === '\n' || clean[afterKey] === '\r' || clean[afterKey] === '\t')) afterKey++;
-            if (afterKey < clean.length && clean[afterKey] === '"') {
-              const idStart = afterKey + 1;
-              const idEnd = clean.indexOf('"', idStart);
-              if (idEnd > idStart) {
-                elementId = clean.slice(idStart, idEnd);
-              }
-            }
-          }
-        }
-        scan = strEnd + 1;
-        continue;
+    if (idKey && idKey.keyStart < elementEnd) {
+      const idValueStart = skipJsonWhitespace(clean, idKey.valueStart);
+      const idLiteral = readJsonStringLiteral(clean, idValueStart);
+      if (idLiteral && idLiteral.end <= elementEnd) {
+        elementId = idLiteral.value;
       }
-      if (clean[scan] === '{') depth++;
-      else if (clean[scan] === '}') depth--;
-      scan++;
     }
 
-    const elementEnd = scan - 1; // The `}` that closed this element
-
     if (elementId !== undefined) {
       allModelIds.push(elementId);
     }
 
     if (elementId === modelId && modelBrace < 0) {
-      // This is the target model — record its position and find its compat
       modelBrace = elementBrace;
       modelEndBrace = elementEnd;
-      const modelContent = clean.slice(modelBrace + 1, modelEndBrace);
-      const compatIdx = modelContent.indexOf('"compat"');
-      if (compatIdx >= 0) {
-        compatKeyStartClean = modelBrace + 1 + compatIdx;
-        let compatScan = compatKeyStartClean + '"compat"'.length;
-        while (compatScan < clean.length && clean[compatScan] !== ':') compatScan++;
-        compatScan++;
-        while (compatScan < clean.length && (clean[compatScan] === ' ' || clean[compatScan] === '\n' || clean[compatScan] === '\r' || clean[compatScan] === '\t')) compatScan++;
-        if (compatScan < clean.length && clean[compatScan] === '{') {
-          compatBrace = compatScan;
-          let cdepth = 1;
-          let cscan = compatScan + 1;
-          while (cscan < clean.length && cdepth > 0) {
-            if (clean[cscan] === '{') cdepth++;
-            else if (clean[cscan] === '}') cdepth--;
-            if (cdepth > 0) cscan++;
+
+      const compatKey = findJsonObjectKey(clean, modelBrace, "compat");
+      if (compatKey && compatKey.keyStart < modelEndBrace) {
+        compatKeyStartClean = compatKey.keyStart;
+        const brace = skipJsonWhitespace(clean, compatKey.valueStart);
+        if (clean[brace] === "{") {
+          const end = findMatchingBracket(clean, brace);
+          if (end !== undefined && end <= modelEndBrace) {
+            compatBrace = brace;
+            compatEndBrace = end;
           }
-          compatEndBrace = cscan;
         }
       }
     }
 
-    modelsScan = scan;
+    modelsScan = elementEnd + 1;
   }
 
   if (modelBrace < 0 || modelEndBrace < 0) return undefined;
@@ -4596,6 +4826,48 @@ function decideFixPlacement(
   };
 }
 
+function findExistingCompatKeysInJsonc(
+  original: string,
+  compatBrace: number,
+  compatEnd: number,
+  keys: string[],
+): string[] {
+  if (compatBrace < 0 || compatEnd <= compatBrace) return [];
+  const clean = stripJsoncComments(original);
+  return keys.filter((key) => {
+    const found = findJsonObjectKey(clean, compatBrace, key);
+    return !!found && found.keyStart < compatEnd;
+  });
+}
+
+function chooseFixPlacement(
+  original: string,
+  location: ModelNodeLocation,
+  compatKeys: Record<string, unknown>,
+  providerLabel: string,
+): { placement: "provider" | "model"; reason: string } {
+  const decision = decideFixPlacement(compatKeys, providerLabel, location.allModelIds);
+  const existingModelKeys = findExistingCompatKeysInJsonc(
+    original,
+    location.compatObjectBrace,
+    location.compatObjectEnd,
+    Object.keys(compatKeys),
+  );
+
+  // Provider-level writes cannot override a model-level compat key because Pi's
+  // merge order is provider.compat then model.compat. If the active model already
+  // has one of the keys we need to repair (e.g. thinkingFormat: "legacy"), write
+  // at model level even when the key would otherwise be provider-safe.
+  if (decision.placement === "provider" && existingModelKeys.length > 0) {
+    return {
+      placement: "model",
+      reason: `model-level compat already contains ${existingModelKeys.join(", ")} — repairing the active model override directly`,
+    };
+  }
+
+  return decision;
+}
+
 function composeFixInsertion(
   original: string,
   location: ModelNodeLocation,
@@ -4607,14 +4879,12 @@ function composeFixInsertion(
   const targetCompatEnd = placement === "provider" ? location.providerCompatEnd : location.compatObjectEnd;
   const containerBrace = placement === "provider" ? location.providerObjectBrace : location.modelObjectBrace;
 
-  // Helper: format the new keys as lines with the given indent, alphabetically sorted.
-  const formatKeys = (indent: string): string =>
-    Object.entries(compatKeys)
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([k, v]) => {
-        const val = typeof v === 'string' ? `"${v}"` : JSON.stringify(v);
-        return `${indent}${JSON.stringify(k)}: ${val}`;
-      })
+  // Helper: format key/value pairs as lines with the given indent,
+  // alphabetically sorted for stable previews and deterministic edits.
+  const sortedEntries = Object.entries(compatKeys).sort(([a], [b]) => a.localeCompare(b));
+  const formatEntries = (indent: string, entries: Array<[string, unknown]>): string =>
+    entries
+      .map(([k, v]) => `${indent}${JSON.stringify(k)}: ${JSON.stringify(v)}`)
       .join(',\n');
 
   // Helper: line-start indentation of the line containing `offset` in `original`.
@@ -4627,25 +4897,52 @@ function composeFixInsertion(
   };
 
   if (targetCompatBrace >= 0 && targetCompatEnd > targetCompatBrace) {
-    // ── Existing compat object: insert new key lines right after `{`. ──
-    // The existing interior is preserved BYTE-FOR-BYTE (no reflow, no re-indent).
+    // ── Existing compat object: insert absent keys and surgically replace
+    // direct existing keys whose value is wrong (e.g. thinkingFormat: "legacy").
+    // Unrelated interior bytes/comments/key order are preserved.
     const interiorStart = targetCompatBrace + 1;
     const interior = original.slice(interiorStart, targetCompatEnd);
     const hasContent = interior.trim().length > 0;
+    const clean = stripJsoncComments(original);
 
-    // Indent for the new key lines: copy the first existing key line's indent,
+    // Indent for inserted key lines: copy the first existing key line's indent,
     // else derive one level deeper than the compat brace's own line.
     const braceLineIndent = lineIndentAt(targetCompatBrace);
     const innerMatch = interior.match(/\r?\n([ \t]+)\S/);
     const innerIndent = innerMatch ? innerMatch[1] : braceLineIndent + '  ';
-    const keysFormatted = formatKeys(innerIndent);
 
-    if (hasContent) {
-      // `{` + "\n<new keys>," + <original interior untouched> + `}`
-      return original.slice(0, interiorStart) + `\n${keysFormatted},` + original.slice(interiorStart);
+    const edits: Array<{ start: number; end: number; text: string }> = [];
+    const missingEntries: Array<[string, unknown]> = [];
+
+    for (const [key, value] of sortedEntries) {
+      const existing = findJsonObjectKey(clean, targetCompatBrace, key);
+      if (existing && existing.keyStart < targetCompatEnd) {
+        const valueStart = skipJsonWhitespace(clean, existing.valueStart);
+        const valueEnd = skipJsonValue(clean, valueStart);
+        if (valueEnd !== undefined && valueEnd <= targetCompatEnd) {
+          const nextValue = JSON.stringify(value);
+          if (original.slice(valueStart, valueEnd) !== nextValue) {
+            edits.push({ start: valueStart, end: valueEnd, text: nextValue });
+          }
+          continue;
+        }
+      }
+      missingEntries.push([key, value]);
     }
-    // Empty compat `{}` (or whitespace only): write keys + put `}` back on its own line.
-    return original.slice(0, interiorStart) + `\n${keysFormatted}\n${braceLineIndent}` + original.slice(targetCompatEnd);
+
+    if (missingEntries.length > 0) {
+      const keysFormatted = formatEntries(innerIndent, missingEntries);
+      if (hasContent) {
+        edits.push({ start: interiorStart, end: interiorStart, text: `\n${keysFormatted},` });
+      } else {
+        edits.push({ start: interiorStart, end: targetCompatEnd, text: `\n${keysFormatted}\n${braceLineIndent}` });
+      }
+    }
+
+    // Apply later edits first so earlier offsets remain valid.
+    return edits
+      .sort((a, b) => b.start - a.start)
+      .reduce((text, edit) => text.slice(0, edit.start) + edit.text + text.slice(edit.end), original);
   }
 
   // ── No compat object yet: create one right after the container `{`. ──
@@ -4666,12 +4963,12 @@ function composeFixInsertion(
     : '  ';
   const innerIndent = keyIndent + unit;
 
-  const compatBlock = `\n${keyIndent}"compat": {\n${formatKeys(innerIndent)}\n${keyIndent}},`;
+  const compatBlock = `\n${keyIndent}"compat": {\n${formatEntries(innerIndent, sortedEntries)}\n${keyIndent}},`;
   return original.slice(0, afterBrace) + compatBlock + suffix;
 }
 
 /**
- * Self-check after compose: parse original and modified via stripJsoncComments,
+ * Self-check after compose: parse original and modified as JSONC,
  * assert target compat flags exist in the right path, and remaining structure
  * is deep-equal (ignoring the inserted keys).
  * Returns null on success, error message on failure.
@@ -4684,17 +4981,17 @@ function selfCheckFix(
   compatKeys: Record<string, unknown>,
 ): string | null {
   try {
-    // Step 1: Parse both versions (this validates JSON syntax)
-    const origParsed = JSON.parse(stripJsoncComments(original));
-    const modParsed = JSON.parse(stripJsoncComments(modified));
+    // Step 1: Parse both versions as JSONC (comments + trailing commas allowed).
+    const origParsed = parseJsonc(original);
+    const modParsed = parseJsonc(modified);
 
     // Step 2: Validate modified file has correct structure
-    const providers = modParsed?.providers;
-    if (!providers || typeof providers !== 'object') {
+    const providers = asRecord(asRecord(modParsed)?.providers);
+    if (!providers) {
       return "Modified file: providers object missing or invalid";
     }
-    const provider = providers[providerLabel];
-    if (!provider || typeof provider !== 'object') {
+    const provider = asRecord(providers[providerLabel]);
+    if (!provider) {
       return `Modified file: provider "${providerLabel}" not found`;
     }
 
@@ -4712,6 +5009,18 @@ function selfCheckFix(
     if (!targetModel || typeof targetModel !== 'object') {
       return `Modified file: model "${modelId}" not found in provider`;
     }
+
+    // Locate the corresponding original provider/model objects. The structure
+    // preservation check below may allow repaired compat values to differ, but
+    // only on these exact target/provider compat objects — never on siblings.
+    const origProviders = asRecord(asRecord(origParsed)?.providers);
+    const origProvider = asRecord(origProviders?.[providerLabel]);
+    const origModels = Array.isArray(origProvider?.models) ? origProvider.models : undefined;
+    const origTargetModel = origModels?.find((m: unknown) => asRecord(m)?.id === modelId);
+    const origTargetModelRecord = asRecord(origTargetModel);
+    if (!origProvider || !origTargetModelRecord) {
+      return `Original file: provider/model "${providerLabel}/${modelId}" not found`;
+    }
     
     // Step 5: Compute the EFFECTIVE merged compat (provider-level + model-level),
     // mirroring Pi's mergeCompat behavior (model wins on conflicts). The fix may
@@ -4754,15 +5063,23 @@ function selfCheckFix(
       for (const key of Object.keys(origObj)) {
         if (!(key in modObj)) return false;
         if (key === 'compat') {
-          // For compat, allow extra keys in modified (the inserted ones)
+          // For compat, allow extra keys in modified (the inserted ones).
+          // Use recursive isSubset so nested objects (e.g. { deep: true })
+          // are compared by content, not reference.
           if (typeof origObj[key] !== 'object' || typeof modObj[key] !== 'object') {
             if (origObj[key] !== modObj[key]) return false;
           } else {
-            // Check all original compat keys are present and equal
             const origCompat = origObj[key] as Record<string, unknown>;
             const modCompat = modObj[key] as Record<string, unknown>;
+            const mayRepairThisCompat = origObj === origProvider || origObj === origTargetModelRecord;
             for (const ck of Object.keys(origCompat)) {
-              if (origCompat[ck] !== modCompat[ck]) return false;
+              if (!(ck in modCompat)) return false;
+              // The fix may repair an existing wrong compat value (for example
+              // thinkingFormat: "legacy" -> "deepseek"), but only on the
+              // target provider/model compat objects. Sibling compat blocks must
+              // remain structure-equivalent.
+              if (mayRepairThisCompat && Object.prototype.hasOwnProperty.call(compatKeys, ck)) continue;
+              if (!isSubset(origCompat[ck], modCompat[ck], `${path}.${ck}`)) return false;
             }
           }
         } else if (!isSubset(origObj[key], modObj[key], `${path}.${key}`)) {
@@ -4781,11 +5098,17 @@ function selfCheckFix(
       return "Modified file: content is shorter than original (possible truncation)";
     }
     
-    // Step 9: Validate no syntax issues by checking brackets balance
-    const openBraces = (modified.match(/{/g) || []).length;
-    const closeBraces = (modified.match(/}/g) || []).length;
-    if (openBraces !== closeBraces) {
-      return `Modified file: bracket mismatch (${openBraces} open, ${closeBraces} close)`;
+    // Step 9: Validate root bracket integrity with the same string/comment-aware
+    // scanner used for edits. Do not count raw braces: comments or strings may
+    // legitimately contain unmatched `{` / `}` bytes.
+    const modifiedClean = stripJsoncComments(modified);
+    const rootStart = skipJsonWhitespace(modifiedClean, 0);
+    const rootEnd = findMatchingBracket(modifiedClean, rootStart);
+    if (rootEnd === undefined) {
+      return "Modified file: root bracket mismatch";
+    }
+    if (skipJsonWhitespace(modifiedClean, rootEnd + 1) !== modifiedClean.length) {
+      return "Modified file: trailing non-whitespace content after root object";
     }
 
     return null;
@@ -4801,8 +5124,7 @@ function selfCheckFix(
 function formatCompatKeysForInsertion(compatKeys: Record<string, unknown>): string {
   return Object.entries(compatKeys)
     .map(([k, v]) => {
-      const val = typeof v === 'string' ? `"${v}"` : String(v);
-      return `  ${JSON.stringify(k)}: ${val}`;
+      return `  ${JSON.stringify(k)}: ${JSON.stringify(v)}`;
     })
     .join(',\n');
 }
@@ -4852,6 +5174,7 @@ export const __internals_for_tests = {
   isOpenAIFamilyToken,
   describeMissingOpenAIFamilyProxyCompat,
   describeMissingOpenAICompatibleProxyCompat,
+  describeOptionalOpenAICompatibleProxyCompat,
   describeMissingDeepSeekCompat,
   isDeepSeekCompatCheckApplicable,
   describeMissingCacheCompatForModel,
@@ -5022,6 +5345,18 @@ export const __internals_for_tests = {
   parsePersistedRoutedModelRef,
   routedModelRefToPiModel,
   buildExactRouterStatusEntry,
+  // Routing-provider protocol helpers
+  PI_ROUTING_REGISTRY_SYMBOL,
+  PI_CACHE_HINTS_SYMBOL,
+  ensureRoutingRegistry,
+  getRoutingRegistry,
+  parseRouteSnapshot,
+  resolveActiveRouteSnapshot,
+  routeSnapshotToPiModel,
+  resolveRouteModel,
+  isVirtualRoutingModel,
+  installCacheHintsService,
+  getCacheHintsService,
   // Persistence helpers (for reload/reset tests)
   mergeCacheSessions,
   mergeLastRoutedModels,
@@ -5033,10 +5368,14 @@ export const __internals_for_tests = {
   // JSONC surgical edit helpers
   MODELS_JSON_PATH,
   stripJsoncComments,
+  stripJsoncTrailingCommas,
+  parseJsonc,
   locateModelInJsonc,
   composeFixInsertion,
   selfCheckFix,
   decideFixPlacement,
+  chooseFixPlacement,
+  findExistingCompatKeysInJsonc,
   deepEqualIgnoringKeys,
   formatCompatKeysForInsertion,
   backupTimestamp,
@@ -5065,6 +5404,7 @@ export default function (pi: ExtensionAPI) {
   let currentSessionHash = "";
   let currentSessionHashSet = false;
   let lastActualRoutedModel: PersistedRoutedModelRef | undefined;
+  let latestCacheHint: PiCacheHintSnapshot | undefined;
   const PERSIST_DEBOUNCE_MS = 2000;
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
@@ -5079,6 +5419,28 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  const uninstallCacheHintsService = installCacheHintsService({
+    version: 1,
+    getHints(input: PiCacheHintsInput): PiCacheHintsOutput | undefined {
+      if (!runtimeOptimizerEnabled || isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) return undefined;
+      const hint = latestCacheHint;
+      if (!hint) return undefined;
+      if (input.sessionIdHash && hint.sessionIdHash && input.sessionIdHash !== hint.sessionIdHash) return undefined;
+      if (input.virtualProvider && hint.virtualProvider && input.virtualProvider !== hint.virtualProvider) return undefined;
+      if (input.virtualModelId && hint.virtualModelId && input.virtualModelId !== hint.virtualModelId) return undefined;
+      if (input.upstreamProvider && hint.upstreamProvider && input.upstreamProvider !== hint.upstreamProvider) return undefined;
+      if (input.upstreamModelId && hint.upstreamModelId && input.upstreamModelId !== hint.upstreamModelId) return undefined;
+      if (input.api && hint.api && input.api !== hint.api) return undefined;
+
+      return {
+        systemPrompt: hint.systemPrompt,
+        promptCacheKey: hint.promptCacheKey,
+        cacheRetention: hint.cacheRetention,
+      };
+    },
+  });
+  void uninstallCacheHintsService;
+
   /**
    * Build a session-scoped stats key from the current session hash + model key.
    * Returns `${sessionHash}:${provider}/${id}`.
@@ -5162,6 +5524,13 @@ export default function (pi: ExtensionAPI) {
     return created;
   }
 
+  function resetStatsForModel(model: PiModel): void {
+    const sk = sessionModelKey(model);
+    delete cacheStatsByModel[sk];
+    recentSamplesByModelKey.delete(sk);
+    lastStatusText = undefined;
+  }
+
   function resetCurrentSessionStats(): void {
     const prefix = `${currentSessionHash || "_nosession"}:`;
     for (const key of Object.keys(cacheStatsByModel)) {
@@ -5170,6 +5539,7 @@ export default function (pi: ExtensionAPI) {
     for (const key of Array.from(recentSamplesByModelKey.keys())) {
       if (key.startsWith(prefix)) recentSamplesByModelKey.delete(key);
     }
+    lastActualRoutedModel = undefined;
     lastStatusText = undefined;
   }
 
@@ -5336,9 +5706,13 @@ export default function (pi: ExtensionAPI) {
     syncSessionHash(ctx);
     await rollOverStatsIfNeeded(ctx);
 
-    const adapter = selectAdapterForModel(model);
+    const routedModel = resolveRouteModel(model, ctx);
+    const displayModel = routedModel ?? model;
+    const adapter = selectAdapterForModel(displayModel);
+    const activeIsVirtualRoute = !!routedModel || isVirtualRoutingModel(model, ctx);
     let statusText: string | undefined;
-    if (!adapter && isRouterModel(model)) {
+
+    if (!adapter && !routedModel && activeIsVirtualRoute) {
       // On model_select (existing footer), keep the existing cache footer
       // visible instead of clearing it. On session_start (no footer yet
       // after reload/fresh start), restore the exact last actual routed model
@@ -5361,8 +5735,8 @@ export default function (pi: ExtensionAPI) {
     if (adapter) {
       // Display session-scoped stats. A model that has never been used
       // in this session shows 0/0. The message_end hook populates
-      // cacheStatsByModel[sessionModelKey(model)] on first use.
-      const sk = model ? sessionModelKey(model) : undefined;
+      // cacheStatsByModel[sessionModelKey(displayModel)] on first use.
+      const sk = displayModel ? sessionModelKey(displayModel) : undefined;
       const stats = sk ? cacheStatsByModel[sk] : undefined;
       const statsText = formatCacheStats(adapter, stats ?? emptyCacheStats());
       statusText = runtimeOptimizerEnabled ? statsText : `Cache Optimizer disabled · ${statsText}`;
@@ -5399,9 +5773,12 @@ export default function (pi: ExtensionAPI) {
     // Re-evaluated on every status update so the marker persists through stats
     // changes and day rollovers. Redundant setStatus calls are blocked by the
     // `lastStatusText` early return above.
-    if (runtimeOptimizerEnabled && statusText !== undefined && model) {
-      const compatMissing = describeMissingCacheCompatForModel(model);
-      if (compatMissing.length > 0) {
+    if (runtimeOptimizerEnabled && statusText !== undefined && displayModel) {
+      // Only show ⚠️ compat when there are safe-fixable missing compat keys.
+      // Optional/advisory-only flags (e.g. supportsLongCacheRetention on generic
+      // OpenAI-compatible proxies) do NOT trigger the marker — the doctor/compat
+      // commands still mention them as optional guidance.
+      if (buildFixSuggestion(displayModel) !== undefined) {
         statusText = statusText + " ⚠️ compat";
       }
     }
@@ -5412,18 +5789,26 @@ export default function (pi: ExtensionAPI) {
     ctx.ui.setStatus(STATUS_KEY, statusText);
   }
 
+  ensureRoutingRegistry();
+
   pi.on("session_start", async (event, ctx) => {
     await restoreCacheStats(event.reason, ctx);
-    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(ctx.model, ctx, warnedModels);
+    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(ctx.model, ctx) ?? ctx.model, ctx, warnedModels);
     await publishStatus(ctx);
   });
 
   pi.on("model_select", async (event, ctx) => {
-    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(event.model, ctx, warnedModels);
+    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(event.model, ctx) ?? event.model, ctx, warnedModels);
     await publishStatus(ctx, event.model);
   });
 
   pi.on("before_agent_start", async (event, _ctx) => {
+    latestCacheHint = undefined;
+    const routeSnapshot = resolveActiveRouteSnapshot(_ctx.model, _ctx);
+    const routedModel = routeSnapshot
+      ? findModelInRegistry(_ctx.modelRegistry, routeSnapshot.provider, routeSnapshot.modelId) ?? routeSnapshotToPiModel(routeSnapshot, _ctx.model)
+      : undefined;
+
     // ────────────────────────────────────────────────────────────────
     // OpenAI Responses-family bypass (codex-responses + responses + azure responses)
     //
@@ -5450,7 +5835,7 @@ export default function (pi: ExtensionAPI) {
     // compression, reorder) for these APIs. Third-party providers
     // that use openai-completions are unaffected.
     // ────────────────────────────────────────────────────────────────
-    const model = _ctx.model;
+    const model = routedModel ?? _ctx.model;
     if (model && isResponsesPromptRewriteBypassApi(model.api)) {
       return {};
     }
@@ -5488,7 +5873,27 @@ export default function (pi: ExtensionAPI) {
     // ships to the provider.
     const optimized = optimizeSystemPrompt(compressedPrompt, event.systemPromptOptions);
 
+    const promptCacheKey = getSessionPromptCacheKey(_ctx);
+    const cacheRetention = process.env[PI_CACHE_RETENTION_ENV] === LONG_CACHE_RETENTION_VALUE ? LONG_CACHE_RETENTION_VALUE : undefined;
+    const publishHint = (systemPrompt: string): void => {
+      latestCacheHint = {
+        sessionIdHash: currentSessionHashSet ? currentSessionHash : sessionHashFromContext(_ctx),
+        virtualProvider: routeSnapshot?.virtualProvider ?? _ctx.model?.provider,
+        virtualModelId: routeSnapshot?.virtualModelId ?? _ctx.model?.id,
+        upstreamProvider: routeSnapshot?.provider ?? model?.provider,
+        upstreamModelId: routeSnapshot?.modelId ?? model?.id,
+        api: model?.api,
+        systemPrompt,
+        promptCacheKey,
+        cacheRetention,
+        timestamp: Date.now(),
+      };
+      const globals = getProtocolGlobal();
+      globals.__piCacheOptimizerCacheKey__ = promptCacheKey;
+    };
+
     if (optimized.changed && optimized.systemPrompt.trim().length > 0) {
+      publishHint(optimized.systemPrompt);
       return { systemPrompt: optimized.systemPrompt };
     }
 
@@ -5497,24 +5902,28 @@ export default function (pi: ExtensionAPI) {
     // the volume cut even when reorder is a no-op (e.g., short sessions
     // where no stable candidate is long enough).
     if (compressedPrompt !== strippedPrompt && compressedPrompt.trim().length > 0) {
+      publishHint(compressedPrompt);
       return { systemPrompt: compressedPrompt };
     }
     if (strippedPrompt !== event.systemPrompt && strippedPrompt.trim().length > 0) {
+      publishHint(strippedPrompt);
       return { systemPrompt: strippedPrompt };
     }
 
+    publishHint(event.systemPrompt);
     return {};
   });
 
   pi.on("before_provider_request", (event, ctx) => {
     if (!shouldInjectOpenAIPromptCacheKey()) return undefined;
-    if (!isOpenAICompatibleApi(ctx.model?.api)) return undefined;
+    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+    if (!isOpenAICompatibleApi(requestModel?.api)) return undefined;
 
     return addOpenAIPromptCacheKey(event.payload, getSessionPromptCacheKey(ctx));
   });
 
   pi.on("after_provider_response", (event, ctx) => {
-    const model = ctx.model;
+    const model = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
     if (!runtimeOptimizerEnabled || !model) return;
     if (event.status !== 400) return;
     if (!isPromptCacheRetention400Applicable(model)) return;
@@ -5539,9 +5948,12 @@ export default function (pi: ExtensionAPI) {
 
     const usage = adapter.normalizeUsage(event.message);
 
-    const statsModel = isRouterModel(ctx.model) ? modelFromAssistantMessage(event.message, ctx.model) : ctx.model;
+    // Completed message metadata is request-local and authoritative for virtual
+    // routing providers. Use it whenever it supplies provider/model identity;
+    // fall back to the active context model for direct providers.
+    const statsModel = modelFromAssistantMessage(event.message, ctx.model) ?? ctx.model;
     let routedModelChanged = false;
-    if (isRouterModel(ctx.model) && statsModel && !isRouterModel(statsModel)) {
+    if (isVirtualRoutingModel(ctx.model, ctx) && statsModel && !isVirtualRoutingModel(statsModel, ctx)) {
       const nextRoutedModel: PersistedRoutedModelRef = {
         provider: statsModel.provider,
         id: statsModel.id,
@@ -5604,7 +6016,8 @@ export default function (pi: ExtensionAPI) {
     description: "Diagnose Pi cache configuration",
     handler: async (args: string, cmdCtx) => {
       syncSessionHash(cmdCtx);
-      const model = cmdCtx.model;
+      const selectedModel = cmdCtx.model;
+      const model = resolveRouteModel(selectedModel, cmdCtx as unknown as ExtensionContext) ?? selectedModel;
       const subcommand = args.trim().toLowerCase().split(/\s+/)[0] || "help";
 
       if (subcommand === "enable") {
@@ -5672,14 +6085,12 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        const sk = sessionModelKey(model);
         const displayKey = modelKey(model);
 
-        // Reset session-scoped stats for the active model.
-        delete cacheStatsByModel[sk];
-
-        // Clear recent samples for this session+model key.
-        recentSamplesByModelKey.delete(sk);
+        // Reset session-scoped stats for the effective active model. If the
+        // selected model is a virtual router and the protocol exposes a live
+        // route, this clears the real upstream bucket, not the router shell.
+        resetStatsForModel(model);
 
         // Persist immediately.
         await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
@@ -5755,7 +6166,7 @@ export default function (pi: ExtensionAPI) {
 
         // Compose the modified text — auto-detect the best placement level:
         // provider level (channel-wide) when safe for all sibling models, else model level.
-        const decision = decideFixPlacement(suggestion.compatKeys, suggestion.providerLabel, location.allModelIds);
+        const decision = chooseFixPlacement(originalText, location, suggestion.compatKeys, suggestion.providerLabel);
         const modifiedText = composeFixInsertion(originalText, location, suggestion.compatKeys, decision.placement);
 
         // Self-check
@@ -5769,10 +6180,9 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        // Build preview snippet
-        const keysPreview = Object.entries(suggestion.compatKeys)
-          .map(([k, v]) => `    ${k}: ${JSON.stringify(v)}`)
-          .join("\n");
+        // Build preview snippet as copyable JSON (the surgical editor will
+        // insert or repair these exact compat key/value pairs).
+        const keysPreview = JSON.stringify(suggestion.compatKeys, null, 2);
         const targetHasCompat = decision.placement === "provider" ? location.providerCompatBrace >= 0 : location.compatObjectBrace >= 0;
         const placementDesc = targetHasCompat ? `existing "compat" object` : `new "compat" object`;
         const locationDesc = decision.placement === "provider"
@@ -5791,7 +6201,7 @@ export default function (pi: ExtensionAPI) {
           ``,
           `Location: ${locationDesc}`,
           `Placement: ${decision.placement} level — ${decision.reason}`,
-          `Keys to insert:`, 
+          `Compat JSON to write:`,
           keysPreview,
           ``, 
           `⚠️  Risk notice:`,
@@ -5948,7 +6358,7 @@ export default function (pi: ExtensionAPI) {
               return;
             }
 
-            const menuDecision = decideFixPlacement(suggestion.compatKeys, suggestion.providerLabel, location.allModelIds);
+            const menuDecision = chooseFixPlacement(originalText, location, suggestion.compatKeys, suggestion.providerLabel);
             const modifiedText = composeFixInsertion(originalText, location, suggestion.compatKeys, menuDecision.placement);
             const checkError = selfCheckFix(originalText, modifiedText, suggestion.providerLabel, suggestion.modelId, suggestion.compatKeys);
             if (checkError !== null) {
@@ -5956,9 +6366,7 @@ export default function (pi: ExtensionAPI) {
               return;
             }
 
-            const keysPreview = Object.entries(suggestion.compatKeys)
-              .map(([k, v]) => `    ${k}: ${JSON.stringify(v)}`)
-              .join("\n");
+            const keysPreview = JSON.stringify(suggestion.compatKeys, null, 2);
             const ts = backupTimestamp();
             const backupPath = `${MODELS_JSON_PATH}.backup-cache-optimizer-${ts}`;
 
@@ -5973,7 +6381,7 @@ export default function (pi: ExtensionAPI) {
               `📝 Preview of changes to ${getModelsJsonDisplayPath()}:`,
               `Location: ${menuLocationDesc}`,
               `Placement: ${menuDecision.placement} level — ${menuDecision.reason}`,
-              `Keys to insert:`, 
+              `Compat JSON to write:`,
               keysPreview,
               ``, 
               `⚠️  Risk notice:`,
@@ -6025,10 +6433,8 @@ export default function (pi: ExtensionAPI) {
               if (!adapter) {
                 cmdCtx.ui.notify("ℹ️ Active model does not match a cache adapter. No stats to reset.", "info");
               } else {
-                const sk = sessionModelKey(model);
                 const displayKey = modelKey(model);
-                delete cacheStatsByModel[sk];
-                recentSamplesByModelKey.delete(sk);
+                resetStatsForModel(model);
                 await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
                 await publishStatus(cmdCtx as unknown as ExtensionContext, model);
                 cmdCtx.ui.notify(