vibeusage 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "repository": {

package/src/commands/doctor.js

@@ -6,6 +6,13 @@ const { resolveTrackerPaths } = require("../lib/tracker-paths");
 const { collectTrackerDiagnostics } = require("../lib/diagnostics");
 const { resolveRuntimeConfig } = require("../lib/runtime-config");
 const { buildDoctorReport } = require("../lib/doctor");
+const {
+  DEFAULT_DAYS: AUDIT_DEFAULT_DAYS,
+  DEFAULT_THRESHOLD_PCT: AUDIT_DEFAULT_THRESHOLD,
+  runSourceAudit,
+  getStrategy: getAuditStrategy,
+  listRegisteredSources,
+} = require("../lib/ops/audit-source");
 
 async function cmdDoctor(argv = []) {
   const opts = parseArgs(argv);
@@ -16,6 +23,11 @@ async function cmdDoctor(argv = []) {
   const configStatus = await readJsonStrict(configPath);
   const config =
     configStatus.status === "ok" && isPlainObject(configStatus.value) ? configStatus.value : {};
+
+  if (opts.auditTokens) {
+    return runAuditTokens({ opts, config });
+  }
+
   const runtime = resolveRuntimeConfig({
     cli: { baseUrl: opts.baseUrl },
     config,
@@ -56,14 +68,192 @@ async function cmdDoctor(argv = []) {
   }
 }
 
+function runAuditTokens({ opts, config }) {
+  const sourceId = opts.auditSource || "claude";
+  if (sourceId === "all") {
+    return runAuditTokensAll({ opts, config });
+  }
+  const strategy = getAuditStrategy(sourceId);
+  if (!strategy) {
+    const registered = ["all", ...listRegisteredSources()].join(", ");
+    const message = `unknown --source '${sourceId}'. Registered: ${registered}.`;
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: "unknown-source", message })}\n`);
+    } else {
+      process.stderr.write(`doctor --audit-tokens: ${message}\n`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+
+  let result;
+  try {
+    result = runSourceAudit({
+      strategy,
+      days: opts.auditDays,
+      threshold: opts.auditThreshold,
+      deviceId: config.deviceId || null,
+      dbJsonPath: opts.auditDbJson || null,
+    });
+  } catch (err) {
+    const message = err?.message || String(err);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: "audit-error", message })}\n`);
+    } else {
+      process.stderr.write(`doctor --audit-tokens: ${message}\n`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.ok) process.exitCode = 2;
+    else if (result.exceedsThreshold) process.exitCode = 1;
+    return;
+  }
+
+  if (!result.ok) {
+    process.stderr.write(`doctor --audit-tokens: ${result.message || result.error}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  process.stdout.write(
+    `${result.displayName || result.source} token audit (last ${result.days} days, window >= ${result.windowStartIso})\n`,
+  );
+  process.stdout.write(
+    `Scanned ${result.filesScanned} .jsonl files, ${formatNumber(result.usageLines)} usage lines, ` +
+      `${formatNumber(result.uniqueMessages)} unique message.ids, ` +
+      `${formatNumber(result.duplicatesSkipped)} duplicates skipped.\n\n`,
+  );
+  process.stdout.write(
+    `${"day".padEnd(12)}  ${"truth".padStart(15)}  ${"db".padStart(15)}  ${"ratio".padStart(8)}  ${"drift".padStart(8)}\n`,
+  );
+  process.stdout.write(`${"-".repeat(66)}\n`);
+  for (const r of result.rows) {
+    const ratio = r.ratio == null ? "—" : `${r.ratio.toFixed(3)}x`;
+    const drift = r.driftPct == null ? "—" : `${r.driftPct.toFixed(1)}%`;
+    process.stdout.write(
+      `${r.day.padEnd(12)}  ${formatNumber(r.truth).padStart(15)}  ` +
+        `${formatNumber(r.db).padStart(15)}  ${ratio.padStart(8)}  ${drift.padStart(8)}\n`,
+    );
+  }
+  process.stdout.write(
+    `\nMax drift: ${result.maxDriftPct.toFixed(2)}% (threshold ${result.thresholdPct}%).\n`,
+  );
+
+  if (result.exceedsThreshold) {
+    process.stderr.write(
+      `\nFAIL drift ${result.maxDriftPct.toFixed(2)}% exceeds threshold ${result.thresholdPct}%.\n` +
+        `If vibeusage >= 0.5.0, scrub the Claude/OpenCode cursor block in\n` +
+        `~/.vibeusage/tracker/cursors.json and rerun \`vibeusage sync --drain\`.\n`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+function runAuditTokensAll({ opts, config }) {
+  const ids = listRegisteredSources();
+  const perSource = [];
+  let anyExceeds = false;
+  let anyHardError = false;
+
+  for (const id of ids) {
+    const strategy = getAuditStrategy(id);
+    let result;
+    try {
+      result = runSourceAudit({
+        strategy,
+        days: opts.auditDays,
+        threshold: opts.auditThreshold,
+        deviceId: config.deviceId || null,
+        // --db-json is source-specific so we skip it under --source=all; the
+        // only sane paths are insforge auto-mode or no-local-sessions.
+      });
+    } catch (err) {
+      result = { ok: false, source: id, error: "audit-error", message: err?.message || String(err) };
+      anyHardError = true;
+    }
+    if (result.ok && result.exceedsThreshold) anyExceeds = true;
+    // no-local-sessions is informational, not a hard error; other non-ok states
+    // (cannot-resolve-user-id, insforge-db-query-failed, etc.) count as errors.
+    if (!result.ok && result.error !== "no-local-sessions") anyHardError = true;
+    perSource.push(result);
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: !anyHardError, thresholdPct: opts.auditThreshold, days: opts.auditDays, sources: perSource }, null, 2)}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `Token audit across all registered sources (last ${opts.auditDays} days)\n\n`,
+    );
+    process.stdout.write(
+      `${"source".padEnd(12)}  ${"status".padEnd(22)}  ${"max drift".padStart(10)}  ${"files".padStart(6)}  ${"events".padStart(6)}\n`,
+    );
+    process.stdout.write(`${"-".repeat(70)}\n`);
+    for (const r of perSource) {
+      if (r.ok) {
+        const statusText = r.exceedsThreshold
+          ? `FAIL > ${opts.auditThreshold}%`
+          : `ok`;
+        const drift = `${r.maxDriftPct.toFixed(1)}%`;
+        process.stdout.write(
+          `${r.source.padEnd(12)}  ${statusText.padEnd(22)}  ${drift.padStart(10)}  ${String(r.filesScanned).padStart(6)}  ${String(r.usageLines).padStart(6)}\n`,
+        );
+      } else {
+        const statusText =
+          r.error === "no-local-sessions" ? "no local sessions" : `ERR ${r.error}`;
+        process.stdout.write(
+          `${r.source.padEnd(12)}  ${statusText.padEnd(22)}  ${"—".padStart(10)}  ${"—".padStart(6)}  ${"—".padStart(6)}\n`,
+        );
+      }
+    }
+    process.stdout.write(
+      `\nThreshold ${opts.auditThreshold}%. ` +
+        (anyExceeds
+          ? `At least one source exceeds threshold — rerun \`vibeusage doctor --audit-tokens --source <id>\` for details.\n`
+          : `All sources within threshold.\n`),
+    );
+  }
+
+  if (anyHardError) process.exitCode = 2;
+  else if (anyExceeds) process.exitCode = 1;
+}
+
 function parseArgs(argv) {
-  const out = { json: false, out: null, baseUrl: null };
+  const out = {
+    json: false,
+    out: null,
+    baseUrl: null,
+    auditTokens: false,
+    auditDays: AUDIT_DEFAULT_DAYS,
+    auditThreshold: AUDIT_DEFAULT_THRESHOLD,
+    auditDbJson: null,
+    auditSource: "claude",
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--json") out.json = true;
     else if (arg === "--out") out.out = argv[++i] || null;
     else if (arg === "--base-url") out.baseUrl = argv[++i] || null;
-    else throw new Error(`Unknown option: ${arg}`);
+    else if (arg === "--audit-tokens") out.auditTokens = true;
+    else if (arg === "--days") {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n) || n <= 0) throw new Error(`--days expects a positive number`);
+      out.auditDays = Math.floor(n);
+    } else if (arg === "--threshold") {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n) || n < 0) throw new Error(`--threshold expects a non-negative number`);
+      out.auditThreshold = n;
+    } else if (arg === "--db-json") out.auditDbJson = argv[++i] || null;
+    else if (arg === "--source") {
+      const raw = argv[++i];
+      if (!raw) throw new Error(`--source expects a value`);
+      out.auditSource = String(raw).trim().toLowerCase();
+    } else throw new Error(`Unknown option: ${arg}`);
   }
   return out;
 }
@@ -89,6 +279,10 @@ function formatCheckLine(check = {}) {
   return `- [${status}] ${check.id || "unknown"}${detail}`;
 }
 
+function formatNumber(n) {
+  return Number(n).toLocaleString("en-US");
+}
+
 function isPlainObject(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }

package/src/commands/sync.js

@@ -132,7 +132,7 @@ async function cmdSync(argv) {
       : { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
 
     const claudeFiles = await listClaudeProjectFiles(claudeProjectsDir);
-    let claudeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    let claudeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0, dedupSkipped: 0 };
     if (claudeFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(
@@ -155,6 +155,7 @@ async function cmdSync(argv) {
         },
         source: "claude",
       });
+      await maybeWarnClaudeDedupSpike({ trackerDir, claudeResult });
     }
 
     const geminiFiles = await listGeminiSessionFiles(geminiTmpDir);
@@ -592,6 +593,33 @@ async function parseOpenclawSanitizedLedger({ trackerDir, cursors, queuePath })
   };
 }
 
+// Claude Code occasionally writes the same assistant message multiple times to
+// its session .jsonl (same message.id, different outer uuid). Parser dedup
+// silently skips the dup rows, but a sudden spike in the dedup-skipped ratio
+// usually means an upstream change that deserves human attention. Emit a
+// debug.jsonl line when the ratio crosses 50% so vibeusage doctor / retro
+// reviewers can find it; intentionally non-blocking.
+async function maybeWarnClaudeDedupSpike({ trackerDir, claudeResult }) {
+  const events = Number(claudeResult?.eventsAggregated || 0);
+  const skipped = Number(claudeResult?.dedupSkipped || 0);
+  const total = events + skipped;
+  if (total === 0) return;
+  const ratio = skipped / total;
+  if (ratio <= 0.5) return;
+  const line =
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      event: "claude_dedup_spike",
+      source: "claude",
+      events_aggregated: events,
+      dedup_skipped: skipped,
+      ratio: Number(ratio.toFixed(3)),
+      hint: "Unusual duplicate rate from ~/.claude/projects jsonl; run `vibeusage doctor --audit-tokens` to compare local vs DB totals.",
+    }) + "\n";
+  const logPath = path.join(trackerDir, "notify.debug.jsonl");
+  await fs.appendFile(logPath, line, "utf8").catch(() => {});
+}
+
 async function safeStatSize(p) {
   try {
     const st = await fs.stat(p);

package/src/lib/ops/audit-claude.js

@@ -0,0 +1,35 @@
+"use strict";
+
+/**
+ * audit-claude.js
+ *
+ * Thin backward-compatible shim over audit-source.js. Retained so existing
+ * consumers (`scripts/ops/compare-claude-ground-truth.cjs`, older doctor
+ * imports) keep working. New code should import audit-source directly and
+ * pass the claude strategy.
+ */
+
+const {
+  DEFAULT_DAYS,
+  DEFAULT_THRESHOLD_PCT,
+  runSourceAudit,
+} = require("./audit-source");
+const claudeStrategy = require("./sources/claude");
+
+function runAudit(opts = {}) {
+  const { projectsDir, ...rest } = opts;
+  return runSourceAudit({
+    ...rest,
+    strategy: claudeStrategy,
+    // Preserve the legacy `projectsDir` option so existing callers and tests
+    // (test/doctor-audit-tokens.test.js) keep working without knowing about
+    // the new sessionRootOverride plumbing.
+    sessionRootOverride: projectsDir || rest.sessionRootOverride || null,
+  });
+}
+
+module.exports = {
+  DEFAULT_DAYS,
+  DEFAULT_THRESHOLD_PCT,
+  runAudit,
+};

package/src/lib/ops/audit-source.js

@@ -0,0 +1,364 @@
+"use strict";
+
+/**
+ * audit-source.js — generic ground-truth auditor.
+ *
+ * Every AI CLI source (claude, opencode, codex, gemini, kimi, ...) carries a
+ * different session-log layout and token schema, but the audit shape is the
+ * same: walk local sessions, dedup by upstream id, sum all channels per day,
+ * then compare against DB totals.
+ *
+ * This module captures that shape. Source-specific knowledge lives in
+ * src/lib/ops/sources/<id>.js as a `strategy` object (see CONTRACT below).
+ *
+ * CONTRACT (strategy shape):
+ *   {
+ *     id: "claude" | "opencode" | ...,
+ *     displayName: "Claude Code",
+ *     sessionRoot({ home, env }) -> absolute path,
+ *     walkSessions({ root }) -> string[]  // list of files/dbs to read
+ *     extractUsage(line, context) -> null | {
+ *       timestamp: "<ISO8601>",
+ *       dedupeId: "<stable id>" | null,
+ *       channels: { input, cache_creation, cache_read, output, reasoning }
+ *     }
+ *     // optional: skip the jsonl line-by-line reader if the source uses sqlite
+ *     //            and must iterate rows differently
+ *     iterateRecords(filePath) -> iterable<{ line, context }>
+ *   }
+ *
+ * Consumers:
+ *   - doctor --audit-tokens --source <id>
+ *   - scripts/ops/compare-<source>-ground-truth.cjs  (thin CLI wrappers)
+ */
+
+const fs = require("node:fs");
+const os = require("node:os");
+const { spawnSync } = require("node:child_process");
+
+const DEFAULT_DAYS = 14;
+const DEFAULT_THRESHOLD_PCT = 25;
+
+function runSourceAudit({
+  strategy,
+  days = DEFAULT_DAYS,
+  threshold = DEFAULT_THRESHOLD_PCT,
+  userId = null,
+  deviceId = null,
+  dbJsonPath = null,
+  dbJson = null,
+  home = os.homedir(),
+  env = process.env,
+  sessionRootOverride = null,
+} = {}) {
+  if (!strategy || typeof strategy !== "object") {
+    throw new Error("runSourceAudit requires a strategy object");
+  }
+  for (const key of ["id", "sessionRoot", "walkSessions", "extractUsage"]) {
+    if (typeof strategy[key] !== "function" && typeof strategy[key] !== "string") {
+      throw new Error(`strategy.${key} is required`);
+    }
+  }
+  if (!Number.isFinite(days) || days <= 0) {
+    throw new Error(`days must be a positive number, got ${days}`);
+  }
+  if (!Number.isFinite(threshold) || threshold < 0) {
+    throw new Error(`threshold must be non-negative, got ${threshold}`);
+  }
+
+  const root = sessionRootOverride || strategy.sessionRoot({ home, env });
+  const now = new Date();
+  const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  start.setUTCDate(start.getUTCDate() - (days - 1));
+  const windowStartIso = start.toISOString();
+  const files = strategy.walkSessions({ root, windowStartIso });
+  if (!files || files.length === 0) {
+    return {
+      ok: false,
+      error: "no-local-sessions",
+      source: strategy.id,
+      message: `no local sessions for source=${strategy.id} under ${root}`,
+      rows: [],
+      maxDriftPct: 0,
+    };
+  }
+
+  const local = computeLocalTotals({ files, windowStartIso, strategy });
+
+  let backend;
+  if (dbJson) {
+    try {
+      backend = parseDbJson(dbJson);
+    } catch (err) {
+      return { ok: false, error: "db-json-parse", source: strategy.id, message: err.message, rows: [], maxDriftPct: 0 };
+    }
+  } else if (dbJsonPath) {
+    let blob;
+    try {
+      blob = fs.readFileSync(dbJsonPath, "utf8");
+    } catch (err) {
+      return {
+        ok: false,
+        error: "db-json-read-failed",
+        source: strategy.id,
+        message: `cannot read ${dbJsonPath}: ${err?.message || err}`,
+        rows: [],
+        maxDriftPct: 0,
+      };
+    }
+    backend = parseDbJson(blob);
+  } else {
+    const resolvedUserId = userId || resolveUserIdViaInsforge({ deviceId });
+    if (!resolvedUserId) {
+      return {
+        ok: false,
+        error: "cannot-resolve-user-id",
+        source: strategy.id,
+        message:
+          "cannot resolve user_id; pass userId explicitly, supply dbJson, or make sure `insforge` CLI is linked to the vibeusage workspace and config.deviceId is set",
+        rows: [],
+        maxDriftPct: 0,
+      };
+    }
+    const queryRes = queryDbTotalsViaInsforge({
+      userId: resolvedUserId,
+      source: strategy.id,
+      windowStartIso,
+    });
+    if (!queryRes.ok) {
+      return { ...queryRes, source: strategy.id, rows: [], maxDriftPct: 0 };
+    }
+    backend = queryRes.byDay;
+  }
+
+  const dayKeys = Array.from(new Set([...local.byDay.keys(), ...backend.keys()])).sort();
+  const rows = [];
+  let maxDriftPct = 0;
+  for (const day of dayKeys) {
+    const truth = (local.byDay.get(day) || { total: 0 }).total;
+    const dbTotal = backend.get(day) || 0;
+    const ratio = truth > 0 ? dbTotal / truth : null;
+    const drift = ratio == null ? null : Math.abs(ratio - 1) * 100;
+    if (drift != null && drift > maxDriftPct) maxDriftPct = drift;
+    rows.push({ day, truth, db: dbTotal, ratio, driftPct: drift });
+  }
+
+  return {
+    ok: true,
+    source: strategy.id,
+    displayName: strategy.displayName || strategy.id,
+    windowStartIso,
+    days,
+    thresholdPct: threshold,
+    filesScanned: files.length,
+    usageLines: local.scanned,
+    uniqueMessages: local.uniqueIds,
+    duplicatesSkipped: local.skippedDup,
+    rows,
+    maxDriftPct: Number(maxDriftPct.toFixed(2)),
+    exceedsThreshold: maxDriftPct > threshold,
+  };
+}
+
+function computeLocalTotals({ files, windowStartIso, strategy }) {
+  const byDay = new Map();
+  const seen = new Set();
+  let scanned = 0;
+  let skippedDup = 0;
+
+  const records = typeof strategy.iterateRecords === "function"
+    ? strategy.iterateRecords
+    : defaultIterateRecords;
+
+  for (const filePath of files) {
+    for (const { line, context } of records(filePath)) {
+      const extracted = strategy.extractUsage(line, context);
+      if (!extracted) continue;
+      const { timestamp, dedupeId, channels } = extracted;
+      if (!timestamp || timestamp < windowStartIso) continue;
+      const day = isoDay(timestamp);
+      if (!day) continue;
+
+      scanned += 1;
+      if (dedupeId && seen.has(dedupeId)) {
+        skippedDup += 1;
+        continue;
+      }
+      if (dedupeId) seen.add(dedupeId);
+
+      const input = nonneg(channels.input);
+      const cacheCreation = nonneg(channels.cache_creation);
+      const cacheRead = nonneg(channels.cache_read);
+      const output = nonneg(channels.output);
+      const reasoning = nonneg(channels.reasoning);
+      const total = input + cacheCreation + cacheRead + output + reasoning;
+      if (total === 0) continue;
+
+      let row = byDay.get(day);
+      if (!row) {
+        row = {
+          total: 0,
+          input: 0,
+          cache_creation: 0,
+          cache_read: 0,
+          output: 0,
+          reasoning: 0,
+          messages: 0,
+        };
+        byDay.set(day, row);
+      }
+      row.total += total;
+      row.input += input;
+      row.cache_creation += cacheCreation;
+      row.cache_read += cacheRead;
+      row.output += output;
+      row.reasoning += reasoning;
+      row.messages += 1;
+    }
+  }
+
+  return { byDay, scanned, skippedDup, uniqueIds: seen.size };
+}
+
+function* defaultIterateRecords(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (_err) {
+    return;
+  }
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    yield { line, context: { filePath } };
+  }
+}
+
+function isoDay(ts) {
+  if (typeof ts !== "string") return null;
+  const m = ts.match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : null;
+}
+
+function nonneg(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.floor(n);
+}
+
+function resolveUserIdViaInsforge({ deviceId }) {
+  if (!deviceId) return null;
+  const r = spawnSync(
+    "insforge",
+    [
+      "db",
+      "query",
+      `SELECT user_id FROM vibeusage_tracker_devices WHERE id='${deviceId}' LIMIT 1`,
+    ],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) return null;
+  const m = (r.stdout || "").match(
+    /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/i,
+  );
+  return m ? m[1] : null;
+}
+
+function queryDbTotalsViaInsforge({ userId, source, windowStartIso }) {
+  const sql =
+    `SELECT DATE(hour_start) AS day, SUM(total_tokens) AS tokens ` +
+    `FROM vibeusage_tracker_hourly ` +
+    `WHERE source='${source}' AND user_id='${userId}' AND hour_start >= '${windowStartIso}' ` +
+    `GROUP BY DATE(hour_start) ORDER BY day`;
+  const r = spawnSync("insforge", ["--json", "db", "query", sql], { encoding: "utf8" });
+  if (r.status !== 0) {
+    return {
+      ok: false,
+      error: "insforge-db-query-failed",
+      message:
+        `\`insforge db query\` failed (${r.status}). Run \`insforge current\` to confirm ` +
+        `the CLI is linked to the vibeusage workspace, or pass dbJson directly.`,
+    };
+  }
+  return { ok: true, byDay: parseDbJson(r.stdout) };
+}
+
+function parseDbJson(blob) {
+  let parsed;
+  if (typeof blob === "object" && blob !== null) {
+    parsed = blob;
+  } else {
+    try {
+      parsed = JSON.parse(blob);
+    } catch (err) {
+      throw new Error(`cannot parse DB JSON: ${err?.message || err}`);
+    }
+  }
+  const rows = Array.isArray(parsed)
+    ? parsed
+    : Array.isArray(parsed?.rows)
+      ? parsed.rows
+      : Array.isArray(parsed?.data)
+        ? parsed.data
+        : null;
+  if (!rows) {
+    throw new Error(
+      `DB JSON shape unexpected (need array of {day, tokens}); got ${
+        Object.keys(parsed || {}).join(",") || "(empty)"
+      }`,
+    );
+  }
+  const byDay = new Map();
+  for (const row of rows) {
+    const rawDay = row?.day ?? row?.date ?? row?.bucket_day;
+    const day = typeof rawDay === "string" ? rawDay.slice(0, 10) : null;
+    if (!day) continue;
+    const total = nonneg(row.tokens ?? row.total_tokens ?? row.total);
+    byDay.set(day, total);
+  }
+  return byDay;
+}
+
+// Registry for doctor --audit-tokens --source routing.
+// Register new strategies as they land in sources/<id>.js.
+function getStrategy(id) {
+  switch (id) {
+    case "claude":
+      // eslint-disable-next-line global-require
+      return require("./sources/claude");
+    case "opencode":
+      // eslint-disable-next-line global-require
+      return require("./sources/opencode");
+    case "codex":
+      // eslint-disable-next-line global-require
+      return require("./sources/codex");
+    case "every-code":
+      // eslint-disable-next-line global-require
+      return require("./sources/every-code");
+    case "gemini":
+      // eslint-disable-next-line global-require
+      return require("./sources/gemini");
+    case "kimi":
+      // eslint-disable-next-line global-require
+      return require("./sources/kimi");
+    case "hermes":
+      // eslint-disable-next-line global-require
+      return require("./sources/hermes");
+    case "openclaw":
+      // eslint-disable-next-line global-require
+      return require("./sources/openclaw");
+    default:
+      return null;
+  }
+}
+
+function listRegisteredSources() {
+  return ["claude", "opencode", "codex", "every-code", "gemini", "kimi", "hermes", "openclaw"];
+}
+
+module.exports = {
+  DEFAULT_DAYS,
+  DEFAULT_THRESHOLD_PCT,
+  runSourceAudit,
+  getStrategy,
+  listRegisteredSources,
+};