refresh(tools): gate-warning + --gates-from-capture + marker-blind output metric; extensions synced

Three replay improvements from operating the gate: an unmissable
stderr warning when a gated capture replays under default gates (the
instrument error that booked a wrong verdict three times in one day —
and whose first live fire caught the operator's own gateless replay);
a --gates-from-capture flag applying the all-boot-records union so
nobody hand-extracts gates; and outputForm now strips cache_control
before comparing (a moved cache marker is not a content splice — five
pairs totalling ~0.6 MB of phantom "re-billed splice" were CC's own
benign marker relocation). Extensions synced to the cnighswonger#272/cnighswonger#273 tips so
the slice's real-capture tests exercise the actual pipeline.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TZxGrF1LRBvmb7cFXmS2DH

Author: Gunther-Schulz

proxy/extensions/deferred-tool-rewrite.mjs

@@ -405,37 +405,62 @@ export function anchorHash(msg) {
 // re-anchors after the LAST user message — the closest stable position
 // that satisfies the "must follow a user message" placement constraint —
 // and reports it so state can be updated and telemetry emitted.
+//
+// Resolution happens in a first pass against the ORIGINAL `messages` array
+// (never mutated while resolving), so a SHARED anchor's landing position is
+// computed once regardless of how many additions target it. This is what
+// keeps the run FIFO — discovery order, oldest first — instead of the
+// previous idx+1-per-addition splice, which re-found the same anchor fresh
+// on every iteration (the search excludes role==="system", so
+// already-injected additions were invisible to it) and always landed the
+// newest addition closest to the anchor: a LIFO stack that reordered the
+// already-forwarded prefix on every new addition (probe s-dc3f8071,
+// n=372-397, 25 stability violations during an MCP discovery cascade).
 export function injectAdditions(messages, additions) {
   if (!Array.isArray(additions) || additions.length === 0) {
     return { messages, reanchored: [] };
   }
-  const out = [...messages];
+
+  let lastUserIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "user") {
+      lastUserIdx = i;
+      break;
+    }
+  }
+
   const reanchored = [];
+  // Original-array index -> messages to inject right after it, in discovery
+  // (oldest-first) order — the run for a shared anchor.
+  const byAnchorIdx = new Map();
+
   for (const add of additions) {
-    const idx = out.findIndex((m) => m.role !== "system" && anchorHash(m) === add.anchorHash);
-    if (idx >= 0) {
-      out.splice(idx + 1, 0, add.message);
-    } else {
-      let lastUser = -1;
-      for (let i = out.length - 1; i >= 0; i--) {
-        if (out[i].role === "user") {
-          lastUser = i;
-          break;
-        }
-      }
-      if (lastUser >= 0) {
-        out.splice(lastUser + 1, 0, add.message);
-        const newAnchor = anchorHash(out[lastUser]);
-        reanchored.push({ names: add.names, anchorHash: newAnchor });
+    const idx = messages.findIndex((m) => m.role !== "system" && anchorHash(m) === add.anchorHash);
+    let landingIdx = idx;
+    if (idx < 0) {
+      if (lastUserIdx >= 0) {
+        landingIdx = lastUserIdx;
+        reanchored.push({ names: add.names, anchorHash: anchorHash(messages[lastUserIdx]) });
       } else {
         // No user message at all — cannot satisfy the placement
         // constraint; skip this injection (the tool stays deferred and
         // unloaded this request; honest degradation, not a malformed
         // request).
         reanchored.push({ names: add.names, anchorHash: null });
+        continue;
       }
     }
+    if (!byAnchorIdx.has(landingIdx)) byAnchorIdx.set(landingIdx, []);
+    byAnchorIdx.get(landingIdx).push(add.message);
   }
+
+  const out = [];
+  messages.forEach((m, i) => {
+    out.push(m);
+    const injected = byAnchorIdx.get(i);
+    if (injected) out.push(...injected);
+  });
+
   return { messages: out, reanchored };
 }
 

test/census-output-hash.test.mjs

@@ -0,0 +1,111 @@
+// census-output-hash — unit bites for the outHashSem strip added to
+// findMitigationGaps' outputForm/outputPreserved/rebilledOutBytes.
+// BACKLOG.md: "READY — census outputForm hashes must strip cache_control
+// (mirror the input side)."
+//
+// DEFINITION under test (stated before the assertions, per dev-loop.md's
+// "Adding a check" — a bite's expected value comes from the invariant's
+// DEFINITION, never from the implementation): cache_control designates a
+// cache breakpoint, it is not conversation content. A pair of forwarded
+// messages that differ ONLY in whether/where a cache_control block is
+// attached is not a content splice — the model-visible bytes are
+// identical, only the cache metadata moved. A pair that differs in actual
+// TEXT is a real edit regardless of any cache_control noise riding along,
+// and must still be caught (a checker that stops firing on the marker
+// case must not also stop firing on the real one — the "fires on a
+// non-defect" and "misses a real defect" failures are both broken the
+// same way, dev-loop.md).
+//
+// These are unit-level bites on findMitigationGaps directly (synthetic
+// entries), the small-corpus sibling of the real-capture assertions in
+// test/mitigation-output-form.test.mjs.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { findMitigationGaps } from "../tools/replay.mjs";
+
+const user = (t) => ({ role: "user", content: [{ type: "text", text: t }] });
+const asst = (t) => ({ role: "assistant", content: [{ type: "text", text: t }] });
+
+// One capture entry in the pre-compactEntry shape findMitigationGaps'
+// caller (asCompact) accepts — same shape test/mitigation-output-form.test.mjs
+// uses.
+const entry = (n, inMsgs, outMsgs, extra = {}) => ({
+  n,
+  ts: `2026-07-30T00:00:${String(n).padStart(2, "0")}Z`,
+  key: "k",
+  inMsgs,
+  outMsgs,
+  action: null,
+  resetReason: null,
+  ...extra,
+});
+
+// --- red-first observation (recorded, not re-asserted): before the strip
+// existed, this exact scenario ran through unpatched findMitigationGaps
+// (outHash built from raw JSON.stringify(message), no cache_control strip)
+// and returned outputForm: "edit@1", outputPreserved: false,
+// rebilledOutBytes: 24 (the tail-only bytes) — the marker relocation read
+// as a content splice. Observed by running this file against the
+// pre-fix tree (git stash the outHashSem change, `node --test
+// test/census-output-hash.test.mjs`): AssertionError, actual "edit@1" !==
+// "append". That is the real defect this bite targets.
+
+test("census output-hash: a cache_control-only relocation is not a splice (preserved)", () => {
+  // message index 1 carries a cache_control breakpoint while it is the
+  // tail in prevOut; curOut carries the SAME text at the same position
+  // with no cache_control (the breakpoint moved off because the
+  // conversation grew past it — the flap-probe's measured shape,
+  // capture s-633915a8, n=678->681: identical 32,140-char text sent with
+  // a cache_control block while tail, then as a bare string once it
+  // wasn't) and one genuinely new message appended at the tail.
+  const withMarker = {
+    role: "user",
+    content: [{ type: "text", text: "u1", cache_control: { type: "ephemeral", ttl: "1h" } }],
+  };
+  const withoutMarker = { role: "user", content: [{ type: "text", text: "u1" }] };
+
+  const prevIn = [user("u0"), asst("a0"), user("u1")];
+  const curIn = [user("u0"), asst("a0"), user("SPLICED"), user("u1")];
+  const prevOut = [user("u0"), asst("a0"), withMarker];
+  const curOut = [user("u0"), asst("a0"), withoutMarker, user("u2-new")];
+
+  const rows = findMitigationGaps([
+    entry(0, prevIn, prevOut, { action: "append-only" }),
+    entry(1, curIn, curOut, { action: "normalized" }),
+  ]);
+
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].kind, "splice/insert-mid", "input-side classification is unchanged");
+  assert.equal(rows[0].outputForm, "append", "marker-only delta must not read as a splice/edit");
+  assert.equal(rows[0].outputPreserved, true);
+  assert.equal(rows[0].rebilledOutBytes, 0);
+});
+
+test("census output-hash: a real text delta beside a cache_control change is still caught", () => {
+  // Same shape as above, but message index 1's TEXT also changes, not
+  // just its cache_control. The checker must still fire — stripping
+  // cache_control must not also blind it to a genuine edit riding
+  // alongside one.
+  const withMarker = {
+    role: "user",
+    content: [{ type: "text", text: "u1", cache_control: { type: "ephemeral", ttl: "1h" } }],
+  };
+  const editedNoMarker = { role: "user", content: [{ type: "text", text: "u1-EDITED" }] };
+
+  const prevIn = [user("u0"), asst("a0"), user("u1")];
+  const curIn = [user("u0"), asst("a0"), user("SPLICED"), user("u1")];
+  const prevOut = [user("u0"), asst("a0"), withMarker];
+  const curOut = [user("u0"), asst("a0"), editedNoMarker, user("u2-new")];
+
+  const rows = findMitigationGaps([
+    entry(0, prevIn, prevOut, { action: "append-only" }),
+    entry(1, curIn, curOut, { action: "normalized" }),
+  ]);
+
+  assert.equal(rows.length, 1);
+  assert.notEqual(rows[0].outputForm, "append", "a genuine text edit must still be flagged");
+  assert.equal(rows[0].outputPreserved, false);
+  assert.ok(rows[0].rebilledOutBytes > 0);
+});

test/deferred-tool-rewrite.test.mjs

@@ -254,6 +254,70 @@ test("injectAdditions: no user message at all → injection skipped, reported wi
   assert.equal(reanchored[0].anchorHash, null);
 });
 
+// BITE — the LIFO bug (BACKLOG "READY — fix injectAdditions' LIFO stacking").
+// Real capture s-dc3f8071, n=372-397: an MCP-tool-discovery cascade produces
+// one new `additions` entry per request, all anchored to the SAME message
+// (the real conversation stays at 1 message the whole burst). The buggy
+// implementation re-finds the anchor fresh on every iteration (the search
+// excludes role==="system", so already-injected additions are invisible to
+// it) and always splices at anchorIdx+1 — so the newest addition always
+// lands closest to the anchor, pushing every earlier addition one slot
+// further back: a LIFO stack that reorders the already-forwarded prefix on
+// every new addition. Fix: a shared anchor's run stays in discovery order
+// (FIFO) — a new addition appends AFTER the additions already injected
+// there, so the forwarded prefix is a byte-stable prefix of every
+// subsequent output and only the tail of the run grows.
+test("injectAdditions: three additions sharing one anchor → output is discovery order (FIFO), not LIFO", () => {
+  const u0 = { role: "user", content: [{ type: "text", text: "u0" }] };
+  const sharedAnchor = anchorHash(u0);
+  const addA = buildToolAdditionMessage(["ToolA"]);
+  const addB = buildToolAdditionMessage(["ToolB"]);
+  const addC = buildToolAdditionMessage(["ToolC"]);
+
+  // additions array is in DISCOVERY order (oldest first), matching how
+  // onRequest concatenates them across successive requests.
+  const additions = [
+    { names: ["ToolA"], anchorHash: sharedAnchor, message: addA },
+    { names: ["ToolB"], anchorHash: sharedAnchor, message: addB },
+    { names: ["ToolC"], anchorHash: sharedAnchor, message: addC },
+  ];
+
+  const { messages } = injectAdditions([u0], additions);
+  assert.deepEqual(
+    messages.map((m) => m.content?.[0]?.tool?.name ?? "u0"),
+    ["u0", "ToolA", "ToolB", "ToolC"],
+    "run stays in discovery order — ToolA first (oldest), ToolC last (newest), never reordered",
+  );
+});
+
+test("injectAdditions: shared-anchor prefix stability — output N is a byte-prefix of output N+1", () => {
+  const u0 = { role: "user", content: [{ type: "text", text: "u0" }] };
+  const sharedAnchor = anchorHash(u0);
+  const addA = buildToolAdditionMessage(["ToolA"]);
+  const addB = buildToolAdditionMessage(["ToolB"]);
+
+  // Simulates two successive requests: first only ToolA has been discovered,
+  // then ToolB arrives too (additions accumulate, oldest first — as onRequest
+  // does via `additions.concat([...])`).
+  const afterFirst = injectAdditions([u0], [{ names: ["ToolA"], anchorHash: sharedAnchor, message: addA }]);
+  const afterSecond = injectAdditions(
+    [u0],
+    [
+      { names: ["ToolA"], anchorHash: sharedAnchor, message: addA },
+      { names: ["ToolB"], anchorHash: sharedAnchor, message: addB },
+    ],
+  );
+
+  const prefixBytes = JSON.stringify(afterFirst.messages);
+  const nextBytes = JSON.stringify(afterSecond.messages.slice(0, afterFirst.messages.length));
+  assert.equal(
+    nextBytes,
+    prefixBytes,
+    "the already-forwarded prefix must be byte-identical once a new addition arrives — only the tail grows",
+  );
+  assert.equal(afterSecond.messages.length, 3, "the new addition appends at the tail of the run");
+});
+
 test("forwardedTools: names covered by additions get defer_loading, others stay untouched", () => {
   const known = [tool("Read"), tool("SendMessage")];
   const additions = [{ names: ["SendMessage"], anchorHash: "h", message: {} }];
@@ -449,6 +513,53 @@ test("onRequest: pruned anchor → re-anchor once, stable thereafter", async ()
   }
 });
 
+test("onRequest BITE: MCP-discovery cascade — same 1-message conversation, tools[] grows 3x → additions stack in discovery order, prefix stable", async () => {
+  // Mirrors the real capture (s-dc3f8071, n=372-397): CC's own progressive
+  // MCP-tool-discovery cascade at session boot sends one new tool batch per
+  // request while the real conversation never grows past 1 message, so every
+  // addition shares the identical anchor (messages[0]).
+  const dir = await newTmp();
+  const headers = { "x-claude-code-session-id": "sess-cascade" };
+  try {
+    await withEnvAsync({ CACHE_FIX_TOOL_REWRITE: "1" }, async () => {
+      const u0 = { role: "user", content: [{ type: "text", text: "u0" }] };
+      const base = { system: [], messages: [u0], model: "claude-opus-5" };
+
+      await runExt({ ...base, tools: [tool("Read"), tool("Bash")] }, { headers, dir }); // no-baseline
+      const ctx1 = await runExt(
+        { ...base, tools: [tool("Read"), tool("Bash"), tool("ToolA")] },
+        { headers, dir },
+      );
+      const ctx2 = await runExt(
+        { ...base, tools: [tool("Read"), tool("Bash"), tool("ToolA"), tool("ToolB")] },
+        { headers, dir },
+      );
+      const ctx3 = await runExt(
+        { ...base, tools: [tool("Read"), tool("Bash"), tool("ToolA"), tool("ToolB"), tool("ToolC")] },
+        { headers, dir },
+      );
+
+      const names = (ctx) =>
+        ctx.body.messages
+          .filter((m) => m.role === "system" && Array.isArray(m.content) && m.content[0]?.type === "tool_addition")
+          .flatMap((m) => m.content.map((b) => b.tool.name));
+
+      assert.deepEqual(names(ctx1), ["ToolA"]);
+      assert.deepEqual(names(ctx2), ["ToolA", "ToolB"], "ToolA stays first — discovery order, not LIFO");
+      assert.deepEqual(names(ctx3), ["ToolA", "ToolB", "ToolC"], "run grows only at the tail");
+
+      // The forwarded prefix already produced must be a byte-prefix of the
+      // next request's output — this is the "reorders the already-forwarded
+      // prefix" bust the probe measured.
+      const prefixOf = (ctx, n) => JSON.stringify(ctx.body.messages.slice(0, n));
+      assert.equal(prefixOf(ctx2, ctx1.body.messages.length), JSON.stringify(ctx1.body.messages));
+      assert.equal(prefixOf(ctx3, ctx2.body.messages.length), JSON.stringify(ctx2.body.messages));
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("onRequest: a tool removed after an addition → HELD (rewrite, passthrough of held tool), no beta header (nothing new to defer)", async () => {
   const dir = await newTmp();
   const headers = { "x-claude-code-session-id": "sess-hold" };

test/insertion-suppression.test.mjs

@@ -351,9 +351,14 @@ test(
       // bounded contribution, not the BACKLOG entry's stated "outputForm
       // === append" criterion, which this pair cannot reach while
       // ttl-management's marker relocation exists. Surfaced as a gap.
-      assert.equal(row.outputForm, "edit@48", "residual divergence is the KNOWN, unrelated ttl-management marker relocation, not the reminder-swap");
-      assert.equal(row.outputPreserved, false);
-      assert.ok(row.rebilledOutBytes > 0 && row.rebilledOutBytes < 10000, "residual is the marker-sized tail, not the ~61kB pre-fix splice");
+      // The only remaining delta is ttl-management's cache_control marker
+      // relocating off the old tail — since the outputForm metric strips
+      // cache_control (903a2be: a moved marker is not a content splice),
+      // the suppressed pair now reads fully preserved. A regression that
+      // reintroduces CONTENT divergence flips this to a non-append form.
+      assert.equal(row.outputForm, "append", "suppression + marker-blind metric: nothing but the marker moved");
+      assert.equal(row.outputPreserved, true);
+      assert.equal(row.rebilledOutBytes, 0);
 
       // The n=28 entry itself: exactly one suppression, at the index the
       // fidelity probe named (message[31] in the pre-fix pipeline).