feat(insertion-normalization): un-merge CC's join-moves, and stop a re-served entry from re-binding

docs/CONSUMER-SETUP.md

@@ -0,0 +1,69 @@
+# Consumer setup — the protection set, nothing else
+
+For running this fork purely as protection: no captures, no telemetry, no
+development machinery. Install and launch mechanics are upstream's — follow
+the main [README](../README.md) ("Quick Start", "Running as a service");
+this page only tells you **which switches to turn on and why**.
+
+## What it protects against
+
+Claude Code re-sends the whole conversation every request; Anthropic bills
+the unchanged part cheaply only while the bytes match exactly. Three CC
+behaviors break that match and silently re-bill six-figure token counts:
+
+1. **Old reminder blocks get re-shaped mid-history**
+   ([anthropics/claude-code#76606](https://github.com/anthropics/claude-code/issues/76606),
+   [#78660](https://github.com/anthropics/claude-code/issues/78660)) — an
+   edit deep in the history re-bills everything after it.
+2. **The tools list changes when a tool loads mid-session**
+   ([#81967](https://github.com/anthropics/claude-code/issues/81967)) — the
+   tools list heads the cached prefix, so one late tool load re-bills the
+   entire context.
+3. **Byte drift in already-sent messages** (stray whitespace, block
+   re-serialization —
+   [#48734](https://github.com/anthropics/claude-code/issues/48734)) — any
+   2-byte wobble invalidates the whole prefix.
+
+The extensions below hold the forwarded bytes stable across all three, and
+a last-line guard makes sure no mitigation can ever corrupt a conversation:
+on any structural mismatch it forwards the original untouched.
+
+## The switches
+
+Bake these into the service at install time (see the README's
+`install-service` section — flags set at install time land in the unit):
+
+```sh
+CACHE_FIX_FORWARD_PROXY=on \
+CACHE_FIX_INSERTION_NORMALIZE=1 \
+CACHE_FIX_VOLATILE_PIN=1 \
+CACHE_FIX_TOOL_REWRITE=1 \
+CACHE_FIX_OUTPUT_GUARD=1 \
+cache-fix-proxy install-service
+```
+
+| switch | what it does |
+|---|---|
+| `FORWARD_PROXY=on` | transport mode — Claude Code connects through the proxy with no `ANTHROPIC_BASE_URL` change |
+| `INSERTION_NORMALIZE=1` | recognizes messages by content, so relocated/re-shaped history is forwarded in its first-seen form |
+| `VOLATILE_PIN=1` | pins reminder blocks to their first serialization — CC's re-stamps stop reaching the wire |
+| `TOOL_REWRITE=1` | freezes the tools list; late-loaded tools are announced at the tail instead of re-writing the prefix (auto-limited to models measured to support it — everywhere else it degrades to stock behavior, never an error) |
+| `OUTPUT_GUARD=1` | the safety net: validates structure after all mitigations and restores the original on any violation |
+
+Everything upstream ships enabled by default stays enabled — those handle
+further stabilization (fingerprint stripping, sort stabilization, etc.).
+
+**Deliberately NOT enabled** (development/telemetry, not protection):
+`REQUEST_CAPTURE`, `SESSION_MIRROR`, `PREFIXDIFF`, `UPSTREAM_DETECTION` —
+these record traffic for the verification machinery. A consumer needs none
+of them; leaving them off means nothing about your conversations is written
+to disk beyond what Claude Code itself stores.
+
+## How you'd notice it working
+
+The mitigation is invisible by design — the observable is your usage:
+long sessions stop hitting sudden six-figure `cache_creation` spikes on
+turns where nothing big changed. If you suspect a problem, the guard's
+restore events land in
+`~/.claude/cache-fix-snapshots/guard-events.jsonl`; an empty or absent
+file is the normal state.

proxy/extensions.json

@@ -15,8 +15,10 @@
   "workflow-agent-id-synthesis": { "enabled": true, "order": 365 },
   "image-retry-circuit-breaker": { "enabled": true, "order": 370 },
   "read-dedupe": { "enabled": true, "order": 380 },
+  "insertion-normalization": { "enabled": true, "order": 395 },
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "messages-cache-breakpoint": { "enabled": true, "order": 410 },
+  "deferred-tool-rewrite": { "enabled": true, "order": 425 },
   "ttl-management": { "enabled": true, "order": 500 },
   "cache-telemetry": { "enabled": true, "order": 600 },
   "overage-warning": { "enabled": true, "order": 610 },

proxy/extensions/fresh-session-sort.mjs

@@ -149,16 +149,29 @@ export default {
       return;
     }
 
-    // Scan backwards to find latest instance of each relocatable block type
+    // Scan backwards to find latest instance of each relocatable block type.
+    // `occurrences` counts EVERY instance seen in the same pass (not just the
+    // kept one) — the extension's own record of whether the type it is about
+    // to relocate has ever appeared anywhere else in this array (including
+    // already at messages[firstUserIdx], before mutation). One occurrence
+    // means this relocation is the type's first appearance in the whole
+    // array — the deliberate one-time bust this extension exists for
+    // (see the module doc). More than one means it recurred — reported as
+    // such rather than folded into the same "first appearance" telemetry,
+    // so a consumer (replay's stability exemption) can tell the two apart
+    // instead of re-deriving it from shape.
     const found = new Map();
+    const occurrences = new Map();
     for (let i = body.messages.length - 1; i >= firstUserIdx; i--) {
       const msg = body.messages[i];
       if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
       for (let j = msg.content.length - 1; j >= 0; j--) {
         const block = msg.content[j];
         const text = block.text || "";
         const blockType = getBlockType(text);
-        if (!blockType || found.has(blockType)) continue;
+        if (!blockType) continue;
+        occurrences.set(blockType, (occurrences.get(blockType) ?? 0) + 1);
+        if (found.has(blockType)) continue;
 
         const fixedText = fixBlockText(blockType, text);
         const { cache_control, ...rest } = block;
@@ -180,11 +193,24 @@ export default {
 
     // Prepend in deterministic order: deferred → mcp → skills → hooks
     const ORDER = ["deferred", "mcp", "skills", "hooks"];
-    const toRelocate = ORDER.filter((t) => found.has(t)).map((t) => found.get(t));
+    const relocatedTypes = ORDER.filter((t) => found.has(t));
+    const toRelocate = relocatedTypes.map((t) => found.get(t));
 
     body.messages[firstUserIdx] = {
       ...body.messages[firstUserIdx],
       content: [...toRelocate, ...body.messages[firstUserIdx].content],
     };
+
+    // Report what happened — nothing downstream re-derives this. A
+    // first-appearance relocation prepends content CC never had at
+    // messages[firstUserIdx] before, which is exactly the shape replay's
+    // cross-request stability check flags as a self-inflicted byte flip
+    // (module doc, top). Telemetry lets that check tell the deliberate
+    // one-time bust apart from a genuine repeat/thrash at the same index.
+    ctx.meta = ctx.meta || {};
+    ctx.meta.freshSessionSortStats = {
+      relocated: relocatedTypes.map((t) => ({ type: t, firstAppearance: occurrences.get(t) === 1 })),
+      targetIndex: firstUserIdx,
+    };
   },
 };