pi-cache-optimizer 2.6.3 → 2.6.5

package/index.ts

@@ -162,9 +162,16 @@ type PersistedCacheStatsV2 = {
 };
 
 /** Per-model-key scoped state. Used in memory and for v3 persistence. */
+type PersistedRoutedModelRef = {
+  provider: string;
+  id: string;
+  name?: string;
+};
+
 type CacheStatsState = {
   statsByModel: Record<string, CacheStats>;
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
+  lastRoutedModelBySession?: Record<string, PersistedRoutedModelRef>;
 };
 
 type PersistedCacheStatsV3 = {
@@ -186,6 +193,13 @@ type PersistedCacheStatsV4 = {
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
 };
 
+type PersistedCacheStatsV5 = {
+  version: 5;
+  sessions: Record<string, Record<string, CacheStats>>;
+  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
+  lastRoutedModelBySession?: Record<string, PersistedRoutedModelRef>;
+};
+
 type UsageSnapshot = {
   cacheRead: number;
   cacheWrite: number;
@@ -1598,7 +1612,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;
 }
 
@@ -1623,9 +1637,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");
   }
@@ -1646,9 +1657,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");
   }
@@ -1656,6 +1664,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")) {
@@ -1746,21 +1768,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.
@@ -3105,12 +3128,58 @@ function parseCacheStats(value: unknown): CacheStats | undefined {
   };
 }
 
+function parsePersistedRoutedModelRef(value: unknown): PersistedRoutedModelRef | undefined {
+  const record = asRecord(value);
+  const provider = record?.provider;
+  const id = record?.id;
+  const name = record?.name;
+  if (!isNonEmptyString(provider) || !isNonEmptyString(id)) return undefined;
+
+  return {
+    provider: provider.trim(),
+    id: id.trim(),
+    name: isNonEmptyString(name) ? name.trim() : id.trim(),
+  };
+}
+
+function routedModelRefToPiModel(ref: PersistedRoutedModelRef): PiModel {
+  return {
+    id: ref.id,
+    name: ref.name ?? ref.id,
+    provider: ref.provider,
+    api: "",
+    baseUrl: "",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+  } as PiModel;
+}
+
+function buildExactRouterStatusEntry(
+  sessionHash: string | undefined,
+  statsByModel: Record<string, CacheStats>,
+  lastRoutedModel: PersistedRoutedModelRef | undefined,
+): { adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
+  if (!sessionHash || !lastRoutedModel) return undefined;
+
+  const model = routedModelRefToPiModel(lastRoutedModel);
+  const adapter = selectAdapterForModel(model);
+  if (!adapter) return undefined;
+
+  const key = makeSessionModelKey(sessionHash, lastRoutedModel.provider, lastRoutedModel.id);
+  return { adapter, stats: statsByModel[key] ?? emptyCacheStats() };
+}
+
 function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
   const record = asRecord(value);
   if (!record) return undefined;
 
-  // version 4: session-scoped stats + legacy family fallback
-  if (record.version === 4) {
+  // version 4/5: session-scoped stats + legacy family fallback.
+  // v5 additionally persists the last actual routed model per session so
+  // router/auto can restore the exact upstream footer after /reload.
+  if (record.version === 4 || record.version === 5) {
     const legacyFamily: Partial<Record<CacheProviderId, CacheStats>> = {};
     const rawFamily = asRecord(record.legacyFamily);
     if (rawFamily) {
@@ -3138,10 +3207,19 @@ function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
       }
     }
 
-    return { statsByModel, legacyFamily };
+    const lastRoutedModelBySession: Record<string, PersistedRoutedModelRef> = {};
+    const rawLastRoutedModels = asRecord(record.lastRoutedModelBySession);
+    if (rawLastRoutedModels) {
+      for (const [sessionHash, rawModel] of Object.entries(rawLastRoutedModels)) {
+        const parsed = parsePersistedRoutedModelRef(rawModel);
+        if (parsed) lastRoutedModelBySession[sessionHash] = parsed;
+      }
+    }
+
+    return { statsByModel, legacyFamily, lastRoutedModelBySession };
   }
 
-  // version 3: migrate to v4 semantics by wrapping statsByModel into sessions
+  // version 3: migrate to v4/v5 semantics by wrapping statsByModel into sessions
   if (record.version === 3) {
     const statsByModel: Record<string, CacheStats> = {};
     const rawModelMap = asRecord(record.statsByModel);
@@ -3335,11 +3413,38 @@ function mergeCacheSessions(
   return sessions;
 }
 
+function mergeLastRoutedModels(
+  existingLastRoutedModelBySession: Record<string, PersistedRoutedModelRef>,
+  state: CacheStatsState,
+  currentSessionHash?: string,
+): Record<string, PersistedRoutedModelRef> {
+  const merged: Record<string, PersistedRoutedModelRef> = { ...existingLastRoutedModelBySession };
+  const incoming = state.lastRoutedModelBySession ?? {};
+
+  if (currentSessionHash !== undefined) {
+    const current = incoming[currentSessionHash];
+    if (current) {
+      merged[currentSessionHash] = current;
+    } else {
+      // Explicit deletion: when incoming state has no entry for current session,
+      // remove any existing stale entry to reflect intentional reset.
+      delete merged[currentSessionHash];
+    }
+    return merged;
+  }
+
+  for (const [sessionHash, ref] of Object.entries(incoming)) {
+    merged[sessionHash] = ref;
+  }
+  return merged;
+}
+
 async function writePersistedCacheStats(state: CacheStatsState, currentSessionHash?: string): Promise<void> {
   await mkdir(STATE_DIR, { recursive: true });
 
   // Read existing file to preserve other sessions' data.
   let existingSessions: Record<string, Record<string, CacheStats>> = {};
+  let existingLastRoutedModelBySession: Record<string, PersistedRoutedModelRef> = {};
   try {
     const raw = await readFile(STATE_FILE_PATH, "utf8");
     const parsed = parsePersistedCacheStats(JSON.parse(raw));
@@ -3355,17 +3460,24 @@ async function writePersistedCacheStats(state: CacheStatsState, currentSessionHa
           existingSessions[hash][modelKey] = stats;
         }
       }
+      existingLastRoutedModelBySession = { ...(parsed.lastRoutedModelBySession ?? {}) };
     }
   } catch {
     // Ignore read errors (file may not exist yet).
   }
 
   const sessions = mergeCacheSessions(existingSessions, state, currentSessionHash);
+  const lastRoutedModelBySession = mergeLastRoutedModels(
+    existingLastRoutedModelBySession,
+    state,
+    currentSessionHash,
+  );
 
-  const payload: PersistedCacheStatsV4 = {
-    version: 4,
+  const payload: PersistedCacheStatsV5 = {
+    version: 5,
     sessions,
     legacyFamily: state.legacyFamily,
+    ...(Object.keys(lastRoutedModelBySession).length > 0 ? { lastRoutedModelBySession } : {}),
   };
   const tempPath = `${STATE_FILE_PATH}.${process.pid}.${Date.now()}.tmp`;
 
@@ -3430,8 +3542,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; " +
@@ -3466,8 +3579,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 " +
@@ -3594,8 +3708,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;
@@ -3607,9 +3734,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));
   }
@@ -3667,7 +3796,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);
@@ -3685,7 +3815,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;
 
@@ -3714,7 +3844,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.");
   }
@@ -3767,11 +3897,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[] = [];
@@ -3781,7 +3917,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).`);
@@ -3791,16 +3932,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));
     }
@@ -4031,8 +4174,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) {
@@ -4046,39 +4191,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.
@@ -4122,153 +4302,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
@@ -4279,83 +4357,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;
@@ -4496,6 +4543,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,
@@ -4507,14 +4596,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`.
@@ -4527,25 +4614,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]);
+    }
+
+    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}` });
+      }
     }
-    // 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);
+
+    // 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 `{`. ──
@@ -4566,12 +4680,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.
@@ -4584,17 +4698,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`;
     }
 
@@ -4612,6 +4726,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
@@ -4654,15 +4780,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}`)) {
@@ -4681,11 +4815,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;
@@ -4701,8 +4841,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');
 }
@@ -4752,6 +4891,7 @@ export const __internals_for_tests = {
   isOpenAIFamilyToken,
   describeMissingOpenAIFamilyProxyCompat,
   describeMissingOpenAICompatibleProxyCompat,
+  describeOptionalOpenAICompatibleProxyCompat,
   describeMissingDeepSeekCompat,
   isDeepSeekCompatCheckApplicable,
   describeMissingCacheCompatForModel,
@@ -4919,8 +5059,12 @@ export const __internals_for_tests = {
   makeSessionModelKey,
   modelKeyFromSessionKey,
   filterRestorableStatsForSession,
+  parsePersistedRoutedModelRef,
+  routedModelRefToPiModel,
+  buildExactRouterStatusEntry,
   // Persistence helpers (for reload/reset tests)
   mergeCacheSessions,
+  mergeLastRoutedModels,
   writePersistedCacheStats,
   readPersistedCacheStats,
   STATE_FILE_PATH,
@@ -4929,10 +5073,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,
@@ -4960,6 +5108,7 @@ export default function (pi: ExtensionAPI) {
   let currentSessionId = "";
   let currentSessionHash = "";
   let currentSessionHashSet = false;
+  let lastActualRoutedModel: PersistedRoutedModelRef | 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[]>();
@@ -4970,6 +5119,7 @@ export default function (pi: ExtensionAPI) {
       currentSessionId = sid;
       currentSessionHash = hashSessionId(sid);
       currentSessionHashSet = true;
+      lastActualRoutedModel = undefined;
     }
   }
 
@@ -5019,7 +5169,13 @@ export default function (pi: ExtensionAPI) {
   }
 
   function getCacheStatsState(): CacheStatsState {
-    return { statsByModel: cacheStatsByModel, legacyFamily: cacheStatsLegacyFamily };
+    return {
+      statsByModel: cacheStatsByModel,
+      legacyFamily: cacheStatsLegacyFamily,
+      ...(currentSessionHashSet && lastActualRoutedModel
+        ? { lastRoutedModelBySession: { [currentSessionHash]: lastActualRoutedModel } }
+        : {}),
+    };
   }
 
   /** Look up active stats for a model, falling back to legacy family. */
@@ -5146,6 +5302,9 @@ export default function (pi: ExtensionAPI) {
         currentSessionHashSet ? currentSessionHash : undefined,
       );
       cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
+      lastActualRoutedModel = currentSessionHashSet
+        ? persisted?.lastRoutedModelBySession?.[currentSessionHash]
+        : undefined;
 
       await rollOverStatsIfNeeded(ctx);
       return;
@@ -5160,10 +5319,63 @@ export default function (pi: ExtensionAPI) {
       currentSessionHashSet ? currentSessionHash : undefined,
     );
     cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
+    lastActualRoutedModel = currentSessionHashSet
+      ? persisted?.lastRoutedModelBySession?.[currentSessionHash]
+      : undefined;
     lastStatusText = undefined;
     await rollOverStatsIfNeeded(ctx);
   }
 
+  /**
+   * Fallback for older persisted files that do not yet carry exact
+   * last-routed-model metadata. When the current model is a router channel
+   * (e.g. router/auto), restorable stats are stored under the real upstream
+   * model's provider/id key, not under router/auto. Find the best valid entry
+   * (highest totalRequests among adapter-detectable model keys) so we can show
+   * meaningful footer content on session_start after reload.
+   */
+  function findBestRouterModelStats(): { adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
+    if (!currentSessionHash) return undefined;
+    const prefix = `${currentSessionHash}:`;
+    let best: { adapter: CacheProviderAdapter; stats: CacheStats; total: number } | undefined;
+
+    for (const [key, stats] of Object.entries(cacheStatsByModel)) {
+      if (!key.startsWith(prefix)) continue;
+
+      // Extract provider/id from key like "abc123:run-claude/claude-opus-4-8"
+      const modelKeyPart = key.slice(prefix.length);
+      const slashIdx = modelKeyPart.indexOf("/");
+      if (slashIdx < 0 || slashIdx >= modelKeyPart.length - 1) continue;
+      const modelId = modelKeyPart.slice(slashIdx + 1);
+      const providerName = modelKeyPart.slice(0, slashIdx);
+
+      // Construct a minimal model for adapter detection.
+      // Every is*LikeModel function only accesses model.id and model.name
+      // via getModelIdNameTokenValues, so { id, name } is sufficient.
+      const mockModel = {
+        id: modelId,
+        name: modelId,
+        provider: providerName,
+        api: "",
+        baseUrl: "",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 0,
+        maxTokens: 0,
+      } as PiModel;
+
+      const adapter = selectAdapterForModel(mockModel);
+      if (!adapter) continue;
+
+      if (!best || stats.totalRequests > best.total) {
+        best = { adapter, stats, total: stats.totalRequests };
+      }
+    }
+
+    return best ? { adapter: best.adapter, stats: best.stats } : undefined;
+  }
+
   async function publishStatus(ctx: ExtensionContext, model: PiModel | undefined = ctx.model): Promise<void> {
     syncSessionHash(ctx);
     await rollOverStatsIfNeeded(ctx);
@@ -5171,11 +5383,23 @@ export default function (pi: ExtensionAPI) {
     const adapter = selectAdapterForModel(model);
     let statusText: string | undefined;
     if (!adapter && isRouterModel(model)) {
-      // router/auto has no stable target family before the first successful
-      // routed response. Keep the existing cache footer visible instead of
-      // clearing it on model_select; message_end will switch to the real
-      // upstream model/provider after pi-router relays the response metadata.
-      return;
+      // 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
+      // for this session when available; fall back to older best-effort
+      // heuristics only when no exact metadata exists.
+      if (lastStatusText !== undefined) return;
+      const realEntry = buildExactRouterStatusEntry(
+        currentSessionHashSet ? currentSessionHash : undefined,
+        cacheStatsByModel,
+        lastActualRoutedModel,
+      ) ?? findBestRouterModelStats();
+      if (realEntry) {
+        const statsText = formatCacheStats(realEntry.adapter, realEntry.stats);
+        statusText = runtimeOptimizerEnabled
+          ? statsText
+          : `Cache Optimizer disabled · ${statsText}`;
+      }
     }
 
     if (adapter) {
@@ -5220,8 +5444,11 @@ export default function (pi: ExtensionAPI) {
     // 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) {
+      // 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(model) !== undefined) {
         statusText = statusText + " ⚠️ compat";
       }
     }
@@ -5360,6 +5587,23 @@ export default function (pi: ExtensionAPI) {
     const usage = adapter.normalizeUsage(event.message);
 
     const statsModel = isRouterModel(ctx.model) ? modelFromAssistantMessage(event.message, ctx.model) : ctx.model;
+    let routedModelChanged = false;
+    if (isRouterModel(ctx.model) && statsModel && !isRouterModel(statsModel)) {
+      const nextRoutedModel: PersistedRoutedModelRef = {
+        provider: statsModel.provider,
+        id: statsModel.id,
+        name: statsModel.name || statsModel.id,
+      };
+      if (
+        !lastActualRoutedModel ||
+        lastActualRoutedModel.provider !== nextRoutedModel.provider ||
+        lastActualRoutedModel.id !== nextRoutedModel.id ||
+        (lastActualRoutedModel.name || lastActualRoutedModel.id) !== (nextRoutedModel.name || nextRoutedModel.id)
+      ) {
+        lastActualRoutedModel = nextRoutedModel;
+        routedModelChanged = true;
+      }
+    }
 
     // Record recent sample (even when usage is missing, for trend diagnosis)
     if (statsModel) {
@@ -5370,7 +5614,10 @@ export default function (pi: ExtensionAPI) {
       recordRecentSample(sk, usage ?? { cacheRead: 0, cacheWrite: 0, totalInput: 0 }, missingFields);
     }
 
-    if (!usage) return;
+    if (!usage) {
+      if (routedModelChanged) schedulePersistCacheStats(ctx);
+      return;
+    }
 
     await rollOverStatsIfNeeded(ctx);
 
@@ -5555,7 +5802,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
@@ -5569,10 +5816,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"
@@ -5591,7 +5837,7 @@ export default function (pi: ExtensionAPI) {
           ``,
           `Location: ${locationDesc}`,
           `Placement: ${decision.placement} level — ${decision.reason}`,
-          `Keys to insert:`, 
+          `Compat JSON to write:`,
           keysPreview,
           ``, 
           `⚠️  Risk notice:`,
@@ -5748,7 +5994,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) {
@@ -5756,9 +6002,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}`;
 
@@ -5773,7 +6017,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:`,