fix(cache): slide the store TTL, pin frozen decisions, and repair lost ones

[OsherElhadad]

Closes #25

A frozen compaction could expire mid-task and hand the provider a different
representation of an already-cached message, forcing a re-write of the whole suffix at
11.5× the cache-read price. Store.Get refreshed LRU recency but never e.expires,
and the default TTL was 1800 s — under Terminal-Bench's ~1975 s mean wall clock, so a
decision died roughly every 69 turns however often it was replayed.

What changed

Failure mode	Fix
Get refreshed recency but not lifetime	Sliding TTL — Get refreshes expires. An entry nobody reads still expires on its original deadline.
1800 s default < task wall clock	store.DefaultTTL 1800 s → 10000 s, still ttl_seconds-configurable.
LRU could drop a decision before its TTL	Replay decisions are pinned, capped at half the entry cap.
A Get miss couldn't be told from a loss	store.FrozenLoser + depth repair, for the reproducible offloaders only (part C, below).
Pinned entries were immortal (TTL enforced only in Get, and a finished session is never read again) — half the cache leaked and, past ~max/2 lifetime freezes, pinning silently stopped working for every later session	Eviction reclaims expired entries first, pinned included; a refresh can reclaim a freed pin slot.
cg:len: (apply's cache boundary) was not pinned, so it competed for a pool this PR halved — losing it makes TailOnly fail open on every index	cg:len: is pinned (it is 2–4 bytes).
cg:res: and cg:sum1: had independent TTLs/pin slots, so losing only the summary made the replay hit and emit different bytes	One JSON key; three helpers deleted.
The store hardcoded component key prefixes (layering inversion)	Owners declare them via store.Options.PinPrefixes.
frozen_dropped counted live, readable entries (marked at freeze time when over the pin cap), so the next ordinary re-freeze looked like a repair and frozen_flips read 0	Losses are recorded only where losses happen (remove); a repeat drop of an already-marked key is not double-counted.
One global loss-mark map evicted an arbitrary victim, so a busy session could delete another session's fresh mark and that session flipped unrepaired	Oldest-first (FIFO) eviction keeps the newest marks.

Part C: a store miss must never force a cache-destructive regression

The design question, and the reason this is not a two-line diff.

reapplyFrozen returning false conflates "no frozen decision" with "the decision
existed and was lost", and those want opposite behavior. The fail-open invariant in
CLAUDE.md says forward the original — correct for a new compaction. But once the
provider has cached the compacted bytes, forwarding the original is itself the
destructive act. The fail direction inverts for an established compaction.

What state has to survive, and where. Only the fact of the freeze — not its payload.
That is one key in a bounded set, so it lives in the store (FrozenLoser.FrozenLost)
rather than in a second content index. The three options the issue floated were weighed:

• a separate longer-lived fingerprint index — a second copy of the same information, with
  its own lifetime bug waiting to happen;
• eviction exemption — necessary but not sufficient (a TTL expiry still loses the entry),
  so it is included, capped at max/2;
• a per-session generation counter — detects that something was lost, but not which
  message, which is exactly what the repair needs.

Behavior. never frozen → obey the tail gate (a new compaction stays in the uncached
tail). frozen, then lost → re-derive it even at depth. This is safe rather than a
fail-open exception, because a deterministic offloader's replacement is a pure function of
(content, component config) and the marker key is sha256(original): re-deriving
reproduces the same bytes the provider cached and re-establishes the freeze. The
component's own never-worse and kept-verbatim guards still apply, so the repair only ever
lifts the depth restriction — it never authorizes new content loss.

Documented as a policy note in docs/design.md rather than a config flag: there is no
sane value for "please flip my cached prefix instead", so a boolean would only be a way to
ask for the bug back.

extract_llm is deliberately excluded from the repair. Its replacement is a sampled
model output — internal/cheapmodel/anthropic.go sends no temperature and no seed — so
re-deriving could splice different bytes into the cached prefix, which is the exact
corruption the repair exists to prevent. And the trade does not pay even ignoring that:
if the bytes differ the suffix is cache-written either way, so the repair branch would
buy a model call for nothing. There is no upside. (An earlier revision of this PR argued
the opposite; that reasoning was wrong.) Two further hazards made the same point: after
lifting the gate the model may not run at all (throttle, timeout, floor), leaving the
output verbatim at depth; and its entry is pinned anyway, so the common case is that it is
never lost. Re-enabling it would require deterministic decoding plus verifying the
re-derived bytes against the stored hash before splicing.

Two findings worth flagging

1. The freeze contract is implemented twice. mask/failed_run use
   freeze/reapplyFrozen (cg:frz:); extract_llm used its own result cache
   (cg:res: plus a separate cg:sum1: key). The shipped codesmart config has no
   mask and failed_run self-skips on a cached agent — so scoping this fix to cg:frz:
   alone would have been measurably inert on the exact traffic that motivated it.
   The split has now been narrowed rather than merely worked around: the projection and its
   summary are one JSON key (they must live and die together — as two independently
   TTL'd, independently pinned keys, losing only the summary made the replay hit and
   silently emit different bytes), which deleted summaryKey/getSummary/putSummary; and
   the store no longer hardcodes component prefixes — they arrive via
   store.Options.PinPrefixes. Fully collapsing the two mechanisms into one helper is still
   feat(components): add xdedup — cross-turn duplicate tool-output references (39.8x measured re-send factor) #27/C3 territory, since only the reproducible offloaders can share the repair path.
2. frozen_hits/misses initially read 0 on a live smoke run while the pipeline replayed
   every turn, because only reapplyFrozen fed the counters. Fixed — otherwise the
   observability added to verify this fix would have been blind on the shipped config.

Measurements

Direct measurement of the mechanism (TestFlipCostOverLongSession)

The hypothesis had to be validated, and a live run cannot isolate it: the effect only
appears past the old TTL, and codesmart omits mask. So the mechanism is measured
deterministically — a 120-turn session at 26 s/request (this gateway's measured latency),
counting tokens the provider must re-write because a cached-prefix message changed
representation:

store behavior	flips	cache-write tokens	premium @ $2.30/M
write-only TTL (old)	50	191,681	$0.44
sliding TTL (new)	0	0	$0.00

Same mechanism and direction as the issue's estimate; its 2.5M-token figure covered the
whole 89-task suite, this is one 120-turn session. The test asserts the old behavior still
reproduces flips, so the fixture cannot silently stop exercising the bug.

Live runs

Two arms of the same binary lineage, differing only in the three behaviors (the
"before" build keeps the new counters so both arms measure identically), on the two
longest-horizon Terminal-Bench tasks from the arms where cache-write was worst
(rstan-to-pystan 14.0% cw/cr, compile-compcert 4.7%).

The fix is UNMEASURED on the shipped default. codesmart (the proxy default) has no
mask, failed_run self-skips on a cached agent, and extract_llm made 0 acts at its
3000-token floor — so on that config nothing is ever frozen and this fix is latent. A
codesmart arm was run first and measured exactly that: frozen_hits 0, frozen_dropped
0 over 145 requests. An honest null result, and the reason the benchmark arm was switched
to general (which includes mask). What is demonstrated below is that the mechanism
works where it is reachable — not that the shipped default improves.

Both arms ran to completion (2 trials each, 93 vs 114 proxy requests).

metric	before (write-only TTL)	after (sliding + pinned + repair)	delta
frozen_dropped	184	0	−100%
frozen_hits (replays landed)	759	1,105	+45.6%
mask acts	78	94	+20.5%
mask saved (cumulative tok)	631,090	1,747,696	+177%
mask saved (unique tok)	21,179	36,242	+71.1%
proxy savings	42.2%	59.4%	+17.2 pp
cache-read tokens	4,191,174	5,317,999	+26.9%
cache-write tokens	251,608	232,297	−7.7%
cache-hit rate	94.27%	95.73%	+1.5 pp
frozen_flips	0	0	—

The headline, and the only claim I make from this run: the old semantics dropped 184 live
frozen decisions mid-session; the new semantics dropped none. That needs no
normalisation. Two secondary signals point the same way — the replay lands more often (759
→ 1,105) and mask keeps more unique content compacted (21,179 → 36,242 tok).

I am not claiming a cost or cache-write win from this run. Both arms were truncated by
the agent wall-clock cap at different points, so absolute totals are not comparable, and
cache-write per request is not flat in request index — normalising by requests would be
reading signal into an artifact. That is the mechanism this issue is about, observed on real
traffic — each drop is a decision that would flip an already-cached message's
representation unless repaired.

Honest caveats, not cherry-picked:

• Both arms' tasks hit the agent wall-clock cap (exception: true, reward 0 in both).
  These two tasks time out on this gateway at ~26 s/request — the same effect documented
  for 11 of 89 TB tasks. So reward is not measurable here, only tokens/counters. Reward
  is neither improved nor worsened by this change on this evidence.
• general adds ~4.6 s/request of its own (extract_llm 514 s cumulative), which itself
  pushes long tasks toward the cap. That is perf(extract_llm): prompt-cache the preamble, global result cache, economic gate, and value-based triggering (measured ~8x underwater) #28's problem, not this one, but it is why
  these tasks timed out where the published codesmart run completed them.
• The frozen_repaired figure in the before arm counts any re-Put of a lost key by the
  normal tail-gated path, not a depth repair (that build has the repair behavior reverted).
  frozen_dropped is the meaningful before/after signal.
• Cost is higher in absolute terms after ($2.12 vs $1.80) because the after arm ran longer
  before hitting the wall-clock cap. With both arms truncated at different points, absolute
  cost and cache-write totals are not comparable in either direction.
• SWE-bench control: 2 of 3 tasks in the first arm died in docker compose environment
  build (shared-host contention), so the two SWE arms are not matched and I draw no
  conclusion from them — including no "no regression" claim, which one trial cannot support.

Memory impact of the longer TTL

Unchanged at steady state — the cap is on entry count (1000), not bytes or time, so
the TTL cannot raise the ceiling; it only slows how fast an idle store shrinks below it.

entry kind	size	1000-entry ceiling
rewind stash (full tool output, TB mean ~4k tok)	15.6 KiB	15.3 MiB
compacted projection (extract_llm)	2.3 KiB	2.3 MiB
marker line (mask/failed_run)	0.2 KiB	0.2 MiB

Worst case, all 1000 entries max-size rewind stashes: 15.3 MiB. The pinned subset is
capped at max/2 = 500 small entries — ≤1.14 MiB — and rewind stashes (the large
payloads) stay fully evictable.

Tests

CGO_ENABLED=1 go build -tags cg_skeleton ./...          # clean
CGO_ENABLED=1 go test  -tags cg_skeleton ./...          # all packages ok
CGO_ENABLED=1 go test -race -tags cg_skeleton ./store/... ./components/...   # ok
make lint                                               # go vet + gofmt clean

New tests: sliding TTL with a fake clock (a continuously-read entry survives 100× its TTL);
an unread entry still expires on its original deadline; the LRU cap still evicts; frozen
entries survive LRU pressure; the pin cap holds; a dropped decision is distinguishable from
a never-frozen one; repaired ≤ dropped; an unpinned decision's loss is still reported; a
forced store miss does not flip an established compaction; a never-frozen message stays
verbatim at depth; a Nop store degrades safely; both replay namespaces feed the counters.

From this review round: expired pinned entries are reclaimed (and a new session can pin
again afterwards); cg:len: survives eviction pressure; a live over-cap entry is not
counted as dropped and re-freezing it manufactures no drop/repair pair; the newest loss
mark survives budget overflow; projection+summary share one key (expired ⇒ miss
outright, unreadable ⇒ miss, never a half-decision); and — with a stub model that returns a
different valid projection per call — a lost extract_llm decision leaves the
cached-prefix message verbatim and triggers no re-derivation call
(components/all/freeze_repair_test.go). That last one fails on 3f7d700 with
verbatim=false, sameAsTurn1=false, i.e. it reproduces the reviewer's finding before
fixing it.

Each behavioral fix was verified to fail without it: reverting the sliding TTL fails
TestMemorySlidingTTLOnGet; reverting the repair fails
TestForcedStoreMissDoesNotFlipEstablishedCompaction with the masked→full diff printed.

Observability

/stats gains frozen_hits, frozen_misses, frozen_dropped, frozen_repaired,
frozen_flips (= dropped − repaired; should be 0). Additive only — verified against
the live endpoint that all 16 pre-existing fields are present and deploy/harbor's
st.get(...) access patterns still parse, since those scripts read this endpoint.

Notes

• docs/results/improvement-plan.md §A2 could not be updated here: it exists only on
  the unmerged origin/docs/terminal-bench branch, not on main. It should be marked
  measured when that branch lands.
• The related MaxCachedIdx fail-open (prevLen miss ⇒ TailOnly true for every index,
  11.2% of TB requests) is documented in docs/design.md but left to its own change —
  inverting TailOnly is A3, not this issue. The sliding TTL does shrink the window, since
  cg:len: is read every turn and so no longer expires mid-session.

[OsherElhadad]

Independent review — verdict: changes requested (GitHub won't let me --request-changes on my own account's PR, so this is a --comment carrying that verdict)

Parts A and B are correct and well-tested. Part C's reasoning is right — the fail direction genuinely does invert for an established compaction, and that is the best insight in this PR. But the implementation of C, and the pinning that supports it, have several defects I reproduced with tests in a scratch worktree. Two of them are blockers; one is a permanent resource leak; two are metrics that fail in the flattering direction (the same class of bug the author already fixed once in b7b7cb0 — it is still there on a different code path).

What I verified myself: build, go test ./... (19 pkgs ok), go test -race -count=5 ./store/... ./components/offload/... (clean, 436s), make lint (clean), the two revert-the-fix checks below, and every "PROBE" claim below is a test I wrote and ran on 3f7d700. mkdocs is not installed on this box, so --strict is unverified. The live benchmark numbers I take on trust.

Revert checks confirmed as claimed:

• removing the e.expires refresh in store.Get → TestMemorySlidingTTLOnGet and TestMemoryUnreadEntryStillExpires fail.
• stubbing frozenLost to false → TestForcedStoreMissDoesNotFlipEstablishedCompaction fails with the masked→full diff printed, exactly as described. TestFlipCostOverLongSession reproduces flips=50 / 191,681 tok / $0.44 → 0.

---

Is "re-derive at depth" safe for every offloader? Answer: no.

mask and failed_run: yes, provably. mask's replacement is prefix + headPeek(content, keepHeadChars) + expand.Marker(sha256(content)) and failed_run's is a constant prefix + the same marker — both pure in (content, component config), and neither depends on the message's index: keep_recent/runs[:len-1] only gate whether the component is a candidate, never what bytes it emits. Config can't drift mid-session either, because there is no hot-reload path (config.Load is called once in cmd/context-guru-proxy/main.go:97) and a restart drops the whole in-memory store, so no stale lostFrozen mark can survive a config change. The purity argument holds for these two. Good.

extract_llm: no. The replacement is a sampled LLM output. internal/cheapmodel/anthropic.go:44-48 sends only model/max_tokens/messages — no temperature: 0, no seed, nothing that pins determinism, and RunExtractionSummary picks a strategy by strategyOrder and validates the candidate rather than reproducing it. components/offload/extract_llm.go:248 lifts the tail gate on repairLostResult, then a fresh model call produces whatever it produces and apply() splices it into a message inside the cached prefix.

I reproduced both failure modes with a stub model:

BLOCKER 1 — extract_llm.go:248: repair with a differing model output is a deliberate deep mutation, scored as a success. Model returns a different-but-valid projection on re-derivation:

model calls=1 dropped=1 repaired=1 flips=0
 was  "PROJECTED SHORT\n<<cg:44ab6ef8...>> [full output: call context_guru_expand]"
 now  "verbose tool output line with detail\nverbose...\n<<cg:44ab6ef8...>> [...]"

The cached-prefix message changed bytes, the suffix is re-written, and frozen_flips reads 0. This is precisely the "converts a rare TTL flip into a deliberate deep mutation" case, and the observability added to catch it reports success. The PR body's "the LLM may not reproduce the bytes exactly — but the alternative is a guaranteed full-suffix cache-write" is not a valid trade here: both branches cost one cache-write of the same suffix, and the LLM branch also costs a model call plus its latency on the hot path. There is no upside. Do instead: don't lift the tail gate for extract_llm. Either (a) restrict repairLostResult to re-emitting bytes you can prove, or (b) if you keep the repair, gate the splice on newProjection == previouslyCachedProjection — which requires keeping a fingerprint of the emitted bytes, i.e. the thing the design note rejected. (b) is the honest version; (a) is the lazy one. At minimum, frozen_repaired must not be credited unless the bytes match.

BLOCKER 2 — extract_llm.go:248 + :262: the repair lifts the gate, then the model may not run at all. With a failing/absent model (rate limit, 15s llmCallTimeout, throttled step via llmAllowedThisRequest, skipFileReads, sz < floor), the message is forwarded verbatim at depth — the exact flip C exists to prevent — and the counters correctly say dropped=1 repaired=0 flips=1, so the repair path is a no-op that spent a model call:

model calls=1 dropped=1 repaired=0 flips=1
PROBE: repair authorized depth mutation but the model failed -> forwarded VERBATIM at depth

So on the config that actually ships (codesmart, where extract_llm is the only replay mechanism), part C is unreliable by construction. Reinforces the fix for blocker 1.

---

High severity

3. state.go:243 / store.go:203: cg:sum1: and cg:res: are two independently-lived keys, so the replay can flip bytes on the HIT path with nothing reported lost. extract_llm.go:230 renders projected + "\n[" + summary + "] " + tok when the summary exists and projected + "\n" + tok when it doesn't. The two keys get separate pin slots and separate sliding TTLs, and repairLostResult only inspects the cg:res: key. Reproduced two ways:

# summary key expires while the result key keeps being read (only res is Get every turn)
 first="PROJECTED\n[one line summary] <<cg:875b...>>..."
 second="PROJECTED\n<<cg:875b...>>..."

# summary evicted past the pin cap while its result stays pinned
 id1: result=true summary=false repairLostResult=false

That is a silent representation flip counted as a frozen_hits success, invisible to frozen_dropped/repaired/flips. Fix: store the summary with the result under one key (one JSON blob), so they cannot diverge. That also deletes summaryKey/getSummary/putSummary and one of the three pinned prefixes — smaller diff than what's here.

4. store.go:203-211, 320-330: pinned entries are immortal, so the pin budget is permanently exhausted and half the cache is leaked. TTL is only enforced inside Get, evictOldest skips pinned entries, and nothing sweeps. A pinned entry whose session ended is never Get again → never expires → never evicted → pinnedN never decrements. Reproduced: 60 short sessions × 10 freezes over 6000s of fake clock, then +24h and 5000 rewind Puts:

after 600 freezes over 6000s:  pinnedN=500 (cap=500) llLen=600
after 24h + 5000 rewinds:      pinnedN=500          llLen=1000
PROBE: pinning is permanently disabled for all future sessions (pinnedN=500)

Two consequences for a long-running proxy (which is the deployment model): (a) 500 dead entries hold half the 1000-entry cache forever — the PR's memory table assumes the pinned subset is live working state; it isn't, it's garbage; (b) after ~500 lifetime frozen keys, every future session's decisions are unpinned, i.e. the eviction-exemption half of the fix silently stops working and the store starts reporting dropped for them at freeze time. The docs' "capped so one pathological session cannot pin the whole cache" is true; what actually happens is that finished sessions pin it. Fix: check expires in evictOldest — an expired pinned entry is evictable (that is one if, and it also repairs (b)). A lazy sweep on Put would do too.

5. store.go:203-211: pinning makes the MaxCachedIdx fail-open more likely, which is not acceptable to defer as A3 given this PR causes it. cg:len: (the prevLen key behind MaxCachedIdx, apply/apply.go:312) is not in frozenNamespace, so it stays fully evictable — while up to half the cache is now unevictable. Reproduced with MaxEntries: 20: 10 frozen keys + 10 ordinary Puts evicts cg:len:s, → MaxCachedIdx = -1 → TailOnly true for every index → the pipeline is licensed to mutate the whole cached prefix. That is a bigger cache-destructive event than the one this PR fixes, and this PR halves the pool it competes for. The design note claims the sliding TTL "shrinks that window" — true for expiry, false for eviction, and the eviction pressure is now worse. Fix: add cg:len: to the pinned set (it is 2-4 bytes per session), or pin it explicitly. Cheap and removes the interaction entirely.

---

Medium — metrics that fail in the flattering direction

6. store.go:189-196 + :203-211: the b7b7cb0 fix is incomplete — the flattering pin-cap metric returns on the second Put of an over-cap key, which is the normal case (mask/failed_run re-freeze every turn):

turn1: dropped=2 repaired=0 flips=2
turn2: dropped=2 repaired=2 flips=0 ; key 'c' present=true pinned=false

dropped=4 repaired=4 → flips=0 is exactly what b7b7cb0's commit message says was wrong; it now takes two turns instead of one. The over-cap decisions are still unpinned and unprotected. Root cause: noteLost is called at freeze time for a live, readable entry, so "dropped" is overloaded to mean both "gone" and "unprotected". Split them: a frozen_unpinned gauge for the pin-cap case, and reserve dropped/repaired for actual loss. That also fixes:

7. store.go:208: frozen_dropped counts entries that are still present and readable. MaxEntries: 4, four freezes → frozen_dropped=2 while both of those keys Get successfully. The headline "184 → 0" is therefore not purely a loss count; some fraction of the 184 may be over-cap-but-live. Worth re-checking against the run's max_entries.

8. store.go:236-241: the FrozenLossStats doc is wrong. It says "Both count each key once, however many turns observe it"; noteLost increments lostN unconditionally, so three expire/re-freeze cycles of one key give dropped=3 repaired=2. Either dedupe or fix the comment. (flips can't go negative — verified: repairedN only increments on a map-hit that is then deleted.)

9. store.go:221-229: lostFrozen is one global bounded map, so sessions starve each other's repairs. The bound is m.max (1000) with arbitrary single-key eviction. Reproduced: session A's loss mark is silently deleted by session B's over-cap traffic, so A's compaction flips with no repair and no report. The issue explicitly asked for "cap that exemption per session"; the pin cap is global and the loss set is global. At 1000 keys and 100 sessions this is unlikely in practice, but the failure is silent — say so in the comment, or key the bound per session.

10. metrics/metrics.go:222-231: the "frozen_misses is dominated by never-frozen-yet" caveat lives only in a Go struct comment. Nobody reading /stats sees it. Put it in docs/reference/routes.md:12, which currently doesn't mention any of the five new fields.

---

Low / process

11. Backward compatibility of /stats: verified OK. All five fields are additive; deploy/harbor/{measure,swebench,replay,replay2}.py use st.get(...) with defaults throughout and reference no removed key.

12. Finding #1 confirmed as stated, and it is the most valuable thing in this PR. config/config.go:135 — codesmart has no mask; failed_run.go:118 self-skips whenever c.CacheAware; extract_llm replays through cg:res:/cg:sum1: only. A cg:frz:-scoped fix would indeed have been inert on the shipped default. But it is papered over, not unified, and the papering is where bugs 1, 2 and 3 come from: store.go:65-73 now hardcodes three component-owned key prefixes inside the store package (layering inversion — the store knows about mask's naming), and state.go carries two parallel helpers (repairLostFreeze / repairLostResult) with different arguments and different guarantees. One store.Pin(key) call at the freeze site, or one shared freeze() that extract_llm also uses, would make frozenNamespace unnecessary. Worth doing here rather than deferring to #27/C3, since C's correctness depends on it.

13. Methodology — the preset switch is legitimate, but the conclusion is over-claimed. The codesmart null result is real (verified mechanically: no mask, failed_run self-skips, and min_tokens: 3000 at config.go:160 gates extract_llm off), and running general to exercise the mechanism is the right call, not preset-shopping — provided the PR says plainly that the fix is unmeasured on the shipped default config, which it does not. It should. The −24.7% cache-write/request normalisation is defensible as a mechanism measurement but not as a cost result: with both tasks truncated by the wall clock at different points, requests are not an exchangeable unit (later requests carry longer prefixes, so cw/req is not flat in request index). Present it as directional, next to frozen_dropped 184→0 which needs no normalisation and is the real evidence. On the SWE control: the body says "not quoting a delta" and then quotes reward 1.0 → 1.0, 11 steps, $0.14 — a null delta is still a delta. Trivial, but say "one unmatched trial pair, no signal" instead.

14. Security: clean. No credential, token, or gateway URL in the diff, tests, docs, or PR body (grepped the full origin/main...HEAD diff for key/bearer/token/password patterns and internal hostnames).

15. Docs. docs/design.md:170-201 explains the inverted fail direction clearly and a future maintainer will not "fix" it back — that section is genuinely good. Two corrections needed: (a) "a pure function of (content, component config)" is false for extract_llm, which is the caller that matters most — scope the claim to the deterministic offloaders and state the extract_llm exception in the doc, not only at the call site; (b) "The sliding TTL shrinks that window" for MaxCachedIdx needs the eviction half (finding 5). mkdocs build --strict not verified (mkdocs not installed here) — please confirm.

---

Minimum to land

1. Don't let extract_llm mutate at depth on an unverified re-derivation (blockers 1+2) — or verify the bytes before splicing.
2. One key for result+summary (finding 3).
3. Expired pinned entries must be evictable (finding 4).
4. Pin or protect cg:len: (finding 5).
5. Stop scoring over-cap decisions as dropped-then-repaired (findings 6+7).

Everything else is comments and docs.

[OsherElhadad]

Thanks — this was a good catch list. All 10 items addressed in f6aa72c; every fix has a test that fails without it. Full gates re-run: build, test -tags cg_skeleton ./..., -race -count=5 on store+components/offload (419 s), gofmt -l clean, go vet clean.

BLOCKER 1 — you're right, and the trade argument was wrong

extract_llm is now excluded from the repair path entirely. I'd argued the repair was worth it because the alternative was a guaranteed suffix cache-write. That reasoning doesn't hold: if the re-derived bytes differ, the suffix is cache-written either way, so the repair branch just adds a model call. No upside — so there was never a trade to make. repairLostResult is deleted.

Confirmed your reproduction rather than taking it on faith: components/all/freeze_repair_test.go drives extract_llm with a stub model returning a different valid projection per call. On 3f7d700 the depth message comes back re-projected with fresh bytes (verbatim=false, sameAsTurn1=false) plus an extra model call; on f6aa72c it's left verbatim with no re-derivation call.

mask/failed_run keep the repair, for exactly the reason you gave — prefix + headPeek(content) + Marker(sha256(content)) is pure in (content, config) and position-independent. That distinction is now the documented precondition for the repair, not an incidental property.

BLOCKER 2 — same fix

Covered by the exclusion: the gate is no longer lifted for the one component whose result isn't guaranteed. Noted at the call site that the model may not run at all (throttle, timeout, floor) as an independent reason the lifted gate was unsafe. And yes — this means part C does not help the shipped codesmart config. Stated plainly in the PR body now (see below) rather than implied.

HIGH 3 — one key

cg:res: + cg:sum1: collapsed into one JSON value (cachedResult{p,s}). Deleted summaryKey/getSummary/putSummary. A replay now returns both parts or misses outright — an unreadable payload is also treated as absent, so a half-decision can never be spliced.

HIGH 4 — pins are reclaimable

evictOldest now reclaims expired entries first, pinned included, and a refresh can claim a pin slot that has since freed. Test: 10 dead-session freezes fill the cap, expire, and 30 ordinary Puts must both drop pinnedN and let a new session pin again.

HIGH 5 — cg:len: pinned

Added to the pin set. You're right that deferring A3 wasn't safe while this PR halved the pool it competes for — the change was making that fail-open more likely, not less. Test asserts it survives eviction pressure. Left TailOnly's inversion itself to A3.

Mediums

• 6/7 — root cause fixed rather than patched: noteLost no longer fires at freeze time for an over-cap entry. It's present and readable, so calling it "dropped" both inflated the count with live entries and made the next re-freeze look like a repair. Losses are recorded only in remove; a repeat drop of an already-marked key isn't double-counted.
• 8 — doc corrected: counts drop events, so dropped−repaired is a running balance of outstanding marks, not distinct broken keys.
• 9 — loss-mark budget evicts oldest-first, so a busy session can't delete another's fresh mark. Marked ponytail: — it's one shared FIFO budget, not a per-session quota; the marks are session-scoped and short-lived, so age is a good enough proxy. Per-session quotas if that's ever shown to starve.
• 10 — docs/reference/routes.md now documents all five fields, including that frozen_misses is a lookup counter dominated by the ordinary "not compacted yet" case, and that frozen_dropped is the one measuring harm.

On the write-up

• Layering inversion fixed: the store no longer hardcodes component prefixes — they arrive via store.Options.PinPrefixes. Combined with the one-key change and the removal of the second repair helper, the divergence that produced blockers 1–3 is gone. Fully collapsing the two mechanisms into one helper I've left to feat(components): add xdedup — cross-turn duplicate tool-output references (39.8x measured re-send factor) #27/C3, since only the reproducible offloaders can share the repair path — that's a real asymmetry, not just duplication.
• Shipped-default caveat is now a callout at the top of the benchmark section: the fix is unmeasured on codesmart, the codesmart arm's null result is reported as such, and what the general arm shows is that the mechanism works where reachable — not that the default improves.
• Dropped the −24.7% cw/req normalisation. Agreed it's reading signal into an artifact with arms truncated at different points. frozen_dropped 184 → 0 is the claim; it needs no normalisation.
• SWE control: picked one framing — not matched, so no conclusion drawn, including no "no regression" claim.

#35 coordination

The cg:len: pin is in store.Options.PinPrefixes (store.LenPrefix) and touches no apply logic, so it should compose with S10's tracker-eviction work rather than conflict — if #35 changes how the boundary is derived, the pin keeps protecting whatever key it lands on. Happy to rebase either way.