tokentracker-cli 1.1.3 → 1.1.5

package/src/lib/rollout.js

@@ -47,6 +47,8 @@ const {
   buildDevinUsageEvents,
 } = require("./devin-usage");
 const { USD_TICKS_PER_USD, normalizeGrokUsage } = require("./grok-usage");
+const { resolveTraeDbPaths, readTraeUsageRows } = require("./trae-db");
+const { normalizeTraeUsage, normalizeTraeModel, traeTimestamp } = require("./trae-usage");
 
 const DEFAULT_SOURCE = "codex";
 const DEFAULT_MODEL = "unknown";
@@ -19662,12 +19664,13 @@ function mergeGrokUsagePrecision(current, next) {
   return "mixed";
 }
 
-function clearGrokHourlyBuckets(hourlyState) {
+function clearSourceHourlyBuckets(hourlyState, source) {
   if (!hourlyState || typeof hourlyState !== "object") return;
+  const prefix = `${source}${BUCKET_SEPARATOR}`;
   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];
+      if (key.startsWith(prefix)) delete buckets[key];
     }
   }
   const groupQueued =
@@ -19676,12 +19679,12 @@ function clearGrokHourlyBuckets(hourlyState) {
       : null;
   if (groupQueued) {
     for (const key of Object.keys(groupQueued)) {
-      if (key.startsWith("grok|")) delete groupQueued[key];
+      if (key.startsWith(prefix)) delete groupQueued[key];
     }
   }
 }
 
-async function retractStaleGrokQueueRows(queuePath, keepKeys) {
+async function retractStaleSourceQueueRows(queuePath, source, keepKeys) {
   if (!queuePath) return 0;
   let raw = "";
   try {
@@ -19691,7 +19694,7 @@ async function retractStaleGrokQueueRows(queuePath, keepKeys) {
     throw error;
   }
 
-  const latestGrok = new Map();
+  const latestRows = new Map();
   for (const line of raw.split("\n")) {
     if (!line.trim()) continue;
     let row;
@@ -19700,21 +19703,21 @@ async function retractStaleGrokQueueRows(queuePath, keepKeys) {
     } catch {
       continue;
     }
-    if ((row?.source || "") !== "grok") continue;
+    if ((row?.source || "") !== source) 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 });
+    latestRows.set(bucketKey(source, model, hourStart), { model, hour_start: hourStart, row });
   }
 
   const zero = initTotals();
   const lines = [];
-  for (const [key, entry] of latestGrok.entries()) {
+  for (const [key, entry] of latestRows.entries()) {
     if (keepKeys.has(key)) continue;
     if (totalsKey(entry.row) === totalsKey(zero)) continue;
     lines.push(
       JSON.stringify({
-        source: "grok",
+        source,
         model: entry.model,
         hour_start: entry.hour_start,
         ...zero,
@@ -19814,7 +19817,7 @@ async function parseGrokBuildIncremental({
         legacySeen: true,
       };
     }
-    clearGrokHourlyBuckets(hourlyState);
+    clearSourceHourlyBuckets(hourlyState, "grok");
   } else {
     sessionSnapshots = normalizeGrokSessionSnapshots(grokState);
   }
@@ -20195,7 +20198,7 @@ async function parseGrokBuildIncremental({
       if (!key.startsWith("grok|") || !bucket?.totals) continue;
       keepKeys.add(key);
     }
-    const retracted = await retractStaleGrokQueueRows(queuePath, keepKeys);
+    const retracted = await retractStaleSourceQueueRows(queuePath, "grok", keepKeys);
     bucketsQueued += retracted;
   }
 
@@ -21687,13 +21690,188 @@ function isCjkCodePoint(code) {
 // ── Trae SOLO (ByteDance AI IDE) ─────────────────────────────────────────────
 // https://www.trae.ai
 //
-// Trae SOLO is scoped to detection (init) + entitlement display (status):
-//   - init: resolveTraeStoragePath() proves an install exists.
-//   - status: readTraeEntitlementFromStorage() serves the plan/limits snapshot.
-// Trae SOLO does NOT expose per-request token usage in a readable local format
-// (session transcripts are SQLCipher-encrypted; memory summaries carry no
-// token counts), so the token-count-only queue is intentionally never written
-// for this provider — the cloud hourly table stays clean.
+// International TRAE usage comes from local encrypted chat_turn metadata.
+//
+// The ledger keeps one compact tuple per turn, keyed by a 128-bit digest, so a
+// correction can retract exactly what the turn contributed even after TRAE
+// deletes its history. total_tokens is the five token columns plus any input
+// without a cache split, which is counted but unpriced (normalizeTraeUsage).
+const TRAE_CURSOR_VERSION = 2;
+const HALF_HOUR_MS = 30 * 60 * 1000;
+const [T_SESSION, T_MODEL, T_BUCKET, T_MODIFIED, T_STORE, T_INPUT, T_CACHED, T_WRITTEN,
+  T_OUTPUT, T_REASONING, T_CONVERSATIONS, T_ESTIMATED, T_UNPRICED] = Array.from({ length: 13 }, (_, i) => i);
+
+function packTraeTurn({ session, model, bucketStart, totals, modifiedAt, store }) {
+  return [session, model, Date.parse(bucketStart) / HALF_HOUR_MS, modifiedAt, store,
+    totals.input_tokens, totals.cached_input_tokens, totals.cache_creation_input_tokens,
+    totals.output_tokens, totals.reasoning_output_tokens, totals.conversation_count,
+    totals.usage_precision === "estimated" ? 1 : 0, totals.unpriced_input_tokens || 0];
+}
+
+function unpackTraeTotals(turn) {
+  const totals = {
+    input_tokens: turn[T_INPUT],
+    cached_input_tokens: turn[T_CACHED],
+    cache_creation_input_tokens: turn[T_WRITTEN],
+    output_tokens: turn[T_OUTPUT],
+    reasoning_output_tokens: turn[T_REASONING],
+    total_tokens: turn[T_INPUT] + turn[T_CACHED] + turn[T_WRITTEN] + turn[T_OUTPUT] + turn[T_REASONING]
+      + turn[T_UNPRICED],
+    conversation_count: turn[T_CONVERSATIONS],
+  };
+  if (turn[T_ESTIMATED]) totals.usage_precision = "estimated";
+  return totals;
+}
+
+function traeTurnBucketStart(turn) {
+  return new Date(turn[T_BUCKET] * HALF_HOUR_MS).toISOString();
+}
+
+async function parseTraeIncremental({
+  dbPaths,
+  cursors,
+  queuePath,
+  env = process.env,
+  onProgress,
+  readUsageRows = readTraeUsageRows,
+} = {}) {
+  const paths = dbPaths || resolveTraeDbPaths(env);
+  const hourlyState = normalizeHourlyState(cursors.hourly);
+  // Queue writes and reads may fail. Publish cursor changes only after the
+  // append succeeds, including copies of the mutable bucket totals.
+  hourlyState.buckets = Object.fromEntries(Object.entries(hourlyState.buckets).map(([key, bucket]) => [
+    key, key.startsWith("trae|") ? { ...bucket, totals: { ...bucket.totals } } : bucket,
+  ]));
+  hourlyState.groupQueued = { ...hourlyState.groupQueued };
+  // A ledger with another TRAE_CURSOR_VERSION cannot retract what it
+  // contributed, so rebuild the TRAE buckets from the stores instead of
+  // adding every turn on top of them.
+  const prior = cursors.trae?.version === TRAE_CURSOR_VERSION ? cursors.trae : null;
+  const rebuilding = !prior && Boolean(cursors.trae);
+  if (rebuilding) clearSourceHourlyBuckets(hourlyState, "trae");
+  const turns = { ...prior?.turns };
+  const databases = { ...prior?.databases };
+  const stores = [...(prior?.stores || [])];
+  const touchedBuckets = new Set();
+  const conversations = new Set(Object.values(turns)
+    .filter((turn) => turn[T_CONVERSATIONS] > 0).map((turn) => turn[T_SESSION]));
+  // 128-bit digests: identifiers are hashed before they are stored.
+  const digest = (value) => crypto.createHash("sha256").update(value).digest().subarray(0, 16).toString("base64url");
+  let recordsProcessed = 0;
+  let eventsAggregated = 0;
+  let recordsSkipped = 0;
+  let estimatedRecords = 0;
+  let unpricedRecords = 0;
+  const errors = [];
+  for (const dbPath of [...new Set(paths)]) {
+    const databaseKey = digest(path.resolve(dbPath));
+    let store = stores.indexOf(databaseKey);
+    if (store < 0) store = stores.push(databaseKey) - 1;
+    let rows;
+    let fingerprint;
+    let finalFingerprint;
+    try {
+      // existsSync also returns false for permission errors. Let stat/read
+      // report inaccessible stores instead of treating them as absent.
+      fssync.statSync(dbPath);
+      fingerprint = devinSqliteFingerprint(dbPath);
+      if (sameSqliteFingerprint(fingerprint, databases[databaseKey])) continue;
+      rows = await readUsageRows(dbPath, { env });
+      finalFingerprint = devinSqliteFingerprint(dbPath);
+    } catch (err) {
+      // One install can be locked, corrupt, or use a different key while
+      // another remains readable. Its prior fingerprint stays retryable;
+      // successful stores still publish together after the queue append.
+      errors.push({ database: dbPath, message: err?.message || String(err) });
+      continue;
+    }
+    for (const row of rows) {
+      recordsProcessed += 1;
+      const totals = normalizeTraeUsage(row.usage, { model: row.model });
+      const timestamp = traeTimestamp(row.created_at);
+      const bucketStart = timestamp && toUtcHalfHourStart(timestamp);
+      const rowId = row.turn_id || row.id;
+      if (!totals || !bucketStart || rowId == null || rowId === "") {
+        recordsSkipped += 1;
+        continue;
+      }
+      const session = digest(String(row.session_id || `${databaseKey}:${rowId}`));
+      // Stable turn ids deduplicate copies across the two international app
+      // stores. Numeric SQLite ids are only unique within their database.
+      const identity = digest(JSON.stringify(row.turn_id
+        ? [session, row.turn_id] : [databaseKey, rowId]));
+      const previous = turns[identity];
+      const modifiedAt = Date.parse(traeTimestamp(row.updated_at) || timestamp);
+      // A copied turn in another install can lag behind the original. Never
+      // let an unrelated rescan of that stale store retract newer usage.
+      // Without a newer timestamp, conflicting copies retain their owner.
+      if (previous && previous[T_STORE] !== store && modifiedAt <= previous[T_MODIFIED]) continue;
+      if (!previous && totals.total_tokens === 0) continue;
+      if (totals.usage_precision === "estimated") estimatedRecords += 1;
+      if (totals.unpriced_input_tokens > 0) unpricedRecords += 1;
+      totals.conversation_count = previous
+        ? previous[T_CONVERSATIONS]
+        : conversations.has(session) ? 0 : 1;
+      conversations.add(session);
+      const model = normalizeTraeModel(row.model);
+      const next = packTraeTurn({ session, model, bucketStart, totals, modifiedAt, store });
+      if (previous && next.every((value, i) => i === T_MODIFIED || i === T_STORE || value === previous[i])) {
+        turns[identity] = next;
+        continue;
+      }
+      if (previous) {
+        const previousBucket = traeTurnBucketStart(previous);
+        const old = getHourlyBucket(hourlyState, "trae", previous[T_MODEL], previousBucket);
+        subtractTotals(old.totals, unpackTraeTotals(previous));
+        touchedBuckets.add(bucketKey("trae", previous[T_MODEL], previousBucket));
+      }
+      const bucket = getHourlyBucket(hourlyState, "trae", model, bucketStart);
+      addTotals(bucket.totals, totals);
+      touchedBuckets.add(bucketKey("trae", model, bucketStart));
+      turns[identity] = next;
+      eventsAggregated += 1;
+    }
+    // A read that races with a writer must be retried on the next sync.
+    databases[databaseKey] = sameSqliteFingerprint(fingerprint, finalFingerprint)
+      ? fingerprint : null;
+    if (typeof onProgress === "function") {
+      onProgress({ recordsProcessed, eventsAggregated, bucketsQueued: touchedBuckets.size });
+    }
+  }
+  // Rebuild precision from the retained contributions, including unchanged
+  // stores. A correction can replace the last estimated turn with reported
+  // usage without changing numeric totals, or move it to another bucket.
+  const bucketPrecisions = new Map();
+  for (const turn of Object.values(turns)) {
+    const key = bucketKey("trae", turn[T_MODEL], traeTurnBucketStart(turn));
+    if (!touchedBuckets.has(key) || unpackTraeTotals(turn).total_tokens === 0) continue;
+    bucketPrecisions.set(key, mergeGrokUsagePrecision(
+      bucketPrecisions.get(key), turn[T_ESTIMATED] ? "estimated" : "reported",
+    ));
+  }
+  for (const key of touchedBuckets) {
+    const precision = bucketPrecisions.get(key);
+    hourlyState.buckets[key].usage_precision = precision === "reported" ? null : precision || null;
+  }
+  // A rebuild is all or nothing. Buckets rebuilt from a subset of the stores
+  // would replace shared buckets with partial totals, and each retry would
+  // append every row again. Keep the old hourly state and ledger instead.
+  if (rebuilding && errors.length) {
+    return { recordsProcessed, eventsAggregated, bucketsQueued: 0, recordsSkipped, estimatedRecords, unpricedRecords, errors };
+  }
+  await ensureDir(path.dirname(queuePath));
+  let bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
+  cursors.hourly = hourlyState;
+  if (rebuilding) {
+    // The old ledger may have filed a turn under another bucket key (model or
+    // half-hour); retract those rows so the dashboard does not count it twice.
+    const keepKeys = new Set(Object.keys(hourlyState.buckets).filter((key) => key.startsWith("trae|")));
+    bucketsQueued += await retractStaleSourceQueueRows(queuePath, "trae", keepKeys);
+  }
+  cursors.trae = { version: TRAE_CURSOR_VERSION, stores, databases, turns };
+  return { recordsProcessed, eventsAggregated, bucketsQueued, recordsSkipped, estimatedRecords, unpricedRecords, errors };
+}
+
 // Ordered candidate app-dir names. The CN IDE build installs as "Trae CN" on
 // Windows; the international build installs as "TRAE SOLO". Both expose the same
 // iCubeServerData entitlement key, so either is a valid Trae IDE install.
@@ -24192,6 +24370,7 @@ async function parseCommandCodeIncremental({
 }
 
 module.exports = {
+  parseTraeIncremental,
   listRolloutFiles,
   listRolloutFilesDeep,
   codexSessionIdFromPath,

package/src/lib/scan-roots.js

@@ -0,0 +1,277 @@
+"use strict";
+
+// Persistent extra scan roots for Codex and Claude Code (#657).
+//
+// Agent harnesses run Codex / Claude Code with a private home
+// (CODEX_HOME=..., CLAUDE_CONFIG_DIR=...). Those sessions were invisible to
+// TokenTracker unless the sync happened to be spawned by a process that
+// inherited the same environment: a hook-fired sync saw them, the native app's
+// background refresh did not. Worse, the two producers then disagreed about
+// where a rollout's cursor lives (the cursor store classifies a rollout as a
+// Codex path — per-day shard — only when it sits under one of ITS codexRoots,
+// everything else goes to core), never saw each other's cursor, and re-parsed
+// the same file from byte 0 on every alternation (#639: one 30-minute bucket
+// re-emitted 138 times, 59B tokens for a 1.2B day).
+//
+// So roots come from ONE persistent list that every producer reads, and the
+// cursor store's codexRoots are derived from that same list.
+//
+// Per provider, in order (first occurrence wins; later duplicates by realpath
+// are dropped):
+//   1. the roots the caller already scans (native home, WSL install)
+//   2. the spawning process's implicit root — CODEX_HOME / CLAUDE_CONFIG_DIR
+//   3. config.scanRoots.<provider>[] from ~/.tokentracker/tracker/config.json
+//
+// Config shape:
+//   { "scanRoots": { "codex": ["~/.local/share/agent/codex"],
+//                    "claude": ["~/.local/share/agent/claude", "~/.claude-native"] } }
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { readJson } = require("./fs");
+const { resolveTrackerPaths } = require("./tracker-paths");
+
+const PROVIDERS = Object.freeze({
+  codex: Object.freeze({ envVar: "CODEX_HOME" }),
+  claude: Object.freeze({ envVar: "CLAUDE_CONFIG_DIR" }),
+});
+const PROVIDER_NAMES = Object.freeze(Object.keys(PROVIDERS));
+
+// Turn a configured root into a stable absolute path. `~` expands against
+// `home`, and a RELATIVE entry is resolved against `home` too — never against
+// process.cwd(), which differs between a hook-fired sync, the CLI and the
+// desktop app and would make producers scan different directories.
+function expandHome(value, home) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed === "~") return path.resolve(home);
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return path.resolve(home, trimmed.slice(2));
+  }
+  return path.isAbsolute(trimmed) ? path.resolve(trimmed) : path.resolve(home, trimmed);
+}
+
+// The spawning process's implicit root — CODEX_HOME / CLAUDE_CONFIG_DIR —
+// normalized ONCE, the same way configured entries are: `~` and relative
+// values are anchored to `home`, never to process.cwd(). Every producer
+// (sync discovery, the cursor store's codexRoots, status, diagnostics, the
+// session browser) must use this value, or a relative CODEX_HOME such as
+// `profiles/codex` is scanned under one directory and cursor-classified
+// under another, and the same rollout replays. Returns null when unset.
+function resolveEnvRoot(provider, { env = process.env, home = os.homedir() } = {}) {
+  const spec = PROVIDERS[provider];
+  if (!spec) return null;
+  const raw = env && typeof env[spec.envVar] === "string" ? env[spec.envVar] : "";
+  return expandHome(raw, home);
+}
+
+// Accepts { codex: string | string[], claude: string | string[] }. Anything
+// else — wrong type, empty strings, unknown providers — is ignored rather than
+// failing the sync: a malformed config must not stop collection.
+function normalizeScanRootsConfig(raw) {
+  const out = {};
+  for (const provider of PROVIDER_NAMES) out[provider] = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  for (const provider of PROVIDER_NAMES) {
+    const value = raw[provider];
+    const list = Array.isArray(value) ? value : (typeof value === "string" ? [value] : []);
+    for (const entry of list) {
+      if (typeof entry !== "string" || !entry.trim()) continue;
+      out[provider].push(entry.trim());
+    }
+  }
+  return out;
+}
+
+// { exists, error }: `exists` is true only for a directory that can be
+// LISTED, not merely stat'ed — a stat-able directory whose listing fails
+// (mode 000, ACL) would otherwise be admitted to the scan, yield no files,
+// read as "present" in status/doctor, and slip past the deferred-repair
+// guard in sync. ENOENT and ENOTDIR (or a regular file in a directory's
+// place) mean the root is absent (error null); any other failure (EACCES,
+// ELOOP, EIO, ...) is reported as `error` so callers can say "unreadable"
+// instead of "missing".
+function scanRootDirState(target, deps = {}) {
+  const statSync = deps.statSync || fs.statSync;
+  const opendirSync = deps.opendirSync || fs.opendirSync;
+  try {
+    if (!statSync(target).isDirectory()) return { exists: false, error: null };
+    // Probe listability without reading entries; large roots stay cheap.
+    opendirSync(target).closeSync();
+    return { exists: true, error: null };
+  } catch (e) {
+    const code = e && typeof e.code === "string" ? e.code : "EUNKNOWN";
+    if (code === "ENOENT" || code === "ENOTDIR") return { exists: false, error: null };
+    return { exists: false, error: code };
+  }
+}
+
+function isDirectorySync(target, deps) {
+  return scanRootDirState(target, deps).exists;
+}
+
+function realpathOrSelf(target, deps) {
+  const realpathSync = deps.realpathSync || fs.realpathSync;
+  try {
+    return realpathSync(target);
+  } catch {
+    return target;
+  }
+}
+
+function identityKey(target, deps) {
+  const resolved = path.resolve(target);
+  const real = realpathOrSelf(resolved, deps);
+  return real.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+
+// Drop later entries that resolve (realpath) to a directory already listed.
+// Used at the projects/ level too: two Claude profiles may symlink one
+// projects/ dir, and reading it under both spellings would double-parse every
+// file, leaving correctness to the bounded claudeHashes layer.
+function dedupeDirsByRealpath(dirs, deps = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of Array.isArray(dirs) ? dirs : []) {
+    if (typeof dir !== "string" || !dir) continue;
+    const key = identityKey(dir, deps);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(dir);
+  }
+  return out;
+}
+
+// Resolve the full, ordered, deduplicated root list per provider.
+//
+//   base: { codex: string[], claude: string[] } — roots the caller scans
+//         anyway (native home, WSL install); they keep their position and
+//         are labelled origin "native".
+//   env:  CODEX_HOME / CLAUDE_CONFIG_DIR become origin "env" unless already
+//         covered by base.
+//   config.scanRoots.<provider>[] become origin "config".
+//
+// Every entry: { path, realPath, exists, error, origin }. `exists` is a
+// readable-directory check and `error` carries a stat error code other than
+// absence (see scanRootDirState); non-existent or unreadable configured roots
+// are kept in the list (so cursor-path classification stays stable while a
+// volume is unmounted) and callers that walk directories skip them via
+// `exists`.
+function resolveScanRoots({
+  home = os.homedir(),
+  env = process.env,
+  config = null,
+  base = {},
+  deps = {},
+} = {}) {
+  const configured = normalizeScanRootsConfig(config && typeof config === "object" ? config.scanRoots : null);
+  const out = {};
+  for (const provider of PROVIDER_NAMES) {
+    const candidates = [];
+    for (const root of Array.isArray(base[provider]) ? base[provider] : []) {
+      if (typeof root === "string" && root.trim()) candidates.push({ raw: root, origin: "native" });
+    }
+    const envRoot = resolveEnvRoot(provider, { env, home });
+    if (envRoot) candidates.push({ raw: envRoot, origin: "env" });
+    for (const root of configured[provider]) candidates.push({ raw: root, origin: "config" });
+
+    const seen = new Set();
+    const entries = [];
+    for (const candidate of candidates) {
+      const expanded = expandHome(candidate.raw, home);
+      if (!expanded) continue;
+      const resolved = expanded;
+      const key = identityKey(resolved, deps);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const state = scanRootDirState(resolved, deps);
+      entries.push({
+        path: resolved,
+        realPath: realpathOrSelf(resolved, deps),
+        exists: state.exists,
+        error: state.error,
+        origin: candidate.origin,
+      });
+    }
+    out[provider] = entries;
+  }
+  return out;
+}
+
+// Append `extraDirs` to `baseDirs`, dropping any extra that resolves (realpath)
+// to a directory already present. Base entries are never collapsed against
+// each other: the native + WSL pair is listed on purpose (see sync.js) and
+// their dedup is handled downstream by file-identity hashes.
+function appendUniqueDirs(baseDirs, extraDirs, deps = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const dir of Array.isArray(baseDirs) ? baseDirs : []) {
+    if (typeof dir !== "string" || !dir) continue;
+    seen.add(identityKey(dir, deps));
+    out.push(dir);
+  }
+  for (const dir of Array.isArray(extraDirs) ? extraDirs : []) {
+    if (typeof dir !== "string" || !dir) continue;
+    const key = identityKey(dir, deps);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(dir);
+  }
+  return out;
+}
+
+// Roots beyond what the caller already scans: the "env" and "config" entries
+// that exist on disk. Paths only, in list order.
+function extraScanRootPaths(entries) {
+  return (Array.isArray(entries) ? entries : [])
+    .filter((entry) => entry && entry.origin !== "native" && entry.exists)
+    .map((entry) => entry.path);
+}
+
+function hasAnyScanChild(root, children, deps = {}) {
+  for (const child of Array.isArray(children) ? children : [children]) {
+    if (isDirectorySync(path.join(root, child), deps)) return true;
+  }
+  return false;
+}
+
+// Human label for status / doctor output.
+function describeScanRootOrigin(entry, provider) {
+  if (!entry || entry.origin === "native") return "native";
+  if (entry.origin === "env") return PROVIDERS[provider]?.envVar || "env";
+  return "scanRoots";
+}
+
+// "" for a readable root, " (missing)" for an absent one, " (unreadable: CODE)"
+// for a stat failure other than absence.
+function describeScanRootState(entry) {
+  if (!entry || entry.exists) return "";
+  return entry.error ? ` (unreadable: ${entry.error})` : " (missing)";
+}
+
+// config.scanRoots as persisted in ~/.tokentracker/tracker/config.json for
+// callers that do not already hold the config (the session browser).
+async function loadScanRootsConfig({ home = os.homedir() } = {}) {
+  const { trackerDir } = await resolveTrackerPaths({ home });
+  const config = await readJson(path.join(trackerDir, "config.json")).catch(() => null);
+  return normalizeScanRootsConfig(config && typeof config === "object" ? config.scanRoots : null);
+}
+
+module.exports = {
+  PROVIDER_NAMES,
+  appendUniqueDirs,
+  dedupeDirsByRealpath,
+  describeScanRootOrigin,
+  describeScanRootState,
+  expandHome,
+  extraScanRootPaths,
+  hasAnyScanChild,
+  loadScanRootsConfig,
+  normalizeScanRootsConfig,
+  resolveEnvRoot,
+  resolveScanRoots,
+  scanRootDirState,
+};