From 2dfd0e278b7b57224649268f027c52dfee1616cb Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@quibiq.de>
Date: Thu, 30 Jul 2026 19:21:20 +0200
Subject: [PATCH 1/7] fix(cache): report history-image hash from the history
 message, not messages[0]
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`historyImageSha8` hashed the image blocks on `messages[0]`, described in its
own docstring as "the synthetic history message". It is not: whenever a slab
anchor exists, `collapseHistory` returns `[...head, syntheticUser, ...tail]`
and transform.ts passes `protectedPrefix = slabAnchorIdx + 1`, so on every
Claude Code request `messages[0]` is the protected slab message. The field
that exists to prove history-image byte-identity was therefore reporting SLAB
stability under the history name — a drifting collapse boundary still showed a
rock-steady `history_image_sha8` in events.jsonl, which is precisely the
signal #11 attribution relies on. Locate the synthetic message by its banner,
the same way `cachePrefixDigest` does.

Also split the pinned-prefix digest per layer. `cache_prefix_sha8` proves THAT
the cacheable prefix moved but never WHICH layer moved, and the layers fail for
different reasons and need different fixes: tools drift when the client loads a
deferred tool, system drifts when volatile text (env, git status) rides inside
the pinned span, and the imaged head drifts when a collapse boundary or marker
placement moves. Emit `cache_prefix_tools_sha8` / `cache_prefix_system_sha8` /
`cache_prefix_head_sha8` alongside the aggregate so one session of telemetry
names the culprit instead of narrowing it to "somewhere in the prefix".

Motivation: a production session showed 530/530 requests with a unique
`cache_prefix_sha8` at a constant `cache_prefix_bytes`, 0 cache_read across
87M cache_create tokens — with the aggregate hash alone the cause could not be
attributed, and `history_image_sha8` looked stable because it was measuring
the wrong message.

(cherry picked from commit fa7314339840518393a478568e7f6da59765e7ba)
---
 src/core/tracker.ts                  |  10 +++
 src/core/transform.ts                |  66 +++++++++++---
 tests/cache-bust-attribution.test.ts | 127 +++++++++++++++++++++++++++
 3 files changed, 191 insertions(+), 12 deletions(-)
 create mode 100644 tests/cache-bust-attribution.test.ts

diff --git a/src/core/tracker.ts b/src/core/tracker.ts
index 4c59b7754..68cc771a1 100644
--- a/src/core/tracker.ts
+++ b/src/core/tracker.ts
@@ -98,6 +98,13 @@ export interface TrackEvent {
   cache_prefix_sha8?: string;
   /** Approx chars in that pinned prefix (growth vs pure-invalidation split). */
   cache_prefix_bytes?: number;
+  /** Per-layer digests of the same pinned prefix. Whichever one moves between
+   *  two turns of a session IS the cache-bust cause: tools (client loaded a
+   *  deferred tool), system (volatile text inside the pinned span), head
+   *  (collapse boundary / marker placement moved). */
+  cache_prefix_tools_sha8?: string;
+  cache_prefix_system_sha8?: string;
+  cache_prefix_head_sha8?: string;
 
   // From TransformInfo.env:
   cwd?: string;
@@ -278,6 +285,9 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
     }
     if (info.cachePrefixSha8) out.cache_prefix_sha8 = info.cachePrefixSha8;
     if (info.cachePrefixBytes !== undefined) out.cache_prefix_bytes = info.cachePrefixBytes;
+    if (info.cachePrefixToolsSha8) out.cache_prefix_tools_sha8 = info.cachePrefixToolsSha8;
+    if (info.cachePrefixSystemSha8) out.cache_prefix_system_sha8 = info.cachePrefixSystemSha8;
+    if (info.cachePrefixHeadSha8) out.cache_prefix_head_sha8 = info.cachePrefixHeadSha8;
     if (info.unknownStaticTags && info.unknownStaticTags.length > 0)
       out.unknown_static_tags = info.unknownStaticTags;
     if (info.churningStaticTags && info.churningStaticTags.length > 0)
diff --git a/src/core/transform.ts b/src/core/transform.ts
index 6d78b0bf5..d7e973447 100644
--- a/src/core/transform.ts
+++ b/src/core/transform.ts
@@ -684,6 +684,13 @@ export interface TransformInfo {
   /** Approx size (chars) of that cached prefix — pairs with cachePrefixSha8 so a
    *  bust reads as growth (size up) vs pure invalidation (size unchanged). */
   cachePrefixBytes?: number;
+  /** Per-layer digests of that same pinned prefix, in wire order: tool
+   *  definitions, system blocks, and the imaged head (messages up to and
+   *  including the history/slab boundary). Exactly one of these moving names
+   *  the cache-bust culprit; the aggregate cachePrefixSha8 alone cannot. */
+  cachePrefixToolsSha8?: string;
+  cachePrefixSystemSha8?: string;
+  cachePrefixHeadSha8?: string;
   /** Why the history collapse didn't run (or did). Diagnostic only. */
   historyReason?:
     | 'no_history'
@@ -1016,13 +1023,27 @@ async function recordRecoverable(
   });
 }
 
-/** Hash the concatenated base64 of every image block on `messages[0]` (the synthetic
- *  history message). Stable across the quantized collapse window → proves Anthropic
- *  can cache_read the history prefix. Returns undefined if no images on messages[0]. */
+/** Hash the concatenated base64 of every image block on the synthetic history
+ *  message. Stable across the quantized collapse window → proves Anthropic can
+ *  cache_read the history prefix. Returns undefined if there is no such message.
+ *
+ *  The synthetic message is NOT `messages[0]` whenever a slab anchor exists:
+ *  collapseHistory returns `[...head, syntheticUser, ...tail]` and transform.ts
+ *  passes `protectedPrefix = slabAnchorIdx + 1`, so on a Claude Code request
+ *  `messages[0]` is the protected slab message. Hashing it reported SLAB image
+ *  stability under the `history_image_sha8` name — the one field meant to prove
+ *  history-image byte-identity was blind to the history images, so a drifting
+ *  collapse boundary still looked stable in telemetry (#11 attribution). Locate
+ *  the message by its banner instead, exactly like cachePrefixDigest does. */
 async function historyImageSha8(
   messages: Message[],
 ): Promise<string | undefined> {
-  const synthetic = messages[0];
+  const synthetic = messages.find(
+    (m) =>
+      Array.isArray(m.content) &&
+      (m.content[0] as TextBlock | undefined)?.type === 'text' &&
+      (m.content[0] as TextBlock).text === HISTORY_SYNTHETIC_INTRO,
+  );
   if (!synthetic || !Array.isArray(synthetic.content)) return undefined;
   let concat = '';
   for (const blk of synthetic.content) {
@@ -1110,7 +1131,10 @@ function relocateAnchorToHistoryImage(messages: Message[] | undefined, anchorOrd
  */
 async function cachePrefixDigest(
   req: { tools?: unknown; system?: unknown; messages?: unknown },
-): Promise<{ sha8: string; bytes: number } | undefined> {
+): Promise<
+  | { sha8: string; bytes: number; toolsSha8: string; systemSha8: string; headSha8: string }
+  | undefined
+> {
   const msgs = Array.isArray(req.messages) ? (req.messages as Message[]) : [];
   // Boundary = latest message carrying pxpipe's imaged prefix: the history image
   // (banner) when collapse ran, else the slab message ('[End of rendered
@@ -1127,19 +1151,34 @@ async function cachePrefixDigest(
     if (isHistory || hasSlab) boundary = i;
   }
   if (boundary < 0) return undefined; // not an imaged-prefix shape — nothing pinned
-  const parts: string[] = [];
-  if (Array.isArray(req.tools)) for (const t of req.tools) parts.push(JSON.stringify(t));
+  // Component digests, in wire order. A whole-prefix hash proves THAT the cache
+  // busted but never WHICH layer moved, and the layers fail for different
+  // reasons: tools drift when the client loads a deferred tool, system drifts
+  // when volatile text (env/git status) rides inside the pinned span, and the
+  // imaged head drifts when a collapse boundary or marker placement moves.
+  // Hashing each separately turns "prefix changed" into a one-line diagnosis.
+  const toolParts: string[] = [];
+  if (Array.isArray(req.tools)) for (const t of req.tools) toolParts.push(JSON.stringify(t));
+  const sysParts: string[] = [];
   const sys = req.system;
-  if (typeof sys === 'string') parts.push(sys);
-  else if (Array.isArray(sys)) for (const b of sys) parts.push(JSON.stringify(b));
+  if (typeof sys === 'string') sysParts.push(sys);
+  else if (Array.isArray(sys)) for (const b of sys) sysParts.push(JSON.stringify(b));
+  const headParts: string[] = [];
   for (let i = 0; i <= boundary; i++) {
     const content = msgs[i]?.content;
-    if (typeof content === 'string') parts.push(content);
+    if (typeof content === 'string') headParts.push(content);
     else if (Array.isArray(content))
-      for (const b of content) parts.push(typeof b === 'string' ? b : JSON.stringify(b));
+      for (const b of content) headParts.push(typeof b === 'string' ? b : JSON.stringify(b));
   }
+  const parts = [...toolParts, ...sysParts, ...headParts];
   const prefix = parts.join('\x00');
-  return { sha8: await sha8(prefix), bytes: prefix.length };
+  return {
+    sha8: await sha8(prefix),
+    bytes: prefix.length,
+    toolsSha8: await sha8(toolParts.join('\x00')),
+    systemSha8: await sha8(sysParts.join('\x00')),
+    headSha8: await sha8(headParts.join('\x00')),
+  };
 }
 
 // Removed: extractClaudeMdSlab(). It scanned the static system text for
@@ -2398,6 +2437,9 @@ export async function transformRequest(
     if (pfx) {
       info.cachePrefixSha8 = pfx.sha8;
       info.cachePrefixBytes = pfx.bytes;
+      info.cachePrefixToolsSha8 = pfx.toolsSha8;
+      info.cachePrefixSystemSha8 = pfx.systemSha8;
+      info.cachePrefixHeadSha8 = pfx.headSha8;
     }
   }
   // Top dropped codepoints, capped at 20 entries to bound JSONL row size.
diff --git a/tests/cache-bust-attribution.test.ts b/tests/cache-bust-attribution.test.ts
new file mode 100644
index 000000000..5e9db716c
--- /dev/null
+++ b/tests/cache-bust-attribution.test.ts
@@ -0,0 +1,127 @@
+/**
+ * Cache-bust ATTRIBUTION telemetry (#11).
+ *
+ * When cache_read collapses in production, these fields are the only evidence
+ * available after the fact. Two contracts:
+ *
+ *  1. `history_image_sha8` must describe the HISTORY images. On a Claude Code
+ *     request the slab anchor makes `messages[0]` the protected slab message,
+ *     not the synthetic history message — hashing index 0 silently reported
+ *     slab stability under the history name, so a drifting collapse boundary
+ *     looked stable in telemetry.
+ *  2. The pinned prefix must be digested per LAYER (tools / system / imaged
+ *     head), because "the prefix changed" does not say which layer moved, and
+ *     the three fail for different reasons and need different fixes.
+ *
+ * Run just this file:  pnpm vitest run tests/cache-bust-attribution.test.ts
+ */
+import { describe, expect, it } from 'vitest';
+import { transformRequest } from '../src/core/transform.js';
+import { HISTORY_SYNTHETIC_INTRO } from '../src/core/history.js';
+import type { Message } from '../src/core/types.js';
+
+const big = (n: number) => 'x'.repeat(n);
+const enc = (obj: unknown) => new TextEncoder().encode(JSON.stringify(obj));
+const dec = (b: Uint8Array): any => JSON.parse(new TextDecoder().decode(b));
+
+/** N closed plain turns — long enough that the collapse gate accepts. */
+function convo(n: number, chars = 3500): Message[] {
+  const out: Message[] = [];
+  for (let i = 0; i < n; i++) {
+    const body = `turn ${i}: ` + big(chars);
+    out.push({ role: i % 2 === 0 ? 'user' : 'assistant', content: body });
+  }
+  return out;
+}
+
+/** A Claude-Code-shaped request: big marked system slab + a long conversation. */
+function ccBody(opts: { turns?: number; tools?: unknown[]; sysSuffix?: string } = {}) {
+  return enc({
+    model: 'claude-3-5-sonnet',
+    system: [
+      {
+        type: 'text',
+        text: big(80_000) + (opts.sysSuffix ?? ''),
+        cache_control: { type: 'ephemeral' },
+      },
+    ],
+    ...(opts.tools ? { tools: opts.tools } : {}),
+    messages: convo(opts.turns ?? 15),
+  });
+}
+
+/** Concatenated base64 of the image blocks on the synthetic history message. */
+function historyImageData(out: Uint8Array): string {
+  const body = dec(out);
+  const synthetic = (body.messages ?? []).find(
+    (m: any) => Array.isArray(m.content) && m.content[0]?.type === 'text' && m.content[0].text === HISTORY_SYNTHETIC_INTRO,
+  );
+  if (!synthetic) return '';
+  return synthetic.content
+    .filter((b: any) => b?.type === 'image')
+    .map((b: any) => b.source.data)
+    .join('');
+}
+
+/** Concatenated base64 of the image blocks on the FIRST message (the slab). */
+function slabImageData(out: Uint8Array): string {
+  const first = dec(out).messages?.[0];
+  if (!first || !Array.isArray(first.content)) return '';
+  return first.content
+    .filter((b: any) => b?.type === 'image')
+    .map((b: any) => b.source.data)
+    .join('');
+}
+
+describe('cache-bust attribution telemetry', () => {
+  it('history_image_sha8 tracks the history images, not the slab message at index 0', async () => {
+    const { body: out, info } = await transformRequest(ccBody());
+    // Precondition: this really is the Claude Code shape — a slab message ahead
+    // of the synthetic history message, both carrying images.
+    const slab = slabImageData(out);
+    const history = historyImageData(out);
+    expect(info.collapsedTurns).toBeGreaterThan(0);
+    expect(slab.length).toBeGreaterThan(0);
+    expect(history.length).toBeGreaterThan(0);
+    expect(history).not.toBe(slab);
+
+    // The reported hash must be a function of the HISTORY images. Prove it by
+    // changing only the history (more collapsed turns) and requiring the hash
+    // to move, while the slab bytes stay identical.
+    const { body: out2, info: info2 } = await transformRequest(ccBody({ turns: 65 }));
+    expect(slabImageData(out2)).toBe(slab); // slab unchanged …
+    expect(historyImageData(out2)).not.toBe(history); // … history changed …
+    expect(info2.historyImageSha).not.toBe(info.historyImageSha); // … so must the hash
+  });
+
+  it('digests the pinned prefix per layer (tools / system / head)', async () => {
+    const { info } = await transformRequest(ccBody());
+    expect(info.cachePrefixSha8).toBeDefined();
+    expect(info.cachePrefixToolsSha8).toBeDefined();
+    expect(info.cachePrefixSystemSha8).toBeDefined();
+    expect(info.cachePrefixHeadSha8).toBeDefined();
+  });
+
+  it('moves ONLY the tools digest when the client adds a tool', async () => {
+    const toolsA = [{ name: 'Read', description: 'Read a file. ' + big(400), input_schema: { type: 'object' } }];
+    const toolsB = [
+      ...toolsA,
+      { name: 'Grep', description: 'Search. ' + big(400), input_schema: { type: 'object' } },
+    ];
+    const a = await transformRequest(ccBody({ tools: toolsA }));
+    const b = await transformRequest(ccBody({ tools: toolsB }));
+    expect(b.info.cachePrefixToolsSha8).not.toBe(a.info.cachePrefixToolsSha8);
+    expect(b.info.cachePrefixSystemSha8).toBe(a.info.cachePrefixSystemSha8);
+    expect(b.info.cachePrefixSha8).not.toBe(a.info.cachePrefixSha8);
+  });
+
+  it('moves the system digest when volatile text rides inside the pinned span', async () => {
+    // `# Environment` churns every turn (cwd, git status, model id). Whatever
+    // survives as system TEXT is inside the pinned prefix and must show up as a
+    // system-layer bust — that is the signal a live capture needs.
+    const a = await transformRequest(ccBody({ sysSuffix: '\n# Environment\ngit status: clean\n' }));
+    const b = await transformRequest(ccBody({ sysSuffix: '\n# Environment\ngit status: 3 files changed\n' }));
+    expect(b.info.cachePrefixSystemSha8).not.toBe(a.info.cachePrefixSystemSha8);
+    expect(b.info.cachePrefixToolsSha8).toBe(a.info.cachePrefixToolsSha8);
+  });
+});

From fec6f65779263b85aa7fc8a76e203233867cfaa4 Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@quibiq.de>
Date: Thu, 30 Jul 2026 19:23:45 +0200
Subject: [PATCH 2/7] fix(cache): digest the MARKED span, not the boundary
 message, for bust attribution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`cachePrefixDigest` hashed every block up to and including the message that
carries pxpipe's imaged prefix. That is not the span Anthropic caches: caching
ends at the LAST cache_control marker, and after a history collapse the two
differ by construction. The synthetic message's newest freeze chunk re-renders
on every turn BY DESIGN (append-only rendering: only completed chunks are
frozen) and it sits AFTER the pinned marker — so the boundary-scoped digest
changes every single turn even when the cached span is byte-stable, and
`cache_prefix_sha8` reads "pxpipe busted its own cache" on healthy traffic.

Emit `cache_prefix_marked_sha8` / `_marked_bytes` / `_marker_pos` alongside:
the digest through the breakpoint, its size, and where the breakpoint sits as
`m<msg>.b<block>`. The marked digest is the one that must hold turn over turn;
the marker position makes a roaming breakpoint — a bust cause in its own right,
previously invisible — a one-field diagnosis.

Tests pin the contract that decides whether cache_read happens at all: two
consecutive turns of one session keep the marked span byte-identical while the
live tail grows.

(cherry picked from commit d7b865542b8b5aeda1bc8634254e946c91c58cad)
---
 src/core/tracker.ts                  | 10 +++++
 src/core/transform.ts                | 60 +++++++++++++++++++++++++++-
 tests/cache-bust-attribution.test.ts | 21 ++++++++++
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/src/core/tracker.ts b/src/core/tracker.ts
index 68cc771a1..8f44ef87d 100644
--- a/src/core/tracker.ts
+++ b/src/core/tracker.ts
@@ -105,6 +105,12 @@ export interface TrackEvent {
   cache_prefix_tools_sha8?: string;
   cache_prefix_system_sha8?: string;
   cache_prefix_head_sha8?: string;
+  /** The span Anthropic really caches (through the last cache_control marker),
+   *  its size, and the marker's position. Unstable marked digest ⇒ pxpipe-side
+   *  bust; stable digest with cache_read 0 ⇒ look upstream, not at the rewrite. */
+  cache_prefix_marked_sha8?: string;
+  cache_prefix_marked_bytes?: number;
+  cache_prefix_marker_pos?: string;
 
   // From TransformInfo.env:
   cwd?: string;
@@ -288,6 +294,10 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
     if (info.cachePrefixToolsSha8) out.cache_prefix_tools_sha8 = info.cachePrefixToolsSha8;
     if (info.cachePrefixSystemSha8) out.cache_prefix_system_sha8 = info.cachePrefixSystemSha8;
     if (info.cachePrefixHeadSha8) out.cache_prefix_head_sha8 = info.cachePrefixHeadSha8;
+    if (info.cachePrefixMarkedSha8) out.cache_prefix_marked_sha8 = info.cachePrefixMarkedSha8;
+    if (info.cachePrefixMarkedBytes !== undefined)
+      out.cache_prefix_marked_bytes = info.cachePrefixMarkedBytes;
+    if (info.cachePrefixMarkerPos) out.cache_prefix_marker_pos = info.cachePrefixMarkerPos;
     if (info.unknownStaticTags && info.unknownStaticTags.length > 0)
       out.unknown_static_tags = info.unknownStaticTags;
     if (info.churningStaticTags && info.churningStaticTags.length > 0)
diff --git a/src/core/transform.ts b/src/core/transform.ts
index d7e973447..6d77114a9 100644
--- a/src/core/transform.ts
+++ b/src/core/transform.ts
@@ -691,6 +691,16 @@ export interface TransformInfo {
   cachePrefixToolsSha8?: string;
   cachePrefixSystemSha8?: string;
   cachePrefixHeadSha8?: string;
+  /** Digest of the span Anthropic actually caches: everything up to and
+   *  including the LAST cache_control marker. After a collapse this is a strict
+   *  subset of the boundary-scoped prefix — the newest freeze chunk re-renders
+   *  every turn by design and sits after the marker — so THIS is the digest that
+   *  must stay stable turn over turn, and the boundary one is context. */
+  cachePrefixMarkedSha8?: string;
+  cachePrefixMarkedBytes?: number;
+  /** Where that last marker sits, as `m<messageIdx>.b<blockIdx>`. A marker that
+   *  roams between turns re-cuts the cached span and busts it on its own. */
+  cachePrefixMarkerPos?: string;
   /** Why the history collapse didn't run (or did). Diagnostic only. */
   historyReason?:
     | 'no_history'
@@ -1132,7 +1142,16 @@ function relocateAnchorToHistoryImage(messages: Message[] | undefined, anchorOrd
 async function cachePrefixDigest(
   req: { tools?: unknown; system?: unknown; messages?: unknown },
 ): Promise<
-  | { sha8: string; bytes: number; toolsSha8: string; systemSha8: string; headSha8: string }
+  | {
+      sha8: string;
+      bytes: number;
+      toolsSha8: string;
+      systemSha8: string;
+      headSha8: string;
+      markedSha8: string;
+      markedBytes: number;
+      markerPos: string;
+    }
   | undefined
 > {
   const msgs = Array.isArray(req.messages) ? (req.messages as Message[]) : [];
@@ -1170,6 +1189,39 @@ async function cachePrefixDigest(
     else if (Array.isArray(content))
       for (const b of content) headParts.push(typeof b === 'string' ? b : JSON.stringify(b));
   }
+  // The span Anthropic actually caches ends at the LAST cache_control marker —
+  // not at the message boundary above. Those differ by construction after a
+  // collapse: the synthetic message's newest freeze chunk re-renders every turn
+  // BY DESIGN and sits AFTER the pinned marker, so the boundary-scoped digest
+  // reports a bust on every single turn even when the cached span is perfectly
+  // stable. Digest the marker-scoped span too, and record where the marker sits:
+  // a moving marker is itself a bust cause, and telemetry could not see it.
+  let markPos = '';
+  const markedParts: string[] = [...toolParts, ...sysParts];
+  const markedUpTo: string[] = [];
+  outer: for (let i = msgs.length - 1; i >= 0; i--) {
+    const content = msgs[i]?.content;
+    if (!Array.isArray(content)) continue;
+    for (let k = content.length - 1; k >= 0; k--) {
+      const b = content[k] as { cache_control?: unknown } | undefined;
+      if (b && typeof b === 'object' && b.cache_control !== undefined) {
+        markPos = `m${i}.b${k}`;
+        for (let mi = 0; mi <= i; mi++) {
+          const c = msgs[mi]?.content;
+          if (typeof c === 'string') markedUpTo.push(c);
+          else if (Array.isArray(c))
+            for (let bk = 0; bk < c.length; bk++) {
+              if (mi === i && bk > k) break;
+              const blk = c[bk];
+              markedUpTo.push(typeof blk === 'string' ? blk : JSON.stringify(blk));
+            }
+        }
+        break outer;
+      }
+    }
+  }
+  markedParts.push(...markedUpTo);
+  const marked = markedParts.join('\x00');
   const parts = [...toolParts, ...sysParts, ...headParts];
   const prefix = parts.join('\x00');
   return {
@@ -1178,6 +1230,9 @@ async function cachePrefixDigest(
     toolsSha8: await sha8(toolParts.join('\x00')),
     systemSha8: await sha8(sysParts.join('\x00')),
     headSha8: await sha8(headParts.join('\x00')),
+    markedSha8: await sha8(marked),
+    markedBytes: marked.length,
+    markerPos: markPos,
   };
 }
 
@@ -2440,6 +2495,9 @@ export async function transformRequest(
       info.cachePrefixToolsSha8 = pfx.toolsSha8;
       info.cachePrefixSystemSha8 = pfx.systemSha8;
       info.cachePrefixHeadSha8 = pfx.headSha8;
+      info.cachePrefixMarkedSha8 = pfx.markedSha8;
+      info.cachePrefixMarkedBytes = pfx.markedBytes;
+      if (pfx.markerPos) info.cachePrefixMarkerPos = pfx.markerPos;
     }
   }
   // Top dropped codepoints, capped at 20 entries to bound JSONL row size.
diff --git a/tests/cache-bust-attribution.test.ts b/tests/cache-bust-attribution.test.ts
index 5e9db716c..b6bc42d4f 100644
--- a/tests/cache-bust-attribution.test.ts
+++ b/tests/cache-bust-attribution.test.ts
@@ -115,6 +115,27 @@ describe('cache-bust attribution telemetry', () => {
     expect(b.info.cachePrefixSha8).not.toBe(a.info.cachePrefixSha8);
   });
 
+  it('digests the MARKED span (what Anthropic caches) and records the marker position', async () => {
+    const { info } = await transformRequest(ccBody());
+    expect(info.cachePrefixMarkedSha8).toBeDefined();
+    expect(info.cachePrefixMarkerPos).toMatch(/^m\d+\.b\d+$/);
+    // The marked span ends at the breakpoint, so it is a strict subset of the
+    // boundary-scoped prefix (which runs to the end of the history message).
+    expect(info.cachePrefixMarkedBytes!).toBeLessThanOrEqual(info.cachePrefixBytes!);
+  });
+
+  it('keeps the marked span byte-identical while the live tail grows', async () => {
+    // The contract that decides whether cache_read happens: two consecutive
+    // turns of one session must send the SAME bytes up to the breakpoint. The
+    // newest freeze chunk re-renders by design, so a boundary-scoped digest may
+    // legitimately move — the marked one may not.
+    const a = await transformRequest(ccBody({ turns: 15 }));
+    const b = await transformRequest(ccBody({ turns: 17 }));
+    expect(b.info.collapsedTurns).toBe(a.info.collapsedTurns); // same collapse window
+    expect(b.info.cachePrefixMarkerPos).toBe(a.info.cachePrefixMarkerPos);
+    expect(b.info.cachePrefixMarkedSha8).toBe(a.info.cachePrefixMarkedSha8);
+  });
+
   it('moves the system digest when volatile text rides inside the pinned span', async () => {
     // `# Environment` churns every turn (cwd, git status, model id). Whatever
     // survives as system TEXT is inside the pinned prefix and must show up as a

From ff8b95f4eb4fc2ffb5d123a4e501d24fdff504a4 Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@quibiq.de>
Date: Thu, 30 Jul 2026 21:31:17 +0200
Subject: [PATCH 3/7] fix(dashboard): divide the by-events cache-hit rate by a
 field that exists

renderStatsTableFragment read s.eventsWithBaseline, but stats.ts emits
eventsWithUsage; the missing field made the comparison false for every
session, so the "cache hit (by events)" row silently rendered "-" no matter
what the cache did. The type carried the stale name too, so tsc had no
chance to catch it.

Test pins the value to its own row (the table renders as one line, so a
bare toContain passes on a neighbouring number) and fails with '-' against
the old expression.

(cherry picked from commit c6c5db6c2916b89cc5ef8114adbdbe02f5acd383)
---
 src/dashboard/fragments.ts  |  2 +-
 src/dashboard/types.ts      |  4 +++-
 tests/dashboard-api.test.ts | 38 ++++++++++++++++++++++++++++++++++++-
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/src/dashboard/fragments.ts b/src/dashboard/fragments.ts
index f875e9067..2d8fe88ac 100644
--- a/src/dashboard/fragments.ts
+++ b/src/dashboard/fragments.ts
@@ -766,7 +766,7 @@ export function renderStatsTableFragment(p: FullStatsPayload): string {
   const totalIn = (s.inputTokensTotal || 0) + (s.cacheCreateTokensTotal || 0) + (s.cacheReadTokensTotal || 0);
   const hitRateTok = totalIn > 0 ? ((s.cacheReadTokensTotal / totalIn) * 100).toFixed(1) + '%' : '-';
   const hitRateEv =
-    s.eventsWithBaseline > 0 ? ((s.cacheHitEvents / s.eventsWithBaseline) * 100).toFixed(1) + '%' : '-';
+    s.eventsWithUsage > 0 ? ((s.cacheHitEvents / s.eventsWithUsage) * 100).toFixed(1) + '%' : '-';
   const charRatio =
     s.origCharsTotal > 0 ? ((s.imageBytesTotal / s.origCharsTotal) * 100).toFixed(3) + 'x' : '-';
 
diff --git a/src/dashboard/types.ts b/src/dashboard/types.ts
index f2090c0d6..7a44053b5 100644
--- a/src/dashboard/types.ts
+++ b/src/dashboard/types.ts
@@ -132,7 +132,9 @@ export interface FullStatsSummary {
   cacheReadTokensTotal: number;
   outputTokensTotal: number;
   cacheHitEvents: number;
-  eventsWithBaseline: number;
+  // Denominator for the event-based cache-hit rate: events that carried usage
+  // data at all. Emitted by stats.ts as `eventsWithUsage`.
+  eventsWithUsage: number;
   origCharsTotal: number;
   imageBytesTotal: number;
   pinCharsTotal?: number;
diff --git a/tests/dashboard-api.test.ts b/tests/dashboard-api.test.ts
index 74756b880..4ec2fa9b2 100644
--- a/tests/dashboard-api.test.ts
+++ b/tests/dashboard-api.test.ts
@@ -15,7 +15,11 @@ import { getAllowedModelBases, setAllowedModelBases } from '../src/core/applicab
 import type { SessionsPaths } from '../src/sessions.js';
 import type { TrackEvent } from '../src/core/tracker.js';
 import type { StatsPayload, RecentPayload } from '../src/dashboard/types.js';
-import { renderHeaderFragment, renderPage } from '../src/dashboard/fragments.js';
+import {
+  renderHeaderFragment,
+  renderPage,
+  renderStatsTableFragment,
+} from '../src/dashboard/fragments.js';
 
 function makeTmp(): SessionsPaths {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pxpipe-dashapi-'));
@@ -1004,3 +1008,35 @@ describe('server-observed warmth: text follows actual cache_read', () => {
     expect(row.session_saved_so_far_delta).toBe(9900);
   });
 });
+
+/**
+ * Regression: the dashboard's "cache hit rate (by events)" row read a summary
+ * field (`eventsWithBaseline`) that stats.ts never emitted — it emits
+ * `eventsWithUsage`. The field existed in the payload *type*, so tsc stayed
+ * quiet, and the row silently rendered "-" forever. This test walks the real
+ * path (fold -> summaryToJson -> renderStatsTableFragment) so any future
+ * rename on either side fails here instead of blanking the dashboard.
+ */
+describe('stats table: event-based cache hit rate', () => {
+  it('renders a real percentage from the summary stats.ts actually emits', async () => {
+    const { newSummary, fold, summaryToJson } = await import('../src/stats.js');
+    let s = newSummary();
+    // 3 events with usage, 2 of them cache hits -> 66.7%
+    s = fold(s, { input_tokens: 100, cache_read_tokens: 900 } as TrackEvent);
+    s = fold(s, { input_tokens: 100, cache_read_tokens: 900 } as TrackEvent);
+    s = fold(s, { input_tokens: 100, cache_read_tokens: 0 } as TrackEvent);
+    // an event carrying no usage at all must not dilute the denominator
+    s = fold(s, { cwd: '/tmp' } as TrackEvent);
+
+    const summary = summaryToJson(s);
+    expect(summary.eventsWithUsage).toBe(3);
+    expect(summary.cacheHitEvents).toBe(2);
+
+    const html = renderStatsTableFragment({ summary } as never);
+    // Pin the value to its own row: the table is a single line, so a bare
+    // "contains" would also pass on some other row's number.
+    const evRow = /<td>cache hit \(by events\)<\/td><td class="num">([^<]*)<\/td>/.exec(html);
+    expect(evRow, 'the "cache hit (by events)" row must exist').not.toBeNull();
+    expect(evRow![1]).toBe('66.7%'); // not '-', which is what the dead field produced
+  });
+});

From 3ce2b987eac7174f974fc737f89566689b6cf67c Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@gmx.de>
Date: Sat, 1 Aug 2026 20:47:43 +0200
Subject: [PATCH 4/7] fix(images): price the client's own images against the
 provider cap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 100-image limit is a property of the wire, not of pxpipe: it counts
the images the client sent (pasted screenshots, pictures a tool returned)
together with every image we add. We priced only our own, so a request
that arrived already full got imaged further and came back 400/500 —
two sessions became unresumable.

Every imaging path now spends from one shared headroom:

  imageHeadroom() = cap - margin - ours - theirs

and the caller's images are counted once, before any rewrite, at both
nesting levels (top-level and inside tool_result).

The gate is quantitative, not boolean. A first cut asked "is there ANY
room left?" and then emitted a whole 15-page slab into it: 94 client
images + a 400k slab put 109 images on the wire. Now:

  - the slab must fit whole or not at all — imaging half of it would
    re-key the cache prefix on every turn whose client-image count moved;
  - each tool_result pages against the LIVE headroom, not a fixed 10;
  - after rendering we verify the real page count, because paging is
    budgeted at denseGeo.cols while rendering happens at o.cols;
  - the history collapse is skipped entirely at zero headroom — its
    budget floors at 1, so it would otherwise emit exactly one image
    and still fail the request.

Degrading means "do not emit this turn", never "un-emit": each turn is
re-derived from the client's own text transcript, so our images are
never stranded there.

Telemetry: native_images and image_budget_skips reach the event log, and
passthrough_reasons loses an allow-list that swallowed exactly the two
reasons worth diagnosing (kept_sharp, image_budget).

Measured, 300 turns + 60k slab + 60k tool_result:

  clients= 0 | slab=3 toolres=3 hist=50 | wire= 56 | text  233k
  clients=50 | slab=3 toolres=3 hist=44 | wire=100 | text  206k
  clients=80 | slab=3 toolres=3 hist=11 | wire= 97 | text  809k
  clients=90 | slab=3 toolres=1 hist= 0 | wire= 94 | text 1053k

Client images always win; we shrink to fit. What remains is a cliff, not
a slope: the collapse is our only reducer and it is image-based, so at a
full wire we drop from compressed straight to raw.

(cherry picked from commit cdae5519b915e9b3a4ac40cdc6185d26de2b6f02)
---
 src/core/history.ts              | 181 +++++++++++++++++++++++--
 src/core/render.ts               |  17 +++
 src/core/session-state.ts        | 146 ++++++++++++++++++++
 src/core/tracker.ts              |  14 +-
 src/core/transform.ts            | 226 +++++++++++++++++++++++++++++--
 src/dashboard.ts                 |  19 ++-
 src/dashboard/fragments.ts       |  18 ++-
 tests/dashboard-api.test.ts      |  39 +++++-
 tests/history-grid-e2e.test.ts   | 161 ++++++++++++++++++++++
 tests/history.test.ts            |  34 ++++-
 tests/native-image-cap.test.ts   | 178 ++++++++++++++++++++++++
 tests/scripts/smoke-collapse.mjs | 101 ++++++++++++++
 12 files changed, 1099 insertions(+), 35 deletions(-)
 create mode 100644 src/core/session-state.ts
 create mode 100644 tests/history-grid-e2e.test.ts
 create mode 100644 tests/native-image-cap.test.ts
 create mode 100644 tests/scripts/smoke-collapse.mjs

diff --git a/src/core/history.ts b/src/core/history.ts
index 8e76935e1..7257ae376 100644
--- a/src/core/history.ts
+++ b/src/core/history.ts
@@ -13,7 +13,7 @@
 
 import type { CacheControl, ContentBlock, ImageBlock, Message, TextBlock, ToolUseBlock, ToolResultBlock } from './types.js';
 import type { RenderedImage } from './render.js';
-import { DENSE_CONTENT_CHARS_PER_IMAGE, DENSE_CONTENT_COLS, DENSE_RENDER_STYLE, MAX_HEIGHT_PX, neutralizeSentinel, reflow, renderTextToPngsWithCharLimit, roleSlotSegment, SLOT_MARK_ASSISTANT, SLOT_MARK_USER, type RenderStyle } from './render.js';
+import { DENSE_CONTENT_CHARS_PER_IMAGE, DENSE_CONTENT_COLS, maxCharsPerImage, DENSE_RENDER_STYLE, MAX_HEIGHT_PX, neutralizeSentinel, reflow, renderTextToPngsWithCharLimit, roleSlotSegment, SLOT_MARK_ASSISTANT, SLOT_MARK_USER, type RenderStyle } from './render.js';
 import { factSheetText } from './factsheet.js';
 import { bytesToBase64 } from './png.js';
 
@@ -76,8 +76,41 @@ export interface HistoryCollapseOptions {
   style: RenderStyle;
   /** Model-profile page-height cap. */
   maxHeightPx: number;
+  /** Chars one rendered page holds. Only an ESTIMATOR input (the renderer paginates
+   *  on its own); it decides how many pages a candidate chunk grid will produce.
+   *  Default {@link DENSE_CONTENT_CHARS_PER_IMAGE}. */
+  pageChars: number;
+  /** Hard cap on image blocks this collapse may emit. Anthropic rejects requests
+   *  with more than 100 images (opaque 500), and a 10-message freeze grid emits
+   *  ≈1 page per chunk regardless of how little text the chunk holds — a 3000-turn
+   *  session hit 317 history images at 43% page fill (#161). When the grid would
+   *  exceed the budget the freeze step is DOUBLED (chunks merge, pages fill) until
+   *  the estimate fits; if even a single chunk cannot fit, the collapse range is
+   *  trimmed from the tail and the remainder stays live text. 0 = unlimited. */
+  imageBudget: number;
+  /** Fill-optimal repack. When true the freeze step is raised until the grid costs
+   *  at most one page more than a perfectly packed render — trading the append-only
+   *  cache freeze for ~2× fewer image tokens. Only correct when the upstream prefix
+   *  cache is dead anyway (cold session, see node.ts session store); on a warm
+   *  session it would re-key every frozen chunk. Default false. */
+  packFill: boolean;
+  /** Sticky lower bound for the freeze step, in messages. Once a session has been
+   *  repacked at a coarser grid, every later turn must keep that grid or the
+   *  re-render re-keys the whole history. Rounded UP to a power-of-two multiple of
+   *  `freezeChunk` so chunk boundaries stay a subset of the base grid. Default 0. */
+  minFreezeStep: number;
 }
 
+/** Images Anthropic accepts per request. Exceeding it fails the WHOLE request with
+ *  an opaque `500` (observed 2026-07-31 at 387 images), not a typed 400 — so the
+ *  cap has to be enforced on our side, before the wire. */
+export const ANTHROPIC_MAX_IMAGES = 100;
+
+/** Default history-image budget: the hard cap minus headroom for the slab, tool-doc
+ *  and tool_result images that share the same request. transform.ts narrows this
+ *  further with the count it has already emitted for this very request. */
+export const ANTHROPIC_HISTORY_IMAGE_BUDGET = 80;
+
 export const HISTORY_DEFAULTS: HistoryCollapseOptions = {
   keepTail: 4,
   minCollapsePrefix: 10,
@@ -88,6 +121,12 @@ export const HISTORY_DEFAULTS: HistoryCollapseOptions = {
   reflow: true,
   style: DENSE_RENDER_STYLE,
   maxHeightPx: MAX_HEIGHT_PX,
+  // MUST agree with `cols` above: pageChars is what the budget arithmetic thinks
+  // one image holds, and DENSE_CONTENT_CHARS_PER_IMAGE is only true at 312 cols.
+  pageChars: maxCharsPerImage(100),
+  imageBudget: ANTHROPIC_HISTORY_IMAGE_BUDGET,
+  packFill: false,
+  minFreezeStep: 0,
 };
 
 /** Per-request telemetry surfaced back to TransformInfo. */
@@ -120,7 +159,16 @@ export interface HistoryCollapseInfo {
     | 'prefix_too_short'
     | 'no_closed_prefix'
     | 'not_profitable'
-    | 'render_empty';
+    | 'render_empty'
+    | 'over_budget';
+  /** Freeze step actually used (messages per chunk). Larger than `o.freezeChunk`
+   *  when the image budget or fill-repack forced chunks to merge. The caller pins
+   *  it per session (`minFreezeStep`) so the coarser grid never falls back — a
+   *  fallback would re-key every frozen chunk it already paid to cache. */
+  freezeStep?: number;
+  /** True when the collapse range had to be shortened to stay inside the image
+   *  budget; the dropped tail stays as live text. */
+  budgetTrimmed?: boolean;
   /** Dropped codepoints from the history render, merged into the
    *  transform-wide map by the caller. */
   droppedChars: number;
@@ -571,6 +619,15 @@ async function userTurnBlocks(
 ): Promise<ContentBlock[]> {
   const out: ContentBlock[] = [];
   let pending: string[] = [];
+  // Over-cap prompts are collected and rendered TOGETHER at the end of the chunk.
+  // One image per pasted document would put a floor of ≥1 image on every such turn
+  // that no grid coarsening can lift: a session with 175 pasted logs rendered 175
+  // near-empty images and blew the 100-image cap (#161), which upstream answers with
+  // a 500 rather than a usable error. Batching packs them at ~28k chars/image and
+  // makes the count a function of BYTES, which the freeze grid can actually control.
+  // Within a chunk the order is fixed and the chunk is frozen once closed, so the
+  // grouped bytes are as stable as the transcript image next to them.
+  const imaged: { idx: number; typed: string }[] = [];
   const flush = () => {
     if (pending.length === 0) return;
     out.push({
@@ -588,19 +645,33 @@ async function userTurnBlocks(
       pending.push(`<user t="${i}">${typed}</user>`);
       continue;
     }
-    // Over the cap: this one prompt becomes its own image, kept separate from the
-    // history transcript image so it stays independently readable and attributable.
-    flush();
+    // Past the cap this is a pasted document, not an instruction: it is rendered
+    // verbatim below instead of bloating the text.
+    imaged.push({ idx: i, typed });
+  }
+  flush();
+  if (imaged.length > 0) {
+    // Every batched turn is NAMED (attribution is the point), but only the newest
+    // few carry a preview: 60 pasted docs × a 300-char preview is a wall of text
+    // that buys nothing the images below don't already say, verbatim.
+    const PREVIEW_LIMIT = 8;
+    const previews = imaged
+      .map((u, k) =>
+        k >= imaged.length - PREVIEW_LIMIT
+          ? `<user t="${u.idx}"> (${u.typed.length} chars) Preview: ${compactPreview(u.typed)}`
+          : `<user t="${u.idx}"> (${u.typed.length} chars)`,
+      )
+      .join('\n');
+    out.push({
+      type: 'text',
+      text: `[${imaged.length} user turn(s) from this session were too long to carry as text; they are rendered verbatim, in turn order, in the image(s) immediately below, separate from the history transcript. Each begins with its own <user t="N"> tag. PRIOR context, not the current request.\n${previews}]`,
+    });
     const imgs = await renderTextToPngsWithCharLimit(
-      `<user t="${i}">\n${typed}\n</user>`,
+      imaged.map((u) => `<user t="${u.idx}">\n${u.typed}\n</user>`).join('\n\n'),
       DENSE_CONTENT_COLS,
       DENSE_CONTENT_CHARS_PER_IMAGE,
       DENSE_RENDER_STYLE,
     );
-    out.push({
-      type: 'text',
-      text: `[<user t="${i}"> was too long to carry as text (${typed.length} chars); it is rendered verbatim in the image(s) immediately below, separate from the history transcript. PRIOR context, not the current request. Preview: ${compactPreview(typed)}]`,
-    });
     for (const img of imgs) {
       out.push({
         type: 'image',
@@ -613,7 +684,6 @@ async function userTurnBlocks(
       onImage(img);
     }
   }
-  flush();
   return out;
 }
 
@@ -704,11 +774,60 @@ export async function collapseHistory(
   }
   // Need at least minCollapsePrefix turns in [protectedPrefix..boundary] — collapsing
   // 2-3 turns is net cost (cache-amortization math doesn't work at small scale).
-  const collapseLen = boundary + 1;
+  let collapseLen = boundary + 1;
   if (collapseLen - protectedPrefix < o.minCollapsePrefix) {
     info.reason = 'prefix_too_short';
     return { messages, info };
   }
+
+  // ---- Image budget ---------------------------------------------------------
+  // Anthropic rejects the WHOLE request past ANTHROPIC_MAX_IMAGES with an opaque
+  // 500, so the budget is a hard constraint we must enforce before the wire. Price
+  // candidate grids off per-message serialized lengths: one pass here replaces
+  // re-serializing the transcript once per candidate step.
+  const budget = o.imageBudget > 0 ? o.imageBudget : Infinity;
+  const pageChars = Math.max(1, o.pageChars);
+  const msgLen: number[] = [];
+  // Over-cap user prompts are imaged too (userTurnBlocks), batched per chunk. They
+  // are NOT part of the transcript segments, so they must be priced separately or
+  // the estimate silently under-counts and the wire limit is what finds out.
+  const userImgLen: number[] = [];
+  for (let i = protectedPrefix; i < collapseLen; i++) {
+    const seg = messagesToHistorySegments(messages, i + 1, i).text;
+    msgLen.push(seg.length === 0 ? 0 : seg.length + 2); // +2 = the "\n\n" joiner
+    const m = messages[i]!;
+    const typed = m.role === 'user' ? typedUserText(m.content) : '';
+    userImgLen.push(typed && typed.length > USER_TEXT_MAX_CHARS ? typed.length + 20 : 0);
+  }
+  const sumOf = (arr: number[], from: number, to: number): number => {
+    let n = 0;
+    for (let i = from; i < to; i++) n += arr[i]!;
+    return n;
+  };
+  const sumLen = (from: number, to: number): number => sumOf(msgLen, from, to);
+  const perfectPages =
+    Math.ceil(sumLen(0, msgLen.length) / pageChars) +
+    Math.ceil(sumOf(userImgLen, 0, userImgLen.length) / pageChars);
+  if (perfectPages > budget) {
+    // Even a perfectly packed render of the full range overflows. Keep the OLDEST
+    // messages collapsed (the frozen prefix must stay anchored at protectedPrefix
+    // or every cached chunk re-keys) and leave the tail as live text.
+    let acc = 0;
+    let k = 0;
+    while (k < msgLen.length && acc + msgLen[k]! + userImgLen[k]! <= budget * pageChars) {
+      acc += msgLen[k]! + userImgLen[k]!;
+      k++;
+    }
+    const trimmedLen = findClosedPrefixBoundary(messages, protectedPrefix + k) + 1;
+    if (trimmedLen - protectedPrefix < o.minCollapsePrefix) {
+      info.reason = 'over_budget';
+      return { messages, info };
+    }
+    collapseLen = trimmedLen;
+    msgLen.length = collapseLen - protectedPrefix;
+    info.budgetTrimmed = true;
+  }
+
   // Exclude slab messages (protectedPrefix) from serialization.
   const text = messagesToHistoryText(messages, collapseLen, protectedPrefix);
   if (!text || text.length === 0) {
@@ -738,7 +857,43 @@ export async function collapseHistory(
   // cacheable image boundary instead of being silently flattened (count conserved,
   // never added). Each chunk is reflowed and rendered on its own, which is what
   // makes the bytes a pure function of the chunk's messages.
-  const step = o.freezeChunk > 0 ? o.freezeChunk : collapseLen - protectedPrefix;
+  //
+  // The grid step is ADAPTIVE. A fixed 10-message step emits ≥1 page per chunk no
+  // matter how little text the chunk holds: a long session of short turns rendered
+  // 317 pages at 43% fill and 500'd the request (#161). Doubling the step merges
+  // neighbouring chunks — pages fill up, count drops ~2× per doubling — while
+  // keeping chunk boundaries a SUBSET of the base grid, so a chunk frozen at the
+  // coarse step spans whole base chunks and stays byte-identical as long as the
+  // step never shrinks again (the caller pins it via minFreezeStep).
+  const baseStep = o.freezeChunk > 0 ? o.freezeChunk : collapseLen - protectedPrefix;
+  const rangeLen = collapseLen - protectedPrefix;
+  const pagesFor = (s: number): number => {
+    let pages = 0;
+    for (let a = 0; a < rangeLen; a += s) {
+      const b = Math.min(a + s, rangeLen);
+      const chars = sumLen(a, b);
+      if (chars > 0) pages += Math.ceil(chars / pageChars);
+      // Over-cap user prompts in this chunk are batched into their own image(s).
+      const uchars = sumOf(userImgLen, a, b);
+      if (uchars > 0) pages += Math.ceil(uchars / pageChars);
+    }
+    return pages;
+  };
+  // Caller cache_control marks force extra splits below; charge one page each so a
+  // marked request can't slip past the budget the estimate just cleared.
+  let markSplits = 0;
+  for (let i = protectedPrefix; i < collapseLen; i++) {
+    if (messageCacheControl(messages[i]!) !== undefined) markSplits++;
+  }
+  let step = baseStep;
+  // Sticky floor first: a session already repacked coarse must STAY coarse.
+  while (step < o.minFreezeStep && step < rangeLen) step *= 2;
+  // packFill trades the append-only freeze for ~2× fewer image tokens and is only
+  // set when the upstream cache is dead anyway (cold session / after a 500).
+  const packedPages = Math.max(1, Math.ceil(sumLen(0, rangeLen) / pageChars));
+  const goal = Math.min(budget, o.packFill ? packedPages + 1 : Infinity);
+  while (step < rangeLen && pagesFor(step) + markSplits > goal) step *= 2;
+  info.freezeStep = step;
   const ends = new Set<number>();
   for (let e = protectedPrefix + step; e < collapseLen; e += step) ends.add(e);
   const markerByEnd = new Map<number, CacheControl>();
diff --git a/src/core/render.ts b/src/core/render.ts
index 924a0ead9..90fb21316 100644
--- a/src/core/render.ts
+++ b/src/core/render.ts
@@ -257,6 +257,23 @@ export const DEFAULT_CELL_H_BONUS = 0;
 export const CELL_W = ATLAS_CELL_W + DEFAULT_CELL_W_BONUS;
 export const CELL_H = ATLAS_CELL_H + DEFAULT_CELL_H_BONUS;
 
+/** Visual rows per image: `floor((MAX_HEIGHT_PX − 2·PAD_Y) / CELL_H)`. Derived
+ *  from the cell geometry above so break-even math auto-tracks it. */
+export const LINES_PER_IMAGE = Math.max(1, Math.floor((MAX_HEIGHT_PX - 2 * PAD_Y) / CELL_H));
+
+/** Real char capacity of one page AT A GIVEN COLUMN WIDTH.
+ *
+ *  Lives here, next to the geometry it is derived from, because every caller that
+ *  budgets images must price pages at the width it actually renders at. The
+ *  DENSE_CONTENT_CHARS_PER_IMAGE constant is only correct for DENSE_CONTENT_COLS
+ *  (312×90); using it while rendering at, say, COLS=100 overstates capacity 3.1×,
+ *  so an image budget clears a plan that then emits 3× the images — the request
+ *  blows the API's per-request limit and comes back 500. Always pass the cols the
+ *  renderer will actually use. */
+export function maxCharsPerImage(cols: number): number {
+  return Math.min(Math.max(1, cols) * LINES_PER_IMAGE, READABLE_CHARS_PER_IMAGE);
+}
+
 export interface RenderedImage {
   png: Uint8Array;
   width: number;
diff --git a/src/core/session-state.ts b/src/core/session-state.ts
new file mode 100644
index 000000000..ddb33aa16
--- /dev/null
+++ b/src/core/session-state.ts
@@ -0,0 +1,146 @@
+/**
+ * Per-session cache-liveness state for the history collapse.
+ *
+ * ## Why this exists
+ *
+ * The history grid is append-only: chunk N's pixels are a pure function of its
+ * message range, so old chunks stay byte-identical as the conversation grows and
+ * ride Anthropic's prompt cache as `cache_read` forever. That freeze is worth a
+ * lot — but only while a cache actually exists. Two situations end it:
+ *
+ *  1. **Idle gap.** Anthropic's ephemeral prefix cache lives {@link CACHE_TTL_SEC}
+ *     seconds past the last hit. Resume a session the next morning and every
+ *     block is `cache_create` again no matter what we send.
+ *  2. **A rejected request.** An oversized request (opaque `500`, see
+ *     {@link ANTHROPIC_MAX_IMAGES}) never populated a cache entry at all.
+ *
+ * In both cases the append-only freeze protects nothing, and the grid is free to
+ * be re-cut for *density* instead: {@link HistoryCollapseOptions.packFill} raises
+ * the freeze step until the pages are nearly full, which roughly halves image
+ * tokens on long sessions of short turns (#161: 317 images at 43% fill).
+ *
+ * ## Why the step is sticky
+ *
+ * Once a session has been repacked coarse, every later turn must keep at least
+ * that step. Falling back to the fine grid would re-cut the same messages into
+ * different chunks — every chunk's bytes change, and the whole history re-keys as
+ * `cache_create`. {@link recordFreezeStep} pins the floor; the collapse only ever
+ * doubles it.
+ *
+ * ## Failure mode we deliberately accept
+ *
+ * State is in-memory and per proxy process. After a restart a live session looks
+ * *unknown*, and unknown is treated as WARM (no repack) — the conservative
+ * choice: at worst we keep paying the old image count, we never nuke a live cache
+ * on a guess. The state re-arms itself on the first idle gap after the restart.
+ */
+
+import { CACHE_TTL_SEC } from './baseline.js';
+
+/** Sessions tracked before the oldest is evicted. One small record each. */
+const SESSIONS_MAX = 512;
+
+/**
+ * Grace added to the provider TTL before we call a cache dead. Our clock is the
+ * request-arrival time, the provider's is its own; a request that lands one
+ * second inside the window can still miss. Only gaps clearly past the TTL flip
+ * the session cold, so a borderline case keeps the (cheap, correct) warm path.
+ */
+const COLD_GRACE_MS = 30_000;
+
+interface SessionRecord {
+  /** Wall-clock ms of the last request we saw for this session. */
+  lastSeenMs: number;
+  /** Coarsest freeze step this session has been rendered at, in messages. */
+  freezeStep: number;
+  /** Set when a request for this session failed in a way that leaves no cache. */
+  cacheDead: boolean;
+}
+
+const sessions = new Map<string, SessionRecord>();
+
+function touch(key: string): SessionRecord {
+  const existing = sessions.get(key);
+  if (existing) {
+    sessions.delete(key); // refresh LRU position
+    sessions.set(key, existing);
+    return existing;
+  }
+  const fresh: SessionRecord = { lastSeenMs: 0, freezeStep: 0, cacheDead: false };
+  sessions.set(key, fresh);
+  while (sessions.size > SESSIONS_MAX) {
+    const oldest = sessions.keys().next().value;
+    if (oldest === undefined) break;
+    sessions.delete(oldest);
+  }
+  return fresh;
+}
+
+export interface HistorySessionState {
+  /** The upstream prefix cache is provably gone — re-cutting the grid is free. */
+  cold: boolean;
+  /** Floor for the freeze step, in messages. 0 = no constraint. */
+  minFreezeStep: number;
+}
+
+/** Neutral answer for callers without a session identity (no fingerprint yet). */
+const UNKNOWN_STATE: HistorySessionState = { cold: false, minFreezeStep: 0 };
+
+/**
+ * Record a request for `sessionKey` and report what the history collapse may
+ * assume about the upstream cache. Call once per transformed request, BEFORE the
+ * collapse runs; it advances the session's last-seen clock.
+ *
+ * A session we have never seen counts as warm (see module docs) — unknown must
+ * never authorize a repack.
+ */
+export function noteHistoryRequest(
+  sessionKey: string | undefined,
+  nowMs: number = Date.now(),
+): HistorySessionState {
+  if (!sessionKey) return UNKNOWN_STATE;
+  const rec = touch(sessionKey);
+  const known = rec.lastSeenMs > 0;
+  const idleMs = nowMs - rec.lastSeenMs;
+  const expired = known && idleMs > CACHE_TTL_SEC * 1000 + COLD_GRACE_MS;
+  const cold = rec.cacheDead || expired;
+  rec.lastSeenMs = nowMs;
+  rec.cacheDead = false; // consumed: this request gets the repack
+  return { cold, minFreezeStep: rec.freezeStep };
+}
+
+/**
+ * Pin the grid this session was last rendered at. Monotonic: the floor only ever
+ * rises, because a later, finer render would re-key every chunk it re-cuts.
+ */
+export function recordFreezeStep(
+  sessionKey: string | undefined,
+  step: number | undefined,
+): void {
+  if (!sessionKey || !step || !Number.isFinite(step) || step <= 0) return;
+  const rec = touch(sessionKey);
+  if (step > rec.freezeStep) rec.freezeStep = step;
+}
+
+/**
+ * Mark this session's upstream cache as gone: the last request was rejected, so
+ * nothing was cached and the next one may re-cut the grid for density. Call on
+ * the failure paths that leave no cache entry (oversized request → opaque 500).
+ */
+export function markCacheDead(sessionKey: string | undefined): void {
+  if (!sessionKey) return;
+  touch(sessionKey).cacheDead = true;
+}
+
+/** Test seam: drop all session state. */
+export function resetSessionState(): void {
+  sessions.clear();
+}
+
+/** Test/telemetry seam: inspect a session without mutating its clock. */
+export function peekSessionState(
+  sessionKey: string,
+): { lastSeenMs: number; freezeStep: number; cacheDead: boolean } | undefined {
+  const rec = sessions.get(sessionKey);
+  return rec ? { ...rec } : undefined;
+}
diff --git a/src/core/tracker.ts b/src/core/tracker.ts
index 8f44ef87d..07e9ddb54 100644
--- a/src/core/tracker.ts
+++ b/src/core/tracker.ts
@@ -27,6 +27,14 @@ export interface TrackEvent {
    *  Compare with image_count: textTokens(n/4) vs imageTokens(n×2500). */
   compressed_chars?: number;
   image_count?: number;
+  /** Images the CLIENT already put on the wire (pasted screenshots, tool-returned
+   *  pictures). They spend from the same provider cap as ours, so this is the
+   *  number that explains an otherwise-surprising image_budget passthrough. */
+  native_images?: number;
+  /** Imaging paths that degraded to text because the wire cap was full. Nonzero
+   *  here plus a fat request means the client's own images crowded us out — the
+   *  request stayed valid, but the token win was skipped. */
+  image_budget_skips?: number;
   image_bytes?: number;
   /** Total pixel area across all rendered images; pairs with cache_create_tokens for px/token regression. */
   image_pixels?: number;
@@ -222,6 +230,10 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
       out.compressed_chars = info.compressedChars;
     }
     if (info.imageCount !== undefined) out.image_count = info.imageCount;
+    // Only when nonzero: a wire without client images is the common case and
+    // should not pay a key per event.
+    if ((info.nativeImages ?? 0) > 0) out.native_images = info.nativeImages;
+    if ((info.imageBudgetSkips ?? 0) > 0) out.image_budget_skips = info.imageBudgetSkips;
     if (info.imageBytes !== undefined) out.image_bytes = info.imageBytes;
     if (info.imagePixels !== undefined && info.imagePixels > 0) {
       out.image_pixels = info.imagePixels;
@@ -275,7 +287,7 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
     }
     if (info.passthroughReasons) {
       const pr = info.passthroughReasons;
-      if ((pr.below_threshold ?? 0) > 0 || (pr.not_profitable ?? 0) > 0) {
+      if (Object.values(pr).some((n) => (n ?? 0) > 0)) {
         out.passthrough_reasons = pr;
       }
     }
diff --git a/src/core/transform.ts b/src/core/transform.ts
index 6d77114a9..f4b150a63 100644
--- a/src/core/transform.ts
+++ b/src/core/transform.ts
@@ -34,6 +34,8 @@ import {
   renderTextToPngsWithCharLimit,
   renderCellHeight,
   renderCellWidth,
+  LINES_PER_IMAGE,
+  maxCharsPerImage,
   type RenderStyle,
 } from './render.js';
 import {
@@ -43,7 +45,13 @@ import {
 import { factSheetText } from './factsheet.js';
 import { stripSchemaDescriptions, schemaHasStructure } from './schema-strip.js';
 import { bytesToBase64 } from './png.js';
-import { collapseHistory, HISTORY_SYNTHETIC_INTRO } from './history.js';
+import {
+  collapseHistory,
+  HISTORY_SYNTHETIC_INTRO,
+  ANTHROPIC_MAX_IMAGES,
+  ANTHROPIC_HISTORY_IMAGE_BUDGET,
+} from './history.js';
+import { noteHistoryRequest, recordFreezeStep } from './session-state.js';
 import type { GptHistoryOptions } from './openai-history.js';
 import { CACHE_CREATE_RATE, CACHE_READ_RATE } from './baseline.js';
 import { visionTokens, type VisionPricing } from './vision-cost.js';
@@ -303,10 +311,17 @@ function imageTokensCost(
 /** Gate geometry for dense tool-result, reminder, and history pages. */
 function denseGateGeometry(o?: Required<TransformOptions>): GateGeometry {
   const profile = o?.model ? resolveGptProfile(o.model) : undefined;
+  const cols = o?.cols ?? profile?.stripCols ?? DENSE_CONTENT_COLS;
   return {
-    cols: o?.cols ?? profile?.stripCols ?? DENSE_CONTENT_COLS,
+    cols,
     maxHeightPx: profile?.maxHeightPx ?? MAX_HEIGHT_PX,
-    maxChars: DENSE_CONTENT_CHARS_PER_IMAGE,
+    // Price a page at the width we actually render at, NOT at the 312-col constant.
+    // These are the same number in the default Anthropic geometry, but a narrower
+    // COLS (env override, GPT strip profile) holds proportionally fewer chars: the
+    // old constant overstated capacity up to 3.1× at COLS=100, so the history image
+    // budget cleared a plan that then emitted 3× the images and the oversized
+    // request came back 500. Capacity must track cols or the budget is fiction.
+    maxChars: maxCharsPerImage(cols),
     style: profile?.style ?? DENSE_RENDER_STYLE,
     // No model on the request (Anthropic slab path): price at the Claude
     // profile, which is what is actually serving it.
@@ -314,13 +329,10 @@ function denseGateGeometry(o?: Required<TransformOptions>): GateGeometry {
   };
 }
 
-/** Visual rows per image: `floor((MAX_HEIGHT_PX − 2·PAD_Y) / CELL_H)`. Derived
- *  from render.ts constants so break-even math auto-tracks cell geometry changes. */
-export const LINES_PER_IMAGE = Math.max(1, Math.floor((MAX_HEIGHT_PX - 2 * PAD_Y) / CELL_H));
-
-export function maxCharsPerImage(cols: number): number {
-  return Math.min(cols * LINES_PER_IMAGE, READABLE_CHARS_PER_IMAGE);
-}
+/** Re-exported from render.ts, which owns the cell geometry these derive from.
+ *  Kept exported here because the eval harnesses and gpt paths import them from
+ *  transform. Single implementation, so the page-capacity math can't fork. */
+export { LINES_PER_IMAGE, maxCharsPerImage };
 
 /** Lossless pre-render whitespace compactor (each `\n` costs ≥1 visual row):
  *  1. Strip trailing whitespace per line (preserves leading indent).
@@ -479,7 +491,7 @@ export function isCompressionProfitableAmortized(
 /** Increment a passthrough-reason counter on `info`. Lazily allocates `passthroughReasons`. */
 function bumpPassthrough(
   info: TransformInfo,
-  reason: 'below_threshold' | 'not_profitable' | 'kept_sharp',
+  reason: 'below_threshold' | 'not_profitable' | 'kept_sharp' | 'image_budget',
 ): void {
   if (!info.passthroughReasons) info.passthroughReasons = {};
   info.passthroughReasons[reason] = (info.passthroughReasons[reason] ?? 0) + 1;
@@ -635,6 +647,14 @@ export interface TransformInfo {
    *  render may repeat its section source. Dashboard-only; not persisted. */
   imageSourceTexts?: Array<string | undefined>;
   toolResultImgs?: number;
+  /** Image blocks the CLIENT already sent (screenshots, pasted images, prior
+   *  tool_result images). They count against the provider's hard image cap just
+   *  like ours do, so every pxpipe imaging path must price them in — a request
+   *  whose own images already fill the cap must not get a single one from us.
+   *  Counted once, before any rewrite. See {@link imageHeadroom}. */
+  nativeImages?: number;
+  /** Imaging steps skipped because the cap was exhausted (telemetry for tuning). */
+  imageBudgetSkips?: number;
   /** Chars of tool docs moved to the system-text Tool Reference (not imaged). */
   toolDocsChars?: number;
   /** Codepoints missing from the atlas (rendered as blank cells). Telemetry for atlas tuning. */
@@ -642,7 +662,7 @@ export interface TransformInfo {
   /** Top dropped codepoints by frequency (`U+HHHH` → count), at most 20 entries. */
   droppedCodepointsTop?: Record<string, number>;
   /** Why blocks passed through without compression. Only present when count > 0. */
-  passthroughReasons?: { below_threshold?: number; not_profitable?: number; kept_sharp?: number };
+  passthroughReasons?: { below_threshold?: number; not_profitable?: number; kept_sharp?: number; image_budget?: number };
   /** Slab gate diagnostics — imageTokens, textTokens, burn terms, and verdict.
    *  Lets hosts measure flap-prevention efficacy and tune amortization horizon. */
   gateEval?: {
@@ -674,6 +694,15 @@ export interface TransformInfo {
    *  proves Anthropic's prompt cache can `cache_read` (0.1×) instead of `cache_create`.
    *  A changing hash means cache-key drift is back. Only set when collapse produced images. */
   historyImageSha?: string;
+  /** Freeze-grid step the history collapse actually used, in messages. Rises when the
+   *  adaptive packer merges chunks to fit the image budget; must never fall within a
+   *  session (a finer re-cut re-keys every chunk). */
+  historyFreezeStep?: number;
+  /** The collapse re-cut the grid for page fill instead of cache freeze — only set when
+   *  the session's upstream cache was provably dead (idle past TTL, or after a reject). */
+  historyPackFill?: boolean;
+  /** The image budget could not hold the whole closed prefix; the tail stayed live text. */
+  historyBudgetTrimmed?: boolean;
   /** sha8 of the ACTUAL cacheable prefix sent this turn (tools + system +
    *  message blocks through the imaged history/slab boundary; the live tail is
    *  excluded). Read-only measurement. A change turn-over-turn within a session
@@ -711,6 +740,7 @@ export interface TransformInfo {
     | 'not_profitable'
     | 'too_many_images'
     | 'render_empty'
+    | 'over_budget'
     | 'collapsed';
   /** Token count of the pre-compression body from /v1/messages/count_tokens (free).
    *  Absent when probe failed — event excluded from savings rollup. */
@@ -1718,6 +1748,71 @@ function applyPins(req: MessagesRequest, info: TransformInfo, pins: Pin[]): void
  * Called from both the main path AND early-exit paths (below_min_chars,
  * not_profitable) — history collapse must run even when the slab skips.
  * Tolerant to missing/short message arrays (collapseHistory short-circuits). */
+/** Slack between our page estimate and the provider's hard image cap. The renderer
+ *  paginates on its own, so a candidate grid can come out one page heavier than the
+ *  estimator predicted; the request must still land under {@link ANTHROPIC_MAX_IMAGES}. */
+const HISTORY_IMAGE_SAFETY_MARGIN = 5;
+
+/**
+ * Image blocks this request may still add before the provider's hard cap.
+ *
+ * The cap counts EVERY image on the wire: the client's own (`nativeImages`) and
+ * ours (`imageCount`). Pricing only ours is how a request with 103 client images
+ * still got imaged further and came back 400 — the cap is a wire property, not a
+ * pxpipe property. Never negative; callers treat 0 as "keep it as text".
+ */
+export function imageHeadroom(info: TransformInfo): number {
+  return Math.max(
+    0,
+    ANTHROPIC_MAX_IMAGES -
+      HISTORY_IMAGE_SAFETY_MARGIN -
+      info.imageCount -
+      (info.nativeImages ?? 0),
+  );
+}
+
+/** Count image blocks already present in the caller's messages. Runs BEFORE any
+ *  rewrite, so it sees the client's images only — ours do not exist yet. */
+export function countNativeImages(messages: readonly Message[] | undefined): number {
+  let n = 0;
+  for (const m of messages ?? []) {
+    if (!Array.isArray(m.content)) continue;
+    for (const blk of m.content) {
+      const t = (blk as { type?: string } | null)?.type;
+      if (t === 'image') n++;
+      else if (t === 'tool_result') {
+        const inner = (blk as ToolResultBlock).content;
+        if (Array.isArray(inner)) {
+          for (const ib of inner) if ((ib as { type?: string } | null)?.type === 'image') n++;
+        }
+      }
+    }
+  }
+  return n;
+}
+
+/**
+ * Per-request history-grid tuning: how many images the collapse may still spend,
+ * and whether it is allowed to re-cut the grid for density.
+ *
+ * `info.imageCount` already holds every image this request emitted before the
+ * collapse (slab, tool docs, tool_results), so the remaining headroom is the hard
+ * cap minus those, minus a margin for estimator drift — and never more than the
+ * standing cost guard {@link ANTHROPIC_HISTORY_IMAGE_BUDGET}.
+ *
+ * `packFill`/`minFreezeStep` come from the session store: repack only when the
+ * upstream cache is provably dead, and never below a grid this session already
+ * froze at. See {@link noteHistoryRequest}.
+ */
+function historyGridTuning(
+  info: TransformInfo,
+): { imageBudget: number; packFill: boolean; minFreezeStep: number } {
+  const headroom = imageHeadroom(info);
+  const imageBudget = Math.max(1, Math.min(ANTHROPIC_HISTORY_IMAGE_BUDGET, headroom));
+  const session = noteHistoryRequest(info.firstUserSha8);
+  return { imageBudget, packFill: session.cold, minFreezeStep: session.minFreezeStep };
+}
+
 async function runHistoryCollapseAndFinalize(
   req: MessagesRequest,
   info: TransformInfo,
@@ -1727,7 +1822,15 @@ async function runHistoryCollapseAndFinalize(
   pins: Pin[],
 ): Promise<{ body: Uint8Array; info: TransformInfo; collapsed: boolean }> {
   let collapsedFlag = false;
-  if (Array.isArray(req.messages) && req.messages.length > 0) {
+  // Same wire cap as every other imaging path: the collapse buys tokens with
+  // image blocks, and a request whose client images already fill the cap has
+  // none left to spend. `historyGridTuning` floors the budget at 1, so without
+  // this guard a full wire would still emit exactly one image — and 400.
+  if (imageHeadroom(info) <= 0) {
+    bumpPassthrough(info, 'image_budget');
+    info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+    info.historyReason ??= 'too_many_images';
+  } else if (Array.isArray(req.messages) && req.messages.length > 0) {
     const historyCpt = opts.charsPerToken !== undefined
       ? o.charsPerToken
       : HISTORY_CHARS_PER_TOKEN;
@@ -1755,6 +1858,7 @@ async function runHistoryCollapseAndFinalize(
     // message carrying them is protected from collapse the same way the
     // non-collapse path already keeps <system-reminder> as text below.
     const protectedPrefix = firstMessageHasSystemReminder(req.messages) ? 1 : 0;
+    const tuning = historyGridTuning(info);
     const { messages: newMessages, info: histInfo } = await collapseHistory(
       req.messages,
       historyProfitable,
@@ -1764,8 +1868,16 @@ async function runHistoryCollapseAndFinalize(
         reflow: o.reflow,
         style: historyGeometry.style,
         maxHeightPx: historyGeometry.maxHeightPx,
+        pageChars: historyGeometry.maxChars,
+        imageBudget: tuning.imageBudget,
+        packFill: tuning.packFill,
+        minFreezeStep: tuning.minFreezeStep,
       },
     );
+    recordFreezeStep(info.firstUserSha8, histInfo.freezeStep);
+    if (histInfo.freezeStep !== undefined) info.historyFreezeStep = histInfo.freezeStep;
+    if (histInfo.budgetTrimmed) info.historyBudgetTrimmed = true;
+    if (tuning.packFill) info.historyPackFill = true;
     if (histInfo.collapsedTurns > 0) {
       req.messages = newMessages;
       info.collapsedTurns = histInfo.collapsedTurns;
@@ -1858,6 +1970,11 @@ export async function transformRequest(
     return { body, info };
   }
 
+  // Price the caller's OWN images before we rewrite anything: they occupy the
+  // same wire cap we are about to spend from. Counted once, here, because every
+  // later path (slab, tool_results, history) rewrites content in place.
+  info.nativeImages = countNativeImages(req.messages);
+
   // 0. User-pinned instructions. Fold the transcript's pin commands, then remove
   //    them from the outbound copy — the client's own transcript is untouched, so
   //    the next request still carries every command and re-derives the same state.
@@ -2059,6 +2176,18 @@ export async function transformRequest(
     return { body: pinsRewrote ? finalized.body : body, info };
   }
 
+  // The wire cap guards even the slab. Imaging it is our biggest single win, but
+  // a request whose client images already fill the provider's cap has no image
+  // left to spend: emitting one anyway turns a large-but-valid request into a
+  // hard 400. Degrade to plain text and say why.
+  if (imageHeadroom(info) <= 0) {
+    info.reason = 'image_budget';
+    bumpPassthrough(info, 'image_budget');
+    info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+    const finalized = await runHistoryCollapseAndFinalize(req, info, o, opts, droppedCodepoints, pins);
+    return { body: pinsRewrote || finalized.collapsed ? finalized.body : body, info };
+  }
+
   // Break-even check guards even the slab (rare edge: tiny tool docs + tiny slab < 10k chars).
   const denseGeo = denseGateGeometry(o);
   // Use slab cpt (2.0) unless host pinned charsPerToken explicitly.
@@ -2144,6 +2273,23 @@ export async function transformRequest(
     denseGeo.style,
     denseGeo.maxHeightPx,
   );
+  // Quantitative cap, not just "is there room": the slab is many pages, and a
+  // boolean "headroom > 0" check happily emitted 15 of them into a single slot
+  // (measured: 94 client images + 400k slab -> 109 on the wire -> 400). All or
+  // nothing, because the slab is part of the cache prefix — imaging half of it
+  // would re-key that prefix on every turn whose client-image count moved.
+  if (images.length > imageHeadroom(info)) {
+    info.reason = `image_budget (slab needs ${images.length}, headroom ${imageHeadroom(info)})`;
+    bumpPassthrough(info, 'image_budget');
+    info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+    const finalized = await runHistoryCollapseAndFinalize(req, info, o, opts, droppedCodepoints, pins);
+    if (finalized.collapsed) {
+      info.compressed = true;
+      return { body: finalized.body, info };
+    }
+    return { body: pinsRewrote ? finalized.body : body, info };
+  }
+
   const imageBlocks: ImageBlock[] = [];
   for (let i = 0; i < images.length; i++) {
     const img = images[i]!;
@@ -2248,6 +2394,15 @@ export async function transformRequest(
                 rewritten.push(blk);
                 continue;
               }
+              // Hard wire cap: the client's own images plus ours must stay
+              // under the provider's limit, else the WHOLE request is rejected.
+              // Out of headroom → keep the text sharp; a big body beats a 400.
+              if (imageHeadroom(info) <= 0) {
+                bumpPassthrough(info, 'image_budget');
+                info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+                rewritten.push(blk);
+                continue;
+              }
               const inner = compactSlabWhitespace(innerRaw);
               // classifyContent sees pre-reflow `inner` so shape bucketing reflects real structure.
               const innerR = maybeReflow(inner, o.reflow);
@@ -2259,13 +2414,17 @@ export async function transformRequest(
                 rewritten.push(blk);
               } else {
                 // Paging: truncate before render if it would blow the image cap.
+                // The per-result cap is the SMALLER of the configured max and what
+                // is actually left on the wire — the headroom shrinks as earlier
+                // results spend it, so each result sees the live number.
+                const resultImageCap = Math.min(o.maxImagesPerToolResult, imageHeadroom(info));
                 const linesPerImage = Math.max(
                   1,
                   Math.floor((denseGeo.maxHeightPx - 2 * PAD_Y) / renderCellHeight(denseGeo.style)),
                 );
                 const paged = truncateForBudget(
                   innerR,
-                  o.maxImagesPerToolResult,
+                  resultImageCap,
                   denseGeo.cols,
                   denseGeo.maxChars,
                   linesPerImage,
@@ -2282,6 +2441,16 @@ export async function transformRequest(
                     denseGeo.style,
                     denseGeo.maxHeightPx,
                   );
+                // Paging is budgeted at denseGeo.cols but rendering happens at
+                // o.cols; when they differ the real page count can exceed the plan.
+                // Verify against the actual render and drop OUR images rather than
+                // ship a request the provider rejects outright.
+                if (imgs.length > imageHeadroom(info)) {
+                  bumpPassthrough(info, 'image_budget');
+                  info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+                  rewritten.push(blk);
+                  continue;
+                }
                 (info.imagePngs ??= []).push(...rawPngs);
                 (info.imageDims ??= []).push(...rawDims);
                 for (const img of imgs) info.imageBytes += approxBlockBytes(img);
@@ -2327,6 +2496,13 @@ export async function transformRequest(
                   newInner.push(ib as TextBlock | ImageBlock);
                   continue;
                 }
+                // Hard wire cap — see the string-content path above.
+                if (imageHeadroom(info) <= 0) {
+                  bumpPassthrough(info, 'image_budget');
+                  info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+                  newInner.push(ib as TextBlock | ImageBlock);
+                  continue;
+                }
                 // Lossless whitespace compaction before gate + render.
                 const innerText = compactSlabWhitespace(innerTextRaw);
                 // R3: gate/page/render on reflowed text; classify pre-reflow.
@@ -2345,9 +2521,10 @@ export async function transformRequest(
                   1,
                   Math.floor((denseGeo.maxHeightPx - 2 * PAD_Y) / renderCellHeight(denseGeo.style)),
                 );
+                const resultImageCap = Math.min(o.maxImagesPerToolResult, imageHeadroom(info));
                 const paged = truncateForBudget(
                   innerTextR,
-                  o.maxImagesPerToolResult,
+                  resultImageCap,
                   denseGeo.cols,
                   denseGeo.maxChars,
                   linesPerImage,
@@ -2364,6 +2541,16 @@ export async function transformRequest(
                     denseGeo.style,
                     denseGeo.maxHeightPx,
                   );
+                // Paging is budgeted at denseGeo.cols but rendering happens at
+                // o.cols; when they differ the real page count can exceed the plan.
+                // Verify against the actual render and drop OUR images rather than
+                // ship a request the provider rejects outright.
+                if (imgs.length > imageHeadroom(info)) {
+                  bumpPassthrough(info, 'image_budget');
+                  info.imageBudgetSkips = (info.imageBudgetSkips ?? 0) + 1;
+                  newInner.push(ib as TextBlock | ImageBlock);
+                  continue;
+                }
                 (info.imagePngs ??= []).push(...rawPngs);
                 (info.imageDims ??= []).push(...rawDims);
                 const srcCacheControl = demoteRelocatedCacheControl((ib as { cache_control?: unknown }).cache_control);
@@ -2433,6 +2620,7 @@ export async function transformRequest(
       );
     };
     const slabAnchorIdx = (req.messages ?? []).findIndex((m) => m.role === 'user');
+    const tuning = historyGridTuning(info);
     const { messages: newMessages, info: histInfo } = await collapseHistory(
       req.messages,
       historyProfitable,
@@ -2442,8 +2630,16 @@ export async function transformRequest(
         reflow: o.reflow,
         style: historyGeometry.style,
         maxHeightPx: historyGeometry.maxHeightPx,
+        pageChars: historyGeometry.maxChars,
+        imageBudget: tuning.imageBudget,
+        packFill: tuning.packFill,
+        minFreezeStep: tuning.minFreezeStep,
       },
     );
+    recordFreezeStep(info.firstUserSha8, histInfo.freezeStep);
+    if (histInfo.freezeStep !== undefined) info.historyFreezeStep = histInfo.freezeStep;
+    if (histInfo.budgetTrimmed) info.historyBudgetTrimmed = true;
+    if (tuning.packFill) info.historyPackFill = true;
     if (histInfo.collapsedTurns > 0) {
       req.messages = newMessages;
       info.collapsedTurns = histInfo.collapsedTurns;
diff --git a/src/dashboard.ts b/src/dashboard.ts
index f6a21e7c5..993564fc3 100644
--- a/src/dashboard.ts
+++ b/src/dashboard.ts
@@ -29,6 +29,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as readline from 'node:readline';
 import type { ProxyEvent } from './core/proxy.js';
 import type { TrackEvent } from './core/tracker.js';
@@ -1497,7 +1498,7 @@ export class DashboardState {
   }
 
   serveHtml(port: number): Response {
-    return htmlResponse(renderPage(port));
+    return htmlResponse(renderPage(port, dashboardHostLabel()));
   }
 
   /** GET /fragments/<name> — server-rendered htmx fragments. Each one reuses
@@ -1716,6 +1717,22 @@ export function dashboardPath(pathname: string): DashboardRoute | null {
   return null;
 }
 
+/** Name of the machine serving this dashboard, shown in the title and topbar.
+ *  PXPIPE_DASH_LABEL overrides it for hosts whose system hostname says nothing
+ *  useful (containers, "localhost"); an explicitly empty label opts out and
+ *  renders the unlabelled page. */
+export function dashboardHostLabel(): string {
+  const override = process.env.PXPIPE_DASH_LABEL;
+  if (override !== undefined) return override.trim();
+  try {
+    const h = os.hostname().trim();
+    // Keep it short: FQDNs push the chip past the wordmark for no added meaning.
+    return h.split('.')[0] || '';
+  } catch {
+    return '';
+  }
+}
+
 function htmlResponse(body: string): Response {
   return new Response(body, {
     headers: { 'content-type': 'text/html; charset=utf-8' },
diff --git a/src/dashboard/fragments.ts b/src/dashboard/fragments.ts
index 2d8fe88ac..33c6be9b1 100644
--- a/src/dashboard/fragments.ts
+++ b/src/dashboard/fragments.ts
@@ -864,6 +864,10 @@ const CSS = `
     background: radial-gradient(circle at 35% 30%, #ffd0a8, var(--flame) 55%, var(--flame-strong));
     box-shadow: 0 0 0 4px var(--flame-tint); flex: none; }
   .wordmark { font-size: 22px; font-weight: 800; color: var(--ink); letter-spacing: -0.02em; }
+  .wordmark-row { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; }
+  /* Which machine is this? Two dashboards from two hosts look identical otherwise. */
+  .hostchip { font-size: 11.5px; font-weight: 600; color: var(--muted); padding: 1px 7px;
+    border: 1px solid var(--line); border-radius: 999px; white-space: nowrap; }
   .tagline { font-size: 12.5px; color: var(--muted); margin-top: 1px; max-width: 460px; }
   .controls { display: flex; flex-direction: column; align-items: flex-end; gap: 6px; }
 
@@ -1188,14 +1192,19 @@ const THEME_JS = `
   })();
 `;
 
-export function renderPage(port: number): string {
+/** `hostLabel` names the machine this proxy runs on. The dashboard is otherwise
+ *  byte-identical across hosts, so a tab opened against a remote host through
+ *  the tailnet front is indistinguishable from the local one - which is how a
+ *  session gets read on the wrong box. Empty label = render as before. */
+export function renderPage(port: number, hostLabel = ''): string {
+  const host = escapeHtml(hostLabel.trim());
   // hx-trigger="load, every Ns": paint on load then poll (2s live, 5s aggregates).
   return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>pxpipe — live dashboard</title>
+<title>${host ? `${host} · pxpipe dashboard` : 'pxpipe — live dashboard'}</title>
 <link rel="icon" href="${FAVICON}" />
 <style>${CSS}</style>
 <script>
@@ -1215,7 +1224,10 @@ export function renderPage(port: number): string {
   <div class="brand">
     <span class="flame-dot"></span>
     <div>
-      <div class="wordmark">pxpipe</div>
+      <div class="wordmark-row">
+        <div class="wordmark">pxpipe</div>
+        ${host ? `<span class="hostchip" title="proxy host">${host}</span>` : ''}
+      </div>
       <div class="tagline">See exactly what got turned into images to shrink your Claude Code bill.</div>
     </div>
   </div>
diff --git a/tests/dashboard-api.test.ts b/tests/dashboard-api.test.ts
index 4ec2fa9b2..2b662a623 100644
--- a/tests/dashboard-api.test.ts
+++ b/tests/dashboard-api.test.ts
@@ -10,7 +10,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { DashboardState, dashboardPath } from '../src/dashboard.js';
+import { DashboardState, dashboardPath, dashboardHostLabel } from '../src/dashboard.js';
 import { getAllowedModelBases, setAllowedModelBases } from '../src/core/applicability.js';
 import type { SessionsPaths } from '../src/sessions.js';
 import type { TrackEvent } from '../src/core/tracker.js';
@@ -367,6 +367,43 @@ describe('serveFragment', () => {
   });
 });
 
+describe('dashboard host label', () => {
+  it('names the host in the title and topbar so two hosts are distinguishable', () => {
+    const html = renderPage(47821, 'ber-dev-lm-ai');
+    expect(html).toContain('<title>ber-dev-lm-ai · pxpipe dashboard</title>');
+    expect(html).toContain('class="hostchip"');
+    expect(html).toContain('>ber-dev-lm-ai<');
+  });
+
+  it('renders the unlabelled page when no host label is given', () => {
+    const html = renderPage(47821);
+    expect(html).toContain('<title>pxpipe — live dashboard</title>');
+    expect(html).not.toContain('class="hostchip"');
+  });
+
+  it('escapes the label instead of injecting it as markup', () => {
+    const html = renderPage(47821, '<img src=x onerror=alert(1)>');
+    expect(html).not.toContain('<img src=x');
+    expect(html).toContain('&lt;img src=x');
+  });
+
+  it('prefers PXPIPE_DASH_LABEL and shortens an FQDN hostname', () => {
+    const prev = process.env.PXPIPE_DASH_LABEL;
+    try {
+      process.env.PXPIPE_DASH_LABEL = 'edi-prod';
+      expect(dashboardHostLabel()).toBe('edi-prod');
+      // An explicitly empty override opts out of the chip entirely.
+      process.env.PXPIPE_DASH_LABEL = '';
+      expect(dashboardHostLabel()).toBe('');
+      delete process.env.PXPIPE_DASH_LABEL;
+      expect(dashboardHostLabel()).toBe(os.hostname().split('.')[0]);
+    } finally {
+      if (prev === undefined) delete process.env.PXPIPE_DASH_LABEL;
+      else process.env.PXPIPE_DASH_LABEL = prev;
+    }
+  });
+});
+
 describe('dashboard page help UI', () => {
   it('ships visible hover/focus tooltip CSS for question-mark controls', () => {
     const html = renderPage(47821);
diff --git a/tests/history-grid-e2e.test.ts b/tests/history-grid-e2e.test.ts
new file mode 100644
index 000000000..f5ce1d99b
--- /dev/null
+++ b/tests/history-grid-e2e.test.ts
@@ -0,0 +1,161 @@
+/**
+ * End-to-end contract for the adaptive history grid, as wired into
+ * `transformRequest` (not the unit level — `history.test.ts` covers the packer
+ * itself). These pin the three properties the session-500s taught us:
+ *
+ *   1. a request can never exceed the provider's hard image cap, no matter how
+ *      large the conversation grows,
+ *   2. the freeze grid never gets FINER within a session (a re-cut re-keys every
+ *      chunk and burns the whole prefix as cache_create), and
+ *   3. dense repacking only happens once the upstream cache is provably dead.
+ *
+ * Run just this file:  pnpm vitest run tests/history-grid-e2e.test.ts
+ */
+import { beforeEach, describe, expect, it } from 'vitest';
+import { transformRequest } from '../src/core/transform.js';
+import { ANTHROPIC_MAX_IMAGES } from '../src/core/history.js';
+import { markCacheDead, resetSessionState } from '../src/core/session-state.js';
+import type { Message } from '../src/core/types.js';
+
+const big = (n: number) => 'x'.repeat(n);
+
+function enc(obj: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(obj));
+}
+function dec(b: Uint8Array): any {
+  return JSON.parse(new TextDecoder().decode(b));
+}
+function countImages(msgs: Message[]): number {
+  let n = 0;
+  for (const m of msgs) {
+    if (!Array.isArray(m.content)) continue;
+    for (const b of m.content as any[]) if (b?.type === 'image') n++;
+  }
+  return n;
+}
+
+/**
+ * `n` closed turns. The first user message is held constant across calls so the
+ * session key (sha8 of the first user text) is stable — that is exactly how the
+ * proxy identifies a conversation.
+ */
+function convo(n: number, chars = 3500): Message[] {
+  const out: Message[] = [{ role: 'user', content: 'SESSION ANCHOR: ' + big(200) }];
+  for (let i = 0; i < n; i++) {
+    const body = `turn ${i}: ` + big(chars);
+    out.push({ role: i % 2 === 0 ? 'assistant' : 'user', content: body });
+  }
+  return out;
+}
+
+function request(messages: Message[]): Uint8Array {
+  return enc({ model: 'claude-3-5-sonnet', messages });
+}
+
+describe('history grid wiring — image budget', () => {
+  beforeEach(() => resetSessionState());
+
+  it('stays under the provider image cap for a conversation far past the budget', async () => {
+    // ~1.4M chars of history. At one page per ~2k chars an unbounded grid would
+    // want hundreds of images; the packer must merge chunks until it fits.
+    const { body: out, info } = await transformRequest(request(convo(400, 3500)));
+    const images = countImages(dec(out).messages);
+
+    expect(images).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+    expect(info.collapsedTurns).toBeGreaterThan(0);
+    // It fit by coarsening the grid and/or leaving the tail live — either way it
+    // must have reported which lever it pulled.
+    expect(
+      (info.historyFreezeStep ?? 0) > 1 || info.historyBudgetTrimmed === true,
+    ).toBe(true);
+  });
+
+  // The regression behind the two unresumable sessions: the budget priced a page
+  // at the 312-col constant while the pages were actually rendered at the
+  // request's `cols`. At COLS=100 a page holds ~3.1× less text, so a plan that
+  // "fit" 100 images emitted ~300 and the provider 500'd. The cap has to hold at
+  // every geometry we can be driven at, not just the default one.
+  it.each([80, 100, 200, 312])('stays under the cap at cols=%i', async (cols) => {
+    const { body: out, info } = await transformRequest(request(convo(400, 3500)), { cols });
+    expect(countImages(dec(out).messages)).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+    expect(info.collapsedTurns).toBeGreaterThan(0);
+  });
+
+  it('keeps total images (slab + tool docs + history) under the cap', async () => {
+    const body = enc({
+      model: 'claude-3-5-sonnet',
+      system: [{ type: 'text', text: big(120_000) }],
+      messages: convo(300, 3500),
+    });
+    const { body: out } = await transformRequest(body);
+    expect(countImages(dec(out).messages)).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+  });
+});
+
+describe('history grid wiring — freeze step is monotonic per session', () => {
+  beforeEach(() => resetSessionState());
+
+  it('never re-cuts to a finer grid as the conversation grows', async () => {
+    const steps: number[] = [];
+    for (const turns of [40, 120, 260, 400]) {
+      const { info } = await transformRequest(request(convo(turns, 3500)));
+      if (info.historyFreezeStep !== undefined) steps.push(info.historyFreezeStep);
+    }
+    expect(steps.length).toBeGreaterThan(1);
+    for (let i = 1; i < steps.length; i++) {
+      expect(steps[i]!).toBeGreaterThanOrEqual(steps[i - 1]!);
+    }
+  });
+
+  it('shrinking back to a short history does not re-cut finer either', async () => {
+    const grown = await transformRequest(request(convo(400, 3500)));
+    const coarse = grown.info.historyFreezeStep ?? 0;
+    expect(coarse).toBeGreaterThan(1);
+
+    // Same session, but the caller replays a much shorter prefix (e.g. after an
+    // edit). A finer grid here would re-key every surviving chunk.
+    const again = await transformRequest(request(convo(60, 3500)));
+    expect(again.info.historyFreezeStep ?? coarse).toBeGreaterThanOrEqual(coarse);
+  });
+
+  it('a different session gets its own grid', async () => {
+    await transformRequest(request(convo(400, 3500)));
+    const other: Message[] = [
+      { role: 'user', content: 'A COMPLETELY DIFFERENT ANCHOR: ' + big(200) },
+      ...convo(40, 3500).slice(1),
+    ];
+    const { info } = await transformRequest(request(other));
+    // Fresh key ⇒ no inherited floor; the small history collapses on a fine grid.
+    expect(info.historyPackFill).toBeUndefined();
+  });
+});
+
+describe('history grid wiring — packFill only on a dead cache', () => {
+  beforeEach(() => resetSessionState());
+
+  it('does not repack while the upstream cache may still be warm', async () => {
+    const { info } = await transformRequest(request(convo(120, 3500)));
+    expect(info.historyPackFill).toBeUndefined();
+  });
+
+  it('repacks after the cache was marked dead (e.g. an upstream reject)', async () => {
+    const first = await transformRequest(request(convo(120, 3500)));
+    const key = first.info.firstUserSha8;
+    expect(key).toBeTruthy();
+
+    markCacheDead(key);
+
+    const second = await transformRequest(request(convo(120, 3500)));
+    expect(second.info.historyPackFill).toBe(true);
+    // Denser pages ⇒ never more images than the cache-friendly cut.
+    expect(second.info.imageCount).toBeLessThanOrEqual(first.info.imageCount);
+  });
+
+  it('the dead-cache flag is consumed — the next turn is append-only again', async () => {
+    const first = await transformRequest(request(convo(120, 3500)));
+    markCacheDead(first.info.firstUserSha8);
+    await transformRequest(request(convo(120, 3500)));
+    const third = await transformRequest(request(convo(130, 3500)));
+    expect(third.info.historyPackFill).toBeUndefined();
+  });
+});
diff --git a/tests/history.test.ts b/tests/history.test.ts
index eff68e666..9b287a179 100644
--- a/tests/history.test.ts
+++ b/tests/history.test.ts
@@ -443,7 +443,7 @@ describe('collapseHistory', () => {
 
     const content = out[0]!.content as Array<Record<string, unknown>>;
     const textBlocks = content.filter((c) => c.type === 'text') as Array<{ text: string }>;
-    const cue = textBlocks.find((b) => b.text.includes('was too long to carry as text'))!;
+    const cue = textBlocks.find((b) => b.text.includes('too long to carry as text'))!;
     expect(cue.text).toContain(`<user t="10">`);
     // The over-cap prompt is imaged separately, so it never lands in the verbatim block.
     const verbatim = textBlocks.find((b) => b.text.includes('User turns from this session'))!;
@@ -453,6 +453,38 @@ describe('collapseHistory', () => {
     expect(transcript.text).not.toContain('PASTED DOC');
   });
 
+  it('batches many over-cap user prompts so images scale with bytes, not with prompt count', async () => {
+    // Regression (#161): one image per pasted document put a floor of ≥1 image on
+    // every such turn that no grid coarsening could lift — 175 pasted logs rendered
+    // 175 near-empty images, past the wire cap, and upstream answered 500.
+    const msgs: Message[] = [];
+    for (let i = 0; i < 120; i++) {
+      msgs.push(i % 2 === 0 ? usr('PASTED ' + 'y'.repeat(3500)) : asst(`turn ${i}: ` + 'x'.repeat(400)));
+    }
+
+    const { messages: out, info } = await collapseHistory(msgs, profitable, {
+      keepTail: 2,
+      minCollapsePrefix: 5,
+      cols: 100,
+      collapseChunk: 0,
+      imageBudget: 100,
+    });
+
+    const content = out[0]!.content as Array<Record<string, unknown>>;
+    const images = content.filter((c) => c.type === 'image').length;
+    // 59 over-cap prompts: one image each would be ≥59 on top of the transcript.
+    expect(images).toBeLessThanOrEqual(100);
+    expect(images).toBeLessThan(59);
+    // The estimate the budget cleared must be the count that actually goes out.
+    expect(info.collapsedImages).toBe(images);
+    const textBlocks = content.filter((c) => c.type === 'text') as Array<{ text: string }>;
+    // Attribution survives batching: every batched turn is still named, in the cue
+    // for whichever chunk carries it.
+    const cues = textBlocks.filter((b) => b.text.includes('too long to carry as text'));
+    const named = cues.map((b) => b.text).join('\n');
+    for (const t of [0, 10, 20, 58]) expect(named).toContain(`<user t="${t}">`);
+  });
+
   it('splits dense collapsed history into readable image pages with only a bounded recency pointer', async () => {
     const body = Array.from(
       { length: 180 },
diff --git a/tests/native-image-cap.test.ts b/tests/native-image-cap.test.ts
new file mode 100644
index 000000000..10b48d7ab
--- /dev/null
+++ b/tests/native-image-cap.test.ts
@@ -0,0 +1,178 @@
+/**
+ * The provider's image cap is a property of the WIRE, not of pxpipe: it counts
+ * the client's own images (screenshots, pasted pictures, images a tool already
+ * returned) together with every image pxpipe adds. Pricing only our own is what
+ * let a request carrying 100+ client images get imaged further and come back
+ * 400/500 — a session the user then could not resume at all.
+ *
+ * These tests pin the two halves of the fix:
+ *   1. `countNativeImages` sees the client's images, at both nesting levels,
+ *   2. once they fill the cap, every pxpipe imaging path degrades to text
+ *      instead of adding one more image block.
+ *
+ * Run just this file:  pnpm vitest run tests/native-image-cap.test.ts
+ */
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  countNativeImages,
+  imageHeadroom,
+  transformRequest,
+} from '../src/core/transform.js';
+import { ANTHROPIC_MAX_IMAGES } from '../src/core/history.js';
+import { resetSessionState } from '../src/core/session-state.js';
+import type { Message } from '../src/core/types.js';
+
+const big = (n: number) => 'x'.repeat(n);
+
+const img = () => ({
+  type: 'image' as const,
+  source: { type: 'base64' as const, media_type: 'image/png' as const, data: 'iVBORw0KGgo=' },
+});
+
+function enc(obj: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(obj));
+}
+function dec(b: Uint8Array): any {
+  return JSON.parse(new TextDecoder().decode(b));
+}
+
+/** Every image on the wire, at both nesting levels — the number the provider counts. */
+function wireImages(msgs: Message[]): number {
+  let n = 0;
+  for (const m of msgs) {
+    if (!Array.isArray(m.content)) continue;
+    for (const b of m.content as any[]) {
+      if (b?.type === 'image') n++;
+      else if (b?.type === 'tool_result' && Array.isArray(b.content)) {
+        for (const ib of b.content) if (ib?.type === 'image') n++;
+      }
+    }
+  }
+  return n;
+}
+
+/** A user turn holding `n` client images, as Claude Code sends pasted screenshots. */
+function clientImages(n: number): Message {
+  return { role: 'user', content: Array.from({ length: n }, img) };
+}
+
+/** A tool_result big enough that pxpipe would normally image it. */
+function toolResult(id: string, chars = 40_000): Message {
+  return {
+    role: 'user',
+    content: [{ type: 'tool_result', tool_use_id: id, content: `RESULT ${id}\n` + big(chars) }],
+  } as unknown as Message;
+}
+
+describe('countNativeImages — what the client already put on the wire', () => {
+  it('counts top-level image blocks', () => {
+    expect(countNativeImages([clientImages(7)])).toBe(7);
+  });
+
+  it('counts images nested inside tool_result content', () => {
+    const msgs = [
+      {
+        role: 'user',
+        content: [{ type: 'tool_result', tool_use_id: 't1', content: [img(), { type: 'text', text: 'hi' }, img()] }],
+      },
+    ] as unknown as Message[];
+    expect(countNativeImages(msgs)).toBe(2);
+  });
+
+  it('ignores string content and is safe on empty/absent input', () => {
+    expect(countNativeImages([{ role: 'user', content: 'plain text' }])).toBe(0);
+    expect(countNativeImages([])).toBe(0);
+    expect(countNativeImages(undefined)).toBe(0);
+  });
+});
+
+describe('imageHeadroom — the client’s images spend from the same budget', () => {
+  it('subtracts ours and theirs alike', () => {
+    const a = imageHeadroom({ imageCount: 0, nativeImages: 0 } as any);
+    const b = imageHeadroom({ imageCount: 10, nativeImages: 0 } as any);
+    const c = imageHeadroom({ imageCount: 0, nativeImages: 10 } as any);
+    expect(b).toBe(a - 10);
+    expect(c).toBe(a - 10); // a client image costs exactly what one of ours costs
+    expect(a).toBeLessThan(ANTHROPIC_MAX_IMAGES); // safety margin is applied
+  });
+
+  it('never goes negative — an over-full request reports zero, not a deficit', () => {
+    expect(imageHeadroom({ imageCount: 0, nativeImages: 500 } as any)).toBe(0);
+  });
+});
+
+describe('tool_result imaging respects the client’s images', () => {
+  beforeEach(() => resetSessionState());
+
+  // Positive control. tool_result imaging only runs on the main path, so the
+  // request needs a system slab above the compress gate — the same shape real
+  // Claude Code traffic has.
+  const withSlab = (messages: Message[]) =>
+    enc({ model: 'claude-3-5-sonnet', system: [{ type: 'text', text: 'SLAB\n' + big(30_000) }], messages });
+
+  it('images a big tool_result when the wire is empty', async () => {
+    const { body: out, info } = await transformRequest(
+      withSlab([{ role: 'user', content: 'go' }, toolResult('t1')]),
+    );
+    expect(info.nativeImages).toBe(0);
+    expect(info.toolResultImgs ?? 0).toBeGreaterThan(0);
+    expect(wireImages(dec(out).messages)).toBeGreaterThan(0);
+  });
+
+  it('leaves the same tool_result as text when the client already filled the cap', async () => {
+    const { body: out, info } = await transformRequest(
+      withSlab([clientImages(ANTHROPIC_MAX_IMAGES), toolResult('t1')]),
+    );
+
+    expect(info.nativeImages).toBe(ANTHROPIC_MAX_IMAGES);
+    // Nothing was added: the only images on the wire are the client's own.
+    expect(wireImages(dec(out).messages)).toBe(ANTHROPIC_MAX_IMAGES);
+    expect(info.imageBudgetSkips ?? 0).toBeGreaterThan(0);
+    expect(info.passthroughReasons?.image_budget ?? 0).toBeGreaterThan(0);
+    // The text survived — degrading must not drop content.
+    expect(JSON.stringify(dec(out).messages)).toContain('RESULT t1');
+  });
+
+  it('never exceeds the cap when the client sits just under it', async () => {
+    const near = ANTHROPIC_MAX_IMAGES - 3;
+    const { body: out } = await transformRequest(
+      withSlab([clientImages(near), toolResult('t1'), toolResult('t2'), toolResult('t3')]),
+    );
+    expect(wireImages(dec(out).messages)).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+  });
+});
+
+describe('the cap is quantitative, not boolean', () => {
+  beforeEach(() => resetSessionState());
+
+  // The first cut of this guard asked "is there ANY room left?" and then emitted
+  // a whole multi-page slab into it: 94 client images + a 400k system slab put
+  // 109 images on the wire — still a hard reject, just a rarer one. Every path
+  // must fit its actual page count, not merely find a nonzero headroom.
+  it.each([
+    [94, 400_000],
+    [90, 400_000],
+    [80, 800_000],
+  ])('stays at or under the cap with %i client images and a %i-char slab', async (clients, slabChars) => {
+    const body = enc({
+      model: 'claude-3-5-sonnet',
+      system: [{ type: 'text', text: 'SLAB\n' + big(slabChars) }],
+      messages: [clientImages(clients), { role: 'user', content: 'hi ' + big(200) }],
+    });
+    const { body: out } = await transformRequest(body);
+    expect(wireImages(dec(out).messages)).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+  });
+
+  it('spends nothing at all when the slab cannot fit whole', async () => {
+    const body = enc({
+      model: 'claude-3-5-sonnet',
+      system: [{ type: 'text', text: 'SLAB\n' + big(400_000) }],
+      messages: [clientImages(90), { role: 'user', content: 'hi ' + big(200) }],
+    });
+    const { info } = await transformRequest(body);
+    // All-or-nothing: a half-imaged slab would re-key the cache prefix on every
+    // turn whose client-image count moved.
+    expect(info.imageCount).toBe(0);
+    expect(info.reason).toMatch(/^image_budget/);
+  });
+});
diff --git a/tests/scripts/smoke-collapse.mjs b/tests/scripts/smoke-collapse.mjs
new file mode 100644
index 000000000..0126365d5
--- /dev/null
+++ b/tests/scripts/smoke-collapse.mjs
@@ -0,0 +1,101 @@
+// Live smoke: real built proxy on a scratch port against a recording fake upstream.
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+
+const UP_PORT = 47897, PX_PORT = 47899;
+const seen = [];
+let failNext = false;
+
+const upstream = http.createServer((req, res) => {
+  let b = '';
+  req.on('data', (c) => (b += c));
+  req.on('end', () => {
+    let parsed = null;
+    try { parsed = JSON.parse(b); } catch {}
+    let imgs = 0;
+    for (const m of parsed?.messages ?? [])
+      if (Array.isArray(m.content)) for (const blk of m.content) if (blk?.type === 'image') imgs++;
+    seen.push({ bytes: Buffer.byteLength(b), imgs, path: req.url });
+    if (failNext) { failNext = false; res.writeHead(500, {'content-type':'application/json'});
+      return res.end(JSON.stringify({ type:'error', error:{ type:'invalid_request_error', message:'too large' }})); }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ id:'msg_1', type:'message', role:'assistant', model:'claude-opus-5',
+      content:[{type:'text',text:'ok'}], usage:{ input_tokens:10, output_tokens:2 }}));
+  });
+});
+await new Promise((r) => upstream.listen(UP_PORT, '127.0.0.1', r));
+
+const px = spawn(process.execPath, ['dist/node.js'], {
+  cwd: '/home/lm/repos/pxpipe',
+  env: { ...process.env, PORT: String(PX_PORT), HOST: '127.0.0.1',
+         ANTHROPIC_UPSTREAM: `http://127.0.0.1:${UP_PORT}`,
+         PXPIPE_LOG: '/tmp/pxpipe-smoke-events.jsonl',
+         PXPIPE_DASH_PORT: '0' },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+const pxlog=[];
+px.stdout.on('data', (d) => { pxlog.push(String(d)); process.stdout.write('[px] '+d); });
+px.stderr.on('data', (d) => { const s = String(d); process.stdout.write('[px] '+s); if (/error|throw|ECONN/i.test(s)) process.stderr.write('[px] ' + s); });
+
+const up = async () => { for (let i=0;i<80;i++) { try { await fetch(`http://127.0.0.1:${PX_PORT}/health`); return true; } catch { await new Promise(r=>setTimeout(r,100)); } } return false; };
+if (!await up()) { console.log('FAIL: proxy did not come up'); px.kill(); process.exit(1); }
+
+const big = (n) => 'x'.repeat(n);
+const convo = (n) => {
+  const out = [{ role:'user', content:'SESSION ANCHOR: ' + big(200) }];
+  for (let i=0;i<n;i++) out.push({ role: i%2===0?'assistant':'user', content:`turn ${i}: `+big(3500) });
+  return out;
+};
+const send = (msgs) => fetch(`http://127.0.0.1:${PX_PORT}/v1/messages`, {
+  method:'POST', headers:{'content-type':'application/json','x-api-key':'test','anthropic-version':'2023-06-01'},
+  body: JSON.stringify({ model:'claude-opus-5', max_tokens:16, messages: msgs }),
+});
+
+// pxpipe also forwards /health and count_tokens baseline probes, and the probe
+// can land AFTER the message it belongs to — `lastMessage()` therefore races and
+// occasionally measures the probe (0 images) instead of the real request.
+const lastMessage = () => [...seen].reverse().find((s) => s.path === '/v1/messages');
+
+const results = [];
+const ck = (name, ok, detail='') => { results.push({name, ok, detail}); console.log(`${ok?'ok  ':'FAIL'}  ${name}${detail?'  — '+detail:''}`); };
+
+// 1. huge conversation goes through and is capped
+const r1 = await send(convo(400));
+ck('400-turn request returns 2xx', r1.status === 200, `status=${r1.status}`);
+const s1 = lastMessage();
+ck('forwarded images <= 100', s1.imgs <= 100, `imgs=${s1.imgs}`);
+ck('forwarded body is sane size', s1.bytes < 12_000_000, `${(s1.bytes/1e6).toFixed(2)} MB`);
+
+// 2. next turn is append-only (cache-friendly), not a full re-cut
+const r2 = await send(convo(410));
+const s2 = lastMessage();
+ck('growth turn still 2xx', r2.status === 200, `status=${r2.status}`);
+ck('growth turn still <= 100 images', s2.imgs <= 100, `imgs=${s2.imgs}`);
+
+// 3. upstream 500 marks the cache dead; the retry repacks denser, not fatter
+failNext = true;
+const r3 = await send(convo(420));
+const r4 = await send(convo(430));
+const s4 = lastMessage();
+ck('after an upstream 500 the next turn still fits', s4.imgs <= 100, `imgs=${s4.imgs}`);
+ck('post-500 turn is not larger than pre-500', s4.imgs <= Math.max(s1.imgs, s2.imgs) , `${s4.imgs} vs ${Math.max(s1.imgs,s2.imgs)}`);
+ck('proxy survived the upstream 500', r4.status === 200, `status=${r4.status}`);
+
+// 4. the client's OWN images count against the same provider cap: a wire that is
+//    already full must come back valid, with pxpipe adding exactly nothing.
+const img = () => ({ type:'image', source:{ type:'base64', media_type:'image/png', data:'iVBORw0KGgo=' }});
+const full = [{ role:'user', content: Array.from({length:100}, img) }, ...convo(200).slice(1)];
+const r5 = await send(full);
+const s5 = lastMessage();
+ck('client-image-saturated request returns 2xx', r5.status === 200, `status=${r5.status}`);
+ck('pxpipe added no images to a full wire', s5.imgs === 100, `imgs=${s5.imgs} (client sent 100)`);
+
+ck('collapse actually ran (not a passthrough smoke)', s1.imgs > 0, `imgs=${s1.imgs}`);
+{ const sk = pxlog.join('').includes('unsupported='); ck('no unsupported-model skips', !sk, sk ? 'proxy logged skip(unsupported=...)' : 'none'); }
+ck('images stay under the hard cap', s1.imgs <= 100 && s2.imgs <= 100 && s4.imgs <= 100, `${s1.imgs}/${s2.imgs}/${s4.imgs}`);
+
+console.log('\nforwarded:', seen.map(s=>`${s.imgs}img/${(s.bytes/1e6).toFixed(1)}MB`).join('  '));
+px.kill(); upstream.close();
+const failed = results.filter(r=>!r.ok);
+console.log(failed.length ? `\n${failed.length} FAILED` : `\nall ${results.length} smoke checks passed`);
+process.exit(failed.length ? 1 : 0);

From cbca953f9e089bd155bd32ca3bca62694706a845 Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@gmx.de>
Date: Sat, 1 Aug 2026 21:56:42 +0200
Subject: [PATCH 5/7] feat(telemetry): wire the cache-liveness hook and report
 the real image count
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three gaps, all of the same kind: the code knew something and never said it.

markCacheDead() existed but nothing ever called it. A rejected request never
populated a prefix cache, so the append-only freeze it was protecting protects
nothing — but only the transform side knew that, and the proxy never told it.
responseLeftNoCache() now names the rule and the response path applies it:
413, any 5xx, and a 400 whose body says the prompt is too long. Everything
else stays warm on purpose. A 401, a 404, a rate limit say nothing about the
cache, and guessing "cold" there would re-cut a live grid and burn the whole
prefix as cache_create — the exact cost this module exists to avoid.

imageCount is what we RENDERED, and the wire disagrees: the history collapse
replaces whole messages, so a tool_result image inside the collapsed range is
never sent. Measured on a tool-heavy shape: 91 rendered, 49 on the wire.
info.wireImages now counts the outgoing body itself, and the event carries it
whenever it differs from the render count.

The event log gains history_freeze_step, history_budget_trimmed and
history_pack_fill, so the adaptive grid is finally observable: until now
nothing recorded whether it had coarsened, why, or whether a repack landed on
a cache we believed dead.

The dashboard says the same in words, but only when there is something to say:
"6 images came from your side and count against the same 100-image request cap
· 48 rendered pages never went out — the history collapse absorbed those
messages (49 on the wire)". A quiet turn stays quiet.

Not fixed here: those 48 absorbed pages are content loss, not just miscounting.
An imaged tool_result serializes into the history as "[tool_result]\n[image]",
so the tool output survives only as the factsheet's exact identifiers. The
cure is ordering — collapse before imaging — which changes the outgoing bytes
for every session and re-keys every cache once, so it wants its own change.

(cherry picked from commit 0f2ac302e1d73292549674ac39fde142565e8b16)
---
 src/core/proxy.ts              |  7 ++++
 src/core/session-state.ts      | 28 +++++++++++++
 src/core/tracker.ts            | 23 +++++++++++
 src/core/transform.ts          | 13 ++++++
 src/dashboard.ts               |  6 +++
 src/dashboard/fragments.ts     | 35 ++++++++++++++++
 tests/cache-liveness.test.ts   | 74 ++++++++++++++++++++++++++++++++++
 tests/context-map.test.ts      | 40 ++++++++++++++++++
 tests/native-image-cap.test.ts | 42 +++++++++++++++++++
 9 files changed, 268 insertions(+)
 create mode 100644 tests/cache-liveness.test.ts

diff --git a/src/core/proxy.ts b/src/core/proxy.ts
index 278a85ee9..7ee68033f 100644
--- a/src/core/proxy.ts
+++ b/src/core/proxy.ts
@@ -3,6 +3,7 @@
  * Adapted by src/node.ts and src/worker.ts; uses only Request/Response/URL/fetch.
  */
 
+import { markCacheDead, responseLeftNoCache } from './session-state.js';
 import { transformRequest, type TransformOptions, type TransformInfo } from './transform.js';
 import { isClaudeModel, transformOpenAIChatCompletions, transformOpenAIResponses } from './openai.js';
 import { isAnthropicMessagesPath, isPxpipeSupportedGptModel, isPxpipeSupportedModel } from './applicability.js';
@@ -1558,6 +1559,12 @@ export function createProxy(config: ProxyConfig = {}) {
       measurementPromise.catch(() => undefined),
       stopReasonPromise.catch(() => undefined),
     ]).then(([usage, errorBody, measurement, stopReason]) => {
+      // A rejected request never populated a prefix cache, so the append-only
+      // freeze this session was protecting protects nothing: let the next turn
+      // re-cut the grid for density instead of preserving dead bytes.
+      if (responseLeftNoCache(upstreamRes.status, errorBody)) {
+        markCacheDead(info?.firstUserSha8);
+      }
       fire(
         upstreamRes.status,
         info,
diff --git a/src/core/session-state.ts b/src/core/session-state.ts
index ddb33aa16..80b7751af 100644
--- a/src/core/session-state.ts
+++ b/src/core/session-state.ts
@@ -132,6 +132,34 @@ export function markCacheDead(sessionKey: string | undefined): void {
   touch(sessionKey).cacheDead = true;
 }
 
+/**
+ * Did this response leave the upstream prefix cache unpopulated?
+ *
+ * A cache entry is written by a request the provider actually *accepted*. Three
+ * outcomes mean it never got that far, so the frozen grid we were protecting
+ * protects nothing and the next turn may re-cut for density:
+ *
+ *  - `413` — payload rejected outright;
+ *  - `400` whose body says the prompt is too long (Anthropic's wording varies:
+ *    `prompt is too long`, `prompt_too_long`, `request_too_large`);
+ *  - `5xx` — includes the opaque `500` an over-cap image count produces.
+ *
+ * Every other 4xx (bad key, rate limit, overloaded) says nothing about the
+ * cache: the prefix may well still be live, so we leave the session warm and
+ * keep the cheap append-only path. Guessing "cold" there would re-cut a live
+ * grid and burn the whole prefix as `cache_create` — the exact failure this
+ * module exists to avoid.
+ */
+export function responseLeftNoCache(status: number, errorBody?: string): boolean {
+  if (status === 413) return true;
+  if (status >= 500) return true;
+  if (status === 400 && errorBody) {
+    return /prompt[\s_-]*(is\s*)?too[\s_-]*long|request[\s_-]*too[\s_-]*large|too many (images|tokens)/i
+      .test(errorBody);
+  }
+  return false;
+}
+
 /** Test seam: drop all session state. */
 export function resetSessionState(): void {
   sessions.clear();
diff --git a/src/core/tracker.ts b/src/core/tracker.ts
index 07e9ddb54..9c69d0cac 100644
--- a/src/core/tracker.ts
+++ b/src/core/tracker.ts
@@ -35,6 +35,10 @@ export interface TrackEvent {
    *  here plus a fat request means the client's own images crowded us out — the
    *  request stayed valid, but the token win was skipped. */
   image_budget_skips?: number;
+  /** Image blocks really on the wire. Present only when it differs from
+   *  image_count + native_images — i.e. when the history collapse absorbed
+   *  messages that already carried images, so we rendered more than we sent. */
+  wire_images?: number;
   image_bytes?: number;
   /** Total pixel area across all rendered images; pairs with cache_create_tokens for px/token regression. */
   image_pixels?: number;
@@ -77,6 +81,16 @@ export interface TrackEvent {
   collapsed_images?: number;
   /** Why history collapse didn't run (or did). Diagnostic. */
   history_reason?: string;
+  /** Messages packed per history image. Rises when the grid is re-cut coarser;
+   *  never falls within a session, because a finer re-cut re-keys every chunk. */
+  history_freeze_step?: number;
+  /** Set when the grid was coarsened purely to fit the image budget — the turn
+   *  paid legibility for a request that would otherwise have been rejected. */
+  history_budget_trimmed?: boolean;
+  /** Set when the session's upstream cache was provably dead and the collapse
+   *  was therefore allowed to repack for density. Pair with cache_read_tokens:
+   *  a repack that lands on a live cache would show as a cache_create spike. */
+  history_pack_fill?: boolean;
   /** Codepoints not in the glyph atlas. A spike means users type glyphs we don't ship — widen ATLAS_PROFILE. */
   dropped_chars?: number;
   /** Top-20 dropped codepoints (U+HHHH keys) by frequency. Only present when dropped_chars > 0. */
@@ -234,6 +248,12 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
     // should not pay a key per event.
     if ((info.nativeImages ?? 0) > 0) out.native_images = info.nativeImages;
     if ((info.imageBudgetSkips ?? 0) > 0) out.image_budget_skips = info.imageBudgetSkips;
+    // Emit only when it disagrees with the render counter: equality is the common
+    // case and a per-event key for "nothing to see" is noise.
+    if (info.wireImages !== undefined
+        && info.wireImages !== (info.imageCount ?? 0) + (info.nativeImages ?? 0)) {
+      out.wire_images = info.wireImages;
+    }
     if (info.imageBytes !== undefined) out.image_bytes = info.imageBytes;
     if (info.imagePixels !== undefined && info.imagePixels > 0) {
       out.image_pixels = info.imagePixels;
@@ -279,6 +299,9 @@ export function toTrackEvent(ev: ProxyEvent): TrackEvent {
     if (info.historyReason !== undefined) {
       out.history_reason = info.historyReason;
     }
+    if (info.historyFreezeStep !== undefined) out.history_freeze_step = info.historyFreezeStep;
+    if (info.historyBudgetTrimmed) out.history_budget_trimmed = true;
+    if (info.historyPackFill) out.history_pack_fill = true;
     if (info.droppedChars !== undefined && info.droppedChars > 0) {
       out.dropped_chars = info.droppedChars;
     }
diff --git a/src/core/transform.ts b/src/core/transform.ts
index f4b150a63..c3d027abc 100644
--- a/src/core/transform.ts
+++ b/src/core/transform.ts
@@ -655,6 +655,10 @@ export interface TransformInfo {
   nativeImages?: number;
   /** Imaging steps skipped because the cap was exhausted (telemetry for tuning). */
   imageBudgetSkips?: number;
+  /** Image blocks actually present in the outgoing body — ours AND the client's.
+   *  This is the only number the provider counts. It is <= imageCount + nativeImages
+   *  because the history collapse can absorb messages that already carried images. */
+  wireImages?: number;
   /** Chars of tool docs moved to the system-text Tool Reference (not imaged). */
   toolDocsChars?: number;
   /** Codepoints missing from the atlas (rendered as blank cells). Telemetry for atlas tuning. */
@@ -1906,6 +1910,13 @@ async function runHistoryCollapseAndFinalize(
   }
   applyPins(req, info, pins);
   info.outgoingTextChars = countOutgoingTextChars(req);
+  // Ground truth, counted from the bytes we are about to send. `imageCount` is
+  // what we RENDERED, and the two differ: the collapse replaces whole messages,
+  // so any tool_result image inside the collapsed range never reaches the wire.
+  // Measured on a tool-heavy shape: 95 rendered, 27 on the wire. The provider
+  // only ever sees this number, so telemetry and any future headroom math must
+  // read it and not the render counter.
+  info.wireImages = countNativeImages(req.messages);
   const outBody = new TextEncoder().encode(JSON.stringify(req));
   return { body: outBody, info, collapsed: collapsedFlag };
 }
@@ -2711,6 +2722,8 @@ export async function transformRequest(
   }
   applyPins(req, info, pins);
   info.outgoingTextChars = countOutgoingTextChars(req);
+  // Ground truth for the main path too — see the note at the other call site.
+  info.wireImages = countNativeImages(req.messages);
   const outBody = new TextEncoder().encode(JSON.stringify(req));
   return { body: outBody, info };
 }
diff --git a/src/dashboard.ts b/src/dashboard.ts
index 993564fc3..3e66faff9 100644
--- a/src/dashboard.ts
+++ b/src/dashboard.ts
@@ -856,6 +856,9 @@ export class DashboardState {
         warm: warmForRow,
         output: out,
         imageCount: info.imageCount ?? 0,
+        nativeImages: info.nativeImages,
+        wireImages: info.wireImages,
+        imageBudgetSkips: info.imageBudgetSkips,
         baselineImagedTokens: info.baselineImagedTokens,
         buckets: { ...(info.bucketChars ?? {}) },
         imageIds: [...imgIds],
@@ -1200,6 +1203,9 @@ export class DashboardState {
           warm: warmForRow,
           output: out,
           imageCount,
+          nativeImages: (t as { native_images?: number }).native_images,
+          wireImages: (t as { wire_images?: number }).wire_images,
+          imageBudgetSkips: (t as { image_budget_skips?: number }).image_budget_skips,
           baselineImagedTokens: (t as { baseline_imaged_tokens?: number }).baseline_imaged_tokens,
           buckets: { ...((t as { bucket_chars?: Record<string, number> }).bucket_chars ?? {}) },
           imageIds: [], // PNG ring is in-memory; not restorable across restart
diff --git a/src/dashboard/fragments.ts b/src/dashboard/fragments.ts
index 33c6be9b1..cc0d77fcb 100644
--- a/src/dashboard/fragments.ts
+++ b/src/dashboard/fragments.ts
@@ -410,6 +410,14 @@ export interface ContextMapData {
   // on the same cache state as the image path; no wall-clock-only inference.
   output: number;
   imageCount: number;
+  /** Image blocks the CLIENT sent. They spend from the provider's cap exactly
+   *  like ours, so they explain a turn that compressed less than usual. */
+  nativeImages?: number;
+  /** Image blocks really on the wire. Lower than imageCount when the history
+   *  collapse absorbed messages that already carried our images. */
+  wireImages?: number;
+  /** Imaging steps that degraded to text because the cap was full. */
+  imageBudgetSkips?: number;
   baselineImagedTokens?: number;
   buckets: Partial<Record<string, number>>; // bucket → chars rendered to PNG
   imageIds: number[]; // image-ring ids for the gallery
@@ -555,6 +563,28 @@ export function renderContextMapFragment(
           : `Billed = after cache discounts (reads at 0.1×), same basis as the Saved column. ${rawPhrase}`;
   const title = isLatest ? 'Latest request' : 'Selected request';
 
+  // The provider caps a request at 100 image blocks and counts the CLIENT's
+  // images against the same limit. Three facts are worth showing, and only when
+  // they are true — a quiet turn should stay quiet:
+  //   - the client brought its own images (they shrank our room),
+  //   - we rendered more pages than we shipped (the collapse ate some),
+  //   - we gave up on imaging something because the cap was full.
+  const capBits: string[] = [];
+  if ((c.nativeImages ?? 0) > 0) {
+    capBits.push(`${c.nativeImages} image${c.nativeImages === 1 ? '' : 's'} came from your side and count against the same 100-image request cap`);
+  }
+  if (c.wireImages !== undefined && c.wireImages < c.imageCount + (c.nativeImages ?? 0)) {
+    const absorbed = c.imageCount + (c.nativeImages ?? 0) - c.wireImages;
+    capBits.push(`${absorbed} rendered page${absorbed === 1 ? '' : 's'} never went out — the history collapse absorbed those messages (${c.wireImages} on the wire)`);
+  }
+  if ((c.imageBudgetSkips ?? 0) > 0) {
+    capBits.push(`${c.imageBudgetSkips} block${c.imageBudgetSkips === 1 ? '' : 's'} stayed as text because the image cap was full`);
+  }
+  const capNote = capBits.length
+    ? `<div class="split-note cap-note">${capBits.map(escapeHtml).join(' · ')}</div>`
+    : '';
+
+
   return (
     `<div class="ctxmap">` +
     `<div class="ctx-headline"><span class="ctx-title">${title}</span> ${headline}</div>` +
@@ -564,6 +594,7 @@ export function renderContextMapFragment(
     `<div class="split-col split-img">` +
     `<div class="split-head">Compressed into images <span class="split-sum">${kFmt(totalImagedChars)} chars · ${c.imageCount} page${c.imageCount === 1 ? '' : 's'}</span></div>` +
     (imgRows || `<div class="ctx-row muted-row">nothing imaged this request</div>`) +
+    capNote +
     `<div class="split-note">pxpipe can misread exact values inside images — treat these as gist, not byte-exact.</div>` +
     `</div>` +
     `<div class="split-col split-txt">` +
@@ -1045,6 +1076,10 @@ const CSS = `
   .ctx-lbl { color: var(--ink-2); } .ctx-val { color: var(--ink); font-variant-numeric: tabular-nums; white-space: nowrap; }
   .muted-row { color: var(--muted); font-style: italic; }
   .split-note { font-size: 10.5px; color: var(--muted); margin-top: 7px; }
+  /* Cap notes explain a turn that compressed less than the user expects, so they
+     must read as a reason, not as fine print. Warm tint, not an error colour —
+     nothing here is broken. */
+  .cap-note { color: var(--ink); border-left: 2px solid var(--flame); padding-left: 7px; }
   .pages-title { font-size: 11px; color: var(--ink-2); margin: 12px 0 6px; }
   .pages { display: flex; flex-wrap: wrap; gap: 6px; max-height: 320px; overflow: auto;
     background: var(--surface-2); padding: 6px; border: 1px solid var(--border); border-radius: 8px; }
diff --git a/tests/cache-liveness.test.ts b/tests/cache-liveness.test.ts
new file mode 100644
index 000000000..f5c29f836
--- /dev/null
+++ b/tests/cache-liveness.test.ts
@@ -0,0 +1,74 @@
+/**
+ * Which upstream outcomes end a session's prefix cache.
+ *
+ * Getting this wrong is expensive in both directions:
+ *
+ *   - miss a real rejection and the grid stays frozen at a shape nothing is
+ *     cached against, so we keep paying for a freeze that buys nothing;
+ *   - call a LIVE cache dead and the next turn re-cuts the grid, changing every
+ *     chunk's bytes and burning the whole prefix as cache_create.
+ *
+ * The second is the worse one, so anything ambiguous must stay warm.
+ *
+ * Run just this file:  pnpm vitest run tests/cache-liveness.test.ts
+ */
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  markCacheDead,
+  peekSessionState,
+  resetSessionState,
+  responseLeftNoCache,
+} from '../src/core/session-state.js';
+
+describe('responseLeftNoCache — outcomes that leave no cache entry', () => {
+  it('treats an outright size rejection as cache-ending', () => {
+    expect(responseLeftNoCache(413)).toBe(true);
+  });
+
+  it('treats every 5xx as cache-ending — the over-cap image count returns an opaque 500', () => {
+    for (const s of [500, 502, 503, 529]) expect(responseLeftNoCache(s)).toBe(true);
+  });
+
+  it('reads a 400 body for the provider’s several spellings of "too long"', () => {
+    const bodies = [
+      '{"error":{"message":"prompt is too long: 245000 tokens > 200000 maximum"}}',
+      '{"error":{"type":"prompt_too_long"}}',
+      '{"error":{"type":"request_too_large","message":"request too large"}}',
+      '{"error":{"message":"too many images in request"}}',
+    ];
+    for (const b of bodies) expect(responseLeftNoCache(400, b)).toBe(true);
+  });
+
+  it('leaves the session warm on a 200', () => {
+    expect(responseLeftNoCache(200)).toBe(false);
+  });
+
+  // These are the dangerous ones: all say nothing about the prefix cache, which
+  // may well still be live. Re-cutting on them would burn it.
+  it('leaves the session warm on 4xx that carry no size signal', () => {
+    expect(responseLeftNoCache(401)).toBe(false); // bad key
+    expect(responseLeftNoCache(403)).toBe(false); // forbidden
+    expect(responseLeftNoCache(404)).toBe(false); // wrong path
+    expect(responseLeftNoCache(429)).toBe(false); // rate limited — cache intact
+    expect(responseLeftNoCache(400)).toBe(false); // 400 with no body to read
+    expect(responseLeftNoCache(400, '{"error":{"message":"invalid model"}}')).toBe(false);
+  });
+});
+
+describe('markCacheDead — session bookkeeping', () => {
+  beforeEach(() => resetSessionState());
+
+  it('flags the session so the next collapse may repack', () => {
+    markCacheDead('abcd1234');
+    expect(peekSessionState('abcd1234')?.cacheDead).toBe(true);
+  });
+
+  it('is a no-op without a session key rather than throwing', () => {
+    expect(() => markCacheDead(undefined)).not.toThrow();
+  });
+
+  it('does not invent state for sessions that never failed', () => {
+    markCacheDead('aaaa1111');
+    expect(peekSessionState('bbbb2222')).toBeUndefined();
+  });
+});
diff --git a/tests/context-map.test.ts b/tests/context-map.test.ts
index fa8cf7422..7ac1d0282 100644
--- a/tests/context-map.test.ts
+++ b/tests/context-map.test.ts
@@ -208,3 +208,43 @@ describe('renderRecentFragment — billed delta presentation', () => {
     expect(html).not.toContain('class="num pos">—</td>');
   });
 });
+
+describe('renderContextMapFragment — the 100-image request cap', () => {
+  // The cap is the single most confusing thing about a turn that compressed
+  // badly: the user sees "only 3 pages imaged" and no reason why. These lines
+  // name the reason, and only when there is one.
+  it('says so when the client\'s own images ate into the cap', () => {
+    const html = renderContextMapFragment(ctx({ nativeImages: 12 }), []);
+    expect(html).toContain('12 images came from your side');
+    expect(html).toContain('100-image request cap');
+  });
+
+  it('reports pages that were rendered but never sent', () => {
+    // 40 ours + 2 theirs = 42 rendered, 28 on the wire → 14 absorbed.
+    const html = renderContextMapFragment(ctx({ imageCount: 40, nativeImages: 2, wireImages: 28 }), []);
+    expect(html).toContain('14 rendered pages never went out');
+    expect(html).toContain('28 on the wire');
+  });
+
+  it('reports blocks that stayed text because the cap was full', () => {
+    const html = renderContextMapFragment(ctx({ imageBudgetSkips: 3 }), []);
+    expect(html).toContain('3 blocks stayed as text');
+  });
+
+  it('uses the singular where it should', () => {
+    const html = renderContextMapFragment(ctx({ nativeImages: 1, imageBudgetSkips: 1 }), []);
+    expect(html).toContain('1 image came from your side');
+    expect(html).toContain('1 block stayed as text');
+  });
+
+  it('stays silent on an ordinary turn', () => {
+    const html = renderContextMapFragment(ctx({ imageCount: 3, wireImages: 3 }), []);
+    expect(html).not.toContain('cap-note');
+  });
+
+  it('stays silent when the wire count merely agrees', () => {
+    const html = renderContextMapFragment(ctx({ imageCount: 3, nativeImages: 0, wireImages: 3 }), []);
+    expect(html).not.toContain('never went out');
+  });
+});
+
diff --git a/tests/native-image-cap.test.ts b/tests/native-image-cap.test.ts
index 10b48d7ab..c9a1cf6d1 100644
--- a/tests/native-image-cap.test.ts
+++ b/tests/native-image-cap.test.ts
@@ -176,3 +176,45 @@ describe('the cap is quantitative, not boolean', () => {
     expect(info.reason).toMatch(/^image_budget/);
   });
 });
+
+describe('wireImages — what the provider actually counts', () => {
+  beforeEach(() => resetSessionState());
+
+  // The render counter and the wire disagree whenever the history collapse
+  // absorbs a message that already carried one of our images: the message is
+  // replaced wholesale, so the image inside it is never sent. Telemetry that
+  // reads imageCount therefore over-reports, and any headroom math that trusts
+  // it under-uses the budget.
+  it('reports the outgoing body, not the render count, on a tool-heavy shape', async () => {
+    const msgs: any[] = [{ role: 'user', content: 'ANCHOR ' + big(200) }];
+    for (let i = 0; i < 60; i++) {
+      msgs.push({ role: 'assistant', content: `turn ${i}: ` + big(4000) });
+      msgs.push(
+        i % 3 === 0
+          ? { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't' + i, content: 'RES\n' + big(90_000) }] }
+          : { role: 'user', content: `reply ${i}: ` + big(2000) },
+      );
+    }
+    const { body: out, info } = await transformRequest(
+      enc({ model: 'claude-opus-5', system: [{ type: 'text', text: 'SLAB\n' + big(50_000) }], messages: msgs }),
+    );
+
+    const actual = wireImages(dec(out).messages);
+    expect(info.wireImages).toBe(actual);
+    // The whole point: we rendered materially more than we shipped.
+    expect(info.imageCount!).toBeGreaterThan(actual);
+    expect(actual).toBeLessThanOrEqual(ANTHROPIC_MAX_IMAGES);
+  });
+
+  it('agrees with the render count when nothing is absorbed', async () => {
+    const { body: out, info } = await transformRequest(
+      enc({
+        model: 'claude-3-5-sonnet',
+        system: [{ type: 'text', text: 'SLAB\n' + big(30_000) }],
+        messages: [clientImages(2), { role: 'user', content: 'hi' }],
+      }),
+    );
+    expect(info.wireImages).toBe(wireImages(dec(out).messages));
+    expect(info.wireImages).toBe((info.imageCount ?? 0) + (info.nativeImages ?? 0));
+  });
+});

From 6d38c22a1ed4664925c158cf98a8acc8e554b204 Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@gmx.de>
Date: Mon, 3 Aug 2026 19:54:31 +0200
Subject: [PATCH 6/7] fix(cache): decide cold from the provider's accounting,
 not the wall clock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The history collapse may re-cut its grid for density only when no prefix cache
exists — a re-cut changes every chunk's bytes and re-keys the whole prefix. That
decision was made from an idle timer set to the ephemeral 5-minute TTL, and it
was wrong most of the times it fired.

Measured over 143 gaps on a production host: past a 5.5-minute gap the cache was
still warm in 66% of cases, past 15 minutes in 40%, past an hour in 13%. Claude
Code marks some blocks with the 1-hour TTL, so the short constant never described
this traffic. The visible damage was one session repacked three times in an hour
on ~10-minute gaps — freeze step 10 → 80 → 160 → 1280, each step re-keying the
prefix at 60-98k cache_create. Every one of those turns had just *written* a
cache, which the clock could not see.

noteCacheOutcome() now feeds each response's usage back into the session store: a
cache_read proves the prefix was live, a cache_create proves one was just
written. Either way the next turn must not re-cut.

Absence of caching is deliberately NOT read as a dead cache. A request with no
cache_control marker reports both counters zero for its whole life, and treating
that as "cold" repacks the grid on every turn to reclaim something that never
existed — the append-only e2e tests caught this, which is why `everCacheAlive`
gates it. Cold now means: one existed, and stopped appearing.

The clock remains only as a backstop for responses whose accounting never
arrived, at an hour rather than five minutes — the point where the measurements
say warmth becomes the exception.

Repack cost this addresses: 1.41M cache_create tokens across 20 requests, 20% of
all create in the sample, a quarter of it spent re-keying caches that were still
alive.

Two mutations verified against the tests: dropping the everCacheAlive gate fails
3, reverting to the timer fails 5.

(cherry picked from commit 570ce26c6db438411249c4be1c9db4b193995a80)
---
 src/core/proxy.ts            |  11 +++-
 src/core/session-state.ts    | 112 ++++++++++++++++++++++++++++++-----
 tests/cache-liveness.test.ts |  93 +++++++++++++++++++++++++++++
 3 files changed, 201 insertions(+), 15 deletions(-)

diff --git a/src/core/proxy.ts b/src/core/proxy.ts
index 7ee68033f..be7416326 100644
--- a/src/core/proxy.ts
+++ b/src/core/proxy.ts
@@ -3,7 +3,7 @@
  * Adapted by src/node.ts and src/worker.ts; uses only Request/Response/URL/fetch.
  */
 
-import { markCacheDead, responseLeftNoCache } from './session-state.js';
+import { markCacheDead, noteCacheOutcome, responseLeftNoCache } from './session-state.js';
 import { transformRequest, type TransformOptions, type TransformInfo } from './transform.js';
 import { isClaudeModel, transformOpenAIChatCompletions, transformOpenAIResponses } from './openai.js';
 import { isAnthropicMessagesPath, isPxpipeSupportedGptModel, isPxpipeSupportedModel } from './applicability.js';
@@ -1565,6 +1565,15 @@ export function createProxy(config: ProxyConfig = {}) {
       if (responseLeftNoCache(upstreamRes.status, errorBody)) {
         markCacheDead(info?.firstUserSha8);
       }
+      // Feed the provider's own cache accounting back into the session store. A
+      // read proves the prefix was live; a create proves one was just written.
+      // Either way the next turn must not re-cut the grid — which the wall clock
+      // alone could not tell, and got wrong on most gaps that mattered.
+      noteCacheOutcome(
+        info?.firstUserSha8,
+        usage?.cache_read_input_tokens,
+        usage?.cache_creation_input_tokens,
+      );
       fire(
         upstreamRes.status,
         info,
diff --git a/src/core/session-state.ts b/src/core/session-state.ts
index 80b7751af..a5a10aa49 100644
--- a/src/core/session-state.ts
+++ b/src/core/session-state.ts
@@ -6,18 +6,31 @@
  * The history grid is append-only: chunk N's pixels are a pure function of its
  * message range, so old chunks stay byte-identical as the conversation grows and
  * ride Anthropic's prompt cache as `cache_read` forever. That freeze is worth a
- * lot — but only while a cache actually exists. Two situations end it:
+ * lot — but only while a cache actually exists. Where there is none, the freeze
+ * protects nothing and the grid is free to be re-cut for *density* instead:
+ * {@link HistoryCollapseOptions.packFill} raises the freeze step until the pages
+ * are nearly full, which roughly halves image tokens on long sessions of short
+ * turns (#161: 317 images at 43% fill).
  *
- *  1. **Idle gap.** Anthropic's ephemeral prefix cache lives {@link CACHE_TTL_SEC}
- *     seconds past the last hit. Resume a session the next morning and every
- *     block is `cache_create` again no matter what we send.
- *  2. **A rejected request.** An oversized request (opaque `500`, see
- *     {@link ANTHROPIC_MAX_IMAGES}) never populated a cache entry at all.
+ * ## How we know whether a cache exists
  *
- * In both cases the append-only freeze protects nothing, and the grid is free to
- * be re-cut for *density* instead: {@link HistoryCollapseOptions.packFill} raises
- * the freeze step until the pages are nearly full, which roughly halves image
- * tokens on long sessions of short turns (#161: 317 images at 43% fill).
+ * The provider tells us, and that beats inferring it. {@link noteCacheOutcome}
+ * feeds each response's accounting back in: a `cache_read` proves the prefix was
+ * live, a `cache_create` proves one was just written. Only when both are zero is
+ * there nothing to lose by re-cutting.
+ *
+ * This module used to decide from the wall clock alone, treating any gap past the
+ * ephemeral 5-minute TTL as cold. That was wrong most of the times it fired —
+ * measured over 143 gaps on a production host, the cache was still warm in 66% of
+ * gaps past 5.5 minutes, 40% past 15 minutes, 13% past an hour. Claude Code marks
+ * some blocks with the 1-hour TTL, so the short constant never described this
+ * traffic. The worst case was a session repacked three times in one hour on
+ * ~10-minute gaps, each repack re-keying the whole prefix — and each preceded by a
+ * turn that had just *written* a cache, which the clock could not see.
+ *
+ * The clock survives only as a backstop for responses whose accounting never
+ * arrived: {@link COLD_HORIZON_MS}. And a rejected request still marks the session
+ * dead outright ({@link markCacheDead}) — a 413/5xx never populated anything.
  *
  * ## Why the step is sticky
  *
@@ -35,8 +48,6 @@
  * on a guess. The state re-arms itself on the first idle gap after the restart.
  */
 
-import { CACHE_TTL_SEC } from './baseline.js';
-
 /** Sessions tracked before the oldest is evicted. One small record each. */
 const SESSIONS_MAX = 512;
 
@@ -48,6 +59,21 @@ const SESSIONS_MAX = 512;
  */
 const COLD_GRACE_MS = 30_000;
 
+/**
+ * Idle gap past which we treat an unobserved cache as gone.
+ *
+ * Not the ephemeral-tier TTL (`CACHE_TTL_SEC`, 5 minutes). Using that here declared sessions cold while their caches were
+ * demonstrably alive: 66% of gaps past 5.5 minutes still cache-read, 40% past
+ * 15 minutes, 13% past an hour (143 gaps, one production host). Claude Code marks
+ * some blocks with the 1-hour TTL, so the short constant never described this
+ * traffic.
+ *
+ * An hour plus the grace is where the evidence turns: past it, warmth is the
+ * exception. This is only a backstop anyway — {@link noteCacheOutcome} answers
+ * from the provider's own accounting whenever a response has been seen.
+ */
+const COLD_HORIZON_MS = 3_600_000 + COLD_GRACE_MS;
+
 interface SessionRecord {
   /** Wall-clock ms of the last request we saw for this session. */
   lastSeenMs: number;
@@ -55,6 +81,20 @@ interface SessionRecord {
   freezeStep: number;
   /** Set when a request for this session failed in a way that leaves no cache. */
   cacheDead: boolean;
+  /**
+   * Did the provider's own accounting show a cache for this session on the last
+   * response — either read from it, or written to it? `undefined` = not observed
+   * yet. This is the server's answer to a question the clock can only guess at.
+   */
+  lastCacheAlive?: boolean;
+  /**
+   * Has this session EVER shown a cache? Absence of caching is not the same fact
+   * as a cache that died: a request carrying no `cache_control` marker reports
+   * both counters zero forever, and repacking such a session every turn would
+   * re-cut the grid over and over for a cache that never existed. Only a session
+   * that once had one, and then lost it, has provably free room to re-cut.
+   */
+  everCacheAlive?: boolean;
 }
 
 const sessions = new Map<string, SessionRecord>();
@@ -102,13 +142,57 @@ export function noteHistoryRequest(
   const rec = touch(sessionKey);
   const known = rec.lastSeenMs > 0;
   const idleMs = nowMs - rec.lastSeenMs;
-  const expired = known && idleMs > CACHE_TTL_SEC * 1000 + COLD_GRACE_MS;
-  const cold = rec.cacheDead || expired;
+
+  // Server truth beats the clock. If the provider's accounting showed a cache on
+  // the last response — read from OR written to — one exists now, and re-cutting
+  // the grid would throw it away.
+  //
+  // The clock alone was wrong most of the time it mattered. Measured over 143
+  // gaps on a production host: past a 5.5-minute gap the cache was still warm in
+  // 66% of cases, past 15 minutes in 40%, past an hour in 13%. One session was
+  // repacked three times in an hour on ~10-minute gaps, each time re-keying the
+  // whole prefix — and each of those turns had just WRITTEN a cache
+  // (create 60-98k, read 0), which the clock could not see and this can.
+  const serverSaysAlive = rec.lastCacheAlive === true;
+  // "Gone" requires that one existed. A session whose counters were always zero
+  // is not a dead cache, it is a session that never had one — repacking it every
+  // turn would churn the grid forever for nothing to reclaim.
+  const serverSaysGone = rec.lastCacheAlive === false && rec.everCacheAlive === true;
+
+  // Backstop for the case the server cannot answer: no observation yet, or an
+  // observation old enough that warmth is empirically rare (13% past an hour).
+  const beyondHorizon = known && idleMs > COLD_HORIZON_MS;
+
+  const cold = rec.cacheDead || (!serverSaysAlive && (serverSaysGone || beyondHorizon));
   rec.lastSeenMs = nowMs;
   rec.cacheDead = false; // consumed: this request gets the repack
   return { cold, minFreezeStep: rec.freezeStep };
 }
 
+/**
+ * Feed the provider's cache accounting back in, once per response.
+ *
+ * `read > 0` proves the prefix was live. `create > 0` proves one was just
+ * written, which is the case the wall clock got wrong: a turn that paid to build
+ * a cache looks identical to a turn that found none, and repacking on top of it
+ * discards the thing just paid for.
+ *
+ * Both zero means nothing is cached for this session, so a repack costs nothing
+ * — that is the only situation where coarsening the grid is free.
+ */
+export function noteCacheOutcome(
+  sessionKey: string | undefined,
+  cacheReadTokens: number | undefined,
+  cacheCreateTokens: number | undefined,
+): void {
+  if (!sessionKey) return;
+  const rec = sessions.get(sessionKey);
+  if (!rec) return; // never transformed under this key — nothing to attribute
+  const alive = (cacheReadTokens ?? 0) > 0 || (cacheCreateTokens ?? 0) > 0;
+  rec.lastCacheAlive = alive;
+  if (alive) rec.everCacheAlive = true;
+}
+
 /**
  * Pin the grid this session was last rendered at. Monotonic: the floor only ever
  * rises, because a later, finer render would re-key every chunk it re-cuts.
diff --git a/tests/cache-liveness.test.ts b/tests/cache-liveness.test.ts
index f5c29f836..87940cfac 100644
--- a/tests/cache-liveness.test.ts
+++ b/tests/cache-liveness.test.ts
@@ -15,6 +15,8 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import {
   markCacheDead,
+  noteCacheOutcome,
+  noteHistoryRequest,
   peekSessionState,
   resetSessionState,
   responseLeftNoCache,
@@ -72,3 +74,94 @@ describe('markCacheDead — session bookkeeping', () => {
     expect(peekSessionState('bbbb2222')).toBeUndefined();
   });
 });
+
+describe('cold detection uses the provider\'s accounting, not the wall clock', () => {
+  beforeEach(() => resetSessionState());
+
+  const MIN = 60_000;
+  const KEY = 'sess1234';
+  // Never 0: lastSeenMs=0 is the store's "never seen" sentinel, so a turn at
+  // epoch 0 would read back as unknown and the horizon could not fire.
+  const T0 = 1_700_000_000_000;
+
+  /** One turn: transform (advances the clock), then the response's cache numbers. */
+  function turn(atMs: number, read: number, create: number) {
+    const state = noteHistoryRequest(KEY, atMs);
+    noteCacheOutcome(KEY, read, create);
+    return state;
+  }
+
+  it('keeps a session warm across a gap the provider proved it survives', () => {
+    // Measured: 66% of gaps past 5.5 minutes still cache-read, so the old
+    // 5-minute threshold called live caches dead most of the time it fired.
+    turn(T0, 100_000, 0);
+    expect(noteHistoryRequest(KEY, T0 + 10 * MIN).cold).toBe(false);
+  });
+
+  it('does not repack on top of a cache the previous turn just paid to write', () => {
+    // The production chain this fixes: three repacks in one hour on ~10-minute
+    // gaps, each preceded by a turn with read=0 and create=60-98k. The clock saw
+    // "no read, long gap" and re-cut; the create said a cache existed.
+    turn(T0, 0, 66_119);
+    expect(noteHistoryRequest(KEY, T0 + 10 * MIN).cold).toBe(false);
+  });
+
+  it('stays warm when the counters were ALWAYS zero — that is no cache, not a dead one', () => {
+    // A request carrying no cache_control marker reports both counters zero for
+    // its whole life. Reading that as "the cache died" would repack the grid on
+    // every single turn, forever, to reclaim a cache that never existed. The
+    // append-only e2e tests caught exactly this.
+    turn(T0, 0, 0);
+    turn(T0 + MIN, 0, 0);
+    expect(noteHistoryRequest(KEY, T0 + 2 * MIN).cold).toBe(false);
+  });
+
+  it('goes cold once a cache existed and then stopped appearing', () => {
+    // This is the real "dead cache": something was there, now nothing is, so
+    // re-cutting the grid costs nothing and reclaims image tokens.
+    turn(T0, 120_000, 0);   // a cache existed
+    turn(T0 + MIN, 0, 0);   // and is gone
+    expect(noteHistoryRequest(KEY, T0 + 2 * MIN).cold).toBe(true);
+  });
+
+  it('goes cold after a rejection regardless of the clock', () => {
+    turn(T0, 100_000, 0);
+    markCacheDead(KEY);
+    expect(noteHistoryRequest(KEY, T0 + 1_000).cold).toBe(true);
+  });
+
+  it('consumes the rejection: the turn after the repack is warm again', () => {
+    turn(T0, 100_000, 0);
+    markCacheDead(KEY);
+    expect(noteHistoryRequest(KEY, T0 + 1_000).cold).toBe(true);
+    noteCacheOutcome(KEY, 0, 50_000); // the repack wrote a fresh cache
+    expect(noteHistoryRequest(KEY, T0 + 2_000).cold).toBe(false);
+  });
+
+  it('falls back to an hour horizon only when the server never answered', () => {
+    // No noteCacheOutcome at all — e.g. a response whose usage never arrived.
+    noteHistoryRequest(KEY, T0);
+    expect(noteHistoryRequest(KEY, T0 + 30 * MIN).cold).toBe(false); // inside the horizon
+    resetSessionState();
+    noteHistoryRequest(KEY, T0);
+    expect(noteHistoryRequest(KEY, T0 + 90 * MIN).cold).toBe(true); // past it
+  });
+
+  it('treats a never-seen session as warm', () => {
+    // Unknown must never authorize a repack: at worst we keep paying the old
+    // image count, we never nuke a live cache on a guess.
+    expect(noteHistoryRequest('brandnew1', 0).cold).toBe(false);
+  });
+
+  it('ignores outcomes for sessions it never transformed', () => {
+    noteCacheOutcome('ghost123', 0, 0);
+    expect(peekSessionState('ghost123')).toBeUndefined();
+  });
+
+  it('lets a proven-dead cache go cold even inside the horizon', () => {
+    turn(T0, 100_000, 0);      // warm
+    turn(T0 + MIN, 0, 0);      // provider says: nothing cached anymore
+    expect(noteHistoryRequest(KEY, T0 + 2 * MIN).cold).toBe(true);
+  });
+});
+

From 9b691ffac64726228f6ef5226c3e522ae5c5fc04 Mon Sep 17 00:00:00 2001
From: Leo Martens <leo.martens@gmx.de>
Date: Wed, 5 Aug 2026 19:37:18 +0200
Subject: [PATCH 7/7] fix(cache): a transient 5xx is not a dead cache
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Production settled a rule I had guessed. Of 20871 requests on ber-dev-tr-ai the
5xx population was 177 × `529 overloaded`, 2 × `500`, 1 × `503` — and 129 of 250
repacks fired directly after one of them.

A 529 means the provider declined to process the request. The prefix cache it
never touched is still there, so marking the session dead re-cut the grid and
threw a live cache away for nothing. That is the same failure the wall-clock rule
had, reintroduced through a blanket `status >= 500`.

`responseLeftNoCache` now fires only on a 413 or a 400 whose body says the prompt
was too long — the two cases where the request itself was refused for its size.

Nothing is lost by dropping the 5xx branch: a cache that genuinely died shows up
on the next turn as a response reporting neither a read nor a write, which
noteCacheOutcome already handles, accurately and for free.

(cherry picked from commit 67bb85ccc66bb2cc97e6eda15859845542c02471)
---
 src/core/session-state.ts    | 25 +++++++++++++++----------
 tests/cache-liveness.test.ts | 16 ++++++++++++++--
 2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/core/session-state.ts b/src/core/session-state.ts
index a5a10aa49..0d23ceb15 100644
--- a/src/core/session-state.ts
+++ b/src/core/session-state.ts
@@ -30,7 +30,8 @@
  *
  * The clock survives only as a backstop for responses whose accounting never
  * arrived: {@link COLD_HORIZON_MS}. And a rejected request still marks the session
- * dead outright ({@link markCacheDead}) — a 413/5xx never populated anything.
+ * dead outright ({@link markCacheDead}) — but only a 413 or a too-long 400, not
+ * a transient 5xx: see {@link responseLeftNoCache}.
  *
  * ## Why the step is sticky
  *
@@ -223,20 +224,24 @@ export function markCacheDead(sessionKey: string | undefined): void {
  * outcomes mean it never got that far, so the frozen grid we were protecting
  * protects nothing and the next turn may re-cut for density:
  *
- *  - `413` — payload rejected outright;
+ *  - `413` — the payload was rejected outright;
  *  - `400` whose body says the prompt is too long (Anthropic's wording varies:
- *    `prompt is too long`, `prompt_too_long`, `request_too_large`);
- *  - `5xx` — includes the opaque `500` an over-cap image count produces.
+ *    `prompt is too long`, `prompt_too_long`, `request_too_large`).
  *
- * Every other 4xx (bad key, rate limit, overloaded) says nothing about the
- * cache: the prefix may well still be live, so we leave the session warm and
- * keep the cheap append-only path. Guessing "cold" there would re-cut a live
- * grid and burn the whole prefix as `cache_create` — the exact failure this
- * module exists to avoid.
+ * NOT any 5xx, which is what this used to say. Production disagreed: of 20871
+ * requests on one host the 5xx population was 177 × `529 overloaded`, 2 × `500`
+ * and 1 × `503` — and 129 of 250 repacks fired directly after one of them. A 529
+ * means the provider declined to process the request; the prefix cache it never
+ * touched is still there, and re-cutting the grid threw it away for nothing.
+ *
+ * Nor any other 4xx. A bad key or a rate limit says nothing about the cache.
+ *
+ * A cache that genuinely died needs no error to be noticed: {@link
+ * noteCacheOutcome} sees the next response report neither a read nor a write, and
+ * that is both accurate and free.
  */
 export function responseLeftNoCache(status: number, errorBody?: string): boolean {
   if (status === 413) return true;
-  if (status >= 500) return true;
   if (status === 400 && errorBody) {
     return /prompt[\s_-]*(is\s*)?too[\s_-]*long|request[\s_-]*too[\s_-]*large|too many (images|tokens)/i
       .test(errorBody);
diff --git a/tests/cache-liveness.test.ts b/tests/cache-liveness.test.ts
index 87940cfac..210937eb5 100644
--- a/tests/cache-liveness.test.ts
+++ b/tests/cache-liveness.test.ts
@@ -27,8 +27,20 @@ describe('responseLeftNoCache — outcomes that leave no cache entry', () => {
     expect(responseLeftNoCache(413)).toBe(true);
   });
 
-  it('treats every 5xx as cache-ending — the over-cap image count returns an opaque 500', () => {
-    for (const s of [500, 502, 503, 529]) expect(responseLeftNoCache(s)).toBe(true);
+  it('does NOT treat a transient 5xx as cache-ending', () => {
+    // Production settled this. Of 20871 requests on one host the 5xx population
+    // was 177x 529 overloaded, 2x 500, 1x 503 — and 129 of 250 repacks fired
+    // directly after one of them. A 529 means the provider declined to process
+    // the request; the prefix cache it never touched is still there, and the
+    // repack threw it away for nothing.
+    for (const s of [500, 502, 503, 504, 529]) expect(responseLeftNoCache(s), String(s)).toBe(false);
+  });
+
+  it('needs no error signal for a cache that really died', () => {
+    // noteCacheOutcome sees the next response report neither a read nor a write.
+    // That is accurate and free, which is why the blanket 5xx rule could go.
+    expect(responseLeftNoCache(529)).toBe(false);
+    expect(responseLeftNoCache(413)).toBe(true);
   });
 
   it('reads a 400 body for the provider’s several spellings of "too long"', () => {