vibeusage 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "repository": {
@@ -49,7 +49,9 @@
     "validate:ui-hardcode": "node scripts/ops/validate-ui-hardcode.cjs"
   },
   "dependencies": {
-    "@insforge/sdk": "1.2.2"
+    "@insforge/sdk": "1.2.2",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@sourcegraph/scip-typescript": "^0.3.6",
@@ -60,5 +62,8 @@
   ],
   "engines": {
     "node": "20.x"
-  }
+  },
+  "bundleDependencies": [
+    "@insforge/sdk"
+  ]
 }

package/src/commands/doctor.js

@@ -146,8 +146,11 @@ function runAuditTokens({ opts, config }) {
   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`,
+        `Rebuild this source from its local session files: ` +
+        `\`vibeusage sync --rebuild ${result.source}\`\n` +
+        `(That clears the source's file/bucket/group cursors atomically and ` +
+        `re-parses every session — fixing drift caused by interrupted uploads ` +
+        `or partial cursor edits.)\n`,
     );
     process.exitCode = 1;
   }
@@ -176,9 +179,12 @@ function runAuditTokensAll({ opts, config }) {
       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;
+    // no-local-sessions and audit-not-applicable are informational, not hard
+    // errors. The latter means the source has no independent ground-truth to
+    // compare against the DB (e.g. hermes plugin-ledger is the same data that
+    // already feeds the DB).
+    const informationalErrors = new Set(["no-local-sessions", "audit-not-applicable"]);
+    if (!result.ok && !informationalErrors.has(result.error)) anyHardError = true;
     perSource.push(result);
   }
 
@@ -204,8 +210,14 @@ function runAuditTokensAll({ opts, config }) {
           `${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}`;
+        let statusText;
+        if (r.error === "no-local-sessions") {
+          statusText = "no local sessions";
+        } else if (r.error === "audit-not-applicable") {
+          statusText = "N/A";
+        } else {
+          statusText = `ERR ${r.error}`;
+        }
         process.stdout.write(
           `${r.source.padEnd(12)}  ${statusText.padEnd(22)}  ${"—".padStart(10)}  ${"—".padStart(6)}  ${"—".padStart(6)}\n`,
         );

package/src/commands/sync.js

@@ -4,6 +4,7 @@ const fs = require("node:fs/promises");
 const cp = require("node:child_process");
 
 const { ensureDir, readJson, writeJson, openLock } = require("../lib/fs");
+const { scrubSourceCursors, listSupportedSources } = require("../lib/cursor-scrub");
 const {
   listRolloutFiles,
   listClaudeProjectFiles,
@@ -65,6 +66,30 @@ async function cmdSync(argv) {
 
     const config = await readJson(configPath);
     const cursors = (await readJson(cursorsPath)) || { version: 1, files: {}, updatedAt: null };
+
+    if (opts.rebuild) {
+      const scrub = scrubSourceCursors({
+        cursors,
+        sourceId: opts.rebuild,
+        home,
+        env: process.env,
+      });
+      // Persist the cleared cursors before parsing begins. If we crash mid-
+      // rebuild, the next sync resumes from a clean state for this source
+      // rather than re-accumulating onto cached totals (the original bug).
+      await writeJson(cursorsPath, cursors);
+      process.stdout.write(
+        `Rebuilding source=${scrub.sourceId}: cleared ${scrub.filesRemoved} file ` +
+          `cursors, ${scrub.bucketsRemoved} hourly buckets, ` +
+          `${scrub.projectBucketsRemoved} project buckets, ` +
+          `${scrub.groupsRemoved} groupQueued entries` +
+          (scrub.extraCursorsCleared.length
+            ? `, ${scrub.extraCursorsCleared.join("+")}`
+            : "") +
+          `.\n`,
+      );
+    }
+
     const uploadThrottle = normalizeUploadState(await readJson(uploadThrottlePath));
     let uploadThrottleState = uploadThrottle;
 
@@ -445,6 +470,7 @@ function parseArgs(argv) {
     fromRetry: false,
     fromOpenclaw: false,
     drain: false,
+    rebuild: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -453,7 +479,35 @@ function parseArgs(argv) {
     else if (a === "--from-retry") out.fromRetry = true;
     else if (a === "--from-openclaw") out.fromOpenclaw = true;
     else if (a === "--drain") out.drain = true;
-    else throw new Error(`Unknown option: ${a}`);
+    else if (a === "--rebuild") {
+      const v = argv[++i];
+      if (!v || v.startsWith("--")) {
+        throw new Error("--rebuild requires a source id (e.g. --rebuild claude)");
+      }
+      out.rebuild = v;
+    } else if (a.startsWith("--rebuild=")) {
+      const v = a.slice("--rebuild=".length);
+      if (!v) throw new Error("--rebuild= requires a source id");
+      out.rebuild = v;
+    } else throw new Error(`Unknown option: ${a}`);
+  }
+  if (out.rebuild) {
+    const supported = listSupportedSources();
+    if (!supported.includes(out.rebuild)) {
+      throw new Error(
+        `--rebuild: unknown source '${out.rebuild}'. Supported: ${supported.join(", ")}`,
+      );
+    }
+    // A rebuild always wants a full upload pass, otherwise the freshly-rebuilt
+    // buckets would sit in queue.jsonl behind the default 10-batch cap.
+    out.drain = true;
+    // OpenClaw is the only source whose ledger parsing is gated behind an
+    // explicit flag (see sync flow's `opts.fromOpenclaw ? parseOpenclaw... : noop`).
+    // A `--rebuild=openclaw` that doesn't also turn that flag on would scrub
+    // the OpenClaw cursors and persist the cleared state without ever re-
+    // aggregating from the ledger — leaving totals stale until a later
+    // plugin-triggered sync. Force the flag so rebuild actually rebuilds.
+    if (out.rebuild === "openclaw") out.fromOpenclaw = true;
   }
   return out;
 }
@@ -480,11 +534,11 @@ async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
       typeof event.model === "string" && event.model.trim() ? event.model.trim() : "unknown";
     const source = "hermes";
     const delta = {
-      input_tokens: Math.max(0, Number(event.input_tokens || 0)),
-      cached_input_tokens: Math.max(
+      input_tokens: Math.max(
         0,
-        Number(event.cache_read_tokens || 0) + Number(event.cache_write_tokens || 0),
+        Number(event.input_tokens || 0) + Number(event.cache_write_tokens || 0),
       ),
+      cached_input_tokens: Math.max(0, Number(event.cache_read_tokens || 0)),
       output_tokens: Math.max(0, Number(event.output_tokens || 0)),
       reasoning_output_tokens: Math.max(0, Number(event.reasoning_tokens || 0)),
       total_tokens: Math.max(0, Number(event.total_tokens || 0)),
@@ -500,6 +554,19 @@ async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
       continue;
     }
 
+    // Fallback: if all fine-grained channels are 0 but total_tokens > 0,
+    // route total into output so the event isn't silently dropped.
+    // This handles upstream plugins that only report total_tokens.
+    if (
+      delta.input_tokens === 0 &&
+      delta.cached_input_tokens === 0 &&
+      delta.output_tokens === 0 &&
+      delta.reasoning_output_tokens === 0 &&
+      delta.total_tokens > 0
+    ) {
+      delta.output_tokens = delta.total_tokens;
+    }
+
     const bucket = getHourlyBucket(hourlyState, source, model, bucketStart);
     addTotals(bucket.totals, delta);
     touchedBuckets.add(bucketKey(source, model, bucketStart));

package/src/lib/cursor-scrub.js

@@ -0,0 +1,164 @@
+"use strict";
+
+const path = require("node:path");
+
+// scrubSourceCursors clears every cursor field that, if left in place, would
+// cause a re-parse of a source's session files to *accumulate* into
+// previously-uploaded buckets instead of *rebuilding* them from scratch.
+//
+// This is the helper that fixes the bug behind the recent "DB tokens doubled"
+// incident: clearing only `cursors.files` causes the parser to re-read the
+// jsonl files and add their token totals on top of whatever was still cached
+// in `cursors.hourly.buckets`. The result is buckets at roughly 2x the
+// ground truth.
+//
+// Four cursor surfaces must be cleared in lockstep for a source rebuild to
+// be correct:
+//   1. cursors.files entries whose path lives under that source's session
+//      root (so the parser re-reads each file from offset 0).
+//   2. cursors.hourly.buckets keyed `<source>|<model>|<hour>` (so per-bucket
+//      totals restart at zero before re-aggregation).
+//   3. cursors.hourly.groupQueued keys for that source (so the next sync
+//      re-enqueues each touched bucket to queue.jsonl for upload).
+//   4. cursors.projectHourly.buckets keyed `<project>|<source>|<hour>`
+//      (project-scoped totals are aggregated independently from the global
+//      hourly state and would otherwise stay doubled in the dashboard's
+//      per-project views).
+//
+// `cursors.projectHourly.projects` holds project metadata (git remotes,
+// display names) and is intentionally preserved — it carries no token
+// totals, just identity.
+//
+// Sources that don't use `cursors.files` (sqlite-backed opencode, ledger-
+// backed hermes/openclaw) carry their progress in dedicated cursor fields;
+// those are reset directly.
+
+const SOURCES = {
+  claude: {
+    sessionRoot: ({ home }) => path.join(home, ".claude", "projects"),
+  },
+  codex: {
+    sessionRoot: ({ home, env }) =>
+      path.join(env.CODEX_HOME || path.join(home, ".codex"), "sessions"),
+  },
+  "every-code": {
+    sessionRoot: ({ home, env }) =>
+      path.join(env.CODE_HOME || path.join(home, ".code"), "sessions"),
+  },
+  gemini: {
+    sessionRoot: ({ home, env }) =>
+      path.join(env.GEMINI_HOME || path.join(home, ".gemini"), "tmp"),
+  },
+  kimi: {
+    sessionRoot: ({ home, env }) =>
+      path.join(env.KIMI_HOME || path.join(home, ".kimi"), "sessions"),
+  },
+  opencode: {
+    extraCursorKeys: ["opencode", "opencodeSqlite"],
+  },
+  hermes: {
+    extraCursorKeys: ["hermesLedger"],
+  },
+  openclaw: {
+    extraCursorKeys: ["openclawLedger"],
+  },
+};
+
+function listSupportedSources() {
+  return Object.keys(SOURCES);
+}
+
+function scrubSourceCursors({ cursors, sourceId, home, env = process.env }) {
+  if (!cursors || typeof cursors !== "object") {
+    throw new Error("scrubSourceCursors: cursors must be an object");
+  }
+  const config = SOURCES[sourceId];
+  if (!config) {
+    throw new Error(
+      `scrubSourceCursors: unknown sourceId '${sourceId}'. Supported: ${listSupportedSources().join(", ")}`,
+    );
+  }
+
+  const result = {
+    sourceId,
+    filesRemoved: 0,
+    bucketsRemoved: 0,
+    groupsRemoved: 0,
+    projectBucketsRemoved: 0,
+    extraCursorsCleared: [],
+  };
+
+  // 1) cursors.files — strip every entry whose path lives under this source's
+  // session root, so the parser re-reads them from byte 0.
+  if (config.sessionRoot && cursors.files && typeof cursors.files === "object") {
+    const prefix = config.sessionRoot({ home, env });
+    for (const key of Object.keys(cursors.files)) {
+      if (typeof key !== "string") continue;
+      if (key.startsWith(prefix)) {
+        delete cursors.files[key];
+        result.filesRemoved += 1;
+      }
+    }
+  }
+
+  // 2) cursors.hourly.buckets — strip every bucket keyed for this source so
+  // its totals restart at zero before re-aggregation.
+  if (cursors.hourly && typeof cursors.hourly === "object") {
+    const bucketPrefix = `${sourceId}|`;
+    if (cursors.hourly.buckets && typeof cursors.hourly.buckets === "object") {
+      for (const key of Object.keys(cursors.hourly.buckets)) {
+        if (typeof key === "string" && key.startsWith(bucketPrefix)) {
+          delete cursors.hourly.buckets[key];
+          result.bucketsRemoved += 1;
+        }
+      }
+    }
+    // 3) cursors.hourly.groupQueued — strip per-source enqueue records so
+    // the next sync re-enqueues each touched bucket for upload.
+    if (cursors.hourly.groupQueued && typeof cursors.hourly.groupQueued === "object") {
+      for (const key of Object.keys(cursors.hourly.groupQueued)) {
+        if (typeof key === "string" && key.startsWith(bucketPrefix)) {
+          delete cursors.hourly.groupQueued[key];
+          result.groupsRemoved += 1;
+        }
+      }
+    }
+  }
+
+  // 4) cursors.projectHourly.buckets — keyed `<project_key>|<source>|<hour>`.
+  // Strip the buckets where the middle segment matches this source, leaving
+  // every other source's project-scoped totals (and the projects metadata
+  // map) untouched.
+  if (
+    cursors.projectHourly &&
+    typeof cursors.projectHourly === "object" &&
+    cursors.projectHourly.buckets &&
+    typeof cursors.projectHourly.buckets === "object"
+  ) {
+    for (const key of Object.keys(cursors.projectHourly.buckets)) {
+      if (typeof key !== "string") continue;
+      const parts = key.split("|");
+      if (parts.length >= 2 && parts[1] === sourceId) {
+        delete cursors.projectHourly.buckets[key];
+        result.projectBucketsRemoved += 1;
+      }
+    }
+  }
+
+  // 5) Source-specific top-level cursor fields (opencode sqlite progress,
+  // hermes/openclaw ledger offsets). Resetting these is what makes a
+  // rebuild work for non-file sources.
+  for (const key of config.extraCursorKeys || []) {
+    if (key in cursors) {
+      delete cursors[key];
+      result.extraCursorsCleared.push(key);
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  scrubSourceCursors,
+  listSupportedSources,
+};

package/src/lib/fs.js

@@ -1,6 +1,12 @@
 const fs = require("node:fs/promises");
 const path = require("node:path");
 
+// proper-lockfile is required lazily inside openLock(): some callers copy
+// src/lib/fs.js into sandboxes that have no node_modules (e.g. the openclaw
+// session plugin test, which materializes src/ under a tmp dir to test the
+// ledger). Those callers only use ensureDir/readJson/etc and would crash on
+// a top-level require.
+
 async function ensureDir(p) {
   await fs.mkdir(p, { recursive: true });
 }
@@ -47,23 +53,132 @@ async function chmod600IfPossible(filePath) {
   } catch (_e) {}
 }
 
-async function openLock(lockPath, { quietIfLocked }) {
+// proper-lockfile gives us atomic mkdir-based mutual exclusion plus a heart-
+// beat mechanism that auto-recovers from orphan locks without TOCTOU races:
+//
+//   - The holder process refreshes the lock-directory's mtime every `update`
+//     ms. As long as that interval keeps running, the lock is "fresh".
+//   - Any acquirer that finds the existing lock with mtime older than `stale`
+//     ms takes it over via a compare-and-swap that is safe under concurrent
+//     attempts (the library's own contract).
+//   - If the holder dies (crash, SIGKILL, reboot) the heartbeat stops; the
+//     next acquirer sees the stale mtime and recovers automatically.
+//
+// We deliberately set `stale` larger than the default to give a working sync
+// some headroom against transient event-loop pauses (large JSON.parse, GC).
+// We pass `realpath: false` because the lock target may not exist as a file
+// — proper-lockfile creates the lock-directory at `lockPath` directly.
+const LOCK_STALE_MS = 60_000;
+const LOCK_UPDATE_MS = 10_000;
+
+async function openLock(lockPath, { quietIfLocked } = {}) {
+  // Lazy require: see top-of-file note about sandboxed callers.
+  const lockfile = require("proper-lockfile");
+
+  // Migration path: pre-proper-lockfile versions of vibeusage created the
+  // lock as a regular *file* (fs.open with "wx"). proper-lockfile creates
+  // it as a *directory* (mkdir). If we hand a stale legacy file off to
+  // proper-lockfile, its mkdir will EEXIST and its internal rmdir-fallback
+  // will then ENOTDIR, throwing instead of returning ELOCKED. Detect and
+  // resolve that mismatch up front.
+  const migration = await migrateLegacyLockFile(lockPath);
+  if (migration === "yield-to-legacy-holder") {
+    if (!quietIfLocked) process.stdout.write("Another sync is already running.\n");
+    return null;
+  }
+
+  let release;
   try {
-    const handle = await fs.open(lockPath, "wx");
-    return {
-      async release() {
-        await handle.close().catch(() => {});
-      },
-    };
+    release = await lockfile.lock(lockPath, {
+      lockfilePath: lockPath,
+      realpath: false,
+      stale: LOCK_STALE_MS,
+      update: LOCK_UPDATE_MS,
+      retries: 0,
+    });
   } catch (e) {
-    if (e && e.code === "EEXIST") {
-      if (!quietIfLocked) {
-        process.stdout.write("Another sync is already running.\n");
-      }
+    if (e && e.code === "ELOCKED") {
+      if (!quietIfLocked) process.stdout.write("Another sync is already running.\n");
       return null;
     }
     throw e;
   }
+  return {
+    async release() {
+      try {
+        await release();
+      } catch (_e) {
+        // Best-effort cleanup. proper-lockfile throws if the lock was already
+        // compromised (e.g. taken over by another process while we were
+        // running) — there is nothing useful to do at that point.
+      }
+    },
+  };
+}
+
+// Detect a leftover lock file from the previous wx-based scheme. Three cases:
+//   - "orphan"        — proven dead by PID liveness; safe to unlink and migrate.
+//   - "alive"         — recorded PID is still running; yield with the standard
+//                       "another sync running" UX.
+//   - "indeterminate" — empty / corrupt / unreadable file. The original
+//                       production openLock wrote a *zero-byte* file (it never
+//                       called writeFile after fs.open(path, "wx")), so this
+//                       is the **expected** legacy format. We cannot prove
+//                       its holder is dead and we MUST NOT auto-delete: a
+//                       still-running legacy sync would lose its lock and a
+//                       new-format sync would start in parallel. Yield and
+//                       print an actionable manual-cleanup notice.
+async function migrateLegacyLockFile(lockPath) {
+  let stat;
+  try {
+    stat = await fs.lstat(lockPath);
+  } catch (e) {
+    if (e && e.code === "ENOENT") return "no-legacy";
+    throw e;
+  }
+  if (stat.isDirectory()) return "no-legacy"; // already in proper-lockfile format
+
+  const verdict = await classifyLegacyFileLock(lockPath);
+  if (verdict === "orphan") {
+    await fs.unlink(lockPath).catch(() => {});
+    return "migrated";
+  }
+  if (verdict === "indeterminate") {
+    process.stderr.write(
+      `vibeusage: legacy sync.lock at ${lockPath} carries no PID payload, ` +
+        `so we cannot prove its owner is dead. Auto-deletion is unsafe — a ` +
+        `still-running legacy sync would lose its lock. If no legacy ` +
+        `vibeusage sync is actually running, remove it manually: rm ${JSON.stringify(
+          lockPath,
+        )}\n`,
+    );
+  }
+  return "yield-to-legacy-holder";
+}
+
+async function classifyLegacyFileLock(lockPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(lockPath, "utf8");
+  } catch (_e) {
+    return "indeterminate";
+  }
+  if (!raw) return "indeterminate";
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_e) {
+    return "indeterminate";
+  }
+  const pid = parsed?.pid;
+  if (!Number.isFinite(pid)) return "indeterminate";
+  try {
+    process.kill(pid, 0);
+    return "alive";
+  } catch (e) {
+    if (e && e.code === "ESRCH") return "orphan";
+    return "alive"; // EPERM = pid exists but belongs to another user
+  }
 }
 
 module.exports = {

package/src/lib/hermes-config.js

@@ -4,6 +4,11 @@ const fs = require("node:fs/promises");
 const fssync = require("node:fs");
 
 const { ensureDir, writeFileAtomic } = require("./fs");
+const {
+  addEnabledPlugin,
+  removeEnabledPlugin,
+  probeEnabledPlugin,
+} = require("./hermes-plugins-config");
 
 const HERMES_PLUGIN_ID = "vibeusage";
 const HERMES_PLUGIN_MARKER = "VIBEUSAGE_HERMES_PLUGIN";
@@ -78,11 +83,33 @@ async function probeHermesPlugin({ home = os.homedir(), env = process.env, track
     };
   }
 
-  const configured = yamlState.value === expectedYaml && initState.value === expectedInit;
+  const filesMatch = yamlState.value === expectedYaml && initState.value === expectedInit;
+
+  // Hermes user plugins are opt-in: the hooks only fire if vibeusage is in
+  // plugins.enabled. Files-on-disk are necessary but NOT sufficient — without
+  // the allow-list entry the ledger stays empty and we silently report 0
+  // tokens forever (see hermes_cli/plugins.py:_get_enabled_plugins).
+  const enabledState = await probeEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+  const isEnabled = enabledState.state === "enabled";
+
+  if (!filesMatch || !isEnabled) {
+    return {
+      configured: false,
+      status: "drifted",
+      detail: "Run vibeusage init to reconcile plugin",
+      filesMatch,
+      enabled: isEnabled,
+      enabledState: enabledState.state,
+      ...paths,
+    };
+  }
+
   return {
-    configured,
-    status: configured ? "ready" : "drifted",
-    detail: configured ? "Plugin installed" : "Run vibeusage init to reconcile plugin",
+    configured: true,
+    status: "ready",
+    detail: "Plugin installed",
+    filesMatch: true,
+    enabled: true,
     ...paths,
   };
 }
@@ -93,30 +120,76 @@ async function installHermesPlugin({ home = os.homedir(), env = process.env, tra
   const nextInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
   const currentYaml = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
   const currentInit = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
-  const changed = currentYaml !== nextYaml || currentInit !== nextInit;
+  const filesChanged = currentYaml !== nextYaml || currentInit !== nextInit;
 
   await ensureDir(paths.pluginDir);
   await writeFileAtomic(paths.pluginYamlPath, nextYaml);
   await writeFileAtomic(paths.pluginInitPath, nextInit);
-  return { configured: true, changed, ...paths };
+
+  // Also opt the plugin into Hermes' allow-list. Hermes loads user plugins
+  // only when their name appears in plugins.enabled (post v20→v21 migration).
+  // Without this step the hooks never fire and the ledger stays empty.
+  let enabledChanged = false;
+  let enableSkippedReason = null;
+  try {
+    const enableResult = await addEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+    enabledChanged = Boolean(enableResult.changed);
+  } catch (err) {
+    // Refuse to clobber malformed user config; surface the reason but don't
+    // throw — the file install half still has value, and the user can rerun
+    // init after fixing config.yaml.
+    enableSkippedReason = err && err.code ? err.code : "enable-failed";
+  }
+
+  return {
+    configured: enableSkippedReason === null,
+    changed: filesChanged || enabledChanged,
+    filesChanged,
+    enabledChanged,
+    enableSkippedReason,
+    ...paths,
+  };
 }
 
 async function removeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
   const paths = resolveHermesPluginPaths({ home, env, trackerDir });
   const hadPluginDir = await pathExists(paths.pluginDir);
+
+  // Always try to clean up the allow-list entry, even if the plugin dir is
+  // already gone — config.yaml could otherwise be left referencing a plugin
+  // that no longer exists.
+  let enabledChanged = false;
+  try {
+    const enableResult = await removeEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+    enabledChanged = Boolean(enableResult.changed);
+  } catch (_err) {
+    // Best-effort; mirrors the behaviour above. Don't block file removal on
+    // a malformed config.yaml.
+  }
+
   if (!hadPluginDir) {
-    return { removed: false, skippedReason: "plugin-missing", ...paths };
+    return {
+      removed: enabledChanged,
+      skippedReason: enabledChanged ? null : "plugin-missing",
+      enabledChanged,
+      ...paths,
+    };
   }
 
   const yamlText = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
   const initText = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
   const markerPresent = hasHermesPluginMarker(yamlText) && hasHermesPluginMarker(initText);
   if (!markerPresent) {
-    return { removed: false, skippedReason: "unexpected-content", ...paths };
+    return {
+      removed: false,
+      skippedReason: "unexpected-content",
+      enabledChanged,
+      ...paths,
+    };
   }
 
   await fs.rm(paths.pluginDir, { recursive: true, force: true }).catch(() => {});
-  return { removed: true, ...paths };
+  return { removed: true, enabledChanged, ...paths };
 }
 
 function buildHermesPluginYaml() {

package/src/lib/hermes-plugins-config.js

@@ -0,0 +1,266 @@
+"use strict";
+
+/**
+ * Manage the `plugins.enabled` allow-list inside Hermes' config.yaml.
+ *
+ * Hermes (>= the v20→v21 migration) loads user plugins on an opt-in basis:
+ * a plugin in `~/.hermes/plugins/<name>/` only fires its hooks if its name
+ * appears in `plugins.enabled` of `~/.hermes/config.yaml` (see
+ * `hermes_cli/plugins.py:_get_enabled_plugins` and the discovery loop at
+ * `hermes_cli/plugins.py:641`).
+ *
+ * `installHermesPlugin` therefore must do TWO things to actually wire up the
+ * vibeusage hook:
+ *   1. Drop the plugin files into `~/.hermes/plugins/vibeusage/` (handled by
+ *      `hermes-config.js`).
+ *   2. Make sure `vibeusage` is listed under `plugins.enabled` here.
+ *
+ * Implementation notes:
+ *   - We use the `yaml` package's `parseDocument` to preserve user comments,
+ *     anchors, and key order. Plain `yaml.parse` + `yaml.stringify` would lose
+ *     all of that.
+ *   - All operations are idempotent. An already-enabled plugin stays as-is and
+ *     the function reports `changed: false`.
+ *   - The file is written atomically via writeFileAtomic to avoid leaving the
+ *     user with a half-written config.yaml on crash.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+
+const YAML = require("yaml");
+const { writeFileAtomic } = require("./fs");
+
+const HERMES_CONFIG_FILENAME = "config.yaml";
+
+function resolveHermesConfigPath({ home = os.homedir(), env = process.env } = {}) {
+  const explicit = typeof env.HERMES_HOME === "string" ? env.HERMES_HOME.trim() : "";
+  const hermesHome = explicit ? path.resolve(explicit) : path.join(home, ".hermes");
+  return path.join(hermesHome, HERMES_CONFIG_FILENAME);
+}
+
+/**
+ * Probe whether a plugin name is currently enabled in `plugins.enabled`.
+ *
+ * Returns one of:
+ *   - { state: "enabled" } — name appears in plugins.enabled
+ *   - { state: "missing-key" } — config exists but plugins.enabled key is absent
+ *   - { state: "missing-name" } — plugins.enabled exists but does not contain the name
+ *   - { state: "config-missing" } — config.yaml does not exist
+ *   - { state: "config-unreadable", error } — read or parse error
+ */
+async function probeEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return { state: "config-missing", configPath };
+    }
+    return {
+      state: "config-unreadable",
+      error: err && err.message ? err.message : String(err),
+      configPath,
+    };
+  }
+
+  let doc;
+  try {
+    doc = YAML.parseDocument(raw);
+  } catch (err) {
+    return {
+      state: "config-unreadable",
+      error: err && err.message ? err.message : String(err),
+      configPath,
+    };
+  }
+  if (doc.errors && doc.errors.length > 0) {
+    return {
+      state: "config-unreadable",
+      error: doc.errors[0].message || "config.yaml has YAML errors",
+      configPath,
+    };
+  }
+
+  const enabled = doc.getIn(["plugins", "enabled"], true);
+  if (enabled === undefined) {
+    return { state: "missing-key", configPath };
+  }
+  const list = enabled && typeof enabled.toJSON === "function" ? enabled.toJSON() : enabled;
+  if (!Array.isArray(list)) {
+    return { state: "missing-key", configPath };
+  }
+  if (list.includes(name)) {
+    return { state: "enabled", configPath };
+  }
+  return { state: "missing-name", configPath };
+}
+
+/**
+ * Idempotently add `name` to plugins.enabled. Creates the `plugins:` map and
+ * `enabled` sequence if either is missing. Preserves comments and surrounding
+ * keys via parseDocument.
+ *
+ * Returns { changed, configPath, configCreated, alreadyEnabled }.
+ */
+async function addEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw = "";
+  let configCreated = false;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      configCreated = true;
+    } else {
+      throw err;
+    }
+  }
+
+  const doc = raw ? YAML.parseDocument(raw) : new YAML.Document({});
+  if (doc.errors && doc.errors.length > 0) {
+    const err = new Error(`config.yaml has YAML errors: ${doc.errors[0].message}`);
+    err.code = "HERMES_CONFIG_INVALID";
+    throw err;
+  }
+
+  // Ensure plugins is a Map.
+  let pluginsNode = doc.get("plugins", true);
+  if (pluginsNode === undefined || pluginsNode === null) {
+    doc.set("plugins", new YAML.YAMLMap());
+    pluginsNode = doc.get("plugins", true);
+  } else if (!(pluginsNode instanceof YAML.YAMLMap)) {
+    // Existing non-map value (string, list, scalar). Refuse so we never silently
+    // clobber user content. Caller should escalate to the user.
+    const err = new Error(
+      "plugins key in config.yaml is not a mapping; refusing to modify",
+    );
+    err.code = "HERMES_PLUGINS_NOT_MAP";
+    throw err;
+  }
+
+  // Ensure plugins.enabled is a Seq.
+  let enabledNode = pluginsNode.get("enabled", true);
+  if (enabledNode === undefined || enabledNode === null) {
+    pluginsNode.set("enabled", new YAML.YAMLSeq());
+    enabledNode = pluginsNode.get("enabled", true);
+  } else if (!(enabledNode instanceof YAML.YAMLSeq)) {
+    const err = new Error(
+      "plugins.enabled in config.yaml is not a sequence; refusing to modify",
+    );
+    err.code = "HERMES_PLUGINS_ENABLED_NOT_SEQ";
+    throw err;
+  }
+
+  // Idempotent add.
+  const current = enabledNode.toJSON() || [];
+  if (Array.isArray(current) && current.includes(name)) {
+    return {
+      changed: false,
+      configPath,
+      configCreated: false,
+      alreadyEnabled: true,
+    };
+  }
+  enabledNode.add(name);
+
+  const out = String(doc);
+  await writeFileAtomic(configPath, out);
+
+  return {
+    changed: true,
+    configPath,
+    configCreated,
+    alreadyEnabled: false,
+  };
+}
+
+/**
+ * Idempotently remove `name` from plugins.enabled. Cleans up empty container
+ * keys (`plugins.enabled` if it becomes [], and `plugins` if it becomes {}).
+ *
+ * Returns { changed, configPath, wasEnabled }.
+ */
+async function removeEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return { changed: false, configPath, wasEnabled: false };
+    }
+    throw err;
+  }
+
+  const doc = YAML.parseDocument(raw);
+  if (doc.errors && doc.errors.length > 0) {
+    const err = new Error(`config.yaml has YAML errors: ${doc.errors[0].message}`);
+    err.code = "HERMES_CONFIG_INVALID";
+    throw err;
+  }
+
+  const pluginsNode = doc.get("plugins", true);
+  if (!(pluginsNode instanceof YAML.YAMLMap)) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+  const enabledNode = pluginsNode.get("enabled", true);
+  if (!(enabledNode instanceof YAML.YAMLSeq)) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+
+  // Find the index, since YAMLSeq.delete by name doesn't match by string value
+  // reliably across all node shapes. Iterating and matching the JSON value is
+  // the safe path.
+  const items = enabledNode.items;
+  let foundIndex = -1;
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    const value = item && typeof item === "object" && "value" in item ? item.value : item;
+    if (value === name) {
+      foundIndex = i;
+      break;
+    }
+  }
+
+  if (foundIndex < 0) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+
+  enabledNode.delete(foundIndex);
+
+  // Clean up empty containers so we don't leave noise in user config.
+  if (enabledNode.items.length === 0) {
+    pluginsNode.delete("enabled");
+  }
+  if (pluginsNode.items.length === 0) {
+    doc.delete("plugins");
+  }
+
+  const out = String(doc);
+  await writeFileAtomic(configPath, out);
+
+  return { changed: true, configPath, wasEnabled: true };
+}
+
+module.exports = {
+  HERMES_CONFIG_FILENAME,
+  resolveHermesConfigPath,
+  probeEnabledPlugin,
+  addEnabledPlugin,
+  removeEnabledPlugin,
+};

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

@@ -69,6 +69,19 @@ function runSourceAudit({
       throw new Error(`strategy.${key} is required`);
     }
   }
+
+  if (strategy.supportsAudit === false) {
+    return {
+      ok: false,
+      error: "audit-not-applicable",
+      source: strategy.id,
+      message:
+        `source=${strategy.id} does not support independent ground-truth audit ` +
+        "(data comes from the same plugin-ledger pipeline that feeds the DB)",
+      rows: [],
+      maxDriftPct: 0,
+    };
+  }
   if (!Number.isFinite(days) || days <= 0) {
     throw new Error(`days must be a positive number, got ${days}`);
   }

package/src/lib/ops/sources/hermes.js

@@ -24,6 +24,7 @@ const path = require("node:path");
 module.exports = {
   id: "hermes",
   displayName: "Hermes Plugin",
+  supportsAudit: false,
   sessionRoot({ home, env }) {
     const base = (env && env.VIBEUSAGE_HOME) || path.join(home, ".vibeusage");
     return path.join(base, "tracker");

package/src/templates/hermes-vibeusage-plugin/__init__.py

@@ -54,12 +54,12 @@ def post_api_request(session_id="", platform="", model="", provider="", api_mode
     record.update({
         "api_mode": str(api_mode or ""),
         "api_call_count": _safe_int(api_call_count),
-        "input_tokens": _safe_int(usage.get("input_tokens")),
-        "output_tokens": _safe_int(usage.get("output_tokens")),
-        "cache_read_tokens": _safe_int(usage.get("cache_read_tokens")),
-        "cache_write_tokens": _safe_int(usage.get("cache_write_tokens")),
-        "reasoning_tokens": _safe_int(usage.get("reasoning_tokens")),
-        "total_tokens": _safe_int(usage.get("total_tokens")),
+        "input_tokens": _safe_int(usage.get("input_tokens") or usage.get("input")),
+        "output_tokens": _safe_int(usage.get("output_tokens") or usage.get("output")),
+        "cache_read_tokens": _safe_int(usage.get("cache_read_tokens") or usage.get("cache_read")),
+        "cache_write_tokens": _safe_int(usage.get("cache_write_tokens") or usage.get("cache_write")),
+        "reasoning_tokens": _safe_int(usage.get("reasoning_tokens") or usage.get("reasoning")),
+        "total_tokens": _safe_int(usage.get("total_tokens") or usage.get("total")),
         "finish_reason": str(finish_reason or ""),
     })
     return _append_record(record)