claude-code-cache-fix 3.1.1 → 3.2.1

package/README.md

@@ -86,6 +86,43 @@ nohup cache-fix-proxy server > /tmp/cache-fix-proxy.log 2>&1 &
 echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:9801' >> ~/.bashrc
 ```
 
+### Docker
+
+A multi-arch (amd64, arm64) container image is published to GitHub Container Registry on every release tag.
+
+```bash
+docker run -d --name cache-fix-proxy \
+  --restart=always \
+  -p 9801:9801 \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+
+# Then in your shell:
+export ANTHROPIC_BASE_URL=http://127.0.0.1:9801
+```
+
+Use `--restart=always` instead of the systemd healthcheck companion — Docker handles auto-recovery natively. Mount nothing; the container is stateless. Override the default port with `-e CACHE_FIX_PROXY_PORT=...`. Override the upstream (e.g. to chain through llm-relay) with `-e CACHE_FIX_PROXY_UPSTREAM=http://host.docker.internal:8080`. The image runs as the unprivileged `node` user (uid 1000) and exposes a `HEALTHCHECK` Docker can use for liveness.
+
+For corporate environments behind an SSL-inspecting proxy, mount your CA bundle and set the env vars:
+
+```bash
+docker run -d --name cache-fix-proxy --restart=always -p 9801:9801 \
+  -e HTTPS_PROXY=http://proxy.corp.example:8080 \
+  -e CACHE_FIX_PROXY_CA_FILE=/etc/ssl/corp-ca.pem \
+  -v /path/to/zscaler-root.pem:/etc/ssl/corp-ca.pem:ro \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+```
+
+Image tags: `latest`, `3`, `3.2`, `3.2.1` (semver-ladder, so `3` always points to the newest 3.x). `latest` always tracks the newest tagged release.
+
+**Linux note:** the chained-upstream `host.docker.internal` example below is automatic on Docker Desktop (macOS / Windows). On plain Linux Docker Engine you usually need `--add-host=host.docker.internal:host-gateway` so the name resolves to the host bridge. Without it, the container's name lookup fails and the proxy can't reach the upstream service running on the host. Example chaining cache-fix proxy through `llm-relay` running on the host:
+
+```bash
+docker run -d --name cache-fix-proxy --restart=always -p 9801:9801 \
+  --add-host=host.docker.internal:host-gateway \
+  -e CACHE_FIX_PROXY_UPSTREAM=http://host.docker.internal:8080 \
+  ghcr.io/cnighswonger/claude-code-cache-fix:latest
+```
+
 ### Health check
 
 ```bash
@@ -297,6 +334,27 @@ export CACHE_FIX_IMAGE_KEEP_LAST=3
 
 Keeps images in the last 3 user messages, replaces older ones with a text placeholder. Only targets `tool_result` blocks — user-pasted images are never touched.
 
+### Oversized-image guard
+
+```bash
+export CACHE_FIX_IMAGE_MAX_DIM=2000
+```
+
+The Anthropic API enforces TWO image-related limits on multi-image requests, and the same error message can fire for either:
+
+> `"An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images."`
+
+Two pressure axes to address them:
+
+| Pressure | Variable | What it does |
+|---|---|---|
+| **Too many images in conversation** | `CACHE_FIX_IMAGE_KEEP_LAST=N` | Strips images from old user messages, keeps only the last N. |
+| **Any single image too large** | `CACHE_FIX_IMAGE_MAX_DIM=2000` | Replaces images exceeding the dimension limit with a forensic placeholder noting the original dimensions. Covers both user-message direct images and tool_result-nested images. |
+
+The two compose: with both set, `KEEP_LAST` runs first (drops the count), then `MAX_DIM` runs on what remains (caps the size of the kept ones). Common triggers for the dimension axis: hi-res manuscript scans, retina screenshots, photos at full resolution.
+
+Pure-JS PNG and JPEG header parsing — no native deps. Other formats (GIF, WebP, AVIF, BMP) pass through unchanged regardless of dimension. Fail-open: images whose dimensions can't be parsed (truncated header, unsupported format) are kept rather than stripped — better to send a request that might error than to strip a valid image we just couldn't measure.
+
 ## System prompt rewrite (preload mode, optional)
 
 The interceptor can rewrite Claude Code's `# Output efficiency` system-prompt section. Disabled by default. Enable with `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`. See [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md) for the three known prompt variants and usage instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.1.1",
+  "version": "3.2.1",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",

package/proxy/extensions/image-strip.mjs

@@ -1,6 +1,13 @@
+import { parseImageDimensions } from "../image-dimensions.mjs";
+
 const KEEP_LAST = parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
+const MAX_DIM = parseInt(process.env.CACHE_FIX_IMAGE_MAX_DIM || "0", 10);
 const PLACEHOLDER = "[image stripped from history — file may still be on disk]";
 
+function oversizedPlaceholder(maxDim, w, h) {
+  return `[image stripped — exceeded ${maxDim}px max dimension (was ${w}x${h}px)]`;
+}
+
 function stripOldToolResultImages(messages, keepLast) {
   if (!keepLast || keepLast <= 0 || !Array.isArray(messages)) {
     return { messages, stats: null };
@@ -58,26 +65,116 @@ function stripOldToolResultImages(messages, keepLast) {
   return { messages: strippedCount > 0 ? result : messages, stats };
 }
 
-export { stripOldToolResultImages, PLACEHOLDER };
+// Strip oversized images from BOTH user-message direct content and
+// tool_result-nested content. Orthogonal to KEEP_LAST: scans every image
+// remaining in the message list and replaces any whose width or height
+// exceeds maxDim. Fail-open: images we can't measure (unsupported format,
+// truncated header) are kept rather than stripped.
+//
+// Stripping by oversize prevents the Anthropic API error:
+//   "An image in the conversation exceeds the dimension limit for many-image
+//    requests (2000px). Start a new session with fewer images."
+function stripOversizedImages(messages, maxDim) {
+  if (!maxDim || maxDim <= 0 || !Array.isArray(messages)) {
+    return { messages, stats: null };
+  }
+
+  let strippedCount = 0;
+  let strippedBytes = 0;
+
+  function maybeStrip(item) {
+    if (!item || item.type !== "image") return item;
+    const src = item.source;
+    if (!src || !src.data || !src.media_type) return item;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) return item; // can't measure → keep
+    if (dims.width <= maxDim && dims.height <= maxDim) return item;
+    strippedCount++;
+    strippedBytes += src.data.length;
+    return { type: "text", text: oversizedPlaceholder(maxDim, dims.width, dims.height) };
+  }
+
+  const result = messages.map((msg) => {
+    if (!Array.isArray(msg.content)) return msg;
+    let mutated = false;
+    const newContent = msg.content.map((block) => {
+      // Direct image block on a user message
+      if (block && block.type === "image") {
+        const replaced = maybeStrip(block);
+        if (replaced !== block) {
+          mutated = true;
+          return replaced;
+        }
+        return block;
+      }
+      // Image nested inside a tool_result.content array
+      if (block && block.type === "tool_result" && Array.isArray(block.content)) {
+        let toolMutated = false;
+        const newToolContent = block.content.map((item) => {
+          const replaced = maybeStrip(item);
+          if (replaced !== item) toolMutated = true;
+          return replaced;
+        });
+        if (toolMutated) {
+          mutated = true;
+          return { ...block, content: newToolContent };
+        }
+      }
+      return block;
+    });
+    return mutated ? { ...msg, content: newContent } : msg;
+  });
+
+  const stats = strippedCount > 0
+    ? { strippedCount, strippedBytes, estimatedTokens: Math.ceil(strippedBytes * 0.125) }
+    : null;
+
+  return { messages: strippedCount > 0 ? result : messages, stats };
+}
+
+export { stripOldToolResultImages, stripOversizedImages, PLACEHOLDER, oversizedPlaceholder };
 
 export default {
   name: "image-strip",
-  description: "Strip base64 images from old tool results to reduce token waste",
+  description:
+    "Strip base64 images from old tool results AND optionally strip oversized images that would trigger Anthropic's many-image dimension limit",
   enabled: false,
   order: 150,
 
   async onRequest(ctx) {
     const keepLast = parseInt(ctx.meta.imageKeepLast ?? KEEP_LAST, 10);
-    if (!keepLast || keepLast <= 0) return;
+    const maxDim = parseInt(ctx.meta.imageMaxDim ?? MAX_DIM, 10);
+    if ((!keepLast || keepLast <= 0) && (!maxDim || maxDim <= 0)) return;
     if (!ctx.body.messages) return;
 
-    const { messages, stats } = stripOldToolResultImages(ctx.body.messages, keepLast);
-    if (stats) {
+    let messages = ctx.body.messages;
+    const logParts = [];
+
+    // Pass 1: existing keep_last behavior. Sets ctx.meta.imageStripStats with
+    // the same shape as before this PR — back-compat preserved.
+    if (keepLast > 0) {
+      const r = stripOldToolResultImages(messages, keepLast);
+      if (r.stats) {
+        messages = r.messages;
+        ctx.meta.imageStripStats = r.stats;
+        logParts.push(`keep_last: ${r.stats.strippedCount} stripped (~${r.stats.estimatedTokens} tokens saved)`);
+      }
+    }
+
+    // Pass 2: new max_dim behavior. Stats land on a new field so consumers
+    // already reading imageStripStats don't see a shape change.
+    if (maxDim > 0) {
+      const r = stripOversizedImages(messages, maxDim);
+      if (r.stats) {
+        messages = r.messages;
+        ctx.meta.imageStripOversizedStats = r.stats;
+        logParts.push(`max_dim: ${r.stats.strippedCount} oversized stripped (~${r.stats.estimatedTokens} tokens saved)`);
+      }
+    }
+
+    if (logParts.length > 0) {
       ctx.body.messages = messages;
-      ctx.meta.imageStripStats = stats;
-      process.stderr.write(
-        `[image-strip] stripped ${stats.strippedCount} images (~${stats.estimatedTokens} tokens saved)\n`
-      );
+      process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
     }
   },
 };

package/proxy/extensions/overage-warning.mjs

@@ -0,0 +1,385 @@
+// overage-warning — emit a one-time warning per Q5h-window threshold
+// crossing when Anthropic's response headers indicate the user is
+// approaching or has crossed the overage threshold.
+//
+// Advisory only. No request mutation. Two outputs:
+//   1. stderr line prefixed `[overage-warning]` for proxy journals/logs
+//   2. structured JSON record appended to `~/.claude/overage-warnings.jsonl`
+//
+// Activation: `enabled: true` in extensions.json (this extension is
+// always loaded), gated at runtime by `CACHE_FIX_OVERAGE_WARNING=1`.
+// Matches the prefix-diff pattern (env-var-only opt-in).
+//
+// See `docs/directives/proxy-overage-cost-warning.md` for the full design.
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+import { WEIGHTED_TOKEN_COST_USD_COARSE } from "../rates.mjs";
+
+// Env-gated runtime flags read on each call. Reading at module load would
+// freeze the values and make per-test isolation impossible. The check is
+// cheap (one process.env lookup per invocation when disabled).
+function isEnabled() {
+  return process.env.CACHE_FIX_OVERAGE_WARNING === "1";
+}
+function isQuiet() {
+  return process.env.CACHE_FIX_OVERAGE_WARNING_QUIET === "1";
+}
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
+
+function debug(msg) {
+  if (isDebug()) process.stderr.write(`[overage-warning] DEBUG: ${msg}\n`);
+}
+
+// --- Module-scope state ---
+//
+// Sliding window of (timestamp, q5h_util, input_tokens, cache_creation_tokens,
+// cache_read_tokens, output_tokens) samples. Used to compute burn rate.
+//
+// Cross-response dedup: per Q5h window (keyed by q5h_resets_at), the set
+// of thresholds we've already warned at. Window expires when q5h_resets_at
+// changes (new window = new dedup state).
+
+const WINDOW_MS = 15 * 60 * 1000;
+const WINDOW_MAX_SAMPLES = 60;
+const WARM_UP_MIN_SAMPLES = 3;
+
+const _window = []; // { t, q5h, input, cache_creation, cache_read, output }
+let _dedupWindowResetsAt = 0;
+let _dedupThresholds = new Set();
+
+function resetState() {
+  _window.length = 0;
+  _dedupWindowResetsAt = 0;
+  _dedupThresholds = new Set();
+}
+
+// --- Pure functions (test seam) ---
+
+export function parseTriggerFromHeaders(headers) {
+  if (!headers || typeof headers !== "object") return { eligible: false };
+  const get = (k) => headers[k] || "";
+  const num = (k) => {
+    const v = get(k);
+    if (!v) return null;
+    const n = parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+  };
+  const intOf = (k) => {
+    const v = get(k);
+    if (!v) return 0;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : 0;
+  };
+
+  const status =
+    get("anthropic-ratelimit-unified-status") ||
+    get("anthropic-ratelimit-unified-5h-status");
+  const surpassed = num("anthropic-ratelimit-unified-7d-surpassed-threshold");
+  const overage_status = get("anthropic-ratelimit-unified-overage-status") || "unknown";
+  const upgrade_paths_raw = get("anthropic-ratelimit-unified-upgrade-paths");
+  const q5h_util = num("anthropic-ratelimit-unified-5h-utilization");
+  const q7d_util = num("anthropic-ratelimit-unified-7d-utilization");
+  const q5h_resets_at = intOf("anthropic-ratelimit-unified-5h-reset");
+
+  // Trigger gates: status is allowed_warning or throttled, surpassed-threshold
+  // header is present and non-empty.
+  const isWarn = status === "allowed_warning" || status === "throttled";
+  if (!isWarn) return { eligible: false };
+  if (surpassed === null) return { eligible: false };
+
+  const upgrade_paths = upgrade_paths_raw
+    ? upgrade_paths_raw.split(",").map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  return {
+    eligible: true,
+    trigger: {
+      status,
+      surpassed_threshold: surpassed,
+      overage_status,
+      upgrade_paths,
+    },
+    snapshot: {
+      q5h_pct: q5h_util !== null ? Math.round(q5h_util * 100) : null,
+      q7d_pct: q7d_util !== null ? Math.round(q7d_util * 100) : null,
+      q5h_resets_at,
+    },
+    raw: {
+      q5h_util,
+      q5h_resets_at,
+    },
+  };
+}
+
+export function dedupKey(threshold, q5h_resets_at) {
+  return `${threshold}@${q5h_resets_at}`;
+}
+
+// Compute burn-rate projection from samples. Returns:
+//   { min_to_100, tokens_per_min, cost_per_hr_usd_coarse, window_samples,
+//     window_minutes }
+// All projection fields are `null` when fewer than WARM_UP_MIN_SAMPLES
+// samples exist OR utilization is non-increasing across the window.
+export function computeProjection(samples, now = Date.now()) {
+  // Drop expired samples (caller may have already done this; defensive).
+  const fresh = samples.filter((s) => now - s.t <= WINDOW_MS);
+
+  if (fresh.length < WARM_UP_MIN_SAMPLES) {
+    return {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: fresh.length,
+      window_minutes: 0,
+    };
+  }
+
+  const oldest = fresh[0];
+  const newest = fresh[fresh.length - 1];
+  const windowMin = (newest.t - oldest.t) / 60_000;
+
+  if (windowMin <= 0) {
+    return {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: fresh.length,
+      window_minutes: 0,
+    };
+  }
+
+  const deltaUtil = newest.q5h - oldest.q5h;
+  const utilPerMin = deltaUtil / windowMin;
+
+  let min_to_100 = null;
+  if (utilPerMin > 0) {
+    min_to_100 = Math.max(0, Math.round((1 - newest.q5h) / utilPerMin));
+  }
+
+  // Sum of all relevant tokens across the window. Each sample carries the
+  // per-call token deltas as pushed by recordSample (caller responsibility).
+  const totalTokens = fresh.reduce(
+    (acc, s) =>
+      acc + (s.input || 0) + (s.cache_creation || 0) + (s.cache_read || 0) + (s.output || 0),
+    0,
+  );
+  const tokens_per_min = totalTokens / windowMin;
+  const cost_per_hr_usd_coarse =
+    utilPerMin > 0
+      ? +(tokens_per_min * 60 * WEIGHTED_TOKEN_COST_USD_COARSE).toFixed(2)
+      : null;
+
+  return {
+    min_to_100,
+    tokens_per_min: Math.round(tokens_per_min),
+    cost_per_hr_usd_coarse,
+    window_samples: fresh.length,
+    window_minutes: +windowMin.toFixed(1),
+  };
+}
+
+export function formatStderrLine({ ts, trigger, snapshot, projection }) {
+  const upgrade = trigger.upgrade_paths.length
+    ? trigger.upgrade_paths.join(", ")
+    : "(none)";
+  const head = `[overage-warning] ${ts} Q5h=${snapshot.q5h_pct}% Q7d=${snapshot.q7d_pct}% (surpassed ${trigger.surpassed_threshold})`;
+  if (projection && projection.min_to_100 !== null && projection.cost_per_hr_usd_coarse !== null) {
+    return `${head} — projected 100% in ~${projection.min_to_100} min, estimated continued burn ≈ $${projection.cost_per_hr_usd_coarse.toFixed(2)}/hr at API rates (coarse). Upgrade paths: ${upgrade}.`;
+  }
+  return `${head} — projection unavailable (warming up). Upgrade paths: ${upgrade}.`;
+}
+
+export function formatJsonlRecord({ ts, trigger, snapshot, projection }) {
+  return {
+    ts,
+    trigger: {
+      status: trigger.status,
+      surpassed_threshold: trigger.surpassed_threshold,
+      overage_status: trigger.overage_status,
+      upgrade_paths: trigger.upgrade_paths,
+    },
+    snapshot: {
+      q5h_pct: snapshot.q5h_pct,
+      q7d_pct: snapshot.q7d_pct,
+      q5h_resets_at: snapshot.q5h_resets_at,
+    },
+    projection: projection || {
+      min_to_100: null,
+      tokens_per_min: null,
+      cost_per_hr_usd_coarse: null,
+      window_samples: 0,
+      window_minutes: 0,
+    },
+  };
+}
+
+// --- Window management ---
+
+export function recordSample(state, sample) {
+  state.window.push(sample);
+  const cutoff = sample.t - WINDOW_MS;
+  while (state.window.length && state.window[0].t < cutoff) state.window.shift();
+  while (state.window.length > WINDOW_MAX_SAMPLES) state.window.shift();
+}
+
+// --- Dedup helpers operating on module state ---
+
+function checkAndMarkDedup(threshold, q5h_resets_at) {
+  // New Q5h window resets the dedup set.
+  if (q5h_resets_at !== _dedupWindowResetsAt) {
+    _dedupWindowResetsAt = q5h_resets_at;
+    _dedupThresholds = new Set();
+  }
+  const key = dedupKey(threshold, q5h_resets_at);
+  if (_dedupThresholds.has(key)) return false;
+  _dedupThresholds.add(key);
+  return true;
+}
+
+// --- I/O ---
+
+async function appendJsonl(record, dir) {
+  const outDir = dir || (process.env.CACHE_FIX_OVERAGE_WARNING_DIR || join(homedir(), ".claude"));
+  const outPath = join(outDir, "overage-warnings.jsonl");
+  await mkdir(outDir, { recursive: true });
+  await appendFile(outPath, JSON.stringify(record) + "\n");
+}
+
+// Test helper: write a record using a caller-supplied directory. Bypasses
+// env-var lookup so tests do not race on a shared env. Pure side effect.
+export async function writeRecord(record, dir) {
+  await appendJsonl(record, dir);
+}
+
+// Test helper: drain in-memory state. For deterministic tests.
+export function _resetForTest() {
+  resetState();
+}
+
+// --- Extension contract ---
+
+export default {
+  name: "overage-warning",
+  description:
+    "Emit one-time warning per Q5h-window threshold crossing when overage headers indicate trouble",
+  enabled: true,
+  order: 610,
+
+  async onResponseStart(ctx) {
+    if (!isEnabled()) return;
+    if (!ctx || !ctx.headers) return;
+
+    try {
+      ctx.meta = ctx.meta || {};
+
+      // Always capture quota state if the headers carry it, regardless of
+      // whether THIS response's status crosses a warning threshold. Future
+      // responses need warm samples to project from.
+      const q5hRaw = ctx.headers["anthropic-ratelimit-unified-5h-utilization"];
+      const q5hUtil = q5hRaw ? parseFloat(q5hRaw) : null;
+      if (q5hUtil !== null && Number.isFinite(q5hUtil)) {
+        ctx.meta._overageQuota = { q5h_util: q5hUtil };
+      }
+
+      // Trigger eligibility latch — only set when this response is the one
+      // that crossed a threshold. Keeps emission gate separate from sampling.
+      const result = parseTriggerFromHeaders(ctx.headers);
+      if (!result.eligible) return;
+      ctx.meta._overageWarning = {
+        eligible: true,
+        emitted: false,
+        trigger: result.trigger,
+        snapshot: result.snapshot,
+        raw: result.raw,
+      };
+    } catch (err) {
+      debug(`onResponseStart unexpected: ${err?.message ?? err}`);
+    }
+  },
+
+  async onStreamEvent(ctx) {
+    if (!isEnabled()) return;
+    if (!ctx || !ctx.event) return;
+
+    try {
+      // Sample collection — happens on every response that has a quota
+      // reading, regardless of whether this response is the one that emits.
+      if (ctx.event.type === "message_start" && ctx.event.message?.usage) {
+        const u = ctx.event.message.usage;
+        const q5hUtil = ctx.meta?._overageQuota?.q5h_util;
+        if (q5hUtil !== undefined && q5hUtil !== null) {
+          const sample = {
+            t: Date.now(),
+            q5h: q5hUtil,
+            input: u.input_tokens || 0,
+            cache_creation: u.cache_creation_input_tokens || 0,
+            cache_read: u.cache_read_input_tokens || 0,
+            output: 0,
+          };
+          recordSample({ window: _window }, sample);
+          // Hand the response its own sample reference. message_delta updates
+          // THIS sample only — never the window's last sample, which could
+          // belong to a different response under interleaving.
+          ctx.meta._overageSample = sample;
+        }
+      }
+
+      if (ctx.event.type === "message_delta") {
+        // Update THIS response's sample with output tokens. The sample
+        // reference is response-local (set by message_start), so a response
+        // that never sampled cannot leak output tokens into another response.
+        const ownSample = ctx.meta?._overageSample;
+        if (ownSample && ctx.event.usage?.output_tokens) {
+          ownSample.output += ctx.event.usage.output_tokens;
+        }
+
+        // Emission gate.
+        const w = ctx.meta?._overageWarning;
+        if (!w || !w.eligible || w.emitted) return;
+
+        const allowed = checkAndMarkDedup(
+          w.trigger.surpassed_threshold,
+          w.snapshot.q5h_resets_at,
+        );
+        if (!allowed) {
+          w.emitted = true;
+          return;
+        }
+
+        const ts = new Date().toISOString();
+        const projection = computeProjection(_window, Date.now());
+        const projectionForOutput =
+          projection.window_samples >= WARM_UP_MIN_SAMPLES &&
+          projection.min_to_100 !== null
+            ? projection
+            : null;
+
+        const record = formatJsonlRecord({
+          ts,
+          trigger: w.trigger,
+          snapshot: w.snapshot,
+          projection: projectionForOutput || projection,
+        });
+
+        if (!isQuiet()) {
+          process.stderr.write(formatStderrLine({
+            ts,
+            trigger: w.trigger,
+            snapshot: w.snapshot,
+            projection: projectionForOutput,
+          }) + "\n");
+        }
+
+        await appendJsonl(record);
+        w.emitted = true;
+      }
+    } catch (err) {
+      debug(`onStreamEvent unexpected: ${err?.message ?? err}`);
+    }
+  },
+};