refresh: the tools as they actually are — checker fix, successions, shape watch, hardened sweep

The branch was cut before an afternoon in which the daily sweep and its
own findings changed these tools materially; as opened, the PR shipped
a safety checker with a known bug (the declared-injection exemption
filtered the output side only — an input carrying an injection-shaped
message, e.g. a chained proxy feeding the pipeline its own output, read
as a message drop nobody made; caught by the first stamped sweep and
fixed with a both-ways bite).

What this refresh brings, each with its tests:
- safetyViolation filters declared injections on BOTH sides;
- findSuccessions: conversation-boundary classification (compaction /
  resume-shaped / fork) with opener pricing; interleaves structurally
  suppressed (never-returns + first-appearance conditions, both
  bite-proven — the one-shot-sidecar phantom was caught by its own
  test);
- census edit rows carry lastHumanAt/anchorDelta (the relation that
  attributed the mid-history edit population to reminder anchoring),
  with far-from-anchor rows flagged and their bytes excerpted to local
  stdout only;
- harvest: shape watch counters (dormant thinking classes, baseline
  prefix sizes) and growth-step snapshots (evidence frozen, scrubbed,
  before capture rotation eats it); shape-verdicts.mjs is the consumer
  so the new ledger fields are never orphan telemetry;
- gate-live: --census on every sweep, rows that compared zero pairs
  marked proves-nothing (ok requires a proving row), and the status
  file stamps the proxy/tools source fingerprints it exercised —
  a verdict that names its config but not its code stays "fresh"
  across code changes it never saw.

proxy/source-fingerprint.mjs is included for the stamp; identical file
ships in the capture PR — merges cleanly in either order, same
precedent as the shared fixtures. docs: dev-loop's closing-gate
section and the consumer setup page ride along.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Gunther-Schulz

docs/CONSUMER-SETUP.md

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

docs/dev-loop.md

@@ -166,6 +166,31 @@ Three things worth keeping from the episode:
   input dies against the cap and fails the sweep the same day, whatever the
   fourth wall turns out to be made of.
 
+## The census names the class; only content names the cause
+
+Row 4 sat "re-opened" for a day with the mechanism unexplained — while an
+outside reporter with far lighter tooling (#78660) had already named it. The
+gap was not effort; it was a structural blindness we designed in: the census
+reduces messages to hashes and ordinals, which is what makes it scalable and
+publishable, and exactly what makes it causally mute. Hashes can say
+same/different/moved; they cannot say "this is the task-tools nudge, and it
+anchors to the last human message." Two rules from the miss:
+
+- **When a class is localized, return to the bytes and to the STRUCTURE.**
+  Read the actual content at the offending position (once, locally — the
+  privacy discipline applies to what gets committed, not to what gets read),
+  and relate the position to conversation structure: roles, anchors,
+  injection zones. The verdict that closed row 4 was one 30-line matcher
+  relating edit positions to the last human-typed message (20 of 22 within
+  ±2). That relation now lives in the census itself (`anchorDelta` on every
+  edit row, with a "far from any anchor = new mechanism" callout) — the
+  matcher was the prototype, per the standing rule about throwaway probes.
+- **Sweep the public tracker when an investigation OPENS, not after it
+  ships.** The row-4 mechanism sat in a public issue for over two weeks
+  while we derived the same facts independently. One `gh search issues` per
+  new unexplained class converts an investigation into a verification —
+  strictly cheaper, and the verification is worth posting back.
+
 ## Never hand-roll identity in a probe
 
 Twice on 2026-07-28 a throwaway probe reached a wrong conclusion because it
@@ -228,6 +253,66 @@ Mechanised on the dotfiles side: `bootstrap/doctor.py` enumerates its own
 test, so a new verdict cannot be added without its could-not-verify case being
 exercised.
 
+## The closing gate: four questions before any proxy work is done
+
+MANDATE (operator, 2026-07-29). Every piece of work here — a fix, an
+investigation, a probe, a doc — answers these four before it closes. Each
+question has a same-day precedent where skipping it cost real time; "no"
+is an acceptable answer, silence is not — and a "no" or "not yet" must
+NAME the missing evidence or design element, which converts it into a
+spec. An unnamed deferral is drift, and a deferral justified by a cited
+rule that collapses under one question was a rationalization, not a
+reason (same day: a trend alarm was declined citing red-before-build,
+which synthetic bites already satisfied; naming the real concern —
+false-fires on deliberate changes — produced the design that dissolved
+it, acknowledge-by-commit, within the hour).
+
+1. **Can this be mechanized?** Interpretation stays human; everything
+   around it is machinery — the check, the annotation, the alarm, the
+   EVIDENCE DELIVERY. The tell remains the throwaway probe: row 4's verdict
+   came from a 30-line matcher that became `anchorDelta` the same day, and
+   the byte-extraction friction that stalled the row for a day became the
+   far-from-anchor excerpt pass. If the answer is "it needs judgment", ask
+   again about the part BELOW the judgment: delivering the inputs to the
+   judgment is always mechanizable.
+2. **Is the evidence harvestable?** Captures rotate on a quadratic clock;
+   a finding that rests on volatile bytes is a finding with an expiry date.
+   If the claim would be unverifiable after rotation, snapshot what proves
+   it — sanitized, via the harvest path — before closing (precedent: the
+   growth-step spec exists because a baseline step's explaining diff dies
+   with the capture).
+3. **Does the census need a new class or annotation?** A class you named
+   by hand while investigating is a classification the census should emit
+   — otherwise the next instance gets re-derived instead of recognized
+   (precedent: `anchorDelta`, occurrence ordinals, the tools-delta kinds
+   all started as hand-derivations). A NAMED deferral can still answer
+   the wrong question here: whether the class deserves an ALARM is
+   question 4's concern — question 3 asks only whether a classification
+   now exists by hand, and a probe that assigns kinds or counts to
+   traffic answers it YES by existing. The one valid deferral argues the
+   derivation is genuinely one-off. (Observed: the resume-boundary
+   classifier was parked with an alarm-shaped basis minutes after its
+   probe had hand-classified every capture; one operator question undid
+   the parking.)
+4. **Did the instruments ride along?** A mitigation change without its
+   replay/gate change ships blind: the gate replays the SERVING config, so
+   an instrument that lags the extension verifies a pipeline nobody runs
+   (precedent: the day every gate run exercised defaults while production
+   ran eleven gates). New state, new record fields, new gates — each lands
+   with its replay handling, its ledger declaration, and its three-answer
+   doctor verdict in the same change.
+
+### Cadence: the gate guards the flow, the sweep re-checks the stock
+
+The closing gate runs at work-time, per change. A dispatched stock-sweep
+(read-only, the four questions over the WHOLE system) is for after building
+bursts — the 2026-07-29 sweep found twelve gaps because twelve pieces of
+machinery had just landed, and its top finding was live within the hour.
+Not a standing schedule: standing machinery must be maintained forever, and
+a sweep of an unchanged system yields nothing. Retirement signal, borrowed
+from skill-craft's consolidation rule: two consecutive sweeps returning
+only minor findings — then the ritual stops until the next burst.
+
 ## Adding a check
 
 Two rules, both learned the expensive way:
@@ -242,6 +327,16 @@ Two rules, both learned the expensive way:
    *different* bug, already fixed. Re-derive which change produced an
    observation before building on it.
 
+   **A bite's expected value comes from the invariant's DEFINITION, never
+   from the implementation or the reasoning that produced it** — an
+   expectation with the same parentage as the code pins the bug it should
+   catch. Write the definitional comment first; the assertion follows from
+   it. (Observed: the succession bite's first draft asserted a
+   one-shot-sidecar handback as a correct succession — same mental model
+   as the code's missing first-appearance condition; writing the
+   definition sentence is what contradicted the assertion, and the
+   phantom-minting bug fell out of the correction.)
+
 3. **The corpus is blind along its own curation axis.** `harvest.mjs` selects
    pairs by *structural novelty* and sanitises them, so the committed fixtures
    are small by construction — and therefore a fixture corpus curated for

proxy/source-fingerprint.mjs

@@ -0,0 +1,80 @@
+// Fingerprint of the proxy's own source tree, computed once at startup and
+// reported on /health as `proxy_tree`.
+//
+// Why this exists. Hot-reload is off, so the running process keeps whatever
+// code it loaded at start; edit proxy/ without restarting and the repo checks
+// pass while the traffic is served by something else. The dotfiles doctor
+// asked that question by comparing the newest MTIME under proxy/ against the
+// unit's start time, with a comment declaring the label to be the whole truth
+// because "what the process holds in memory is not hashable".
+//
+// It is not the whole truth, and 2026-07-28 showed how: restoring a file from
+// a backup after a bite test moved its mtime while leaving the bytes
+// identical, and doctor reported "still running old code" about a proxy that
+// was running exactly the code on disk. A checker that fires on a non-defect
+// trains its reader to ignore it — the same fault, in the same repo, that the
+// mtime comment was written to avoid.
+//
+// What the process holds is not hashable, but what it LOADED is: it can
+// fingerprint its own source at startup and publish the result. Then doctor
+// compares content to content, and mtime churn is silent by construction.
+//
+// The algorithm is deliberately dull, because a second implementation would
+// have to match it: every regular file under the root except node_modules and
+// dot-directories, relative POSIX paths sorted byte-wise, each contributing
+// `path\n<sha256 of contents>\n` to one running hash. Nothing here depends on
+// filesystem order, mtimes, or inode numbers.
+//
+// There is no second implementation: doctor shells out to this file rather
+// than mirroring it in Python. Two implementations of one hash is exactly the
+// kind of duplication that drifts silently and reports a mismatch nobody can
+// explain.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKIP_DIRS = new Set(["node_modules"]);
+
+async function collect(root, dir, out) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      await collect(root, full, out);
+    } else if (e.isFile()) {
+      out.push(relative(root, full).split(sep).join("/"));
+    }
+  }
+  return out;
+}
+
+export async function sourceFingerprint(root) {
+  const files = (await collect(root, root, [])).sort();
+  const h = createHash("sha256");
+  for (const rel of files) {
+    const bytes = await readFile(join(root, rel));
+    h.update(rel);
+    h.update("\n");
+    h.update(createHash("sha256").update(bytes).digest("hex"));
+    h.update("\n");
+  }
+  return h.digest("hex").slice(0, 12);
+}
+
+export const PROXY_ROOT = dirname(fileURLToPath(import.meta.url));
+
+// `node proxy/source-fingerprint.mjs [root]` — the form doctor calls.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const root = process.argv[2] ?? PROXY_ROOT;
+  sourceFingerprint(root).then(
+    (fp) => process.stdout.write(fp + "\n"),
+    (err) => {
+      process.stderr.write(`source-fingerprint failed: ${err?.message ?? err}\n`);
+      process.exit(1);
+    },
+  );
+}

test/gate-live.test.mjs

@@ -104,6 +104,29 @@ test("replay children run under the heap cap, before the script path", () => {
     "cap must precede the script path or node passes it to the script instead",
   );
   assert.ok(args.includes("CACHE_FIX_PREFIXDIFF=1"), "gate env must survive");
+  // Census rides every sweep: dropping it silently reverts the row-4
+  // annotations to on-demand and the daily verdict stops carrying them.
+  assert.ok(args.includes("--census"), "sweep must run the census annotations");
+});
+
+test("BITE — a row that compared zero pairs is marked proves-nothing, never padded into clean", () => {
+  // c-empty (71 requests, all empty bodies) and single-request captures ran
+  // ZERO cross-request checks; before this flag they counted toward
+  // "9 captures clean". Absence of comparison must be visible.
+  const row = summarise("c-empty.jsonl", 10, json({
+    report: Array.from({ length: 71 }, (_, n) => ({ n })),
+    violations: [], safety: [], sequence: [], orderViolations: [],
+    census: { pairs: 0 },
+  }));
+  assert.equal(row.provesNothing, true);
+  assert.equal(rowIsClean(row), true, "proves-nothing is not FAILING — it is not PROVING");
+  const real = summarise("s.jsonl", 10, json({
+    report: [{ n: 0 }, { n: 1 }],
+    violations: [], safety: [], sequence: [], orderViolations: [],
+    census: { pairs: 1 },
+  }));
+  assert.equal(real.provesNothing, false);
+  assert.equal(real.pairs, 1);
 });
 
 test("nothing comparable is NOT a failure — it is an honest absence of evidence", () => {