@vibe-cafe/vibe-usage 0.10.10 → 0.10.12

package/README.md

@@ -51,7 +51,7 @@ npx @vibe-cafe/vibe-usage status       # Show config & detected tools
 
 | Tool | Data Location |
 |------|---------------|
-| Alma | Electron app-data `alma/chat_threads.db` (macOS: `~/Library/Application Support/alma/chat_threads.db`; fixture/relocation override: `VIBE_USAGE_ALMA_DB`). Reads the `usage_records` ledger plus workspace names without selecting chat bodies, message metadata, provider credentials, or full workspace paths. Cache writes are included in input usage. The ledger contains assistant responses only, so Alma emits token buckets without session timing. |
+| Alma | Electron app-data `alma/chat_threads.db` (macOS: `~/Library/Application Support/alma/chat_threads.db`; fixture/relocation override: `VIBE_USAGE_ALMA_DB`). Reads the `usage_records` ledger plus workspace names without selecting chat bodies, message metadata, provider credentials, or full workspace paths. Provider-prefixed model identifiers are normalized to their final model segment. Cache writes are included in input usage. The ledger contains assistant responses only, so Alma emits token buckets without session timing. |
 | Claude Code + Claude Desktop Code/Cowork | Claude Code data in `~/.claude/projects/` (tokens + sessions) and `~/.claude/transcripts/` (sessions only), plus Claude Desktop Cowork's per-session `.claude/projects/` directories. Also scans `$CLAUDE_CONFIG_DIR` and data-bearing `~/.claude-*` profiles. All variants use the existing `claude-code` source; the parser selects the most complete copy of each session so shared/copied transcripts are not counted twice. Logs are streamed and cache creation tokens are included in input usage. |
 | Codex CLI | `$CODEX_HOME/sessions/` and `$CODEX_HOME/archived_sessions/` (default `~/.codex`), plus an optional temporary `--extra-codex-home` or manually persisted `codexExtraHome`; a versioned local index avoids re-reading unchanged rollouts and reads only safe append tails for ordinary sessions, while fork/sub-agent replay matching, duplicate suppression, and live/archive/cross-root deduplication retain their existing semantics |
 | Grok | `$GROK_HOME/sessions/<encoded-cwd>/<session-id>/` (default `~/.grok`); token usage from `updates.jsonl` `turn_completed.usage` (per-model `modelUsage`, cache reads, reasoning); project from `summary.json` cwd; honors `GROK_HOME` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-cafe/vibe-usage",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "description": "Track your AI coding tool token usage and sync to vibecafe.ai",
   "type": "module",
   "scripts": {

package/src/api.js

@@ -231,75 +231,89 @@ function _jsonRequest(apiUrl, path, method, body, timeoutMs) {
 }
 
 /**
- * GET user settings from the vibecafe API.
- * Returns null after transient failures are exhausted. A 401 remains distinct
- * so callers can surface invalid credentials instead of calling it an outage.
+ * Authenticated GET returning parsed JSON. Shared by summary and settings so
+ * callers don't hand-roll their own https request + error mapping.
+ * - 401 → Error('UNAUTHORIZED') with statusCode 401
+ * - other non-2xx / timeout / bad JSON → Error with statusCode
  * @param {string} apiUrl
  * @param {string} apiKey
- * @returns {Promise<{uploadProject: boolean} | null>}
+ * @param {string} path
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<any>}
  */
-export async function fetchSettings(apiUrl, apiKey, retry = {}) {
-  const wait = retry.sleep ?? sleep;
-  const random = retry.random ?? Math.random;
-
-  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    try {
-      return await fetchSettingsOnce(apiUrl, apiKey);
-    } catch (err) {
-      if (err.message === 'UNAUTHORIZED') throw err;
-      // Retrying a permanent client response cannot make it valid. 429 is the
-      // exception: it is transient load shedding and benefits from backoff.
-      if (err.statusCode >= 400 && err.statusCode < 500 && err.statusCode !== 429) {
-        return null;
-      }
-      if (attempt < MAX_RETRIES - 1) {
-        await wait(retryDelayMs(attempt, random));
-      }
-    }
-  }
-  return null;
-}
-
-function fetchSettingsOnce(apiUrl, apiKey) {
+export function getJson(apiUrl, apiKey, path, { timeoutMs = 15_000 } = {}) {
   return new Promise((resolve, reject) => {
-    const url = new URL('/api/usage/settings', apiUrl);
+    const url = new URL(path, apiUrl);
     const mod = url.protocol === 'https:' ? https : http;
 
     const req = mod.request(url, {
       method: 'GET',
-      timeout: 10_000,
-      headers: {
-        'Authorization': `Bearer ${apiKey}`,
-      },
+      timeout: timeoutMs,
+      headers: { 'Authorization': `Bearer ${apiKey}` },
     }, (res) => {
       let data = '';
       res.on('data', (chunk) => { data += chunk; });
       res.on('end', () => {
         if (res.statusCode === 401) {
-          reject(new Error('UNAUTHORIZED'));
+          const err = new Error('UNAUTHORIZED');
+          err.statusCode = 401;
+          reject(err);
           return;
         }
         if (res.statusCode < 200 || res.statusCode >= 300) {
-          const err = new Error(`HTTP ${res.statusCode}: ${data}`);
+          const err = new Error(`HTTP ${res.statusCode}: ${data.slice(0, 200)}`);
           err.statusCode = res.statusCode;
           reject(err);
           return;
         }
         try {
-          const settings = JSON.parse(data);
-          if (typeof settings?.uploadProject !== 'boolean') {
-            reject(new Error('Invalid settings response'));
-            return;
-          }
-          resolve(settings);
+          resolve(JSON.parse(data));
         } catch {
-          reject(new Error('Invalid settings response'));
+          reject(new Error('Invalid JSON response'));
         }
       });
     });
 
     req.on('error', reject);
-    req.on('timeout', () => { req.destroy(new Error('Settings request timed out')); });
+    req.on('timeout', () => { req.destroy(); reject(new Error(`Request timed out (${timeoutMs}ms)`)); });
     req.end();
   });
 }
+
+/**
+ * GET user settings from the vibecafe API.
+ * Returns null after transient failures are exhausted. A 401 remains distinct
+ * so callers can surface invalid credentials instead of calling it an outage.
+ * @param {string} apiUrl
+ * @param {string} apiKey
+ * @returns {Promise<{uploadProject: boolean} | null>}
+ */
+export async function fetchSettings(apiUrl, apiKey, retry = {}) {
+  const wait = retry.sleep ?? sleep;
+  const random = retry.random ?? Math.random;
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    try {
+      return await fetchSettingsOnce(apiUrl, apiKey);
+    } catch (err) {
+      if (err.message === 'UNAUTHORIZED') throw err;
+      // Retrying a permanent client response cannot make it valid. 429 is the
+      // exception: it is transient load shedding and benefits from backoff.
+      if (err.statusCode >= 400 && err.statusCode < 500 && err.statusCode !== 429) {
+        return null;
+      }
+      if (attempt < MAX_RETRIES - 1) {
+        await wait(retryDelayMs(attempt, random));
+      }
+    }
+  }
+  return null;
+}
+
+async function fetchSettingsOnce(apiUrl, apiKey) {
+  const settings = await getJson(apiUrl, apiKey, '/api/usage/settings', { timeoutMs: 10_000 });
+  if (typeof settings?.uploadProject !== 'boolean') {
+    throw new Error('Invalid settings response');
+  }
+  return settings;
+}

package/src/parsers/aggregate.js

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+
+// Shared bucket/session aggregation used by every parser. Lives in its own
+// module (not the parser registry in index.js) so parsers never have to import
+// the registry that imports them — that circular dependency only worked because
+// these functions are hoisted declarations. Keeping them here breaks the cycle.
+//
+// Data model: parsers emit flat per-message "entries" (token usage) and
+// per-message "events" (timing), and these two functions fold them into the
+// bucket/session shapes described in AGENTS.md.
+
+export function roundToHalfHour(date) {
+  const d = new Date(date);
+  d.setMinutes(d.getMinutes() < 30 ? 0 : 30, 0, 0);
+  return d;
+}
+
+// Server column limits (usage_buckets: model varchar(100), project varchar(200)).
+// Anything longer aborts the whole INSERT chunk with 22001, so clamp here.
+const MODEL_MAX_LENGTH = 100;
+const PROJECT_MAX_LENGTH = 200;
+
+// Server token columns are bigint — a single fractional/NaN value aborts the
+// whole INSERT chunk with 22P02, taking every other tool's rows in the batch
+// down with it.
+function toTokenCount(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.round(n);
+}
+
+export function aggregateToBuckets(entries) {
+  const map = new Map();
+
+  for (const e of entries) {
+    const model = String(e.model || 'unknown').slice(0, MODEL_MAX_LENGTH);
+    const project = String(e.project || 'unknown').slice(0, PROJECT_MAX_LENGTH);
+    const bucketStart = roundToHalfHour(e.timestamp).toISOString();
+    const key = `${e.source}|${model}|${project}|${e.hostname || ''}|${bucketStart}`;
+
+    if (!map.has(key)) {
+      map.set(key, {
+        source: e.source,
+        model,
+        project,
+        // Cloud-sourced parsers (cursor) pre-set a fixed hostname sentinel; it
+        // must survive aggregation, or sync.js stamps the machine hostname and
+        // every machine gets its own duplicate row server-side.
+        ...(e.hostname ? { hostname: e.hostname } : {}),
+        bucketStart,
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedInputTokens: 0,
+        reasoningOutputTokens: 0,
+      });
+    }
+
+    const b = map.get(key);
+    b.inputTokens += e.inputTokens || 0;
+    b.outputTokens += e.outputTokens || 0;
+    b.cachedInputTokens += e.cachedInputTokens || 0;
+    b.reasoningOutputTokens += e.reasoningOutputTokens || 0;
+  }
+
+  // Clamp after summation, not per entry — rounding each entry first would
+  // discard sub-integer values instead of letting them accumulate.
+  return Array.from(map.values()).map((b) => {
+    const inputTokens = toTokenCount(b.inputTokens);
+    const outputTokens = toTokenCount(b.outputTokens);
+    const cachedInputTokens = toTokenCount(b.cachedInputTokens);
+    const reasoningOutputTokens = toTokenCount(b.reasoningOutputTokens);
+    return {
+      ...b,
+      inputTokens,
+      outputTokens,
+      cachedInputTokens,
+      reasoningOutputTokens,
+      totalTokens: inputTokens + outputTokens + reasoningOutputTokens,
+    };
+  });
+}
+
+/**
+ * Extract session metadata from timing events.
+ * Each event: { sessionId, source, project, timestamp: Date, role: 'user'|'assistant' }
+ *
+ * Turn = first AI response → last AI response before next user prompt.
+ * activeSeconds = sum(generation durations), excluding queue/TTFT wait.
+ * durationSeconds = wall clock from first to last message.
+ */
+export function extractSessions(events) {
+  const groups = new Map();
+  for (const e of events) {
+    if (!groups.has(e.sessionId)) groups.set(e.sessionId, []);
+    groups.get(e.sessionId).push(e);
+  }
+
+  const sessions = [];
+  for (const [sessionId, sessionEvents] of groups) {
+    sessionEvents.sort((a, b) => a.timestamp - b.timestamp);
+
+    const first = sessionEvents[0];
+    const last = sessionEvents[sessionEvents.length - 1];
+    const durationSeconds = Math.round((last.timestamp - first.timestamp) / 1000);
+
+    let activeSeconds = 0;
+    let turnStart = null;
+    let turnEnd = null;
+    let waitingForFirstResponse = false;
+
+    for (const event of sessionEvents) {
+      if (event.role === 'user') {
+        if (turnStart !== null && turnEnd !== null && turnEnd > turnStart) {
+          activeSeconds += Math.round((turnEnd - turnStart) / 1000);
+        }
+        turnStart = null;
+        turnEnd = null;
+        waitingForFirstResponse = true;
+      } else if (waitingForFirstResponse) {
+        turnStart = event.timestamp;
+        turnEnd = event.timestamp;
+        waitingForFirstResponse = false;
+      } else if (turnStart !== null) {
+        turnEnd = event.timestamp;
+      }
+    }
+    if (turnStart !== null && turnEnd !== null && turnEnd > turnStart) {
+      activeSeconds += Math.round((turnEnd - turnStart) / 1000);
+    }
+
+    const userPromptHours = new Array(24).fill(0);
+    let userMessageCount = 0;
+    for (const event of sessionEvents) {
+      if (event.role === 'user') {
+        userMessageCount++;
+        userPromptHours[event.timestamp.getUTCHours()]++;
+      }
+    }
+
+    const sessionHash = createHash('sha256').update(sessionId).digest('hex').slice(0, 16);
+
+    sessions.push({
+      source: first.source,
+      project: first.project || 'unknown',
+      sessionHash,
+      firstMessageAt: first.timestamp.toISOString(),
+      lastMessageAt: last.timestamp.toISOString(),
+      durationSeconds,
+      activeSeconds,
+      messageCount: sessionEvents.length,
+      userMessageCount,
+      userPromptHours,
+    });
+  }
+
+  return sessions;
+}

package/src/parsers/alma.js

@@ -1,11 +1,21 @@
 import { existsSync } from 'node:fs';
 import { basename } from 'node:path';
 import { getAlmaDbPath } from '../tools.js';
-import { aggregateToBuckets } from './index.js';
-import { queryDbJson } from './sqlite.js';
+import { aggregateToBuckets } from './aggregate.js';
+import { toCount } from './fs-utils.js';
+import { queryDbJson, sqliteUnavailableError, isSqliteUnavailableError } from './sqlite.js';
 
 export { getAlmaDbPath as resolveAlmaDbPath };
 
+export function normalizeAlmaModel(value) {
+  if (typeof value !== 'string') return 'unknown';
+  const model = value.trim();
+  if (!model) return 'unknown';
+  const separator = model.lastIndexOf(':');
+  if (separator === -1) return model;
+  return model.slice(separator + 1).trim() || 'unknown';
+}
+
 const ALMA_USAGE_SQL = `
   SELECT
     usage_records.model AS model,
@@ -21,11 +31,6 @@ const ALMA_USAGE_SQL = `
   LEFT JOIN workspaces ON workspaces.id = chat_threads.workspace_id
 `;
 
-function tokenCount(value) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? number : 0;
-}
-
 function safeWorkspaceName(value) {
   if (typeof value !== 'string') return 'unknown';
   const normalized = value.trim().replace(/\\/g, '/').replace(/\/+$/, '');
@@ -53,9 +58,7 @@ export async function parse() {
   try {
     rows = queryDbJson(dbPath, ALMA_USAGE_SQL);
   } catch (error) {
-    if (error?.status === 127 || /ENOENT/i.test(error?.message)) {
-      throw new Error('sqlite3 CLI not found. Install sqlite3 (or use Node >= 22.5) to sync Alma data.');
-    }
+    if (isSqliteUnavailableError(error)) throw sqliteUnavailableError('Alma');
     return skippedResult(error);
   }
 
@@ -64,15 +67,15 @@ export async function parse() {
     const timestamp = new Date(row.timestamp);
     if (Number.isNaN(timestamp.getTime())) continue;
 
-    const inputTokens = tokenCount(row.inputTokens) + tokenCount(row.cacheWriteInputTokens);
-    const outputTokens = tokenCount(row.outputTokens);
-    const cachedInputTokens = tokenCount(row.cachedInputTokens);
-    const reasoningOutputTokens = tokenCount(row.reasoningOutputTokens);
+    const inputTokens = toCount(row.inputTokens) + toCount(row.cacheWriteInputTokens);
+    const outputTokens = toCount(row.outputTokens);
+    const cachedInputTokens = toCount(row.cachedInputTokens);
+    const reasoningOutputTokens = toCount(row.reasoningOutputTokens);
     if (inputTokens + outputTokens + cachedInputTokens + reasoningOutputTokens === 0) continue;
 
     entries.push({
       source: 'alma',
-      model: row.model || 'unknown',
+      model: normalizeAlmaModel(row.model),
       project: safeWorkspaceName(row.workspaceName),
       timestamp,
       inputTokens,

package/src/parsers/amp.js

@@ -1,7 +1,7 @@
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { aggregateToBuckets, extractSessions } from './index.js';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
 
 function resolveThreadsDir() {
   if (process.env.AMP_DATA_DIR) return process.env.AMP_DATA_DIR;

package/src/parsers/antigravity-db.js

@@ -1,7 +1,6 @@
-import { copyFileSync, existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { queryDbJson } from './sqlite.js';
+import { queryDbJsonSnapshotOnLock, sqliteUnavailableError, isSqliteUnavailableError } from './sqlite.js';
 
 /**
  * Offline reader for Antigravity SQLite conversation stores.
@@ -149,38 +148,16 @@ export function parseGenMetadataBlob(buf) {
 
 // ── SQLite store reading ──────────────────────────────────────────────
 
-function isLockError(err) {
-  return err && typeof err.message === 'string' && /database is locked/i.test(err.message);
-}
-
-function isSqliteUnavailableError(err) {
-  return err && typeof err.message === 'string' && /ENOENT|sqlite3.*not found/i.test(err.message);
-}
-
 function queryCascadeDb(conversationsDir, cascadeId, sql) {
   const dbPath = join(conversationsDir, `${cascadeId}.db`);
   try {
-    return queryDbJson(dbPath, sql);
+    // The App can hold the live DB open; queryDbJsonSnapshotOnLock copies the
+    // WAL set to a temp dir and retries on "database is locked" so one active
+    // cascade does not make the whole Antigravity parser go empty.
+    return queryDbJsonSnapshotOnLock(dbPath, sql, { tempPrefix: 'vibe-usage-antigravity-' });
   } catch (err) {
-    if (isSqliteUnavailableError(err)) {
-      throw new Error('sqlite3 CLI not found. Install sqlite3 (or use Node >= 22.5) to sync Antigravity data.');
-    }
-    if (!isLockError(err)) throw err;
-
-    // The App can hold the live DB open. Query a WAL-consistent snapshot so
-    // one active cascade does not make the whole Antigravity parser go empty.
-    const snapshotDir = mkdtempSync(join(tmpdir(), 'vibe-usage-antigravity-'));
-    const snapshotPath = join(snapshotDir, `${cascadeId}.db`);
-    try {
-      copyFileSync(dbPath, snapshotPath);
-      for (const suffix of ['-shm', '-wal']) {
-        const companion = `${dbPath}${suffix}`;
-        if (existsSync(companion)) copyFileSync(companion, `${snapshotPath}${suffix}`);
-      }
-      return queryDbJson(snapshotPath, sql);
-    } finally {
-      rmSync(snapshotDir, { recursive: true, force: true });
-    }
+    if (isSqliteUnavailableError(err)) throw sqliteUnavailableError('Antigravity');
+    throw err;
   }
 }
 

package/src/parsers/antigravity.js

@@ -2,7 +2,7 @@ import { execSync } from 'node:child_process';
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { aggregateToBuckets, extractSessions } from './index.js';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
 import { listDbCascades, readDbUsageRecords, readDbWorkspaceUri, readDbSessionEvents } from './antigravity-db.js';
 
 

package/src/parsers/claude-code.js

@@ -1,7 +1,8 @@
 import { createReadStream, readdirSync, statSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { join, basename, sep } from 'node:path';
-import { aggregateToBuckets, extractSessions } from './index.js';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
+import { projectFromCwd, toCount } from './fs-utils.js';
 import { getClaudeRoots } from '../claude-roots.js';
 
 const MAX_WARNINGS = 20;
@@ -49,19 +50,6 @@ function projectFromRelative(relative) {
   return parts.at(-1) || 'unknown';
 }
 
-/** Works for Unix and Windows cwd values regardless of the current OS. */
-function projectFromCwd(cwd, fallback) {
-  if (typeof cwd !== 'string') return fallback;
-  const trimmed = cwd.trim().replace(/[\\/]+$/, '');
-  if (!trimmed) return fallback;
-  return trimmed.split(/[\\/]/).filter(Boolean).at(-1) || fallback;
-}
-
-function toCount(value) {
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? n : 0;
-}
-
 function cacheCreationTokens(usage) {
   const direct = toCount(usage.cache_creation_input_tokens);
   const breakdown = usage.cache_creation || {};
@@ -207,7 +195,7 @@ async function scanProjectCandidate(candidate) {
     if (usageScore === 0) return;
 
     entries.push({
-      uuid: typeof obj.uuid === 'string' && obj.uuid ? obj.uuid : null,
+      dedupeKey: usageDedupeKey(obj),
       usageScore,
       source: 'claude-code',
       model,
@@ -251,22 +239,36 @@ async function scanBestCandidate(candidates, scanner, ctx) {
   return null;
 }
 
+// One API call is written as several assistant lines - one per content block -
+// that share `message.id`/`requestId` and repeat the same `usage` object, so a
+// per-line key counts the same call once per block. Streaming also emits an
+// early partial line (lower `output_tokens`) before the final one under that
+// same id. Keying on the call identity collapses both, and the existing
+// highest-usageScore wins rule then keeps the final, complete payload.
+// Records without either id (older logs) fall back to the line uuid.
+function usageDedupeKey(obj) {
+  const messageId = typeof obj.message?.id === 'string' ? obj.message.id.trim() : '';
+  const requestId = typeof obj.requestId === 'string' ? obj.requestId.trim() : '';
+  if (messageId || requestId) return `call:${messageId}\u0000${requestId}`;
+  return typeof obj.uuid === 'string' && obj.uuid ? obj.uuid : null;
+}
+
 function mergeUsageEntry(ctx, entry) {
-  if (!entry.uuid) {
+  if (!entry.dedupeKey) {
     ctx.anonymousEntries.push(entry);
     return;
   }
-  const current = ctx.entriesByUuid.get(entry.uuid);
-  // Claude sometimes copies the same UUID into another session with zeroed
+  const current = ctx.entriesByKey.get(entry.dedupeKey);
+  // Claude sometimes copies the same record into another session with zeroed
   // usage. Keep the most complete payload, independent of directory order.
   if (!current || entry.usageScore > current.usageScore) {
-    ctx.entriesByUuid.set(entry.uuid, entry);
+    ctx.entriesByKey.set(entry.dedupeKey, entry);
   }
 }
 
 export async function parse() {
   const ctx = {
-    entriesByUuid: new Map(),
+    entriesByKey: new Map(),
     anonymousEntries: [],
     sessionEvents: [],
     warnings: [],
@@ -295,8 +297,8 @@ export async function parse() {
 
   const entries = [
     ...ctx.anonymousEntries,
-    ...ctx.entriesByUuid.values(),
-  ].map(({ uuid: _uuid, usageScore: _usageScore, ...entry }) => entry);
+    ...ctx.entriesByKey.values(),
+  ].map(({ dedupeKey: _dedupeKey, usageScore: _usageScore, ...entry }) => entry);
 
   return {
     buckets: aggregateToBuckets(entries),

package/src/parsers/cline.js

@@ -1,19 +1,9 @@
-import { readFileSync, statSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { aggregateToBuckets, extractSessions } from './index.js';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
+import { readJsonSafe, projectFromPath } from './fs-utils.js';
 import { findClineDataDirs } from '../cline-roots.js';
 
-function readJsonSafe(path) {
-  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
-}
-
-function projectFromPath(absPath) {
-  if (!absPath || typeof absPath !== 'string') return 'unknown';
-  const trimmed = absPath.replace(/[\\/]+$/, '');
-  const name = basename(trimmed);
-  return name || 'unknown';
-}
-
 export async function parse() {
   const extDirs = findClineDataDirs();
   if (extDirs.length === 0) return { buckets: [], sessions: [] };

package/src/parsers/codex.js

@@ -10,7 +10,7 @@ import {
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createHash } from 'node:crypto';
-import { aggregateToBuckets } from './index.js';
+import { aggregateToBuckets } from './aggregate.js';
 import {
   codexSessionDirs,
   resolveCodexHomes,

package/src/parsers/contract.js

@@ -0,0 +1,55 @@
+/**
+ * Parser result contract.
+ *
+ * Every parser exports an async parse() returning either
+ *   { buckets: object[], sessions: object[], skipped?: boolean, warnings?: string[], indexing?: object }
+ * or a legacy bare buckets array.
+ *
+ * buckets entries are the aggregateToBuckets() output shape
+ * ({ source, model, project, hostname?, bucketStart, inputTokens, ... }).
+ * sessions entries are the extractSessions() output shape
+ * ({ source, project, sessionHash, firstMessageAt, ... }).
+ */
+
+/**
+ * Normalize a raw parser return value into a validated shape. Every emitted
+ * item's source must match the registry key the parser is registered under;
+ * rejecting a typo keeps that parser out of state pruning and prevents a
+ * server-side dropped source from silently discarding its prior upload state.
+ *
+ * @param {string} source registry key
+ * @param {unknown} result raw return value
+ * @returns {{ buckets: object[], sessions: object[], skipped: boolean, warnings: string[], indexing?: object }}
+ */
+export function normalizeParserResult(source, result) {
+  const buckets = Array.isArray(result) ? result : result?.buckets;
+  const sessions = Array.isArray(result) ? [] : (result?.sessions || []);
+  if (!Array.isArray(buckets) || !Array.isArray(sessions)) {
+    throw new TypeError('Parser returned an invalid result');
+  }
+
+  for (const bucket of buckets) {
+    if (bucket?.source !== source) {
+      throw new TypeError(
+        'parser ' + source + ' emitted a bucket with source=' + JSON.stringify(bucket?.source),
+      );
+    }
+  }
+  for (const session of sessions) {
+    if (session?.source !== source) {
+      throw new TypeError(
+        'parser ' + source + ' emitted a session with source=' + JSON.stringify(session?.source),
+      );
+    }
+  }
+
+  const warnings = Array.isArray(result?.warnings) ? result.warnings.slice() : [];
+
+  return {
+    buckets,
+    sessions,
+    skipped: result?.skipped === true,
+    warnings,
+    ...(result?.indexing ? { indexing: result.indexing } : {}),
+  };
+}

package/src/parsers/copilot-cli.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { homedir } from 'node:os';
-import { aggregateToBuckets, extractSessions } from './index.js';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
 
 const SESSION_STATE_DIR = join(homedir(), '.copilot', 'session-state');