fix(cli): align pi/gemini/claude-code token edge cases with ccusage

- pi: an explicit totalTokens can now only ADD tokens the parts don't account for,
  never shrink the parts sum (ccusage apply_total_token_fallback) — fixes both
  total-only records counting 0 output and a small explicit total undercounting.
- gemini: treat empty/whitespace id and sessionId as absent (new nonEmptyStringField,
  mirroring ccusage non_empty_string) so distinct events are not collapsed and
  sessions are attributed correctly; a present messages[] array no longer falls
  through to the stats branch.
- claude-code: drop the synthetic "<synthetic>" model so it does not create a bogus
  per-model bucket.

Author: Jannchie

packages/cli/src/adapters/claude-code.ts

@@ -225,7 +225,13 @@ async function parseClaudeCodeSessionFile(
       continue
     }
 
-    model = stringField(message, 'model') || model
+    // Claude Code stamps injected/synthetic assistant turns with model
+    // "<synthetic>"; ccusage strips it so those tokens don't create a bogus
+    // per-model bucket. Ignore it here too (keep the real running model).
+    const parsedModel = stringField(message, 'model')
+    if (parsedModel && parsedModel !== '<synthetic>') {
+      model = parsedModel
+    }
     // Skip the entire assistant entry when (messageId, requestId) was
     // already processed — applies to both the usage metrics and any
     // tool_use items so we don't double-emit tool.started either.

packages/cli/src/adapters/gemini.ts

@@ -10,6 +10,7 @@ import { matchesBackfillFilters } from '../lib/backfill.js'
 import {
   arrayField,
   isPlainObject,
+  nonEmptyStringField,
   numberField,
   objectField,
   stringField,
@@ -223,16 +224,19 @@ function parseJsonRecord(
   fileStem: string,
   fallbackTs: string,
 ): ParsedFile {
-  const sessionId = stringField(record, 'sessionId')
-    ?? stringField(record, 'session_id')
+  const sessionId = nonEmptyStringField(record, 'sessionId')
+    ?? nonEmptyStringField(record, 'session_id')
     ?? fileStem
   const sessionTs = timestampFrom(stringField(record, 'startTime'))
     ?? timestampFrom(stringField(record, 'lastUpdated'))
     ?? fallbackTs
 
-  const messages = arrayField(record, 'messages').filter(isPlainObject)
-  if (messages.length > 0) {
-    const usages = messages
+  // A `messages` array — even an empty one — marks this as a session-file record;
+  // ccusage returns its (possibly empty) messages and never falls through to the
+  // top-level type/stats branches, so neither do we.
+  if (Array.isArray(record.messages)) {
+    const usages = arrayField(record, 'messages')
+      .filter(isPlainObject)
       .filter(message => stringField(message, 'type') === 'gemini')
       .map(message => parseDirectEvent(message, undefined, sessionTs))
       .filter((usage): usage is GeminiUsage => usage !== undefined)
@@ -268,7 +272,7 @@ function parseJsonlRecords(
     if (!record) {
       continue
     }
-    const sid = stringField(record, 'sessionId') ?? stringField(record, 'session_id')
+    const sid = nonEmptyStringField(record, 'sessionId') ?? nonEmptyStringField(record, 'session_id')
     if (sid) {
       sessionId = sid
     }
@@ -282,7 +286,9 @@ function parseJsonlRecords(
       if (!usage) {
         continue
       }
-      const id = stringField(record, 'id')
+      // An empty / whitespace id is not a real dedup key (ccusage non_empty_string
+      // -> None); push those verbatim instead of collapsing distinct events.
+      const id = nonEmptyStringField(record, 'id')
       if (id === undefined) {
         usages.push(usage)
       }

packages/cli/src/adapters/pi.ts

@@ -323,7 +323,16 @@ export function piUsageFromMessage(message: Record<string, unknown>): Partial<Me
   const output = numberField(usage, 'output') || 0
   const cacheRead = numberField(usage, 'cacheRead') || 0
   const cacheWrite = numberField(usage, 'cacheWrite') || 0
-  const totalTokens = numberField(usage, 'totalTokens') || (input + output + cacheRead + cacheWrite)
+  // ccusage apply_total_token_fallback: an explicit totalTokens can only ADD tokens
+  // the parts don't account for (folded into billable output), never shrink the
+  // parts sum. This both counts total-only records (output would otherwise be 0)
+  // and stops an explicit total smaller than the parts from undercounting the grand
+  // total.
+  const explicitTotal = numberField(usage, 'totalTokens') || 0
+  const partsSum = input + output + cacheRead + cacheWrite
+  const missing = Math.max(0, explicitTotal - partsSum)
+  const billableOutput = output + missing
+  const totalTokens = partsSum + missing
 
   if (totalTokens <= 0) {
     return undefined
@@ -334,7 +343,7 @@ export function piUsageFromMessage(message: Record<string, unknown>): Partial<Me
 
   return {
     tokensInput: (input + cacheRead + cacheWrite) || undefined,
-    tokensOutput: output || undefined,
+    tokensOutput: billableOutput || undefined,
     tokensCachedInput: (cacheRead + cacheWrite) || undefined,
     tokensCacheReadInput: cacheRead || undefined,
     tokensCacheCreationInput: cacheWrite || undefined,

packages/cli/src/lib/fields.ts

@@ -6,6 +6,14 @@ export function stringField(object: unknown, key: string): string | undefined {
   return typeof value === 'string' ? value : undefined
 }
 
+// Like stringField but treats empty / whitespace-only strings as absent, mirroring
+// ccusage's non_empty_string (trim -> None). Returns the original (untrimmed) value
+// when non-empty, so it composes with `??` fallbacks and dedup-key checks.
+export function nonEmptyStringField(object: unknown, key: string): string | undefined {
+  const value = stringField(object, key)
+  return value && value.trim().length > 0 ? value : undefined
+}
+
 export function numberField(object: Record<string, unknown>, key: string): number | undefined {
   const value = object[key]
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined

packages/cli/test/gemini.test.ts

@@ -48,6 +48,22 @@ test('parses JSONL direct events and keeps tokensInput cache-inclusive', async (
   assert.equal(usages[1].metrics?.tokensTotal, 240)
 })
 
+test('empty-string ids are not a dedup key; distinct events are kept', async () => {
+  // stringField returns '' verbatim; treating it as a real id collapsed distinct
+  // events (last-write-wins). ccusage non_empty_string maps '' -> None -> no dedup.
+  const dir = await mkdtemp(path.join(tmpdir(), 'gemini-'))
+  const file = path.join(dir, 'session.jsonl')
+  await writeLines(file, [
+    { type: 'gemini', model: 'g', id: '', timestamp: '2026-04-29T00:00:01.000Z', tokens: { input: 10, output: 5 } },
+    { type: 'gemini', model: 'g', id: '  ', timestamp: '2026-04-29T00:00:02.000Z', tokens: { input: 999, output: 5 } },
+  ])
+
+  const usages = usageEvents(await parse(file))
+  assert.equal(usages.length, 2)
+  assert.equal(usages[0].metrics?.tokensInput, 10)
+  assert.equal(usages[1].metrics?.tokensInput, 999)
+})
+
 test('brackets usage events with session.started and session.ended', async () => {
   const dir = await mkdtemp(path.join(tmpdir(), 'gemini-'))
   const file = path.join(dir, 'session.jsonl')

packages/cli/test/pi.test.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+// eslint-disable-next-line test/no-import-node-test -- This repo uses node:test as the runner.
+import { test } from 'node:test'
+import { piUsageFromMessage } from '../src/adapters/pi.ts'
+
+// pi mirrors ccusage apply_total_token_fallback: an explicit totalTokens can only
+// ADD tokens the itemized parts don't account for, never shrink the parts sum.
+
+test('parity: ccusage pi falls_back_to_total_tokens_when_pi_parts_are_missing', () => {
+  // usage with only totalTokens → the whole total is folded into billable output.
+  const usage = piUsageFromMessage({ usage: { totalTokens: 333 } })
+
+  assert.ok(usage)
+  assert.equal(usage.tokensOutput, 333)
+  assert.equal(usage.tokensTotal, 333)
+})
+
+test('pi never lets an explicit total shrink the parts sum', () => {
+  // totalTokens (150) is smaller than input+output+cacheRead (2150) — e.g. a total
+  // computed excluding cache. The grand total must not undercount the parts.
+  const usage = piUsageFromMessage({ usage: { input: 100, output: 50, cacheRead: 2000, totalTokens: 150 } })
+
+  assert.ok(usage)
+  // cache-inclusive input: 100 + 2000.
+  assert.equal(usage.tokensInput, 2100)
+  assert.equal(usage.tokensOutput, 50)
+  assert.equal(usage.tokensTotal, 2150) // max(explicit 150, parts 2150)
+})
+
+test('pi still passes through a consistent explicit total', () => {
+  const usage = piUsageFromMessage({ usage: { input: 100, output: 50, totalTokens: 200 } })
+
+  assert.ok(usage)
+  assert.equal(usage.tokensInput, 100)
+  assert.equal(usage.tokensOutput, 100) // 50 + (200 - 150) folded
+  assert.equal(usage.tokensTotal, 200)
+})