tokentracker-cli 0.84.4 → 0.84.6

package/src/lib/rollout.js

@@ -8,6 +8,11 @@ const { ensureDir } = require("./fs");
 const { readSqliteJsonRows, readSqliteJsonRowsAsync } = require("./sqlite-reader");
 const wsl = require("./wsl-probe");
 const { resolveInstallPaths } = require("./install-resolver");
+const {
+  consumeUsageDelta,
+  createUsageDeltaState,
+  snapshotUsageBaselines,
+} = require("./codex-token-usage");
 
 const DEFAULT_SOURCE = "codex";
 const DEFAULT_MODEL = "unknown";
@@ -360,6 +365,9 @@ async function parseRolloutIncremental({
     const lastTotal = sameInode && !truncated && !rebuildingCodexBaseline
       ? prev.lastTotal || null
       : null;
+    const tokenUsageBaselines = sameInode && !truncated && !rebuildingCodexBaseline
+      ? prev.tokenUsageBaselines || null
+      : null;
     const lastModel = sameInode && !truncated ? prev.lastModel || null : null;
 
     const codexProjectFastPath = projectEnabled && fileSource === DEFAULT_SOURCE;
@@ -430,6 +438,7 @@ async function parseRolloutIncremental({
           filePath,
           fileStat: st,
           lastTotal,
+          tokenUsageBaselines,
           lastModel,
           projectState,
           projectMetaCache,
@@ -442,6 +451,7 @@ async function parseRolloutIncremental({
           fileStat: st,
           startOffset,
           lastTotal,
+          tokenUsageBaselines,
           lastModel,
           hourlyState,
           touchedBuckets,
@@ -462,6 +472,7 @@ async function parseRolloutIncremental({
       inode,
       offset: result.endOffset,
       lastTotal: result.lastTotal,
+      tokenUsageBaselines: result.tokenUsageBaselines,
       lastModel: result.lastModel,
       updatedAt: new Date().toISOString(),
     };
@@ -1731,6 +1742,7 @@ async function parseRolloutFile({
   fileStat,
   startOffset,
   lastTotal,
+  tokenUsageBaselines,
   lastModel,
   hourlyState,
   touchedBuckets,
@@ -1751,14 +1763,25 @@ async function parseRolloutFile({
   const projectFileContexts = [];
   addProjectFileContext(projectFileContexts, projectContext);
   if (startOffset >= endOffset) {
-    return { endOffset, lastTotal, lastModel, eventsAggregated: 0, projectFileContexts };
+    return {
+      endOffset,
+      lastTotal,
+      tokenUsageBaselines,
+      lastModel,
+      eventsAggregated: 0,
+      projectFileContexts,
+    };
   }
 
   const stream = fssync.createReadStream(filePath, { encoding: "utf8", start: startOffset });
   const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
 
   let model = typeof lastModel === "string" ? lastModel : null;
-  let totals = lastTotal && typeof lastTotal === "object" ? lastTotal : null;
+  const usageDeltaState = createUsageDeltaState({
+    lastTotal,
+    baselines: tokenUsageBaselines,
+  });
+  let latestTotal = lastTotal && typeof lastTotal === "object" ? lastTotal : null;
   let currentCwd = null;
   let currentDate = null;
   let isForkedRollout = false;
@@ -1840,15 +1863,13 @@ async function parseRolloutFile({
 
     const lastUsage = info.last_token_usage;
     const totalUsage = info.total_token_usage;
+    if (totalUsage && typeof totalUsage === "object") latestTotal = totalUsage;
 
-    const delta = pickDelta(lastUsage, totalUsage, totals);
-    if (!delta) continue;
+    const rawDelta = consumeUsageDelta(usageDeltaState, lastUsage, totalUsage);
+    const delta = rawDelta ? normalizeUsage(rawDelta) : null;
+    if (!delta || isAllZeroUsage(delta)) continue;
     delta.conversation_count = 1;
 
-    if (totalUsage && typeof totalUsage === "object") {
-      totals = totalUsage;
-    }
-
     // Forked Codex rollouts replay the parent session's entire token history
     // into the child file the moment the fork is created. The date guard below
     // (current_date < rolloutDate) catches cross-day forks, but same-day forks
@@ -1863,8 +1884,8 @@ async function parseRolloutFile({
     // flush spacing and well below genuine turn cadence (≥~4.6s observed). The
     // first replayed row cannot be identified without lookahead, so it is still
     // counted (a bounded, <1% residual over-count); dropping real usage is the
-    // worse failure, so we bias against it. `totals` is already advanced above,
-    // keeping the cumulative-delta baseline correct for the live turns we keep.
+    // worse failure, so we bias against it. `usageDeltaState` is already advanced above,
+    // keeping the cumulative lineage correct for the live turns we keep.
     // Scoped to forked codex rollouts. (issue #169 follow-up.)
     let forkedReplaySkip = false;
     if (isForkedRollout && source === DEFAULT_SOURCE && replayPrefixActive) {
@@ -1903,8 +1924,8 @@ async function parseRolloutFile({
     // buckets. External tools rewrite session files without changing the token
     // data — Codex-Manager atomically rewrites them (new inode) to patch the
     // provider on every account/channel switch — so without dedup each switch
-    // double-counts the rewritten sessions. `totals` is already advanced above,
-    // so skipping an already-seen event keeps the cumulative-delta chain intact
+    // double-counts the rewritten sessions. `usageDeltaState` is already advanced above,
+    // so skipping an already-seen event keeps the cumulative lineage intact
     // while preventing the re-add; genuinely new turns carry new timestamps and
     // are still counted. Key = sessionUUID:eventTimestamp (both stable across the
     // rewrite and across a sessions/ -> archived_sessions/ move).
@@ -1939,13 +1960,21 @@ async function parseRolloutFile({
     eventsAggregated += 1;
   }
 
-  return { endOffset, lastTotal: totals, lastModel: model, eventsAggregated, projectFileContexts };
+  return {
+    endOffset,
+    lastTotal: latestTotal,
+    tokenUsageBaselines: snapshotUsageBaselines(usageDeltaState),
+    lastModel: model,
+    eventsAggregated,
+    projectFileContexts,
+  };
 }
 
 async function scanRolloutProjectFileContexts({
   filePath,
   fileStat,
   lastTotal,
+  tokenUsageBaselines,
   lastModel,
   projectState,
   projectMetaCache,
@@ -1958,7 +1987,14 @@ async function scanRolloutProjectFileContexts({
   const projectFileContexts = [];
   addProjectFileContext(projectFileContexts, projectContext);
   if (!projectState || endOffset <= 0) {
-    return { endOffset, lastTotal, lastModel, eventsAggregated: 0, projectFileContexts };
+    return {
+      endOffset,
+      lastTotal,
+      tokenUsageBaselines,
+      lastModel,
+      eventsAggregated: 0,
+      projectFileContexts,
+    };
   }
 
   const stream = fssync.createReadStream(filePath, { encoding: "utf8", start: 0 });
@@ -2005,7 +2041,14 @@ async function scanRolloutProjectFileContexts({
     addProjectFileContext(projectFileContexts, context);
   }
 
-  return { endOffset, lastTotal, lastModel, eventsAggregated: 0, projectFileContexts };
+  return {
+    endOffset,
+    lastTotal,
+    tokenUsageBaselines,
+    lastModel,
+    eventsAggregated: 0,
+    projectFileContexts,
+  };
 }
 
 async function parseClaudeFile({
@@ -3570,48 +3613,6 @@ function extractTokenCount(obj) {
   return null;
 }
 
-function pickDelta(lastUsage, totalUsage, prevTotals) {
-  const hasLast = isNonEmptyObject(lastUsage);
-  const hasTotal = isNonEmptyObject(totalUsage);
-  const hasPrevTotals = isNonEmptyObject(prevTotals);
-
-  if (hasTotal && hasPrevTotals) {
-    if (totalsReset(totalUsage, prevTotals)) {
-      const resetUsage = hasLast ? lastUsage : totalUsage;
-      const normalized = normalizeUsage(resetUsage);
-      return isAllZeroUsage(normalized) ? null : normalized;
-    }
-
-    const delta = {};
-    for (const k of [
-      "input_tokens",
-      "cached_input_tokens",
-      "cache_creation_input_tokens",
-      "output_tokens",
-      "reasoning_output_tokens",
-      "total_tokens",
-    ]) {
-      const a = Number(totalUsage[k]);
-      const b = Number(prevTotals[k]);
-      if (Number.isFinite(a) && Number.isFinite(b)) delta[k] = Math.max(0, a - b);
-    }
-    const normalized = normalizeUsage(delta);
-    return isAllZeroUsage(normalized) ? null : normalized;
-  }
-
-  if (hasLast) {
-    const normalized = normalizeUsage(lastUsage);
-    return isAllZeroUsage(normalized) ? null : normalized;
-  }
-
-  if (hasTotal) {
-    const normalized = normalizeUsage(totalUsage);
-    return isAllZeroUsage(normalized) ? null : normalized;
-  }
-
-  return null;
-}
-
 function normalizeUsage(u) {
   const out = {};
   for (const k of [
@@ -3694,13 +3695,6 @@ function isAllZeroUsage(u) {
   return true;
 }
 
-function totalsReset(curr, prev) {
-  const currTotal = curr?.total_tokens;
-  const prevTotal = prev?.total_tokens;
-  if (!isFiniteNumber(currTotal) || !isFiniteNumber(prevTotal)) return false;
-  return currTotal < prevTotal;
-}
-
 function isFiniteNumber(v) {
   return typeof v === "number" && Number.isFinite(v);
 }
@@ -4940,32 +4934,77 @@ function resolveKiroCliDbPath(env = process.env) {
 // no hyphens. kiro-cli writes proper UUIDs; lock to the canonical shape.
 const KIRO_CLI_SESSION_FILE_RE =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/i;
-
-// Lists ~/.kiro/sessions/cli/{uuid}.json files. Includes files whose sibling
-// .lock is present — we read those as tail-only snapshots so a running
-// session's completed turns still land in the queue on the next sync. The
-// .json files are rewritten atomically by kiro-cli on each turn flush, so
-// a stale read just means we'll pick up the rest next time.
+// The directory prefix and direct messages.jsonl child are the stable
+// contract. Do not assume the suffix will always remain a UUID: Kiro has
+// already changed this layout once, and an opaque non-empty session id is
+// sufficient to keep discovery both bounded and forward-compatible.
+const KIRO_CLI_V2_SESSION_DIR_RE = /^sess_.+$/;
+
+// Lists both Kiro CLI session layouts:
+//   legacy: ~/.kiro/sessions/cli/{uuid}.json
+//   2.13+:  ~/.kiro/sessions/{workspaceHash}/sess_{uuid}/messages.jsonl
+//
+// Legacy .json files are rewritten atomically per turn. The 2.13+ JSONL is
+// append-only and may be read while a session is active. Only the direct
+// messages.jsonl child is accepted; sub-executions and arbitrary nested JSONL
+// files are intentionally excluded.
 //
 // TASK-014: env.HOME is honored (symmetric with resolveKiroCliDbPath) so
 // callers can redirect to a tmp home for hermetic tests/CI.
 function resolveKiroCliSessionFiles(env = process.env) {
   const home = env.HOME || require("node:os").homedir();
   const kiroHome = env.KIRO_HOME || path.join(home, ".kiro");
-  const sessionsDir = path.join(kiroHome, "sessions", "cli");
-  if (!fssync.existsSync(sessionsDir)) return [];
+  const sessionsRoot = path.join(kiroHome, "sessions");
+  if (!fssync.existsSync(sessionsRoot)) return [];
   const files = [];
+
+  const legacyDir = path.join(sessionsRoot, "cli");
   try {
-    for (const entry of fssync.readdirSync(sessionsDir)) {
+    for (const entry of fssync.readdirSync(legacyDir)) {
       // TASK-003: only canonical {uuid}.json files; backups, scratch,
       // typos are skipped so they don't feed JSON.parse garbage.
       if (!KIRO_CLI_SESSION_FILE_RE.test(entry)) continue;
-      files.push(path.join(sessionsDir, entry));
+      files.push(path.join(legacyDir, entry));
     }
   } catch {
     // ignore read errors
   }
-  return files;
+
+  try {
+    const workspaceDirs = fssync.readdirSync(sessionsRoot, {
+      withFileTypes: true,
+    });
+    for (const workspace of workspaceDirs) {
+      if (!workspace.isDirectory() || workspace.name === "cli") continue;
+      const workspacePath = path.join(sessionsRoot, workspace.name);
+      let sessionDirs;
+      try {
+        sessionDirs = fssync.readdirSync(workspacePath, {
+          withFileTypes: true,
+        });
+      } catch {
+        continue;
+      }
+      for (const session of sessionDirs) {
+        if (
+          !session.isDirectory() ||
+          !KIRO_CLI_V2_SESSION_DIR_RE.test(session.name)
+        ) {
+          continue;
+        }
+        const messagesPath = path.join(
+          workspacePath,
+          session.name,
+          "messages.jsonl",
+        );
+        if (fssync.existsSync(messagesPath)) files.push(messagesPath);
+      }
+    }
+  } catch {
+    // ignore read errors
+  }
+
+  return files.sort();
 }
 
 // Build char-count maps from a .jsonl sibling file. Lets us approximate
@@ -5183,6 +5222,199 @@ async function readKiroCliSessionTurns(jsonPath) {
   return flat;
 }
 
+function kiroCliV2ContentChars(value) {
+  if (typeof value === "string") return value.length;
+  if (Array.isArray(value)) {
+    return value.reduce(
+      (sum, item) => sum + kiroCliV2ContentChars(item),
+      0,
+    );
+  }
+  if (!value || typeof value !== "object") return 0;
+  for (const key of ["content", "text", "value", "parts", "entries"]) {
+    if (value[key] !== undefined) {
+      return kiroCliV2ContentChars(value[key]);
+    }
+  }
+  return 0;
+}
+
+// Kiro CLI 2.13+ writes event-sourced sessions under
+// ~/.kiro/sessions/<workspaceHash>/sess_<uuid>/messages.jsonl. The records do
+// not carry token counts, but user/assistant text, turn boundaries, timestamps,
+// and assistant reasoningModelId are sufficient for the same 4 chars/token
+// approximation used by the legacy CLI reader.
+async function readKiroCliV2SessionTurns(messagesPath) {
+  if (
+    !messagesPath ||
+    path.basename(messagesPath) !== "messages.jsonl" ||
+    !fssync.existsSync(messagesPath)
+  ) {
+    return [];
+  }
+
+  const sessionDir = path.dirname(messagesPath);
+  let sessionMeta = {};
+  try {
+    sessionMeta = JSON.parse(
+      fssync.readFileSync(path.join(sessionDir, "session.json"), "utf8"),
+    );
+  } catch {
+    // messages.jsonl is self-contained enough to parse without session.json.
+  }
+
+  const sessionId =
+    typeof sessionMeta?.id === "string" && sessionMeta.id
+      ? sessionMeta.id
+      : path.basename(sessionDir);
+  const fallbackModel =
+    typeof sessionMeta?.modelId === "string" ? sessionMeta.modelId : null;
+  const fallbackTimestamp = Date.parse(
+    sessionMeta?.createdAt || sessionMeta?.lastModifiedAt || "",
+  );
+
+  const flat = [];
+  let stream;
+  try {
+    stream = fssync.createReadStream(messagesPath, { encoding: "utf8" });
+  } catch {
+    return flat;
+  }
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+
+  let pendingUserChars = 0;
+  let pendingUserTimestampMs = NaN;
+  let turn = null;
+  let fallbackTurnIndex = 0;
+
+  const flushTurn = () => {
+    if (!turn) return;
+    const hasUsage =
+      turn.outputChars > 0 ||
+      turn.reasoningChars > 0;
+    const tsMs = Number.isFinite(turn.timestampMs)
+      ? turn.timestampMs
+      : Number.isFinite(pendingUserTimestampMs)
+        ? pendingUserTimestampMs
+        : fallbackTimestamp;
+    if (hasUsage && Number.isFinite(tsMs) && tsMs > 0) {
+      const requestId =
+        turn.executionId ||
+        `${sessionId}:v2:${fallbackTurnIndex}`;
+      const messageIds = Array.from(turn.messageIds);
+      flat.push({
+        request_id: requestId,
+        message_id: messageIds[0] || turn.executionId || null,
+        all_message_ids: messageIds,
+        session_id: sessionId,
+        session_model_id: fallbackModel,
+        model_id: turn.modelId || fallbackModel,
+        request_start_timestamp_ms: tsMs,
+        user_prompt_length: turn.inputChars,
+        response_size: turn.outputChars,
+        reasoning_size: turn.reasoningChars,
+      });
+    }
+    fallbackTurnIndex++;
+    turn = null;
+  };
+
+  const startTurn = (payload, timestampMs) => {
+    flushTurn();
+    turn = {
+      executionId:
+        typeof payload?.executionId === "string" ? payload.executionId : null,
+      timestampMs:
+        Number.isFinite(timestampMs)
+          ? timestampMs
+          : pendingUserTimestampMs,
+      inputChars: pendingUserChars,
+      outputChars: 0,
+      reasoningChars: 0,
+      modelId: null,
+      messageIds: new Set(),
+    };
+    pendingUserChars = 0;
+    pendingUserTimestampMs = NaN;
+  };
+
+  try {
+    for await (const line of rl) {
+      if (!line || !line.trim()) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const payload = event?.payload;
+      if (!payload || typeof payload !== "object") continue;
+      const type =
+        typeof payload.type === "string"
+          ? payload.type.toLowerCase()
+          : "";
+      const timestampMs = Date.parse(event.timestamp || "");
+
+      if (type === "user") {
+        if (turn) flushTurn();
+        pendingUserChars = kiroCliV2ContentChars(payload.content);
+        pendingUserTimestampMs = timestampMs;
+        continue;
+      }
+
+      if (type === "turn_start") {
+        startTurn(payload, timestampMs);
+        continue;
+      }
+
+      if (
+        ["assistant", "tool_call", "tool_result", "usage_summary"].includes(
+          type,
+        ) &&
+        !turn
+      ) {
+        startTurn(payload, timestampMs);
+      }
+      if (!turn) continue;
+
+      if (
+        typeof payload.executionId === "string" &&
+        payload.executionId &&
+        !turn.executionId
+      ) {
+        turn.executionId = payload.executionId;
+      }
+      if (typeof event.id === "string" && event.id) {
+        turn.messageIds.add(event.id);
+      }
+
+      if (type === "assistant") {
+        const chars = kiroCliV2ContentChars(payload.content);
+        if (
+          typeof payload.operationType === "string" &&
+          payload.operationType.toLowerCase() === "reasoning"
+        ) {
+          turn.reasoningChars += chars;
+        } else {
+          turn.outputChars += chars;
+        }
+        if (
+          typeof payload.reasoningModelId === "string" &&
+          payload.reasoningModelId
+        ) {
+          turn.modelId = payload.reasoningModelId;
+        }
+      } else if (type === "turn_end") {
+        flushTurn();
+      }
+    }
+  } catch {
+    // Return complete turns parsed before a concurrent truncate/delete.
+  }
+  flushTurn();
+  return flat;
+}
+
 // Canonicalize a Kiro-CLI-emitted model id so IDE and CLI rows collapse when
 // they refer to the same underlying Bedrock model. Examples:
 //   anthropic.claude-sonnet-4-20250514-v1:0  -> claude-sonnet-4
@@ -5202,6 +5434,7 @@ function canonicalizeKiroCliModelId(raw) {
   if (!name) return null;
   name = name.toLowerCase();
   if (name === "auto") return null;
+  name = name.replace(/^(?:qdev|kiro)::/, "");
   // Strip provider prefix (anthropic., aws., openai., or a full Bedrock ARN).
   name = name.replace(
     /^(?:arn:aws:bedrock:[^:]*:[^:]*:(?:foundation-model\/)?|anthropic\.|openai\.|aws\.)/,
@@ -5294,10 +5527,11 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
   const resolvedEnv = env || process.env;
   const dbPath = resolveKiroCliDbPath(resolvedEnv);
 
-  // Combine two sources under the same (source='kiro', cursors.kiroCli)
-  // namespace: historical rows from the SQLite DB plus live session state
-  // from ~/.kiro/sessions/cli/{uuid}.json (covers turns from a running
-  // session that hasn't flushed to SQLite yet). Request ID shapes differ:
+  // Combine three sources under the same (source='kiro', cursors.kiroCli)
+  // namespace: historical rows from the SQLite DB, legacy live session state
+  // from ~/.kiro/sessions/cli/{uuid}.json, and Kiro CLI 2.13+ event logs at
+  // ~/.kiro/sessions/<workspaceHash>/sess_<uuid>/messages.jsonl. Request ID
+  // shapes differ:
   // SQLite carries a persisted request_id UUID; session files synthesize
   // `${sessionId}:${loop_id.rand}`. When kiro-cli migrates a live session
   // into SQLite the same turn lands under a new request_id — the cross-
@@ -5309,8 +5543,11 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
     : [];
   const sessionFilesList = resolveKiroCliSessionFiles(resolvedEnv);
   let flatSessions = [];
-  for (const jsonPath of sessionFilesList) {
-    const turns = await readKiroCliSessionTurns(jsonPath);
+  for (const sessionPath of sessionFilesList) {
+    const turns =
+      path.basename(sessionPath) === "messages.jsonl"
+        ? await readKiroCliV2SessionTurns(sessionPath)
+        : await readKiroCliSessionTurns(sessionPath);
     for (const turn of turns) flatSessions.push(turn);
   }
   // Per-request state replaces the old seenIds set. Each entry captures
@@ -5382,7 +5619,14 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
       toRetract.push([reqId, prev, sid]);
     }
     for (const [reqId, prev, sid] of toRetract) {
-      if (prev.input_tokens || prev.output_tokens) {
+      if (
+        prev.input_tokens ||
+        prev.output_tokens ||
+        prev.reasoning_output_tokens
+      ) {
+        const prevReasoning = toNonNegativeInt(
+          prev.reasoning_output_tokens,
+        );
         const prevBucket = getHourlyBucket(
           hourlyState,
           "kiro",
@@ -5394,8 +5638,12 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
           cached_input_tokens: 0,
           cache_creation_input_tokens: 0,
           output_tokens: -prev.output_tokens,
-          reasoning_output_tokens: 0,
-          total_tokens: -(prev.input_tokens + prev.output_tokens),
+          reasoning_output_tokens: -prevReasoning,
+          total_tokens: -(
+            prev.input_tokens +
+            prev.output_tokens +
+            prevReasoning
+          ),
           conversation_count: -1,
         });
         touchedBuckets.add(bucketKey("kiro", prev.model, prev.bucketStart));
@@ -5488,8 +5736,12 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
 
     const promptChars = toNonNegativeInt(r.user_prompt_length);
     const responseChars = toNonNegativeInt(r.response_size);
+    const reasoningChars = toNonNegativeInt(r.reasoning_size);
     const approxInput = Math.floor(promptChars / KIRO_CLI_CHARS_PER_TOKEN);
     const approxOutput = Math.floor(responseChars / KIRO_CLI_CHARS_PER_TOKEN);
+    const approxReasoning = Math.floor(
+      reasoningChars / KIRO_CLI_CHARS_PER_TOKEN,
+    );
 
     const tsMs = Number(r.request_start_timestamp_ms);
     if (!Number.isFinite(tsMs) || tsMs <= 0) continue;
@@ -5502,37 +5754,52 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
     const model = canonical || "kiro-cli-agent";
 
     // Fingerprint captures every field whose change should cause a re-bucket.
-    const fingerprint = `${promptChars}:${responseChars}:${model}:${tsMs}`;
+    const fingerprint =
+      `${promptChars}:${responseChars}:${reasoningChars}:${model}:${tsMs}`;
     const prev = requestState[requestId];
     if (prev && prev.fingerprint === fingerprint) continue; // unchanged
 
     // Subtract the prior contribution (if any) from its prior bucket so the
     // bucket's absolute totals reflect the CURRENT truth, not the historical
     // truth. enqueueTouchedBuckets will emit the net delta at flush time.
-    if (prev && (prev.input_tokens || prev.output_tokens)) {
+    if (
+      prev &&
+      (
+        prev.input_tokens ||
+        prev.output_tokens ||
+        prev.reasoning_output_tokens
+      )
+    ) {
+      const prevReasoning = toNonNegativeInt(
+        prev.reasoning_output_tokens,
+      );
       const prevBucket = getHourlyBucket(hourlyState, "kiro", prev.model, prev.bucketStart);
       addTotals(prevBucket.totals, {
         input_tokens: -prev.input_tokens,
         cached_input_tokens: 0,
         cache_creation_input_tokens: 0,
         output_tokens: -prev.output_tokens,
-        reasoning_output_tokens: 0,
-        total_tokens: -(prev.input_tokens + prev.output_tokens),
+        reasoning_output_tokens: -prevReasoning,
+        total_tokens: -(
+          prev.input_tokens +
+          prev.output_tokens +
+          prevReasoning
+        ),
         conversation_count: -1,
       });
       touchedBuckets.add(bucketKey("kiro", prev.model, prev.bucketStart));
     }
 
     // Add the new contribution.
-    if (approxInput > 0 || approxOutput > 0) {
+    if (approxInput > 0 || approxOutput > 0 || approxReasoning > 0) {
       const bucket = getHourlyBucket(hourlyState, "kiro", model, bucketStart);
       addTotals(bucket.totals, {
         input_tokens: approxInput,
         cached_input_tokens: 0,
         cache_creation_input_tokens: 0,
         output_tokens: approxOutput,
-        reasoning_output_tokens: 0,
-        total_tokens: approxInput + approxOutput,
+        reasoning_output_tokens: approxReasoning,
+        total_tokens: approxInput + approxOutput + approxReasoning,
         conversation_count: 1,
       });
       touchedBuckets.add(bucketKey("kiro", model, bucketStart));
@@ -5551,6 +5818,7 @@ async function parseKiroCliIncremental({ sessionFiles, cursors, queuePath, onPro
       model,
       input_tokens: approxInput,
       output_tokens: approxOutput,
+      reasoning_output_tokens: approxReasoning,
       ...(r.session_id ? { session_id: r.session_id } : {}),
     };
 
@@ -6204,7 +6472,7 @@ async function parseKimiCodeIncremental({ wireFiles, cursors, queuePath, onProgr
 // each sync (passive scan only, same shape as Kimi's wire.jsonl reader).
 //
 // Per-line record types: message, reasoning, topic, file-history-snapshot.
-// Only `type=="message" && role=="assistant"` carry token usage. The shape:
+// Only `type=="message" and role=="assistant"` carry token usage. The shape:
 //
 //   providerData.rawUsage = {
 //     prompt_tokens: 22223,           // OpenAI-style — INCLUDES cached
@@ -6734,7 +7002,7 @@ async function parseCodebuddyIncremental({
 // (each verified against real ~/.workbuddy logs, NOT assumed from CodeBuddy):
 //
 //   1. Usage lives on `function_call` records too — not only on
-//      `type=="message" && role=="assistant"`. Each LLM round-trip (whether it
+//      `type=="message" and role=="assistant"`. Each LLM round-trip (whether it
 //      ends in a tool call or a text reply) carries its own providerData.rawUsage.
 //      We therefore aggregate EVERY record that has providerData.rawUsage and
 //      dedup per response id, instead of filtering by record type.
@@ -12387,7 +12655,8 @@ async function parseCopilotAppDbIncremental({
 // ─────────────────────────────────────────────────────────────────────────────
 
 const GROK_ESTIMATED_INPUT_RATIO = 0.8;
-const GROK_CURSOR_VERSION = 3;
+// v4: bill from turn_completed.usage (true cumulative API usage), not context-window totalTokens.
+const GROK_CURSOR_VERSION = 4;
 
 function resolveGrokBuildHome(env = process.env) {
   if (env.TOKENTRACKER_GROK_HOME) return env.TOKENTRACKER_GROK_HOME;
@@ -12540,6 +12809,9 @@ function grokMessageCountFromSignals(signals) {
   );
 }
 
+// Context-window telemetry only. Prefer turn_completed.usage when available —
+// signals.totalTokens / contextTokensUsed track the live window, not billable
+// cumulative spend across a session (especially after compaction).
 function grokEffectiveTotalFromSignals(signals) {
   if (!signals || typeof signals !== "object") return 0;
   const beforeCompaction = normalizeNonNegativeNumber(signals.totalTokensBeforeCompaction);
@@ -12612,28 +12884,135 @@ function grokFileEndsWithNewline(filePath, size) {
   }
 }
 
-async function readGrokUpdateTokenEvents(updatesPath, fallbackTimestamp, prevOffsetEntry) {
-  if (!updatesPath) return { events: [], offsetEntry: null };
+
+function canonicalizeGrokUsageModel(model) {
+  const raw = normalizeModelInput(model) || "grok-build";
+  const lower = raw.toLowerCase();
+  // Free Build SKU must not fuzzy-match paid grok-4.5 rates in native clients.
+  if (lower.includes("build-free") || lower.endsWith("-free") || lower.includes("free-tier")) {
+    return "grok-build-free";
+  }
+  if (lower === "grok-4.5-build" || lower === "grok-4-5-build") {
+    return "grok-4.5-build";
+  }
+  return raw;
+}
+
+function normalizeGrokTurnUsage(usage, model, timestamp, eventId) {
+  if (!usage || typeof usage !== "object") return null;
+  const inputRaw = normalizeNonNegativeNumber(
+    usage.inputTokens ?? usage.input_tokens,
+  );
+  const output = normalizeNonNegativeNumber(
+    usage.outputTokens ?? usage.output_tokens,
+  );
+  const cached = normalizeNonNegativeNumber(
+    usage.cachedReadTokens ??
+      usage.cache_read_input_tokens ??
+      usage.cached_input_tokens,
+  );
+  const reasoning = normalizeNonNegativeNumber(
+    usage.reasoningTokens ?? usage.reasoning_output_tokens,
+  );
+  // Grok reports inputTokens as the full prompt (including cache hits). Split
+  // so pricing can apply cache_read rates correctly.
+  const nonCachedInput = Math.max(0, inputRaw - cached);
+  let total = normalizeNonNegativeNumber(usage.totalTokens ?? usage.total_tokens);
+  if (total <= 0) {
+    total = inputRaw + output + reasoning;
+  }
+  if (total <= 0 && nonCachedInput <= 0 && cached <= 0 && output <= 0) return null;
+  return {
+    input_tokens: nonCachedInput,
+    cached_input_tokens: cached,
+    cache_creation_input_tokens: 0,
+    output_tokens: output,
+    reasoning_output_tokens: reasoning,
+    total_tokens: total > 0 ? total : nonCachedInput + cached + output + reasoning,
+    billable_total_tokens: total > 0 ? total : nonCachedInput + cached + output + reasoning,
+    conversation_count: 1,
+    model: canonicalizeGrokUsageModel(model),
+    timestamp,
+    eventId,
+  };
+}
+
+function extractGrokTurnUsageEvents(record, fallbackTimestamp, fallbackModel, lineIndex) {
+  const update = record?.params?.update;
+  if (!update || typeof update !== "object") return [];
+  if (update.sessionUpdate !== "turn_completed") return [];
+  const usage = update.usage;
+  if (!usage || typeof usage !== "object") return [];
+
+  const meta = record?.params?._meta || record?._meta || {};
+  const timestamp = grokTimestampFromUpdate(meta, record, fallbackTimestamp);
+  const baseEventId = grokEventId(
+    meta.eventId ?? record?.eventId ?? record?.id ?? update.prompt_id,
+    String(lineIndex),
+  );
+
+  const modelUsage =
+    usage.modelUsage && typeof usage.modelUsage === "object" ? usage.modelUsage : null;
+  const events = [];
+  if (modelUsage && Object.keys(modelUsage).length > 0) {
+    for (const [modelName, modelUsageEntry] of Object.entries(modelUsage)) {
+      if (!modelUsageEntry || typeof modelUsageEntry !== "object") continue;
+      const event = normalizeGrokTurnUsage(
+        modelUsageEntry,
+        modelName,
+        timestamp,
+        `${baseEventId}|${modelName}`,
+      );
+      if (event) events.push(event);
+    }
+  }
+  if (events.length === 0) {
+    const event = normalizeGrokTurnUsage(usage, fallbackModel, timestamp, baseEventId);
+    if (event) events.push(event);
+  }
+  return events;
+}
+
+// Context-window watermark events (legacy / fallback only).
+function extractGrokContextTokenEvent(record, fallbackTimestamp, lineIndex) {
+  const meta = record?.params?._meta || record?._meta;
+  if (!meta || typeof meta !== "object") return null;
+  const totalTokens = normalizeNonNegativeNumber(meta.totalTokens);
+  if (totalTokens <= 0) return null;
+  return {
+    totalTokens,
+    timestamp: grokTimestampFromUpdate(meta, record, fallbackTimestamp),
+    eventId: grokEventId(meta.eventId ?? record?.eventId ?? record?.id, String(lineIndex)),
+  };
+}
+
+async function readGrokUpdateTokenEvents(updatesPath, fallbackTimestamp, prevOffsetEntry, options = {}) {
+  const fallbackModel = options.fallbackModel || "grok-build";
+  if (!updatesPath) {
+    return { turnEvents: [], contextEvents: [], offsetEntry: null };
+  }
   let stat;
   try {
     stat = fssync.statSync(updatesPath);
-    if (!stat.isFile()) return { events: [], offsetEntry: null };
+    if (!stat.isFile()) return { turnEvents: [], contextEvents: [], offsetEntry: null };
   } catch {
-    return { events: [], offsetEntry: null };
+    return { turnEvents: [], contextEvents: [], offsetEntry: null };
   }
 
-  // updates.jsonl is append-only and carries cumulative totalTokens, deduped
-  // by the session high-watermark, so resuming from the last consumed byte is
-  // safe: re-read events stay below the watermark (no double count), and any
-  // bytes a write race leaves unparsed are covered by the next event's
-  // cumulative total. Re-read from 0 on truncation or inode change.
+  // updates.jsonl is append-only. Turn usage is additive per turn_completed, so
+  // resuming from the last consumed byte is safe. Re-read from 0 on truncation
+  // or inode change.
   const prevSize = Number(prevOffsetEntry?.size) || 0;
   const prevIno = prevOffsetEntry?.ino;
   const inodeChanged = typeof prevIno === "number" && prevIno !== stat.ino;
   const startOffset = stat.size < prevSize || inodeChanged ? 0 : prevSize;
   const baseOffset = { mtimeMs: stat.mtimeMs, ino: stat.ino };
   if (stat.size <= startOffset) {
-    return { events: [], offsetEntry: { size: startOffset, ...baseOffset } };
+    return {
+      turnEvents: [],
+      contextEvents: [],
+      offsetEntry: { size: startOffset, ...baseOffset },
+    };
   }
 
   // Only advance the stored offset to the end of the last newline-terminated
@@ -12642,7 +13021,8 @@ async function readGrokUpdateTokenEvents(updatesPath, fallbackTimestamp, prevOff
   // complete instead of skipping it forever (which would undercount tokens).
   const endsWithNewline = grokFileEndsWithNewline(updatesPath, stat.size);
 
-  const events = [];
+  const turnEvents = [];
+  const contextEvents = [];
   let lineIndex = 0;
   let lastLine = "";
   const input = fssync.createReadStream(updatesPath, {
@@ -12662,21 +13042,24 @@ async function readGrokUpdateTokenEvents(updatesPath, fallbackTimestamp, prevOff
       } catch {
         continue;
       }
-      const meta = record?.params?._meta || record?._meta;
-      if (!meta || typeof meta !== "object") continue;
-      const totalTokens = normalizeNonNegativeNumber(meta.totalTokens);
-      if (totalTokens <= 0) continue;
-      const timestamp = grokTimestampFromUpdate(meta, record, fallbackTimestamp);
-      events.push({
-        totalTokens,
-        timestamp,
-        eventId: grokEventId(meta.eventId ?? record?.eventId ?? record?.id, String(lineIndex)),
-      });
+      const turns = extractGrokTurnUsageEvents(
+        record,
+        fallbackTimestamp,
+        fallbackModel,
+        lineIndex,
+      );
+      if (turns.length > 0) {
+        turnEvents.push(...turns);
+        continue;
+      }
+      const contextEvent = extractGrokContextTokenEvent(record, fallbackTimestamp, lineIndex);
+      if (contextEvent) contextEvents.push(contextEvent);
     }
   } catch {
-    // Stream error mid-read: keep the events we got, but do not advance the
-    // offset so the next sync retries the same range (watermark-safe).
-    return { events, offsetEntry: prevOffsetEntry || null };
+    // Stream error mid-read: discard partial events and do not advance the
+    // offset, so the next sync re-extracts from the same range exactly once
+    // instead of double-counting already-parsed turn events.
+    return { turnEvents: [], contextEvents: [], offsetEntry: prevOffsetEntry || null };
   }
 
   // When the file does not end on a newline, the final emitted line is a
@@ -12684,7 +13067,11 @@ async function readGrokUpdateTokenEvents(updatesPath, fallbackTimestamp, prevOff
   // stays on a complete-line boundary and the line is re-read once finished.
   const trailingPartialBytes = endsWithNewline ? 0 : Buffer.byteLength(lastLine, "utf8");
   const committedSize = Math.max(startOffset, stat.size - trailingPartialBytes);
-  return { events, offsetEntry: { size: committedSize, ...baseOffset } };
+  return {
+    turnEvents,
+    contextEvents,
+    offsetEntry: { size: committedSize, ...baseOffset },
+  };
 }
 
 function estimateGrokTokenDelta(totalTokens, conversationCount, options = {}) {
@@ -12706,6 +13093,70 @@ function estimateGrokTokenDelta(totalTokens, conversationCount, options = {}) {
   };
 }
 
+function clearGrokHourlyBuckets(hourlyState) {
+  if (!hourlyState || typeof hourlyState !== "object") return;
+  const buckets = hourlyState.buckets && typeof hourlyState.buckets === "object" ? hourlyState.buckets : null;
+  if (buckets) {
+    for (const key of Object.keys(buckets)) {
+      if (key.startsWith("grok|")) delete buckets[key];
+    }
+  }
+  const groupQueued =
+    hourlyState.groupQueued && typeof hourlyState.groupQueued === "object"
+      ? hourlyState.groupQueued
+      : null;
+  if (groupQueued) {
+    for (const key of Object.keys(groupQueued)) {
+      if (key.startsWith("grok|")) delete groupQueued[key];
+    }
+  }
+}
+
+async function retractStaleGrokQueueRows(queuePath, keepKeys) {
+  if (!queuePath) return 0;
+  let raw = "";
+  try {
+    raw = fssync.readFileSync(queuePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return 0;
+    throw error;
+  }
+
+  const latestGrok = new Map();
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if ((row?.source || "") !== "grok") continue;
+    const model = normalizeModelInput(row.model) || DEFAULT_MODEL;
+    const hourStart = typeof row.hour_start === "string" ? row.hour_start : null;
+    if (!hourStart) continue;
+    latestGrok.set(bucketKey("grok", model, hourStart), { model, hour_start: hourStart, row });
+  }
+
+  const zero = initTotals();
+  const lines = [];
+  for (const [key, entry] of latestGrok.entries()) {
+    if (keepKeys.has(key)) continue;
+    if (totalsKey(entry.row) === totalsKey(zero)) continue;
+    lines.push(
+      JSON.stringify({
+        source: "grok",
+        model: entry.model,
+        hour_start: entry.hour_start,
+        ...zero,
+      }),
+    );
+  }
+  if (lines.length === 0) return 0;
+  await fs.appendFile(queuePath, `${lines.join("\n")}\n`, "utf8");
+  return lines.length;
+}
+
 async function parseGrokBuildIncremental({
   sessions,
   cursors = {},
@@ -12716,11 +13167,44 @@ async function parseGrokBuildIncremental({
   if (queuePath) await ensureDir(path.dirname(queuePath));
   const hourlyState = normalizeHourlyState(cursors?.hourly);
   const grokState = cursors.grok && typeof cursors.grok === "object" ? { ...cursors.grok } : {};
-  let sessionSnapshots = normalizeGrokSessionSnapshots(grokState);
+  const prevVersion = Number(grokState.version) || 0;
+  const needsTurnUsageMigration = prevVersion < GROK_CURSOR_VERSION;
+
+  // v3 and earlier treated context-window totalTokens as cumulative spend, which
+  // undercounts heavily (often 10-50x) and mis-splits input/output. Rebuild from
+  // turn_completed.usage when migrating to v4.
+  //
+  // Drop prior watermark totals / updateOffsets so files are re-read from byte 0,
+  // but keep legacySeen markers from seenSessions so the one-shot baseline
+  // (sessions already counted under the old scanner) still applies.
+  let sessionSnapshots;
+  if (needsTurnUsageMigration) {
+    const normalized = normalizeGrokSessionSnapshots(grokState);
+    sessionSnapshots = {};
+    for (const [sessionId, snapshot] of Object.entries(normalized)) {
+      if (!snapshot?.legacySeen) continue;
+      sessionSnapshots[sessionId] = {
+        totalTokens: 0,
+        messageCount: 0,
+        model: null,
+        source: null,
+        lastEventId: null,
+        lastEventTimestamp: null,
+        updatedAt: snapshot.updatedAt || null,
+        legacySeen: true,
+      };
+    }
+    clearGrokHourlyBuckets(hourlyState);
+  } else {
+    sessionSnapshots = normalizeGrokSessionSnapshots(grokState);
+  }
   const prevUpdateOffsets =
-    grokState.updateOffsets && typeof grokState.updateOffsets === "object"
+    !needsTurnUsageMigration &&
+    grokState.updateOffsets &&
+    typeof grokState.updateOffsets === "object"
       ? grokState.updateOffsets
       : {};
+
   // Rebuilt from the sessions seen this scan, so entries for deleted session
   // dirs are pruned and the cursor stays bounded by the on-disk session count.
   const updateOffsets = {};
@@ -12755,83 +13239,142 @@ async function parseGrokBuildIncremental({
     const model = grokModelFromSignals(safeSignals);
     const lastActive = grokLastActiveFromSignals(safeSignals, summary);
 
-    let highWatermark = previousTotal;
-    let observedTotal = previousTotal;
+    let cumulativeTotal = previousTotal;
     let tokenDeltaForSession = 0;
     let finalTouchedHourStart = null;
     let source = previous.source || null;
     let lastEventId = previous.lastEventId || null;
     let lastEventTimestamp = previous.lastEventTimestamp || null;
-    const pendingTokenDeltas = [];
-
-    const recordTokenDelta = (deltaTokens, timestamp, deltaSource) => {
-      const hourStartStr = toUtcHalfHourStart(timestamp) || toUtcHalfHourStart(Date.now());
-      if (!hourStartStr) return false;
-      pendingTokenDeltas.push({ deltaTokens, hourStartStr });
-      tokenDeltaForSession += deltaTokens;
-      finalTouchedHourStart = hourStartStr;
-      source = deltaSource;
-      lastEventTimestamp = timestamp || lastEventTimestamp;
-      return true;
-    };
+    let lastModel = previous.model || model;
+    let sawTurnUsage = source === "turn_usage" || previous.source === "turn_usage";
+    // Defer bucket writes until after we know whether this is a legacy baseline
+    // pass (first sighting of a session already counted under an older scanner).
+    const pendingBucketDeltas = [];
 
     const updatesPath = grokUpdatesPathForSession(sess);
     const updates = await readGrokUpdateTokenEvents(
       updatesPath,
       lastActive,
       updatesPath ? prevUpdateOffsets[updatesPath] : null,
+      { fallbackModel: model },
     );
     if (updatesPath && updates.offsetEntry) {
       updateOffsets[updatesPath] = updates.offsetEntry;
     }
-    for (const event of updates.events) {
-      observedTotal = Math.max(observedTotal, event.totalTokens);
+
+    // Preferred path: each turn_completed carries true cumulative API usage for
+    // that turn (input/output/cache/reasoning). Sum them.
+    for (const event of updates.turnEvents) {
+      sawTurnUsage = true;
+      const hourStartStr = toUtcHalfHourStart(event.timestamp) || toUtcHalfHourStart(lastActive) || toUtcHalfHourStart(Date.now());
+      if (!hourStartStr) continue;
+      const eventModel = event.model || model;
+      const delta = {
+        input_tokens: event.input_tokens,
+        cached_input_tokens: event.cached_input_tokens,
+        cache_creation_input_tokens: event.cache_creation_input_tokens,
+        output_tokens: event.output_tokens,
+        reasoning_output_tokens: event.reasoning_output_tokens,
+        total_tokens: event.total_tokens,
+        billable_total_tokens: event.billable_total_tokens,
+        conversation_count: event.conversation_count || 1,
+      };
+      pendingBucketDeltas.push({ model: eventModel, hourStartStr, delta });
+      cumulativeTotal += event.total_tokens;
+      tokenDeltaForSession += event.total_tokens;
+      finalTouchedHourStart = hourStartStr;
+      source = "turn_usage";
       lastEventId = event.eventId || lastEventId;
       lastEventTimestamp = event.timestamp || lastEventTimestamp;
-      if (event.totalTokens <= highWatermark) continue;
-      const deltaTokens = event.totalTokens - highWatermark;
-      highWatermark = event.totalTokens;
-      recordTokenDelta(deltaTokens, event.timestamp || lastActive, "updates");
-    }
+      lastModel = eventModel;
+    }
+
+    // Fallback only when this session never emitted turn_completed usage
+    // (older logs / partial sessions). Context watermark is a lower-bound
+    // estimate and must not run on top of turn usage.
+    if (!sawTurnUsage) {
+      let highWatermark = previousTotal;
+      for (const event of updates.contextEvents) {
+        lastEventId = event.eventId || lastEventId;
+        lastEventTimestamp = event.timestamp || lastEventTimestamp;
+        if (event.totalTokens <= highWatermark) continue;
+        const deltaTokens = event.totalTokens - highWatermark;
+        highWatermark = event.totalTokens;
+        const hourStartStr =
+          toUtcHalfHourStart(event.timestamp) ||
+          toUtcHalfHourStart(lastActive) ||
+          toUtcHalfHourStart(Date.now());
+        if (!hourStartStr) continue;
+        const delta = estimateGrokTokenDelta(deltaTokens, 0, { allowZeroConversationCount: true });
+        pendingBucketDeltas.push({ model, hourStartStr, delta });
+        tokenDeltaForSession += deltaTokens;
+        finalTouchedHourStart = hourStartStr;
+        source = "updates";
+      }
 
-    const effectiveSignalTotal = grokEffectiveTotalFromSignals(safeSignals);
-    observedTotal = Math.max(observedTotal, effectiveSignalTotal);
-    if (effectiveSignalTotal > highWatermark) {
-      const deltaTokens = effectiveSignalTotal - highWatermark;
-      highWatermark = effectiveSignalTotal;
-      recordTokenDelta(deltaTokens, lastActive, "signals");
+      const effectiveSignalTotal = grokEffectiveTotalFromSignals(safeSignals);
+      if (effectiveSignalTotal > highWatermark) {
+        const deltaTokens = effectiveSignalTotal - highWatermark;
+        highWatermark = effectiveSignalTotal;
+        const hourStartStr = toUtcHalfHourStart(lastActive) || toUtcHalfHourStart(Date.now());
+        if (hourStartStr) {
+          const delta = estimateGrokTokenDelta(deltaTokens, 0, { allowZeroConversationCount: true });
+          pendingBucketDeltas.push({ model, hourStartStr, delta });
+          tokenDeltaForSession += deltaTokens;
+          finalTouchedHourStart = hourStartStr;
+          source = "signals";
+        }
+      }
+      cumulativeTotal = Math.max(previousTotal, highWatermark);
     }
 
-    const finalTotal = Math.max(previousTotal, highWatermark, observedTotal);
+    const finalTotal = Math.max(previousTotal, cumulativeTotal);
+    // Sessions already observed under an older scanner must establish a watermark
+    // without backfilling historical tokens as brand-new usage.
     const legacyBaselineOnly = previous.legacySeen && previousTotal === 0 && finalTotal > 0;
+
     if (!legacyBaselineOnly) {
-      for (const pending of pendingTokenDeltas) {
-        const delta = estimateGrokTokenDelta(pending.deltaTokens, 0, { allowZeroConversationCount: true });
-        const bucket = getHourlyBucket(hourlyState, "grok", model, pending.hourStartStr);
-        addTotals(bucket.totals, delta);
-        touchedBuckets.add(bucketKey("grok", model, pending.hourStartStr));
+      for (const pending of pendingBucketDeltas) {
+        const bucket = getHourlyBucket(hourlyState, "grok", pending.model, pending.hourStartStr);
+        addTotals(bucket.totals, pending.delta);
+        touchedBuckets.add(bucketKey("grok", pending.model, pending.hourStartStr));
         eventsAggregated++;
       }
-    }
 
-    if (!legacyBaselineOnly && tokenDeltaForSession > 0 && finalTouchedHourStart) {
-      const deltaMessageCount =
-        messageCount > previousMessageCount ? messageCount - previousMessageCount : 1;
-      const bucket = getHourlyBucket(hourlyState, "grok", model, finalTouchedHourStart);
-      addTotals(bucket.totals, { conversation_count: deltaMessageCount });
-      touchedBuckets.add(bucketKey("grok", model, finalTouchedHourStart));
+      // Message/conversation count for fallback-only sessions (turn path already
+      // counts each turn_completed as one conversation).
+      if (!sawTurnUsage && tokenDeltaForSession > 0 && finalTouchedHourStart) {
+        const deltaMessageCount =
+          messageCount > previousMessageCount ? messageCount - previousMessageCount : 1;
+        const bucket = getHourlyBucket(hourlyState, "grok", lastModel || model, finalTouchedHourStart);
+        addTotals(bucket.totals, { conversation_count: deltaMessageCount });
+        touchedBuckets.add(bucketKey("grok", lastModel || model, finalTouchedHourStart));
+      }
     }
 
     if (finalTotal > 0 && (tokenDeltaForSession > 0 || previousTotal > 0 || legacyBaselineOnly)) {
       sessionSnapshots[sessionId] = {
         totalTokens: finalTotal,
         messageCount: Math.max(previousMessageCount, messageCount),
-        model,
+        model: lastModel || model,
         source: source || previous.source || null,
         lastEventId,
         lastEventTimestamp,
         updatedAt: new Date().toISOString(),
       };
+    } else if (previous.legacySeen && finalTotal === 0) {
+      // Keep the baseline marker across empty syncs so later growth is still
+      // baselined once instead of backfilled as brand-new usage.
+      sessionSnapshots[sessionId] = {
+        totalTokens: 0,
+        messageCount: Math.max(previousMessageCount, messageCount),
+        model: lastModel || model,
+        source: previous.source || null,
+        lastEventId: lastEventId || previous.lastEventId || null,
+        lastEventTimestamp: lastEventTimestamp || previous.lastEventTimestamp || null,
+        updatedAt: new Date().toISOString(),
+        legacySeen: true,
+      };
     }
 
     if (onProgress) {
@@ -12839,19 +13382,45 @@ async function parseGrokBuildIncremental({
     }
   }
 
-  const bucketsQueued = queuePath
+  let bucketsQueued = queuePath
     ? await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets })
     : 0;
+
+  // After a semantics migration, retract stale grok queue keys that the full
+  // rescan no longer produces so dashboard "latest per key" no longer keeps
+  // the old undercounted rows.
+  if (needsTurnUsageMigration && queuePath) {
+    const keepKeys = new Set();
+    for (const [key, bucket] of Object.entries(hourlyState.buckets || {})) {
+      if (!key.startsWith("grok|") || !bucket?.totals) continue;
+      keepKeys.add(key);
+    }
+    const retracted = await retractStaleGrokQueueRows(queuePath, keepKeys);
+    bucketsQueued += retracted;
+  }
+
   hourlyState.updatedAt = new Date().toISOString();
   cursors.hourly = hourlyState;
   sessionSnapshots = capGrokSessionSnapshots(sessionSnapshots);
 
+  const migrations = grokState.migrations && typeof grokState.migrations === "object"
+    ? { ...grokState.migrations }
+    : {};
+  if (needsTurnUsageMigration) {
+    migrations.turnUsageV4 = {
+      appliedAt: new Date().toISOString(),
+      fromVersion: prevVersion,
+      toVersion: GROK_CURSOR_VERSION,
+    };
+  }
+
   cursors.grok = {
     ...grokState,
     version: GROK_CURSOR_VERSION,
     sessionSnapshots,
     seenSessions: Object.keys(sessionSnapshots),
     updateOffsets,
+    migrations,
     updatedAt: new Date().toISOString()
   };