vibeusage 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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,
+};