claude-code-cache-fix 3.9.0 → 4.1.0

package/proxy/extensions/thinking-block-sanitize.mjs

@@ -1,12 +1,27 @@
 // thinking-block-sanitize — request-path mitigation for the CC thinking-desync
-// wedge (anthropics/claude-code#63147). On replay paths (resume / --continue /
+// wedge (anthropics/claude-code#63147).
+//
+// v1 (default since v4.0.0; CACHE_FIX_THINKING_SANITIZE unset or =on): On replay paths (resume / --continue /
 // auto-compaction / parallel-tool-cancel), CC re-sends prior assistant turns'
 // thinking in the OMITTED shape `{ type:"thinking", thinking:"", signature }`.
 // The API rejects modified thinking in the *latest* assistant message with a
-// permanent 400, which wedges the session. This extension drops the omitted
-// thinking blocks the API treats as optional, before the request is forwarded.
+// permanent 400, which wedges the session. v1 drops these omitted blocks
+// before forwarding. Never touches non-empty thinking; never touches
+// redacted_thinking (v1's empirical exclusion — zero observed in worst-case
+// wedged transcripts).
+//
+// v2 (CACHE_FIX_THINKING_SANITIZE=v2): Additionally handles yurukusa's "13E"
+// pattern — when ToolSearch dynamically loads a tool mid-conversation, the
+// prior assistant turn's thinking signature is invalidated because it was
+// computed over the now-stale tools surface. The API rejects + CC's harness
+// strips-and-retries, paying a 400 + retry tax every turn. v2 detects
+// cross-request tools-surface change via a per-session tools-hash baseline,
+// and strips ALL prior-turn signed thinking (both `thinking` blocks with
+// non-empty text AND `redacted_thinking` blocks — v2's scope is structural,
+// not empirical) on hash mismatch. Same active-tool-continuation latest-turn
+// guard as v1.
 //
-// Resolved turn-selection rule (directive Open Question 1, empirical capture):
+// Resolved turn-selection rule (v1 directive Open Question 1, empirical capture):
 //   - drop omitted thinking from ALL prior assistant turns, AND
 //   - from the LATEST assistant turn UNLESS it is an active tool-continuation
 //     (last block is a tool_use with a following tool_result) — that case is
@@ -16,15 +31,47 @@
 //     / MAX_THINKING_TOKENS=0 stop it only by disabling thinking entirely
 //     (lossy); DISABLE_INTERLEAVED_THINKING=1 does NOT stop the 400 — so the
 //     answer for that case is don't-resume + heal/retire.
-// Never touches non-empty thinking, and never touches redacted_thinking (v1).
 //
-// OPT-IN for v1: only runs when CACHE_FIX_THINKING_SANITIZE=on (default off) —
-// it mutates request bodies and its coverage is not yet live-validated.
+// v2 state pattern (per directive proxy-thinking-block-sanitize-v2.md):
+//   - In-memory per-session map keyed by canonical session filename, seeded
+//     once from sessions/<sid>.json on first request that session. Mirrors
+//     session-health's pattern. Lives at module scope.
+//   - Baseline updates ONLY on response success (HTTP 2xx). 4xx/5xx leave
+//     the baseline unchanged so a failed request's hash doesn't become the
+//     new ground truth.
+//   - First request observes-and-establishes (no strip; baseline is set
+//     after the response succeeds).
+//   - When canonical session id is "unknown" (raw id null/empty/whitespace),
+//     v2 no-ops entirely. The shared sessions/unknown.json would cross-
+//     contaminate baselines across unrelated agents otherwise.
+//
+// Modes via CACHE_FIX_THINKING_SANITIZE (as of v4.0.0 — v1 default-on flip):
+//   unset (or "on")                       — v1 only (omitted-text drop). DEFAULT.
+//   "off"                                 — extension no-ops (explicit disable)
+//   "v2"                                  — v1 + v2 (omitted-text drop AND
+//                                           tools-hash-mismatch drop). v2 is
+//                                           strict superset of v1.
+//   any other value                       — treated as v1 (the default), not off.
+//                                           Matches the precedent of being
+//                                           permissive about the on-path.
+//
+// v1 default-on rationale: 7-day prod dogfood across 37 sessions (2026-05-29
+// → 2026-06-05) on `=on`: zero `cannot be modified` 400s, cache hit-rate
+// aggregate 94.66% vs 92.44% baseline (no prefix degradation), sanitize fired
+// on ~35% of sessions, ~800 blocks dropped per day, max 938K context healthy.
+// v2 stays opt-in via `=v2` because the dogfood only ran v1.
 //
 // Order 550: after the request-body mutators (ttl-management 500) and before
 // session-health (590), so #160's thinking_block_count reflects the forwarded
-// body. The per-request drop count is exposed via ctx.meta._thinkingSanitize
-// for cache-telemetry (600) to merge into the per-session JSON.
+// body. The per-request drop counts are exposed via ctx.meta._thinkingSanitize
+// (v1 counter) and ctx.meta._thinkingSanitizeV2 (v2 counter + baseline) for
+// cache-telemetry (600) to merge into the per-session JSON.
+
+import { readFileSync } from "node:fs";
+import { resolveSessionId, sessionFilePath, sessionFilename } from "./cache-telemetry.mjs";
+import { computeSignatureSurfaceHash } from "./signature-surface-hash.mjs";
+
+// --- v1 predicates ---
 
 export function isOmittedThinking(block) {
   return (
@@ -70,14 +117,38 @@ function latestAssistantIndex(messages) {
   return -1;
 }
 
-// Pure planner: returns { messages, dropped }. Does not mutate the input.
-// `messages` is the new array (a message that loses all content is dropped).
-export function planSanitize(messages) {
-  if (!Array.isArray(messages)) return { messages, dropped: 0 };
+// --- v2 predicate ---
+
+// v2 strips signed `thinking` blocks (non-empty text) AND `redacted_thinking`
+// blocks. v1's `isOmittedThinking` filter handles the empty-text case
+// independently — when both flags are active, v1 drops the empty ones and v2
+// drops the signed ones; predicates are non-overlapping.
+export function isSignedThinkingForV2(block) {
+  if (!block) return false;
+  if (block.type === "redacted_thinking") return true;
+  // Non-empty thinking with a signature — v1 leaves these alone by design.
+  return (
+    block.type === "thinking" &&
+    typeof block.thinking === "string" &&
+    block.thinking.trim() !== "" &&
+    typeof block.signature === "string" &&
+    block.signature.length > 0
+  );
+}
+
+// --- Pure planner ---
+//
+// Returns { messages, dropped, droppedV2 }. Does not mutate input.
+// `v2StripSigned` is the externally-determined boolean: should v2's
+// signed-thinking drop fire this request? (Caller has already computed
+// hash mismatch + session-state checks.)
+export function planSanitize(messages, { v2StripSigned = false } = {}) {
+  if (!Array.isArray(messages)) return { messages, dropped: 0, droppedV2: 0 };
   const latestAsst = latestAssistantIndex(messages);
   const protectLatest = latestAsst >= 0 && isActiveToolContinuation(messages, latestAsst);
 
   let dropped = 0;
+  let droppedV2 = 0;
   let changed = false;
   const out = [];
   for (let i = 0; i < messages.length; i++) {
@@ -87,14 +158,24 @@ export function planSanitize(messages) {
       continue;
     }
     if (i === latestAsst && protectLatest) {
-      out.push(msg); // active continuation — leave its thinking intact
+      // Active continuation — leave thinking intact (both v1 and v2 respect
+      // this; the API needs the signed thinking for the pending tool call).
+      out.push(msg);
       continue;
     }
     const kept = msg.content.filter((b) => {
+      // v1 always-active drop predicate.
       if (isOmittedThinking(b)) {
         dropped++;
         return false;
       }
+      // v2-only drop predicate. Predicates are mutually exclusive on a single
+      // block: omitted thinking matches v1's predicate but not v2's, and
+      // signed/redacted thinking matches v2's predicate but not v1's.
+      if (v2StripSigned && isSignedThinkingForV2(b)) {
+        droppedV2++;
+        return false;
+      }
       return true;
     });
     if (kept.length === msg.content.length) {
@@ -106,25 +187,158 @@ export function planSanitize(messages) {
       changed = true;
     }
   }
-  return { messages: changed ? out : messages, dropped };
+  return { messages: changed ? out : messages, dropped, droppedV2 };
+}
+
+// --- v2 mode + state ---
+
+// "off" | "on" | "v2". As of v4.0.0 the default flipped from "off" to "on" —
+// v1 (omitted-text drop) is the new default behavior. Set
+// CACHE_FIX_THINKING_SANITIZE=off to explicitly disable; =v2 to additionally
+// enable the v2 tools-hash-mismatch drop (still opt-in pending its own
+// prod-dogfood window after #200 closes the silent-load failure mode).
+// Unknown values fall through to "on" — we are permissive about the on-path
+// and only treat the literal "off" as a disable.
+export function modeFromEnv(env = process.env) {
+  const v = env.CACHE_FIX_THINKING_SANITIZE;
+  if (v === "off") return "off";
+  if (v === "v2") return "v2";
+  return "on";
+}
+
+// Per-session state, in memory. Keyed by canonical session filename
+// (sessionFilename(rawId)). Each entry: { tools_hash_baseline }.
+// Mirrors session-health's pattern: seeded once from disk on first request
+// that session, then maintained in memory + persisted via cache-telemetry's
+// spread of ctx.meta._thinkingSanitizeV2.
+const v2SessionState = new Map();
+
+function seedV2FromFile(rawSid) {
+  let prev = null;
+  try {
+    prev = JSON.parse(readFileSync(sessionFilePath(rawSid), "utf8"));
+  } catch {}
+  return {
+    tools_hash_baseline:
+      typeof prev?.tools_hash_baseline === "string" ? prev.tools_hash_baseline : null,
+  };
+}
+
+// Test-only reset (also useful for proxy-restart simulation in unit tests).
+export function _resetV2State() {
+  v2SessionState.clear();
 }
 
+// --- Extension default-export ---
+
 export default {
   name: "thinking-block-sanitize",
   description:
-    "Drop omitted (empty-text) thinking blocks from prior assistant turns and the latest non-continuation turn, to head off the CC thinking-desync 400 (#63147). Opt-in via CACHE_FIX_THINKING_SANITIZE=on.",
+    "Drop omitted (empty-text) thinking blocks from prior assistant turns and the latest non-continuation turn, to head off the CC thinking-desync 400 (#63147). v1 mode: omitted-text drop only. v2 mode: also drop signed thinking + redacted_thinking on cross-request tools-hash mismatch (ToolSearch surface). v1 is now ON by default as of v4.0.0; set CACHE_FIX_THINKING_SANITIZE=off to disable, =v2 to additionally opt into v2.",
   order: 550,
 
   async onRequest(ctx) {
-    if (process.env.CACHE_FIX_THINKING_SANITIZE !== "on") return;
+    const mode = modeFromEnv();
+    if (mode === "off") return;
+
     const body = ctx.body;
     if (!body || !Array.isArray(body.messages)) return;
 
-    const { messages, dropped } = planSanitize(body.messages);
-    if (dropped > 0) body.messages = messages;
+    // v2 only fires when mode === "v2" AND we have a usable session id.
+    let v2StripSigned = false;
+    let stateKey = null;
+    let currentHash = null;
+
+    if (mode === "v2") {
+      // Resolve session id inline — cache-telemetry's onRequest runs at order
+      // 600, after us, so ctx.meta._sessionId is not yet set when we fire at
+      // order 550. We import resolveSessionId from cache-telemetry to keep
+      // canonicalization consistent.
+      const rawSid = resolveSessionId(ctx.headers);
+      stateKey = sessionFilename(rawSid);
+
+      // "unknown" canonical id → no-op for v2 (cross-contamination risk on
+      // the shared sessions/unknown.json baseline). v1's strip still runs
+      // below regardless.
+      if (stateKey !== "unknown") {
+        currentHash = computeSignatureSurfaceHash({ tools: body.tools });
+
+        // Seed in-memory state from disk on first encounter that session
+        // (covers proxy restart — re-reads persisted baseline).
+        let st = v2SessionState.get(stateKey);
+        if (!st) {
+          st = seedV2FromFile(rawSid);
+          v2SessionState.set(stateKey, st);
+        }
+
+        const baseline = st.tools_hash_baseline;
+        // Mismatch only fires when there IS a baseline AND it differs.
+        // First request (baseline === null) observes-and-establishes — no strip.
+        v2StripSigned = baseline !== null && baseline !== currentHash;
+
+        // Stash for the onResponseStart hook to advance the baseline iff the
+        // response succeeded. Stash BEFORE the plan + strip so the response
+        // path has access regardless of whether anything was dropped.
+        ctx.meta._thinkingSanitizeV2PendingHash = currentHash;
+        ctx.meta._thinkingSanitizeV2StateKey = stateKey;
+      }
+    }
+
+    const { messages, dropped, droppedV2 } = planSanitize(body.messages, {
+      v2StripSigned,
+    });
+    if (dropped > 0 || droppedV2 > 0) body.messages = messages;
 
     // Counts only — never content. Exposed for cache-telemetry to persist and
     // for the #160 session-health signal.
+    // v1 counter — unchanged, fires for both modes.
     ctx.meta._thinkingSanitize = { thinking_blocks_dropped: dropped };
+
+    // v2 counter — fires only in v2 mode. Includes the post-mismatch baseline
+    // value that cache-telemetry will persist (so consumers can see the
+    // current baseline in the session JSON even on requests that didn't
+    // strip). The actual advance only happens on response success below.
+    if (mode === "v2" && stateKey && stateKey !== "unknown") {
+      ctx.meta._thinkingSanitizeV2 = {
+        thinking_blocks_dropped_v2: droppedV2,
+        // Persist the SOON-TO-BE-NEW baseline (it'll be advanced on success).
+        // On 4xx/5xx, the cache-telemetry write still happens but the
+        // in-memory state isn't advanced — next request re-reads disk and
+        // sees the persisted value, which may now disagree with in-memory.
+        // We resolve that by NOT writing the new hash to disk on failure:
+        // see onResponseStart below, which is the only thing that advances
+        // both in-memory and (indirectly via cache-telemetry's spread) disk.
+        // For now, leave tools_hash_baseline at the CURRENT baseline value;
+        // onResponseStart will overwrite this in meta if the response is 2xx.
+        tools_hash_baseline: v2SessionState.get(stateKey)?.tools_hash_baseline ?? null,
+      };
+    }
+  },
+
+  // Advance the baseline only on HTTP 2xx response. 4xx/5xx leaves the
+  // in-memory state and the meta-stashed baseline untouched, so a failed
+  // request's hash never becomes the new ground truth.
+  async onResponseStart(ctx) {
+    const stateKey = ctx.meta._thinkingSanitizeV2StateKey;
+    const pendingHash = ctx.meta._thinkingSanitizeV2PendingHash;
+    if (!stateKey || !pendingHash) return;
+    if (typeof ctx.status !== "number") return;
+    if (ctx.status < 200 || ctx.status >= 300) return;
+
+    // Advance in-memory baseline.
+    let st = v2SessionState.get(stateKey);
+    if (!st) {
+      st = { tools_hash_baseline: null };
+      v2SessionState.set(stateKey, st);
+    }
+    st.tools_hash_baseline = pendingHash;
+
+    // Update the meta-stashed baseline so cache-telemetry's spread writes
+    // the new value to disk. If meta._thinkingSanitizeV2 wasn't stashed
+    // (e.g. mode flip mid-request), construct it now.
+    if (!ctx.meta._thinkingSanitizeV2) {
+      ctx.meta._thinkingSanitizeV2 = { thinking_blocks_dropped_v2: 0 };
+    }
+    ctx.meta._thinkingSanitizeV2.tools_hash_baseline = pendingHash;
   },
 };

package/proxy/extensions/usage-log.mjs

@@ -26,6 +26,7 @@
 //   overage_disabled_reason?: string ≤64             (optional)
 //   cache_hit_rate: float 0–1
 //   q5h_delta, q7d_delta: float (0 on first call after restart)
+//   request_id?: string ≤64                          (optional, gated)
 //
 // `peak_hour` is NOT in the wire format. It can be derived from `ts` if any
 // consumer needs it.
@@ -36,6 +37,17 @@
 // CACHE_FIX_USAGE_LOG=<path> overrides the destination path only — it is NOT
 // an enable flag and never has been.
 //
+// CACHE_FIX_USAGE_LOG_REQID=on emits the optional `request_id` field
+// (sourced from the upstream `request-id` response header). Default-off in
+// v4.1.0 to avoid breaking unpatched claude-meter installs whose strict-
+// object schema rejects unknown keys. claude-meter v0.7.0+ accepts the
+// optional field; the v4.2.0 flip to default-on assumes that floor.
+// The field is the post-hoc join key against CC's per-session JSONL
+// transcripts
+// (`~/.claude/projects/<project>/<session-uuid>.jsonl` carry `requestId`
+// for every API call), which recovers per-CC-session attribution that
+// `sid` alone cannot provide. See docs/directives/proxy-usage-log-request-id.md.
+//
 // See `docs/directives/proxy-claude-meter-compat.md` for full design.
 
 import { appendFile, mkdir } from "node:fs/promises";
@@ -91,6 +103,17 @@ export function extractMessageDeltaFields(event) {
   return { output_tokens: event.usage.output_tokens || 0 };
 }
 
+// Extract upstream request-id from response headers, guarded against the
+// max(64) MeterRowSchema constraint. Returns the string when valid, or
+// `undefined` so the optional schema field is omitted on bad input rather
+// than emitting a row that would fail meter-side validation.
+export function extractRequestId(headers) {
+  const raw = headers?.["request-id"];
+  if (typeof raw !== "string") return undefined;
+  if (raw.length === 0 || raw.length > 64) return undefined;
+  return raw;
+}
+
 function num(headers, key) {
   const v = headers?.[key];
   if (v === undefined || v === null || v === "") return null;
@@ -134,7 +157,7 @@ export function computeDelta(current, previous) {
   return current - previous;
 }
 
-export function assembleRecord({ start, delta, quota, requestedModel, sid, prevQ5h, prevQ7d, now = new Date() }) {
+export function assembleRecord({ start, delta, quota, requestedModel, sid, prevQ5h, prevQ7d, requestId, now = new Date() }) {
   const s = start || {};
   const d = delta || {};
   const q = quota || {};
@@ -194,6 +217,26 @@ export function assembleRecord({ start, delta, quota, requestedModel, sid, prevQ
     record.overage_disabled_reason = q.overage_disabled_reason;
   }
 
+  // Optional: emit request_id when CACHE_FIX_USAGE_LOG_REQID=on AND the
+  // captured value is a non-empty string within the schema's max(64)
+  // constraint. Belt-and-braces: extractRequestId enforces these guards at
+  // capture time, and assembleRecord re-enforces them here so a future
+  // refactor that bypasses the extractor can't emit a row that would fail
+  // claude-meter's strict-object validation.
+  // Env read happens per-call so operators can flip it at runtime without
+  // proxy restart, matching the image-strip debug-gate pattern.
+  // Cross-repo contract: claude-code-meter v0.7.0+ accepts this optional
+  // field; older meter installs reject rows that carry it, so the gate
+  // stays default-off in v4.1.0. Default flips on in cache-fix v4.2.0.
+  if (
+    process.env.CACHE_FIX_USAGE_LOG_REQID === "on" &&
+    typeof requestId === "string" &&
+    requestId.length > 0 &&
+    requestId.length <= 64
+  ) {
+    record.request_id = requestId;
+  }
+
   return record;
 }
 
@@ -250,6 +293,7 @@ export default {
       const delta = extractMessageDeltaFields(ctx.event);
       const quota = parseQuotaHeaders(ctx.responseHeaders || {});
       const requestedModel = ctx.telemetry?.requestedModel || undefined;
+      const requestId = extractRequestId(ctx.responseHeaders || {});
 
       const record = assembleRecord({
         start,
@@ -259,6 +303,7 @@ export default {
         sid: _sid,
         prevQ5h: _lastQ5h,
         prevQ7d: _lastQ7d,
+        requestId,
         now: new Date(),
       });
 

package/proxy/extensions.json

@@ -1,82 +1,20 @@
 {
-  "bootstrap-defense": {
-    "enabled": true,
-    "order": 45
-  },
-  "ttl-tier-detect": {
-    "enabled": true,
-    "order": 75
-  },
-  "fingerprint-strip": {
-    "enabled": true,
-    "order": 100
-  },
-  "image-strip": {
-    "enabled": true,
-    "order": 150
-  },
-  "sort-stabilization": {
-    "enabled": true,
-    "order": 200
-  },
-  "fresh-session-sort": {
-    "enabled": true,
-    "order": 250
-  },
-  "identity-normalization": {
-    "enabled": true,
-    "order": 300
-  },
-  "smoosh-split": {
-    "enabled": true,
-    "order": 320
-  },
-  "content-strip": {
-    "enabled": true,
-    "order": 330
-  },
-  "tool-input-normalize": {
-    "enabled": true,
-    "order": 340
-  },
-  "microcompact-stability": {
-    "enabled": true,
-    "order": 350
-  },
-  "thinking-display": {
-    "enabled": true,
-    "order": 360
-  },
-  "cache-control-normalize": {
-    "enabled": true,
-    "order": 400
-  },
-  "messages-cache-breakpoint": {
-    "enabled": true,
-    "order": 410
-  },
-  "ttl-management": {
-    "enabled": true,
-    "order": 500
-  },
-  "cache-telemetry": {
-    "enabled": true,
-    "order": 600
-  },
-  "overage-warning": {
-    "enabled": true,
-    "order": 610
-  },
-  "request-log": {
-    "enabled": false,
-    "order": 700
-  },
-  "usage-log": {
-    "enabled": true,
-    "order": 650
-  },
-  "rate-limit-log": {
-    "enabled": true,
-    "order": 660
-  }
+  "bootstrap-defense": { "enabled": true, "order": 45 },
+  "ttl-tier-detect": { "enabled": true, "order": 75 },
+  "fingerprint-strip": { "enabled": true, "order": 100 },
+  "image-strip": { "enabled": true, "order": 150 },
+  "sort-stabilization": { "enabled": true, "order": 200 },
+  "fresh-session-sort": { "enabled": true, "order": 250 },
+  "identity-normalization": { "enabled": true, "order": 300 },
+  "smoosh-split": { "enabled": true, "order": 320 },
+  "content-strip": { "enabled": true, "order": 330 },
+  "tool-input-normalize": { "enabled": true, "order": 340 },
+  "microcompact-stability": { "enabled": true, "order": 350 },
+  "thinking-display": { "enabled": true, "order": 360 },
+  "cache-control-normalize": { "enabled": true, "order": 400 },
+  "messages-cache-breakpoint": { "enabled": true, "order": 410 },
+  "ttl-management": { "enabled": true, "order": 500 },
+  "cache-telemetry": { "enabled": true, "order": 600 },
+  "overage-warning": { "enabled": true, "order": 610 },
+  "request-log": { "enabled": false, "order": 700 }
 }

package/proxy/helpers.mjs

@@ -0,0 +1,30 @@
+// Escape a value for safe rendering into a systemd `Environment=KEY=VALUE` line.
+//
+// Per systemd.exec(5) Environment= and systemd.unit(5) Specifier Expansion:
+//   - Literal `%` is the specifier-expansion marker; to embed one in a value
+//     the unit file must write `%%`. Without escaping, `a%20b` is parsed as
+//     a failed `%20` specifier expansion, systemd logs "Invalid slot" and
+//     silently drops the variable (empirically reproduced 2026-06-07).
+//   - Backslash is a C-string escape inside quoted strings AND inside the
+//     Environment= value parser; `\b` becomes byte 0x08 (backspace), `\n`
+//     becomes LF, etc. To embed a literal `\` the unit must write `\\`.
+//   - `"` requires `\"` (after the backslash escape rule above).
+//   - Whitespace requires the whole value to be quoted (`"..."`).
+//
+// Order matters: escape `%` first (it produces `%%`, neither of which we
+// want to re-escape later), then handle `\` and `"` together inside the
+// quoting branch.
+export const systemdEscape = (v) => {
+  const percentEscaped = v.replace(/%/g, '%%');
+  const needsQuoting = /[\s"\\]/.test(v);
+  if (!needsQuoting) return percentEscaped;
+  return `"${percentEscaped.replace(/[\\"]/g, '\\$&')}"`;
+};
+
+export const xmlEscape = (v) => v.replace(/[&<>'"]/g, c => ({
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  "'": '&apos;',
+  '"': '&quot;'
+})[c]);

package/proxy/pipeline.mjs

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 let registry = [];
+let failedExtensions = []; // [{ file, error, lastAttempt }]
 
 export async function loadExtensions(dir, configPath) {
   let config = {};
@@ -15,6 +16,7 @@ export async function loadExtensions(dir, configPath) {
   const mjsFiles = files.filter((f) => f.endsWith(".mjs")).sort();
 
   const extensions = [];
+  const newlyFailed = [];
   for (const file of mjsFiles) {
     try {
       const mod = await import(pathToFileURL(join(dir, file)).href + "?t=" + Date.now());
@@ -29,12 +31,24 @@ export async function loadExtensions(dir, configPath) {
         extensions.push({ ...ext, order, _file: file });
       }
     } catch (err) {
-      process.stderr.write(`[pipeline] failed to load ${file}: ${err.message}\n`);
+      // Load-bearing observability: this branch is the only signal that the
+      // proxy is running with a degraded extension graph. See #196: a Node
+      // ESM cache stale-import race silently broke thinking-block-sanitize
+      // v2 for 17 hours post-merge before AITL grepped the journal. The
+      // [CRITICAL] prefix is harder to miss than the prior [pipeline] one,
+      // and the explicit "restart proxy to recover" hint tells the operator
+      // what to do — the underlying Node ESM cache problem can't be fixed
+      // in-process (you can't evict cached transitive imports), so a full
+      // process restart is the only path to recover the extension graph.
+      const msg = `[CRITICAL] extension load failed: ${file}: ${err.message} — restart the proxy via your supervisor to recover (in-process reload cannot fix stale ESM cache; see #196)\n`;
+      process.stderr.write(msg);
+      newlyFailed.push({ file, error: String(err.message || err), lastAttempt: new Date().toISOString() });
     }
   }
 
   extensions.sort((a, b) => a.order - b.order);
   registry = extensions;
+  failedExtensions = newlyFailed;
   return extensions;
 }
 
@@ -46,6 +60,13 @@ export function snapshotRegistry() {
   return [...registry];
 }
 
+// Exposed for /health and any operator-facing tool that wants to surface
+// extension-load failures. Returns a fresh array per call so callers can't
+// mutate internal state.
+export function getFailedExtensions() {
+  return failedExtensions.map((f) => ({ ...f }));
+}
+
 // Route scoping: extensions default to messages-only so that adding a new
 // route (e.g. /api/claude_cli/bootstrap) doesn't drag every existing
 // message-mutating extension onto it — most throw on a null body because