feat(prefix-diff): full cache-key attribution — marker windows, tail snapshots, per-tenant baselines

[Gunther-Schulz]

Rework of prefix-diff from a head-only preview into the attribution instrument the rest of the series cites. Read-only throughout — it observes and logs, never mutates a request — so the blast radius is misreporting, not corruption.

What changed, each step measured

• Marker-anchored + tail snapshot windows — long-session busts were invisible to the head-only diff: on every deep request the divergence sat past the preview window, and the log said "no differences" while the bill said otherwise.
• Full cache-key coverage — params (model, max_tokens, thinking, output_config, speed), betas, and the anthropic-beta header. Each was a blind spot that produced a false "clean" on a real bust.
• Per-tenant baselines — keyed by the agent-id header when present, else the full system-prompt hash. The prior 400-char truncation merged agents sharing a long preamble (the shape every real agent system prompt has), silently combining baselines and attributing diffs to the wrong conversation. Co-tenant diffs are labelled as such, never guessed. The truncation bite is pinned: two prompts sharing a ~960-char preamble must not collide.
• Change-kind recording — how a mid-history message changed (which block, what kind), not only where; the where alone cannot separate a reminder rewrite from a genuine edit.
• Robustness — per-key write serialization, timestamp-based eviction, preview of every content shape.

Evidence

84 tests green. This instrument produced the attribution lines quoted in #272/#273's evidence and in anthropics/claude-code#76606/#81967 — e.g. classifying system[…], tools[Agent:added,…], messages@0(user), header:anthropic-beta[+…] per request pair in production. Standalone: no dependency on the other PRs in the series.

🤖 Generated with Claude Code

[Gunther-Schulz]

Pushed wave 2 for this slice — one commit, 69497a3: event records carry their tap-point view marker, single-sourced from the module's own ordering, so a prefix-diff attribution can say which extension's view it measured. Tests: 85 pass / 0 fail. One deliberate surplus vs. the fork: this branch keeps its tenantId full-text-hash collision test, which the fork solved differently — nothing from the fork commit is missing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TcivCe2iLnKZxpB4qTXzEb

[vsits-codex-review-agent]

Review: prefix-diff attribution rewrite

Date: 2026-07-31
Reviewed: PR #280 at 69497a3 (merged onto origin/main 81f47a5; review worktree HEAD a87d1e494c6e399b7416ee47af453423bc26ac87)
Round: 1
Label applied: changes-requested

What Is Correct

• The extension remains read-only with respect to the request pipeline. The only hook call is snapshotPrefix(ctx.body, { headers: ctx.headers }), and I found no assignment to ctx.body, ctx.headers, or ctx.meta in proxy/extensions/prefix-diff.mjs:1150-1158.
• The merged suite passed cleanly at the review head: 1500 tests, 0 failures.
• The size increase is at least attached to the stated defect rather than obviously dead code. Compared with origin/main's 277-line implementation, this file is now 1,160 lines (+959/-76 in the diff). The production diff adds 959 LOC with 927 test LOC behind it (0.97x test:prod), no new env vars, no new files, one new persisted artifact family (<key>-events.jsonl, plus .1 rotation), and 17 additional named test seams. Subsystem-by-subsystem: stable session keys, cache-key param coverage, beta-header coverage, per-tenant baselines, per-key serialization, and timestamp-based tenant eviction are all load-bearing for the capability the PR claims; I am not blocking on size alone.

Blockers

• The rewrite persists substantially more request content to disk than the old diagnostic, and does so without explicit file-mode hardening. buildSystemSnapshot() now stores system-block text up to 20,000 chars per block (proxy/extensions/prefix-diff.mjs:320-352), buildMessageHashes() stores a preview on every message index (proxy/extensions/prefix-diff.mjs:436-455), and buildEventRecord() persists divergent message previews plus system windows into the append-only ledger (proxy/extensions/prefix-diff.mjs:807-858). Those artifacts are then written with plain writeFile / appendFile and no explicit mode or post-write chmod (proxy/extensions/prefix-diff.mjs:877-897). That makes the PR's risk framing inaccurate: worst case is no longer just misreporting, it is also durable prompt-derived content retention under whatever umask the host happens to use. On this repo, anything that persists request bodies or system prompts is security-relevant and needs an explicit permissions/retention story.
• The per-tenant timestamp eviction only bounds tenants within one session key; it does not bound the number of session-key files in ~/.claude/cache-fix-snapshots/. Each new session key gets its own -last.json, -diff.json, and -events.jsonl (plus rotated .1) at proxy/extensions/prefix-diff.mjs:963-966, while eviction only trims the in-file tenant map at proxy/extensions/prefix-diff.mjs:1073-1096. There is no cross-key GC, TTL, cap, or sweep. For an opt-in diagnostic on a long-lived proxy, "timestamp eviction" therefore does not answer the unbounded-growth question that matters operationally: total file count and total retained bytes across sessions can still grow forever.

What Needs Attention

• This is load-bearing even without a directive. The PR changes a shared telemetry/persistence format and writes prompt-derived material to disk, so the missing ## Non-Functional Requirements / Load-bearing? section should be corrected in the PR description before merge.
• The full-system-prompt hash used for tenant fallback is not itself a content leak; it is a one-pass SHA over in-memory text (proxy/extensions/prefix-diff.mjs:247-269). The actual leak surface is the persisted snapshot/ledger content called out above.
• The tests are broad (85 tests in test/proxy-prefix-diff.test.mjs) and do cover read-only behavior, header passthrough, beta-header diffs, concurrent tenant baselines, and tenant eviction, but they do not currently pin file permissions or any cross-key retention policy.

Bloat / Non-Functional

• Size numbers: old implementation 277 lines, new implementation 1,160 lines; diff +959/-76; production added lines split roughly into 547 code and 412 comment/blank lines; tests add 927 LOC (0.97x).
• Per-subsystem bloat assessment: marker windows, tail snapshots, full cache-key coverage, per-tenant baselines, per-key serialization, and timestamp eviction each have a concrete defect anchor in the claimed capability. The line mass I could not justify as strictly necessary for the defect is not a separate abstraction so much as the decision to make the ledger self-contained by persisting rich content. That is why my blocking finding is about retention/security surface, not "too many tests" or comment density.

Recommendations

• Either reduce the persisted content surface back to hashes/bounded metadata, or explicitly harden and document it: 0600 writes, retention/GC across session keys, and a clear statement that enabling CACHE_FIX_PREFIXDIFF=1 stores prompt-derived content on disk.
• Add a cross-key cleanup policy so the snapshot directory is bounded over time, not just each per-session tenant map.
• Update the PR description with explicit non-functional requirements and load-bearing classification, since this now changes diagnostic schema and local persistence semantics rather than only log wording.

Bottom Line

The extension does appear read-only in the request path, and the attribution features are mostly tied to real blind spots rather than obvious speculative abstraction. I am still requesting changes because the rewrite materially enlarges the on-disk content and retention surface without explicit permissions or a cross-session bound, so the current "misreporting only" risk framing does not hold. — Codex review

[vsits-proxy-builder]

Review result: changes requested. One correction to the framing, and a bound that's missing.

The read-only claim holds. We checked it independently — the only pipeline touch is snapshotPrefix(ctx.body, { headers: ctx.headers }), no assignment to ctx.body, ctx.headers, or ctx.meta anywhere in the module. That's the claim that made this the low-risk member of the series, and it survived scrutiny.

But "blast radius is misreporting, not corruption" doesn't follow from it. The rewrite persists prompt-derived content, not just hashes:

• buildSystemSnapshot() stores text: system.slice(0, SYSTEM_TEXT_CAP) — up to 20,000 chars of system-prompt text per block (:320-352). The comment is explicit that this is deliberate: full text rather than an opaque hash so the diff can point at exact bytes.
• buildMessageHashes() keeps a preview per message index (:436-455); buildEventRecord() persists divergent previews plus system windows into the ledger (:807-858).

And the writes carry no mode — writeFile at :881, appendFile at :897, no mode:, no chmod. So on a default-umask host that's prompt content at 0644.

Not mutating the request is not the same as not retaining it. Worst case here is durable retention of prompt-derived material, which is a different risk class than a wrong log line.

Second blocker: nothing bounds the snapshot directory across sessions. Timestamp eviction trims the tenant map within a key (:1073-1096), but every new session key gets its own -last.json, -diff.json, and -events.jsonl plus rotation (:963-966). No cross-key GC, TTL, or cap. On a long-lived proxy the file count and total bytes grow without limit — and given the point above, what's growing is prompt-derived content.

Either bound the content (hashes and bounded metadata) or bound the retention (0600, cross-key sweep, documented TTL) — and say plainly in the README that CACHE_FIX_PREFIXDIFF=1 writes prompt-derived content to disk. Right now someone enabling a "diagnostic" wouldn't expect that.

On size: 277 lines → 1,160. We went through it subsystem by subsystem and marker windows, tail snapshots, full cache-key coverage, per-tenant baselines, per-key serialization, and timestamp eviction each anchor to a real blind spot you documented. Not blocking on size — the extra mass is the decision to make the ledger self-contained by persisting rich content, which is the same decision the blocker above is about. Fix that and the size question mostly resolves itself.

The 400-char truncation bug is a good catch, incidentally — merging agents that share a long preamble would produce confidently wrong attribution, which is worse than no attribution.

Process: load-bearing (persistence semantics + prompt-derived content on disk), so human review from Chris before merge. A ## Non-Functional Requirements section would help — we now ask for one on PRs this size, see CONTRIBUTING.md added today. Fork PRs don't get CI here; we ran it locally: 1500/0 merged onto main.

— Proxy Builder