fix(billing): 缓存命中统计缺失 + Billing 页空白 + 侧栏图标

三个问题都来自生产实测，不是代码审阅。

## 1. 缓存命中被计费却不被统计
网关确实从上游 usage 提取了 prompt_cache_hit_tokens（审计里能看到
cache_hit_tokens: 270104 / cache_reported: true，占 prompt 的 99.9%），
costFor() 也用它给缓存段定价了 —— 但**没有任何 bucket 记录它**。
结果：一个 99.88% 命中率的网关，报表显示 prompt_tokens 却看不出其中
多少是缓存读，也无从按源/模型/key 看命中率。

每个 bucket 现在多三个字段：
  cache_hit_tokens    命中数（按上游上报）
  cache_fresh_tokens  未命中的 prompt
  cache_reported_reqs 上游确实上报了缓存数的请求数

第三个字段是刻意的：**「零命中」与「上游根本不上报」在命中总量里完全一样**，
而它们在「缓存折扣有没有生效」这个问题上含义相反。没有它就无法区分，
只能猜。

chat.go 的 payload 之前**没有** cache_reported（审计有、插件没有），
所以任何插件侧的缓存统计都只能猜 —— 已补上。

旧 state 文件的 bucket 没有这些字段：Lua 里 nil + number 会抛错，而钩子抛错
会让**该请求完全不记账**（一个统计缺口会变成静默缺口）。add() 里做了回填。

UI 增加 fresh/cache/cache% 三列 + Cache hit rate KPI；未上报的显示 n/r 而不是 0%。

## 2. Billing 页空白：render() 引用了未定义的 s
`render(st)` 里两处 KPI 写成 `s.degraded_reqs`，ReferenceError 让整个渲染
中断，所有表格停在初始的空 innerHTML。症状是「页面加载了但什么都没有」，
而 /api/plugins/billing/state 返回 200 且有真实数据 —— 载荷完全正确，
DOM 是空的。

更糟的是 refresh() 里的 `catch (e) { /* never break the page */ }` 把错误
**静默吞掉**了：网络面板一切正常，页面什么都没有。现在 catch 会
console.error（仍然不抛，装饰性组件不该拖垮宿主页，但必须留痕）。

## 3. 侧栏图标
billing 声明 icon = "💰"，而原生 tab 全是内联 SVG（stroke: currentColor）。
emoji 尺寸不对、不跟随主题。

WebUI 增加 pluginIconHTML：插件图标可以是文本，也可以是内联 SVG。
**SVG 走严格白名单**（tag + 属性都是 allowlist，不是 denylist）——
插件是在运维者浏览器里跑的第三方代码，不能"信任插件"；但也不能直接拒绝
SVG，因为那是唯一能和原生 tab 视觉一致的方式。

用真实 Chromium 验证 12 个用例，全部挡住，包括 foreignObject 里嵌 HTML
命名空间 <img onerror> 这个经典绕过（整体丢弃，所以 img/onerror 也没了）。
★ node 里没有 DOMParser/jsdom，所以没法在单测里跑这个过滤器 —— 用正则近似
会得到一个"测试通过但浏览器里失效"的过滤器，这比没有测试更糟。

顺带修了过滤器的两个真缺陷：输出里嵌套了空 `<svg></svg>`，且 viewBox
是从包装元素读的（永远是 null）而不是插件自己的，所以任何自定义 viewBox
的图标都会丢失。

## 判据（新增 7 项，全部变异验证）
写「注入脚本能否正常执行」这个守卫时我错了四次：
  1. 静态扫「已声明的名字」→ 把 HTML 字符串里的 CSS 类名（class/div/td）
     全报成未定义
  2. 用 CSS 选择器解析器查样式表 → 报样式表本身坏了
  3. 只挂 process 的 uncaughtException → 脚本在 IIFE 里异步跑，错误是
     unhandledRejection，判据对原 bug 全绿
  4. 只查「有没有抛错」→ render() 开头是 `if (!st) return`，传错字段是
     **静默 no-op**：不抛、不打日志、不报错，只是页面空白
最终判据是：在 node 里用 DOM stub 真跑一遍，同时要求「无异常」且
「至少写进一个容器」，并监听 console.error。变异验证：还原 s → 红；
render 收到 undefined 字段 → 红。

表头/行列数一致性也有守卫：row() 加了缓存列而表头没加时，表格会整体错位
（cache% 落到 completion 列下）—— 渲染正常、有数据、但要仔细看才发现。

## 生产验证
重启后价目表与累计账完整保留（1.17 亿 prompt tokens）。
新请求缓存统计生效：cache_hit 947,436 / cache_fresh 888，
cache_reported_reqs 7 / 395（其余来自旧 state，正是该字段存在的意义）。
真实浏览器：表格 3 行、KPI 7 项、表头 name/cost/reqs/prompt/fresh/cache/cache%/completion、
SVG 图标 currentColor 渲染、控制台无 billing 错误。391 个测试全绿。

## 另发现一个无关 bug（未修）
首页 stats 图表抛 IndexSizeError: arc 半径为负（-2），在 ui/index.html 的
paintStats 附近。属状态页图表，不在本次范围。

internal/gateway/chat.go

@@ -1020,9 +1020,17 @@ func (g *Gateway) fireEnd(rec *Req) {
 		"completion_tokens": rec.Compl,
 		"cache_hit_tokens":  rec.CacheHit,
 		"cache_miss_tokens": rec.CacheMiss,
-		"image_count":       rec.ImageCount,
+		// Whether UPSTREAM reported a cache number at all. A plugin cannot
-		"error":             rec.Err,
+		// infer this from cache_hit_tokens alone: zero hits because nothing was
-		"time":              rec.Time,
+		// cached and zero hits because the provider never reports caching are
+		// the same value, and they mean opposite things when you are checking
+		// whether a cache discount is doing anything. The audit record already
+		// carried this (rec.CacheReported); the plugin payload did not, so any
+		// plugin-level cache accounting had to guess.
+		"cache_reported": rec.CacheReported,
+		"image_count":    rec.ImageCount,
+		"error":          rec.Err,
+		"time":           rec.Time,
 		// chain_walk: the AUTO tier-by-tier trace, when the request went
 		// through the chain. Empty for a direct request and for a gateway with
 		// no plugins loaded. Absent rather than empty so a plugin can tell

internal/gateway/ui/index.html

@@ -5119,6 +5119,95 @@
         },
       };
 
+      // pluginIconHTML renders a plugin-declared sidebar icon.
+      //
+      // Text icons are escaped as before. An icon that looks like markup is
+      // accepted ONLY as a sanitized inline <svg>: a fixed tag allowlist, no
+      // <script>, no event handlers, no external references. Plugins are
+      // third-party code running in the operator's browser, so "trust the
+      // plugin" is not a posture this can take — but neither can it refuse SVG
+      // outright, because that is the only way an icon matches the native tabs.
+      function pluginIconHTML(icon) {
+        var raw = icon == null ? "" : String(icon);
+        if (!raw) return '<span style="font-size:18px;line-height:1">\u2022</span>';
+        if (!/<[a-zA-Z!/]/.test(raw)) {
+          // Plain text (an emoji or a glyph).
+          return '<span style="font-size:18px;line-height:1">' + esc(raw) + "</span>";
+        }
+        var cleaned = sanitizePluginSVG(raw);
+        if (!cleaned) {
+          // Markup that is not an acceptable SVG: fall back to a neutral dot
+          // rather than injecting it or showing raw tags.
+          return '<span style="font-size:18px:line-height:1">\u2022</span>';
+        }
+        return (
+          '<span style="font-size:18px;line-height:1;display:inline-flex">' +
+          cleaned +
+          "</span>"
+        );
+      }
+
+      // sanitizePluginSVG keeps only what an icon needs.
+      //
+      // Allowlist, not a denylist: anything not named here is dropped, so a new
+      // dangerous construct cannot slip through by default. Attributes are
+      // limited to geometry and paint (no href/src, no on*, no style with url()).
+      var SVG_OK_TAGS = { svg: 1, path: 1, circle: 1, rect: 1, line: 1, polyline: 1, polygon: 1, g: 1 };
+      var SVG_OK_ATTRS = {
+        viewBox: 1, fill: 1, stroke: 1, "stroke-width": 1, "stroke-linecap": 1,
+        "stroke-linejoin": 1, d: 1, cx: 1, cy: 1, r: 1, x: 1, y: 1, rx: 1, ry: 1,
+        x1: 1, y1: 1, x2: 1, y2: 1, points: 1, width: 1, height: 1, opacity: 1,
+      };
+      function sanitizePluginSVG(raw) {
+        var doc = new DOMParser().parseFromString("<svg>" + raw + "</svg>", "image/svg+xml");
+        var svg = doc.documentElement;
+        if (!svg || svg.nodeName.toLowerCase() !== "svg" || doc.querySelector("parsererror")) {
+          return "";
+        }
+        // The wrapper we build is the only <svg> we emit. A plugin's own <svg>
+        // is unwrapped, otherwise the output nests an empty <svg></svg> inside
+        // ours — visible in the markup, and it also meant the viewBox was read
+        // from the WRAPPER (which never has one) rather than from the plugin's,
+        // so any icon declaring a non-default viewBox silently lost it.
+        var kept = [];
+        (function walk(node, depth) {
+          if (depth > 4) return;
+          for (var i = 0; i < node.children.length; i++) {
+            var el = node.children[i];
+            var name = el.nodeName.toLowerCase();
+            if (name === "svg") {
+              walk(el, depth + 1); // unwrap, do not emit
+              continue;
+            }
+            if (!SVG_OK_TAGS[name]) continue;
+            var attrs = "";
+            for (var a = 0; a < el.attributes.length; a++) {
+              var at = el.attributes[a];
+              var an = at.name.toLowerCase();
+              // Reject anything that can fetch or execute, whatever it is called.
+              if (/^on/.test(an) || /href|src|xlink|formaction|style/.test(an)) continue;
+              if (!SVG_OK_ATTRS[an]) continue;
+              var val = String(at.value).replace(/[<>"'&]/g, "");
+              attrs += " " + an + '="' + val + '"';
+            }
+            kept.push("<" + name + attrs + "></" + name + ">");
+            walk(el, depth + 1);
+          }
+        })(svg, 0);
+        if (!kept.length) return "";
+        // Prefer the plugin's own viewBox; fall back to the 24px grid every
+        // native icon uses.
+        var innerSvg = svg.querySelector("svg");
+        var vb = (innerSvg && innerSvg.getAttribute("viewBox")) || svg.getAttribute("viewBox") || "0 0 24 24";
+        return (
+          '<svg viewBox="' + vb.replace(/[^\d\s.\-]/g, "") + '" fill="none" ' +
+          'stroke="currentColor" stroke-width="2" stroke-linecap="round" ' +
+          'stroke-linejoin="round" style="width:18px;height:18px">' +
+          kept.join("") +
+          "</svg>"
+        );
+      }
+
       // remountPluginElements re-attaches plugin elements after a host page
       // rebuilt its DOM. Safe to call at any time: each mount is a no-op when
       // the wrapper is already present in the current build of the pane, so a
@@ -5173,10 +5262,16 @@
             btn.className = "sb-i";
             btn.dataset.tab = id;
             btn.title = ui.page.title || id;
-            btn.innerHTML =
+            // A plugin icon may be plain text (an emoji, a glyph) or an inline
-              '<span style="font-size:18px;line-height:1">' +
+            // SVG snippet. Native tabs use inline SVG styled with
-              esc(ui.page.icon || "•") +
+            // `stroke: currentColor`, so an emoji next to them renders at the
-              "</span>";
+            // wrong size and ignores the theme — that is what "the icon looks
+            // wrong" meant.
+            //
+            // The SVG form is allowed through RAW, which is only safe because
+            // it is strictly filtered: see pluginIconHTML. Escaping it (as this
+            // did) would print the markup as text instead.
+            btn.innerHTML = pluginIconHTML(ui.page.icon);
             btn.onclick = () => goTab(id);
             nav.appendChild(btn);
             PLUGIN_PAGES.add(id);

internal/lua/billing_test.go

@@ -676,3 +676,118 @@ func TestBillingPeakDoesNotDoubleCacheRead(t *testing.T) {
 	got := stateOf(t, ps)["total"].(map[string]interface{})["cost"].(float64)
 	approx(t, "cache-only cost (not doubled)", got, 1e6*1.5e-7*0.02)
 }
+
+// TestBillingTracksCacheUsage is the guard for the gap production exposed: the
+// gateway had prompt_cache_hit_tokens and costFor() priced the cache leg, but no
+// bucket recorded the number. On a gateway where 99.88% of prompt tokens were
+// cache reads, the report showed a prompt_tokens figure with no way to tell that
+// most of it was cached.
+func TestBillingTracksCacheUsage(t *testing.T) {
+	ps, _ := billingVM(t)
+
+	ps.Fire(StageRequestEnd, map[string]interface{}{
+		"model": "m", "source": "s", "key": "k", "ok": true,
+		"prompt_tokens": 1000, "completion_tokens": 50,
+		"cache_hit_tokens": 900, "cache_reported": true,
+	})
+	// A second request from a source that does not report caching at all.
+	ps.Fire(StageRequestEnd, map[string]interface{}{
+		"model": "m2", "source": "s2", "ok": true,
+		"prompt_tokens": 100, "completion_tokens": 10,
+	})
+
+	st := ps.State("billing").(map[string]interface{})
+	total := st["total"].(map[string]interface{})
+	if total["cache_hit_tokens"] != float64(900) {
+		t.Errorf("total.cache_hit_tokens = %v, want 900", total["cache_hit_tokens"])
+	}
+	if total["cache_fresh_tokens"] != float64(200) {
+		t.Errorf("total.cache_fresh_tokens = %v, want 200 (1000-900 + 100)", total["cache_fresh_tokens"])
+	}
+	// Only the first request reported a cache number.
+	if total["cache_reported_reqs"] != float64(1) {
+		t.Errorf("★ total.cache_reported_reqs = %v, want 1 — a source that never "+
+			"reports cache usage must be distinguishable from one reporting zero hits",
+			total["cache_reported_reqs"])
+	}
+
+	// Per-source separation.
+	bySrc := st["by_source"].(map[string]interface{})
+	s1 := bySrc["s"].(map[string]interface{})
+	if s1["cache_hit_tokens"] != float64(900) {
+		t.Errorf("by_source[s].cache_hit_tokens = %v, want 900", s1["cache_hit_tokens"])
+	}
+	s2 := bySrc["s2"].(map[string]interface{})
+	if s2["cache_reported_reqs"] != float64(0) {
+		t.Errorf("by_source[s2].cache_reported_reqs = %v, want 0", s2["cache_reported_reqs"])
+	}
+	if s2["cache_fresh_tokens"] != float64(100) {
+		t.Errorf("by_source[s2].cache_fresh_tokens = %v, want 100", s2["cache_fresh_tokens"])
+	}
+}
+
+// TestBillingCacheBucketsSurviveOlderStateFiles: a state file written before these
+// fields existed must not crash the hook. `nil + number` is an error in Lua, and
+// a hook that throws stops accounting for that request entirely — which is how a
+// billing gap turns into a silent one.
+func TestBillingCacheBucketsSurviveOlderStateFiles(t *testing.T) {
+	ps, _ := billingVM(t)
+	// Simulate a state restored from an older build: buckets without the new keys.
+	legacy := map[string]interface{}{
+		"total": map[string]interface{}{
+			"cost": 1.0, "requests": float64(5), "prompt_tokens": float64(500),
+			"completion_tokens": float64(50), "failures": float64(0),
+		},
+		"by_source": map[string]interface{}{
+			"legacy": map[string]interface{}{"cost": float64(0), "requests": float64(5),
+				"prompt_tokens": float64(500), "completion_tokens": float64(50), "failures": float64(0)},
+		},
+		"by_model": map[string]interface{}{}, "by_key": map[string]interface{}{},
+		"by_day": map[string]interface{}{}, "started": float64(0),
+	}
+	if err := ps.SetState("billing", legacy); err != nil {
+		t.Fatalf("SetState: %v", err)
+	}
+	ps.Fire(StageRequestEnd, map[string]interface{}{
+		"model": "m", "source": "legacy", "ok": true,
+		"prompt_tokens": 100, "completion_tokens": 10,
+		"cache_hit_tokens": 60, "cache_reported": true,
+	})
+	if len(ps.HookErrors()) != 0 {
+		t.Fatalf("hook error on a legacy state: %v", ps.HookErrors())
+	}
+	st := ps.State("billing").(map[string]interface{})
+	tot := st["total"].(map[string]interface{})
+	if tot["requests"] != float64(6) {
+		t.Errorf("requests = %v, want 6 (5 legacy + 1 new)", tot["requests"])
+	}
+	if tot["cache_hit_tokens"] != float64(60) {
+		t.Errorf("cache_hit_tokens = %v, want 60", tot["cache_hit_tokens"])
+	}
+	lg := st["by_source"].(map[string]interface{})["legacy"].(map[string]interface{})
+	if lg["cache_hit_tokens"] != float64(60) {
+		t.Errorf("legacy bucket cache_hit_tokens = %v, want 60", lg["cache_hit_tokens"])
+	}
+}
+
+// TestBillingCacheHitClampedInStats: costFor clamps the cache leg, so the
+// recorded numbers must be clamped the same way. A provider that reports more
+// cache hits than prompt tokens must not produce negative fresh tokens.
+func TestBillingCacheHitClampedInStats(t *testing.T) {
+	ps, _ := billingVM(t)
+	ps.Fire(StageRequestEnd, map[string]interface{}{
+		"model": "m", "source": "s", "ok": true,
+		"prompt_tokens": 100, "completion_tokens": 5,
+		"cache_hit_tokens": 5000, "cache_reported": true,
+	})
+	st := ps.State("billing").(map[string]interface{})
+	tot := st["total"].(map[string]interface{})
+	if tot["cache_hit_tokens"] != float64(100) {
+		t.Errorf("★ cache_hit_tokens = %v, want 100 (clamped to prompt_tokens)",
+			tot["cache_hit_tokens"])
+	}
+	if tot["cache_fresh_tokens"] != float64(0) {
+		t.Errorf("★ cache_fresh_tokens = %v, want 0, never negative",
+			tot["cache_fresh_tokens"])
+	}
+}

internal/lua/billing_ui_test.go

@@ -0,0 +1,329 @@
+package lua
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// The billing page rendered EMPTY in production while its data endpoint returned
+// 200 with real numbers. The cause was one line: render(st) referenced an
+// undefined `s` for two KPI cells, so the ReferenceError aborted the whole
+// render and every table stayed at its initial empty innerHTML.
+//
+// Nothing in the build, the tests or the API surfaced it. This file is the guard
+// for the whole class: a plugin's injected UI that references an undefined name,
+// or that depends on a container the page does not provide, fails silently.
+
+// billingUI returns the injected markup for the billing plugin: the full page
+// mount and the status-page element mount.
+func billingUI(t *testing.T) (page string, statusElement string) {
+	t.Helper()
+	src, err := os.ReadFile("plugins/billing.lua")
+	if err != nil {
+		t.Fatalf("read billing.lua: %v", err)
+	}
+	// Located BY CONTENT, not by index. The plugin also uses a long string for
+	// its inline SVG icon, so "the first long string" is the icon and "the
+	// second" is the page — which is exactly the kind of positional assumption
+	// that breaks the next time an icon or a description is added.
+	page = longStringContaining(t, string(src), "billing-root")
+	statusElement = longStringContaining(t, string(src), "billing-status-tile")
+	return page, statusElement
+}
+
+// longStringContaining returns the [==[ ... ]==] body that contains marker.
+func longStringContaining(t *testing.T, src, marker string) string {
+	t.Helper()
+	re := regexp.MustCompile(`(?s)\[==\[(.*?)\]==\]`)
+	for _, m := range re.FindAllStringSubmatch(src, -1) {
+		if strings.Contains(m[1], marker) {
+			return m[1]
+		}
+	}
+	t.Fatalf("no long string contains %q", marker)
+	return ""
+}
+
+// TestBillingMountScriptExecutes is the guard for the production bug.
+//
+// The Billing page rendered empty while its data endpoint returned 200 with real
+// numbers. Cause: render(st) referenced an undefined `s` for two KPI cells, the
+// ReferenceError aborted the render, and every table kept its initial empty
+// innerHTML. Nothing in the build or the API surfaced it.
+//
+// Two earlier attempts at a static check were both wrong: a "declared names"
+// scan flagged every CSS class inside the inline HTML strings (class, div, td),
+// and a CSS-selector parse of the stylesheet reported the stylesheet itself as
+// broken. Static analysis of JS embedded in HTML strings is the wrong tool.
+//
+// So this actually RUNS the script, in node, against a minimal DOM stub, and
+// fails on any thrown error. Skipped when node is unavailable, with the reason
+// printed — never silently passing as if it had checked.
+func TestBillingMountScriptExecutes(t *testing.T) {
+	page, el := billingUI(t)
+	scripts := extractScripts(page)
+	if len(scripts) == 0 {
+		t.Fatal("no <script> found in the billing page mount")
+	}
+	for i, js := range scripts {
+		assertRendersAndDoesNotThrow(t, i, js)
+	}
+	for i, js := range extractScripts(el) {
+		assertRendersAndDoesNotThrow(t, i, js)
+	}
+}
+
+// assertRendersAndDoesNotThrow executes a mount script under node against a DOM
+// stub and fails on EITHER a thrown/reported error OR an empty render.
+//
+// Checking only for exceptions is not enough, and that is the third wrong
+// attempt at this guard. The plugin's render() opens with `if (!st) return;`,
+// so passing the wrong field (`render(j.stateX)`) is a SILENT no-op: no throw,
+// no console.error, no rejection — just an empty page. Only looking at the
+// produced DOM catches that class.
+func assertRendersAndDoesNotThrow(t *testing.T, idx int, js string) {
+	t.Helper()
+	node, err := exec.LookPath("node")
+	if err != nil {
+		t.Skipf("node not available (%v): cannot execute the injected script", err)
+	}
+
+	stub := `
+global.window = global;
+global.document = {
+  getElementById: function (id) {
+    if (!global.__els) global.__els = {};
+    if (!global.__els[id]) global.__els[id] = {
+      style: {}, dataset: {}, classList: { add: function(){}, remove: function(){} },
+      // Both writes count: the Billing page fills innerHTML, the status-page
+      // tile assigns textContent. Watching only one of them flagged the tile as
+      // "renders nothing" — a false positive that would have taught everyone to
+      // ignore this test.
+      set innerHTML(v) { if (v && String(v).trim()) global.__written.push(id); this.__h = v; },
+      get innerHTML() { return this.__h || ""; },
+      set textContent(v) { if (v !== undefined && String(v).trim()) global.__written.push(id); this.__t = v; },
+      get textContent() { return this.__t || ""; },
+      set innerText(v) { if (v !== undefined && String(v).trim()) global.__written.push(id); this.__i = v; },
+      get innerText() { return this.__i || ""; },
+      appendChild: function(){}, querySelector: function(){ return null; },
+      querySelectorAll: function(){ return []; }, addEventListener: function(){} };
+    return global.__els[id];
+  },
+  createElement: function () { return { style: {}, dataset: {}, appendChild: function(){}, setAttribute: function(){} }; },
+  addEventListener: function () {},
+};
+global.pluginAPI = { onTabShown: function () {} };
+global.fetch = function () {
+  // A payload with real numbers, so a working render produces visible output.
+  return Promise.resolve({ ok: true, json: function () {
+    return Promise.resolve({ plugin: "billing", state: {
+      currency: "USD",
+      total: { cost: 1.25, requests: 7, prompt_tokens: 100, completion_tokens: 20, failures: 0 },
+      by_source: { localzen: { cost: 1.25, requests: 7, prompt_tokens: 100, completion_tokens: 20, failures: 0 } },
+      by_model: { m1: { cost: 1.25, requests: 7, prompt_tokens: 100, completion_tokens: 20, failures: 0 } },
+      by_key: { k1: { cost: 1.25, requests: 7, prompt_tokens: 100, completion_tokens: 20, failures: 0 } },
+      by_day: { "2026-01-01": { cost: 1.25, requests: 7, prompt_tokens: 100, completion_tokens: 20, failures: 0 } },
+      degraded_reqs: 1, unpriced_reqs: 2,
+    }});
+  }});
+};
+global.__written = [];
+global.__errors = [];
+// The plugin's refresh() swallows its own errors so decoration can never break
+// the host page — which is right, and is exactly why the production ReferenceError
+// was invisible. So the trace has to come from console.error, which the plugin now
+// emits. Hooking process events alone made this test pass against the very bug it
+// was written for (verified by re-introducing the typo and watching it stay green).
+var __realErr = console.error;
+console.error = function () {
+  global.__errors.push("console.error: " + Array.prototype.map.call(arguments, function (a) {
+    return (a && a.message) ? a.message : String(a);
+  }).join(" "));
+  __realErr.apply(console, arguments);
+};
+process.on("uncaughtException", function (e) { global.__errors.push("uncaught: " + String(e && e.message || e)); });
+process.on("unhandledRejection", function (e) { global.__errors.push("unhandled: " + String(e && e.message || e)); });
+`
+	// 50ms is not a guess: the plugin's IIFE kicks off refresh() which awaits a
+	// fetch; a rejection lands on the microtask queue almost immediately.
+	script := strings.Join([]string{
+		stub, js,
+		`setTimeout(function(){
+   console.log("__ERRS__" + JSON.stringify({errors: global.__errors, written: global.__written}));
+ }, 300);`,
+	}, "\n")
+	cmd := exec.Command(node, "-e", script)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Errorf("mount script %d crashed under node: %v\n%s", idx, err, out)
+		return
+	}
+	// The script may print other things; find the JSON we appended.
+	line := ""
+	for _, l := range strings.Split(string(out), "\n") {
+		if i := strings.Index(l, "__ERRS__"); i >= 0 {
+			line = strings.TrimSpace(l[i+len("__ERRS__"):])
+		}
+	}
+	if line == "" {
+		t.Errorf("mount script %d produced no error report — the harness did not "+
+			"run to completion, so it cannot be trusted to have checked anything", idx)
+		return
+	}
+	var report struct {
+		Errors  []string `json:"errors"`
+		Written []string `json:"written"`
+	}
+	if err := json.Unmarshal([]byte(line), &report); err != nil {
+		t.Errorf("could not parse the error report %q: %v", line, err)
+		return
+	}
+	for _, e := range report.Errors {
+		t.Errorf("mount script %d reported %q — this is the failure that leaves "+
+			"the Billing page blank while the API still returns data", idx, e)
+	}
+	if len(report.Written) == 0 {
+		t.Errorf("mount script %d wrote NOTHING into any container — the page "+
+			"renders empty. render() guards with `if (!st) return`, so a wrong "+
+			"field name is a silent no-op: no throw, no console output, no error "+
+			"anywhere. This is what the production page looked like.", idx)
+	}
+}
+
+func extractScripts(html string) []string {
+	re := regexp.MustCompile(`(?s)<script[^>]*>(.*?)</script>`)
+	var out []string
+	for _, m := range re.FindAllStringSubmatch(html, -1) {
+		out = append(out, m[1])
+	}
+	return out
+}
+
+// TestBillingPageCoversItsData is the other half: the page declares tables for
+// per-source / per-model / per-key / per-day and must actually render into them.
+// A table id that is never written to is exactly how "the page loads and shows
+// nothing" happens without an error.
+func TestBillingPageCoversItsData(t *testing.T) {
+	page, _ := billingUI(t)
+	for _, id := range []string{
+		"billing-kpis", "billing-by-source", "billing-by-model",
+		"billing-by-key", "billing-by-day",
+	} {
+		if !strings.Contains(page, `id="`+id+`"`) {
+			t.Errorf("the page has no container #%s", id)
+		}
+	}
+	// Every container must be written to by the script, not just declared.
+	scripts := extractScripts(page)
+	all := strings.Join(scripts, "\n")
+	for _, id := range []string{"billing-kpis", "billing-by-source", "billing-by-model", "billing-by-key", "billing-by-day"} {
+		if !strings.Contains(all, `getElementById("`+id+`")`) {
+			t.Errorf("#%s is declared but never read by the script — it stays empty forever", id)
+		}
+	}
+}
+
+// TestPluginIconIsNotARawEmoji guards the sidebar icon. The billing plugin
+// declared icon = "💰" and the WebUI drops that verbatim into the button, while
+// every native tab uses an inline SVG styled with `stroke: currentColor`. An
+// emoji there renders at the wrong size and ignores the theme, so it does not
+// match its neighbours — which is what the operator reported.
+func TestPluginIconIsNotARawEmoji(t *testing.T) {
+	icon := billingIcon(mustBillingSource(t))
+	if icon == "" {
+		t.Fatal("billing declares no icon; the sidebar entry would be blank")
+	}
+	if isEmojiIcon(icon) {
+		t.Errorf("page icon is the raw emoji %q — the WebUI sidebar renders "+
+			"native tabs as inline SVG (stroke: currentColor), so an emoji is the "+
+			"wrong size and ignores the theme. Use an inline SVG path instead.", icon)
+	}
+}
+
+// isEmojiIcon reports whether s is a pictographic emoji rather than markup or a
+// text glyph. Codepoints in the pictographic blocks, plus the regional-indicator
+// pair used by flags.
+func isEmojiIcon(s string) bool {
+	r := []rune(s)
+	if len(r) == 0 {
+		return false
+	}
+	// Anything containing '<' is markup (an inline <svg>), which is the fix.
+	if strings.ContainsRune(s, '<') {
+		return false
+	}
+	for _, c := range r {
+		switch {
+		case c >= 0x1F300 && c <= 0x1FAFF, // pictographs, symbols, supplemental
+			c >= 0x1F000 && c <= 0x1F2FF, // mahjong/domino/cards
+			c >= 0x2600 && c <= 0x27BF,   // misc symbols + dingbats
+			c >= 0x2B00 && c <= 0x2BFF,   // arrows/misc symbols
+			c == 0xFE0F,                  // variation selector-16
+			c >= 0x1F1E6 && c <= 0x1F1FF: // regional indicators (flags)
+			return true
+		}
+	}
+	return false
+}
+
+func mustBillingSource(t *testing.T) string {
+	t.Helper()
+	b, err := os.ReadFile("plugins/billing.lua")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(b)
+}
+
+// billingIcon extracts the declared page icon. It accepts BOTH a quoted string
+// and a [==[ ... ]==] long string, because an inline SVG cannot be written as a
+// Lua short string without escaping every quote in it.
+func billingIcon(src string) string {
+	if m := regexp.MustCompile(`(?m)^\s*icon\s*=\s*"([^"]*)"`).FindStringSubmatch(src); m != nil {
+		return m[1]
+	}
+	if m := regexp.MustCompile(`(?s)\bicon\s*=\s*\[==\[(.*?)\]==\]`).FindStringSubmatch(src); m != nil {
+		return m[1]
+	}
+	return ""
+}
+
+// TestBillingTableHeaderMatchesRowColumns catches column drift.
+//
+// row() gained cache columns (fresh / cache / cache%) while the header row did
+// not, in the same edit. The result is a table whose cells are shifted one
+// column left from "fresh" onward — so "cache%" sits under "completion" and the
+// last cell has no label. It renders, it has data, and it is wrong in a way that
+// takes a careful read to notice.
+func TestBillingTableHeaderMatchesRowColumns(t *testing.T) {
+	page, _ := billingUI(t)
+	js := strings.Join(extractScripts(page), "\n")
+	if !strings.Contains(js, "<th>") {
+		t.Fatal("no table header found in the billing page script")
+	}
+	hStart := strings.Index(js, "function tableFor")
+	if hStart < 0 {
+		t.Fatal("no tableFor in the billing page script")
+	}
+	header := js[hStart:]
+	th := strings.Count(header, "<th>")
+
+	rStart := strings.Index(js, "function row")
+	rEnd := strings.Index(js, "function tableFor")
+	if rStart < 0 || rEnd < 0 || rEnd <= rStart {
+		t.Fatal("could not isolate row()")
+	}
+	row := js[rStart:rEnd]
+	// Each cell closes with </td>; the first cell uses <td><b>..</b></td> so
+	// counting </td> is exact.
+	td := strings.Count(row, "</td>")
+
+	if th != td {
+		t.Errorf("★ header declares %d columns but row() emits %d cells — the "+
+			"table is misaligned from the first differing column on", th, td)
+	}
+}

internal/lua/plugins/billing.lua

@@ -98,8 +98,25 @@ plugin.cache_discount = 0.1
 -- Sorted top-N lists are maintained incrementally rather than re-sorted on
 -- every request: this hook runs once per request on the hot path, so it does
 -- map updates only. The sort happens when state is READ.
+-- CACHE ACCOUNTING (added after production showed the gap):
+-- the gateway extracts prompt_cache_hit_tokens from upstream usage and puts it
+-- in the request_end payload, and costFor() already used it to price the cache
+-- leg — but no bucket recorded it. So a gateway where 99.88% of prompt tokens
+-- were cache reads showed a prompt_tokens number with no indication of that,
+-- and there was no way to see cache hit rate per source/model/key at all.
+--
+-- cache_hit_tokens   hits, as reported by upstream
+-- cache_fresh_tokens prompt tokens that were NOT cache reads
+-- cache_reported_reqs  requests where upstream gave a cache number at all.
+--   Kept separate from a zero: "upstream does not report cache usage" and
+--   "upstream reported zero hits" look identical in a hit total, and they mean
+--   opposite things when you are trying to work out whether a cache discount is
+--   doing anything.
 local function emptyBucket()
-  return { cost = 0, requests = 0, prompt_tokens = 0, completion_tokens = 0, failures = 0 }
+  return {
+    cost = 0, requests = 0, prompt_tokens = 0, completion_tokens = 0, failures = 0,
+    cache_hit_tokens = 0, cache_fresh_tokens = 0, cache_reported_reqs = 0,
+  }
 end
 
 plugin.state = {
@@ -120,12 +137,21 @@ local function bucket(tbl, k)
   return b
 end
 
-local function add(b, cost, prompt, completion, ok)
+local function add(b, cost, prompt, completion, ok, cacheHit, cacheReported)
   b.cost = b.cost + cost
   b.requests = b.requests + 1
   b.prompt_tokens = b.prompt_tokens + prompt
   b.completion_tokens = b.completion_tokens + completion
   if not ok then b.failures = b.failures + 1 end
+  -- Backfill guards a bucket that predates these fields (a state file written
+  -- by an older build, or one restored from disk): nil + number is an error in
+  -- Lua, and a hook that throws stops accounting for that request entirely.
+  if b.cache_hit_tokens == nil then b.cache_hit_tokens = 0 end
+  if b.cache_fresh_tokens == nil then b.cache_fresh_tokens = 0 end
+  if b.cache_reported_reqs == nil then b.cache_reported_reqs = 0 end
+  b.cache_hit_tokens = b.cache_hit_tokens + (cacheHit or 0)
+  b.cache_fresh_tokens = b.cache_fresh_tokens + ((prompt or 0) - (cacheHit or 0))
+  if cacheReported then b.cache_reported_reqs = b.cache_reported_reqs + 1 end
 end
 
 -- ---------- pricing ----------
@@ -393,15 +419,25 @@ function plugin.on_request_end(payload)
   -- once, whereas the walk may contain several skipped tiers.
   if payload.degraded then s.degraded_reqs = s.degraded_reqs + 1 end
 
-  add(s.total, cost, prompt, completion, ok)
+  local cacheHit = tonumber(payload.cache_hit_tokens) or 0
+  if cacheHit < 0 then cacheHit = 0 end
+  if cacheHit > prompt then cacheHit = prompt end
+  -- cache_reported is the gateway's own signal that UPSTREAM gave a cache
+  -- number. Without it a source that never reports cache usage is
+  -- indistinguishable from one that always reports zero hits.
+  local cacheReported = payload.cache_reported and true or false
+  local C = cacheHit
+  local R = cacheReported
+
+  add(s.total, cost, prompt, completion, ok, C, R)
   if payload.source ~= nil and payload.source ~= "" then
-    add(bucket(s.by_source, payload.source), cost, prompt, completion, ok)
+    add(bucket(s.by_source, payload.source), cost, prompt, completion, ok, C, R)
   end
   if payload.model ~= nil and payload.model ~= "" then
-    add(bucket(s.by_model, payload.model), cost, prompt, completion, ok)
+    add(bucket(s.by_model, payload.model), cost, prompt, completion, ok, C, R)
   end
   if payload.key ~= nil and payload.key ~= "" then
-    add(bucket(s.by_key, payload.key), cost, prompt, completion, ok)
+    add(bucket(s.by_key, payload.key), cost, prompt, completion, ok, C, R)
   end
 
   -- Daily rollup, so the dashboard can draw a trend without the browser
@@ -410,7 +446,7 @@ function plugin.on_request_end(payload)
   local ts = payload.time
   if ts ~= nil and ts > 0 then
     if ts > 1000000000000 then ts = ts / 1000 end  -- kernel sends unix MILLIseconds
-    add(bucket(s.by_day, dayKey(ts)), cost, prompt, completion, ok)
+    add(bucket(s.by_day, dayKey(ts)), cost, prompt, completion, ok, C, R)
   end
   return nil  -- last stage: nobody downstream would read a return value
 end
@@ -423,7 +459,7 @@ plugin.ui = {
   page = {
     page_id = "billing",
     title = "Billing",
-    icon = "💰",
+    icon = [==[<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><path d="M14.5 9.5a3 3 0 0 0-2.5-1.3c-1.4 0-2.4.7-2.4 1.8 0 2.6 5.2 1.4 5.2 4 0 1.1-1 1.8-2.5 1.8-1.1 0-2.1-.4-2.7-1.2"/><path d="M12 6.4v11.2"/></svg>]==],
     order = 40,
     mount = [==[
 <div id="billing-root" style="padding:16px">
@@ -464,9 +500,25 @@ plugin.ui = {
       return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
     });
   }
+  // Cache hit rate, with the reporting caveat made visible.
+  //
+  // A bucket whose upstream never reports cache usage would render as "0%" from
+  // a 0/0 and read as "the cache is not working", when the truth is "this
+  // provider does not tell us". "n/r" keeps those apart.
+  function cacheRate(b) {
+    var prompt = b.prompt_tokens || 0;
+    var hit = b.cache_hit_tokens || 0;
+    if (!prompt) return "\u2014";
+    if (!b.cache_reported_reqs) return "n/r";
+    return ((hit / prompt) * 100).toFixed(1) + "%";
+  }
   function row(name, b, cur) {
+    var fresh = (b.cache_fresh_tokens === undefined) ? (b.prompt_tokens || 0) : b.cache_fresh_tokens;
     return "<tr><td><b>" + esc(name) + "</b></td><td>" + money(b.cost, cur) +
       "</td><td>" + (b.requests || 0) + "</td><td>" + (b.prompt_tokens || 0) +
+      "</td><td>" + fresh +
+      "</td><td>" + (b.cache_hit_tokens || 0) +
+      "</td><td>" + esc(cacheRate(b)) +
       "</td><td>" + (b.completion_tokens || 0) + "</td></tr>";
   }
   function tableFor(el, obj, cur, empty) {
@@ -475,7 +527,8 @@ plugin.ui = {
     keys.sort(function (a, b) { return (obj[b].cost || 0) - (obj[a].cost || 0); });
     var h = "<table style='width:100%;border-collapse:collapse;font-size:13px'>" +
       "<tr style='text-align:left;opacity:.65'><th>name</th><th>cost</th><th>reqs</th>" +
-      "<th>prompt</th><th>completion</th></tr>";
+      "<th>prompt</th><th>fresh</th><th>cache</th><th>cache%</th>" +
+      "<th>completion</th></tr>";
     for (var i = 0; i < keys.length; i++) {
       var k = keys[i];
       h += "<tr style='border-top:1px solid rgba(120,90,150,.14)'>" + row(k, obj[k], cur) + "</tr>";
@@ -489,8 +542,8 @@ plugin.ui = {
     document.getElementById("billing-kpis").innerHTML = [
       ["Total", money(t.cost, cur)],
       ["Requests", t.requests || 0],
-      ["Degraded", s.degraded_reqs || 0],
+      ["Degraded", st.degraded_reqs || 0],
-      ["Unpriced", s.unpriced_reqs || 0],
+      ["Unpriced", st.unpriced_reqs || 0],
       ["Prompt tokens", t.prompt_tokens || 0],
       ["Completion tokens", t.completion_tokens || 0],
       ["Failures", t.failures || 0]
@@ -510,7 +563,14 @@ plugin.ui = {
       if (!r.ok) return;
       var j = await r.json();
       render(j.state);
-    } catch (e) { /* the pane is optional decoration; never break the page */ }
+    } catch (e) {
+      // Swallowing this is what made the production bug invisible: render() threw
+      // a ReferenceError on an undefined `s`, the catch ate it, every table kept
+      // its empty placeholder, and the page looked fine in the network tab while
+      // showing nothing. Still must not THROW (the pane is decoration and must
+      // never break the host page) — but it must leave a trace.
+      if (window.console && console.error) console.error("[billing] render failed", e);
+    }
   }
   window.__billingRefresh = refresh;
   refresh();
@@ -560,7 +620,12 @@ plugin.ui = {
       }
       document.getElementById("billing-status-sub").textContent =
         (st.total.requests || 0) + " requests" + (parts.length ? " · top: " + parts.join(" · ") : "");
-    } catch (e) { /* decoration only */ }
+    } catch (e) {
+      // Same reasoning as the Billing page: decoration must never break the
+      // host page, but a silent catch turns a broken widget into "the plugin
+      // just doesn't show anything" with no way to tell why.
+      if (window.console && console.error) console.error("[billing] status tile refresh failed", e);
+    }
   }
   if (window.pluginAPI && pluginAPI.onTabShown) pluginAPI.onTabShown(tick);
   tick();