tokentracker-cli 0.91.0 → 0.91.3

package/src/commands/status.js

@@ -89,6 +89,13 @@ const {
   resolveCopilotAppDbPaths,
   probeWslDistros,
 } = require("../lib/rollout");
+const {
+  TRAE_CN_USAGE_ENV,
+  isTraeCnUsageEnabled,
+  resolveTraeCnStoragePath,
+  readTraeCnAuthFromStorage,
+  extractTraeCnToken,
+} = require("../lib/trae-cn-config");
 const wsl = require("../lib/wsl-probe");
 const { getWslMode, isInvalidWslMode, shouldProbeWsl, discoverWslHome } = wsl;
 const { resolveInstallPaths, resolveZcodeNativeDbPath } = require("../lib/install-resolver");
@@ -642,6 +649,34 @@ async function cmdStatus(argv = []) {
     ? readTraeEntitlementFromStorage(traeStoragePath)
     : null;
 
+  // Trae SOLO CN — opt-in usage-API reader. Unlike the passive entitlement
+  // reader above, this source sends the locally stored sign-in JWT to TRAE's
+  // official API, so status surfaces the opt-in flag, the resolved storage
+  // path, and whether the auth blob decrypts — the three inputs a "why is my
+  // TRAE CN data missing" diagnosis needs.
+  // A resolvable default path does NOT mean the app is installed - the macOS
+  // resolver always derives one. Match the sync path semantics exactly:
+  // installed iff the storage file actually exists on disk.
+  const traeCnStoragePath = resolveTraeCnStoragePath({ env: process.env, home });
+  const traeCnInstalled = Boolean(
+    traeCnStoragePath && fssync.existsSync(traeCnStoragePath),
+  );
+  let traeCnAuthState = "not-signed-in";
+  if (traeCnInstalled) {
+    try {
+      const traeCnAuth = readTraeCnAuthFromStorage({ env: process.env, home, platform: process.platform });
+      if (traeCnAuth) {
+        extractTraeCnToken(traeCnAuth);
+        traeCnAuthState = "readable";
+      }
+    } catch (error) {
+      // Distinguish a real IO failure (unreadable) from present-but-bad
+      // data (malformed); neither ever carries storage contents.
+      traeCnAuthState = error?.code === "TRAE_CN_STORAGE_UNREADABLE" ? "unreadable" : "malformed";
+    }
+  }
+  const traeCnUsageOptIn = isTraeCnUsageEnabled(process.env);
+
   // Grok Build (xAI TUI)
   const grokHookState = await probeGrokHookState({ home, trackerDir, env: process.env });
   const grokSessions = grokHookState.hasGrokInstall || grokHookState.sessionsDir
@@ -933,6 +968,14 @@ async function cmdStatus(argv = []) {
               ...(traeEntitlement ? { entitlement: traeEntitlement } : {}),
             }
           : { installed: false },
+        "trae-cn": traeCnInstalled
+          ? {
+              installed: true,
+              detail: traeCnStoragePath,
+              auth: traeCnAuthState,
+              usage_opt_in: traeCnUsageOptIn,
+            }
+          : { installed: false },
         grok_build: grokInstalled
           ? {
               installed: true,
@@ -1105,6 +1148,9 @@ async function cmdStatus(argv = []) {
       traeEntitlement
         ? `- Trae SOLO plan: ${formatTraeEntitlementLine(traeEntitlement)}`
         : null,
+      traeCnInstalled
+        ? `- Trae SOLO CN: usage sync ${traeCnUsageOptIn ? "opted in" : `off (set ${TRAE_CN_USAGE_ENV}=1 to enable)`}, auth ${traeCnAuthState} (${traeCnStoragePath})`
+        : null,
       ...(() => {
         if (!hermesInstalled) return [];
         return [`- Hermes Agent: state.db found (${hermesPath})`];

package/src/commands/sync.js

@@ -112,6 +112,7 @@ const {
   resolveDroidModel,
   resolveDshSessionFiles,
   parseDshIncremental,
+  parseTraeCnApiIncremental,
   bucketKey,
   toUtcHalfHourStart,
   totalsKey,
@@ -134,6 +135,11 @@ const {
   parseCursorCsv,
 } = require("../lib/cursor-config");
 const { purgeProjectUsage } = require("../lib/project-usage-purge");
+const {
+  fetchTraeCnUsageWithAuth,
+  resolveTraeCnStoragePath,
+  isTraeCnUsageEnabled,
+} = require("../lib/trae-cn-config");
 const {
   isCodexSessionCursorPath,
   isCursorStoreRetry,
@@ -291,6 +297,7 @@ const AUTO_SYNC_SOURCES = new Set([
   "qoder-cn",
   "reasonix",
   "roocode",
+  "trae-cn",
   "workbuddy",
   "zcode",
   "zed",
@@ -452,6 +459,15 @@ async function cmdSync(argv, context = {}) {
   const lockWaitOptions = context && typeof context === "object"
     ? context.lockWaitOptions
     : undefined;
+  // Narrow test-only seam for TRAE Work CN: deterministic injected fetch + a
+  // fixed "now" for the rolling range. Production keeps the global fetch and
+  // current time; no public CLI flag/config is introduced.
+  const traeCnFetchImpl = context && typeof context === "object"
+    ? context.traeCnFetchImpl
+    : undefined;
+  const traeCnNowMs = context && typeof context === "object"
+    ? context.traeCnNowMs
+    : undefined;
   const syncDiagnostics = diagnostics && typeof diagnostics === "object" ? diagnostics : null;
   const home = os.homedir();
   const { trackerDir } = await resolveTrackerPaths({ home });
@@ -1663,6 +1679,93 @@ async function cmdSync(argv, context = {}) {
       }
     }
 
+    // ── Trae Work CN (国内版) — account-level usage API ──
+    // A simple explicit rolling 30-day window captured once per sync (no
+    // cursor checkpoints / full-history import / page retries / background
+    // requests). Runs only when the user has opted in via
+    // TOKENTRACKER_TRAE_CN_USAGE=1 (the read transmits the locally stored
+    // sign-in JWT to TRAE's official endpoint, so it is never default-on),
+    // the sync is non-lightweight, the source is allowed, and the CN storage
+    // file exists — which excludes both ordinary background and `--auto
+    // --background --all-local-sources`. Fetching goes through the
+    // storage-backed helper so its single 401/403 reread/retry is used; an
+    // empty response is a successful no-op; each window is bounded to 100
+    // pages/2,000 rows and an over-capacity window is split into staggered
+    // sub-windows (still over capacity at the finest allowed granularity, or
+    // any other fetch/page/schema/auth failure) skips the parser and leaves
+    // prior data untouched while unrelated providers continue.
+    let traeCnResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (
+      !isBackgroundLightweightSync &&
+      isTraeCnUsageEnabled(process.env) &&
+      sourceAllowed("trae-cn")
+    ) {
+      const nowMs = Number.isFinite(traeCnNowMs) ? traeCnNowMs : Date.now();
+      const fetchImpl = typeof traeCnFetchImpl === "function" ? traeCnFetchImpl : fetch;
+      const endTime = Math.floor(nowMs / 1000);
+      // Align the REAL fetch start down to a half-hour boundary so the API
+      // range fully contains every bucket it can touch (a raw 08:37 start
+      // would only partially cover the 08:30 bucket) - session bucket floors
+      // never straddle the queried range.
+      const HALF_HOUR_SEC = 30 * 60;
+      const startTime = Math.max(
+        1,
+        Math.floor((endTime - 30 * 24 * 60 * 60) / HALF_HOUR_SEC) * HALF_HOUR_SEC,
+      );
+      try {
+        // Absent storage means "not signed in" — a silent skip, not an error.
+        const traeCnStoragePath = resolveTraeCnStoragePath({ env: process.env, home });
+        if (traeCnStoragePath && fssync.existsSync(traeCnStoragePath)) {
+          if (progress?.enabled) {
+            progress.start(`Fetching TRAE Work CN usage...`);
+          }
+          const traeCnUsage = await fetchTraeCnUsageWithAuth({
+            start_time: startTime,
+            end_time: endTime,
+            fetchImpl,
+            env: process.env,
+            home,
+          });
+          const traeCnSessions = Array.isArray(traeCnUsage?.sessions) ? traeCnUsage.sessions : [];
+          // An empty payload parses as a pure no-op: the TRAE absence
+          // contract is NOT PROVEN (no evidence that a missing session means
+          // deleted/zero), so an empty response asserts nothing - no usage
+          // mutation and no session states. Non-empty snapshots append one
+          // canonical session-state observation per CHANGED session (the
+          // cloud LWW upsert reconciles cross-device versions).
+          {
+            if (progress?.enabled && traeCnSessions.length > 0) {
+              progress.start(
+                `Parsing TRAE Work CN ${renderBar(0)} 0/${formatNumber(
+                  traeCnSessions.length,
+                )} records | buckets 0`,
+              );
+            }
+            traeCnResult = await parseTraeCnApiIncremental({
+              sessions: traeCnSessions,
+              cursors,
+              queuePath,
+              onProgress: makeProviderProgress("TRAE Work CN"),
+              windowStartMs: startTime * 1000,
+              windowEndMs: endTime * 1000,
+              // The LOGICAL fetch stamp carried into every session state's
+              // snapshot_verified_at: the same clock that produced the query
+              // range, not the later enqueue moment (append-only queue
+              // replays it verbatim, so transport retries never fake
+              // freshness).
+              snapshotVerifiedAtMs: nowMs,
+            });
+            // A partially malformed snapshot throws inside the parser (fail
+            // closed - it must not become the authoritative window state);
+            // warnProviderParseFailure below reports it without sensitive
+            // data while unrelated providers continue.
+          }
+        }
+      } catch (err) {
+        warnProviderParseFailure("TRAE Work CN", err, opts);
+      }
+    }
+
     // ── Kiro (SQLite-based, with JSONL fallback; dual-install aware) ──
     let kiroResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (sourceAllowed("kiro")) {
@@ -2157,7 +2260,12 @@ async function cmdSync(argv, context = {}) {
     }
 
     // ── Grok Build (xAI) ──
-    let grokResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    let grokResult = {
+      recordsProcessed: 0,
+      eventsAggregated: 0,
+      bucketsQueued: 0,
+      projectBucketsQueued: 0,
+    };
     // Full passive scan of all Grok sessions (historical + any not covered by hook)
     const grokSessions = sourceAllowed("grok") ? resolveGrokBuildSessions(process.env) : [];
     const grokSessionInputs = [...grokSessions];
@@ -2179,6 +2287,11 @@ async function cmdSync(argv, context = {}) {
           sessionId: hookSessionId,
           sessionDir:
             typeof grokHookSignal.sessionDir === "string" ? grokHookSignal.sessionDir : undefined,
+          cwd: typeof grokHookSignal.cwd === "string" ? grokHookSignal.cwd : undefined,
+          encodedCwd:
+            typeof grokHookSignal.sessionDir === "string" && grokHookSignal.sessionDir
+              ? path.basename(path.dirname(grokHookSignal.sessionDir))
+              : undefined,
           updatesPath:
             typeof grokHookSignal.updatesPath === "string" ? grokHookSignal.updatesPath : undefined,
           signalsPath:
@@ -2208,6 +2321,7 @@ async function cmdSync(argv, context = {}) {
           sessions: grokSessionInputs,
           cursors,
           queuePath,
+          projectQueuePath,
           env: process.env,
           onProgress: (p) => {
             if (!progress?.enabled) return;
@@ -2224,6 +2338,8 @@ async function cmdSync(argv, context = {}) {
         recordsProcessed: grokResult.recordsProcessed + grokScanResult.recordsProcessed,
         eventsAggregated: grokResult.eventsAggregated + grokScanResult.eventsAggregated,
         bucketsQueued: grokResult.bucketsQueued + grokScanResult.bucketsQueued,
+        projectBucketsQueued:
+          (grokResult.projectBucketsQueued || 0) + (grokScanResult.projectBucketsQueued || 0),
       };
     }
     if (isFullSourceScan && opts.repairGrok) {
@@ -2584,6 +2700,7 @@ async function cmdSync(argv, context = {}) {
       qoderCnResult.recordsProcessed +
       claudeScienceResult.recordsProcessed +
       cursorResult.recordsProcessed +
+      traeCnResult.recordsProcessed +
       kiroResult.recordsProcessed +
       kiroCliResult.recordsProcessed +
       hermesResult.recordsProcessed +
@@ -2619,6 +2736,7 @@ async function cmdSync(argv, context = {}) {
       qoderCnResult.bucketsQueued +
       claudeScienceResult.bucketsQueued +
       cursorResult.bucketsQueued +
+      traeCnResult.bucketsQueued +
       kiroResult.bucketsQueued +
       kiroCliResult.bucketsQueued +
       hermesResult.bucketsQueued +
@@ -2650,6 +2768,7 @@ async function cmdSync(argv, context = {}) {
       cursorStore.requiresCommit !== true &&
       totalParsed === 0 &&
       totalBuckets === 0 &&
+      !(grokResult.projectBucketsQueued > 0) &&
       !codexColdAuditDue &&
       !codexFallbackRetryRan &&
       !grokHookSignalConsumed &&
@@ -2972,6 +3091,8 @@ function recordCodexColdScanAudit(
 module.exports = {
   cmdSync,
   acquireSyncLock,
+  readQueueBatch,
+  drainQueueToCloud,
   migrateCursorUnknownBuckets,
   migrateRolloutCumulativeDeltaBuckets,
   repairCodebuddyLogJsonlOverlap,
@@ -3472,7 +3593,10 @@ async function drainQueueToCloud({ baseUrl, deviceToken, queuePath, queueStatePa
   for (let batch = 0; batch < maxBatches; batch++) {
     if (offset >= queueSize) break;
     const result = await readQueueBatch(queuePath, offset, limit);
-    if (result.buckets.length === 0) break;
+    // A states-only tail (e.g. a retry batch whose bucket rows already
+    // uploaded) is still a meaningful upload: it advances the canonical
+    // session corrections cloud-side.
+    if (result.buckets.length === 0 && result.sessionStates.length === 0) break;
 
     const root = baseUrl.replace(/\/$/, "");
     const anonKey = process.env.TOKENTRACKER_INSFORGE_ANON_KEY || "";
@@ -3485,7 +3609,12 @@ async function drainQueueToCloud({ baseUrl, deviceToken, queuePath, queueStatePa
     const res = await fetch(`${root}/functions/${INGEST_SLUG}`, {
       method: "POST",
       headers,
-      body: JSON.stringify({ hourly: result.buckets }),
+      body: JSON.stringify({
+        hourly: result.buckets,
+        ...(result.sessionStates.length > 0
+          ? { account_session_states: result.sessionStates }
+          : {}),
+      }),
     });
 
     const rawText = await res.text().catch(() => "");
@@ -3522,6 +3651,26 @@ async function readQueueBatch(queuePath, startOffset, maxBuckets) {
   const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
 
   const bucketMap = new Map();
+  // Account session states (kind: "account_session_state") are queue
+  // control records, not usage rows: collect them separately so they ride
+  // the same upload (after the bucket rows in file order) without entering
+  // the bucket stream. Keyed by (source, session_id) LAST-WINS: the
+  // append-only queue writes a session's newer observation after its older
+  // one, and only the latest per session may reach the ingest batch (a
+  // duplicate would make the cloud ON CONFLICT affect one row twice).
+  // snapshot_verified_at rides along verbatim from the ORIGINAL fetch, so a
+  // transport retry never fakes logical freshness.
+  //
+  // Batching: session-state records count toward the SAME per-batch record
+  // cap (maxBuckets) as bucket rows. The ingest edge rejects a request with
+  // more than 500 states (HTTP 400); before they counted, a states-heavy
+  // queue (a fresh device's first 30-day TRAE sync appends one record per
+  // observed session) was read in ONE uncapped batch - the 400 left the
+  // queue offset untouched and every retry re-read the identical oversized
+  // request, a permanent upload failure. With the default batchSize of 200
+  // (and the MAX_INGEST_BUCKETS=500 clamp above), every request stays under
+  // the edge cap while batching follows the existing design.
+  const sessionStateMap = new Map();
   let offset = startOffset;
   let linesRead = 0;
   for await (const line of rl) {
@@ -3534,6 +3683,37 @@ async function readQueueBatch(queuePath, startOffset, maxBuckets) {
     } catch (_e) {
       continue;
     }
+    if (bucket?.kind === "account_session_state") {
+      if (typeof bucket.source === "string" && typeof bucket.session_id === "string" && bucket.session_id.trim()) {
+        const ssSource = bucket.source.trim().toLowerCase();
+        sessionStateMap.set(ssSource + "|" + bucket.session_id.trim(), {
+          source: ssSource,
+          session_id: bucket.session_id.trim(),
+          model: typeof bucket.model === "string" ? bucket.model : "",
+          bucket_start: typeof bucket.bucket_start === "string" ? bucket.bucket_start : "",
+          input_tokens: Number(bucket.input_tokens) || 0,
+          output_tokens: Number(bucket.output_tokens) || 0,
+          cached_input_tokens: Number(bucket.cached_input_tokens) || 0,
+          cache_creation_input_tokens: Number(bucket.cache_creation_input_tokens) || 0,
+          reasoning_output_tokens: Number(bucket.reasoning_output_tokens) || 0,
+          total_tokens: Number(bucket.total_tokens) || 0,
+          ...(typeof bucket.snapshot_verified_at === "string" && bucket.snapshot_verified_at
+            ? { snapshot_verified_at: bucket.snapshot_verified_at }
+            : {}),
+        });
+        // Counted like a bucket row: the record rides THIS batch and its
+        // bytes are covered by nextOffset, so the next batch resumes right
+        // after it.
+        linesRead += 1;
+        if (linesRead >= maxBuckets) break;
+      }
+      continue;
+    }
+    // Pre-release watermark records from this feature branch's dev queues
+    // are obsolete control records: drop them instead of letting them enter
+    // the bucket stream (they carry no hour_start and would be skipped
+    // downstream anyway, but be explicit).
+    if (bucket?.kind === "account_sync_watermark") continue;
     const hourStart = typeof bucket?.hour_start === "string" ? bucket.hour_start : null;
     if (!hourStart) continue;
     const source = (typeof bucket?.source === "string" ? bucket.source.trim().toLowerCase() : "") || "codex";
@@ -3553,7 +3733,11 @@ async function readQueueBatch(queuePath, startOffset, maxBuckets) {
 
   rl.close();
   stream.close?.();
-  return { buckets: Array.from(bucketMap.values()), nextOffset: offset };
+  return {
+    buckets: Array.from(bucketMap.values()),
+    sessionStates: Array.from(sessionStateMap.values()),
+    nextOffset: offset,
+  };
 }
 
 function normalizeGrokRepairSource(value) {

package/src/lib/account-usage-dedup.js

@@ -0,0 +1,267 @@
+"use strict";
+
+/**
+ * Account-level cross-device truth - JS reference implementation.
+ *
+ * Account-level sources (ACCOUNT_LEVEL_SOURCES in src/lib/source-metadata.js)
+ * come from a per-ACCOUNT cloud API, so every device that syncs them stores
+ * its own copy of the SAME account data. How to dedup depends on the source:
+ *
+ *   - 'cursor' has NO stable session identity: its rows are identical across
+ *     devices, so the legacy whole-row MAX pick per (hour, source, model)
+ *     dedups them (dedupeAccountLevelRows below).
+ *   - 'trae-cn' is a CORRECTABLE snapshot: totals can be revised down, a
+ *     session can move to another model or another half-hour. Hour-level
+ *     dedup CANNOT express that (a fresh device's first data bucket cannot
+ *     safely displace earlier hours - that would need an unproven "absent =
+ *     deleted" contract - and a 10:00 -> 10:30 bucket migration strands the
+ *     old hour). Canonical truth for trae-cn therefore lives at the SESSION
+ *     level (tokentracker_account_session_states; migrations/
+ *     20260817120000_account-session-states.sql): identity is
+ *     (user_id, source, session_id) - device_id is NOT identity (the usage
+ *     API request carries no device discriminator). Session-id evidence
+ *     (2026-08-17): repeated-fetch stability VERIFIED, cross-window
+ *     stability VERIFIED; cross-device same-account stability NOT DIRECTLY
+ *     VERIFIED (no second independent device/auth experiment). Every
+ *     observation of one
+ *     session whole-row-replaces the previous state under a strict LWW
+ *     guard, so the three correction classes collapse into ONE operation:
+ *
+ *     downward  S tokens 100 -> 60        replaced, total 60
+ *     model     S model A -> B            replaced, only B remains
+ *     bucket    S bucket 10:00 -> 10:30   replaced, only 10:30 remains
+ *
+ * ABSENCE is NOT PROVEN to mean deletion, so nothing ever deletes a session
+ * row: a session missing from a non-empty snapshot asserts nothing, and an
+ * empty snapshot asserts nothing at all.
+ *
+ * Freshness: the TRAE API exposes no provider-side ordering signal (probed
+ * 2026-08-17: headers carry only CDN trace ids, rows carry no revision), so
+ * snapshot_verified_at is the CLIENT logical fetch stamp (best-effort
+ * cross-device ordering under clock skew - documented residual risk, NOT
+ * strict correctness). It is stamped once per real fetch and replayed
+ * verbatim by the append-only queue; the LWW guard applies strictly newer
+ * (>) stamps only, so retries are idempotent and a re-delivered older
+ * observation cannot displace a newer one. Equal stamps keep the
+ * first-applied row (stable under retries).
+ *
+ * This module is the executable specification of that semantics; the
+ * deployed SQL (migrations/20260817120000_account-session-states.sql upsert,
+ * scripts/ops/account-usage-grouped-rpc.sql + leaderboard_hourly_dedup_v2
+ * aggregation branches) implements the same algorithm and MUST stay in sync
+ * - test/account-usage-dedup.test.js pins both.
+ */
+
+// Queue record kind the TRAE CN parser emits for one changed session's
+// canonical observation (src/lib/rollout.js appendTraeCnSessionStates).
+const SESSION_STATE_KIND = "account_session_state";
+
+function parseMs(value) {
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+// Token columns that make up a canonical session state row (the SQL table's
+// non-key, non-metadata columns).
+const TOKEN_COLUMNS = [
+  "input_tokens",
+  "output_tokens",
+  "cached_input_tokens",
+  "cache_creation_input_tokens",
+  "reasoning_output_tokens",
+  "total_tokens",
+];
+
+function normalizeStateRow(observation) {
+  const source = String(observation?.source ?? "").trim().toLowerCase();
+  const sessionId = String(observation?.session_id ?? "").trim();
+  if (!source || !sessionId) return null;
+  const verifiedMs = parseMs(observation?.snapshot_verified_at);
+  if (verifiedMs === null) return null;
+  const bucketStart = String(observation?.bucket_start ?? "");
+  if (parseMs(bucketStart) === null) return null;
+  const model = String(observation?.model ?? "");
+  if (!model) return null;
+  const row = {
+    source,
+    session_id: sessionId,
+    model,
+    bucket_start: bucketStart,
+    snapshot_verified_at: observation.snapshot_verified_at,
+  };
+  for (const column of TOKEN_COLUMNS) {
+    const value = Number(observation?.[column]);
+    row[column] = Number.isFinite(value) ? value : 0;
+  }
+  return row;
+}
+
+/**
+ * Whole-row LWW replace of canonical session states - mirrors
+ * tokentracker_upsert_account_session_states() (migrations/
+ * 20260817120000_account-session-states.sql): a row applies only when its
+ * snapshot_verified_at is STRICTLY newer (>) than the stored one. Replays of
+ * the same observation are no-ops; equal stamps keep the first-applied row.
+ *
+ * @param {Map<string, object>} states - canonical table keyed by
+ *   `${source}|${session_id}` (mirrors the (user_id, source, session_id) PK
+ *   for one account; mutated in place).
+ * @param {Array<object>} observations - ingest batch (already deduped to one
+ *   row per session by the edge, like the SQL batch upsert requires).
+ * @returns {number} applied row count (mirrors the SQL ROW_COUNT return).
+ */
+function upsertAccountSessionStates(states, observations) {
+  const table = states instanceof Map ? states : new Map();
+  const batch = Array.isArray(observations) ? observations : [];
+  let applied = 0;
+  for (const observation of batch) {
+    const row = normalizeStateRow(observation);
+    if (!row) continue;
+    const key = `${row.source}|${row.session_id}`;
+    const stored = table.get(key);
+    if (!stored) {
+      table.set(key, row);
+      applied += 1;
+      continue;
+    }
+    const storedMs = parseMs(stored.snapshot_verified_at) ?? -Infinity;
+    const rowMs = parseMs(row.snapshot_verified_at) ?? -Infinity;
+    if (rowMs > storedMs) {
+      table.set(key, row);
+      applied += 1;
+    }
+  }
+  return applied;
+}
+
+/**
+ * Aggregate canonical session states into hourly rows - mirrors the trae-cn
+ * branch of account_usage_grouped (scripts/ops/account-usage-grouped-rpc.sql)
+ * and leaderboard_hourly_dedup_v2: SUM per (bucket_start, source, model),
+ * conversations = session count.
+ *
+ * @param {Map<string, object>|Array<object>} states
+ * @param {{from?: string, to?: string}} [opts] - optional [from, to) window.
+ * @returns {Array<object>} rows shaped like tokentracker_hourly aggregates.
+ */
+function aggregateSessionStates(states, opts = {}) {
+  const values = states instanceof Map ? [...states.values()] : Array.isArray(states) ? states : [];
+  const fromMs = parseMs(opts.from ?? "");
+  const toMs = parseMs(opts.to ?? "");
+  const grouped = new Map();
+  for (const state of values) {
+    const row = normalizeStateRow(state);
+    if (!row) continue;
+    const bucketMs = parseMs(row.bucket_start);
+    if (bucketMs === null) continue;
+    if (fromMs !== null && bucketMs < fromMs) continue;
+    if (toMs !== null && bucketMs >= toMs) continue;
+    const key = `${row.bucket_start}||${row.source}||${row.model}`;
+    const acc = grouped.get(key) || {
+      hour_start: row.bucket_start,
+      source: row.source,
+      model: row.model,
+      input_tokens: 0,
+      output_tokens: 0,
+      cached_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+      reasoning_output_tokens: 0,
+      total_tokens: 0,
+      conversations: 0,
+    };
+    for (const column of TOKEN_COLUMNS) acc[column] += row[column];
+    acc.conversations += 1;
+    grouped.set(key, acc);
+  }
+  return [...grouped.values()].sort(
+    (a, b) =>
+      String(a.hour_start).localeCompare(String(b.hour_start)) ||
+      String(a.source).localeCompare(String(b.source)) ||
+      String(a.model).localeCompare(String(b.model)),
+  );
+}
+
+// Mirrors the legacy SQL DISTINCT ON (hour, source, model)
+// ORDER BY total_tokens DESC, updated_at DESC (device_id asc as the final
+// deterministic tiebreak). Used ONLY for account-level sources without a
+// stable session identity ('cursor') and watermark-less history.
+function pickLegacyRow(rows) {
+  let best = null;
+  for (const row of rows) {
+    if (!best) {
+      best = row;
+      continue;
+    }
+    const rowTotal = Number(row.total_tokens) || 0;
+    const bestTotal = Number(best.total_tokens) || 0;
+    if (rowTotal !== bestTotal) {
+      if (rowTotal > bestTotal) best = row;
+      continue;
+    }
+    const rowUpdated = parseMs(row.updated_at ?? "") ?? -Infinity;
+    const bestUpdated = parseMs(best.updated_at ?? "") ?? -Infinity;
+    if (rowUpdated !== bestUpdated) {
+      if (rowUpdated > bestUpdated) best = row;
+      continue;
+    }
+    if (String(row.device_id) < String(best.device_id)) best = row;
+  }
+  return best;
+}
+
+/**
+ * Legacy whole-row MAX dedup for account-level hourly rows WITHOUT a stable
+ * session identity ('cursor'): rows are identical across devices, so one
+ * canonical row per (hour, source, model) suffices. Sources with a session
+ * identity ('trae-cn') must instead aggregate from canonical session states
+ * (aggregateSessionStates) - never from per-device hourly rows.
+ *
+ * @param {Array<{device_id: string, hour_start: string, source: string,
+ *   model: string, updated_at?: string, total_tokens: number}>} rows -
+ *   every device's tokentracker_hourly-shaped rows.
+ * @returns {Array} canonical rows - one consistent row per (hour, model).
+ */
+function dedupeAccountLevelRows(rows) {
+  if (!Array.isArray(rows)) return [];
+  // Group rows by (source, hour_start); keep original row objects untouched.
+  const byHour = new Map();
+  for (const row of rows) {
+    if (!row || typeof row.hour_start !== "string" || !row.hour_start) continue;
+    const key = `${row.source}||${row.hour_start}`;
+    const list = byHour.get(key) || [];
+    list.push(row);
+    byHour.set(key, list);
+  }
+
+  const out = [];
+  for (const [, hourRows] of byHour) {
+    const byModel = new Map();
+    for (const row of hourRows) {
+      const modelKey = row.model || "unknown";
+      const list = byModel.get(modelKey) || [];
+      list.push(row);
+      byModel.set(modelKey, list);
+    }
+    for (const list of byModel.values()) {
+      out.push(pickLegacyRow(list));
+    }
+  }
+  return out;
+}
+
+/** Total tokens of a deduped row set - convenience for tests/diagnostics. */
+function sumTotalTokens(rows) {
+  return (Array.isArray(rows) ? rows : []).reduce(
+    (acc, row) => acc + (Number(row?.total_tokens) || 0),
+    0,
+  );
+}
+
+module.exports = {
+  SESSION_STATE_KIND,
+  TOKEN_COLUMNS,
+  upsertAccountSessionStates,
+  aggregateSessionStates,
+  dedupeAccountLevelRows,
+  sumTotalTokens,
+};

package/src/lib/local-api.js

@@ -338,6 +338,10 @@ function readQueueData(queuePath) {
       if (!line.trim()) continue;
       try {
         const row = JSON.parse(line);
+        // Account session states (and the pre-release watermark records
+        // this branch may still hold in a dev queue) are cloud-side control
+        // records, not usage rows - never surface them locally.
+        if (row?.kind === "account_session_state" || row?.kind === "account_sync_watermark") continue;
         // Deduplicate: each sync appends cumulative totals per bucket, so for
         // each (source, model, hour_start) keep only the latest (last) entry.
         const key = `${row.source || ""}|${row.model || ""}|${row.hour_start || ""}`;