claude-code-cache-fix 1.6.4 → 1.7.0

package/README.md

@@ -303,6 +303,51 @@ Snapshots are saved to `~/.claude/cache-fix-snapshots/` and diff reports are gen
 
 - **[@ArkNill/claude-code-hidden-problem-analysis](https://github.com/ArkNill/claude-code-hidden-problem-analysis)** — Systematic proxy-based analysis of 7 bugs including microcompact, budget enforcement, false rate limiter, and extended thinking quota impact. The monitoring features in v1.1.0 are informed by this research.
 - **[@Renvect/X-Ray-Claude-Code-Interceptor](https://github.com/Renvect/X-Ray-Claude-Code-Interceptor)** — Diagnostic HTTPS proxy with real-time dashboard, system prompt section diffing, per-tool stripping thresholds, and multi-stream JSONL logging. Works with any Claude client that supports `ANTHROPIC_BASE_URL` (CLI, VS Code extension, desktop app), complementing this package's CLI-only `NODE_OPTIONS` approach.
+- **[@fgrosswig/claude-usage-dashboard](https://github.com/fgrosswig/claude-usage-dashboard)** — Self-hosted forensic dashboard with SSE live monitoring, multi-host aggregation, cache-health scoring, and forced-restart/compaction detection. Reads from Claude Code's native session JSONL files and optionally from an HTTP proxy NDJSON stream. v1.4.0 documented the forced-session-restart mechanism at quota-cap boundaries (~490K tokens per event) and the 78–91% cache-wipe pattern at compaction events. Complementary to our interceptor's in-process vantage point. See [Works with @fgrosswig's dashboard](#works-with-fgrosswigs-dashboard) below for the interop pattern.
+
+## Works with @fgrosswig's dashboard
+
+This interceptor and [@fgrosswig](https://github.com/fgrosswig)'s
+[claude-usage-dashboard](https://github.com/fgrosswig/claude-usage-dashboard)
+solve strongly complementary problems. The interceptor captures per-call API
+data from inside the Node.js process — cache metrics, quota state, TTL tier,
+rewrites applied. The dashboard provides the visualization layer — historical
+trending, per-day charts, multi-host aggregation, cache-health scoring.
+
+Running both gives you the best of both tools, and the integration is a
+one-liner thanks to the dashboard's tolerant NDJSON ingest and our new
+`usage-to-dashboard-ndjson` translator.
+
+### Quick setup
+
+```bash
+# Install both tools
+npm install -g claude-code-cache-fix
+# (follow fgrosswig's dashboard install: https://github.com/fgrosswig/claude-usage-dashboard)
+
+# One-shot translation (reads ~/.claude/usage.jsonl, writes to
+# ~/.claude/anthropic-proxy-logs/proxy-YYYY-MM-DD.ndjson, which his
+# dashboard already watches)
+node $(npm root -g)/claude-code-cache-fix/tools/usage-to-dashboard-ndjson.mjs
+
+# Or keep it live-updating as the interceptor logs new calls
+node $(npm root -g)/claude-code-cache-fix/tools/usage-to-dashboard-ndjson.mjs --follow &
+```
+
+No configuration required on the dashboard side — fgrosswig's
+`collectProxyNdjsonFiles()` auto-discovers files in
+`~/.claude/anthropic-proxy-logs/` (or `$ANTHROPIC_PROXY_LOG_DIR`), and our
+translator writes to exactly that path with the expected `proxy-YYYY-MM-DD.ndjson`
+filename convention. The dashboard's tolerant ingestion layer ignores unknown
+fields, so interceptor-specific extras (`ttl_tier`, `ephemeral_1h_input_tokens`,
+`ephemeral_5m_input_tokens`, `peak_hour`, quota state) pass through cleanly
+and remain available to downstream consumers that know to read them.
+
+The `cost_factor` metric in `tools/cost-report.mjs` also comes from
+fgrosswig's methodology — the `(input + output + cache_read + cache_creation) / output`
+ratio that gives a single-number measure of how much context is being paid
+per useful output token. A rising cost factor across a long session is the
+measurable signature of cache-efficiency degradation.
 
 ## Used in production
 
@@ -316,6 +361,7 @@ Snapshots are saved to `~/.claude/cache-fix-snapshots/` and diff reports are gen
 - **[@cnighswonger](https://github.com/cnighswonger)** — Fingerprint stabilization, tool ordering fix, image stripping, monitoring features, overage TTL downgrade discovery, package maintainer
 - **[@ArkNill](https://github.com/ArkNill)** — Microcompact mechanism analysis, GrowthBook flag documentation, false rate limiter identification
 - **[@Renvect](https://github.com/Renvect)** — Image duplication discovery, cross-project directory contamination analysis
+- **[@fgrosswig](https://github.com/fgrosswig)** — [claude-usage-dashboard](https://github.com/fgrosswig/claude-usage-dashboard) forensic methodology: cost-factor overhead ratio metric, `anthropic-*` header capture pattern, proxy NDJSON schema that informed our dashboard interop layer
 
 If you contributed to the community effort on these issues and aren't listed here, please open an issue or PR — we want to credit everyone properly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
   "type": "module",
   "exports": "./preload.mjs",

package/preload.mjs

@@ -1009,6 +1009,30 @@ globalThis.fetch = async function (url, options) {
         monitorContextDegradation(payload.messages);
       }
 
+      // Diagnostic: dump full tools array (names, descriptions, schemas, sizes) to a file
+      // when CACHE_FIX_DUMP_TOOLS=<path> is set. Useful for per-version tool-schema drift
+      // analysis and for understanding which tools contribute prefix bloat. First used
+      // during the 2026-04-11 cross-version regression investigation.
+      if (process.env.CACHE_FIX_DUMP_TOOLS && payload.tools) {
+        try {
+          const dumpPath = process.env.CACHE_FIX_DUMP_TOOLS;
+          const dump = {
+            timestamp: new Date().toISOString(),
+            tool_count: payload.tools.length,
+            tools: payload.tools.map(t => ({
+              name: t.name,
+              description: t.description || "",
+              desc_chars: (t.description || "").length,
+              schema_chars: JSON.stringify(t.input_schema || {}).length,
+              total_chars: JSON.stringify(t).length,
+            })),
+            system_chars: JSON.stringify(payload.system || "").length,
+            total_tools_chars: JSON.stringify(payload.tools).length,
+          };
+          writeFileSync(dumpPath, JSON.stringify(dump, null, 2));
+        } catch (e) { debugLog("DUMP ERROR:", e?.message); }
+      }
+
       // Prompt size measurement — log system prompt, tools, and injected block sizes
       if (DEBUG && payload.system && payload.tools && payload.messages) {
         const sysChars = JSON.stringify(payload.system).length;
@@ -1061,6 +1085,25 @@ globalThis.fetch = async function (url, options) {
       const status = response.headers.get("anthropic-ratelimit-unified-status");
       const overage = response.headers.get("anthropic-ratelimit-unified-overage-status");
 
+      // Capture ALL anthropic-* and request-id/cf-ray response headers.
+      // Pattern borrowed from @fgrosswig's claude-usage-dashboard proxy:
+      //   https://github.com/fgrosswig/claude-usage-dashboard
+      // Widening beyond the specific unified-ratelimit headers above future-proofs
+      // us against Anthropic adding new headers (e.g. experimental rollout flags,
+      // region hints, new quota dimensions) without needing code changes.
+      const allAnthropicHeaders = {};
+      for (const [name, value] of response.headers.entries()) {
+        const lower = name.toLowerCase();
+        if (
+          lower.startsWith("anthropic-") ||
+          lower === "request-id" ||
+          lower === "x-request-id" ||
+          lower === "cf-ray"
+        ) {
+          allAnthropicHeaders[lower] = value;
+        }
+      }
+
       if (h5 || h7d) {
         const quotaFile = join(homedir(), ".claude", "quota-status.json");
         let quota = {};
@@ -1070,6 +1113,7 @@ globalThis.fetch = async function (url, options) {
         quota.seven_day = h7d ? { utilization: parseFloat(h7d), pct: Math.round(parseFloat(h7d) * 100), resets_at: reset7d ? parseInt(reset7d) : null } : quota.seven_day;
         quota.status = status || null;
         quota.overage_status = overage || null;
+        quota.all_headers = allAnthropicHeaders;
 
         // Peak hour detection — Anthropic applies higher quota drain rate during
         // weekday peak hours: 13:00–19:00 UTC (Mon–Fri).

package/tools/cost-report.mjs

@@ -484,6 +484,12 @@ function printJsonReport(results, summary, ratesData, adminSummary) {
       total_cost: summary.totalCost,
       avg_cost_per_call: summary.totalCost / summary.calls,
       tokens: summary.totals,
+      cost_factor: (function () {
+        // fgrosswig-style overhead ratio: gross tokens / output tokens
+        const gross = summary.totals.input + summary.totals.output +
+                      summary.totals.cache_read + summary.totals.cache_1h + summary.totals.cache_5m;
+        return summary.totals.output > 0 ? gross / summary.totals.output : null;
+      })(),
       by_model: summary.byModel,
       degradation: summary.degradedCalls > 0 ? {
         degraded_calls: summary.degradedCalls,
@@ -544,6 +550,15 @@ function printMarkdownReport(results, summary, ratesData, adminSummary) {
   lines.push(`| Total cache write 5m | ${fmt(summary.totals.cache_5m)} |`);
   lines.push(`| **Total cost** | **${fmtCost(summary.totalCost)}** |`);
   lines.push(`| Avg cost per call | ${fmtCost(summary.totalCost / summary.calls)} |`);
+  {
+    // Cost factor: popularized by @fgrosswig's claude-usage-dashboard
+    // (https://github.com/fgrosswig/claude-usage-dashboard)
+    const grossTokens = summary.totals.input + summary.totals.output +
+                        summary.totals.cache_read + summary.totals.cache_1h + summary.totals.cache_5m;
+    if (summary.totals.output > 0) {
+      lines.push(`| Cost factor (tokens/output) | ${(grossTokens / summary.totals.output).toFixed(1)}× |`);
+    }
+  }
   lines.push('');
 
   // By model
@@ -680,6 +695,22 @@ function printTextReport(results, summary, ratesData, adminSummary) {
       }
     }
   }
+
+  // ── Cost factor (overhead ratio) ──
+  // Credit: this metric was popularized by @fgrosswig's claude-usage-dashboard
+  // (https://github.com/fgrosswig/claude-usage-dashboard). It divides total
+  // tokens processed (input + output + cache_read + cache_creation) by useful
+  // output tokens, giving a single-number "how much context am I carrying
+  // per useful word of output" multiplier. Values climb over long sessions
+  // due to resume/compaction cycles; a rising curve is a signal that cache
+  // efficiency is degrading.
+  const totalCacheCreate = summary.totals.cache_1h + summary.totals.cache_5m;
+  const grossTokens = summary.totals.input + summary.totals.output +
+                      summary.totals.cache_read + totalCacheCreate;
+  if (summary.totals.output > 0) {
+    const costFactor = grossTokens / summary.totals.output;
+    console.log(`  Cost factor:           ${costFactor.toFixed(1)}× (tokens/output)`);
+  }
   console.log('');
 
   // ── Degradation ──

package/tools/sim-cost-reconcile.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# sim-cost-reconcile — One-liner wrapper for running cost-report.mjs against
+# a simulation log with admin API cross-reference enabled.
+#
+# Usage:
+#   sim-cost-reconcile <sim-dir-or-log> [extra cost-report.mjs args...]
+#
+# Examples:
+#   sim-cost-reconcile ~/git_repos/kanfei_test/kanfei-nowcast/.test_cache/simulations/realtime_sim_harnett_county_qlcs_2026_20260411_024836
+#   sim-cost-reconcile path/to/simulation.log --format md > report.md
+#
+# Reads admin key from $ANTHROPIC_ADMIN_KEY or ~/.config/anthropic/admin-key.
+# If no admin key is available, runs with telemetry only and warns.
+#
+# NOTE on admin reconciliation: the admin API returns data at 1h-bucket
+# resolution, so if multiple sims (or other API activity) overlap the same
+# hour, the admin total will include all of it. For an accurate multi-sim
+# aggregate, run this on each sim and sum the telemetry totals, then pull
+# the admin total once over the full window.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COST_REPORT="$SCRIPT_DIR/cost-report.mjs"
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $(basename "$0") <sim-dir-or-log> [extra cost-report args...]" >&2
+    exit 1
+fi
+
+TARGET="$1"
+shift
+
+# Resolve a dir to its simulation.log
+if [[ -d "$TARGET" ]]; then
+    LOG="$TARGET/simulation.log"
+    if [[ ! -f "$LOG" ]]; then
+        echo "ERROR: no simulation.log in $TARGET" >&2
+        exit 1
+    fi
+elif [[ -f "$TARGET" ]]; then
+    LOG="$TARGET"
+else
+    echo "ERROR: $TARGET is neither a file nor a directory" >&2
+    exit 1
+fi
+
+# Load admin key
+ADMIN_KEY_FILE="${HOME}/.config/anthropic/admin-key"
+if [[ -n "${ANTHROPIC_ADMIN_KEY:-}" ]]; then
+    KEY="$ANTHROPIC_ADMIN_KEY"
+elif [[ -r "$ADMIN_KEY_FILE" ]]; then
+    KEY="$(cat "$ADMIN_KEY_FILE")"
+else
+    echo "WARNING: no admin key found ($ADMIN_KEY_FILE missing, ANTHROPIC_ADMIN_KEY unset)" >&2
+    echo "         running telemetry-only — pass --admin-key or set env var to enable reconciliation" >&2
+    exec node "$COST_REPORT" --sim-log "$LOG" "$@"
+fi
+
+exec node "$COST_REPORT" --sim-log "$LOG" --admin-key "$KEY" "$@"

package/tools/usage-to-dashboard-ndjson.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * usage-to-dashboard-ndjson — Translate claude-code-cache-fix's usage.jsonl
+ * into the proxy NDJSON format expected by @fgrosswig's claude-usage-dashboard,
+ * and write to the directory his dashboard already watches.
+ *
+ *   https://github.com/fgrosswig/claude-usage-dashboard
+ *
+ * # Why this exists
+ *
+ * Our interceptor and fgrosswig's dashboard are strongly complementary:
+ * the interceptor captures per-call API data from inside the Node.js process
+ * (cache metrics, quota state, request rewrites), while his dashboard
+ * provides visualization, historical trending, and multi-host aggregation.
+ *
+ * Rather than build our own visualization layer, we translate our per-call
+ * usage records into the NDJSON schema his dashboard ingests. A user running
+ * both tools gets the best of both: the interceptor fixes what it can fix
+ * and emits rich per-call data, and the dashboard displays that data
+ * alongside whatever Claude Code's own session JSONLs already capture.
+ *
+ * # What this tool does
+ *
+ * Reads `~/.claude/usage.jsonl` (our interceptor's per-call log) and
+ * translates each entry into a minimal-but-compatible record in the shape
+ * his dashboard expects under `~/.claude/anthropic-proxy-logs/*.ndjson`.
+ * The output file follows the convention `proxy-YYYY-MM-DD.ndjson`, one
+ * file per UTC day, matching the filename pattern his `collectProxyNdjsonFiles()`
+ * helper discovers.
+ *
+ * # Fields emitted
+ *
+ * Mapped from our usage.jsonl to fgrosswig's proxy-core.js shape:
+ *
+ *   {
+ *     "ts_start":  <our timestamp>,
+ *     "ts_end":    <our timestamp>,        // single-point, no duration
+ *     "duration_ms": null,                 // we don't measure this
+ *     "method":    "POST",
+ *     "path":      "/v1/messages",
+ *     "upstream_status": 200,              // implicit from usage presence
+ *     "usage": {
+ *       "input_tokens": <ours>,
+ *       "output_tokens": <ours>,
+ *       "cache_read_input_tokens": <ours>,
+ *       "cache_creation_input_tokens": <ours>
+ *     },
+ *     "cache_read_ratio": <computed>,
+ *     "cache_health":     "healthy" | "affected" | "mixed",
+ *     "request_hints":    { "model": <ours> },
+ *     "response_anthropic_headers": {      // if quota fields available
+ *       "anthropic-ratelimit-unified-5h-utilization": "<ours>",
+ *       "anthropic-ratelimit-unified-7d-utilization": "<ours>"
+ *     },
+ *     "ttl_tier":         <ours, interceptor-specific>,
+ *     "ephemeral_1h_input_tokens": <ours, interceptor-specific>,
+ *     "ephemeral_5m_input_tokens": <ours, interceptor-specific>,
+ *     "source": "claude-code-cache-fix"
+ *   }
+ *
+ * Extra fields beyond fgrosswig's native schema (ttl_tier, ephemeral_*,
+ * source) are added for forward-compatibility — his dashboard ignores
+ * unknown fields per its tolerant-ingest design, and our own tooling
+ * downstream may find them useful when consuming the same NDJSON.
+ *
+ * # Usage
+ *
+ *   # One-shot translation (reads all of usage.jsonl, writes today's file)
+ *   node tools/usage-to-dashboard-ndjson.mjs
+ *
+ *   # Follow mode (tail usage.jsonl, append new records as they arrive)
+ *   node tools/usage-to-dashboard-ndjson.mjs --follow
+ *
+ *   # Custom input/output paths
+ *   node tools/usage-to-dashboard-ndjson.mjs --input /path/to/usage.jsonl --output-dir /path/to/ndjson-dir
+ *
+ *   # Dry-run: print to stdout instead of writing files
+ *   node tools/usage-to-dashboard-ndjson.mjs --stdout
+ *
+ * # Environment
+ *
+ *   ANTHROPIC_PROXY_LOG_DIR  Override output directory (matches fgrosswig's
+ *                            dashboard env var so both tools stay in sync).
+ *
+ * Part of claude-code-cache-fix. MIT licensed.
+ *   https://github.com/cnighswonger/claude-code-cache-fix
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, statSync, watch } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ─── CLI parsing ────────────────────────────────────────────────────────────
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {
+    input: join(homedir(), '.claude', 'usage.jsonl'),
+    outputDir: process.env.ANTHROPIC_PROXY_LOG_DIR || join(homedir(), '.claude', 'anthropic-proxy-logs'),
+    stdout: false,
+    follow: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--input':      opts.input = args[++i]; break;
+      case '--output-dir': opts.outputDir = args[++i]; break;
+      case '--stdout':     opts.stdout = true; break;
+      case '--follow':     opts.follow = true; break;
+      case '-h':
+      case '--help':       opts.help = true; break;
+      default:
+        console.error(`unknown flag: ${args[i]}`);
+        opts.help = true;
+    }
+  }
+
+  return opts;
+}
+
+function printUsage() {
+  console.log(`usage-to-dashboard-ndjson — Translate cache-fix usage.jsonl to fgrosswig dashboard NDJSON.
+
+Usage:
+  node usage-to-dashboard-ndjson.mjs                 One-shot: read all, write today's file
+  node usage-to-dashboard-ndjson.mjs --follow        Tail usage.jsonl, append new records live
+  node usage-to-dashboard-ndjson.mjs --stdout        Print NDJSON to stdout instead of files
+  node usage-to-dashboard-ndjson.mjs --input <path>  Custom input (default: ~/.claude/usage.jsonl)
+  node usage-to-dashboard-ndjson.mjs --output-dir <path>  Custom output dir (default: ~/.claude/anthropic-proxy-logs)
+
+Output files follow the convention: proxy-YYYY-MM-DD.ndjson (one per UTC day).
+
+Environment:
+  ANTHROPIC_PROXY_LOG_DIR  Override output directory (also used by fgrosswig's dashboard).
+
+Credit: this tool writes the NDJSON schema expected by @fgrosswig's
+claude-usage-dashboard (https://github.com/fgrosswig/claude-usage-dashboard).
+Running both tools together gives users per-call data from our interceptor
+plus the visualization layer from his dashboard, with no coordination needed.
+`);
+}
+
+// ─── Record translation ─────────────────────────────────────────────────────
+
+/**
+ * Translate one claude-code-cache-fix usage.jsonl record into a
+ * fgrosswig-dashboard-compatible NDJSON record. Returns null if the
+ * record doesn't have enough fields to be usable.
+ */
+function translateRecord(entry) {
+  if (!entry || !entry.timestamp || !entry.model) return null;
+
+  const inTok = entry.input_tokens || 0;
+  const outTok = entry.output_tokens || 0;
+  const crTok = entry.cache_read_input_tokens || 0;
+  const ccTok = entry.cache_creation_input_tokens || 0;
+
+  // Cache health (fgrosswig's semantic labels)
+  const totalCacheInput = crTok + ccTok;
+  const cacheReadRatio = totalCacheInput > 0 ? crTok / totalCacheInput : null;
+  let cacheHealth = 'na';
+  if (cacheReadRatio != null) {
+    if (cacheReadRatio >= 0.8) cacheHealth = 'healthy';
+    else if (cacheReadRatio < 0.4 && ccTok > 0) cacheHealth = 'affected';
+    else cacheHealth = 'mixed';
+  }
+
+  // Reconstruct a minimal response_anthropic_headers blob from the quota
+  // pct fields we captured. Not byte-identical to what the proxy would see
+  // on the wire, but structurally compatible for the dashboard's consumers.
+  const responseHeaders = {};
+  if (entry.q5h_pct != null) {
+    responseHeaders['anthropic-ratelimit-unified-5h-utilization'] = String(entry.q5h_pct / 100);
+  }
+  if (entry.q7d_pct != null) {
+    responseHeaders['anthropic-ratelimit-unified-7d-utilization'] = String(entry.q7d_pct / 100);
+  }
+
+  const rec = {
+    ts_start: entry.timestamp,
+    ts_end: entry.timestamp,
+    duration_ms: null,
+    method: 'POST',
+    path: '/v1/messages',
+    upstream_status: 200,
+    usage: {
+      input_tokens: inTok,
+      output_tokens: outTok,
+      cache_read_input_tokens: crTok,
+      cache_creation_input_tokens: ccTok,
+    },
+    cache_read_ratio: cacheReadRatio,
+    cache_health: cacheHealth,
+    request_hints: {
+      model: entry.model,
+    },
+    response_anthropic_headers: responseHeaders,
+    // Interceptor-specific extras — fgrosswig's dashboard ignores unknown
+    // fields, so these pass through without breaking ingestion.
+    ttl_tier: entry.ttl_tier || null,
+    ephemeral_1h_input_tokens: entry.ephemeral_1h_input_tokens || 0,
+    ephemeral_5m_input_tokens: entry.ephemeral_5m_input_tokens || 0,
+    peak_hour: entry.peak_hour || false,
+    source: 'claude-code-cache-fix',
+  };
+
+  // Synthesize a stable pseudo-request-id from timestamp + model for dedup
+  // at the dashboard layer. Not a real request ID — just a deterministic key.
+  rec.req_id = 'ccf_' + entry.timestamp.replace(/[^0-9]/g, '') + '_' + entry.model.slice(-6);
+
+  return rec;
+}
+
+// ─── File output ────────────────────────────────────────────────────────────
+
+function dayFileFor(outputDir, isoTimestamp) {
+  // proxy-YYYY-MM-DD.ndjson from UTC date
+  const date = isoTimestamp.slice(0, 10);
+  return join(outputDir, `proxy-${date}.ndjson`);
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function writeRecords(records, outputDir, useStdout) {
+  if (useStdout) {
+    for (const r of records) {
+      process.stdout.write(JSON.stringify(r) + '\n');
+    }
+    return records.length;
+  }
+
+  ensureDir(outputDir);
+
+  // Group by day for efficient appending
+  const byDay = new Map();
+  for (const r of records) {
+    const day = dayFileFor(outputDir, r.ts_start);
+    if (!byDay.has(day)) byDay.set(day, []);
+    byDay.get(day).push(r);
+  }
+
+  for (const [dayFile, dayRecords] of byDay) {
+    const payload = dayRecords.map(r => JSON.stringify(r)).join('\n') + '\n';
+    // Overwrite on one-shot mode — the tool is idempotent within a single
+    // input file, so rewriting today's file from a full replay is safe.
+    writeFileSync(dayFile, payload);
+  }
+
+  return records.length;
+}
+
+// ─── One-shot batch mode ────────────────────────────────────────────────────
+
+function runBatch(opts) {
+  if (!existsSync(opts.input)) {
+    console.error(`ERROR: input file not found: ${opts.input}`);
+    process.exit(1);
+  }
+
+  const raw = readFileSync(opts.input, 'utf8');
+  const lines = raw.split('\n').filter(l => l.trim());
+  const records = [];
+  let skipped = 0;
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      const rec = translateRecord(entry);
+      if (rec) records.push(rec);
+      else skipped++;
+    } catch {
+      skipped++;
+    }
+  }
+
+  const written = writeRecords(records, opts.outputDir, opts.stdout);
+  if (!opts.stdout) {
+    console.error(`usage-to-dashboard-ndjson: wrote ${written} records to ${opts.outputDir} (${skipped} skipped)`);
+  }
+}
+
+// ─── Follow mode ────────────────────────────────────────────────────────────
+
+function runFollow(opts) {
+  if (!existsSync(opts.input)) {
+    console.error(`ERROR: input file not found: ${opts.input}`);
+    process.exit(1);
+  }
+
+  // First, catch up on the existing file (idempotent write)
+  runBatch(opts);
+
+  // Then watch for new entries
+  console.error(`usage-to-dashboard-ndjson: watching ${opts.input} for new records...`);
+  let lastSize = statSync(opts.input).size;
+
+  watch(opts.input, { persistent: true }, () => {
+    let currentSize;
+    try { currentSize = statSync(opts.input).size; } catch { return; }
+    if (currentSize <= lastSize) {
+      // File truncated or unchanged — rewind lastSize
+      if (currentSize < lastSize) lastSize = 0;
+      return;
+    }
+    // Read only the new bytes
+    try {
+      const fd = readFileSync(opts.input, 'utf8');
+      const newContent = fd.slice(lastSize);
+      lastSize = currentSize;
+      const newLines = newContent.split('\n').filter(l => l.trim());
+      const newRecs = [];
+      for (const line of newLines) {
+        try {
+          const entry = JSON.parse(line);
+          const rec = translateRecord(entry);
+          if (rec) newRecs.push(rec);
+        } catch {}
+      }
+      if (newRecs.length > 0) {
+        // Append to today's dayfile per record
+        ensureDir(opts.outputDir);
+        for (const r of newRecs) {
+          const dayFile = dayFileFor(opts.outputDir, r.ts_start);
+          appendFileSync(dayFile, JSON.stringify(r) + '\n');
+        }
+        console.error(`[${new Date().toISOString()}] appended ${newRecs.length} records`);
+      }
+    } catch (err) {
+      console.error(`watch error: ${err.message}`);
+    }
+  });
+
+  // Keep the process alive
+  process.stdin.resume();
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+const opts = parseArgs();
+if (opts.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (opts.follow) {
+  runFollow(opts);
+} else {
+  runBatch(opts);
+}