getaimeter 0.6.0 → 0.6.1

package/watcher.js

@@ -1,648 +1,711 @@
-'use strict';
-
-const fs     = require('fs');
-const path   = require('path');
-const crypto = require('crypto');
-const { execSync } = require('child_process');
-const { getApiKey, getWatchPaths } = require('./config');
-const { getOffset, setOffset, isDuplicate, save: saveState } = require('./state');
-const { postUsage } = require('./reporter');
-
-// ---------------------------------------------------------------------------
-// Logging
-// ---------------------------------------------------------------------------
-
-const LOG_FILE = path.join(require('./config').AIMETER_DIR, 'watcher.log');
-
-function log(...args) {
-  const ts  = new Date().toISOString();
-  const msg = `[${ts}] ${args.join(' ')}`;
-  console.log(msg);
-  try {
-    fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
-    fs.appendFileSync(LOG_FILE, msg + '\n');
-  } catch {}
-}
-
-function logError(...args) {
-  log('ERROR:', ...args);
-}
-
-// ---------------------------------------------------------------------------
-// Source detection from file path
-// ---------------------------------------------------------------------------
-
-// Cache detected sources per file to avoid re-reading headers
-const _sourceCache = new Map();
-
-// Track cumulative token counts per file for Codex CLI (which reports cumulative, not delta)
-const _codexCumulative = {};
-
-function detectSource(filePath) {
-  if (_sourceCache.has(filePath)) return _sourceCache.get(filePath);
-
-  const normalized = filePath.replace(/\\/g, '/');
-  if (normalized.includes('local-agent-mode-sessions')) {
-    _sourceCache.set(filePath, 'desktop_app');
-    return 'desktop_app';
-  }
-
-  // For subagent files (e.g. .../ceeb9217.../subagents/agent-xxx.jsonl),
-  // inherit the parent session's source. Parent JSONL is at the grandparent dir level.
-  if (normalized.includes('/subagents/')) {
-    // Extract session UUID dir: .../projects/PROJECT/SESSION_UUID/subagents/...
-    const match = normalized.match(/(.+)\/([^/]+)\/subagents\//);
-    if (match) {
-      const projectDir = match[1]; // .../projects/PROJECT
-      const sessionUuid = match[2]; // SESSION_UUID
-      const parentFile = path.join(projectDir.replace(/\//g, path.sep), sessionUuid + '.jsonl');
-      try {
-        if (fs.existsSync(parentFile)) {
-          const parentSource = detectSource(parentFile);
-          _sourceCache.set(filePath, parentSource);
-          return parentSource;
-        }
-      } catch {}
-    }
-  }
-
-  if (normalized.includes('.copilot/') || normalized.includes('/copilot/')) {
-    _sourceCache.set(filePath, 'copilot_cli');
-    return 'copilot_cli';
-  }
-  if (normalized.includes('.gemini/') || normalized.includes('/gemini/')) {
-    _sourceCache.set(filePath, 'gemini_cli');
-    return 'gemini_cli';
-  }
-  if (normalized.includes('.codex/') || normalized.includes('/codex/')) {
-    _sourceCache.set(filePath, 'codex_cli');
-    return 'codex_cli';
-  }
-  if (normalized.includes('/Cursor/') || normalized.includes('/cursor/') || normalized.includes('.cursor/')) {
-    _sourceCache.set(filePath, 'cursor');
-    return 'cursor';
-  }
-
-  // Read first 10KB of the file to find entrypoint or IDE markers
-  let source = 'cli'; // default
-  try {
-    const fd = fs.openSync(filePath, 'r');
-    const buf = Buffer.alloc(Math.min(10240, fs.fstatSync(fd).size));
-    fs.readSync(fd, buf, 0, buf.length, 0);
-    fs.closeSync(fd);
-    const header = buf.toString('utf8');
-
-    if (header.includes('"entrypoint":"claude-desktop"') || header.includes('"entrypoint": "claude-desktop"')) {
-      source = 'desktop_app';
-    } else if (header.includes('ide_opened_file') || header.includes('claude-vscode') || header.includes('"entrypoint":"vscode"') || header.includes('"entrypoint": "vscode"')) {
-      source = 'vscode';
-    }
-    // else remains 'cli'
-  } catch {}
-
-  _sourceCache.set(filePath, source);
-  return source;
-}
-
-// ---------------------------------------------------------------------------
-// JSONL parsing — extract usage from new bytes in a transcript file
-// ---------------------------------------------------------------------------
-
-function extractNewUsage(filePath) {
-  let stat;
-  try { stat = fs.statSync(filePath); } catch { return []; }
-
-  const currentSize = stat.size;
-  const lastOffset  = getOffset(filePath);
-
-  if (currentSize <= lastOffset) return [];
-
-  // Read only the new bytes
-  const fd  = fs.openSync(filePath, 'r');
-  const buf = Buffer.alloc(currentSize - lastOffset);
-  fs.readSync(fd, buf, 0, buf.length, lastOffset);
-  fs.closeSync(fd);
-
-  const text  = buf.toString('utf8');
-  const lines = text.split('\n');
-
-  // If we're reading from mid-file (offset > 0), the first line may be partial
-  if (lastOffset > 0 && lines.length > 0) lines.shift();
-
-  const usageEvents = [];
-  let lineOffset = lastOffset;
-  let pendingThinkingChars = 0; // Track thinking chars from streaming progress messages
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    lineOffset += Buffer.byteLength(line + '\n', 'utf8');
-    if (!trimmed) continue;
-
-    let obj;
-    try { obj = JSON.parse(trimmed); } catch { continue; }
-
-    // Normalize entry: support both direct assistant messages and progress-wrapped
-    // sub-agent messages (where haiku calls appear as type="progress" with the
-    // real message at obj.data.message.message).
-    let msg = null;
-    let msgId = null; // truthy only for progress entries (used for dedup)
-
-    if (obj.type === 'assistant' && obj.message && obj.message.usage) {
-      msg = obj.message;
-    } else if (
-      obj.type === 'progress' &&
-      obj.data && obj.data.message && obj.data.message.message &&
-      obj.data.message.message.usage
-    ) {
-      msg   = obj.data.message.message;
-      msgId = msg.id; // progress fires multiple times; dedup by message ID
-    }
-
-    if (!msg) {
-      // ── Codex CLI format ──────────────────────────────────────────
-      // Codex events have { type: "event", payload: { type: "token_count", ... } }
-      // with cumulative input_tokens, output_tokens, reasoning_tokens, cached_input_tokens
-      if (obj.type === 'event' && obj.payload?.type === 'token_count') {
-        const p = obj.payload;
-        const codexModel = obj.turn_context?.model || 'codex';
-        // Token counts are cumulative per session; we store deltas
-        // Use a per-file tracker for the previous cumulative values
-        const prevKey = filePath;
-        const prev = _codexCumulative[prevKey] || { input: 0, output: 0, reasoning: 0, cached: 0 };
-        const deltaInput = (p.input_tokens || 0) - prev.input;
-        const deltaOutput = (p.output_tokens || 0) - prev.output;
-        const deltaReasoning = (p.reasoning_tokens || 0) - prev.reasoning;
-
-        _codexCumulative[prevKey] = {
-          input: p.input_tokens || 0,
-          output: p.output_tokens || 0,
-          reasoning: p.reasoning_tokens || 0,
-          cached: p.cached_input_tokens || 0,
-        };
-
-        // Skip if no new tokens (duplicate or first read)
-        if (deltaInput <= 0 && deltaOutput <= 0) continue;
-
-        const hashKey = `${filePath}:${lineOffset}:codex:${p.input_tokens}:${p.output_tokens}`;
-        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
-        if (isDuplicate(hash)) continue;
-
-        usageEvents.push({
-          provider:         'openai',
-          model:            codexModel,
-          source:           'codex_cli',
-          inputTokens:      deltaInput,
-          outputTokens:     deltaOutput,
-          thinkingTokens:   deltaReasoning,
-          cacheReadTokens:  0,
-          cacheWriteTokens: 0,
-        });
-        continue;
-      }
-
-      // ── Copilot CLI format ────────────────────────────────────────
-      // Copilot events: { type: "token_usage", input_tokens, output_tokens, reasoning_tokens, model }
-      if (obj.type === 'token_usage' && (obj.input_tokens !== undefined || obj.output_tokens !== undefined)) {
-        const copilotModel = obj.model || 'copilot';
-        const hashKey = `${filePath}:${lineOffset}:copilot:${obj.input_tokens || 0}:${obj.output_tokens || 0}`;
-        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
-        if (isDuplicate(hash)) continue;
-
-        usageEvents.push({
-          provider:         'github',
-          model:            copilotModel,
-          source:           'copilot_cli',
-          inputTokens:      obj.input_tokens || 0,
-          outputTokens:     obj.output_tokens || 0,
-          thinkingTokens:   obj.reasoning_tokens || 0,
-          cacheReadTokens:  0,
-          cacheWriteTokens: 0,
-        });
-        continue;
-      }
-
-      // ── Gemini CLI format ─────────────────────────────────────────
-      // Gemini events may contain usageMetadata: { promptTokenCount, candidatesTokenCount, totalTokenCount }
-      if (obj.usageMetadata && (obj.usageMetadata.promptTokenCount || obj.usageMetadata.candidatesTokenCount)) {
-        const um = obj.usageMetadata;
-        const geminiModel = obj.modelVersion || obj.model || 'gemini';
-        const hashKey = `${filePath}:${lineOffset}:gemini:${um.promptTokenCount || 0}:${um.candidatesTokenCount || 0}`;
-        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
-        if (isDuplicate(hash)) continue;
-
-        usageEvents.push({
-          provider:         'google',
-          model:            geminiModel,
-          source:           'gemini_cli',
-          inputTokens:      um.promptTokenCount || 0,
-          outputTokens:     um.candidatesTokenCount || 0,
-          thinkingTokens:   um.thoughtsTokenCount || 0,
-          cacheReadTokens:  um.cachedContentTokenCount || 0,
-          cacheWriteTokens: 0,
-        });
-        continue;
-      }
-
-      continue;
-    }
-
-    // Skip synthetic/internal messages
-    if (msg.model === '<synthetic>') continue;
-
-    const model = msg.model || '';
-
-    // Check content blocks for thinking tokens and completion status
-    const contentBlocks = msg.content || [];
-    const hasTextContent = contentBlocks.some(b => b.type === 'text' || b.type === 'tool_use');
-    for (const block of contentBlocks) {
-      if (block.type === 'thinking' && block.thinking) {
-        pendingThinkingChars = Math.max(pendingThinkingChars, block.thinking.length);
-      }
-    }
-
-    // Skip streaming in-progress messages:
-    // Null stop_reason with ONLY thinking content = streaming reasoning still in progress.
-    // Null stop_reason WITH text/tool_use content = complete response (e.g., haiku sub-agent
-    // calls that never receive a stop_reason in the JSONL but are finished).
-    if (!msg.stop_reason && !hasTextContent) continue;
-
-    const u = msg.usage;
-
-    // Estimate thinking tokens: ~4 chars per token (conservative estimate)
-    // The API doesn't separate thinking_tokens in the JSONL usage field
-    const estimatedThinkingTokens = pendingThinkingChars > 0
-      ? Math.ceil(pendingThinkingChars / 4)
-      : 0;
-    pendingThinkingChars = 0; // Reset for next turn
-
-    // Build dedup hash.
-    // For entries with a message ID (progress or assistant), use ONLY the message
-    // ID so the same call is counted once even if it appears in both the parent
-    // session file (as progress) and the subagent file (as assistant).
-    // For entries without an ID, fall back to file+offset.
-    const effectiveId = msgId || msg.id;
-    const hashKey = effectiveId
-      ? `msgid:${effectiveId}`
-      : `${filePath}:${lineOffset}:${model}:${u.input_tokens || 0}:${u.output_tokens || 0}`;
-    const hash = crypto.createHash('md5').update(hashKey).digest('hex');
-
-    if (isDuplicate(hash)) continue;
-
-    usageEvents.push({
-      provider:         'anthropic',
-      model,
-      source:           detectSource(filePath),
-      inputTokens:      u.input_tokens               || 0,
-      outputTokens:     u.output_tokens              || 0,
-      thinkingTokens:   estimatedThinkingTokens,
-      cacheReadTokens:  u.cache_read_input_tokens    || 0,
-      cacheWriteTokens: u.cache_creation_input_tokens || 0,
-    });
-  }
-
-  // Update offset to current file size
-  setOffset(filePath, currentSize);
-
-  return usageEvents;
-}
-
-// ---------------------------------------------------------------------------
-// Cursor IDE — extract usage from SQLite state.vscdb
-// ---------------------------------------------------------------------------
-
-// Track last-seen composerData keys to detect new conversations
-const _cursorSeenKeys = new Set();
-let _cursorSqliteAvailable = null; // null = unchecked, true/false after first check
-
-function isSqliteAvailable() {
-  if (_cursorSqliteAvailable !== null) return _cursorSqliteAvailable;
-  try {
-    execSync('sqlite3 --version', { stdio: 'pipe', timeout: 5000 });
-    _cursorSqliteAvailable = true;
-  } catch {
-    _cursorSqliteAvailable = false;
-    log('sqlite3 CLI not found — Cursor tracking disabled. Install sqlite3 to enable.');
-  }
-  return _cursorSqliteAvailable;
-}
-
-function extractCursorUsage(dbPath) {
-  if (!isSqliteAvailable()) return [];
-  if (!fs.existsSync(dbPath)) return [];
-
-  // Check if the DB file has been modified since our last check
-  let stat;
-  try { stat = fs.statSync(dbPath); } catch { return []; }
-  const currentMtime = stat.mtimeMs;
-  const lastMtime = getOffset(dbPath + ':mtime');
-  if (currentMtime <= lastMtime) return [];
-
-  const usageEvents = [];
-
-  try {
-    // Query composerData entries from Cursor's KV store
-    // Each entry has usageData with per-model cost and count
-    const raw = execSync(
-      `sqlite3 "${dbPath}" "SELECT key, value FROM cursorDiskKV WHERE key LIKE 'composerData:%'"`,
-      { timeout: 10000, maxBuffer: 50 * 1024 * 1024, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
-    );
-
-    if (!raw || !raw.trim()) {
-      setOffset(dbPath + ':mtime', currentMtime);
-      return [];
-    }
-
-    for (const line of raw.split('\n')) {
-      if (!line.trim()) continue;
-
-      // sqlite3 outputs "key|value" with pipe separator
-      const sepIdx = line.indexOf('|');
-      if (sepIdx < 0) continue;
-
-      const key = line.substring(0, sepIdx);
-      const valueStr = line.substring(sepIdx + 1);
-
-      // Skip already-seen conversations
-      if (_cursorSeenKeys.has(key)) continue;
-
-      let data;
-      try { data = JSON.parse(valueStr); } catch { continue; }
-
-      // Extract usage from composerData.usageData
-      // Format: { "model-name": { costInCents: 0.42, amount: 1 }, ... }
-      const usage = data.usageData;
-      if (!usage || typeof usage !== 'object') {
-        _cursorSeenKeys.add(key);
-        continue;
-      }
-
-      const composerId = data.composerId || key;
-      const timestamp = data.lastUpdatedAt || data.createdAt;
-
-      for (const [model, stats] of Object.entries(usage)) {
-        if (!stats || typeof stats !== 'object') continue;
-
-        const costCents = stats.costInCents || 0;
-        const amount = stats.amount || 0;
-        if (costCents <= 0 && amount <= 0) continue;
-
-        const hashKey = `cursor:${composerId}:${model}:${costCents}:${amount}`;
-        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
-        if (isDuplicate(hash)) continue;
-
-        // Determine provider from model name
-        let provider = 'openai'; // default — Cursor uses OpenAI models primarily
-        if (model.includes('claude') || model.includes('anthropic')) {
-          provider = 'anthropic';
-        } else if (model.includes('gemini')) {
-          provider = 'google';
-        }
-
-        // Estimate tokens from cost (rough inverse of pricing)
-        // costInCents is total cost. We don't have exact input/output split,
-        // so we attribute it all as output tokens for a rough estimate.
-        // Using mid-range pricing for estimation: ~$10/M tokens average
-        const estimatedTokens = Math.round((costCents / 100) / (10 / 1_000_000));
-
-        usageEvents.push({
-          provider,
-          model,
-          source:           'cursor',
-          inputTokens:      0,
-          outputTokens:     estimatedTokens > 0 ? estimatedTokens : amount * 500, // fallback: ~500 tokens per request
-          thinkingTokens:   0,
-          cacheReadTokens:  0,
-          cacheWriteTokens: 0,
-        });
-      }
-
-      _cursorSeenKeys.add(key);
-    }
-  } catch (err) {
-    // SQLite might be locked by Cursor — this is normal, retry next poll
-    if (!err.message.includes('database is locked')) {
-      logError('Cursor SQLite read error:', err.message);
-    }
-  }
-
-  setOffset(dbPath + ':mtime', currentMtime);
-  return usageEvents;
-}
-
-// ---------------------------------------------------------------------------
-// Report usage events to backend
-// ---------------------------------------------------------------------------
-
-async function sleep(ms) {
-  return new Promise(r => setTimeout(r, ms));
-}
-
-async function reportEvents(events) {
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    logError('No API key configured. Run: aimeter setup');
-    return;
-  }
-
-  for (const evt of events) {
-    let attempt = 0;
-    while (attempt < 4) {
-      const result = await postUsage(apiKey, evt);
-      if (result.ok) {
-        log(`Reported: ${evt.source} ${evt.model} in=${evt.inputTokens} out=${evt.outputTokens} cache_r=${evt.cacheReadTokens}`);
-        break;
-      } else if (result.status === 429) {
-        attempt++;
-        const wait = attempt * 15_000; // 15s, 30s, 45s
-        logError(`Rate limited (429). Retry ${attempt}/3 in ${wait / 1000}s...`);
-        await sleep(wait);
-      } else {
-        logError(`Failed to report: HTTP ${result.status} ${result.error || ''}`);
-        break;
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// File watcher
-// ---------------------------------------------------------------------------
-
-/**
- * Process a single file: extract new usage and report it.
- * Called only from the poll loop — single-threaded, no races.
- */
-async function processFile(filePath) {
-  try {
-    const events = extractNewUsage(filePath);
-    if (events.length > 0) {
-      await reportEvents(events);
-      saveState();
-    }
-  } catch (err) {
-    logError(`Processing ${filePath}:`, err.message);
-  }
-}
-
-/**
- * Recursively find all .jsonl files under a directory.
- */
-function findJsonlFiles(dir) {
-  const results = [];
-  let entries;
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
-
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      results.push(...findJsonlFiles(full));
-    } else if (entry.name.endsWith('.jsonl')) {
-      results.push(full);
-    }
-  }
-  return results;
-}
-
-/**
- * Find Cursor state.vscdb files in watch paths.
- */
-function findCursorDbs(dirs) {
-  const results = [];
-  for (const dir of dirs) {
-    const vscdb = path.join(dir, 'state.vscdb');
-    if (fs.existsSync(vscdb)) {
-      results.push(vscdb);
-    }
-  }
-  return results;
-}
-
-/**
- * Start watching all configured paths.
- * Returns a cleanup function.
- */
-function startWatching() {
-  const watchPaths = getWatchPaths();
-
-  if (watchPaths.length === 0) {
-    logError('No AI tool directories found. Is Claude Code, Cursor, Codex, or Gemini CLI installed?');
-    process.exit(1);
-  }
-
-  log('AIMeter Watcher starting...');
-  log('Watching:', watchPaths.join(', '));
-
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    log('WARNING: No API key found. Usage will not be reported.');
-    log('Run: aimeter setup');
-  } else {
-    log('API key:', apiKey.slice(0, 8) + '...' + apiKey.slice(-4));
-  }
-
-  // Initial scan: mark existing files as "already read" so we only report
-  // NEW usage going forward. Without this, first run floods the backend.
-  const { load: loadState } = require('./state');
-  const state = loadState();
-  const isFirstRun = Object.keys(state.fileOffsets || {}).length === 0;
-
-  let filesMarked = 0;
-  for (const watchPath of watchPaths) {
-    const files = findJsonlFiles(watchPath);
-    for (const file of files) {
-      if (isFirstRun) {
-        // First run: skip to end of all files
-        try {
-          const size = fs.statSync(file).size;
-          setOffset(file, size);
-          filesMarked++;
-        } catch {}
-      } else {
-        // Subsequent runs: process new data since last offset
-        const events = extractNewUsage(file);
-        if (events.length > 0) {
-          reportEvents(events);
-          filesMarked += events.length;
-        }
-      }
-    }
-  }
-  if (isFirstRun) {
-    log(`First run: marked ${filesMarked} existing files as read. Only new usage will be reported.`);
-  } else if (filesMarked > 0) {
-    log(`Catch-up: processed ${filesMarked} new events since last run`);
-  }
-  saveState();
-
-  // Poll every 5 seconds — simple, reliable, no race conditions.
-  // fs.watch is unreliable on Windows for deeply nested dirs and fires duplicates.
-  const POLL_INTERVAL = 5_000;
-  let polling = false;
-
-  // Find Cursor DBs once at startup
-  const cursorDbs = findCursorDbs(watchPaths);
-  if (cursorDbs.length > 0) {
-    log('Cursor databases found:', cursorDbs.join(', '));
-    // Mark existing Cursor data as seen on first run
-    if (isFirstRun) {
-      for (const dbPath of cursorDbs) {
-        try {
-          const mtime = fs.statSync(dbPath).mtimeMs;
-          setOffset(dbPath + ':mtime', mtime);
-          // Pre-populate seen keys so we don't report historical data
-          extractCursorUsage(dbPath); // populates _cursorSeenKeys but we discard results
-        } catch {}
-      }
-      log('Cursor: marked existing conversations as read');
-    }
-  }
-
-  const pollInterval = setInterval(async () => {
-    if (polling) return; // skip if previous poll still running
-    polling = true;
-    try {
-      // Poll JSONL files (Claude, Codex, Gemini, etc.)
-      for (const watchPath of watchPaths) {
-        const files = findJsonlFiles(watchPath);
-        for (const file of files) {
-          try {
-            const currentSize = fs.statSync(file).size;
-            const lastOffset  = getOffset(file);
-            if (currentSize > lastOffset) {
-              await processFile(file);
-            }
-          } catch {}
-        }
-      }
-
-      // Poll Cursor SQLite databases
-      for (const dbPath of cursorDbs) {
-        try {
-          const events = extractCursorUsage(dbPath);
-          if (events.length > 0) {
-            await reportEvents(events);
-            saveState();
-          }
-        } catch (err) {
-          logError('Cursor poll error:', err.message);
-        }
-      }
-    } finally {
-      polling = false;
-    }
-  }, POLL_INTERVAL);
-  log(`Polling every ${POLL_INTERVAL / 1000}s`);
-
-  // Periodic state save
-  const saveInterval = setInterval(() => saveState(), 30_000);
-
-  // Return cleanup
-  return () => {
-    clearInterval(saveInterval);
-    clearInterval(pollInterval);
-    saveState();
-    log('Watcher stopped.');
-  };
-}
-
-module.exports = { startWatching };
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const { getApiKey, getWatchPaths } = require('./config');
+const { getOffset, setOffset, isDuplicate, save: saveState } = require('./state');
+const { postUsage } = require('./reporter');
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
+const LOG_FILE = path.join(require('./config').AIMETER_DIR, 'watcher.log');
+
+function log(...args) {
+  const ts  = new Date().toISOString();
+  const msg = `[${ts}] ${args.join(' ')}`;
+  console.log(msg);
+  try {
+    fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+    fs.appendFileSync(LOG_FILE, msg + '\n');
+  } catch {}
+}
+
+function logError(...args) {
+  log('ERROR:', ...args);
+}
+
+// ---------------------------------------------------------------------------
+// Source detection from file path
+// ---------------------------------------------------------------------------
+
+// Cache detected sources per file to avoid re-reading headers
+const _sourceCache = new Map();
+
+// Track cumulative token counts per file for Codex CLI (which reports cumulative, not delta)
+const _codexCumulative = {};
+
+function detectSource(filePath) {
+  if (_sourceCache.has(filePath)) return _sourceCache.get(filePath);
+
+  const normalized = filePath.replace(/\\/g, '/');
+  if (normalized.includes('local-agent-mode-sessions')) {
+    _sourceCache.set(filePath, 'desktop_app');
+    return 'desktop_app';
+  }
+
+  // For subagent files (e.g. .../ceeb9217.../subagents/agent-xxx.jsonl),
+  // inherit the parent session's source. Parent JSONL is at the grandparent dir level.
+  if (normalized.includes('/subagents/')) {
+    // Extract session UUID dir: .../projects/PROJECT/SESSION_UUID/subagents/...
+    const match = normalized.match(/(.+)\/([^/]+)\/subagents\//);
+    if (match) {
+      const projectDir = match[1]; // .../projects/PROJECT
+      const sessionUuid = match[2]; // SESSION_UUID
+      const parentFile = path.join(projectDir.replace(/\//g, path.sep), sessionUuid + '.jsonl');
+      try {
+        if (fs.existsSync(parentFile)) {
+          const parentSource = detectSource(parentFile);
+          _sourceCache.set(filePath, parentSource);
+          return parentSource;
+        }
+      } catch {}
+    }
+  }
+
+  if (normalized.includes('.copilot/') || normalized.includes('/copilot/')) {
+    _sourceCache.set(filePath, 'copilot_cli');
+    return 'copilot_cli';
+  }
+  if (normalized.includes('.gemini/') || normalized.includes('/gemini/')) {
+    _sourceCache.set(filePath, 'gemini_cli');
+    return 'gemini_cli';
+  }
+  if (normalized.includes('.codex/') || normalized.includes('/codex/')) {
+    _sourceCache.set(filePath, 'codex_cli');
+    return 'codex_cli';
+  }
+  if (normalized.includes('/Cursor/') || normalized.includes('/cursor/') || normalized.includes('.cursor/')) {
+    _sourceCache.set(filePath, 'cursor');
+    return 'cursor';
+  }
+
+  // Read first 10KB of the file to find entrypoint or IDE markers
+  let source = 'cli'; // default
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(Math.min(10240, fs.fstatSync(fd).size));
+    fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    const header = buf.toString('utf8');
+
+    if (header.includes('"entrypoint":"claude-desktop"') || header.includes('"entrypoint": "claude-desktop"')) {
+      source = 'desktop_app';
+    } else if (header.includes('ide_opened_file') || header.includes('claude-vscode') || header.includes('"entrypoint":"vscode"') || header.includes('"entrypoint": "vscode"')) {
+      source = 'vscode';
+    }
+    // else remains 'cli'
+  } catch {}
+
+  _sourceCache.set(filePath, source);
+  return source;
+}
+
+// ---------------------------------------------------------------------------
+// JSONL parsing — extract usage from new bytes in a transcript file
+// ---------------------------------------------------------------------------
+
+function extractNewUsage(filePath) {
+  let stat;
+  try { stat = fs.statSync(filePath); } catch { return []; }
+
+  const currentSize = stat.size;
+  const lastOffset  = getOffset(filePath);
+
+  if (currentSize <= lastOffset) return [];
+
+  // Read only the new bytes
+  const fd  = fs.openSync(filePath, 'r');
+  const buf = Buffer.alloc(currentSize - lastOffset);
+  fs.readSync(fd, buf, 0, buf.length, lastOffset);
+  fs.closeSync(fd);
+
+  const text  = buf.toString('utf8');
+  const lines = text.split('\n');
+
+  // If we're reading from mid-file (offset > 0), the first line may be partial
+  if (lastOffset > 0 && lines.length > 0) lines.shift();
+
+  const usageEvents = [];
+  let lineOffset = lastOffset;
+  let pendingThinkingChars = 0; // Track thinking chars from streaming progress messages
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    lineOffset += Buffer.byteLength(line + '\n', 'utf8');
+    if (!trimmed) continue;
+
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+
+    // Normalize entry: support both direct assistant messages and progress-wrapped
+    // sub-agent messages (where haiku calls appear as type="progress" with the
+    // real message at obj.data.message.message).
+    let msg = null;
+    let msgId = null; // truthy only for progress entries (used for dedup)
+
+    if (obj.type === 'assistant' && obj.message && obj.message.usage) {
+      msg = obj.message;
+    } else if (
+      obj.type === 'progress' &&
+      obj.data && obj.data.message && obj.data.message.message &&
+      obj.data.message.message.usage
+    ) {
+      msg   = obj.data.message.message;
+      msgId = msg.id; // progress fires multiple times; dedup by message ID
+    }
+
+    if (!msg) {
+      // ── Codex CLI format ──────────────────────────────────────────
+      // Codex events have { type: "event", payload: { type: "token_count", ... } }
+      // with cumulative input_tokens, output_tokens, reasoning_tokens, cached_input_tokens
+      if (obj.type === 'event' && obj.payload?.type === 'token_count') {
+        const p = obj.payload;
+        const codexModel = obj.turn_context?.model || 'codex';
+        // Token counts are cumulative per session; we store deltas
+        // Use a per-file tracker for the previous cumulative values
+        const prevKey = filePath;
+        const prev = _codexCumulative[prevKey] || { input: 0, output: 0, reasoning: 0, cached: 0 };
+        const deltaInput = (p.input_tokens || 0) - prev.input;
+        const deltaOutput = (p.output_tokens || 0) - prev.output;
+        const deltaReasoning = (p.reasoning_tokens || 0) - prev.reasoning;
+
+        _codexCumulative[prevKey] = {
+          input: p.input_tokens || 0,
+          output: p.output_tokens || 0,
+          reasoning: p.reasoning_tokens || 0,
+          cached: p.cached_input_tokens || 0,
+        };
+
+        // Skip if no new tokens (duplicate or first read)
+        if (deltaInput <= 0 && deltaOutput <= 0) continue;
+
+        const hashKey = `${filePath}:${lineOffset}:codex:${p.input_tokens}:${p.output_tokens}`;
+        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
+        if (isDuplicate(hash)) continue;
+
+        usageEvents.push({
+          provider:         'openai',
+          model:            codexModel,
+          source:           'codex_cli',
+          inputTokens:      deltaInput,
+          outputTokens:     deltaOutput,
+          thinkingTokens:   deltaReasoning,
+          cacheReadTokens:  0,
+          cacheWriteTokens: 0,
+        });
+        continue;
+      }
+
+      // ── Copilot CLI format ────────────────────────────────────────
+      // Copilot events: { type: "token_usage", input_tokens, output_tokens, reasoning_tokens, model }
+      if (obj.type === 'token_usage' && (obj.input_tokens !== undefined || obj.output_tokens !== undefined)) {
+        const copilotModel = obj.model || 'copilot';
+        const hashKey = `${filePath}:${lineOffset}:copilot:${obj.input_tokens || 0}:${obj.output_tokens || 0}`;
+        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
+        if (isDuplicate(hash)) continue;
+
+        usageEvents.push({
+          provider:         'github',
+          model:            copilotModel,
+          source:           'copilot_cli',
+          inputTokens:      obj.input_tokens || 0,
+          outputTokens:     obj.output_tokens || 0,
+          thinkingTokens:   obj.reasoning_tokens || 0,
+          cacheReadTokens:  0,
+          cacheWriteTokens: 0,
+        });
+        continue;
+      }
+
+      // ── Gemini CLI format ─────────────────────────────────────────
+      // Gemini events may contain usageMetadata: { promptTokenCount, candidatesTokenCount, totalTokenCount }
+      if (obj.usageMetadata && (obj.usageMetadata.promptTokenCount || obj.usageMetadata.candidatesTokenCount)) {
+        const um = obj.usageMetadata;
+        const geminiModel = obj.modelVersion || obj.model || 'gemini';
+        const hashKey = `${filePath}:${lineOffset}:gemini:${um.promptTokenCount || 0}:${um.candidatesTokenCount || 0}`;
+        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
+        if (isDuplicate(hash)) continue;
+
+        usageEvents.push({
+          provider:         'google',
+          model:            geminiModel,
+          source:           'gemini_cli',
+          inputTokens:      um.promptTokenCount || 0,
+          outputTokens:     um.candidatesTokenCount || 0,
+          thinkingTokens:   um.thoughtsTokenCount || 0,
+          cacheReadTokens:  um.cachedContentTokenCount || 0,
+          cacheWriteTokens: 0,
+        });
+        continue;
+      }
+
+      continue;
+    }
+
+    // Skip synthetic/internal messages
+    if (msg.model === '<synthetic>') continue;
+
+    const model = msg.model || '';
+
+    // Check content blocks for thinking tokens and completion status
+    const contentBlocks = msg.content || [];
+    const hasTextContent = contentBlocks.some(b => b.type === 'text' || b.type === 'tool_use');
+    for (const block of contentBlocks) {
+      if (block.type === 'thinking' && block.thinking) {
+        pendingThinkingChars = Math.max(pendingThinkingChars, block.thinking.length);
+      }
+    }
+
+    // Skip streaming in-progress messages:
+    // Null stop_reason with ONLY thinking content = streaming reasoning still in progress.
+    // Null stop_reason WITH text/tool_use content = complete response (e.g., haiku sub-agent
+    // calls that never receive a stop_reason in the JSONL but are finished).
+    if (!msg.stop_reason && !hasTextContent) continue;
+
+    const u = msg.usage;
+
+    // Estimate thinking tokens: ~4 chars per token (conservative estimate)
+    // The API doesn't separate thinking_tokens in the JSONL usage field
+    const estimatedThinkingTokens = pendingThinkingChars > 0
+      ? Math.ceil(pendingThinkingChars / 4)
+      : 0;
+    pendingThinkingChars = 0; // Reset for next turn
+
+    // Build dedup hash.
+    // For entries with a message ID (progress or assistant), use ONLY the message
+    // ID so the same call is counted once even if it appears in both the parent
+    // session file (as progress) and the subagent file (as assistant).
+    // For entries without an ID, fall back to file+offset.
+    const effectiveId = msgId || msg.id;
+    const hashKey = effectiveId
+      ? `msgid:${effectiveId}`
+      : `${filePath}:${lineOffset}:${model}:${u.input_tokens || 0}:${u.output_tokens || 0}`;
+    const hash = crypto.createHash('md5').update(hashKey).digest('hex');
+
+    if (isDuplicate(hash)) continue;
+
+    usageEvents.push({
+      provider:         'anthropic',
+      model,
+      source:           detectSource(filePath),
+      inputTokens:      u.input_tokens               || 0,
+      outputTokens:     u.output_tokens              || 0,
+      thinkingTokens:   estimatedThinkingTokens,
+      cacheReadTokens:  u.cache_read_input_tokens    || 0,
+      cacheWriteTokens: u.cache_creation_input_tokens || 0,
+    });
+  }
+
+  // Update offset to current file size
+  setOffset(filePath, currentSize);
+
+  return usageEvents;
+}
+
+// ---------------------------------------------------------------------------
+// Cursor IDE — extract usage from SQLite state.vscdb
+// ---------------------------------------------------------------------------
+
+// Track last-seen composerData keys to detect new conversations
+const _cursorSeenKeys = new Set();
+let _cursorSqliteAvailable = null; // null = unchecked, true/false after first check
+
+// Locate sqlite3 binary — may be in PATH or in the WinGet install location
+let _sqlite3Path = null;
+
+function findSqlite3() {
+  if (_cursorSqliteAvailable !== null) return _cursorSqliteAvailable;
+
+  // Try bare command first
+  try {
+    execSync('sqlite3 --version', { stdio: 'pipe', timeout: 5000 });
+    _sqlite3Path = 'sqlite3';
+    _cursorSqliteAvailable = true;
+    return true;
+  } catch {}
+
+  // Windows: check WinGet install location
+  if (process.platform === 'win32') {
+    const wingetDir = path.join(process.env.LOCALAPPDATA || '', 'Microsoft', 'WinGet', 'Packages');
+    try {
+      const entries = fs.readdirSync(wingetDir);
+      for (const entry of entries) {
+        if (entry.startsWith('SQLite.SQLite')) {
+          const candidate = path.join(wingetDir, entry, 'sqlite3.exe');
+          if (fs.existsSync(candidate)) {
+            _sqlite3Path = candidate;
+            _cursorSqliteAvailable = true;
+            return true;
+          }
+        }
+      }
+    } catch {}
+  }
+
+  _cursorSqliteAvailable = false;
+  log('sqlite3 CLI not found — Cursor tracking disabled. Install sqlite3 to enable.');
+  return false;
+}
+
+function runSqlite(dbPath, query) {
+  // Write query to temp file to avoid shell escaping nightmares on Windows
+  const tmpFile = path.join(require('os').tmpdir(), `aimeter_sql_${Date.now()}.sql`);
+  try {
+    fs.writeFileSync(tmpFile, query + ';\n');
+    return execSync(`"${_sqlite3Path}" "${dbPath}" < "${tmpFile}"`, {
+      timeout: 10000,
+      maxBuffer: 50 * 1024 * 1024,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true,
+    });
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
+function extractCursorUsage(dbPath) {
+  if (!findSqlite3()) return [];
+  if (!fs.existsSync(dbPath)) return [];
+
+  // Check if the DB file has been modified since our last check
+  let stat;
+  try { stat = fs.statSync(dbPath); } catch { return []; }
+  const currentMtime = stat.mtimeMs;
+  const lastMtime = getOffset(dbPath + ':mtime');
+  if (currentMtime <= lastMtime) return [];
+
+  const usageEvents = [];
+
+  try {
+    // Cursor v11 schema: usageData is always empty, tokenCount is always 0.
+    // Strategy: query composerData for model + timestamp, then count AI bubbles
+    // and measure their text length to estimate tokens.
+    //
+    // Query: join composerData (for model) with bubble count + total text length
+    // We use a simpler approach: get conversations, then get their bubble stats.
+
+    // Step 1: Get conversations with model info
+    const composerRaw = runSqlite(dbPath,
+      "SELECT key, json_extract(value, '$.composerId'), json_extract(value, '$.modelConfig.modelName'), json_extract(value, '$.createdAt') FROM cursorDiskKV WHERE key LIKE 'composerData:%'"
+    );
+
+    if (!composerRaw || !composerRaw.trim()) {
+      setOffset(dbPath + ':mtime', currentMtime);
+      return [];
+    }
+
+    const conversations = [];
+    for (const line of composerRaw.split('\n')) {
+      if (!line.trim()) continue;
+      const parts = line.split('|');
+      if (parts.length < 4) continue;
+      const [key, composerId, modelName, createdAt] = parts;
+      if (_cursorSeenKeys.has(key)) continue;
+      conversations.push({ key, composerId, modelName: modelName || 'default', createdAt: parseInt(createdAt) || 0 });
+    }
+
+    if (conversations.length === 0) {
+      setOffset(dbPath + ':mtime', currentMtime);
+      return [];
+    }
+
+    // Step 2: For new conversations, count AI response bubbles and measure text
+    for (const conv of conversations) {
+      try {
+        // Count AI responses (type=2) and sum their text lengths
+        const bubbleRaw = runSqlite(dbPath,
+          `SELECT count(*), sum(length(json_extract(value, '$.text'))) FROM cursorDiskKV WHERE key LIKE 'bubbleId:${conv.composerId}:%' AND json_extract(value, '$.type') = 2`
+        );
+
+        if (!bubbleRaw || !bubbleRaw.trim()) {
+          _cursorSeenKeys.add(conv.key);
+          continue;
+        }
+
+        const [countStr, textLenStr] = bubbleRaw.trim().split('|');
+        const responseCount = parseInt(countStr) || 0;
+        const totalTextLen = parseInt(textLenStr) || 0;
+
+        if (responseCount === 0) {
+          _cursorSeenKeys.add(conv.key);
+          continue;
+        }
+
+        // Also count user messages for input estimation
+        const userRaw = runSqlite(dbPath,
+          `SELECT sum(length(json_extract(value, '$.text'))) FROM cursorDiskKV WHERE key LIKE 'bubbleId:${conv.composerId}:%' AND json_extract(value, '$.type') = 1`
+        );
+        const userTextLen = parseInt((userRaw || '').trim()) || 0;
+
+        // Estimate tokens: ~4 chars per token
+        const estimatedInputTokens = Math.ceil(userTextLen / 4);
+        const estimatedOutputTokens = Math.ceil(totalTextLen / 4);
+
+        if (estimatedInputTokens === 0 && estimatedOutputTokens === 0) {
+          _cursorSeenKeys.add(conv.key);
+          continue;
+        }
+
+        const hashKey = `cursor:${conv.composerId}:${responseCount}:${totalTextLen}`;
+        const hash = crypto.createHash('md5').update(hashKey).digest('hex');
+        if (isDuplicate(hash)) {
+          _cursorSeenKeys.add(conv.key);
+          continue;
+        }
+
+        // Determine provider from model name
+        let provider = 'openai';
+        let model = conv.modelName;
+        if (model === 'default') model = 'cursor-default';
+        if (model.includes('claude') || model.includes('anthropic')) {
+          provider = 'anthropic';
+        } else if (model.includes('gemini')) {
+          provider = 'google';
+        }
+
+        usageEvents.push({
+          provider,
+          model,
+          source:           'cursor',
+          inputTokens:      estimatedInputTokens,
+          outputTokens:     estimatedOutputTokens,
+          thinkingTokens:   0,
+          cacheReadTokens:  0,
+          cacheWriteTokens: 0,
+        });
+      } catch {}
+
+      _cursorSeenKeys.add(conv.key);
+    }
+  } catch (err) {
+    if (!err.message.includes('database is locked')) {
+      logError('Cursor SQLite read error:', err.message);
+    }
+  }
+
+  setOffset(dbPath + ':mtime', currentMtime);
+  return usageEvents;
+}
+
+// ---------------------------------------------------------------------------
+// Report usage events to backend
+// ---------------------------------------------------------------------------
+
+async function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+async function reportEvents(events) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    logError('No API key configured. Run: aimeter setup');
+    return;
+  }
+
+  for (const evt of events) {
+    let attempt = 0;
+    while (attempt < 4) {
+      const result = await postUsage(apiKey, evt);
+      if (result.ok) {
+        log(`Reported: ${evt.source} ${evt.model} in=${evt.inputTokens} out=${evt.outputTokens} cache_r=${evt.cacheReadTokens}`);
+        break;
+      } else if (result.status === 429) {
+        attempt++;
+        const wait = attempt * 15_000; // 15s, 30s, 45s
+        logError(`Rate limited (429). Retry ${attempt}/3 in ${wait / 1000}s...`);
+        await sleep(wait);
+      } else {
+        logError(`Failed to report: HTTP ${result.status} ${result.error || ''}`);
+        break;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File watcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a single file: extract new usage and report it.
+ * Called only from the poll loop — single-threaded, no races.
+ */
+async function processFile(filePath) {
+  try {
+    const events = extractNewUsage(filePath);
+    if (events.length > 0) {
+      await reportEvents(events);
+      saveState();
+    }
+  } catch (err) {
+    logError(`Processing ${filePath}:`, err.message);
+  }
+}
+
+/**
+ * Recursively find all .jsonl files under a directory.
+ */
+function findJsonlFiles(dir) {
+  const results = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findJsonlFiles(full));
+    } else if (entry.name.endsWith('.jsonl')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Find Cursor state.vscdb files in watch paths.
+ */
+function findCursorDbs(dirs) {
+  const results = [];
+  for (const dir of dirs) {
+    const vscdb = path.join(dir, 'state.vscdb');
+    if (fs.existsSync(vscdb)) {
+      results.push(vscdb);
+    }
+  }
+  return results;
+}
+
+/**
+ * Start watching all configured paths.
+ * Returns a cleanup function.
+ */
+function startWatching() {
+  const watchPaths = getWatchPaths();
+
+  if (watchPaths.length === 0) {
+    logError('No AI tool directories found. Is Claude Code, Cursor, Codex, or Gemini CLI installed?');
+    process.exit(1);
+  }
+
+  log('AIMeter Watcher starting...');
+  log('Watching:', watchPaths.join(', '));
+
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    log('WARNING: No API key found. Usage will not be reported.');
+    log('Run: aimeter setup');
+  } else {
+    log('API key:', apiKey.slice(0, 8) + '...' + apiKey.slice(-4));
+  }
+
+  // Initial scan: mark existing files as "already read" so we only report
+  // NEW usage going forward. Without this, first run floods the backend.
+  const { load: loadState } = require('./state');
+  const state = loadState();
+  const isFirstRun = Object.keys(state.fileOffsets || {}).length === 0;
+
+  let filesMarked = 0;
+  for (const watchPath of watchPaths) {
+    const files = findJsonlFiles(watchPath);
+    for (const file of files) {
+      if (isFirstRun) {
+        // First run: skip to end of all files
+        try {
+          const size = fs.statSync(file).size;
+          setOffset(file, size);
+          filesMarked++;
+        } catch {}
+      } else {
+        // Subsequent runs: process new data since last offset
+        const events = extractNewUsage(file);
+        if (events.length > 0) {
+          reportEvents(events);
+          filesMarked += events.length;
+        }
+      }
+    }
+  }
+  if (isFirstRun) {
+    log(`First run: marked ${filesMarked} existing files as read. Only new usage will be reported.`);
+  } else if (filesMarked > 0) {
+    log(`Catch-up: processed ${filesMarked} new events since last run`);
+  }
+  saveState();
+
+  // Poll every 5 seconds — simple, reliable, no race conditions.
+  // fs.watch is unreliable on Windows for deeply nested dirs and fires duplicates.
+  const POLL_INTERVAL = 5_000;
+  let polling = false;
+
+  // Find Cursor DBs once at startup
+  const cursorDbs = findCursorDbs(watchPaths);
+  if (cursorDbs.length > 0) {
+    log('Cursor databases found:', cursorDbs.join(', '));
+    // Mark existing Cursor data as seen on first run
+    if (isFirstRun) {
+      for (const dbPath of cursorDbs) {
+        try {
+          const mtime = fs.statSync(dbPath).mtimeMs;
+          setOffset(dbPath + ':mtime', mtime);
+          // Pre-populate seen keys so we don't report historical data
+          extractCursorUsage(dbPath); // populates _cursorSeenKeys but we discard results
+        } catch {}
+      }
+      log('Cursor: marked existing conversations as read');
+    }
+  }
+
+  const pollInterval = setInterval(async () => {
+    if (polling) return; // skip if previous poll still running
+    polling = true;
+    try {
+      // Poll JSONL files (Claude, Codex, Gemini, etc.)
+      for (const watchPath of watchPaths) {
+        const files = findJsonlFiles(watchPath);
+        for (const file of files) {
+          try {
+            const currentSize = fs.statSync(file).size;
+            const lastOffset  = getOffset(file);
+            if (currentSize > lastOffset) {
+              await processFile(file);
+            }
+          } catch {}
+        }
+      }
+
+      // Poll Cursor SQLite databases
+      for (const dbPath of cursorDbs) {
+        try {
+          const events = extractCursorUsage(dbPath);
+          if (events.length > 0) {
+            await reportEvents(events);
+            saveState();
+          }
+        } catch (err) {
+          logError('Cursor poll error:', err.message);
+        }
+      }
+    } finally {
+      polling = false;
+    }
+  }, POLL_INTERVAL);
+  log(`Polling every ${POLL_INTERVAL / 1000}s`);
+
+  // Periodic state save
+  const saveInterval = setInterval(() => saveState(), 30_000);
+
+  // Return cleanup
+  return () => {
+    clearInterval(saveInterval);
+    clearInterval(pollInterval);
+    saveState();
+    log('Watcher stopped.');
+  };
+}
+
+module.exports = { startWatching };