pi-cache-optimizer 2.8.3 → 2.8.5

package/index.ts

@@ -1,6 +1,6 @@
-import { createHash } from "node:crypto";
-import { chmod, copyFile, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { constants as fsConstants, readFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { constants as fsConstants, readFileSync, watch } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import {
@@ -21,6 +21,7 @@ type CacheRetentionEnvSnapshot = {
 const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
 const LONG_CACHE_RETENTION_VALUE = "long";
 const PI_CACHE_RETENTION_BASELINE_SYMBOL = Symbol.for("pi.cache.optimizer.retention-baseline.v1");
+const ROUTED_FALLBACK_MODEL_SYMBOL = Symbol("pi-cache-optimizer.routed-fallback-model");
 
 type CacheRetentionBaselineV1 = {
   version: 1;
@@ -102,7 +103,19 @@ const STATUS_KEY = "pi-cache-stats";
 const STATE_DIR = getAgentDir();
 const STATE_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-stats.json");
 const LEGACY_STATE_FILE_PATH = join(STATE_DIR, "deepseek-cache-optimizer-stats.json");
+const SHARD_STATE_DIR = join(STATE_DIR, "pi-cache-optimizer-stats.d");
+const SHARD_FILES_DIR = join(SHARD_STATE_DIR, "shards");
+const SHARD_EPOCH_DIR = join(SHARD_STATE_DIR, "epochs");
+const SHARD_MODEL_EPOCH_DIR = join(SHARD_EPOCH_DIR, "models");
+const SHARD_MAINTENANCE_DIR = join(SHARD_STATE_DIR, "maintenance");
+const SHARD_GLOBAL_EPOCH_PATH = join(SHARD_EPOCH_DIR, "global.json");
+const SHARD_CLEANUP_LOCK_PATH = join(SHARD_MAINTENANCE_DIR, "cleanup.lock");
+const SHARD_CLEANUP_MARKER_PATH = join(SHARD_MAINTENANCE_DIR, "last-cleanup");
 const CONFIG_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-config.json");
+const SHARD_RETENTION_MS = 48 * 60 * 60 * 1000;
+const SHARD_TEMP_RETENTION_MS = 24 * 60 * 60 * 1000;
+const SHARD_CLEANUP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const SHARD_CLEANUP_LOCK_STALE_MS = 60 * 60 * 1000;
 const CACHE_PROVIDER_IDS: CacheProviderId[] = ["deepseek", "openai", "claude", "gemini"];
 const OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY";
 const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
@@ -224,6 +237,10 @@ type CacheCompat = {
   cacheControlFormat?: string;
   forceAdaptiveThinking?: boolean;
   allowEmptySignature?: boolean;
+  openRouterRouting?: UnknownRecord;
+  vercelGatewayRouting?: UnknownRecord;
+  chatTemplateKwargs?: UnknownRecord;
+  chatTemplateArgs?: UnknownRecord;
 };
 
 type CacheStats = {
@@ -379,6 +396,46 @@ type OptimizedSystemPrompt = {
  * Contains only numeric counters and booleans — never message content, prompts,
  * payloads, headers, API keys, or model outputs.
  */
+type PersistedStatsShardV7 = {
+  version: 7;
+  kind: "pi-cache-optimizer-shard";
+  instanceId: string;
+  sessionHash: string;
+  process: {
+    pid: number;
+    ppid: number;
+    instanceStartedAt: number;
+  };
+  lifecycle: {
+    state: "active" | "closed";
+    createdAt: number;
+    updatedAt: number;
+    closedAt?: number;
+  };
+  day: string;
+  globalEpoch: string;
+  models: Record<string, {
+    modelEpoch: string;
+    provider: string;
+    modelId: string;
+    modelName?: string;
+    api?: string;
+    stats: CacheStats;
+  }>;
+  lastRoutedModel?: PersistedRoutedModelRef;
+};
+
+type ShardAggregate = {
+  bySession: Record<string, Record<string, CacheStats>>;
+  totalsByModel: Record<string, CacheStats>;
+  instancesBySession: Record<string, number>;
+  instancesBySessionModel: Record<string, Record<string, number>>;
+  sessionsByModel: Record<string, number>;
+  instancesByModel: Record<string, number>;
+  modelRefsByKey: Record<string, PersistedRoutedModelRef>;
+  lastRoutedModelBySession: Record<string, PersistedRoutedModelRef>;
+};
+
 type CacheUsageSample = {
   timestamp: number;
   hit: boolean;
@@ -961,19 +1018,23 @@ function resolveActiveRouteSnapshot(
 }
 
 function routeSnapshotToPiModel(snapshot: PiRouteSnapshot, fallback?: PiModel): PiModel {
+  const sameIdentity = fallback?.provider === snapshot.provider && fallback?.id === snapshot.modelId;
   return {
-    ...(fallback ?? {}),
+    ...(sameIdentity ? 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,
+    api: snapshot.api ?? (sameIdentity ? fallback?.api : undefined) ?? "",
+    baseUrl: sameIdentity ? fallback?.baseUrl ?? "" : "",
+    reasoning: sameIdentity ? fallback?.reasoning ?? false : false,
+    input: sameIdentity ? fallback?.input ?? ["text"] : ["text"],
+    cost: sameIdentity
+      ? fallback?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+      : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: sameIdentity ? fallback?.contextWindow ?? 0 : 0,
+    maxTokens: sameIdentity ? fallback?.maxTokens ?? 0 : 0,
+    compat: sameIdentity ? fallback?.compat : undefined,
+    [ROUTED_FALLBACK_MODEL_SYMBOL]: true,
   } as PiModel;
 }
 
@@ -989,6 +1050,27 @@ function findModelInRegistry(registry: ModelRegistryLike | undefined, provider:
   return all.find((candidate) => candidate.provider === provider && candidate.id === id);
 }
 
+function isRoutedFallbackModel(model: PiModel | undefined): boolean {
+  return !!model && (model as PiModel & Record<symbol, unknown>)[ROUTED_FALLBACK_MODEL_SYMBOL] === true;
+}
+
+function applyConfiguredTransportToModel(model: PiModel, config: unknown): PiModel {
+  const providers = asRecord(asRecord(config)?.providers);
+  const provider = asRecord(providers?.[model.provider]);
+  const customModel = Array.isArray(provider?.models)
+    ? asRecord(provider.models.find((entry: unknown) => asRecord(entry)?.id === model.id))
+    : undefined;
+  const configuredApi = customModel?.api ?? provider?.api;
+  const configuredBaseUrl = customModel?.baseUrl ?? provider?.baseUrl;
+  const api = isNonEmptyString(model.api)
+    ? model.api
+    : (isNonEmptyString(configuredApi) ? configuredApi : model.api);
+  const baseUrl = isNonEmptyString(model.baseUrl)
+    ? model.baseUrl
+    : (isNonEmptyString(configuredBaseUrl) ? configuredBaseUrl : model.baseUrl);
+  return api === model.api && baseUrl === model.baseUrl ? model : { ...model, api, baseUrl };
+}
+
 function resolveRouteModel(
   model: PiModel | undefined,
   ctx?: ContextWithOptionalModelRegistry,
@@ -996,8 +1078,9 @@ function resolveRouteModel(
   const snapshot = resolveActiveRouteSnapshot(model, ctx);
   if (!snapshot) return undefined;
 
-  return findModelInRegistry(ctx?.modelRegistry, snapshot.provider, snapshot.modelId)
+  const resolved = findModelInRegistry(ctx?.modelRegistry, snapshot.provider, snapshot.modelId)
     ?? routeSnapshotToPiModel(snapshot, model);
+  return applyConfiguredTransportToModel(resolved, readEffectiveCompatConfig());
 }
 
 function isVirtualRoutingModel(model: PiModel | undefined, ctx?: Pick<ExtensionContext, "sessionManager">): boolean {
@@ -1082,17 +1165,286 @@ function getNonNegativeNumber(record: UnknownRecord, key: string): number | unde
  * Model-level compat takes precedence over provider-level compat for overlapping keys.
  * This matches Pi's model-registry.js mergeCompat behavior.
  */
+const NESTED_COMPAT_KEYS = [
+  "openRouterRouting",
+  "vercelGatewayRouting",
+  "chatTemplateKwargs",
+  "chatTemplateArgs",
+] as const;
+
+function mergeCacheCompat(...sources: Array<UnknownRecord | undefined>): CacheCompat {
+  const merged: CacheCompat = {};
+  for (const source of sources) {
+    if (!source) continue;
+    const previousNested = Object.fromEntries(
+      NESTED_COMPAT_KEYS.map((key) => [key, asRecord(merged[key])]),
+    ) as Partial<Record<(typeof NESTED_COMPAT_KEYS)[number], UnknownRecord | undefined>>;
+    Object.assign(merged, source);
+    for (const key of NESTED_COMPAT_KEYS) {
+      const baseValue = previousNested[key];
+      const overrideValue = asRecord(source[key]);
+      if (baseValue || overrideValue) {
+        merged[key] = { ...baseValue, ...overrideValue };
+      }
+    }
+  }
+  return merged;
+}
+
+function getEffectiveCompatSources(model: PiModel, config: unknown): Array<{ source: "provider" | "model" | "runtime" | "modelOverride"; compat: UnknownRecord }> {
+  const root = asRecord(config);
+  const providers = asRecord(root?.providers);
+  const provider = asRecord(providers?.[model.provider]);
+  const providerCompat = asRecord(provider?.compat);
+  const customModel = Array.isArray(provider?.models)
+    ? provider.models.find((entry: unknown) => asRecord(entry)?.id === model.id)
+    : undefined;
+  const customModelCompat = asRecord(asRecord(customModel)?.compat);
+  const runtimeCompat = asRecord(model.compat);
+  const modelOverride = asRecord(asRecord(provider?.modelOverrides)?.[model.id]);
+  const modelOverrideCompat = asRecord(modelOverride?.compat);
+
+  return [
+    ...(providerCompat ? [{ source: "provider" as const, compat: providerCompat }] : []),
+    ...(customModelCompat ? [{ source: "model" as const, compat: customModelCompat }] : []),
+    ...(runtimeCompat ? [{ source: "runtime" as const, compat: runtimeCompat }] : []),
+    ...(modelOverrideCompat ? [{ source: "modelOverride" as const, compat: modelOverrideCompat }] : []),
+  ];
+}
+
+function resolveEffectiveCompatFromConfig(model: PiModel, config: unknown): CacheCompat {
+  // Pi's effective precedence is provider → models[] → runtime model →
+  // modelOverrides. The runtime layer is intentionally included between the
+  // config model and modelOverride: extension providers can replace the model
+  // object after lower config layers were applied, while the override remains
+  // Pi's highest-precedence user layer.
+  return mergeCacheCompat(...getEffectiveCompatSources(model, config).map(({ compat }) => compat));
+}
+
+function getEffectiveCompatValueSource(
+  model: PiModel,
+  config: unknown,
+  key: keyof CacheCompat,
+): "provider" | "model" | "runtime" | "modelOverride" | undefined {
+  let source: "provider" | "model" | "runtime" | "modelOverride" | undefined;
+  for (const candidate of getEffectiveCompatSources(model, config)) {
+    if (Object.prototype.hasOwnProperty.call(candidate.compat, key)) source = candidate.source;
+  }
+  return source;
+}
+
+function isOptionalString(value: unknown): boolean {
+  return value === undefined || (typeof value === "string" && value.length > 0);
+}
+
+function isOptionalBoolean(value: unknown): boolean {
+  return value === undefined || typeof value === "boolean";
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isRecordOfStrings(value: unknown): boolean {
+  const record = asRecord(value);
+  return !!record && Object.values(record).every((entry) => typeof entry === "string");
+}
+
+function isThinkingLevelMap(value: unknown): boolean {
+  const map = asRecord(value);
+  if (!map) return false;
+  return ["off", "minimal", "low", "medium", "high", "xhigh", "max"].every((key) =>
+    map[key] === undefined || map[key] === null || typeof map[key] === "string"
+  );
+}
+
+function isValidModelCostTier(value: unknown): boolean {
+  const tier = asRecord(value);
+  return !!tier
+    && isFiniteNumber(tier.inputTokensAbove)
+    && isFiniteNumber(tier.input)
+    && isFiniteNumber(tier.output)
+    && isFiniteNumber(tier.cacheRead)
+    && isFiniteNumber(tier.cacheWrite);
+}
+
+function isValidModelCost(value: unknown, partial: boolean): boolean {
+  const cost = asRecord(value);
+  if (!cost) return false;
+  for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
+    if ((!partial || cost[key] !== undefined) && !isFiniteNumber(cost[key])) return false;
+  }
+  return cost.tiers === undefined || (Array.isArray(cost.tiers) && cost.tiers.every(isValidModelCostTier));
+}
+
+function isValidModelDefinition(value: unknown): boolean {
+  const model = asRecord(value);
+  if (!model || !isNonEmptyString(model.id)) return false;
+  if (!isOptionalString(model.name) || !isOptionalString(model.api) || !isOptionalString(model.baseUrl)) return false;
+  if (!isOptionalBoolean(model.reasoning) || !isValidCompatRecord(model.compat)) return false;
+  if (model.thinkingLevelMap !== undefined && !isThinkingLevelMap(model.thinkingLevelMap)) return false;
+  if (model.input !== undefined && (!Array.isArray(model.input) || !model.input.every((entry) => entry === "text" || entry === "image"))) return false;
+  if (model.cost !== undefined && !isValidModelCost(model.cost, false)) return false;
+  if (model.contextWindow !== undefined && !isFiniteNumber(model.contextWindow)) return false;
+  if (model.maxTokens !== undefined && !isFiniteNumber(model.maxTokens)) return false;
+  if (model.samplingParams !== undefined && !asRecord(model.samplingParams)) return false;
+  if (model.headers !== undefined && !isRecordOfStrings(model.headers)) return false;
+  return true;
+}
+
+function isValidModelOverride(value: unknown): boolean {
+  const override = asRecord(value);
+  if (!override || !isValidCompatRecord(override.compat)) return false;
+  if (!isOptionalString(override.name) || !isOptionalBoolean(override.reasoning)) return false;
+  if (override.thinkingLevelMap !== undefined && !isThinkingLevelMap(override.thinkingLevelMap)) return false;
+  if (override.input !== undefined && (!Array.isArray(override.input) || !override.input.every((entry) => entry === "text" || entry === "image"))) return false;
+  if (override.cost !== undefined && !isValidModelCost(override.cost, true)) return false;
+  if (override.contextWindow !== undefined && !isFiniteNumber(override.contextWindow)) return false;
+  if (override.maxTokens !== undefined && !isFiniteNumber(override.maxTokens)) return false;
+  if (override.samplingParams !== undefined && !asRecord(override.samplingParams)) return false;
+  if (override.headers !== undefined && !isRecordOfStrings(override.headers)) return false;
+  return true;
+}
+
+function isValidOpenAICompletionsCompat(compat: UnknownRecord): boolean {
+  const booleanKeys = [
+    "supportsStore", "supportsDeveloperRole", "supportsReasoningEffort",
+    "supportsUsageInStreaming", "requiresToolResultName", "requiresAssistantAfterToolResult",
+    "requiresThinkingAsText", "requiresReasoningContentOnAssistantMessages",
+    "supportsOpenAIGrammarTools", "supportsStrictMode", "sendSessionAffinityHeaders",
+    "supportsLongCacheRetention",
+  ];
+  if (booleanKeys.some((key) => !isOptionalBoolean(compat[key]))) return false;
+  if (compat.maxTokensField !== undefined && compat.maxTokensField !== "max_completion_tokens" && compat.maxTokensField !== "max_tokens") return false;
+  if (compat.thinkingFormat !== undefined && ![
+    "openai", "openrouter", "together", "baseten", "deepseek", "zai", "qwen",
+    "chat-template", "qwen-chat-template", "string-thinking", "ant-ling",
+  ].includes(String(compat.thinkingFormat))) return false;
+  if (compat.cacheControlFormat !== undefined && compat.cacheControlFormat !== "anthropic") return false;
+  if (compat.deferredToolsMode !== undefined && compat.deferredToolsMode !== "kimi") return false;
+  if (compat.sessionAffinityFormat !== undefined && !["openai", "openai-nosession", "openrouter"].includes(String(compat.sessionAffinityFormat))) return false;
+  for (const key of NESTED_COMPAT_KEYS) {
+    if (compat[key] !== undefined && !asRecord(compat[key])) return false;
+  }
+  return true;
+}
+
+function isValidOpenAIResponsesCompat(compat: UnknownRecord): boolean {
+  const booleanKeys = [
+    "supportsDeveloperRole", "supportsLongCacheRetention", "supportsStrictMode",
+    "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch",
+  ];
+  if (booleanKeys.some((key) => !isOptionalBoolean(compat[key]))) return false;
+  return compat.sessionAffinityFormat === undefined
+    || ["openai", "openai-nosession", "openrouter"].includes(String(compat.sessionAffinityFormat));
+}
+
+function isValidAnthropicMessagesCompat(compat: UnknownRecord): boolean {
+  return [
+    "supportsEagerToolInputStreaming", "supportsLongCacheRetention",
+    "sendSessionAffinityHeaders", "supportsCacheControlOnTools", "supportsTemperature",
+    "forceAdaptiveThinking", "allowEmptySignature", "supportsStrictTools", "supportsToolReferences",
+  ].every((key) => isOptionalBoolean(compat[key]));
+}
+
+function isValidCompatRecord(value: unknown): boolean {
+  if (value === undefined) return true;
+  const compat = asRecord(value);
+  return !!compat && (
+    isValidOpenAICompletionsCompat(compat)
+    || isValidOpenAIResponsesCompat(compat)
+    || isValidAnthropicMessagesCompat(compat)
+  );
+}
+
+function isValidModelsConfigForEffectiveCompat(value: unknown): boolean {
+  const root = asRecord(value);
+  const providers = asRecord(root?.providers);
+  if (!root || !providers) return false;
+
+  for (const providerValue of Object.values(providers)) {
+    const provider = asRecord(providerValue);
+    if (!provider) return false;
+    if (!isOptionalString(provider.name) || !isOptionalString(provider.baseUrl) || !isOptionalString(provider.apiKey) || !isOptionalString(provider.api)) return false;
+    if (!isOptionalBoolean(provider.authHeader) || !isValidCompatRecord(provider.compat)) return false;
+    if (provider.oauth !== undefined && provider.oauth !== "radius") return false;
+    if (provider.headers !== undefined && !isRecordOfStrings(provider.headers)) return false;
+    if (provider.models !== undefined && (!Array.isArray(provider.models) || !provider.models.every(isValidModelDefinition))) return false;
+    const overrides = provider.modelOverrides === undefined ? undefined : asRecord(provider.modelOverrides);
+    if (provider.modelOverrides !== undefined && (!overrides || !Object.values(overrides).every(isValidModelOverride))) return false;
+  }
+  return true;
+}
+
+function readEffectiveCompatConfig(): unknown | undefined {
+  try {
+    const parsed = parseJsonc(readFileSync(MODELS_JSON_PATH, "utf8"));
+    return isValidModelsConfigForEffectiveCompat(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function getCompat(model: PiModel | undefined): CacheCompat {
   if (!model) return {} as CacheCompat;
+  return resolveEffectiveCompatFromConfig(model, readEffectiveCompatConfig());
+}
+
+function hasProviderHeader(headers: Record<string, unknown>, name: string): boolean {
+  const normalized = name.toLowerCase();
+  return Object.keys(headers).some((headerName) => headerName.toLowerCase() === normalized);
+}
 
-  // Pi merges provider.compat with model.compat (model wins on conflicts)
-  // We approximate this by reading from ctx.model which should already have merged compat
-  // However, for safety, we check both levels if available
-  const modelCompat = (model.compat ?? {}) as CacheCompat;
+function setProviderHeaderIfMissing(
+  headers: Record<string, string | null | undefined>,
+  name: string,
+  value: string,
+): boolean {
+  if (hasProviderHeader(headers, name)) return false;
+  headers[name] = value;
+  return true;
+}
 
-  // Note: ctx.model from Pi should already contain merged compat,
-  // but we document the two-level structure for clarity
-  return modelCompat;
+function addEffectiveSessionAffinityHeaders(
+  headers: Record<string, string | null | undefined>,
+  model: PiModel | undefined,
+  sessionId: string | undefined,
+  effectiveCompat?: CacheCompat,
+  optimizerEnabled: boolean = runtimeOptimizerEnabled,
+  effectiveSource?: "provider" | "model" | "runtime" | "modelOverride",
+): boolean {
+  if (!optimizerEnabled || !model || !isNonEmptyString(sessionId)) return false;
+  if (!isOpenAICompatibleProxyApi(model.api) || !isNonEmptyString(model.baseUrl) || isOfficialOpenAIBaseUrl(model)) return false;
+  const config = effectiveCompat === undefined || effectiveSource === undefined
+    ? readEffectiveCompatConfig()
+    : undefined;
+  const compat = effectiveCompat ?? resolveEffectiveCompatFromConfig(model, config);
+  const source = effectiveSource
+    ?? getEffectiveCompatValueSource(model, config, "sendSessionAffinityHeaders")
+    ?? (Object.prototype.hasOwnProperty.call(asRecord(model.compat) ?? {}, "sendSessionAffinityHeaders") ? "runtime" : undefined);
+  if (compat.sendSessionAffinityHeaders !== true) return false;
+
+  // Pi already handles an effective runtime-model true. The bridge is only for
+  // effective values that live in models.json layers and were lost when an
+  // extension provider rebuilt/replaced the runtime model object.
+  if (source === "runtime") return false;
+
+  const format = compat.sessionAffinityFormat ?? (
+    lower(model.provider).includes("openrouter") || lower(model.baseUrl).includes("openrouter.ai")
+      ? "openrouter"
+      : "openai"
+  );
+  const value = sessionId.trim();
+  let changed = false;
+  if (format === "openrouter") {
+    return setProviderHeaderIfMissing(headers, "x-session-id", value);
+  }
+  if (format === "openai") {
+    changed = setProviderHeaderIfMissing(headers, "session_id", value) || changed;
+  }
+  changed = setProviderHeaderIfMissing(headers, "x-client-request-id", value) || changed;
+  changed = setProviderHeaderIfMissing(headers, "x-session-affinity", value) || changed;
+  return changed;
 }
 
 /** Join display-only path fragments without resolving them for I/O. */
@@ -1171,6 +1523,7 @@ const CACHE_OPTIMIZER_COMMANDS = [
 ] as const;
 const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode"] as const;
 const CACHE_OPTIMIZER_FOOTER_MODES = ["total", "session", "process"] as const;
+const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"] as const;
 
 function filterCommandCompletionItems(
   values: readonly string[],
@@ -1209,9 +1562,18 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix: string): CommandCo
     if (subcommandPrefix === "config") {
       return filterCommandCompletionItems(CACHE_OPTIMIZER_CONFIG_ARGUMENTS, "", "config");
     }
+    if (subcommandPrefix === "stats") {
+      return filterCommandCompletionItems(CACHE_OPTIMIZER_STATS_ARGUMENTS, "", "stats");
+    }
     return filterCommandCompletionItems(CACHE_OPTIMIZER_COMMANDS, parts[0]);
   }
 
+  if (parts[0].toLowerCase() === "stats") {
+    return parts.length === 2
+      ? filterCommandCompletionItems(CACHE_OPTIMIZER_STATS_ARGUMENTS, parts[1], "stats")
+      : null;
+  }
+
   if (parts[0].toLowerCase() !== "config") return null;
 
   if (parts.length === 2) {
@@ -1267,7 +1629,7 @@ function resolveFooterStatsMode(
 ): { mode: FooterStatsMode; source: FooterStatsModeSource } {
   if (configuredMode) return { mode: configuredMode, source: "config" };
   const envMode = parseFooterStatsMode(env[FOOTER_MODE_ENV]);
-  return envMode ? { mode: envMode, source: "env" } : { mode: "total", source: "default" };
+  return envMode ? { mode: envMode, source: "env" } : { mode: "session", source: "default" };
 }
 
 function footerStatsMode(
@@ -1564,6 +1926,14 @@ function isKimiCodingEmptySignatureModel(model: PiModel | undefined): boolean {
 }
 
 function isAdaptiveThinkingCompatApplicable(model: PiModel): boolean {
+  // A routed registry miss may preserve the upstream API/model identity while
+  // lacking a verified endpoint. Do not diagnose or suggest compat fixes for
+  // that incomplete transport metadata; ordinary direct Anthropic models still
+  // use their normal native adaptive-thinking check.
+  if (isRoutedFallbackModel(model) && !isNonEmptyString(model.baseUrl)) {
+    return false;
+  }
+
   return lower(model.api) === "anthropic-messages"
     && (isAdaptiveGenerationModel(model) || isKimiCodingAdaptiveModel(model));
 }
@@ -2389,13 +2759,17 @@ function isOfficialOpenAIBaseUrl(model: PiModel): boolean {
   }
 }
 
+function isKnownThirdPartyOpenAIEndpoint(model: PiModel): boolean {
+  return isNonEmptyString(model.baseUrl) && !isOfficialOpenAIBaseUrl(model);
+}
+
 function describeMissingOpenAIFamilyProxyCompat(model: PiModel): string[] {
   const compat = getCompat(model);
   const missing: string[] = [];
 
   if (!isOpenAIFamilyModel(model)) return missing;
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
-  if (isOfficialOpenAIBaseUrl(model)) return missing;
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) return missing;
 
   if (compat.sendSessionAffinityHeaders !== true) {
     missing.push("sendSessionAffinityHeaders");
@@ -2415,7 +2789,7 @@ function describeMissingOpenAICompatibleProxyCompat(model: PiModel): string[] {
   const missing: string[] = [];
 
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
-  if (isOfficialOpenAIBaseUrl(model)) return missing;
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) return missing;
   if (isPiBuiltInLlamaCppModel(model)) return missing;
 
   if (compat.sendSessionAffinityHeaders === undefined) {
@@ -2443,7 +2817,7 @@ function describeOptionalOpenAICompatibleProxyCompat(model: PiModel): string[] {
   const optional: string[] = [];
 
   if (!isOpenAICompatibleProxyApi(model.api)) return optional;
-  if (isOfficialOpenAIBaseUrl(model)) return optional;
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) return optional;
   if (isPiBuiltInLlamaCppModel(model)) return optional;
 
   if (compat.supportsLongCacheRetention !== true) {
@@ -2628,7 +3002,10 @@ function describeMissingDeepSeekCompat(model: PiModel): string[] {
 }
 
 function isDeepSeekCompatCheckApplicable(model: PiModel): boolean {
-  return isDeepSeekLikeModel(model) && isOpenAICompatibleApi(model.api) && !isPiBuiltInLlamaCppModel(model);
+  return isDeepSeekLikeModel(model)
+    && isOpenAICompatibleApi(model.api)
+    && isKnownThirdPartyOpenAIEndpoint(model)
+    && !isPiBuiltInLlamaCppModel(model);
 }
 
 function describeMissingCacheCompatForModel(model: PiModel): string[] {
@@ -3840,6 +4217,87 @@ function formatRecentTrendSummary(samples: CacheUsageSample[], maxCount: number)
 /**
  * Build the output for `/cache-optimizer stats`.
  */
+function formatCompactStats(stats: CacheStats): string {
+  const percent = stats.totalInputTokens > 0
+    ? (stats.cachedInputTokens / stats.totalInputTokens) * 100
+    : 0;
+  return `${stats.hitRequests}/${stats.totalRequests}·${formatTokenCount(stats.cachedInputTokens)}/${formatTokenCount(stats.totalInputTokens)} ${percent.toFixed(1)}%`;
+}
+
+function modelFromStatsKey(key: string, ref?: PersistedRoutedModelRef): PiModel | undefined {
+  const slash = key.indexOf("/");
+  if (slash <= 0 || slash >= key.length - 1) return undefined;
+  return routedModelRefToPiModel(ref ?? { provider: key.slice(0, slash), id: key.slice(slash + 1) });
+}
+
+function sortStatsEntries(entries: Array<[string, CacheStats]>, activeModelKey?: string): Array<[string, CacheStats]> {
+  return entries.sort(([left], [right]) => {
+    if (left === activeModelKey) return -1;
+    if (right === activeModelKey) return 1;
+    return left.localeCompare(right);
+  });
+}
+
+function buildSessionStatsOutput(
+  sessionModels: Record<string, CacheStats>,
+  activeModel?: PiModel,
+  modelRefsByKey: Record<string, PersistedRoutedModelRef> = {},
+): string {
+  const activeKey = activeModel ? modelKey(activeModel) : undefined;
+  const models = { ...sessionModels };
+  if (activeModel && selectAdapterForModel(activeModel) && !models[activeKey!]) {
+    models[activeKey!] = emptyCacheStats();
+  }
+  const entries = sortStatsEntries(Object.entries(models), activeKey);
+  if (entries.length === 0) return "ℹ️ No cache statistics recorded for the current session today.";
+  const lines = ["Scope: current session", `Day:   ${currentLocalDay()}`, `Models: ${entries.length}`];
+  for (const [key, stats] of entries) {
+    const model = modelFromStatsKey(key, modelRefsByKey[key]);
+    const adapter = model ? selectAdapterForModel(model) : undefined;
+    lines.push("", `── ${key} ──`, `Adapter: ${adapter?.label ?? "Unknown cache adapter"}`);
+    lines.push(`Requests:      ${stats.hitRequests} hit / ${stats.totalRequests} total`);
+    lines.push(`Cached tokens: ${formatTokenCount(stats.cachedInputTokens)} / ${formatTokenCount(stats.totalInputTokens)} input · ${stats.totalInputTokens > 0 ? `${((stats.cachedInputTokens / stats.totalInputTokens) * 100).toFixed(1)}%` : "0.0%"}`);
+    lines.push(`Summary:       ${formatCompactStats(stats)}`);
+    if (stats.cacheWriteInputTokens > 0) lines.push(`Cache write:   ${formatTokenCount(stats.cacheWriteInputTokens)}`);
+  }
+  return lines.join("\n");
+}
+
+function buildAllStatsOutput(aggregate: ShardAggregate): string {
+  const entries = sortStatsEntries(Object.entries(aggregate.totalsByModel));
+  if (entries.length === 0) return "ℹ️ No local cache statistics recorded today.";
+  const sessionCount = Object.keys(aggregate.instancesBySession).length;
+  const instanceCount = Object.values(aggregate.instancesBySession).reduce((sum, value) => sum + value, 0);
+  const lines = ["Scope: all local sessions", `Day:   ${currentLocalDay()}`, `Sessions: ${sessionCount}`, `Instances: ${instanceCount}`];
+  for (const [key, stats] of entries) {
+    const model = modelFromStatsKey(key, aggregate.modelRefsByKey[key]);
+    const adapter = model ? selectAdapterForModel(model) : undefined;
+    lines.push("", `── ${key} ──`, `Adapter: ${adapter?.label ?? "Unknown cache adapter"}`);
+    lines.push(`Sessions: ${aggregate.sessionsByModel[key] ?? 0} · Instances: ${aggregate.instancesByModel[key] ?? 0}`);
+    lines.push(`Requests:      ${stats.hitRequests} hit / ${stats.totalRequests} total`);
+    lines.push(`Cached tokens: ${formatTokenCount(stats.cachedInputTokens)} / ${formatTokenCount(stats.totalInputTokens)} input · ${stats.totalInputTokens > 0 ? `${((stats.cachedInputTokens / stats.totalInputTokens) * 100).toFixed(1)}%` : "0.0%"}`);
+    lines.push(`Summary:       ${formatCompactStats(stats)}`);
+    if (stats.cacheWriteInputTokens > 0) lines.push(`Cache write:   ${formatTokenCount(stats.cacheWriteInputTokens)}`);
+  }
+  return lines.join("\n");
+}
+
+function buildContributorsStatsOutput(aggregate: ShardAggregate, activeModel: PiModel | undefined, currentSessionHash?: string): string {
+  if (!activeModel) return "ℹ️ No active model selected.";
+  const key = modelKey(activeModel);
+  const rows = Object.entries(aggregate.bySession)
+    .filter(([, models]) => models[key])
+    .sort(([left], [right]) => left === currentSessionHash ? -1 : right === currentSessionHash ? 1 : left.localeCompare(right));
+  if (rows.length === 0) return `ℹ️ No contributors recorded for ${key} today.`;
+  const lines = [`Model: ${key}`, "Scope: contributing local sessions today"];
+  let otherIndex = 0;
+  for (const [sessionHash, models] of rows) {
+    const label = sessionHash === currentSessionHash ? "Current session" : `Other session ${++otherIndex}`;
+    lines.push("", label, `  Instances: ${aggregate.instancesBySessionModel[sessionHash]?.[key] ?? 0}`, `  ${formatCompactStats(models[key])}`);
+  }
+  return lines.join("\n");
+}
+
 function buildStatsOutput(model: PiModel | undefined, adapter: CacheProviderAdapter | undefined, stats: CacheStats | undefined, recentSamples: CacheUsageSample[]): string {
   const lines: string[] = [];
 
@@ -4248,8 +4706,8 @@ function filterRestorableStatsForSession(
  *     `restoreCacheStats` can migrate them on the next load before the session
  *     id is known.
  *
- * Pure function (no I/O) — suitable for unit tests without touching the real
- * state file at `~/.pi/agent/pi-cache-optimizer-stats.json`.
+ * Historical v1-v6 pure helper (no runtime I/O). Permanent migration tests
+ * exercise it directly; v7 startup never reads or writes the obsolete file.
  */
 function mergeCacheSessions(
   existingSessions: Record<string, Record<string, CacheStats>>,
@@ -4409,15 +4867,312 @@ async function writePersistedCacheStats(
   await rename(tempPath, STATE_FILE_PATH);
 }
 
+function modelEpochPath(modelKeyValue: string): string {
+  return join(SHARD_MODEL_EPOCH_DIR, `${createHash("sha256").update(modelKeyValue).digest("hex")}.json`);
+}
+
+function initialEpoch(scope: string): string {
+  return `initial:${scope}`;
+}
+
+function parseEpochRecord(value: unknown): string | undefined {
+  const record = asRecord(value);
+  return record?.version === 1 && isNonEmptyString(record.epoch) ? record.epoch.trim() : undefined;
+}
+
+async function readEpochFile(path: string, fallback: string): Promise<string> {
+  try {
+    return parseEpochRecord(JSON.parse(await readFile(path, "utf8"))) ?? fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+async function readGlobalStatsEpoch(): Promise<string> {
+  return readEpochFile(SHARD_GLOBAL_EPOCH_PATH, initialEpoch("global"));
+}
+
+async function readModelStatsEpoch(modelKeyValue: string): Promise<string> {
+  return readEpochFile(modelEpochPath(modelKeyValue), initialEpoch(`model:${modelKeyValue}`));
+}
+
+async function writeStatsEpoch(path: string, epoch: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, JSON.stringify({ version: 1, epoch, createdAt: Date.now() }, null, 2) + "\n", "utf8");
+  await rename(tempPath, path);
+}
+
+async function advanceGlobalStatsEpoch(): Promise<string> {
+  const epoch = `${Date.now()}-${randomUUID()}`;
+  await writeStatsEpoch(SHARD_GLOBAL_EPOCH_PATH, epoch);
+  return epoch;
+}
+
+async function advanceModelStatsEpoch(modelKeyValue: string): Promise<string> {
+  const epoch = `${Date.now()}-${randomUUID()}`;
+  await writeStatsEpoch(modelEpochPath(modelKeyValue), epoch);
+  return epoch;
+}
+
+function parsePersistedStatsShardV7(value: unknown): PersistedStatsShardV7 | undefined {
+  const record = asRecord(value);
+  const processRecord = asRecord(record?.process);
+  const lifecycle = asRecord(record?.lifecycle);
+  const rawModels = asRecord(record?.models);
+  if (
+    record?.version !== 7 ||
+    record.kind !== "pi-cache-optimizer-shard" ||
+    !isNonEmptyString(record.instanceId) ||
+    !isNonEmptyString(record.sessionHash) ||
+    !processRecord ||
+    !Number.isInteger(processRecord.pid) ||
+    !Number.isInteger(processRecord.ppid) ||
+    typeof processRecord.instanceStartedAt !== "number" ||
+    !lifecycle ||
+    (lifecycle.state !== "active" && lifecycle.state !== "closed") ||
+    typeof lifecycle.createdAt !== "number" ||
+    typeof lifecycle.updatedAt !== "number" ||
+    !isNonEmptyString(record.day) ||
+    !/^\d{4}-\d{2}-\d{2}$/.test(record.day) ||
+    !isNonEmptyString(record.globalEpoch) ||
+    !rawModels
+  ) return undefined;
+
+  const models: PersistedStatsShardV7["models"] = {};
+  for (const [key, rawEntry] of Object.entries(rawModels)) {
+    const entry = asRecord(rawEntry);
+    const stats = parseCacheStats(entry?.stats);
+    if (
+      !entry || !stats || !isNonEmptyString(entry.modelEpoch) ||
+      !isNonEmptyString(entry.provider) || !isNonEmptyString(entry.modelId) ||
+      key !== `${entry.provider.trim()}/${entry.modelId.trim()}`
+    ) continue;
+    models[key] = {
+      modelEpoch: entry.modelEpoch.trim(),
+      provider: entry.provider.trim(),
+      modelId: entry.modelId.trim(),
+      ...(isNonEmptyString(entry.modelName) ? { modelName: entry.modelName.trim() } : {}),
+      ...(isNonEmptyString(entry.api) ? { api: entry.api.trim() } : {}),
+      stats,
+    };
+  }
 
+  const lastRoutedModel = parsePersistedRoutedModelRef(record.lastRoutedModel);
+  return {
+    version: 7,
+    kind: "pi-cache-optimizer-shard",
+    instanceId: record.instanceId.trim(),
+    sessionHash: record.sessionHash.trim(),
+    process: {
+      pid: Number(processRecord.pid),
+      ppid: Number(processRecord.ppid),
+      instanceStartedAt: processRecord.instanceStartedAt,
+    },
+    lifecycle: {
+      state: lifecycle.state,
+      createdAt: lifecycle.createdAt,
+      updatedAt: lifecycle.updatedAt,
+      ...(typeof lifecycle.closedAt === "number" ? { closedAt: lifecycle.closedAt } : {}),
+    },
+    day: record.day,
+    globalEpoch: record.globalEpoch.trim(),
+    models,
+    ...(lastRoutedModel ? { lastRoutedModel } : {}),
+  };
+}
+
+async function writeStatsShardV7(path: string, shard: PersistedStatsShardV7): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(shard, null, 2) + "\n", "utf8");
+  await rename(tempPath, path);
+}
+
+async function readValidStatsShardsV7(directory: string = SHARD_FILES_DIR): Promise<PersistedStatsShardV7[]> {
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return [];
+    throw error;
+  }
+  const shards: PersistedStatsShardV7[] = [];
+  for (const name of names) {
+    if (!/^[0-9a-f-]+\.json$/i.test(name)) continue;
+    const path = join(directory, name);
+    try {
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink()) continue;
+      const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+      const filenameInstanceId = name.slice(0, -".json".length);
+      if (parsed && parsed.instanceId === filenameInstanceId) shards.push(parsed);
+    } catch {
+      // Ignore malformed or transiently unavailable shards. Atomic writers will
+      // publish a complete replacement on the next successful update.
+    }
+  }
+  return shards;
+}
+
+async function aggregateStatsShardsV7(
+  shards: PersistedStatsShardV7[],
+  day: string = currentLocalDay(),
+): Promise<ShardAggregate> {
+  const globalEpoch = await readGlobalStatsEpoch();
+  const modelEpochs = new Map<string, string>();
+  const result: ShardAggregate = {
+    bySession: {},
+    totalsByModel: {},
+    instancesBySession: {},
+    instancesBySessionModel: {},
+    sessionsByModel: {},
+    instancesByModel: {},
+    modelRefsByKey: {},
+    lastRoutedModelBySession: {},
+  };
+  const routedUpdatedAt = new Map<string, number>();
+  const modelRefUpdatedAt = new Map<string, number>();
+  const modelSessions = new Map<string, Set<string>>();
+
+  for (const shard of shards) {
+    if (shard.day !== day || shard.globalEpoch !== globalEpoch) continue;
+    let contributed = false;
+    if (shard.lastRoutedModel && (routedUpdatedAt.get(shard.sessionHash) ?? -1) < shard.lifecycle.updatedAt) {
+      routedUpdatedAt.set(shard.sessionHash, shard.lifecycle.updatedAt);
+      result.lastRoutedModelBySession[shard.sessionHash] = shard.lastRoutedModel;
+    }
+    for (const [key, entry] of Object.entries(shard.models)) {
+      let epoch = modelEpochs.get(key);
+      if (!epoch) {
+        epoch = await readModelStatsEpoch(key);
+        modelEpochs.set(key, epoch);
+      }
+      if (entry.modelEpoch !== epoch || entry.stats.day !== day) continue;
+      contributed = true;
+      const sessionModels = result.bySession[shard.sessionHash] ??= {};
+      sessionModels[key] = mergeCacheStatsForTotal(sessionModels[key], entry.stats);
+      result.totalsByModel[key] = mergeCacheStatsForTotal(result.totalsByModel[key], entry.stats);
+      result.instancesByModel[key] = (result.instancesByModel[key] ?? 0) + 1;
+      if ((modelRefUpdatedAt.get(key) ?? -1) < shard.lifecycle.updatedAt) {
+        modelRefUpdatedAt.set(key, shard.lifecycle.updatedAt);
+        result.modelRefsByKey[key] = {
+          provider: entry.provider,
+          id: entry.modelId,
+          name: entry.modelName ?? entry.modelId,
+        };
+      }
+      const sessionInstances = result.instancesBySessionModel[shard.sessionHash] ??= {};
+      sessionInstances[key] = (sessionInstances[key] ?? 0) + 1;
+      const sessions = modelSessions.get(key) ?? new Set<string>();
+      sessions.add(shard.sessionHash);
+      modelSessions.set(key, sessions);
+    }
+    if (contributed) {
+      result.instancesBySession[shard.sessionHash] = (result.instancesBySession[shard.sessionHash] ?? 0) + 1;
+    }
+  }
+  for (const [key, sessions] of modelSessions) result.sessionsByModel[key] = sessions.size;
+  return result;
+}
+
+async function loadStatsShardAggregateV7(directory: string = SHARD_FILES_DIR): Promise<ShardAggregate> {
+  return aggregateStatsShardsV7(await readValidStatsShardsV7(directory));
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return getErrorCode(error) === "EPERM";
+  }
+}
+
+async function removeLegacyStatsFiles(): Promise<void> {
+  for (const path of [STATE_FILE_PATH, LEGACY_STATE_FILE_PATH]) {
+    try {
+      await unlink(path);
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove obsolete stats file ${path}`, error);
+    }
+  }
+}
+
+async function cleanupStatsShardsV7(now = Date.now(), directory: string = SHARD_FILES_DIR): Promise<number> {
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    return getErrorCode(error) === "ENOENT" ? 0 : Promise.reject(error);
+  }
+  const today = currentLocalDay();
+  let removed = 0;
+  for (const name of names) {
+    const isShard = /^[0-9a-f-]+\.json$/i.test(name);
+    const isTemp = name.endsWith(".tmp");
+    if (!isShard && !isTemp) continue;
+    const path = join(directory, name);
+    try {
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink()) continue;
+      if (isTemp) {
+        if (now - info.mtimeMs < SHARD_TEMP_RETENTION_MS) continue;
+      } else {
+        const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+        if (parsed?.day === today) continue;
+        const updatedAt = parsed?.lifecycle.updatedAt ?? info.mtimeMs;
+        if (now - updatedAt < SHARD_RETENTION_MS) continue;
+        if (parsed?.lifecycle.state === "active" && isProcessAlive(parsed.process.pid)) continue;
+      }
+      await unlink(path);
+      removed += 1;
+    } catch {
+      // Best-effort maintenance must never block the extension.
+    }
+  }
+  return removed;
+}
+
+async function maybeCleanupStatsShardsV7(now = Date.now()): Promise<void> {
+  await mkdir(SHARD_MAINTENANCE_DIR, { recursive: true });
+  try {
+    const marker = await stat(SHARD_CLEANUP_MARKER_PATH);
+    if (now - marker.mtimeMs < SHARD_CLEANUP_INTERVAL_MS) return;
+  } catch {}
+
+  try {
+    await mkdir(SHARD_CLEANUP_LOCK_PATH);
+  } catch (error) {
+    if (getErrorCode(error) !== "EEXIST") return;
+    try {
+      const lock = await stat(SHARD_CLEANUP_LOCK_PATH);
+      if (now - lock.mtimeMs <= SHARD_CLEANUP_LOCK_STALE_MS) return;
+      await rm(SHARD_CLEANUP_LOCK_PATH, { recursive: true, force: true });
+      await mkdir(SHARD_CLEANUP_LOCK_PATH);
+    } catch {
+      return;
+    }
+  }
+
+  try {
+    await cleanupStatsShardsV7(now);
+    const tempPath = `${SHARD_CLEANUP_MARKER_PATH}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tempPath, `${now}\n`, "utf8");
+    await rename(tempPath, SHARD_CLEANUP_MARKER_PATH);
+  } finally {
+    await rm(SHARD_CLEANUP_LOCK_PATH, { recursive: true, force: true });
+  }
+}
 
 function isCompatCheckApplicable(model: PiModel): boolean {
-  return isOpenAICompatibleProxyApi(model.api) && !isOfficialOpenAIBaseUrl(model) && !isPiBuiltInLlamaCppModel(model);
+  return isOpenAICompatibleProxyApi(model.api) && isKnownThirdPartyOpenAIEndpoint(model) && !isPiBuiltInLlamaCppModel(model);
 }
 
 function isPromptCacheRetention400Applicable(model: PiModel): boolean {
   return isOpenAICompatibleApi(model.api) &&
-    !isOfficialOpenAIBaseUrl(model) &&
+    isKnownThirdPartyOpenAIEndpoint(model) &&
     !isPiBuiltInLlamaCppModel(model) &&
     getCompat(model).supportsLongCacheRetention === true;
 }
@@ -4445,6 +5200,7 @@ function isExplicitPromptCacheRetentionUnsupportedApplicable(model: PiModel): bo
  */
 function isSessionAffinity403Applicable(model: PiModel): boolean {
   if (!isOpenAICompatibleProxyApi(model.api)) return false;
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) return false;
   if (isPiBuiltInLlamaCppModel(model)) return false;
   return getCompat(model).sendSessionAffinityHeaders === true;
 }
@@ -4461,7 +5217,7 @@ function isSessionAffinity403Applicable(model: PiModel): boolean {
  */
 function isOpenAISdkHeader403Applicable(model: PiModel): boolean {
   if (!isOpenAICompatibleProxyApi(model.api)) return false;
-  if (isOfficialOpenAIBaseUrl(model)) return false;
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) return false;
   if (isPiBuiltInLlamaCppModel(model)) return false;
   return getCompat(model).sendSessionAffinityHeaders !== true;
 }
@@ -4499,8 +5255,9 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
     return notes;
   }
 
-  // Official OpenAI bypass — no notes needed.
-  if (isOfficialOpenAIBaseUrl(model)) {
+  // Unknown/default endpoints and official OpenAI are not diagnosable as
+  // third-party router channels. Request-header bridging also fails closed.
+  if (!isKnownThirdPartyOpenAIEndpoint(model)) {
     return notes;
   }
 
@@ -4667,6 +5424,13 @@ function getCompatCheckNotApplicableLines(model: PiModel): string[] {
     ];
   }
 
+  if (isOpenAICompatibleApi(api) && !isNonEmptyString(model.baseUrl)) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Upstream endpoint metadata is unavailable; session-affinity header injection is disabled.",
+    ];
+  }
+
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
@@ -6718,6 +7482,7 @@ export const __internals_for_tests = {
   buildSafeOpenAIProxyCompatSuggestion,
   getPromptCacheRetentionUnsupportedHint,
   isOfficialOpenAIBaseUrl,
+  isKnownThirdPartyOpenAIEndpoint,
   isCompatCheckApplicable,
   isPromptCacheRetention400Applicable,
   isSessionAffinity403Applicable,
@@ -6838,6 +7603,11 @@ export const __internals_for_tests = {
   buildOpenAIProxyCompatWarningText,
   getModelIdNameTokenValues,
   getAssistantMessageModelTokenValues,
+  mergeCacheCompat,
+  resolveEffectiveCompatFromConfig,
+  getEffectiveCompatValueSource,
+  isValidModelsConfigForEffectiveCompat,
+  addEffectiveSessionAffinityHeaders,
   getCompat,
   modelKey,
   modelFromAssistantMessage,
@@ -6876,6 +7646,10 @@ export const __internals_for_tests = {
   // Recent sample / stats output / diagnosis helpers
   MAX_RECENT_SAMPLES,
   buildStatsOutput,
+  buildSessionStatsOutput,
+  buildAllStatsOutput,
+  buildContributorsStatsOutput,
+  formatCompactStats,
   buildLowHitDiagnosis,
   formatRecentTrendSummary,
   formatHitRatio,
@@ -6908,6 +7682,8 @@ export const __internals_for_tests = {
   parseRouteSnapshot,
   resolveActiveRouteSnapshot,
   routeSnapshotToPiModel,
+  isRoutedFallbackModel,
+  applyConfiguredTransportToModel,
   resolveRouteModel,
   isVirtualRoutingModel,
   installCacheHintsService,
@@ -6923,8 +7699,23 @@ export const __internals_for_tests = {
   createSerializedAsyncRunner,
   writePersistedCacheStats,
   readPersistedCacheStats,
+  parsePersistedStatsShardV7,
+  writeStatsShardV7,
+  readValidStatsShardsV7,
+  aggregateStatsShardsV7,
+  loadStatsShardAggregateV7,
+  cleanupStatsShardsV7,
+  removeLegacyStatsFiles,
+  readGlobalStatsEpoch,
+  readModelStatsEpoch,
+  advanceGlobalStatsEpoch,
+  advanceModelStatsEpoch,
+  modelEpochPath,
   STATE_FILE_PATH,
   LEGACY_STATE_FILE_PATH,
+  SHARD_STATE_DIR,
+  SHARD_FILES_DIR,
+  SHARD_GLOBAL_EPOCH_PATH,
   STATE_DIR,
   // JSONC surgical edit helpers
   MODELS_JSON_PATH,
@@ -6981,17 +7772,25 @@ export default function (pi: ExtensionAPI) {
   let lastStatusText: string | undefined;
   let persistenceWarningShown = false;
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
+  let shardRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  let shardWatcher: ReturnType<typeof watch> | undefined;
   const enqueuePersist = createSerializedAsyncRunner();
-  let replacePersistedTotalsOnNextWrite = false;
-  let forceReplaceTotalsAfterFailure = false;
-  const pendingDeletedTotalModelKeys = new Set<string>();
+  const instanceId = randomUUID();
+  const instanceStartedAt = Date.now();
+  const instanceShardPath = join(SHARD_FILES_DIR, `${instanceId}.json`);
+  const modelApiByKey = new Map<string, string>();
+  const modelNameByKey = new Map<string, string>();
+  const modelEpochByKey = new Map<string, string>();
+  let currentGlobalEpoch = initialEpoch("global");
   let integrityNotificationShown = false;
   let currentSessionId = "";
   let currentSessionHash = "";
   let currentSessionHashSet = false;
   let lastActualRoutedModel: PersistedRoutedModelRef | undefined;
   let latestCacheHint: PiCacheHintSnapshot | undefined;
+  let shardCreatedAt = Date.now();
   const PERSIST_DEBOUNCE_MS = 2000;
+  const SHARD_REFRESH_DEBOUNCE_MS = 250;
 
   function buildObservedRuntimeFixSuggestion(model: PiModel): FixSuggestion | undefined {
     const key = modelKey(model);
@@ -7106,17 +7905,102 @@ export default function (pi: ExtensionAPI) {
     recentSamplesByModelKey.clear();
   }
 
-  function getCacheStatsState(): CacheStatsState {
+  async function refreshShardAggregate(): Promise<ShardAggregate> {
+    const persistedShards = await readValidStatsShardsV7();
+    const shards = persistedShards.filter((shard) => shard.instanceId !== instanceId);
+    if (currentSessionHashSet) shards.push(buildCurrentStatsShard());
+    const aggregate = await aggregateStatsShardsV7(shards);
+
+    // A reset from another process can advance epochs while this instance is
+    // idle. Adopt those epochs during every aggregate refresh, not only when a
+    // later message_end arrives, so this instance cannot keep an old in-memory
+    // process bucket visible in `process` mode or rewrite stale counters during
+    // shutdown. Model-scoped resets clear only the affected local bucket.
+    const latestGlobalEpoch = await readGlobalStatsEpoch();
+    if (currentGlobalEpoch !== latestGlobalEpoch) {
+      currentGlobalEpoch = latestGlobalEpoch;
+      cacheStatsProcessByModel = {};
+      modelEpochByKey.clear();
+      modelApiByKey.clear();
+      modelNameByKey.clear();
+      lastActualRoutedModel = undefined;
+    } else {
+      for (const key of Object.keys(cacheStatsProcessByModel)) {
+        const latestModelEpoch = await readModelStatsEpoch(key);
+        if ((modelEpochByKey.get(key) ?? initialEpoch(`model:${key}`)) === latestModelEpoch) continue;
+        delete cacheStatsProcessByModel[key];
+        modelEpochByKey.set(key, latestModelEpoch);
+        modelApiByKey.delete(key);
+        modelNameByKey.delete(key);
+      }
+    }
+
+    cacheStatsByModel = {};
+    for (const [sessionHash, models] of Object.entries(aggregate.bySession)) {
+      for (const [key, stats] of Object.entries(models)) {
+        cacheStatsByModel[`${sessionHash}:${key}`] = stats;
+      }
+    }
+    cacheStatsTotalsByModel = aggregate.totalsByModel;
+    if (currentSessionHashSet) {
+      lastActualRoutedModel = aggregate.lastRoutedModelBySession[currentSessionHash];
+    }
+    lastStatusText = undefined;
+    return aggregate;
+  }
+
+  async function ensureCurrentEpochs(): Promise<void> {
+    currentGlobalEpoch = await readGlobalStatsEpoch();
+    for (const key of Object.keys(cacheStatsProcessByModel)) {
+      modelEpochByKey.set(key, await readModelStatsEpoch(key));
+    }
+  }
+
+  function buildCurrentStatsShard(state: "active" | "closed" = "active"): PersistedStatsShardV7 {
+    const now = Date.now();
+    const models: PersistedStatsShardV7["models"] = {};
+    for (const [key, stats] of Object.entries(cacheStatsProcessByModel)) {
+      const slash = key.indexOf("/");
+      if (slash <= 0 || slash >= key.length - 1) continue;
+      models[key] = {
+        modelEpoch: modelEpochByKey.get(key) ?? initialEpoch(`model:${key}`),
+        provider: key.slice(0, slash),
+        modelId: key.slice(slash + 1),
+        ...(modelNameByKey.get(key) ? { modelName: modelNameByKey.get(key) } : {}),
+        ...(modelApiByKey.get(key) ? { api: modelApiByKey.get(key) } : {}),
+        stats: cloneCacheStats(stats),
+      };
+    }
     return {
-      statsByModel: cacheStatsByModel,
-      totalsByModel: cacheStatsTotalsByModel,
-      legacyFamily: cacheStatsLegacyFamily,
-      ...(currentSessionHashSet && lastActualRoutedModel
-        ? { lastRoutedModelBySession: { [currentSessionHash]: lastActualRoutedModel } }
-        : {}),
+      version: 7,
+      kind: "pi-cache-optimizer-shard",
+      instanceId,
+      sessionHash: currentSessionHash || "_nosession",
+      process: { pid: process.pid, ppid: process.ppid, instanceStartedAt },
+      lifecycle: {
+        state,
+        createdAt: shardCreatedAt,
+        updatedAt: now,
+        ...(state === "closed" ? { closedAt: now } : {}),
+      },
+      day: currentLocalDay(),
+      globalEpoch: currentGlobalEpoch,
+      models,
+      ...(lastActualRoutedModel ? { lastRoutedModel: { ...lastActualRoutedModel } } : {}),
     };
   }
 
+  function scheduleShardRefresh(ctx?: ExtensionContext, model?: PiModel): void {
+    if (shardRefreshTimer !== null) clearTimeout(shardRefreshTimer);
+    shardRefreshTimer = setTimeout(() => {
+      shardRefreshTimer = null;
+      void refreshShardAggregate()
+        .then(() => publishStatus(ctx as ExtensionContext, model ?? ctx?.model))
+        .catch(() => undefined);
+    }, SHARD_REFRESH_DEBOUNCE_MS);
+    shardRefreshTimer.unref?.();
+  }
+
   /** Look up visible cumulative stats for a model, falling back to legacy family. */
   function getStatsForModel(model: PiModel | undefined, adapter: CacheProviderAdapter): CacheStats {
     if (model) {
@@ -7166,79 +8050,41 @@ export default function (pi: ExtensionAPI) {
     return created;
   }
 
-  function resetStatsForModel(model: PiModel): void {
+  async function resetStatsForModel(model: PiModel): Promise<void> {
     const displayKey = modelKey(model);
+    const nextEpoch = await advanceModelStatsEpoch(displayKey);
+    modelEpochByKey.set(displayKey, nextEpoch);
+    delete cacheStatsProcessByModel[displayKey];
+    delete cacheStatsTotalsByModel[displayKey];
     for (const key of Object.keys(cacheStatsByModel)) {
       if (modelKeyFromSessionScoped(key) === displayKey) delete cacheStatsByModel[key];
     }
-    delete cacheStatsTotalsByModel[displayKey];
-    delete cacheStatsProcessByModel[displayKey];
-    pendingDeletedTotalModelKeys.add(displayKey);
     for (const key of Array.from(recentSamplesByModelKey.keys())) {
       if (modelKeyFromSessionScoped(key) === displayKey) recentSamplesByModelKey.delete(key);
     }
     lastStatusText = undefined;
   }
 
-  function resetCurrentSessionStats(): void {
-    const prefix = `${currentSessionHash || "_nosession"}:`;
-    for (const key of Object.keys(cacheStatsByModel)) {
-      if (key.startsWith(prefix)) delete cacheStatsByModel[key];
-    }
-    cacheStatsProcessByModel = {};
+  async function resetCurrentSessionStats(): Promise<void> {
+    currentGlobalEpoch = await advanceGlobalStatsEpoch();
+    cacheStatsByModel = {};
     cacheStatsTotalsByModel = {};
-    replacePersistedTotalsOnNextWrite = true;
-    for (const key of Array.from(recentSamplesByModelKey.keys())) {
-      if (key.startsWith(prefix)) recentSamplesByModelKey.delete(key);
-    }
+    cacheStatsProcessByModel = {};
+    modelEpochByKey.clear();
+    modelApiByKey.clear();
+    modelNameByKey.clear();
+    clearRecentSamples();
     lastActualRoutedModel = undefined;
     lastStatusText = undefined;
   }
 
-  function snapshotCacheStatsState(): CacheStatsState {
-    const state = getCacheStatsState();
-    const statsByModel = Object.fromEntries(
-      Object.entries(state.statsByModel).map(([key, stats]) => [key, { ...stats }]),
-    );
-    const totalsByModel = Object.fromEntries(
-      Object.entries(state.totalsByModel).map(([key, stats]) => [key, { ...stats }]),
-    );
-    const legacyFamily: Partial<Record<CacheProviderId, CacheStats>> = {};
-    for (const id of CACHE_PROVIDER_IDS) {
-      const stats = state.legacyFamily[id];
-      if (stats) legacyFamily[id] = { ...stats };
-    }
-    const lastRoutedModelBySession = state.lastRoutedModelBySession
-      ? Object.fromEntries(
-        Object.entries(state.lastRoutedModelBySession).map(([key, model]) => [key, { ...model }]),
-      )
-      : undefined;
-    return { statsByModel, totalsByModel, legacyFamily, lastRoutedModelBySession };
-  }
-
-  function persistCacheStats(ctx?: ExtensionContext): Promise<void> {
-    const state = snapshotCacheStatsState();
-    const sessionHash = currentSessionHashSet ? currentSessionHash : undefined;
-    const deleteModelKeys = Array.from(pendingDeletedTotalModelKeys);
-    const replaceTotals = replacePersistedTotalsOnNextWrite;
-    // This queued write owns the current intents. Later mutations can enqueue
-    // independent intents without an earlier completion clearing them.
-    pendingDeletedTotalModelKeys.clear();
-    replacePersistedTotalsOnNextWrite = false;
-
+  function persistCacheStats(ctx?: ExtensionContext, lifecycleState: "active" | "closed" = "active"): Promise<void> {
+    const shard = buildCurrentStatsShard(lifecycleState);
     return enqueuePersist(async () => {
-      const recoverFromEarlierFailure = forceReplaceTotalsAfterFailure;
       try {
-        await writePersistedCacheStats(state, sessionHash, {
-          deleteModelKeys,
-          replaceTotals: replaceTotals || recoverFromEarlierFailure,
-        });
-        if (recoverFromEarlierFailure) forceReplaceTotalsAfterFailure = false;
+        await writeStatsShardV7(instanceShardPath, shard);
       } catch (error) {
-        // The next queued write must replace totals authoritatively so a failed
-        // reset/delete cannot merge stale persisted counters back into state.
-        forceReplaceTotalsAfterFailure = true;
-        console.warn(`${LOG_PREFIX}: failed to persist cache stats`, error);
+        console.warn(`${LOG_PREFIX}: failed to persist cache stats shard`, error);
         if (!persistenceWarningShown) {
           persistenceWarningShown = true;
           ctx?.ui.notify(
@@ -7250,61 +8096,37 @@ export default function (pi: ExtensionAPI) {
     });
   }
 
-  /** Schedule a debounced persist. Coalesces rapid message_end writes
-   *  into a single disk write after PERSIST_DEBOUNCE_MS of silence.
-   *  In-memory stats remain instantly up-to-date for the footer; only
-   *  the on-disk persistence is delayed. */
   function schedulePersistCacheStats(ctx?: ExtensionContext): void {
     if (persistTimer !== null) clearTimeout(persistTimer);
     persistTimer = setTimeout(() => {
       persistTimer = null;
-      persistCacheStats(ctx).catch((err) => {
-        console.warn(`${LOG_PREFIX}: debounced persist failed`, err);
-      });
+      void persistCacheStats(ctx).then(() => refreshShardAggregate()).catch(() => undefined);
     }, PERSIST_DEBOUNCE_MS);
+    persistTimer.unref?.();
   }
 
-  /** Flush any pending debounced persist immediately (cancels timer + writes).
-   *  Used on reload and day-rollover where immediate durability matters. */
-  async function flushPersistCacheStats(ctx?: ExtensionContext): Promise<void> {
+  async function flushPersistCacheStats(ctx?: ExtensionContext, lifecycleState: "active" | "closed" = "active"): Promise<void> {
     if (persistTimer !== null) {
       clearTimeout(persistTimer);
       persistTimer = null;
     }
-    await persistCacheStats(ctx);
+    // Adopt resets performed by another Pi process before capturing the shard
+    // snapshot. Otherwise shutdown/command flush could rewrite stale local
+    // counters under an old epoch even though aggregation already hid them.
+    await refreshShardAggregate();
+    await persistCacheStats(ctx, lifecycleState);
+    await refreshShardAggregate();
   }
 
   async function rollOverStatsIfNeeded(ctx?: ExtensionContext): Promise<void> {
     const day = currentLocalDay();
     let changed = false;
-
-    // Roll over per-model entries.
-    for (const key of Object.keys(cacheStatsByModel)) {
-      const stats = cacheStatsByModel[key];
-      if (stats && stats.day !== day) {
-        cacheStatsByModel[key] = emptyCacheStats(day);
-        changed = true;
-      }
-    }
-
-    // Roll over cumulative provider/model totals.
     for (const key of Object.keys(cacheStatsProcessByModel)) {
-      const stats = cacheStatsProcessByModel[key];
-      if (stats && stats.day !== day) {
+      if (cacheStatsProcessByModel[key]?.day !== day) {
         cacheStatsProcessByModel[key] = emptyCacheStats(day);
         changed = true;
       }
     }
-
-    for (const key of Object.keys(cacheStatsTotalsByModel)) {
-      const stats = cacheStatsTotalsByModel[key];
-      if (stats && stats.day !== day) {
-        cacheStatsTotalsByModel[key] = emptyCacheStats(day);
-        changed = true;
-      }
-    }
-
-    // Roll over legacy family entries.
     for (const id of CACHE_PROVIDER_IDS) {
       const stats = cacheStatsLegacyFamily[id];
       if (stats && stats.day !== day) {
@@ -7312,57 +8134,37 @@ export default function (pi: ExtensionAPI) {
         changed = true;
       }
     }
-
     if (changed) {
+      shardCreatedAt = Date.now();
       lastStatusText = undefined;
-      await persistCacheStats(ctx);
+      await ensureCurrentEpochs();
+      await flushPersistCacheStats(ctx);
     }
   }
 
   async function restoreCacheStats(reason: string, ctx: ExtensionContext): Promise<void> {
     syncSessionHash(ctx);
-
+    lastStatusText = undefined;
+    cacheStatsProcessByModel = {};
+    cacheStatsLegacyFamily = emptyAllCacheStats();
+    modelEpochByKey.clear();
+    modelApiByKey.clear();
+    modelNameByKey.clear();
+    currentGlobalEpoch = await readGlobalStatsEpoch();
     if (reason === "reload") {
-      // /reload: preserve session-scoped stats (same session hash).
-      // Pi extension reload creates a fresh closure, so cacheStatsByModel
-      // starts empty. Read persisted data and filter for current session.
-      lastStatusText = undefined;
       lastPromptIntegrityWarningAt = 0;
       integrityNotificationShown = false;
       clearRecentSamples();
-
-      const persisted = await readPersistedCacheStats();
-      cacheStatsByModel = filterRestorableStatsForSession(
-        persisted,
-        currentSessionHashSet ? currentSessionHash : undefined,
-      );
-      cacheStatsProcessByModel = {};
-      cacheStatsTotalsByModel = persisted?.totalsByModel ?? {};
-      cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
-      lastActualRoutedModel = currentSessionHashSet
-        ? persisted?.lastRoutedModelBySession?.[currentSessionHash]
-        : undefined;
-
-      await rollOverStatsIfNeeded(ctx);
-      return;
     }
-
-    // First load / process start: read persisted stats and filter for
-    // this session's entries. If the session hash is unavailable, start
-    // fresh instead of loading all persisted session buckets.
-    const persisted = await readPersistedCacheStats();
-    cacheStatsByModel = filterRestorableStatsForSession(
-      persisted,
-      currentSessionHashSet ? currentSessionHash : undefined,
-    );
-    cacheStatsProcessByModel = {};
-    cacheStatsTotalsByModel = persisted?.totalsByModel ?? {};
-    cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
-    lastActualRoutedModel = currentSessionHashSet
-      ? persisted?.lastRoutedModelBySession?.[currentSessionHash]
-      : undefined;
-    lastStatusText = undefined;
-    await rollOverStatsIfNeeded(ctx);
+    await removeLegacyStatsFiles();
+    await mkdir(SHARD_FILES_DIR, { recursive: true });
+    await refreshShardAggregate();
+    await flushPersistCacheStats(ctx);
+    await maybeCleanupStatsShardsV7();
+    // Maintenance may remove expired shard files after the initial refresh.
+    // Re-scan before publishing so startup/footer command state cannot retain
+    // counters from files that no longer exist.
+    await refreshShardAggregate();
   }
 
   async function publishStatus(ctx: ExtensionContext, model: PiModel | undefined = ctx.model): Promise<void> {
@@ -7407,8 +8209,9 @@ export default function (pi: ExtensionAPI) {
     }
 
     if (adapter) {
-      // Footer mode defaults to daily provider/model totals. Users may select
-      // current-session counters through persistent command config or the env var.
+      // Footer mode defaults to current-session provider/model totals. Users may
+      // select all-current-day or current-process counters through persistent
+      // command config or the environment variable.
       const stats = displayModel
         ? selectFooterStatsForModel(mode, sessionHash, cacheStatsByModel, cacheStatsTotalsByModel, displayModel, cacheStatsProcessByModel)
         : undefined;
@@ -7480,25 +8283,45 @@ export default function (pi: ExtensionAPI) {
    * The caller strips prompt_cache_retention when this returns false.
    */
   function hasExplicitLongRetentionOptIn(model: PiModel): boolean {
-    try {
-      const text = readFileSync(MODELS_JSON_PATH, "utf8");
-      const parsed = parseJsonc(text);
-      return hasExplicitLongRetentionOptInFromConfig(parsed, model.provider, model.id);
-    } catch {
-      return false;
-    }
+    return hasExplicitLongRetentionOptInFromConfig(
+      readEffectiveCompatConfig(),
+      model.provider,
+      model.id,
+    );
   }
 
   pi.on("session_start", async (event, ctx) => {
     if (runtimeOptimizerEnabled) requestLongCacheRetention();
     await restoreCacheStats(event.reason, ctx);
+    if (ctx.mode === "tui" && !shardWatcher) {
+      try {
+        shardWatcher = watch(SHARD_FILES_DIR, () => scheduleShardRefresh(ctx));
+        shardWatcher.unref?.();
+      } catch {
+        // Lifecycle and explicit command refreshes remain authoritative.
+      }
+    }
+    await publishStatus(ctx);
+  });
+
+  pi.on("tool_execution_end", async (_event, ctx) => {
+    await refreshShardAggregate();
+    await publishStatus(ctx);
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    await refreshShardAggregate();
     await publishStatus(ctx);
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
     try {
-      await flushPersistCacheStats(ctx);
+      await flushPersistCacheStats(ctx, "closed");
     } finally {
+      if (shardRefreshTimer !== null) clearTimeout(shardRefreshTimer);
+      shardRefreshTimer = null;
+      shardWatcher?.close();
+      shardWatcher = undefined;
       latestCacheHint = undefined;
       delete getProtocolGlobal().__piCacheOptimizerCacheKey__;
       uninstallCacheHintsService();
@@ -7508,6 +8331,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("model_select", async (event, ctx) => {
     if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(event.model, ctx) ?? event.model, ctx, warnedModels);
+    await refreshShardAggregate();
     await publishStatus(ctx, event.model);
   });
 
@@ -7631,6 +8455,15 @@ export default function (pi: ExtensionAPI) {
     return {};
   });
 
+  pi.on("before_provider_headers", (event, ctx) => {
+    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+    addEffectiveSessionAffinityHeaders(
+      event.headers,
+      requestModel,
+      ctx.sessionManager.getSessionId(),
+    );
+  });
+
   pi.on("before_provider_request", (event, ctx) => {
     const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
 
@@ -7862,6 +8695,20 @@ export default function (pi: ExtensionAPI) {
     // Update session, process-local, and cumulative buckets for the actual
     // routed model. The process bucket is intentionally never persisted.
     if (statsModel) {
+      const key = modelKey(statsModel);
+      const latestGlobalEpoch = await readGlobalStatsEpoch();
+      const latestModelEpoch = await readModelStatsEpoch(key);
+      if (currentGlobalEpoch !== latestGlobalEpoch) {
+        currentGlobalEpoch = latestGlobalEpoch;
+        cacheStatsProcessByModel = {};
+        modelEpochByKey.clear();
+      }
+      if (modelEpochByKey.get(key) !== latestModelEpoch) {
+        delete cacheStatsProcessByModel[key];
+        modelEpochByKey.set(key, latestModelEpoch);
+      }
+      modelApiByKey.set(key, statsModel.api ?? "");
+      modelNameByKey.set(key, statsModel.name || statsModel.id);
       const sk = sessionModelKey(statsModel);
       addUsageToCacheStats(getOrCreateStatsByModelKey(sk), usage);
       addUsageToCacheStats(getOrCreateProcessStatsForModel(statsModel), usage);
@@ -7871,6 +8718,7 @@ export default function (pi: ExtensionAPI) {
     }
 
     schedulePersistCacheStats(ctx);
+    await refreshShardAggregate();
     await publishStatus(ctx, statsModel);
   });
 
@@ -7881,7 +8729,7 @@ export default function (pi: ExtensionAPI) {
   //   disable — disable runtime prompt/cache optimizations for this process
   //   doctor  — show current model/provider/api/baseUrl/compat status
   //             with low-hit diagnosis
-  //   stats   — show active model stats bucket, recent trend, usage
+  //   stats   — show detailed current-session models; `stats all` shows all local shards
   //   compat  — show compat suggestion with file path
   //   config footer-mode total|session|process — persist footer mode override
   //   fix     — auto-fix compat issues (writes models.json, requires UI)
@@ -7900,17 +8748,18 @@ export default function (pi: ExtensionAPI) {
 
       if (subcommand === "enable") {
         setRuntimeOptimizerEnabled(true);
-        resetCurrentSessionStats();
+        await resetCurrentSessionStats();
         await flushPersistCacheStats(cmdCtx);
         await publishStatus(cmdCtx, model);
         cmdCtx.ui.notify(`✅ Pi Cache Optimizer enabled for this Pi process. Local footer stats were reset for before/after comparison.\n${formatOptimizerRuntimeMode()}`, "info");
       } else if (subcommand === "disable") {
         setRuntimeOptimizerEnabled(false);
-        resetCurrentSessionStats();
+        await resetCurrentSessionStats();
         await flushPersistCacheStats(cmdCtx);
         await publishStatus(cmdCtx, model);
         cmdCtx.ui.notify(`⏸️ Pi Cache Optimizer disabled for this Pi process. Local footer stats were reset and will keep collecting while disabled for comparison.\n${formatOptimizerRuntimeMode()}`, "warning");
       } else if (subcommand === "doctor") {
+        await refreshShardAggregate();
         if (!model) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
@@ -7926,16 +8775,18 @@ export default function (pi: ExtensionAPI) {
           : diagnosis;
         cmdCtx.ui.notify(fullDiagnosis, "info");
       } else if (subcommand === "stats") {
-        if (!model) {
-          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
-          return;
+        const aggregate = await refreshShardAggregate();
+        const statsMode = commandParts[1];
+        if (statsMode === "all") {
+          cmdCtx.ui.notify(buildAllStatsOutput(aggregate), "info");
+        } else if (statsMode === "contributors") {
+          cmdCtx.ui.notify(buildContributorsStatsOutput(aggregate, model, currentSessionHashSet ? currentSessionHash : undefined), "info");
+        } else if (statsMode) {
+          cmdCtx.ui.notify("Usage: /cache-optimizer stats [all|contributors]", "info");
+        } else {
+          const sessionModels = currentSessionHashSet ? aggregate.bySession[currentSessionHash] ?? {} : {};
+          cmdCtx.ui.notify(buildSessionStatsOutput(sessionModels, model, aggregate.modelRefsByKey), "info");
         }
-        const adapter = selectAdapterForModel(model);
-        const sk = model ? sessionModelKey(model) : undefined;
-        const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
-        const samples = sk ? getRecentSamples(sk) : [];
-        const output = buildStatsOutput(model, adapter, statsState, samples);
-        cmdCtx.ui.notify(output, "info");
       } else if (subcommand === "config") {
         const configKey = commandParts[1];
         const requestedMode = commandParts[2];
@@ -7998,7 +8849,7 @@ export default function (pi: ExtensionAPI) {
         // Reset local footer 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);
+        await resetStatsForModel(model);
 
         // Persist immediately.
         await flushPersistCacheStats(cmdCtx);
@@ -8348,7 +9199,7 @@ export default function (pi: ExtensionAPI) {
             "Enable — Turn on runtime optimizations",
             "Disable — Turn off runtime optimizations",
             "Doctor — Show cache configuration",
-            "Stats — Show cache stats and trend",
+            "Stats — Show current-session model statistics",
             "Compat — Show compat suggestion",
             "Fix — Auto-fix compat issues (writes models.json)",
             "Footer mode — Choose total, session, or process stats",
@@ -8369,12 +9220,12 @@ export default function (pi: ExtensionAPI) {
           } else if (choice === menuOptions[5]) {
             await handleCacheOptimizerCommand("fix", cmdCtx);
           } else if (choice === menuOptions[6]) {
-            const modeOptions = ["total — Daily cumulative totals (default)", "session — Current Pi conversation session", "process — Current Pi process only", "Cancel"];
+            const modeOptions = ["session — Current Pi conversation session (default)", "total — All local sessions today", "process — Current extension instance only", "Cancel"];
             const modeChoice = await cmdCtx.ui.select("Footer cache stats mode", modeOptions);
             const nextMode = modeChoice === modeOptions[0]
-              ? "total"
+              ? "session"
               : modeChoice === modeOptions[1]
-                ? "session"
+                ? "total"
                 : modeChoice === modeOptions[2]
                   ? "process"
                   : undefined;
@@ -8392,7 +9243,9 @@ export default function (pi: ExtensionAPI) {
         diagnosis.push("  enable  — Enable prompt/cache optimizations for this Pi process");
         diagnosis.push("  disable — Disable prompt/cache optimizations for this Pi process");
         diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat and low-hit diagnosis");
-        diagnosis.push("  stats   — Show active model stats bucket and recent trend");
+        diagnosis.push("  stats   — Show detailed statistics for every model in the current session");
+        diagnosis.push("  stats all — Show detailed totals for every model across all local sessions");
+        diagnosis.push("  stats contributors — Show per-session contributors for the active model");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
         diagnosis.push("  config footer-mode total|session|process — Persist the footer stats mode");
         diagnosis.push("  fix     — Auto-fix compat issues (writes models.json, requires UI)");