tokentracker-cli 1.1.3 → 1.1.5

package/src/lib/session-analytics.js

@@ -33,6 +33,14 @@ const { parseCodexRolloutFile } = require("./codex-rollout-parser");
 const { computeRowCost, getModelPricing } = require("./pricing");
 const { USD_TICKS_PER_USD, normalizeGrokUsage } = require("./grok-usage");
 const wsl = require("./wsl-probe");
+const {
+  appendUniqueDirs,
+  dedupeDirsByRealpath,
+  expandHome,
+  loadScanRootsConfig,
+  normalizeScanRootsConfig,
+  scanRootDirState,
+} = require("./scan-roots");
 
 // Bump the sidecar when derived metrics change so cached rows are rebuilt
 // instead of leaving the dashboard on the previous (over-counted) heuristic.
@@ -1074,8 +1082,11 @@ function providerRoots(home, providerDir, env, deps = {}) {
       && path.resolve(home) === path.resolve(homedir())
       && typeof env?.CODEX_HOME === "string"
       && env.CODEX_HOME.trim();
+    // Same normalization as sync / the cursor store (scan-roots.expandHome):
+    // a relative CODEX_HOME is anchored to home, never to process.cwd(), so
+    // the browser walks the exact root the cursors were keyed under.
     const nativeRoot = useProcessCodexHome
-      ? path.resolve(env.CODEX_HOME.trim())
+      ? expandHome(env.CODEX_HOME, home)
       : path.join(home, providerDir);
     roots.push(nativeRoot);
   }
@@ -1095,7 +1106,21 @@ function providerRoots(home, providerDir, env, deps = {}) {
     const wslRoot = discoverWslHome(providerDir, { env });
     if (wslRoot) roots.push(wslRoot);
   }
-  return [...new Set(roots)];
+  // Extra roots (#657), mirroring src/commands/sync.js: CLAUDE_CONFIG_DIR is
+  // the spawning process's implicit Claude root (additive — ~/.claude stays
+  // scanned), and config.scanRoots.<provider> arrives as deps.extraRoots from
+  // discoverSessionFiles. Extras are realpath-deduped against the roots above
+  // so one directory listed under two spellings is walked once.
+  const extras = [];
+  const useProcessClaudeConfigDir = providerDir === ".claude"
+    && path.resolve(home) === path.resolve(homedir())
+    && typeof env?.CLAUDE_CONFIG_DIR === "string"
+    && env.CLAUDE_CONFIG_DIR.trim();
+  if (useProcessClaudeConfigDir) extras.push(expandHome(env.CLAUDE_CONFIG_DIR, home));
+  for (const extra of Array.isArray(deps.extraRoots) ? deps.extraRoots : []) {
+    if (typeof extra === "string" && extra) extras.push(path.resolve(extra));
+  }
+  return appendUniqueDirs([...new Set(roots)], extras);
 }
 
 // Group one logical session discovered under more than one root. A group is
@@ -1221,10 +1246,37 @@ function groupCodexFiles(filePaths) {
 
 async function discoverSessionFiles(home, env = process.env, deps = {}) {
   const grokHome = resolveGrokHome(home);
-  const claudeRoots = providerRoots(home, ".claude", env, deps);
-  const codexRoots = providerRoots(home, ".codex", env, deps);
+  // config.scanRoots (#657): read from the tracker config unless the caller
+  // injects it (tests). A missing or malformed config yields no extras.
+  const scanRootsConfig = deps.scanRootsConfig !== undefined
+    ? normalizeScanRootsConfig(deps.scanRootsConfig)
+    : await loadScanRootsConfig({ home });
+  // expandHome resolves `~` and relative entries against `home` (never cwd);
+  // only readable directories are walked, absence and stat errors alike.
+  const extraRootsFor = (provider) => scanRootsConfig[provider]
+    .map((root) => expandHome(root, home))
+    .filter((root) => root && scanRootDirState(root).exists);
+  const claudeRoots = providerRoots(home, ".claude", env, { ...deps, extraRoots: extraRootsFor("claude") });
+  const codexRoots = providerRoots(home, ".codex", env, { ...deps, extraRoots: extraRootsFor("codex") });
+  // Two distinct roots may share one projects/ dir through a symlink; dedupe
+  // the derived projects dirs by realpath (as sync does) so the browser never
+  // lists the same transcript twice under two spellings.
+  const claudeProjectsDirs = dedupeDirsByRealpath(claudeRoots.map((r) => path.join(r, "projects")));
+  // listClaudeProjectFiles / listRolloutFilesDeep turn a listing error into an
+  // empty result, so a root whose projects/ (or sessions/) exists but cannot be
+  // read would look like "no sessions" and get cached as such. Report those
+  // directories as incomplete discovery instead; the caller decides not to
+  // persist a partial inventory (sync defers its repair on the same state).
+  const incomplete = [];
+  for (const dir of [
+    ...claudeProjectsDirs,
+    ...codexRoots.map((r) => path.join(r, "sessions")),
+  ]) {
+    const state = scanRootDirState(dir);
+    if (state.error !== null) incomplete.push({ path: dir, error: state.error });
+  }
   const [claudeGroups, codexGroups, archivedGroups, grok] = await Promise.all([
-    Promise.all(claudeRoots.map((r) => listClaudeProjectFiles(path.join(r, "projects")))),
+    Promise.all(claudeProjectsDirs.map((dir) => listClaudeProjectFiles(dir))),
     Promise.all(codexRoots.map((r) => listRolloutFilesDeep(path.join(r, "sessions")))),
     Promise.all(codexRoots.map((r) => listRolloutFilesDeep(path.join(r, "archived_sessions")))),
     listGrokSessionFiles(path.join(grokHome, "sessions")),
@@ -1239,7 +1291,20 @@ async function discoverSessionFiles(home, env = process.env, deps = {}) {
   const claude = allClaude.filter((filePaths) => !filePaths.some((filePath) => filePath
     .split(path.sep)
     .some((segment) => segment.endsWith(CLAUDE_MEM_OBSERVER_PROJECT_SUFFIX))));
-  return { claude, codex: groupCodexFiles([...codex, ...archived]), grok };
+  return { claude, codex: groupCodexFiles([...codex, ...archived]), grok, incomplete };
+}
+
+// Warn once per unreadable directory per process: the dashboard polls this
+// path, and a line per poll would flood the serve log.
+const warnedIncompleteDiscovery = new Set();
+function warnIncompleteDiscovery(incomplete) {
+  for (const entry of incomplete) {
+    if (warnedIncompleteDiscovery.has(entry.path)) continue;
+    warnedIncompleteDiscovery.add(entry.path);
+    if (!process.env.NODE_TEST_CONTEXT) {
+      console.warn(`[session-analytics] session directory unreadable (${entry.error}), inventory incomplete: ${entry.path}`);
+    }
+  }
 }
 
 function filesSignature(files) {
@@ -1368,6 +1433,19 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     } catch { /* first run */ }
   }
   const discovered = await discoverSessionFiles(home);
+  // Incomplete discovery (an unreadable projects/ or sessions/ dir): never let
+  // a partial inventory replace a complete snapshot. Serve the last complete
+  // sidecar when there is one; otherwise build from what is readable but do
+  // not persist it, so the next refresh tries again.
+  const incompleteDirs = Array.isArray(discovered.incomplete) ? discovered.incomplete : [];
+  if (incompleteDirs.length > 0) {
+    warnIncompleteDiscovery(incompleteDirs);
+    if (!force && previousMeta?.version === SIDECAR_VERSION) {
+      const cached = readSidecar(sidecarPath);
+      Object.defineProperty(cached, "incompleteDirs", { value: incompleteDirs, enumerable: false });
+      return cached;
+    }
+  }
   // Codex thread titles are stored separately from rollout files. Include the
   // index in the overall signature so an index-only rename reaches the
   // per-file dependency check below on the next refresh. Grok titles/metadata
@@ -1437,19 +1515,22 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     nextFiles[cacheKey] = { stat_key: statKey };
   }
   sessions.sort((a, b) => String(b.ended_at || "").localeCompare(String(a.ended_at || "")));
-  const content = sessions.map(serializeSessionRecord).join("\n") + (sessions.length ? "\n" : "");
-  await writeAtomic(sidecarPath, content);
-  const generatedAt = new Date().toISOString();
-  await writeAtomic(metaPath, `${JSON.stringify({
-    version: SIDECAR_VERSION,
-    signature,
-    generated_at: generatedAt,
-    checked_at: generatedAt,
-    files: nextFiles,
-  })}\n`);
+  if (incompleteDirs.length === 0) {
+    const content = sessions.map(serializeSessionRecord).join("\n") + (sessions.length ? "\n" : "");
+    await writeAtomic(sidecarPath, content);
+    const generatedAt = new Date().toISOString();
+    await writeAtomic(metaPath, `${JSON.stringify({
+      version: SIDECAR_VERSION,
+      signature,
+      generated_at: generatedAt,
+      checked_at: generatedAt,
+      files: nextFiles,
+    })}\n`);
+  }
   // Non-enumerable so the array still behaves exactly like a plain row list
   // for every existing caller (map/filter/JSON of the rows is unaffected).
   Object.defineProperty(sessions, "skippedFiles", { value: skippedFiles, enumerable: false });
+  Object.defineProperty(sessions, "incompleteDirs", { value: incompleteDirs, enumerable: false });
   return sessions;
 }
 
@@ -2006,6 +2087,7 @@ module.exports = {
   resumeCommandFor,
   sessionsToCsv,
   providerRoots,
+  discoverSessionFiles,
   dedupeClaudeFilesAcrossRoots,
   analyticsEntryStatKey,
 };

package/src/lib/trae-db.js

@@ -0,0 +1,127 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { openTraeSnapshot } = require("./trae-snapshot");
+const { withTraeSqlite } = require("./trae-sqlite");
+
+const TOKEN_FIELDS = [
+  "prompt_tokens", "prompt_tokens_total", "input_tokens",
+  "completion_tokens", "completion_tokens_total", "output_tokens",
+  "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens",
+  "reasoning_tokens", "reasoning_output_tokens",
+];
+
+function resolveTraeDbPaths(env = process.env, { platform = process.platform, home = os.homedir() } = {}) {
+  const explicit = String(env.TOKENTRACKER_TRAE_DB || "").trim();
+  if (explicit) return [path.resolve(explicit)];
+  const customHome = String(env.TOKENTRACKER_TRAE_HOME || "").trim();
+  const parent = platform === "win32"
+    ? env.APPDATA || path.join(home, "AppData", "Roaming")
+    : platform === "darwin"
+      ? path.join(home, "Library", "Application Support")
+      : env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const roots = customHome ? [customHome] : [path.join(parent, "Trae"), path.join(parent, "TRAE SOLO")];
+  const result = [];
+  for (const root of roots) {
+    // A decrypted sibling may be an old export. Only an explicit DB override
+    // opts into one; normal discovery always reads the current application DB.
+    for (const module of ["ai-agent", "ai-chat"]) {
+      const candidate = path.resolve(root, "ModularData", module, "database.db");
+      let present;
+      try { present = fs.statSync(candidate).isFile(); }
+      catch (err) {
+        // Permission failures must reach the reader's diagnostics, not masquerade
+        // as an absent installation and silently drop an entire usage history.
+        present = err.code !== "ENOENT" && err.code !== "ENOTDIR";
+      }
+      if (present) {
+        result.push(candidate);
+        break;
+      }
+    }
+  }
+  return [...new Set(result)];
+}
+
+function error(message) {
+  return new Error(`Cannot read TRAE usage: ${message}`);
+}
+
+async function projectUsage(queryRows) {
+  const tables = await queryRows("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'chat_turn'");
+  // history_v2.token_usage can be a context-size snapshot rather than billed
+  // usage. Do not synthesize input tokens from those scalar values.
+  if (!tables.length) throw error("unsupported database schema: chat_turn table is missing.");
+  const columns = new Set((await queryRows("PRAGMA table_info(chat_turn)")).map((row) => row.name));
+  if (!columns.has("context") || (!columns.has("created_at") && !columns.has("updated_at"))) {
+    throw error("unsupported chat_turn schema.");
+  }
+  const column = (name, fallback = "NULL") => columns.has(name) ? `"${name}"` : fallback;
+  const date = columns.has("created_at") && columns.has("updated_at")
+    ? 'COALESCE("created_at", "updated_at")' : column("created_at", column("updated_at"));
+  const modelPaths = [
+    "persist_user_message_context.model_info.display_model_name",
+    "persist_user_message_context.model_info.model_name",
+    "persist_user_message_context.model_info.config_name", "model_name", "model",
+    "agent_model", "selected_model.name", "selectedModel.name",
+  ];
+  const model = modelPaths.map((field) => `CASE WHEN json_type(context, '$.${field}') = 'text'
+    THEN NULLIF(NULLIF(TRIM(json_extract(context, '$.${field}')), ''), '-') END`);
+  const fields = TOKEN_FIELDS.map((field) => `CASE
+    WHEN json_type(context, '$.token_usage.${field}') IN ('integer', 'real')
+    THEN json_extract(context, '$.token_usage.${field}') END AS "${field}"`);
+  const invalidFields = TOKEN_FIELDS.map((field) =>
+    `COALESCE(json_type(context, '$.token_usage.${field}') NOT IN ('integer', 'real', 'null'), 0)`);
+  // Project inside SQLite: prompts, messages, session titles, fee/account data,
+  // and the rest of the context never cross into JS results or cursor state.
+  const query = `SELECT CAST(${column("id", "rowid")} AS TEXT) AS id,
+    ${column("session_id")} AS session_id, ${column("turn_id")} AS turn_id,
+    ${date} AS created_at, ${column("updated_at")} AS updated_at,
+    COALESCE(${model.join(", ")}, 'trae-unknown') AS model,
+    ${fields.join(", ")}, (${invalidFields.join(" OR ")}) AS invalid_usage
+    FROM chat_turn WHERE CASE WHEN json_valid(context)
+      THEN json_type(context, '$.token_usage') = 'object' ELSE 0 END`;
+  return (await queryRows(query)).map((row) => {
+    const usage = {};
+    let invalid = Boolean(row.invalid_usage);
+    for (const field of TOKEN_FIELDS) {
+      const value = row[field];
+      if (value == null) continue;
+      if (!Number.isSafeInteger(value) || value < 0) invalid = true;
+      else usage[field] = value;
+    }
+    return {
+      id: row.id, session_id: row.session_id, turn_id: row.turn_id,
+      created_at: row.created_at, updated_at: row.updated_at,
+      model: row.model, usage: invalid ? null : usage,
+    };
+  });
+}
+
+async function readTraeUsageRows(dbPath, { env = process.env } = {}) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let snapshot;
+    try { snapshot = openTraeSnapshot(dbPath, env); }
+    catch (err) {
+      // A writer can also change the files while the snapshot opens. Retry
+      // that too, and report the specific failure once attempts run out.
+      if (err?.transient && attempt < 2) continue;
+      throw err;
+    }
+    try {
+      let result;
+      try { result = await withTraeSqlite(snapshot, projectUsage); }
+      catch (err) {
+        // A writer may have changed pages while SQLite was reading. Discard
+        // every projected row and retry; never publish a mixed snapshot.
+        if (snapshot.isStable()) throw err;
+        continue;
+      }
+      if (snapshot.isStable()) return result;
+    } finally { snapshot.close(); }
+  }
+  throw error("database changed during the read; retry after TRAE finishes its current turn.");
+}
+
+module.exports = { resolveTraeDbPaths, readTraeUsageRows };

package/src/lib/trae-snapshot.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+
+const SQLITE_HEADER = Buffer.from("SQLite format 3\0");
+const PAGE_SIZE = 4096;
+const RESERVED = 80;
+// TRAE's shared application key
+const DEFAULT_SQLCIPHER_KEY = "3605f6691095a993f03d5009c918352ef5be31ae31e8f000212b81ff058da773";
+const CACHE_PAGES = 64;
+const MAX_WAL_INDEX_PAGES = 1024 * 1024;
+
+function error(message) { return new Error(`Cannot read TRAE usage: ${message}`); }
+// A writer race rather than a bad store: the caller may retry immediately.
+function transientError(message) { return Object.assign(error(message), { transient: true }); }
+
+function statOptional(file) {
+  try { return fs.statSync(file, { bigint: true }); }
+  catch (err) { if (err.code === "ENOENT" || err.code === "ENOTDIR") return null; throw err; }
+}
+
+function sameStat(a, b) {
+  if (!a || !b) return a === b;
+  return a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && a.ino === b.ino;
+}
+
+function readExact(fd, target, offset) {
+  let read = 0;
+  while (read < target.length) {
+    const count = fs.readSync(fd, target, read, target.length - read, offset + read);
+    if (!count) throw transientError("database or WAL was truncated during the read; retry when TRAE is idle.");
+    read += count;
+  }
+  return target;
+}
+
+function pageDecryptor(firstPage, env) {
+  const hex = String(env.TOKENTRACKER_TRAE_SQLCIPHER_KEY || "").trim() || DEFAULT_SQLCIPHER_KEY;
+  if (!/^[0-9a-f]{64}$/i.test(hex)) throw error("TOKENTRACKER_TRAE_SQLCIPHER_KEY must contain 64 hex characters.");
+  const key = Buffer.from(hex, "hex");
+  const salt = Buffer.from(firstPage.subarray(0, 16).map((byte) => byte ^ 0x3a));
+  // SQLCipher 4 raw-key format: AES-256-CBC, 4096-byte pages, SHA-512 HMAC.
+  // https://github.com/sqlcipher/sqlcipher/blob/master/src/sqlcipher.c
+  const hmacKey = crypto.pbkdf2Sync(key, salt, 2, 32, "sha512");
+  salt.fill(0);
+  return {
+    decrypt(page, number) {
+      const start = number === 1 ? 16 : 0;
+      const ivOffset = PAGE_SIZE - RESERVED;
+      const pageId = Buffer.alloc(4);
+      pageId.writeUInt32LE(number);
+      const expected = crypto.createHmac("sha512", hmacKey)
+        .update(page.subarray(start, ivOffset + 16)).update(pageId).digest();
+      if (!crypto.timingSafeEqual(expected, page.subarray(ivOffset + 16))) {
+        throw error("SQLCipher authentication failed (incorrect key, unsupported format, or damaged database); set TOKENTRACKER_TRAE_SQLCIPHER_KEY to override the shared application key.");
+      }
+      const decipher = crypto.createDecipheriv("aes-256-cbc", key, page.subarray(ivOffset, ivOffset + 16));
+      decipher.setAutoPadding(false);
+      const decoded = decipher.update(page.subarray(start, ivOffset));
+      decipher.final();
+      page.fill(0);
+      if (number === 1) SQLITE_HEADER.copy(page);
+      decoded.copy(page, start);
+      decoded.fill(0);
+      if (number === 1 && (page.readUInt16BE(16) !== PAGE_SIZE || page[20] !== RESERVED)) {
+        throw error("unsupported SQLCipher page format.");
+      }
+      return page;
+    },
+    dispose() { key.fill(0); hmacKey.fill(0); },
+  };
+}
+
+function checksum(data, bigEndian, state = [0, 0]) {
+  let [a, b] = state;
+  for (let i = 0; i < data.length; i += 8) {
+    const x = bigEndian ? data.readUInt32BE(i) : data.readUInt32LE(i);
+    const y = bigEndian ? data.readUInt32BE(i + 4) : data.readUInt32LE(i + 4);
+    a = (a + x + b) >>> 0;
+    b = (b + y + a) >>> 0;
+  }
+  return [a, b];
+}
+
+function indexWal(fd, size, pageSize) {
+  const pages = new Map();
+  if (fd == null || size === 0) return { pages, pageCount: null };
+  if (size < 32) throw transientError("incomplete WAL header; retry when TRAE is idle.");
+  const header = readExact(fd, Buffer.alloc(32), 0);
+  const magic = header.readUInt32BE(0);
+  if ((magic !== 0x377f0682 && magic !== 0x377f0683) ||
+      header.readUInt32BE(4) !== 3007000 || header.readUInt32BE(8) !== pageSize) {
+    throw error("unsupported WAL format.");
+  }
+  const bigEndian = magic === 0x377f0683;
+  let sum = checksum(header.subarray(0, 24), bigEndian);
+  if (sum[0] !== header.readUInt32BE(24) || sum[1] !== header.readUInt32BE(28)) throw error("WAL header checksum failed.");
+  let pageCount = null;
+  let pending = new Map();
+  const frame = Buffer.alloc(24 + pageSize);
+  // Index offsets instead of buffering/decrypting an entire WAL. Uncommitted
+  // frames never enter the visible page map. SQLite checksums cover ciphertext.
+  // https://www.sqlite.org/fileformat2.html#walformat
+  for (let offset = 32; offset + frame.length <= size; offset += frame.length) {
+    readExact(fd, frame, offset);
+    if (!frame.subarray(8, 16).equals(header.subarray(16, 24))) break;
+    // Like a salt mismatch, the first checksum mismatch ends the valid log (a
+    // torn append or crash leftover); only committed frames before it count.
+    sum = checksum(frame.subarray(24), bigEndian, checksum(frame.subarray(0, 8), bigEndian, sum));
+    if (sum[0] !== frame.readUInt32BE(16) || sum[1] !== frame.readUInt32BE(20)) break;
+    const number = frame.readUInt32BE(0);
+    const commit = frame.readUInt32BE(4);
+    if (!number || number === 0xffffffff || commit === 0xffffffff) throw error("invalid WAL page number or database size.");
+    pending.set(number, offset + 24);
+    if (pending.size + pages.size > MAX_WAL_INDEX_PAGES) throw error("WAL index exceeds the bounded-memory limit; let TRAE checkpoint its WAL and retry.");
+    if (commit) {
+      for (const [page, position] of pending) pages.set(page, position);
+      pending = new Map();
+      pageCount = commit;
+      for (const page of pages.keys()) if (page > commit) pages.delete(page);
+    }
+  }
+  frame.fill(0);
+  return { pages, pageCount };
+}
+
+// A read-only, optimistic snapshot. SQLite reads authenticated pages on demand;
+// no decrypted database is ever written to disk or materialized in memory.
+// The caller must discard results if isStable() fails after the SQL query.
+function openTraeSnapshot(dbPath, env = process.env) {
+  const paths = [dbPath, `${dbPath}-wal`, `${dbPath}-journal`];
+  const before = paths.map(statOptional);
+  if (!before[0]) throw error("database no longer exists.");
+  if (before.some((stat) => stat && (!stat.isFile() || stat.size > BigInt(Number.MAX_SAFE_INTEGER)))) {
+    throw error("unsupported database file or size.");
+  }
+  const handles = [];
+  const cache = new Map();
+  let decryptor;
+  const close = () => {
+    for (const page of cache.values()) page.fill(0);
+    cache.clear();
+    if (decryptor) { decryptor.dispose(); decryptor = null; }
+    let failure;
+    while (handles.length) {
+      try { fs.closeSync(handles.pop()); }
+      catch (err) { failure ||= err; }
+    }
+    if (failure) throw failure;
+  };
+  try {
+    const dbFd = fs.openSync(dbPath, "r");
+    handles.push(dbFd);
+    if (!sameStat(before[0], fs.fstatSync(dbFd, { bigint: true }))) throw transientError("database changed while opening; retry when TRAE is idle.");
+    let walFd = null;
+    if (before[1]) {
+      walFd = fs.openSync(paths[1], "r");
+      handles.push(walFd);
+      if (!sameStat(before[1], fs.fstatSync(walFd, { bigint: true }))) throw transientError("WAL changed while opening; retry when TRAE is idle.");
+    }
+    if (before[2] && before[2].size >= 8n) {
+      const journalFd = fs.openSync(paths[2], "r");
+      handles.push(journalFd);
+      if (readExact(journalFd, Buffer.alloc(8), 0).some((byte) => byte !== 0)) throw error("a rollback transaction is active; retry when TRAE is idle.");
+    }
+    const size = Number(before[0].size);
+    if (size < 100) throw error("database is truncated.");
+    const header = readExact(dbFd, Buffer.alloc(100), 0);
+    const encrypted = !header.subarray(0, 16).equals(SQLITE_HEADER);
+    const encodedSize = encrypted ? PAGE_SIZE : header.readUInt16BE(16);
+    const pageSize = encodedSize === 1 ? 65536 : encodedSize;
+    if (pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) || size % pageSize) throw error("invalid database page size or truncated database.");
+    if (encrypted) decryptor = pageDecryptor(header, env);
+    const { pages, pageCount } = indexWal(walFd, Number(before[1]?.size || 0n), pageSize);
+    const finalPageCount = pageCount == null ? size / pageSize : pageCount;
+    if (!finalPageCount || finalPageCount > 0xfffffffe) throw error("invalid database size.");
+    const byteLength = finalPageCount * pageSize;
+    const getPage = (number) => {
+      if (cache.has(number)) {
+        const page = cache.get(number);
+        cache.delete(number);
+        cache.set(number, page);
+        return page;
+      }
+      const page = Buffer.alloc(pageSize);
+      try {
+        if (pages.has(number)) readExact(walFd, page, pages.get(number));
+        else readExact(dbFd, page, (number - 1) * pageSize);
+        if (decryptor) decryptor.decrypt(page, number);
+        if (number === 1) {
+          // Present the committed view as a standalone rollback-mode database.
+          page[18] = 1;
+          page[19] = 1;
+          page.writeUInt32BE(finalPageCount, 28);
+          page.writeUInt32BE(page.readUInt32BE(24), 92);
+        }
+      } catch (err) { page.fill(0); throw err; }
+      cache.set(number, page);
+      if (cache.size > CACHE_PAGES) {
+        const oldest = cache.keys().next().value;
+        cache.get(oldest).fill(0);
+        cache.delete(oldest);
+      }
+      return page;
+    };
+    return {
+      byteLength,
+      read(target, offset) {
+        if (!Number.isSafeInteger(offset) || offset < 0) throw error("invalid read offset.");
+        target.fill(0);
+        const count = Math.min(target.length, Math.max(0, byteLength - offset));
+        let copied = 0;
+        while (copied < count) {
+          const position = offset + copied;
+          const pageOffset = position % pageSize;
+          const length = Math.min(count - copied, pageSize - pageOffset);
+          const page = getPage(Math.floor(position / pageSize) + 1);
+          target.set(page.subarray(pageOffset, pageOffset + length), copied);
+          copied += length;
+        }
+        return count;
+      },
+      isStable() { return paths.map(statOptional).every((stat, i) => sameStat(before[i], stat)); },
+      close,
+    };
+  } catch (err) { close(); throw err; }
+}
+
+module.exports = { openTraeSnapshot };

package/src/lib/trae-sqlite.js

@@ -0,0 +1,143 @@
+const fs = require("node:fs");
+
+let enginePromise;
+let queryQueue = Promise.resolve();
+
+async function createEngine() {
+  const [{ default: initialize }, sqlite, { FacadeVFS }] = await Promise.all([
+    import("@journeyapps/wa-sqlite/dist/wa-sqlite.mjs"),
+    import("@journeyapps/wa-sqlite"),
+    import("@journeyapps/wa-sqlite/src/FacadeVFS.js"),
+  ]);
+  const module = await initialize({
+    wasmBinary: fs.readFileSync(require.resolve("@journeyapps/wa-sqlite/dist/wa-sqlite.wasm")),
+  });
+  const api = sqlite.Factory(module);
+  const snapshots = new Map();
+  const handles = new Map();
+
+  // Register one VFS for the lifetime of the engine. Each query gets a distinct
+  // virtual filename, without accumulating WASM callbacks or touching disk.
+  class TraeVFS extends FacadeVFS {
+    constructor() {
+      super("tokentracker-trae", module);
+    }
+
+    jOpen(name, fileId, flags, outputFlags) {
+      const state = snapshots.get(name);
+      if (!state || !(flags & sqlite.SQLITE_OPEN_MAIN_DB)) return sqlite.SQLITE_CANTOPEN;
+      handles.set(fileId, state);
+      outputFlags.setInt32(0, sqlite.SQLITE_OPEN_READONLY, true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jRead(fileId, output, offset) {
+      const state = handles.get(fileId);
+      if (!state) return sqlite.SQLITE_IOERR_READ;
+      // FacadeVFS passes a proxy over WASM memory, not a native Uint8Array.
+      // Keep the temporary buffer small and erase it after copying its page.
+      const buffer = Buffer.alloc(output.byteLength);
+      try {
+        const count = state.snapshot.read(buffer, offset);
+        if (!Number.isSafeInteger(count) || count < 0 || count > buffer.length) {
+          throw new Error("Invalid TRAE snapshot read length.");
+        }
+        buffer.fill(0, count);
+        output.set(buffer);
+        return count === buffer.length ? sqlite.SQLITE_OK : sqlite.SQLITE_IOERR_SHORT_READ;
+      } catch (err) {
+        state.error ||= err;
+        output.fill(0);
+        return sqlite.SQLITE_IOERR_READ;
+      } finally {
+        buffer.fill(0);
+      }
+    }
+
+    jFileSize(fileId, output) {
+      const state = handles.get(fileId);
+      if (!state) return sqlite.SQLITE_IOERR_FSTAT;
+      output.setBigInt64(0, BigInt(state.snapshot.byteLength), true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jClose(fileId) {
+      handles.delete(fileId);
+      return sqlite.SQLITE_OK;
+    }
+
+    jAccess(name, flags, output) {
+      output.setInt32(0, snapshots.has(name) ? 1 : 0, true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jWrite() { return sqlite.SQLITE_READONLY; }
+    jTruncate() { return sqlite.SQLITE_READONLY; }
+    jDelete() { return sqlite.SQLITE_READONLY; }
+  }
+
+  const vfs = new TraeVFS();
+  api.vfs_register(vfs, false);
+  return { api, sqlite, snapshots, handles, vfs, nextId: 0 };
+}
+
+/**
+ * Query a read-only, random-access snapshot without materializing its database.
+ * The caller owns snapshot cleanup; only the projected SQL rows leave this VFS.
+ */
+async function querySnapshot(snapshot, callback) {
+  if (!Number.isSafeInteger(snapshot.byteLength) || snapshot.byteLength < 0) {
+    throw new Error("Invalid TRAE snapshot size.");
+  }
+  enginePromise ||= createEngine().catch((err) => {
+    enginePromise = undefined;
+    throw err;
+  });
+  const engine = await enginePromise;
+  const { api, sqlite, snapshots, handles, vfs } = engine;
+  const name = `trae-${++engine.nextId}.db`;
+  const state = { snapshot, error: null };
+  snapshots.set(name, state);
+  let db;
+  let failure;
+  try {
+    db = await api.open_v2(name, sqlite.SQLITE_OPEN_READONLY, vfs.name);
+    const query = async (sql) => {
+      const rows = [];
+      try {
+        await api.exec(db, sql, (values, columns) => {
+          rows.push(Object.fromEntries(columns.map((column, index) => [column, values[index]])));
+        });
+      } catch (err) {
+        throw state.error || err;
+      }
+      return rows;
+    };
+    await query("PRAGMA query_only=ON; PRAGMA cache_size=-4096; PRAGMA temp_store=MEMORY;");
+    return await callback(query);
+  } catch (err) {
+    failure = state.error || err;
+    throw failure;
+  } finally {
+    try {
+      if (db) await api.close(db);
+    } catch (err) {
+      if (!failure) throw state.error || err;
+    } finally {
+      snapshots.delete(name);
+      for (const [fileId, opened] of handles) {
+        if (opened === state) handles.delete(fileId);
+      }
+    }
+  }
+}
+
+function withTraeSqlite(snapshot, callback) {
+  // The package's async convenience API shares temporary WASM allocations.
+  // Serialize access to the single engine even when callers read in parallel.
+  const operation = queryQueue.then(() => querySnapshot(snapshot, callback));
+  queryQueue = operation.catch(() => {});
+  return operation;
+}
+
+module.exports = { withTraeSqlite };