@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/metrics.mjs

@@ -0,0 +1,268 @@
+/**
+ * src/server/metrics.mjs
+ *
+ * v4.7.0 — Tiny Prometheus-style metrics registry.
+ *
+ * Implements the three primitive metric types we actually use:
+ *   - counter(name, help)        → { inc(labels) }
+ *   - gauge(name, help)          → { set(value, labels) }
+ *   - histogram(name, help, opts) → { observe(value, labels) }
+ *
+ * Storage is in-process: counters/gauges/histograms are kept in Maps
+ * keyed by metric name → label-set signature → values. Labels are
+ * JSON-stringified to produce a stable key (sorted-keys would be
+ * nicer but JSON.stringify of a literal object preserves insertion
+ * order, which is good enough for our use — every caller writes the
+ * same label shape for the same metric).
+ *
+ * `render()` returns the Prometheus text exposition format
+ * (Content-Type: text/plain; version=0.0.4) so it can be scraped by
+ * Prometheus or read by humans. The output includes the `# HELP` and
+ * `# TYPE` headers for every metric.
+ *
+ * `reset()` clears the registry — only intended for tests.
+ */
+
+const counters = new Map();
+const gauges = new Map();
+const histograms = new Map();
+
+// Default Prometheus-style histogram buckets in seconds (suitable for
+// HTTP latency). Override per-metric via opts.buckets.
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+function labelsKey(labels) {
+  if (!labels || typeof labels !== 'object') return '{}';
+  const keys = Object.keys(labels);
+  if (keys.length === 0) return '{}';
+  const ordered = {};
+  for (const k of keys.sort()) ordered[k] = labels[k];
+  return JSON.stringify(ordered);
+}
+
+function labelsToString(labels) {
+  if (!labels || typeof labels !== 'object') return '';
+  const keys = Object.keys(labels);
+  if (keys.length === 0) return '';
+  return keys
+    .sort()
+    .map((k) => `${k}="${escapeLabelValue(String(labels[k]))}"`)
+    .join(',');
+}
+
+function escapeLabelValue(v) {
+  return v.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}
+
+export function counter(name, help) {
+  if (!name) throw new Error('counter(name, help): name is required');
+  return {
+    inc(labels = {}) {
+      const key = labelsKey(labels);
+      let entry = counters.get(name);
+      if (!entry) {
+        entry = { help: help || '', values: new Map() };
+        counters.set(name, entry);
+      }
+      const v = entry.values.get(key) || { labels, value: 0 };
+      v.value += 1;
+      entry.values.set(key, v);
+    },
+  };
+}
+
+export function gauge(name, help) {
+  if (!name) throw new Error('gauge(name, help): name is required');
+  return {
+    set(value, labels = {}) {
+      const key = labelsKey(labels);
+      let entry = gauges.get(name);
+      if (!entry) {
+        entry = { help: help || '', values: new Map() };
+        gauges.set(name, entry);
+      }
+      entry.values.set(key, { labels, value: Number(value) });
+    },
+  };
+}
+
+export function histogram(name, help, opts = {}) {
+  if (!name) throw new Error('histogram(name, help, opts): name is required');
+  const buckets = Array.isArray(opts.buckets) && opts.buckets.length > 0
+    ? [...opts.buckets].sort((a, b) => a - b)
+    : DEFAULT_BUCKETS;
+  return {
+    observe(value, labels = {}) {
+      const key = labelsKey(labels);
+      let entry = histograms.get(name);
+      if (!entry) {
+        entry = {
+          help: help || '',
+          buckets,
+          values: new Map(),
+        };
+        histograms.set(name, entry);
+      }
+      const v = entry.values.get(key) || {
+        labels,
+        count: 0,
+        sum: 0,
+        bucketCounts: buckets.map(() => 0),
+      };
+      v.count += 1;
+      v.sum += Number(value);
+      for (let i = 0; i < buckets.length; i += 1) {
+        if (Number(value) <= buckets[i]) v.bucketCounts[i] += 1;
+      }
+      entry.values.set(key, v);
+    },
+  };
+}
+
+function renderCounters() {
+  const lines = [];
+  for (const [name, entry] of counters) {
+    lines.push(`# HELP ${name} ${entry.help}`);
+    lines.push(`# TYPE ${name} counter`);
+    for (const v of entry.values.values()) {
+      const labels = labelsToString(v.labels);
+      lines.push(`${name}${labels ? '{' + labels + '}' : ''} ${v.value}`);
+    }
+  }
+  return lines;
+}
+
+function renderGauges() {
+  const lines = [];
+  for (const [name, entry] of gauges) {
+    lines.push(`# HELP ${name} ${entry.help}`);
+    lines.push(`# TYPE ${name} gauge`);
+    for (const v of entry.values.values()) {
+      const labels = labelsToString(v.labels);
+      lines.push(`${name}${labels ? '{' + labels + '}' : ''} ${v.value}`);
+    }
+  }
+  return lines;
+}
+
+function renderHistograms() {
+  const lines = [];
+  for (const [name, entry] of histograms) {
+    lines.push(`# HELP ${name} ${entry.help}`);
+    lines.push(`# TYPE ${name} histogram`);
+    for (const v of entry.values.values()) {
+      const baseLabels = labelsToString(v.labels);
+      for (let i = 0; i < entry.buckets.length; i += 1) {
+        const le = entry.buckets[i];
+        const bucketLabels = baseLabels
+          ? `${baseLabels},le="${le}"`
+          : `le="${le}"`;
+        lines.push(`${name}_bucket{${bucketLabels}} ${v.bucketCounts[i]}`);
+      }
+      const infLabels = baseLabels ? `${baseLabels},le="+Inf"` : 'le="+Inf"';
+      lines.push(`${name}_bucket{${infLabels}} ${v.count}`);
+      const sumLabels = baseLabels;
+      lines.push(
+        `${name}_sum${sumLabels ? '{' + sumLabels + '}' : ''} ${v.sum}`,
+      );
+      lines.push(
+        `${name}_count${sumLabels ? '{' + sumLabels + '}' : ''} ${v.count}`,
+      );
+    }
+  }
+  return lines;
+}
+
+export function render() {
+  const parts = [
+    ...renderCounters(),
+    ...renderGauges(),
+    ...renderHistograms(),
+  ];
+  return parts.length === 0 ? '' : `${parts.join('\n')}\n`;
+}
+
+/**
+ * Reset every metric. Intended for tests — never call this from a
+ * long-running server.
+ */
+export function reset() {
+  counters.clear();
+  gauges.clear();
+  histograms.clear();
+}
+
+// ─── v5.1.0 ────────────────────────────────────────────────────────────────
+// Trace → metrics correlation helpers.
+//
+// The OTEL exporter ships spans to a collector; the Prometheus
+// exporter ships counters from this in-process registry. To answer
+// "how many `chat.send` spans landed in the last hour?" without
+// leaving the dashboard, route handlers call `recordTrace(name,
+// attributes)` from inside their `withSpan` wrapper. The Map keeps a
+// bounded per-(name, attribute-set) count so a single high-cardinality
+// label (e.g. `chat.session_id`) does not blow up memory.
+//
+// `traceCountByName` is intentionally exported read-only — tests
+// import it to assert the helper was called with the right key, but
+// production code should always go through `recordTrace` to keep
+// the key derivation in one place.
+//
+//─── v5.1.0 ends ───────────────────────────────────────────────────────────
+
+/**
+ * Bounded counter of recorded trace samples, keyed by
+ * `${name}:${JSON.stringify(attributes)}`. Routes populate this
+ * from inside their `withSpan` callback so the dashboard can answer
+ * "how often did span X fire with attribute set Y" without leaving
+ * the process.
+ *
+ * The Map is intentionally an exported `let`-equivalent: tests
+ * reset it via {@link resetTraceCounts}; production code never
+ * mutates the Map directly.
+ *
+ * @type {Map<string, number>}
+ */
+export const traceCountByName = new Map();
+
+/**
+ * Increment the trace counter for `(name, attributes)`.
+ *
+ * The composite key is `${name}:${jsonString}` so two spans named
+ * `chat.send` with different `chat.session_id` attributes are
+ * tracked separately. Undefined/null/empty-string attribute values
+ * are dropped from the key for stability (avoids the empty-string vs
+ * undefined distinction polluting counts). Keys are alphabetised
+ * before serialisation so `{a:1,b:2}` and `{b:2,a:1}` collide on
+ * the same bucket — `JSON.stringify` alone would not give that
+ * guarantee because it preserves insertion order.
+ *
+ * @param {string} name
+ * @param {Record<string, string|number|boolean|undefined|null>} [attributes]
+ * @returns {number} the new total for that key
+ */
+export function recordTrace(name, attributes = {}) {
+  if (!name) return 0;
+  const keys = [];
+  if (attributes && typeof attributes === 'object') {
+    for (const k of Object.keys(attributes)) {
+      const v = attributes[k];
+      if (v === undefined || v === null || v === '') continue;
+      keys.push(k);
+    }
+  }
+  keys.sort();
+  const cleanAttrs = {};
+  for (const k of keys) cleanAttrs[k] = attributes[k];
+  const key = `${name}:${JSON.stringify(cleanAttrs)}`;
+  const next = (traceCountByName.get(key) || 0) + 1;
+  traceCountByName.set(key, next);
+  return next;
+}
+
+/**
+ * Clear every recorded-trace counter. Intended for tests.
+ */
+export function resetTraceCounts() {
+  traceCountByName.clear();
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/minimax-usage-store.mjs

@@ -0,0 +1,372 @@
+/**
+ * src/server/minimax-usage-store.mjs
+ *
+ * JSONL append-only usage log at ~/.local/share/bizar/usage.jsonl.
+ *
+ * Records every MiniMax API call (chatCompletion, fetchRemains) so that:
+ *   - The Usage view can show per-model/per-key analytics over 24h/7d/30d
+ *   - Agents can read their own rolling usage totals via getUsageLimitsForAgent()
+ *     to avoid burning through quota mid-session
+ *   - Approximate USD cost estimates can be surfaced
+ *
+ * Record shape:
+ * {
+ *   ts: 1234567890,                    // unix ms
+ *   providerId: "minimax",
+ *   modelId: "MiniMax-M3",
+ *   endpoint: "chat" | "remains" | "test",
+ *   requestId: "msg_abc",
+ *   promptTokens: 100,
+ *   completionTokens: 200,
+ *   totalTokens: 300,
+ *   cachedTokens: 0,
+ *   reasoningTokens: 50,
+ *   latencyMs: 1234,
+ *   finishReason: "stop",
+ *   error: null | {code: "...", message: "..."},
+ *   keyEnvVar: "BIZAR_MINIMAX_KEY",   // which env var / key slot was used
+ *   isBackup: false,
+ *   cached: false                      // true = returned from cache; NOT counted in cost
+ * }
+ *
+ * Exports:
+ *   recordUsage(record)            — append JSON line
+ *   queryUsage({range, from, to, providerId, modelId})
+ *   getUsageSummary(providerId)   — last-5-min rolling totals
+ *   getUsageLimitsForAgent(providerId)  — agent-awareness compact summary
+ *   pruneUsage({olderThanMs})     — remove old records
+ *   __resetStoreForTests()        — wipe the JSONL (tests only)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ─── Price map (USD per 1M tokens) ────────────────────────────────────────
+
+/** @type {Record<string, {in: number, out: number}>} */
+export const PRICE_PER_MTOK = {
+  'minimax/MiniMax-M3':             { in: 1.00, out: 3.00 },
+  'minimax/MiniMax-M2.7':           { in: 0.86, out: 2.59 },
+  'minimax/MiniMax-M2.7-highspeed':{ in: 1.20, out: 3.60 },
+  'minimax/MiniMax-M2.5':           { in: 0.59, out: 1.77 },
+  'minimax/MiniMax-M2.5-highspeed':{ in: 0.86, out: 2.59 },
+  'minimax/MiniMax-M2.1':           { in: 0.40, out: 1.20 },
+  'minimax/MiniMax-M2.1-highspeed': { in: 0.58, out: 1.74 },
+  'minimax/MiniMax-M2':             { in: 0.20, out: 0.60 },
+};
+
+// ─── Store path ─────────────────────────────────────────────────────────────
+
+// Allow test override without patching process.env.HOME (which can be racy with
+// ESM module-level evaluation order in the Node test runner).
+const STORE_HOME = process.env.BIZAR_STORE_HOME
+  ? process.env.BIZAR_STORE_HOME
+  : join(homedir(), '.local', 'share', 'bizar');
+const STORE_DIR  = STORE_HOME;
+const STORE_FILE = join(STORE_DIR, 'usage.jsonl');
+
+function ensureStoreDir() {
+  // mode 0o700 — Node.js v24.16.0 has a bug where recursive+mode:0o600 fails with
+  // EACCES in /tmp temp dirs even with umask 0o022; 0o700 is fine here.
+  try { mkdirSync(STORE_DIR, { recursive: true, mode: 0o700 }); } catch { /* already exists */ }
+}
+
+// ─── Cost estimation ─────────────────────────────────────────────────────────
+
+/** Approximate USD cost for a usage record. Returns 0 if model is unknown. */
+function estimateCost(record) {
+  if (record.cached || record.error) return 0;
+  const key = `minimax/${record.modelId}`;
+  const price = PRICE_PER_MTOK[key];
+  if (!price) return 0;
+  const p = record.promptTokens ?? 0;
+  const c = record.completionTokens ?? 0;
+  return (p / 1_000_000) * price.in + (c / 1_000_000) * price.out;
+}
+
+// ─── Record ─────────────────────────────────────────────────────────────────
+
+/**
+ * Append a usage record to the JSONL store.
+ * Auto-creates the parent directory on first call.
+ * @param {object} record
+ */
+export function recordUsage(record) {
+  ensureStoreDir();
+  const line = JSON.stringify(record) + '\n';
+  appendFileSync(STORE_FILE, line, 'utf8');
+}
+
+// ─── Parse helpers ───────────────────────────────────────────────────────────
+
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  try { return JSON.parse(trimmed); } catch { return null; }
+}
+
+/** @returns {object[]} */
+export function readAllRecords() {
+  if (!existsSync(STORE_FILE)) return [];
+  try {
+    const raw = readFileSync(STORE_FILE, 'utf8');
+    return raw.split('\n').map(parseLine).filter(r => r !== null);
+  } catch { return []; }
+}
+
+// ─── Range helpers ───────────────────────────────────────────────────────────
+
+function msForRange(range) {
+  const map = { '24h': 86_400_000, '7d': 604_800_000, '30d': 2_592_600_000 };
+  return map[range] ?? 86_400_000;
+}
+
+function dateStr(ts) {
+  const d = new Date(ts);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// ─── Aggregation helpers ─────────────────────────────────────────────────────
+
+function computeTotals(records) {
+  if (records.length === 0) {
+    return { requests: 0, errors: 0, promptTokens: 0, completionTokens: 0,
+             totalTokens: 0, cachedTokens: 0, reasoningTokens: 0,
+             avgLatencyMs: 0, p95LatencyMs: 0, costEstimate: 0 };
+  }
+  const errors    = records.filter(r => r.error !== null).length;
+  const latencies = records.map(r => r.latencyMs).filter(l => l >= 0).sort((a, b) => a - b);
+  const avg       = latencies.length ? latencies.reduce((a, b) => a + b, 0) / latencies.length : 0;
+  const p95Idx    = Math.floor(latencies.length * 0.95);
+  const p95       = latencies[p95Idx] ?? 0;
+  const cost      = records.reduce((sum, r) => sum + estimateCost(r), 0);
+  return {
+    requests:        records.length,
+    errors,
+    promptTokens:    records.reduce((s, r) => s + (r.promptTokens ?? 0), 0),
+    completionTokens: records.reduce((s, r) => s + (r.completionTokens ?? 0), 0),
+    totalTokens:     records.reduce((s, r) => s + (r.totalTokens ?? 0), 0),
+    cachedTokens:    records.reduce((s, r) => s + (r.cachedTokens ?? 0), 0),
+    reasoningTokens: records.reduce((s, r) => s + (r.reasoningTokens ?? 0), 0),
+    avgLatencyMs:    Math.round(avg),
+    p95LatencyMs:    Math.round(p95),
+    costEstimate:    Math.round(cost * 100_000) / 100_000,
+  };
+}
+
+function computeDaily(records) {
+  const byDate = new Map();
+  for (const r of records) {
+    const d = dateStr(r.ts);
+    if (!byDate.has(d)) byDate.set(d, []);
+    byDate.get(d).push(r);
+  }
+  return Array.from(byDate.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([date, recs]) => {
+      const t = computeTotals(recs);
+      return { date, requests: t.requests, totalTokens: t.totalTokens,
+               promptTokens: t.promptTokens, completionTokens: t.completionTokens,
+               errors: t.errors, avgLatencyMs: t.avgLatencyMs };
+    });
+}
+
+function computePerModel(records) {
+  const byModel = new Map();
+  for (const r of records) {
+    const key = `${r.providerId}::${r.modelId}`;
+    if (!byModel.has(key)) byModel.set(key, []);
+    byModel.get(key).push(r);
+  }
+  return Array.from(byModel.entries())
+    .map(([key, recs]) => {
+      const [providerId, modelId] = key.split('::');
+      const t = computeTotals(recs);
+      return { providerId, modelId, requests: t.requests, totalTokens: t.totalTokens,
+               promptTokens: t.promptTokens, completionTokens: t.completionTokens,
+               errors: t.errors, avgLatencyMs: t.avgLatencyMs };
+    })
+    .sort((a, b) => b.requests - a.requests);
+}
+
+function computePerKey(records) {
+  const byKey = new Map();
+  for (const r of records) {
+    const key = `${r.keyEnvVar}::${r.isBackup}`;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(r);
+  }
+  return Array.from(byKey.entries())
+    .map(([key, recs]) => {
+      const [keyEnvVar, isBackupStr] = key.split('::');
+      const isBackup = isBackupStr === 'true';
+      return {
+        keyEnvVar,
+        isBackup,
+        requests: recs.length,
+        errors: recs.filter(r => r.error !== null).length,
+        lastUsed: recs.length ? Math.max(...recs.map(r => r.ts)) : null,
+        status: isBackup ? 'backup' : 'active',
+      };
+    })
+    .sort((a, b) => (b.lastUsed ?? 0) - (a.lastUsed ?? 0));
+}
+
+function computeErrors(records) {
+  const byError = new Map();
+  for (const r of records) {
+    if (!r.error) continue;
+    const key = `${r.error.code}::${r.error.message}`;
+    if (!byError.has(key)) byError.set(key, { code: r.error.code, message: r.error.message, recs: [] });
+    byError.get(key).recs.push(r);
+  }
+  return Array.from(byError.values())
+    .map(({ code, message, recs }) => ({
+      code, message,
+      count: recs.length,
+      lastOccurred: recs.length ? Math.max(...recs.map(r => r.ts)) : null,
+    }))
+    .sort((a, b) => b.count - a.count);
+}
+
+// ─── Query ──────────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} opts
+ * @param {'24h'|'7d'|'30d'|'custom'} [opts.range='24h']
+ * @param {number} [opts.from] — unix ms, required when range === 'custom'
+ * @param {number} [opts.to]   — unix ms, required when range === 'custom'
+ * @param {string} [opts.providerId]
+ * @param {string} [opts.modelId]
+ */
+export function queryUsage(opts = {}) {
+  const { range = '24h', from, to, providerId, modelId } = opts;
+
+  let fromMs;
+  let toMs;
+  if (range === 'custom') {
+    if (typeof from !== 'number' || typeof to !== 'number') {
+      throw new Error('range=custom requires `from` and `to` (unix ms)');
+    }
+    fromMs = from;
+    toMs = to;
+  } else {
+    toMs = Date.now();
+    fromMs = toMs - msForRange(range);
+  }
+
+  let records = readAllRecords()
+    .filter(r => r.ts >= fromMs && r.ts <= toMs);
+
+  if (providerId) records = records.filter(r => r.providerId === providerId);
+  if (modelId)    records = records.filter(r => r.modelId === modelId);
+
+  return {
+    totals:   computeTotals(records),
+    daily:    computeDaily(records),
+    perModel: computePerModel(records),
+    perKey:   computePerKey(records),
+    errors:   computeErrors(records),
+  };
+}
+
+// ─── Rolling summary (for agents) ──────────────────────────────────────────
+
+/** Last-5-minute rolling window totals — used for "agents know their limits". */
+export function getUsageSummary(providerId = 'minimax') {
+  const cutoff = Date.now() - 5 * 60 * 1000;
+  const records = readAllRecords()
+    .filter(r => r.providerId === providerId && r.ts >= cutoff);
+  const t = computeTotals(records);
+  return { requests: t.requests, tokens: t.totalTokens, errors: t.errors, avgLatencyMs: t.avgLatencyMs };
+}
+
+// ─── Agent awareness ─────────────────────────────────────────────────────────
+
+/**
+ * Compact usage summary for injection into an agent's system prompt context.
+ * @param {string} [providerId='minimax']
+ */
+export async function getUsageLimitsForAgent(providerId = 'minimax') {
+  const now = Date.now();
+  const cutoff5m  = now - 5 * 60 * 1000;
+  const cutoff24h = now - 86_400_000;
+
+  const all = readAllRecords().filter(r => r.providerId === providerId);
+
+  const last5min  = all.filter(r => r.ts >= cutoff5m);
+  const last24h   = all.filter(r => r.ts >= cutoff24h);
+
+  const t5  = computeTotals(last5min);
+  const t24 = computeTotals(last24h);
+
+  // Heuristic limits: 1000 requests / 1M tokens per 24h for the free-ish tier.
+  const limits = { dailyRequests: 1000, dailyTokens: 1_000_000 };
+
+  const percentUsed24h = limits.dailyTokens > 0
+    ? Math.round((t24.totalTokens / limits.dailyTokens) * 1000) / 10
+    : 0;
+
+  /** @type {null|string} */
+  let warning = null;
+  if (percentUsed24h >= 80) warning = 'approaching_daily_limit';
+  if (last24h.filter(r => r.isBackup).length > last24h.length * 0.5) {
+    warning = 'key_cycling';
+  }
+
+  // Estimate time until midnight UTC reset.
+  const midnightUtc = new Date();
+  midnightUtc.setUTCHours(0, 0, 0, 0);
+  midnightUtc.setUTCDate(midnightUtc.getUTCDate() + 1);
+  const msUntilReset = midnightUtc.getTime() - now;
+  const hr = Math.floor(msUntilReset / 3_600_000);
+  const min = Math.floor((msUntilReset % 3_600_000) / 60_000);
+  const estimatedTimeUntilReset = msUntilReset > 0 ? `${hr}h ${min}m` : null;
+
+  return {
+    provider: providerId,
+    requestsLast5min:  t5.requests,
+    tokensLast5min:    t5.totalTokens,
+    requestsLast24h:   t24.requests,
+    tokensLast24h:     t24.totalTokens,
+    limits,
+    percentUsed24h,
+    estimatedTimeUntilReset,
+    warning,
+  };
+}
+
+// ─── Prune ──────────────────────────────────────────────────────────────────
+
+/**
+ * Remove records older than `olderThanMs` from the JSONL.
+ * @param {{olderThanMs?: number}} [opts]
+ */
+export function pruneUsage(opts = {}) {
+  const { olderThanMs = Infinity } = opts;
+  if (olderThanMs === Infinity) return 0;
+  const cutoff = Date.now() - olderThanMs;
+  const all = readAllRecords();
+  const keep = all.filter(r => r.ts >= cutoff);
+  const removed = all.length - keep.length;
+  if (removed === 0) return 0;
+  // Rewrite without the pruned records.
+  ensureStoreDir();
+  const tmp = STORE_FILE + '.tmp';
+  const lines = keep.map(r => JSON.stringify(r)).join('\n') + '\n';
+  writeFileSync(tmp, lines, 'utf8');
+  try { unlinkSync(STORE_FILE); } catch { /* ignore */ }
+  try { require('node:fs').renameSync(tmp, STORE_FILE); } catch {
+    writeFileSync(STORE_FILE, lines, 'utf8');
+    try { unlinkSync(tmp); } catch { /* ignore */ }
+  }
+  return removed;
+}
+
+// ─── Test reset ─────────────────────────────────────────────────────────────
+
+/** Wipes the entire JSONL. For tests only. */
+export function __resetStoreForTests() {
+  try { unlinkSync(STORE_FILE); } catch { /* ignore */ }
+}