claude-code-cache-fix 3.1.1 → 3.2.0

package/README.md

@@ -86,6 +86,43 @@ nohup cache-fix-proxy server > /tmp/cache-fix-proxy.log 2>&1 &
 echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:9801' >> ~/.bashrc
 ```
 
+### Docker
+
+A multi-arch (amd64, arm64) container image is published to GitHub Container Registry on every release tag.
+
+```bash
+docker run -d --name cache-fix-proxy \
+  --restart=always \
+  -p 9801:9801 \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+
+# Then in your shell:
+export ANTHROPIC_BASE_URL=http://127.0.0.1:9801
+```
+
+Use `--restart=always` instead of the systemd healthcheck companion — Docker handles auto-recovery natively. Mount nothing; the container is stateless. Override the default port with `-e CACHE_FIX_PROXY_PORT=...`. Override the upstream (e.g. to chain through llm-relay) with `-e CACHE_FIX_PROXY_UPSTREAM=http://host.docker.internal:8080`. The image runs as the unprivileged `node` user (uid 1000) and exposes a `HEALTHCHECK` Docker can use for liveness.
+
+For corporate environments behind an SSL-inspecting proxy, mount your CA bundle and set the env vars:
+
+```bash
+docker run -d --name cache-fix-proxy --restart=always -p 9801:9801 \
+  -e HTTPS_PROXY=http://proxy.corp.example:8080 \
+  -e CACHE_FIX_PROXY_CA_FILE=/etc/ssl/corp-ca.pem \
+  -v /path/to/zscaler-root.pem:/etc/ssl/corp-ca.pem:ro \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+```
+
+Image tags: `latest`, `3`, `3.2`, `3.2.0` (semver-ladder, so `3` always points to the newest 3.x). `latest` always tracks the newest tagged release.
+
+**Linux note:** the chained-upstream `host.docker.internal` example below is automatic on Docker Desktop (macOS / Windows). On plain Linux Docker Engine you usually need `--add-host=host.docker.internal:host-gateway` so the name resolves to the host bridge. Without it, the container's name lookup fails and the proxy can't reach the upstream service running on the host. Example chaining cache-fix proxy through `llm-relay` running on the host:
+
+```bash
+docker run -d --name cache-fix-proxy --restart=always -p 9801:9801 \
+  --add-host=host.docker.internal:host-gateway \
+  -e CACHE_FIX_PROXY_UPSTREAM=http://host.docker.internal:8080 \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+```
+
 ### Health check
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",

package/proxy/extensions/overage-warning.mjs

@@ -0,0 +1,385 @@
+// overage-warning — emit a one-time warning per Q5h-window threshold
+// crossing when Anthropic's response headers indicate the user is
+// approaching or has crossed the overage threshold.
+//
+// Advisory only. No request mutation. Two outputs:
+//   1. stderr line prefixed `[overage-warning]` for proxy journals/logs
+//   2. structured JSON record appended to `~/.claude/overage-warnings.jsonl`
+//
+// Activation: `enabled: true` in extensions.json (this extension is
+// always loaded), gated at runtime by `CACHE_FIX_OVERAGE_WARNING=1`.
+// Matches the prefix-diff pattern (env-var-only opt-in).
+//
+// See `docs/directives/proxy-overage-cost-warning.md` for the full design.
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+import { WEIGHTED_TOKEN_COST_USD_COARSE } from "../rates.mjs";
+
+// Env-gated runtime flags read on each call. Reading at module load would
+// freeze the values and make per-test isolation impossible. The check is
+// cheap (one process.env lookup per invocation when disabled).
+function isEnabled() {
+  return process.env.CACHE_FIX_OVERAGE_WARNING === "1";
+}
+function isQuiet() {
+  return process.env.CACHE_FIX_OVERAGE_WARNING_QUIET === "1";
+}
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
+
+function debug(msg) {
+  if (isDebug()) process.stderr.write(`[overage-warning] DEBUG: ${msg}\n`);
+}
+
+// --- Module-scope state ---
+//
+// Sliding window of (timestamp, q5h_util, input_tokens, cache_creation_tokens,
+// cache_read_tokens, output_tokens) samples. Used to compute burn rate.
+//
+// Cross-response dedup: per Q5h window (keyed by q5h_resets_at), the set
+// of thresholds we've already warned at. Window expires when q5h_resets_at
+// changes (new window = new dedup state).
+
+const WINDOW_MS = 15 * 60 * 1000;
+const WINDOW_MAX_SAMPLES = 60;
+const WARM_UP_MIN_SAMPLES = 3;
+
+const _window = []; // { t, q5h, input, cache_creation, cache_read, output }
+let _dedupWindowResetsAt = 0;
+let _dedupThresholds = new Set();
+
+function resetState() {
+  _window.length = 0;
+  _dedupWindowResetsAt = 0;
+  _dedupThresholds = new Set();
+}
+
+// --- Pure functions (test seam) ---
+
+export function parseTriggerFromHeaders(headers) {
+  if (!headers || typeof headers !== "object") return { eligible: false };
+  const get = (k) => headers[k] || "";
+  const num = (k) => {
+    const v = get(k);
+    if (!v) return null;
+    const n = parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+  };
+  const intOf = (k) => {
+    const v = get(k);
+    if (!v) return 0;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : 0;
+  };
+
+  const status =
+    get("anthropic-ratelimit-unified-status") ||
+    get("anthropic-ratelimit-unified-5h-status");
+  const surpassed = num("anthropic-ratelimit-unified-7d-surpassed-threshold");
+  const overage_status = get("anthropic-ratelimit-unified-overage-status") || "unknown";
+  const upgrade_paths_raw = get("anthropic-ratelimit-unified-upgrade-paths");
+  const q5h_util = num("anthropic-ratelimit-unified-5h-utilization");
+  const q7d_util = num("anthropic-ratelimit-unified-7d-utilization");
+  const q5h_resets_at = intOf("anthropic-ratelimit-unified-5h-reset");
+
+  // Trigger gates: status is allowed_warning or throttled, surpassed-threshold
+  // header is present and non-empty.
+  const isWarn = status === "allowed_warning" || status === "throttled";
+  if (!isWarn) return { eligible: false };
+  if (surpassed === null) return { eligible: false };
+
+  const upgrade_paths = upgrade_paths_raw
+    ? upgrade_paths_raw.split(",").map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  return {
+    eligible: true,
+    trigger: {
+      status,
+      surpassed_threshold: surpassed,
+      overage_status,
+      upgrade_paths,
+    },
+    snapshot: {
+      q5h_pct: q5h_util !== null ? Math.round(q5h_util * 100) : null,
+      q7d_pct: q7d_util !== null ? Math.round(q7d_util * 100) : null,
+      q5h_resets_at,
+    },
+    raw: {
+      q5h_util,
+      q5h_resets_at,
+    },
+  };
+}
+
+export function dedupKey(threshold, q5h_resets_at) {
+  return `${threshold}@${q5h_resets_at}`;
+}
+
+// Compute burn-rate projection from samples. Returns:
+//   { min_to_100, tokens_per_min, cost_per_hr_usd_coarse, window_samples,
+//     window_minutes }
+// All projection fields are `null` when fewer than WARM_UP_MIN_SAMPLES
+// samples exist OR utilization is non-increasing across the window.
+export function computeProjection(samples, now = Date.now()) {
+  // Drop expired samples (caller may have already done this; defensive).
+  const fresh = samples.filter((s) => now - s.t <= WINDOW_MS);
+
+  if (fresh.length < WARM_UP_MIN_SAMPLES) {
+    return {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: fresh.length,
+      window_minutes: 0,
+    };
+  }
+
+  const oldest = fresh[0];
+  const newest = fresh[fresh.length - 1];
+  const windowMin = (newest.t - oldest.t) / 60_000;
+
+  if (windowMin <= 0) {
+    return {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: fresh.length,
+      window_minutes: 0,
+    };
+  }
+
+  const deltaUtil = newest.q5h - oldest.q5h;
+  const utilPerMin = deltaUtil / windowMin;
+
+  let min_to_100 = null;
+  if (utilPerMin > 0) {
+    min_to_100 = Math.max(0, Math.round((1 - newest.q5h) / utilPerMin));
+  }
+
+  // Sum of all relevant tokens across the window. Each sample carries the
+  // per-call token deltas as pushed by recordSample (caller responsibility).
+  const totalTokens = fresh.reduce(
+    (acc, s) =>
+      acc + (s.input || 0) + (s.cache_creation || 0) + (s.cache_read || 0) + (s.output || 0),
+    0,
+  );
+  const tokens_per_min = totalTokens / windowMin;
+  const cost_per_hr_usd_coarse =
+    utilPerMin > 0
+      ? +(tokens_per_min * 60 * WEIGHTED_TOKEN_COST_USD_COARSE).toFixed(2)
+      : null;
+
+  return {
+    min_to_100,
+    tokens_per_min: Math.round(tokens_per_min),
+    cost_per_hr_usd_coarse,
+    window_samples: fresh.length,
+    window_minutes: +windowMin.toFixed(1),
+  };
+}
+
+export function formatStderrLine({ ts, trigger, snapshot, projection }) {
+  const upgrade = trigger.upgrade_paths.length
+    ? trigger.upgrade_paths.join(", ")
+    : "(none)";
+  const head = `[overage-warning] ${ts} Q5h=${snapshot.q5h_pct}% Q7d=${snapshot.q7d_pct}% (surpassed ${trigger.surpassed_threshold})`;
+  if (projection && projection.min_to_100 !== null && projection.cost_per_hr_usd_coarse !== null) {
+    return `${head} — projected 100% in ~${projection.min_to_100} min, estimated continued burn ≈ $${projection.cost_per_hr_usd_coarse.toFixed(2)}/hr at API rates (coarse). Upgrade paths: ${upgrade}.`;
+  }
+  return `${head} — projection unavailable (warming up). Upgrade paths: ${upgrade}.`;
+}
+
+export function formatJsonlRecord({ ts, trigger, snapshot, projection }) {
+  return {
+    ts,
+    trigger: {
+      status: trigger.status,
+      surpassed_threshold: trigger.surpassed_threshold,
+      overage_status: trigger.overage_status,
+      upgrade_paths: trigger.upgrade_paths,
+    },
+    snapshot: {
+      q5h_pct: snapshot.q5h_pct,
+      q7d_pct: snapshot.q7d_pct,
+      q5h_resets_at: snapshot.q5h_resets_at,
+    },
+    projection: projection || {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: 0,
+      window_minutes: 0,
+    },
+  };
+}
+
+// --- Window management ---
+
+export function recordSample(state, sample) {
+  state.window.push(sample);
+  const cutoff = sample.t - WINDOW_MS;
+  while (state.window.length && state.window[0].t < cutoff) state.window.shift();
+  while (state.window.length > WINDOW_MAX_SAMPLES) state.window.shift();
+}
+
+// --- Dedup helpers operating on module state ---
+
+function checkAndMarkDedup(threshold, q5h_resets_at) {
+  // New Q5h window resets the dedup set.
+  if (q5h_resets_at !== _dedupWindowResetsAt) {
+    _dedupWindowResetsAt = q5h_resets_at;
+    _dedupThresholds = new Set();
+  }
+  const key = dedupKey(threshold, q5h_resets_at);
+  if (_dedupThresholds.has(key)) return false;
+  _dedupThresholds.add(key);
+  return true;
+}
+
+// --- I/O ---
+
+async function appendJsonl(record, dir) {
+  const outDir = dir || (process.env.CACHE_FIX_OVERAGE_WARNING_DIR || join(homedir(), ".claude"));
+  const outPath = join(outDir, "overage-warnings.jsonl");
+  await mkdir(outDir, { recursive: true });
+  await appendFile(outPath, JSON.stringify(record) + "\n");
+}
+
+// Test helper: write a record using a caller-supplied directory. Bypasses
+// env-var lookup so tests do not race on a shared env. Pure side effect.
+export async function writeRecord(record, dir) {
+  await appendJsonl(record, dir);
+}
+
+// Test helper: drain in-memory state. For deterministic tests.
+export function _resetForTest() {
+  resetState();
+}
+
+// --- Extension contract ---
+
+export default {
+  name: "overage-warning",
+  description:
+    "Emit one-time warning per Q5h-window threshold crossing when overage headers indicate trouble",
+  enabled: true,
+  order: 610,
+
+  async onResponseStart(ctx) {
+    if (!isEnabled()) return;
+    if (!ctx || !ctx.headers) return;
+
+    try {
+      ctx.meta = ctx.meta || {};
+
+      // Always capture quota state if the headers carry it, regardless of
+      // whether THIS response's status crosses a warning threshold. Future
+      // responses need warm samples to project from.
+      const q5hRaw = ctx.headers["anthropic-ratelimit-unified-5h-utilization"];
+      const q5hUtil = q5hRaw ? parseFloat(q5hRaw) : null;
+      if (q5hUtil !== null && Number.isFinite(q5hUtil)) {
+        ctx.meta._overageQuota = { q5h_util: q5hUtil };
+      }
+
+      // Trigger eligibility latch — only set when this response is the one
+      // that crossed a threshold. Keeps emission gate separate from sampling.
+      const result = parseTriggerFromHeaders(ctx.headers);
+      if (!result.eligible) return;
+      ctx.meta._overageWarning = {
+        eligible: true,
+        emitted: false,
+        trigger: result.trigger,
+        snapshot: result.snapshot,
+        raw: result.raw,
+      };
+    } catch (err) {
+      debug(`onResponseStart unexpected: ${err?.message ?? err}`);
+    }
+  },
+
+  async onStreamEvent(ctx) {
+    if (!isEnabled()) return;
+    if (!ctx || !ctx.event) return;
+
+    try {
+      // Sample collection — happens on every response that has a quota
+      // reading, regardless of whether this response is the one that emits.
+      if (ctx.event.type === "message_start" && ctx.event.message?.usage) {
+        const u = ctx.event.message.usage;
+        const q5hUtil = ctx.meta?._overageQuota?.q5h_util;
+        if (q5hUtil !== undefined && q5hUtil !== null) {
+          const sample = {
+            t: Date.now(),
+            q5h: q5hUtil,
+            input: u.input_tokens || 0,
+            cache_creation: u.cache_creation_input_tokens || 0,
+            cache_read: u.cache_read_input_tokens || 0,
+            output: 0,
+          };
+          recordSample({ window: _window }, sample);
+          // Hand the response its own sample reference. message_delta updates
+          // THIS sample only — never the window's last sample, which could
+          // belong to a different response under interleaving.
+          ctx.meta._overageSample = sample;
+        }
+      }
+
+      if (ctx.event.type === "message_delta") {
+        // Update THIS response's sample with output tokens. The sample
+        // reference is response-local (set by message_start), so a response
+        // that never sampled cannot leak output tokens into another response.
+        const ownSample = ctx.meta?._overageSample;
+        if (ownSample && ctx.event.usage?.output_tokens) {
+          ownSample.output += ctx.event.usage.output_tokens;
+        }
+
+        // Emission gate.
+        const w = ctx.meta?._overageWarning;
+        if (!w || !w.eligible || w.emitted) return;
+
+        const allowed = checkAndMarkDedup(
+          w.trigger.surpassed_threshold,
+          w.snapshot.q5h_resets_at,
+        );
+        if (!allowed) {
+          w.emitted = true;
+          return;
+        }
+
+        const ts = new Date().toISOString();
+        const projection = computeProjection(_window, Date.now());
+        const projectionForOutput =
+          projection.window_samples >= WARM_UP_MIN_SAMPLES &&
+          projection.min_to_100 !== null
+            ? projection
+            : null;
+
+        const record = formatJsonlRecord({
+          ts,
+          trigger: w.trigger,
+          snapshot: w.snapshot,
+          projection: projectionForOutput || projection,
+        });
+
+        if (!isQuiet()) {
+          process.stderr.write(formatStderrLine({
+            ts,
+            trigger: w.trigger,
+            snapshot: w.snapshot,
+            projection: projectionForOutput,
+          }) + "\n");
+        }
+
+        await appendJsonl(record);
+        w.emitted = true;
+      }
+    } catch (err) {
+      debug(`onStreamEvent unexpected: ${err?.message ?? err}`);
+    }
+  },
+};

package/proxy/extensions/upstream-change-detection.mjs

@@ -0,0 +1,533 @@
+// upstream-change-detection — read-only structural fingerprinter that
+// detects when Anthropic ships CC updates that change the structural shape
+// of /v1/messages requests. Per-namespace baseline persists across proxy
+// restarts to prevent false-positive floods.
+//
+// Output:
+//   - stderr line prefixed [upstream-change] for proxy journals/logs
+//   - ~/.claude/upstream-changes.jsonl (event log: baseline_established,
+//     structural_change)
+//   - ~/.claude/upstream-baseline.json (per-namespace baseline, atomic
+//     full replace)
+//
+// Activation: `enabled: true` in extensions.json (always loaded), gated at
+// runtime by `CACHE_FIX_UPSTREAM_DETECTION=1`. Prefix-diff pattern.
+//
+// Privacy: every persisted field is a count, position, boolean, bucket
+// label, or hash of stable identifiers. NO prompt content, NO file paths,
+// NO message text. Test #18 enforces this at unit level.
+//
+// See `docs/directives/proxy-upstream-change-detection.md` for full design.
+
+import {
+  mkdir as _mkdir,
+  readFile as _readFile,
+  writeFile as _writeFile,
+  rename as _rename,
+  unlink as _unlink,
+  appendFile as _appendFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash, randomBytes } from "node:crypto";
+
+// --- Allowlists ---
+//
+// New entries are signal: when a request's text contains a marker / tag we
+// haven't seen before, the boolean unknown-detector flips. Add entries here
+// only when investigation has confirmed the new item is legitimate
+// (genuine CC change, not an exploit attempt).
+
+const KNOWN_SECTION_MARKERS = [
+  "# Environment",
+  "# System",
+  "# Tools",
+  "# Personality",
+  "# Settings",
+  "# Memory",
+  "# Output efficiency",
+  "# auto memory",
+  "# Doing tasks",
+  "# Tone and style",
+  "# Using your tools",
+  "# Text output",
+  "# Session-specific guidance",
+  "# Code references",
+  "# Executing actions with care",
+];
+
+const KNOWN_REMINDER_PATTERNS = [
+  "<system-reminder>",
+  "<command-name>",
+  "<command-message>",
+  "<command-args>",
+  "<git-status>",
+  "<local-command-stdout>",
+  "<local-command-stderr>",
+  "<command-stdout>",
+  "<command-stderr>",
+  "<file-attachment>",
+];
+
+const SECTION_MARKER_SHAPE = /^# [A-Z][a-zA-Z ]{1,30}$/m;
+const REMINDER_TAG_SHAPE = /<[a-z][a-z-]{1,30}>/;
+
+// --- Env gates (per-call to ease test isolation) ---
+
+function isEnabled() {
+  return process.env.CACHE_FIX_UPSTREAM_DETECTION === "1";
+}
+function isQuiet() {
+  return process.env.CACHE_FIX_UPSTREAM_QUIET === "1";
+}
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
+
+function debug(msg) {
+  if (isDebug()) process.stderr.write(`[upstream-change] DEBUG: ${msg}\n`);
+}
+
+// --- Default fs (overridable for tests) ---
+
+const DEFAULT_FS = {
+  mkdir: _mkdir,
+  readFile: _readFile,
+  writeFile: _writeFile,
+  rename: _rename,
+  unlink: _unlink,
+  appendFile: _appendFile,
+};
+
+// --- Module-scope state ---
+
+let _namespaceMap = new Map();
+let _baselineLoadedFrom = null;
+
+export function _resetForTest() {
+  _namespaceMap = new Map();
+  _baselineLoadedFrom = null;
+}
+
+function getOutputDir() {
+  return process.env.CACHE_FIX_UPSTREAM_DIR || join(homedir(), ".claude");
+}
+
+function getBaselinePath(dir) {
+  return join(dir || getOutputDir(), "upstream-baseline.json");
+}
+
+function getJsonlPath(dir) {
+  return join(dir || getOutputDir(), "upstream-changes.jsonl");
+}
+
+// --- Pure helpers ---
+
+function sha16(s) {
+  return createHash("sha256").update(s).digest("hex").slice(0, 16);
+}
+
+export function bucketBlockSize(size) {
+  if (size < 200) return "tiny";
+  if (size < 2000) return "small";
+  if (size < 20000) return "medium";
+  return "large";
+}
+
+export function bucketMaxTokens(n) {
+  if (!Number.isFinite(n) || n <= 0) return "unset";
+  if (n < 1024) return "tiny";
+  if (n < 8192) return "1k-8k";
+  if (n < 32768) return "8k-32k";
+  if (n < 100000) return "32k-100k";
+  return "huge";
+}
+
+export function matchKnownSectionMarkers(text) {
+  if (typeof text !== "string" || !text) return [];
+  // Strict line-based match. The marker must be the ENTIRE line (after split),
+  // otherwise "# Environment Details" would falsely match "# Environment" and
+  // we would record an allowlist index for a marker that didn't actually
+  // appear as a section header.
+  const lineSet = new Set(text.split("\n"));
+  const indices = [];
+  for (let i = 0; i < KNOWN_SECTION_MARKERS.length; i++) {
+    if (lineSet.has(KNOWN_SECTION_MARKERS[i])) indices.push(i);
+  }
+  return indices;
+}
+
+export function hasUnknownSectionMarker(text) {
+  if (typeof text !== "string" || !text) return false;
+  // Find candidate markers via the shape regex on each line.
+  const lines = text.split("\n");
+  for (const line of lines) {
+    if (SECTION_MARKER_SHAPE.test(line) && !KNOWN_SECTION_MARKERS.includes(line)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function matchKnownReminderPatterns(text) {
+  if (typeof text !== "string" || !text) return [];
+  const indices = [];
+  for (let i = 0; i < KNOWN_REMINDER_PATTERNS.length; i++) {
+    if (text.includes(KNOWN_REMINDER_PATTERNS[i])) indices.push(i);
+  }
+  return indices;
+}
+
+export function hasUnknownReminderPattern(text) {
+  if (typeof text !== "string" || !text) return false;
+  const matches = text.matchAll(/<[a-z][a-z-]{1,30}>/g);
+  for (const m of matches) {
+    if (!KNOWN_REMINDER_PATTERNS.includes(m[0])) return true;
+  }
+  return false;
+}
+
+export function namespaceKey(model, betaHeadersArr) {
+  const sorted = Array.isArray(betaHeadersArr) ? [...betaHeadersArr].sort() : [];
+  return sha16(`${model || ""}|${sorted.join(",")}`);
+}
+
+// Beta features arrive on the `anthropic-beta` REQUEST HEADER (Node http
+// header keys are lowercased). The proxy surfaces request headers on
+// `ctx.headers` to onRequest hooks. The function accepts the headers map
+// (case-insensitive lookup) and falls back to body.anthropic_beta only as
+// a defensive fallback for edge cases where a caller pre-merged it.
+export function extractBetaHeaders(headers, body) {
+  const fromHeader = headers && (headers["anthropic-beta"] || headers["Anthropic-Beta"] || headers["ANTHROPIC-BETA"]);
+  let raw = fromHeader;
+  if (!raw) raw = body?.anthropic_beta;
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map(String).map((s) => s.trim()).filter(Boolean);
+  if (typeof raw === "string") return raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+function blockTextLength(block) {
+  if (!block || typeof block !== "object") return 0;
+  if (typeof block.text === "string") return block.text.length;
+  if (typeof block.content === "string") return block.content.length;
+  return 0;
+}
+
+function blockText(block) {
+  if (!block || typeof block !== "object") return "";
+  if (typeof block.text === "string") return block.text;
+  if (typeof block.content === "string") return block.content;
+  return "";
+}
+
+function countCacheControlInArray(arr) {
+  if (!Array.isArray(arr)) return { count: 0, positions: [] };
+  const positions = [];
+  for (let i = 0; i < arr.length; i++) {
+    const item = arr[i];
+    if (item && typeof item === "object" && item.cache_control) {
+      positions.push(i);
+    }
+  }
+  return { count: positions.length, positions };
+}
+
+function fingerprintSystem(system) {
+  const blocks = Array.isArray(system) ? system : [];
+  const types = blocks.map((b) => (b && typeof b === "object" && typeof b.type === "string" ? b.type : "unknown"));
+  const sizes = blocks.map((b) => bucketBlockSize(blockTextLength(b)));
+  const cc = countCacheControlInArray(blocks);
+
+  const knownIndicesSet = new Set();
+  let unknownPresent = false;
+  for (const b of blocks) {
+    const text = blockText(b);
+    for (const idx of matchKnownSectionMarkers(text)) knownIndicesSet.add(idx);
+    if (!unknownPresent && hasUnknownSectionMarker(text)) unknownPresent = true;
+  }
+  const knownIndicesSorted = [...knownIndicesSet].sort((a, b) => a - b);
+
+  return {
+    block_count: blocks.length,
+    block_types_in_order: types,
+    block_size_buckets: sizes,
+    known_section_marker_set_hash: sha16(knownIndicesSorted.join(",")),
+    known_section_marker_count: knownIndicesSorted.length,
+    unknown_section_marker_present: unknownPresent,
+    cache_control_count: cc.count,
+    cache_control_positions: cc.positions,
+  };
+}
+
+function fingerprintTools(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) {
+    return {
+      count: 0,
+      names_sorted_hash: sha16(""),
+      schema_shape_hash: sha16(""),
+    };
+  }
+  const names = tools.map((t) => (t && typeof t.name === "string" ? t.name : "")).sort();
+  // Build name → sorted-param-keys map deterministically.
+  const shape = {};
+  for (const t of tools) {
+    if (!t || typeof t.name !== "string") continue;
+    const props = t.input_schema?.properties;
+    const keys = props && typeof props === "object" ? Object.keys(props).sort() : [];
+    shape[t.name] = keys;
+  }
+  const shapeOrdered = {};
+  for (const k of Object.keys(shape).sort()) shapeOrdered[k] = shape[k];
+
+  return {
+    count: tools.length,
+    names_sorted_hash: sha16(JSON.stringify(names)),
+    schema_shape_hash: sha16(JSON.stringify(shapeOrdered)),
+  };
+}
+
+function fingerprintMessages(messages) {
+  const arr = Array.isArray(messages) ? messages : [];
+  let cc = 0;
+  const knownSet = new Set();
+  let unknownPresent = false;
+
+  for (const msg of arr) {
+    if (!msg || typeof msg !== "object") continue;
+    if (Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block && typeof block === "object" && block.cache_control) cc++;
+        const text = blockText(block);
+        for (const idx of matchKnownReminderPatterns(text)) knownSet.add(idx);
+        if (!unknownPresent && hasUnknownReminderPattern(text)) unknownPresent = true;
+      }
+    } else if (typeof msg.content === "string") {
+      for (const idx of matchKnownReminderPatterns(msg.content)) knownSet.add(idx);
+      if (!unknownPresent && hasUnknownReminderPattern(msg.content)) unknownPresent = true;
+    }
+  }
+
+  const knownSorted = [...knownSet].sort((a, b) => a - b);
+  return {
+    count: arr.length,
+    first_role: arr[0]?.role || null,
+    cache_control_count_in_messages: cc,
+    known_reminder_pattern_set_hash: sha16(knownSorted.join(",")),
+    known_reminder_pattern_count: knownSorted.length,
+    unknown_reminder_pattern_present: unknownPresent,
+  };
+}
+
+function fingerprintRequestExtras(body) {
+  return {
+    has_thinking: !!body?.thinking,
+    has_metadata: !!body?.metadata,
+    stream: body?.stream === true,
+    max_tokens_bucket: bucketMaxTokens(body?.max_tokens),
+  };
+}
+
+// Compute a structural fingerprint. `headers` is the request headers map
+// (case-insensitive lookup is internal); pass `{}` if not available.
+export function computeFingerprint(body, headers = {}) {
+  const safeBody = body && typeof body === "object" ? body : {};
+  const beta = extractBetaHeaders(headers, safeBody);
+  return {
+    version: 1,
+    namespace: {
+      model: typeof safeBody.model === "string" ? safeBody.model : "",
+      beta_headers_sorted_hash: sha16([...beta].sort().join(",")),
+      beta_headers_count: beta.length,
+    },
+    system: fingerprintSystem(safeBody.system),
+    tools: fingerprintTools(safeBody.tools),
+    messages: fingerprintMessages(safeBody.messages),
+    request_extras: fingerprintRequestExtras(safeBody),
+  };
+}
+
+// Diff two fingerprints. Returns array of { path, from, to } entries. Equality
+// is structural (deep). Arrays are compared by JSON stringification.
+export function diffFingerprints(prev, current) {
+  const diff = [];
+  if (!prev || !current) return diff;
+  walk("", prev, current, diff);
+  return diff;
+}
+
+function walk(prefix, a, b, out) {
+  if (a === b) return;
+  if (typeof a !== typeof b) {
+    out.push({ path: prefix, from: a, to: b });
+    return;
+  }
+  if (Array.isArray(a) || Array.isArray(b) || typeof a !== "object" || a === null || b === null) {
+    if (JSON.stringify(a) !== JSON.stringify(b)) {
+      out.push({ path: prefix, from: a, to: b });
+    }
+    return;
+  }
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    const subPath = prefix ? `${prefix}.${k}` : k;
+    walk(subPath, a[k], b[k], out);
+  }
+}
+
+// --- Persistence ---
+
+async function loadBaseline(fs = DEFAULT_FS, dir = getOutputDir()) {
+  const path = getBaselinePath(dir);
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.namespaces && typeof parsed.namespaces === "object") {
+      _namespaceMap = new Map(Object.entries(parsed.namespaces));
+      _baselineLoadedFrom = path;
+      return _namespaceMap;
+    }
+  } catch (err) {
+    debug(`baseline load failed (${path}): ${err?.message ?? err}`);
+  }
+  _namespaceMap = new Map();
+  return _namespaceMap;
+}
+
+async function persistBaseline(fs = DEFAULT_FS, dir = getOutputDir()) {
+  const finalPath = getBaselinePath(dir);
+  const tmpSuffix = `${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}`;
+  const tmpPath = `${finalPath}.tmp.${tmpSuffix}`;
+  const doc = {
+    version: 1,
+    namespaces: Object.fromEntries(_namespaceMap),
+  };
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmpPath, JSON.stringify(doc));
+    await fs.rename(tmpPath, finalPath);
+  } finally {
+    try { await fs.unlink(tmpPath); } catch {}
+  }
+}
+
+async function appendEvent(record, fs = DEFAULT_FS, dir = getOutputDir()) {
+  const path = getJsonlPath(dir);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// Test seam: bypass module-scope state and operate on a caller-supplied map.
+export async function processRequestForTest(body, { dir, map = _namespaceMap, fs = DEFAULT_FS, headers = {} } = {}) {
+  return _processRequest(body, headers, { dir, map, fs });
+}
+
+async function _processRequest(body, headers, { dir, map, fs }) {
+  const fingerprint = computeFingerprint(body, headers);
+  const nsKey = namespaceKey(fingerprint.namespace.model, extractBetaHeaders(headers, body));
+  const ts = new Date().toISOString();
+
+  const existing = map.get(nsKey);
+  if (!existing) {
+    const entry = {
+      namespace: fingerprint.namespace,
+      fingerprint,
+      established_at: ts,
+      last_updated_at: ts,
+      update_count: 0,
+    };
+    map.set(nsKey, entry);
+    await appendEvent(
+      { ts, event: "baseline_established", namespace: fingerprint.namespace, fingerprint },
+      fs,
+      dir,
+    );
+    return { event: "baseline_established", nsKey };
+  }
+
+  if (JSON.stringify(existing.fingerprint) === JSON.stringify(fingerprint)) {
+    return { event: "noop", nsKey };
+  }
+
+  const diff = diffFingerprints(existing.fingerprint, fingerprint);
+  const previous = existing.fingerprint;
+  const updated = {
+    namespace: fingerprint.namespace,
+    fingerprint,
+    established_at: existing.established_at,
+    last_updated_at: ts,
+    update_count: (existing.update_count || 0) + 1,
+  };
+  map.set(nsKey, updated);
+
+  await appendEvent(
+    {
+      ts,
+      event: "structural_change",
+      namespace: fingerprint.namespace,
+      diff,
+      previous,
+      current: fingerprint,
+    },
+    fs,
+    dir,
+  );
+
+  return { event: "structural_change", nsKey, diff };
+}
+
+function formatStderrLine({ ts, namespace, diff }) {
+  const head = `[upstream-change] ${ts} model=${namespace.model || "?"} beta=${namespace.beta_headers_count}`;
+  const summary = diff
+    .slice(0, 6)
+    .map((d) => `${d.path}: ${JSON.stringify(d.from)} → ${JSON.stringify(d.to)}`)
+    .join("; ");
+  const more = diff.length > 6 ? ` (+${diff.length - 6} more)` : "";
+  return `${head} :: ${summary}${more}`;
+}
+
+// --- Extension contract ---
+
+export default {
+  name: "upstream-change-detection",
+  description:
+    "Detect structural changes in CC-originated /v1/messages requests via per-namespace fingerprint",
+  enabled: true,
+  order: 50,
+
+  async onRequest(ctx) {
+    if (!isEnabled()) return;
+    if (!ctx || !ctx.body) return;
+
+    try {
+      const dir = getOutputDir();
+      const fs = DEFAULT_FS;
+      // Lazy-load baseline on first call after module load.
+      if (_baselineLoadedFrom === null) {
+        await loadBaseline(fs, dir);
+        _baselineLoadedFrom = getBaselinePath(dir);
+      }
+      const result = await _processRequest(ctx.body, ctx.headers || {}, { dir, map: _namespaceMap, fs });
+      // Persist baseline whenever it changed.
+      if (result.event === "baseline_established" || result.event === "structural_change") {
+        await persistBaseline(fs, dir);
+      }
+      if (result.event === "structural_change" && !isQuiet()) {
+        const ts = new Date().toISOString();
+        const namespace = _namespaceMap.get(result.nsKey)?.namespace;
+        process.stderr.write(formatStderrLine({ ts, namespace: namespace || {}, diff: result.diff }) + "\n");
+      }
+    } catch (err) {
+      debug(`onRequest unexpected: ${err?.message ?? err}`);
+    }
+  },
+};
+
+// Expose internals for testing.
+export {
+  loadBaseline,
+  persistBaseline,
+  appendEvent,
+  formatStderrLine,
+  _namespaceMap as __testNamespaceMap,
+};

package/proxy/extensions/usage-log.mjs

@@ -1,46 +1,275 @@
+// usage-log — append per-call usage record to ~/.claude/usage.jsonl.
+//
+// The emitted record matches `MeterRowSchema` v:1 from
+// `claude-code-meter/src/log/schema.mjs` exactly. claude-meter validates each
+// row through that schema; the wire format is the cross-repo contract.
+//
+// Schema (every row):
+//   v: 1
+//   ts: ISO datetime
+//   sid: 8-char lowercase hex (proxy session, sticky for proxy lifetime)
+//   model: string ≤64, /^[a-z0-9._-]+$/
+//   requested_model?: string ≤64, /^[a-z0-9._-]*$/  (optional)
+//   model_mismatch?: bool                            (optional)
+//   speed: "standard" | "fast" | ""
+//   service_tier: string ≤32, /^[a-z0-9_-]*$/
+//   input_tokens, output_tokens, cache_creation_input_tokens,
+//   cache_read_input_tokens, ephemeral_1h_input_tokens,
+//   ephemeral_5m_input_tokens, web_search_requests: int ≥ 0
+//   q5h, q7d: float 0–2
+//   q5h_reset, q7d_reset: int (unix sec)
+//   qstatus, qoverage, qclaim: string lowercase enums
+//   qfallback_pct: float 0–1
+//   qoverage_util?: float ≥ 0                        (optional)
+//   qrepresentative_claim?: string ≤16               (optional)
+//   org_id?: 16-char hex (sha256(raw header).digest("hex").slice(0,16))
+//   overage_disabled_reason?: string ≤64             (optional)
+//   cache_hit_rate: float 0–1
+//   q5h_delta, q7d_delta: float (0 on first call after restart)
+//
+// `peak_hour` is NOT in the wire format. It can be derived from `ts` if any
+// consumer needs it.
+//
+// Activation: enabled:false in the export default (existing usage-log
+// pattern). Users opt in by adding an entry to proxy/extensions.json:
+//   "usage-log": { "enabled": true, "order": 650 }
+// CACHE_FIX_USAGE_LOG=<path> overrides the destination path only — it is NOT
+// an enable flag and never has been.
+//
+// See `docs/directives/proxy-claude-meter-compat.md` for full design.
+
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 
 const LOG_PATH = process.env.CACHE_FIX_USAGE_LOG || join(homedir(), ".claude", "usage.jsonl");
 
-function buildRecord(meta, telemetry, responseHeaders) {
-  const now = new Date();
-  const utcHour = now.getUTCHours();
-  const utcDay = now.getUTCDay();
+// --- Module-scope state ---
+
+const _sid = generateSid();
+let _lastQ5h = null;
+let _lastQ7d = null;
+
+// --- Pure helpers (test seam) ---
 
-  const stats = meta.cacheStats || {};
-  const quota = meta._quotaData || {};
+export function generateSid() {
+  return createHash("sha256")
+    .update(`${process.pid}-${Date.now()}-${Math.random()}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+export function hashOrgId(rawOrgId) {
+  if (!rawOrgId || typeof rawOrgId !== "string") return undefined;
+  return createHash("sha256").update(rawOrgId).digest("hex").slice(0, 16);
+}
 
+export function extractMessageStartFields(event) {
+  if (!event || event.type !== "message_start") return null;
+  const msg = event.message;
+  if (!msg || !msg.usage) return null;
+  const usage = msg.usage;
+  const cc = usage.cache_creation || {};
+  const sti = usage.server_tool_use || {};
   return {
-    timestamp: now.toISOString(),
-    model: telemetry.model || "unknown",
-    input_tokens: stats.inputTokens || 0,
-    output_tokens: stats.outputTokens || 0,
-    cache_read_input_tokens: stats.cacheRead || 0,
-    cache_creation_input_tokens: stats.cacheCreation || 0,
-    q5h_pct: quota.five_hour ? quota.five_hour.pct : null,
-    q7d_pct: quota.seven_day ? quota.seven_day.pct : null,
-    peak_hour: utcDay >= 1 && utcDay <= 5 && utcHour >= 13 && utcHour < 19,
+    model: typeof msg.model === "string" ? msg.model : "",
+    speed: usage.speed || "",
+    service_tier: usage.service_tier || "",
+    input_tokens: usage.input_tokens || 0,
+    cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+    cache_read_input_tokens: usage.cache_read_input_tokens || 0,
+    ephemeral_1h_input_tokens: cc.ephemeral_1h_input_tokens || 0,
+    ephemeral_5m_input_tokens: cc.ephemeral_5m_input_tokens || 0,
+    web_search_requests: sti.web_search_requests || 0,
+  };
+}
+
+export function extractMessageDeltaFields(event) {
+  if (!event || event.type !== "message_delta") return null;
+  if (!event.usage) return null;
+  return { output_tokens: event.usage.output_tokens || 0 };
+}
+
+function num(headers, key) {
+  const v = headers?.[key];
+  if (v === undefined || v === null || v === "") return null;
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function intOf(headers, key) {
+  const v = headers?.[key];
+  if (v === undefined || v === null || v === "") return 0;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function strOf(headers, key) {
+  const v = headers?.[key];
+  return typeof v === "string" ? v : "";
+}
+
+export function parseQuotaHeaders(headers) {
+  const h = headers || {};
+  return {
+    q5h: num(h, "anthropic-ratelimit-unified-5h-utilization") ?? 0,
+    q7d: num(h, "anthropic-ratelimit-unified-7d-utilization") ?? 0,
+    q5h_reset: intOf(h, "anthropic-ratelimit-unified-5h-reset"),
+    q7d_reset: intOf(h, "anthropic-ratelimit-unified-7d-reset"),
+    qstatus: strOf(h, "anthropic-ratelimit-unified-status"),
+    qoverage: strOf(h, "anthropic-ratelimit-unified-overage-status"),
+    qclaim: strOf(h, "anthropic-ratelimit-unified-claim"),
+    qfallback_pct: num(h, "anthropic-ratelimit-unified-fallback-percentage") ?? 0,
+    qoverage_util: num(h, "anthropic-ratelimit-unified-overage-utilization"),
+    qrepresentative_claim: strOf(h, "anthropic-ratelimit-unified-representative-claim") || undefined,
+    org_id_raw: strOf(h, "anthropic-organization-id") || undefined,
+    overage_disabled_reason: strOf(h, "anthropic-ratelimit-unified-overage-disabled-reason") || undefined,
+  };
+}
+
+export function computeDelta(current, previous) {
+  if (previous === null || previous === undefined) return 0;
+  if (typeof current !== "number" || typeof previous !== "number") return 0;
+  return current - previous;
+}
+
+export function assembleRecord({ start, delta, quota, requestedModel, sid, prevQ5h, prevQ7d, now = new Date() }) {
+  const s = start || {};
+  const d = delta || {};
+  const q = quota || {};
+
+  const inputTokens = s.input_tokens || 0;
+  const outputTokens = d.output_tokens || 0;
+  const cacheRead = s.cache_read_input_tokens || 0;
+  const cacheCreation = s.cache_creation_input_tokens || 0;
+  const totalIn = inputTokens + cacheCreation + cacheRead;
+  const cacheHitRate = totalIn > 0 ? cacheRead / totalIn : 0;
+
+  const record = {
+    v: 1,
+    ts: now.toISOString(),
+    sid,
+    model: s.model || "",
+    speed: s.speed || "",
+    service_tier: s.service_tier || "",
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_creation_input_tokens: cacheCreation,
+    cache_read_input_tokens: cacheRead,
+    ephemeral_1h_input_tokens: s.ephemeral_1h_input_tokens || 0,
+    ephemeral_5m_input_tokens: s.ephemeral_5m_input_tokens || 0,
+    web_search_requests: s.web_search_requests || 0,
+    q5h: q.q5h ?? 0,
+    q7d: q.q7d ?? 0,
+    q5h_reset: q.q5h_reset || 0,
+    q7d_reset: q.q7d_reset || 0,
+    qstatus: q.qstatus || "",
+    qoverage: q.qoverage || "",
+    qclaim: q.qclaim || "",
+    qfallback_pct: q.qfallback_pct ?? 0,
+    cache_hit_rate: cacheHitRate,
+    q5h_delta: computeDelta(q.q5h, prevQ5h),
+    q7d_delta: computeDelta(q.q7d, prevQ7d),
   };
+
+  // Optional fields are OMITTED (not present as undefined) when source absent.
+  if (requestedModel) {
+    record.requested_model = requestedModel;
+    if (record.model && requestedModel !== record.model) {
+      record.model_mismatch = true;
+    }
+  }
+  if (q.qoverage_util !== null && q.qoverage_util !== undefined) {
+    record.qoverage_util = q.qoverage_util;
+  }
+  if (q.qrepresentative_claim) {
+    record.qrepresentative_claim = q.qrepresentative_claim;
+  }
+  const orgIdHashed = hashOrgId(q.org_id_raw);
+  if (orgIdHashed) {
+    record.org_id = orgIdHashed;
+  }
+  if (q.overage_disabled_reason) {
+    record.overage_disabled_reason = q.overage_disabled_reason;
+  }
+
+  return record;
 }
 
-export { buildRecord, LOG_PATH };
+// --- I/O ---
+
+async function appendJsonl(record, path = LOG_PATH) {
+  await mkdir(join(homedir(), ".claude"), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// Test helper: write a record to a caller-supplied path. Bypasses env-var
+// lookup so tests don't race on a shared env.
+export async function writeRecord(record, path) {
+  await mkdir(path.substring(0, path.lastIndexOf("/")), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// Test helper: reset module-scope delta state.
+export function _resetDeltaStateForTest() {
+  _lastQ5h = null;
+  _lastQ7d = null;
+}
+
+export { LOG_PATH };
+
+// --- Extension contract ---
 
 export default {
   name: "usage-log",
-  description: "Append per-call usage record to ~/.claude/usage.jsonl",
+  description: "Append per-call usage record to ~/.claude/usage.jsonl (MeterRowSchema v:1)",
   enabled: false,
   order: 650,
 
   async onStreamEvent(ctx) {
-    if (!ctx.event || ctx.event.type !== "message_delta" || !ctx.event.usage) return;
-
-    const record = buildRecord(ctx.meta, ctx.telemetry || {}, ctx.responseHeaders);
+    if (!ctx || !ctx.event) return;
 
     try {
-      await mkdir(join(homedir(), ".claude"), { recursive: true });
-      await appendFile(LOG_PATH, JSON.stringify(record) + "\n");
-    } catch {}
+      // message_start: capture per-response state into ctx.meta._usageLog.
+      if (ctx.event.type === "message_start") {
+        const start = extractMessageStartFields(ctx.event);
+        if (start) {
+          ctx.meta = ctx.meta || {};
+          ctx.meta._usageLog = { start };
+        }
+        return;
+      }
+
+      // message_delta: assemble and emit the final record.
+      if (ctx.event.type !== "message_delta" || !ctx.event.usage) return;
+
+      const start = ctx.meta?._usageLog?.start;
+      if (!start) return; // no message_start was observed for this response
+
+      const delta = extractMessageDeltaFields(ctx.event);
+      const quota = parseQuotaHeaders(ctx.responseHeaders || {});
+      const requestedModel = ctx.telemetry?.requestedModel || undefined;
+
+      const record = assembleRecord({
+        start,
+        delta,
+        quota,
+        requestedModel,
+        sid: _sid,
+        prevQ5h: _lastQ5h,
+        prevQ7d: _lastQ7d,
+        now: new Date(),
+      });
+
+      // Update delta tracking AFTER assembly so the first call's delta is 0
+      // (per the directive contract: first call after restart → deltas zero).
+      _lastQ5h = quota.q5h;
+      _lastQ7d = quota.q7d;
+
+      await appendJsonl(record, process.env.CACHE_FIX_USAGE_LOG || LOG_PATH);
+    } catch {
+      // Fail-open: never throw to the pipeline.
+    }
   },
 };

package/proxy/extensions.json

@@ -9,5 +9,6 @@
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "ttl-management": { "enabled": true, "order": 500 },
   "cache-telemetry": { "enabled": true, "order": 600 },
+  "overage-warning": { "enabled": true, "order": 610 },
   "request-log": { "enabled": false, "order": 700 }
 }

package/proxy/rates.mjs

@@ -0,0 +1,16 @@
+// Shared rate constants for cost projections.
+//
+// This is a deliberate over-simplification for v3.2.0. Anthropic's
+// per-token rates vary by model, by cache tier (input vs cache_read vs
+// cache_creation_5m vs cache_creation_1h), and by overage classification.
+// Encoding all of that correctly is its own subproject — see the v3.3.0
+// follow-up for a precise per-tier engine.
+//
+// For v3.2.0 we ship a single weighted blend constant suitable for
+// a coarse "burn rate at API rates" indicator. Consumers MUST label the
+// resulting number as `coarse` so users do not mistake it for a precise
+// quote.
+
+// Heuristic blend covering input + cache_read + cache_creation + output
+// at a typical Opus 4.7 mix. Order of magnitude is right; precise it is not.
+export const WEIGHTED_TOKEN_COST_USD_COARSE = 0.000005;