pi-cache-optimizer 2.4.8 → 2.5.0

package/README.md

@@ -254,11 +254,30 @@ Stats rules:
 - Stats are persisted in a small local JSON state file at `~/.pi/agent/pi-cache-optimizer-stats.json`. Earlier 1.x releases used `~/.pi/agent/deepseek-cache-optimizer-stats.json`; on first run after upgrade the old file is read once, copied into the new path, and best-effort deleted. The file stores only counters and the local day; it does not store API keys, prompts, messages, headers, or model output.
 - Existing v1 state files from DeepSeek-only releases are migrated into the DeepSeek adapter counters automatically.
 
-Reset behavior:
-
-- Pi restarts do **not** clear stats; the persisted counters are restored.
-- `/reload` / extension reload resets the persisted counters because Pi exposes `session_start` with reason `reload`.
-- Crossing the local natural-day boundary resets counters on the next status update or supported-provider response.
+Session scope:
+
+- Stats are now scoped per Pi session + provider/model, not global.
+- Each Pi process (session) starts with fresh counters. Different sessions using the
+  same provider/model do not share footer statistics or reset effects.
+- Within the same Pi session, stats accumulate normally for each provider/model.
+- Pi restarts start fresh stats for the new session.
+- `/reload` does **not** clear accumulated session-scoped stats; it only clears transient
+  in-memory data (recent samples, integrity notification state).
+- Crossing the local natural-day boundary resets counters on the next status update or
+  supported-provider response.
+- Persisted stats are stored under an opaque session hash key (SHA-256 hash of session id)
+  so that different sessions' data is isolated on disk. Raw session ids are never logged,
+  displayed, or written to the stats file.
+
+> **Concurrent-write caveat**: Stats are persisted atomically (write-temp then rename),
+> but multiple Pi processes reading and writing simultaneously can still experience
+> a lost-update window (the classic read-modify-write race). The implementation
+> preserves sequential operation semantics (each write replaces only the current
+> session's data and re-appends other sessions from the previous read), but does
+> **not** guarantee concurrent-safety across processes. If you run multiple Pi
+> instances using the same `models.json` with different provider/model IDs, their
+> stats files may occasionally overwrite each other's session data. This affects
+> only the on-disk persistence; in-memory counters per process remain correct.
 
 ## Suggested compat config
 
@@ -304,14 +323,38 @@ The extension registers a Pi command `/cache-optimizer` for interactive diagnosi
 ```
 /cache-optimizer              — interactive menu (or text help when no UI)
 /cache-optimizer doctor        — show provider, model, API, base URL, compat status
+                                    and low-hit cause diagnosis
+/cache-optimizer stats         — show active model stats bucket and recent trend
 /cache-optimizer compat        — show compat suggestion with edit instructions
+/cache-optimizer reset         — reset local session stats for the current model
+                                  (does not affect upstream provider prompt cache)
 ```
 
 When run without arguments, `/cache-optimizer` shows an interactive selection menu
-(Doctor / Compat / Cancel) when the Pi UI supports it (`ctx.ui.select`). In
-non-interactive terminals, it falls back to text help with current model compat
+(Doctor / Stats / Compat / Reset / Cancel) when the Pi UI supports it (`ctx.ui.select`).
+In non-interactive terminals, it falls back to text help with current model compat
 status.
 
+### `/cache-optimizer reset`
+
+Resets only the current Pi session's stats bucket for the active provider/model.
+Clears today's request counters (hit/total), cached token counts, and recent trend
+samples for that model. Other provider/model buckets within the same session are
+unaffected, and other sessions' data is preserved.
+
+```text
+Provider: otokapi
+Model: gpt-5.5
+
+✅ Reset local session cache stats for "otokapi/gpt-5.5".
+   Upstream provider prompt cache was not modified.
+   New requests will start a fresh stats bucket for this Pi session.
+```
+
+If no active model is selected, a warning is shown. If the active model does not
+match a cache adapter (footer stats are not shown for it), a friendly no-op message
+is displayed instead.
+
 ### `/cache-optimizer doctor`
 
 Displays the active model's provider, model id, name, API type, base URL, current
@@ -345,7 +388,52 @@ it shows `✅ Compat fully configured.` if the model is an applicable
 third-party proxy, or `ℹ️ Compat check not applicable for this model.`
 otherwise.
 
-When the model is routed through a known router/channel proxy (OpenRouter,
+### `/cache-optimizer stats`
+
+Displays the active model's stats bucket (`provider/modelId`), today's request
+count (hit/total), cached input tokens vs total input tokens, and the hit rate
+percentage. Also shows recent trend summaries (last 10 and last 30 samples):
+
+```text
+Model key: otokapi/gpt-5.5
+Adapter:   OpenAI cache
+
+── Today ──
+Requests:      3 hit / 10 total · 30%
+Cached tokens: 0.0015M / 0.005M input · 30%
+
+── Recent trend ──
+Recent 10/10: 3/10 hits · 30% tok cached
+Recent 10/10: 3/10 hits · 30% tok cached
+```
+
+If the active model has no adapter match, a friendly message is shown. If
+no samples have been recorded yet in this session, trend shows "no samples".
+
+### Low-hit cause diagnosis
+
+The `/cache-optimizer doctor` output includes a "Cache diagnosis" section
+with prioritized low-hit cause analysis:
+
+1. **Missing compat flags** — flags that enable prompt caching and session-affinity
+   routing are absent.
+2. **Router/channel risk** — multi-backend routing may split the cache across
+   different upstream instances.
+3. **Missing usage fields** — the proxy may not return prompt-level usage
+   fields, causing the footer to under-report hits.
+4. **Recent low trend** — when today's cache hit rate is below 30%,
+   the diagnosis suggests proxy route instability or prompt prefix churn.
+
+For fully configured models that still have low cache hit rates, the diagnosis
+emphasizes sticky routing and upstream cache usage verification rather than
+pointing to compat flags.
+
+### Router/channel diagnostics
+
+For models using OpenAI-compatible APIs (`openai-completions` or
+`openai-responses`) through a non-official base URL, the extension detects
+common router/channel proxy patterns from `provider`, `baseUrl`, and `compat`
+metadata:
 Vercel AI Gateway, LiteLLM, OneAPI/NewAPI/VoAPI, or a generic third-party
 OpenAI-compatible proxy), both `doctor` and `compat` subcommands append
 router/channel diagnostics with targeted recommendations.

package/README.zh-CN.md

@@ -249,11 +249,48 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 - 统计会持久化到本地小 JSON 文件：`~/.pi/agent/pi-cache-optimizer-stats.json`。早期 1.x 版本使用 `~/.pi/agent/deepseek-cache-optimizer-stats.json`；首次运行新版时会从旧路径读一次、复制到新路径、然后 best-effort 删除旧文件。该文件只保存计数器和本地日期，不保存 API key、prompt、消息内容、headers 或模型输出。
 - DeepSeek-only 旧版本的 v1 状态文件会自动迁移到 DeepSeek adapter 计数器。
 
-重置规则：
+## 统计桶隔离（Session-scoped）
 
-- Pi 重启**不会**清零统计；扩展会恢复已持久化的计数器。
-- `/reload` / extension reload 会清零并覆盖持久化计数器，因为 Pi 会暴露 `session_start` 的 `reason: "reload"`。
-- 长时间运行跨过本地自然日时，会在下一次状态更新或受支持 provider 响应统计前自动按本地日期清零。
+- 统计现在按 Pi session + provider/model 隔离，不再全局聚合。
+- 每个 Pi 进程（session）从零开始计数。不同 session 对同一 provider/model 的统计不共享。
+- 同一 Pi session 中，同一 provider/model 的统计正常累积。
+- Pi 进程重新启动时，新的 session 从头开始统计。
+- `/reload` **不会**清空累计的 session-scoped 统计；只清除临时内存状态（recent samples、integrity notification）。
+- 跨过本地自然日时，下一次状态更新或受支持 provider 响应时会自动按本地日期清零。
+- 持久化统计文件使用不透明的 session hash key（SHA-256 哈希后的 session id）来隔离不同 session 的数据。原始 session id 不会写入文件。
+
+> **并发写入说明**：统计以原子方式持久化（写 temp 文件再 rename），但多个 Pi 进程同时读写仍然存在 lost-update 窗口（经典的 read-modify-write 竞态）。实现中尽可能保留顺序语义（每次写入只替换当前 session 的数据，其他 session 的数据从前次读取追加），但**不保证**跨进程并发安全。如果同时运行多个 Pi 实例使用不同 provider/model，统计文件偶尔可能覆盖彼此 session 的数据。这只影响磁盘持久化；每个进程的内存统计始终正确。
+
+## 诊断命令
+
+扩展注册了 Pi 命令 `/cache-optimizer` 用于交互式诊断。
+
+```
+/cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
+/cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
+                                   及低命中原因诊断
+/cache-optimizer stats         — 显示当前模型的 stats 桶和近期趋势
+/cache-optimizer compat        — 显示 compat 建议和编辑说明
+/cache-optimizer reset         — 重置当前 Pi session 中当前模型的本地统计
+                                  （不影响上游 provider prompt cache）
+```
+
+不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Stats / Compat / Reset / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
+
+### `/cache-optimizer reset`
+
+仅重置当前 Pi session 中活跃 provider/model 的统计桶。清除今日请求计数（命中/总数）、缓存 token 计数和近期趋势样本。同一 session 中其他 provider/model 的桶不受影响，其他 session 的数据也不受影响。
+
+```text
+Provider: otokapi
+Model: gpt-5.5
+
+✅ 已重置 "otokapi/gpt-5.5" 的本地 session 缓存统计。
+   上游 provider prompt cache 未被修改。
+   新的请求将为这个 Pi session 重新开始统计。
+```
+
+如果没有选中的模型，显示警告。如果当前模型不匹配缓存的 adapter（不显示底部统计），则显示友好的无操作提示。
 
 ## 建议的 compat 配置
 
@@ -291,68 +328,6 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 
 > 提醒：只有在 endpoint 或代理明确支持时，才建议启用 session-affinity headers 或 cache-control compat。
 
-## 诊断命令
-
-扩展注册了 Pi 命令 `/cache-optimizer` 用于交互式诊断。
-
-```
-/cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
-/cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
-/cache-optimizer compat        — 显示 compat 建议和编辑说明
-```
-
-不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Compat / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
-
-### `/cache-optimizer doctor`
-
-显示当前模型的 provider、model id、名称、API 类型、base URL、当前 `compat` 标志以及缺少的缓存/session-affinity 标志。如果缺少标志，还会显示可复制的 JSON 片段和精确编辑位置。
-
-如果所有 compat 标志都已配置且适用（第三方 `openai-completions` 代理），输出显示 `✅ Compat fully configured.`。对于不适用 compat 检查的模型（官方 OpenAI、非 `openai-completions` API、custom transport），显示 `ℹ️ Compat check not applicable for this model.`：
-
-```text
-Provider: otokapi
-Model:    gpt-5.5
-API:      openai-completions
-Base URL: https://otokapi.example.com/v1
-Compat:   {}
-⚠️  Missing compat flags: supportsLongCacheRetention, sendSessionAffinityHeaders
-Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as baseUrl/api/apiKey/models):
-{
-  "supportsLongCacheRetention": true,
-  "sendSessionAffinityHeaders": true
-}
-```
-
-### `/cache-optimizer compat`
-
-显示当前模型的 compat 建议，包括文件路径、provider 路径和可复制 JSON 片段。当没有缺失的 compat 标志时，如果模型是适用的第三方代理则显示 `✅ Compat fully configured.`，否则显示 `ℹ️ Compat check not applicable for this model.`。
-
-当模型通过已知的路由器/通道代理（OpenRouter、Vercel AI Gateway、LiteLLM、OneAPI/NewAPI/VoAPI 或通用第三方 OpenAI-compatible 代理）时，`doctor` 和 `compat` 子命令都会附加路由/通道诊断信息和建议。
-
-### 路由/通道诊断
-
-对于通过非官方 base URL 使用 OpenAI-compatible API（`openai-completions` 或 `openai-responses`）的模型，扩展会从 `provider`、`baseUrl` 和 `compat` 元数据中检测常见的路由/通道代理模式：
-
-| 类型 | 检测方式 | 建议 |
-|------|----------|------|
-| **OpenRouter** | baseUrl 或 provider 包含 `openrouter`/`openrouter.ai` | 在 compat 中用 `openRouterRouting.only` 或 `.order` 固定上游 provider |
-| **Vercel AI Gateway** | baseUrl 包含 `ai-gateway.vercel.sh` 或 provider 包含 `vercel` | 在 compat 中用 `vercelGatewayRouting.only` 或 `.order` 固定上游 |
-| **LiteLLM / OneAPI / NewAPI / VoAPI** | baseUrl 或 provider 包含 `litellm`、`oneapi`/`one-api`、`newapi`/`new-api`、`voapi`/`vo-api` | 确保每 session 固定路由，转发 `prompt_cache_key` + session-affinity headers，返回缓存用量字段 |
-| **通用第三方代理** | 任何非官方 base URL 的 `openai-completions` 模型，且不匹配以上类型 | 通用建议：验证单上游路由、转发 `prompt_cache_key` + session-affinity headers、返回缓存用量 |
-
-这些诊断**仅用于建议**。它们不参与 adapter selection（仍基于 id/name）、不参与 `prompt_cache_key` 注入、不参与 footer 统计、也不做任何自动化配置修改。检测仅使用 Pi 暴露的元数据（`provider`、`api`、`baseUrl`、`compat`），不会读取或暴露 API key、prompt、payload、headers 或模型输出。
-
-官方 OpenAI（`api.openai.com`）和 custom transport（`kiro-api`、`anthropic-messages`、`bedrock-converse-stream`）不会触发路由/通道诊断。
-
-### 安全说明
-
-命令只读取 Pi 通过 `ctx.model` 暴露的元数据：provider、id、name、api、baseUrl、compat。它**不会**读取或暴露：
-- API key 或环境密钥
-- 请求/响应 payload
-- Prompt 或模型输出
-- HTTP headers
-- `~/.pi/agent/models.json` 的原始内容
-
 ## 原理
 
 Provider 缓存通常依赖精确或近似精确的前缀匹配。Pi 的 system prompt 包含跨会话稳定的内容（工具定义、技能、规范），也包含每次变化的动态内容（git status、当前任务）。

package/index.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -135,6 +136,19 @@ type PersistedCacheStatsV3 = {
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
 };
 
+/**
+ * V4 format: session-scoped stats buckets.
+ * Each Pi process/session gets its own stats isolated by a hashed session id.
+ *
+ * sessions: sessionHash → modelKey (provider/id) → CacheStats
+ * legacyFamily: unchanged from v3 (migration/fallback when ctx.model is unknown)
+ */
+type PersistedCacheStatsV4 = {
+  version: 4;
+  sessions: Record<string, Record<string, CacheStats>>;
+  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
+};
+
 type UsageSnapshot = {
   cacheRead: number;
   cacheWrite: number;
@@ -147,6 +161,23 @@ type OptimizedSystemPrompt = {
   changed: boolean;
 };
 
+/**
+ * Per-request sample stored for trend analysis and usage-field-missing detection.
+ * Contains only numeric counters and booleans — never message content, prompts,
+ * payloads, headers, API keys, or model outputs.
+ */
+type CacheUsageSample = {
+  timestamp: number;
+  hit: boolean;
+  cachedInputTokens: number;
+  cacheWriteInputTokens: number;
+  totalInputTokens: number;
+  missingUsageFields: boolean;
+};
+
+/** Maximum number of recent samples kept per model key (in-memory only, not persisted). */
+const MAX_RECENT_SAMPLES = 50;
+
 type CacheProviderAdapter = {
   id: CacheProviderId;
   label: string;
@@ -545,6 +576,32 @@ function getSessionPromptCacheKey(ctx: ExtensionContext): string | undefined {
   return clampPromptCacheKey(ctx.sessionManager.getSessionId());
 }
 
+/**
+ * Hash a session id for use as a non-reversible opaque scope key.
+ * Returns a 16-character hex string (64 bits of SHA-256 digest prefix)
+ * suitable for scoping stats buckets without exposing the raw session id.
+ */
+function hashSessionId(sessionId: string): string {
+  return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+}
+
+/**
+ * Build a session-scoped stats key from a session hash + provider/id.
+ * Pure function (no closure dependency) for use by tests and internals.
+ */
+function makeSessionModelKey(sessionHash: string, provider: string, id: string): string {
+  return `${sessionHash}:${provider}/${id}`;
+}
+
+/**
+ * Extract the user-facing model key from a session-scoped key.
+ * "abc123:otokapi/gpt-5.5" → "otokapi/gpt-5.5"
+ */
+function modelKeyFromSessionKey(sessionModelKey: string): string {
+  const idx = sessionModelKey.indexOf(":");
+  return idx >= 0 ? sessionModelKey.slice(idx + 1) : sessionModelKey;
+}
+
 function asRecord(value: unknown): UnknownRecord | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   return value as UnknownRecord;
@@ -1141,6 +1198,10 @@ function modelKey(model: PiModel): string {
   return `${model.provider}/${model.id}`;
 }
 
+function keyForModelExt(model: { provider: string; id: string }): string {
+  return `${model.provider}/${model.id}`;
+}
+
 function usageRecordFromAssistant(message: unknown): UnknownRecord | undefined {
   return asRecord(getAssistantRecord(message)?.usage);
 }
@@ -2473,6 +2534,119 @@ function formatCacheStats(adapter: CacheProviderAdapter, stats: CacheStats): str
   return `${adapter.label} ${stats.hitRequests}/${stats.totalRequests} · ${formatTokenCount(stats.cachedInputTokens)}/${formatTokenCount(stats.totalInputTokens)} tok${percent}${writeText}`;
 }
 
+/**
+ * Compute a hit-ratio percentage string for a value between 0 and 1.
+ * Returns e.g. "75%", "0%", "100%", or "N/A" for zero total.
+ */
+function formatHitRatio(hits: number, total: number): string {
+  if (total <= 0) return "N/A";
+  return `${Math.round((hits / total) * 100)}%`;
+}
+
+/**
+ * Format a token-to-M abbreviation for stats output.
+ * Example: 1500000 → "1.50M"
+ */
+function formatTokenM(value: number): string {
+  const millions = Math.max(0, Math.round(value)) / 1_000_000;
+  if (millions === 0) return "0";
+  if (millions < 0.01) return millions.toFixed(4);
+  if (millions >= 10) return millions.toFixed(1);
+  return millions.toFixed(2);
+}
+
+/**
+ * Check if an assistant message's usage fields appear to be missing or empty.
+ * Returns true when Pi-normalized fields (input, cacheRead, cacheWrite) are all
+ * absent/zero AND raw usage fields (prompt_tokens, etc.) are also absent/zero
+ * for the given adapter.
+ */
+function hasMissingUsageFields(message: unknown, adapter: CacheProviderAdapter): boolean {
+  const usage = usageRecordFromAssistant(message);
+  if (!usage) return true;
+
+  // Check Pi-normalized fields
+  const input = getNonNegativeNumber(usage, "input");
+  const cacheRead = getNonNegativeNumber(usage, "cacheRead");
+  const cacheWrite = getNonNegativeNumber(usage, "cacheWrite");
+
+  // If Pi-normalized fields exist with non-zero values, usage is present
+  if (cacheRead !== undefined || cacheWrite !== undefined || (input !== undefined && input > 0)) {
+    return false;
+  }
+
+  // Check raw usage for the adapter's provider family
+  const rawUsage = adapter.normalizeUsage(message);
+  if (!rawUsage || (rawUsage.cacheRead === 0 && rawUsage.cacheWrite === 0 && rawUsage.totalInput === 0)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Build a summary string for the recent trend (last N samples).
+ * Example: "Recent 10: 7/10 hits · 65% tok cached · no missing usage"
+ */
+function formatRecentTrendSummary(samples: CacheUsageSample[], maxCount: number): string {
+  const recent = samples.slice(-maxCount);
+  if (recent.length === 0) return `Recent ${maxCount}: no samples yet`;
+
+  const hits = recent.filter((s) => s.hit).length;
+  const totalCached = recent.reduce((sum, s) => sum + s.cachedInputTokens, 0);
+  const totalInput = recent.reduce((sum, s) => sum + s.totalInputTokens, 0);
+  const missingCount = recent.filter((s) => s.missingUsageFields).length;
+
+  const hitRatio = formatHitRatio(hits, recent.length);
+  const tokenRatio = totalInput > 0 ? formatHitRatio(totalCached, totalInput) : "N/A";
+
+  let result = `Recent ${recent.length}/${maxCount}: ${hits}/${recent.length} hits · ${tokenRatio} tok cached`;
+  if (missingCount > 0) {
+    result += ` · ${missingCount} missing usage`;
+  }
+  return result;
+}
+
+/**
+ * Build the output for `/cache-optimizer stats`.
+ */
+function buildStatsOutput(model: PiModel | undefined, adapter: CacheProviderAdapter | undefined, stats: CacheStats | undefined, recentSamples: CacheUsageSample[]): string {
+  const lines: string[] = [];
+
+  if (!model || !adapter) {
+    lines.push("ℹ️ No cache-adapter-matched model active. Select a model with a recognized provider family.");
+    return lines.join("\n");
+  }
+
+  const key = modelKey(model);
+  const currentStats = stats ?? emptyCacheStats();
+
+  lines.push(`Model key: ${key}`);
+  lines.push(`Adapter:   ${adapter.label}`);
+  lines.push("");
+  lines.push("── Today ──");
+  lines.push(`Requests:      ${currentStats.hitRequests} hit / ${currentStats.totalRequests} total · ${formatHitRatio(currentStats.hitRequests, currentStats.totalRequests)}`);
+  lines.push(`Cached tokens: ${formatTokenM(currentStats.cachedInputTokens)}M / ${formatTokenM(currentStats.totalInputTokens)}M input · ${currentStats.totalInputTokens > 0 ? `${Math.round((currentStats.cachedInputTokens / currentStats.totalInputTokens) * 100)}%` : "N/A"}`);
+  if (currentStats.cacheWriteInputTokens > 0) {
+    lines.push(`Cache write:   ${formatTokenM(currentStats.cacheWriteInputTokens)}M tok`);
+  }
+
+  lines.push("");
+  lines.push("── Recent trend ──");
+  lines.push(formatRecentTrendSummary(recentSamples, 10));
+  lines.push(formatRecentTrendSummary(recentSamples, 30));
+
+  // Check if any sample has missingUsageFields flagged
+  const missingAny = recentSamples.some((s) => s.missingUsageFields);
+  if (missingAny) {
+    lines.push("");
+    lines.push("⚠️ Some recent responses had missing or empty cache usage fields. Footer may under-report hits.");
+    lines.push("   The proxy may not return prompt_cache_hit_tokens or usage.input/cacheRead in responses.");
+  }
+
+  return lines.join("\n");
+}
+
 function getErrorCode(error: unknown): string | undefined {
   return typeof error === "object" && error !== null && "code" in error
     ? String((error as { code?: unknown }).code)
@@ -2517,7 +2691,39 @@ function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
   const record = asRecord(value);
   if (!record) return undefined;
 
-  // version 3: model-scoped stats + legacy family fallback
+  // version 4: session-scoped stats + legacy family fallback
+  if (record.version === 4) {
+    const legacyFamily: Partial<Record<CacheProviderId, CacheStats>> = {};
+    const rawFamily = asRecord(record.legacyFamily);
+    if (rawFamily) {
+      for (const id of CACHE_PROVIDER_IDS) {
+        const stats = parseCacheStats(rawFamily[id]);
+        if (stats) legacyFamily[id] = stats;
+      }
+    }
+
+    // Collect all session entries into statsByModel with session-hash-prefixed keys
+    // (e.g. "abc123:otokapi/gpt-5.5") so that writePersistedCacheStats can later
+    // reconstruct individual sessions from the flat key format and other sessions'
+    // data is not silently lost on round-trip.
+    const statsByModel: Record<string, CacheStats> = {};
+    const rawSessions = asRecord(record.sessions);
+    if (rawSessions) {
+      for (const [sessionHash, modelMap] of Object.entries(rawSessions)) {
+        const parsedMap = asRecord(modelMap);
+        if (parsedMap) {
+          for (const [modelKey, val] of Object.entries(parsedMap)) {
+            const parsed = parseCacheStats(val);
+            if (parsed) statsByModel[`${sessionHash}:${modelKey}`] = parsed;
+          }
+        }
+      }
+    }
+
+    return { statsByModel, legacyFamily };
+  }
+
+  // version 3: migrate to v4 semantics by wrapping statsByModel into sessions
   if (record.version === 3) {
     const statsByModel: Record<string, CacheStats> = {};
     const rawModelMap = asRecord(record.statsByModel);
@@ -2602,11 +2808,122 @@ async function readPersistedCacheStats(): Promise<CacheStatsState | undefined> {
   return undefined;
 }
 
-async function writePersistedCacheStats(state: CacheStatsState): Promise<void> {
+/**
+ * The closure-internal writer. Since the closure has access to currentSessionHash,
+ * it passes the hash and statsByModel here. This function wraps them in the v4
+ * sessions format, combining with any previously-persisted sessions for safety.
+ *
+ * When called from the closure, `state.statsByModel` contains only the current
+ * session's entries (keyed by `${sessionHash}:${provider}/${id}`). We extract
+ * the model-key-only entries and store them under the session hash.
+ */
+/**
+ * Merge in-memory stats state into an existing sessions map for persistence.
+ *
+ * When `currentSessionHash` is provided (explicit hash mode):
+ *   - Current-session entries are extracted from `state.statsByModel` (keys
+ *     prefixed with `currentSessionHash:`) and written under the session hash.
+ *   - The transitional legacy `_nosession` bucket is DELETED — its entries
+ *     were already consumed and migrated into memory by `restoreCacheStats`.
+ *     Keeping `_nosession` on disk would allow resurrection of reset stats
+ *     on the next reload (the reset-undo bug).
+ *   - Other real session hashes are preserved intact.
+ *
+ * When `currentSessionHash` is undefined (no-hash mode):
+ *   - Keys with a hash prefix (`hash:provider/model`) are grouped under their
+ *     respective session hashes.
+ *   - Keys without a hash prefix (legacy v3) are grouped under `_nosession` so
+ *     `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`.
+ */
+function mergeCacheSessions(
+  existingSessions: Record<string, Record<string, CacheStats>>,
+  state: CacheStatsState,
+  currentSessionHash?: string,
+): Record<string, Record<string, CacheStats>> {
+  // Deep-copy to avoid mutating the caller's object.
+  const sessions: Record<string, Record<string, CacheStats>> = {};
+  for (const [hash, models] of Object.entries(existingSessions)) {
+    sessions[hash] = { ...models };
+  }
+
+  if (currentSessionHash !== undefined) {
+    // Explicit hash mode: extract this session's data from state.statsByModel.
+    // When the session has no entries (e.g. after reset of sole bucket), this
+    // still sets an empty map, ensuring the deleted bucket does not return.
+    const prefix = `${currentSessionHash}:`;
+    const currentModelStats: Record<string, CacheStats> = {};
+    for (const [fullKey, stats] of Object.entries(state.statsByModel)) {
+      if (fullKey.startsWith(prefix)) {
+        currentModelStats[fullKey.slice(prefix.length)] = stats;
+      }
+    }
+    sessions[currentSessionHash] = currentModelStats;
+
+    // _nosession is a transitional legacy migration bucket — once we write
+    // under an authoritative session hash, those entries have already been
+    // consumed and migrated into memory by restoreCacheStats. Delete to
+    // prevent resurrection of reset stats on the next reload.
+    delete sessions["_nosession"];
+  } else {
+    // No-hash mode: group entries by their existing hash prefix to avoid
+    // collapsing multiple sessions into one bucket. Keys without a hash
+    // prefix (legacy v3) go under "_nosession" so restoreCacheStats can
+    // migrate them to the current session on next load.
+    const nosessionMap: Record<string, CacheStats> = {};
+    for (const [fullKey, stats] of Object.entries(state.statsByModel)) {
+      const idx = fullKey.indexOf(":");
+      if (idx >= 0) {
+        const hash = fullKey.slice(0, idx);
+        const modelKey = fullKey.slice(idx + 1);
+        if (!sessions[hash]) sessions[hash] = {};
+        sessions[hash][modelKey] = stats;
+      } else {
+        // Key without hash prefix (legacy v3) — group under _nosession.
+        nosessionMap[fullKey] = stats;
+      }
+    }
+    if (Object.keys(nosessionMap).length > 0) {
+      sessions["_nosession"] = nosessionMap;
+    }
+  }
+
+  return sessions;
+}
+
+async function writePersistedCacheStats(state: CacheStatsState, currentSessionHash?: string): Promise<void> {
   await mkdir(STATE_DIR, { recursive: true });
-  const payload: PersistedCacheStatsV3 = {
-    version: 3,
-    statsByModel: state.statsByModel,
+
+  // Read existing file to preserve other sessions' data.
+  let existingSessions: Record<string, Record<string, CacheStats>> = {};
+  try {
+    const raw = await readFile(STATE_FILE_PATH, "utf8");
+    const parsed = parsePersistedCacheStats(JSON.parse(raw));
+    if (parsed) {
+      // Reconstruct sessions from statsByModel keys.
+      // Each key has form `${hash}:${provider}/${id}`; group by hash.
+      for (const [fullKey, stats] of Object.entries(parsed.statsByModel)) {
+        const idx = fullKey.indexOf(":");
+        if (idx >= 0) {
+          const hash = fullKey.slice(0, idx);
+          const modelKey = fullKey.slice(idx + 1);
+          if (!existingSessions[hash]) existingSessions[hash] = {};
+          existingSessions[hash][modelKey] = stats;
+        }
+      }
+    }
+  } catch {
+    // Ignore read errors (file may not exist yet).
+  }
+
+  const sessions = mergeCacheSessions(existingSessions, state, currentSessionHash);
+
+  const payload: PersistedCacheStatsV4 = {
+    version: 4,
+    sessions,
     legacyFamily: state.legacyFamily,
   };
   const tempPath = `${STATE_FILE_PATH}.${process.pid}.${Date.now()}.tmp`;
@@ -2842,6 +3159,115 @@ function buildDoctorDiagnosis(model: PiModel): string {
   return lines.join("\n");
 }
 
+/**
+ * Build a "Cache diagnosis" section for low-hit causes, appended to doctor output.
+ * This is a separate function because it depends on per-session state (recent samples,
+ * per-model stats) that is not available at the module level.
+ */
+function buildLowHitDiagnosis(
+  model: PiModel,
+  adapter: CacheProviderAdapter | undefined,
+  stats: CacheStats | undefined,
+  samples: CacheUsageSample[],
+): string[] {
+  const lines: string[] = [];
+
+  // 1. Missing compat flags (reuse existing check)
+  const missingCompat = describeMissingOpenAICompatibleProxyCompat(model);
+
+  // 2. Router/channel risk (reuse existing check)
+  const routerNotes = describeRouterChannelDiagnostics(model);
+
+  // 3. Recent samples missing usage fields
+  const missingUsageSamples = samples.filter((s) => s.missingUsageFields).length;
+
+  // 4. Recent trend analysis
+  const recent10 = samples.slice(-10);
+  const recent10Hits = recent10.filter((s) => s.hit).length;
+  const recent10Total = recent10.length;
+  const recent10Cached = recent10.reduce((sum, s) => sum + s.cachedInputTokens, 0);
+  const recent10Input = recent10.reduce((sum, s) => sum + s.totalInputTokens, 0);
+
+  // 5. Today's overall trend from persisted stats
+  const todayStats = stats ?? emptyCacheStats();
+
+  const hasMissingCompat = missingCompat.length > 0;
+  const hasRouterRisk = routerNotes.length > 0;
+  const hasUsageMissing = missingUsageSamples > 0;
+
+  // Determine if there are actual issues worth flagging
+  const hasActualIssues = hasMissingCompat || hasUsageMissing ||
+    // Low hit trend (today total > 3 and hit ratio < 30%)
+    (todayStats.totalRequests > 3 && todayStats.totalInputTokens > 0 &&
+     (todayStats.cachedInputTokens / todayStats.totalInputTokens) < 0.3) ||
+    // Low hit rate in recent samples (recent10Total >= 3 and all misses)
+    (recent10Total >= 3 && recent10Hits === 0);
+
+  // Skip section if no issues
+  if (!hasActualIssues && !(hasRouterRisk && (hasMissingCompat || hasUsageMissing))) {
+    return lines;
+  }
+
+  lines.push("");
+  lines.push("── Cache diagnosis ──");
+
+  // Priority 1: missing compat flags
+  if (hasMissingCompat) {
+    lines.push(`⚠️  Missing compat flags: ${missingCompat.join(", ")}`);
+    lines.push("   These flags enable prompt caching and session-affinity routing.");
+    lines.push("   Run /cache-optimizer compat for edit instructions.");
+  }
+
+  // Priority 2: router/channel risk (only flag when there are other issues)
+  // Router notes are already shown in the main doctor output, so we only
+  // mention them in the diagnosis section when they compound a problem.
+  if (hasRouterRisk && (hasMissingCompat || hasUsageMissing || hasActualIssues)) {
+    lines.push("🔀 Router/channel proxy detected — see routing notes above.");
+  }
+
+  // Priority 3: usage fields missing
+  if (hasUsageMissing) {
+    lines.push(`⚠️  ${missingUsageSamples}/${samples.length} recent responses had missing/empty usage fields.`);
+    lines.push("   Footer may under-report cache hit rate.");
+    lines.push("   Verify the proxy returns prompt-level usage (prompt_tokens, input_tokens_details).");
+  }
+
+  // Priority 4: recent trend low
+  if (recent10Total > 0) {
+    const hitRatio = recent10Input > 0 ? Math.round((recent10Cached / recent10Input) * 100) : 0;
+    const todayHitRatio = todayStats.totalInputTokens > 0
+      ? Math.round((todayStats.cachedInputTokens / todayStats.totalInputTokens) * 100)
+      : 0;
+
+    if (recent10Hits === 0 && todayStats.totalRequests > 3 && todayHitRatio < 30) {
+      lines.push(`📉 Cache hit rate is low: ${todayHitRatio}% today (${recent10Total} recent samples).`);
+      lines.push("   Likely causes: proxy routing to different backends per request,");
+      lines.push("   or prompt prefix changes across turns.");
+      lines.push("   Verify session affinity (sendSessionAffinityHeaders) and long cache retention.");
+    } else if (todayHitRatio < 30 && todayStats.totalRequests > 3) {
+      lines.push(`📉 Cache hit rate is low: ${todayHitRatio}% today (${todayStats.totalRequests} total requests).`);
+      lines.push("   Check compat flags and proxy upstream routing.");
+    }
+
+    // Show brief trend summary if there are enough samples
+    if (recent10Total >= 3) {
+      const trend = formatRecentTrendSummary(samples, 10);
+      lines.push(`📊 ${trend}`);
+    }
+  }
+
+  // For fully configured but low hit models, emphasize sticky routing
+  if (!hasMissingCompat && !hasRouterRisk && todayStats.totalRequests > 3 && todayHitRatio < 30) {
+    lines.push("💡 Compat is configured but cache hit rate remains low.");
+    lines.push("   Possible causes:");
+    lines.push("   • Proxy still routes to multiple backends — check session affinity on the proxy side.");
+    lines.push("   • Prompt prefix varies per turn — check dynamic context in system prompt.");
+    lines.push("   • Provider does not return cache usage fields — footer can't measure hits.");
+  }
+
+  return lines;
+}
+
 function buildCompatDiagnosis(model: PiModel): string | undefined {
   const missing = describeMissingOpenAICompatibleProxyCompat(model);
   const routerNotes = describeRouterChannelDiagnostics(model);
@@ -3042,6 +3468,26 @@ export const __internals_for_tests = {
   emptyAllCacheStats,
   parseCacheStats,
   parsePersistedCacheStats,
+  // Recent sample / stats output / diagnosis helpers
+  MAX_RECENT_SAMPLES,
+  buildStatsOutput,
+  buildLowHitDiagnosis,
+  formatRecentTrendSummary,
+  formatHitRatio,
+  formatTokenM,
+  hasMissingUsageFields,
+  keyForModelExt,
+  // Session-scoped helpers
+  hashSessionId,
+  makeSessionModelKey,
+  modelKeyFromSessionKey,
+  // Persistence helpers (for reload/reset tests)
+  mergeCacheSessions,
+  writePersistedCacheStats,
+  readPersistedCacheStats,
+  STATE_FILE_PATH,
+  LEGACY_STATE_FILE_PATH,
+  STATE_DIR,
 };
 
 export default function (pi: ExtensionAPI) {
@@ -3052,8 +3498,57 @@ export default function (pi: ExtensionAPI) {
   let persistenceWarningShown = false;
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
   let integrityNotificationShown = false;
+  let currentSessionId = "";
+  let currentSessionHash = "";
+  let currentSessionHashSet = false;
   const PERSIST_DEBOUNCE_MS = 2000;
+  /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
+  const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
+
+  /**
+   * Build a session-scoped stats key from the current session hash + model key.
+   * Returns `${sessionHash}:${provider}/${id}`.
+   */
+  function sessionModelKey(model: { provider: string; id: string }): string {
+    const hash = currentSessionHash || "_nosession";
+    return `${hash}:${model.provider}/${model.id}`;
+  }
 
+  /**
+   * Extract the user-facing model key from a session-scoped key.
+   * "abc123:otokapi/gpt-5.5" → "otokapi/gpt-5.5"
+   */
+  function modelKeyFromSessionScoped(sKey: string): string {
+    const idx = sKey.indexOf(":");
+    return idx >= 0 ? sKey.slice(idx + 1) : sKey;
+  }
+
+  function recordRecentSample(modelKeyStr: string, usage: UsageSnapshot, missingUsageFields: boolean): void {
+    let samples = recentSamplesByModelKey.get(modelKeyStr);
+    if (!samples) {
+      samples = [];
+      recentSamplesByModelKey.set(modelKeyStr, samples);
+    }
+    samples.push({
+      timestamp: Date.now(),
+      hit: usage.cacheRead > 0,
+      cachedInputTokens: usage.cacheRead,
+      cacheWriteInputTokens: usage.cacheWrite,
+      totalInputTokens: usage.totalInput,
+      missingUsageFields,
+    });
+    if (samples.length > MAX_RECENT_SAMPLES) {
+      samples.splice(0, samples.length - MAX_RECENT_SAMPLES);
+    }
+  }
+
+  function getRecentSamples(modelKeyStr: string): CacheUsageSample[] {
+    return recentSamplesByModelKey.get(modelKeyStr) ?? [];
+  }
+
+  function clearRecentSamples(): void {
+    recentSamplesByModelKey.clear();
+  }
 
   function getCacheStatsState(): CacheStatsState {
     return { statsByModel: cacheStatsByModel, legacyFamily: cacheStatsLegacyFamily };
@@ -3062,7 +3557,7 @@ export default function (pi: ExtensionAPI) {
   /** Look up active stats for a model, falling back to legacy family. */
   function getStatsForModel(model: PiModel | undefined, adapter: CacheProviderAdapter): CacheStats {
     if (model) {
-      const key = modelKey(model);
+      const key = sessionModelKey(model);
       const existing = cacheStatsByModel[key];
       if (existing) return existing;
     }
@@ -3089,7 +3584,7 @@ export default function (pi: ExtensionAPI) {
 
   async function persistCacheStats(ctx?: ExtensionContext): Promise<void> {
     try {
-      await writePersistedCacheStats(getCacheStatsState());
+      await writePersistedCacheStats(getCacheStatsState(), currentSessionHashSet ? currentSessionHash : undefined);
     } catch (error) {
       console.warn(`${LOG_PREFIX}: failed to persist cache stats`, error);
       if (!persistenceWarningShown) {
@@ -3155,19 +3650,80 @@ export default function (pi: ExtensionAPI) {
   }
 
   async function restoreCacheStats(reason: string, ctx: ExtensionContext): Promise<void> {
+    // Set session id on first load and on reload (same session).
+    const sid = ctx.sessionManager.getSessionId();
+    if (sid && (sid !== currentSessionId || !currentSessionHashSet)) {
+      currentSessionId = sid;
+      currentSessionHash = hashSessionId(sid);
+      currentSessionHashSet = true;
+    }
+
     if (reason === "reload") {
-      cacheStatsByModel = {};
-      cacheStatsLegacyFamily = emptyAllCacheStats();
+      // /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;
-      // Reset integrity diagnostics on reload
       lastPromptIntegrityWarningAt = 0;
       integrityNotificationShown = false;
-      await flushPersistCacheStats(ctx);
+      clearRecentSamples();
+
+      const persisted = await readPersistedCacheStats();
+      if (persisted && currentSessionHash) {
+        const prefix = `${currentSessionHash}:`;
+        const filteredModelStats: Record<string, CacheStats> = {};
+        for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
+          if (fullKey.startsWith(prefix)) {
+            // Current session's data
+            filteredModelStats[fullKey] = stats;
+          } else if (!fullKey.includes(":")) {
+            // Legacy v3-style key without session hash — migrate to current session
+            filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
+          } else if (fullKey.startsWith("_nosession:")) {
+            // _nosession migration remnant from old-path v4 write — migrate to current session
+            filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
+          }
+        }
+        cacheStatsByModel = filteredModelStats;
+        cacheStatsLegacyFamily = persisted.legacyFamily;
+      } else if (persisted) {
+        cacheStatsByModel = persisted.statsByModel;
+        cacheStatsLegacyFamily = persisted.legacyFamily;
+      } else {
+        cacheStatsByModel = {};
+        cacheStatsLegacyFamily = emptyAllCacheStats();
+      }
+
+      await rollOverStatsIfNeeded(ctx);
       return;
     }
 
+    // First load / process start: read persisted stats and filter for
+    // this session's entries. If the session has no persisted data yet,
+    // start fresh.
     const persisted = await readPersistedCacheStats();
-    if (persisted) {
+    if (persisted && currentSessionHash) {
+      const prefix = `${currentSessionHash}:`;
+      const filteredModelStats: Record<string, CacheStats> = {};
+      for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
+        if (fullKey.startsWith(prefix)) {
+          // Current session's data — load it.
+          filteredModelStats[fullKey] = stats;
+        } else if (!fullKey.includes(":")) {
+          // Legacy v3-style key without session hash (e.g. "otokapi/gpt-5.5").
+          // Migrate to current session by prefixing with the session hash.
+          filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
+        } else if (fullKey.startsWith("_nosession:")) {
+          // _nosession migration remnant from old-path v4 write — migrate to current session
+          filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
+        }
+        // Other sessions' entries are preserved in the file but not loaded
+        // into memory; they'll be rewritten on next persist.
+      }
+      cacheStatsByModel = filteredModelStats;
+      cacheStatsLegacyFamily = persisted.legacyFamily;
+    } else if (persisted) {
+      // Persisted data exists but no session hash set yet.
+      // This shouldn't normally happen — use the data as-is.
       cacheStatsByModel = persisted.statsByModel;
       cacheStatsLegacyFamily = persisted.legacyFamily;
     } else {
@@ -3184,13 +3740,11 @@ export default function (pi: ExtensionAPI) {
     const adapter = selectAdapterForModel(model);
     let statusText: string | undefined;
     if (adapter) {
-      // Display only per-model scoped stats. A model that has never been
-      // used in this session shows 0/0 rather than falling back to legacy
-      // family aggregated stats (which could span different providers with
-      // the same model-family name). The message_end hook populates
-      // cacheStatsByModel[key] on first use with that model.
-      const key = model ? modelKey(model) : undefined;
-      const stats = key ? cacheStatsByModel[key] : undefined;
+      // Display session-scoped stats. A model that has never been used
+      // in this session shows 0/0. The message_end hook populates
+      // cacheStatsByModel[sessionModelKey(model)] on first use.
+      const sk = model ? sessionModelKey(model) : undefined;
+      const stats = sk ? cacheStatsByModel[sk] : undefined;
       statusText = formatCacheStats(adapter, stats ?? emptyCacheStats());
     }
 
@@ -3345,15 +3899,25 @@ export default function (pi: ExtensionAPI) {
     if (!adapter) return;
 
     const usage = adapter.normalizeUsage(event.message);
+
+    // Record recent sample (even when usage is missing, for trend diagnosis)
+    if (ctx.model) {
+      const sk = sessionModelKey(ctx.model);
+      const missingFields = usage === undefined || (usage.cacheRead === 0 && usage.cacheWrite === 0 && usage.totalInput === 0)
+        ? true
+        : hasMissingUsageFields(event.message, adapter);
+      recordRecentSample(sk, usage ?? { cacheRead: 0, cacheWrite: 0, totalInput: 0 }, missingFields);
+    }
+
     if (!usage) return;
 
     await rollOverStatsIfNeeded(ctx);
 
-    // Update stats scoped to the active model (provider/id key).
+    // Update stats scoped to current session + active model.
     // Falls back to legacy family when ctx.model is undefined.
     if (ctx.model) {
-      const key = modelKey(ctx.model);
-      addUsageToCacheStats(getOrCreateStatsByModelKey(key), usage);
+      const sk = sessionModelKey(ctx.model);
+      addUsageToCacheStats(getOrCreateStatsByModelKey(sk), usage);
     } else {
       addUsageToCacheStats(getStatsForModel(undefined, adapter), usage);
     }
@@ -3366,8 +3930,11 @@ export default function (pi: ExtensionAPI) {
   // Register /cache-optimizer command
   // Subcommands:
   //   doctor  — show current model/provider/api/baseUrl/compat status
+  //             with low-hit diagnosis
+  //   stats   — show active model stats bucket, recent trend, usage
   //   compat  — show compat suggestion with file path
-  //   (no args) — show help summary + current diagnosis
+  //   reset   — reset current session model stats bucket (local only)
+  //   (no args) — interactive menu (with UI) or help summary
   // ────────────────────────────────────────────────────────────────
   pi.registerCommand("cache-optimizer", {
     description: "Diagnose Pi cache configuration",
@@ -3380,7 +3947,27 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+        const diagnosis = buildDoctorDiagnosis(model);
+        const adapter = selectAdapterForModel(model);
+        const sk = model ? sessionModelKey(model) : undefined;
+        const statsState = sk ? cacheStatsByModel[sk] : undefined;
+        const samples = sk ? getRecentSamples(sk) : [];
+        const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
+        const fullDiagnosis = lowHitLines.length > 0
+          ? diagnosis + "\n" + lowHitLines.join("\n")
+          : 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 adapter = selectAdapterForModel(model);
+        const sk = model ? sessionModelKey(model) : undefined;
+        const statsState = sk ? cacheStatsByModel[sk] : undefined;
+        const samples = sk ? getRecentSamples(sk) : [];
+        const output = buildStatsOutput(model, adapter, statsState, samples);
+        cmdCtx.ui.notify(output, "info");
       } else if (subcommand === "compat") {
         if (!model) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
@@ -3397,12 +3984,46 @@ export default function (pi: ExtensionAPI) {
             "info",
           );
         }
+      } else if (subcommand === "reset") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        const adapter = selectAdapterForModel(model);
+        if (!adapter) {
+          cmdCtx.ui.notify("ℹ️ Active model does not match a cache adapter. No stats to reset.", "info");
+          return;
+        }
+
+        const sk = sessionModelKey(model);
+        const displayKey = modelKey(model);
+
+        // Reset session-scoped stats for the active model.
+        delete cacheStatsByModel[sk];
+
+        // Clear recent samples for this session+model key.
+        recentSamplesByModelKey.delete(sk);
+
+        // Persist immediately.
+        await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
+
+        // Update footer to show 0/0.
+        await publishStatus(cmdCtx as unknown as ExtensionContext, model);
+
+        cmdCtx.ui.notify(
+          `✅ Reset local session cache stats for "${displayKey}". ` +
+          "Upstream provider prompt cache was not modified. " +
+          "New requests will start a fresh stats bucket for this Pi session.",
+          "info",
+        );
       } else {
         // Try interactive selection menu when UI supports it
         if (cmdCtx.hasUI) {
           const menuOptions = [
             "🩺 Doctor — Show current model cache configuration",
+            "📊 Stats — Show active model stats bucket and trend",
             "⚙️  Compat — Show compat suggestion with edit instructions",
+            "🔄 Reset — Reset local session stats for current model",
             "❌ Cancel",
           ];
           const choice = await cmdCtx.ui.select("Cache Optimizer", menuOptions);
@@ -3410,9 +4031,29 @@ export default function (pi: ExtensionAPI) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
-              cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+              const diagnosis = buildDoctorDiagnosis(model);
+              const adapter = selectAdapterForModel(model);
+              const sk = model ? sessionModelKey(model) : undefined;
+              const statsState = sk ? cacheStatsByModel[sk] : undefined;
+              const samples = sk ? getRecentSamples(sk) : [];
+              const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
+              const fullDiagnosis = lowHitLines.length > 0
+                ? diagnosis + "\n" + lowHitLines.join("\n")
+                : diagnosis;
+              cmdCtx.ui.notify(fullDiagnosis, "info");
             }
           } else if (choice === menuOptions[1]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              const adapter = selectAdapterForModel(model);
+              const sk = model ? sessionModelKey(model) : undefined;
+              const statsState = sk ? cacheStatsByModel[sk] : undefined;
+              const samples = sk ? getRecentSamples(sk) : [];
+              const output = buildStatsOutput(model, adapter, statsState, samples);
+              cmdCtx.ui.notify(output, "info");
+            }
+          } else if (choice === menuOptions[2]) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
@@ -3428,6 +4069,27 @@ export default function (pi: ExtensionAPI) {
                 );
               }
             }
+          } else if (choice === menuOptions[3]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              const adapter = selectAdapterForModel(model);
+              if (!adapter) {
+                cmdCtx.ui.notify("ℹ️ Active model does not match a cache adapter. No stats to reset.", "info");
+              } else {
+                const sk = sessionModelKey(model);
+                const displayKey = modelKey(model);
+                delete cacheStatsByModel[sk];
+                recentSamplesByModelKey.delete(sk);
+                await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
+                await publishStatus(cmdCtx as unknown as ExtensionContext, model);
+                cmdCtx.ui.notify(
+                  `✅ Reset local session cache stats for "${displayKey}". ` +
+                  "Upstream provider prompt cache was not modified.",
+                  "info",
+                );
+              }
+            }
           }
           // choice === "cancel" or undefined → no action
           return;
@@ -3436,18 +4098,21 @@ export default function (pi: ExtensionAPI) {
         // Fallback: text help when no interactive UI
         const diagnosis: string[] = [];
         diagnosis.push("📋 /cache-optimizer commands:");
-        diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat status");
+        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("  compat  — Show compat suggestion with edit location");
+        diagnosis.push("  reset   — Reset local session stats for current model (does not affect upstream)");
         diagnosis.push("");
         if (model) {
+          const displayKey = modelKey(model);
           const missing = describeMissingOpenAICompatibleProxyCompat(model);
           if (missing.length > 0) {
-            diagnosis.push(`⚠️  Active model "${modelKey(model)}" missing compat: ${missing.join(", ")}`);
+            diagnosis.push(`⚠️  Active model "${displayKey}" missing compat: ${missing.join(", ")}`);
             diagnosis.push('Run "/cache-optimizer compat" for edit instructions.');
           } else if (isCompatCheckApplicable(model)) {
-            diagnosis.push(`✅ Active model "${modelKey(model)}": compat fully configured.`);
+            diagnosis.push(`✅ Active model "${displayKey}": compat fully configured.`);
           } else {
-            diagnosis.push(`ℹ️ Active model "${modelKey(model)}": compat check not applicable.`);
+            diagnosis.push(`ℹ️ Active model "${displayKey}": compat check not applicable.`);
           }
         } else {
           diagnosis.push("No active model selected.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.4.8",
+  "version": "2.5.0",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",