coding-tool-x 3.8.4 → 3.8.6

package/src/server/services/session-history-index.js

@@ -1,7 +1,9 @@
 'use strict';
 
 const { openDatabase, closeDatabase } = require('./sqlite-connection');
+
 const { PATHS } = require('../../config/paths');
+const platformRuntime = require('../../platforms/runtime');
 const fs = require('fs');
 const path = require('path');
 
@@ -12,11 +14,180 @@ const path = require('path');
 /** @type {number} Maximum time a source inventory is considered fresh */
 const INDEX_INVENTORY_TTL_MS = 30000;
 
-/** @type {number} Max wait for stale-ok on a cold source */
-const COLD_STALE_WAIT_MS = 2500;
 
-/** @type {number} Hard timeout for worker processes */
-const WORKER_TIMEOUT_MS = 180000;
+/** @type {number} Maximum time a cold stale-ok read waits for inventory */
+const INDEX_COLD_WAIT_MS = 1500;
+/** @type {number} Maximum age for a lock whose owner cannot be inspected */
+const INVENTORY_LOCK_STALE_MS = 30 * 60 * 1000;
+/** @type {number} Maximum time a competing inventory waits for the database writer */
+const INVENTORY_LOCK_WAIT_MS = 30000;
+/** @type {number} Number of files parsed before results are released */
+const INVENTORY_PARSE_BATCH_SIZE = 8;
+/** @type {number} Maximum number of files parsed concurrently */
+const INVENTORY_PARSE_CONCURRENCY = 2;
+const BUILTIN_SESSION_SOURCES = new Set(['claude', 'codex', 'gemini', 'omp']);
+// Keep synchronized with the parserVersion exposed by the built-in session drivers.
+const BUILTIN_SESSION_PARSER_VERSIONS = Object.freeze({ claude: 2, codex: 2, gemini: 2, omp: 2 });
+function _parserVersionForDriver(driver) {
+  const version = Number(driver?.parserVersion);
+  return Number.isInteger(version) && version >= 1 ? version : 1;
+}
+function _isUsableRuntime(runtime) {
+  return !!runtime && typeof runtime === 'object' && typeof runtime.getDriver === 'function';
+}
+
+function _inventoryLockPath(dbPath) {
+  return `${path.resolve(String(dbPath))}.inventory.lock`;
+}
+
+function _isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+/**
+ * Acquire a durable database-wide inventory lock. The in-memory single-flight
+ * map only protects requests inside one Node process; production indexing is
+ * deliberately performed in child processes, so it cannot prevent two
+ * workers from writing the same database after a parent restart.
+ */
+function _tryAcquireInventoryLock(dbPath, source) {
+  const lockPath = _inventoryLockPath(dbPath);
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, source, startedAt: Date.now() }), 'utf8');
+      return { fd, lockPath };
+    } catch (error) {
+      if (fd !== undefined) {
+        try { fs.closeSync(fd); } catch (_err) {}
+      }
+      if (error?.code !== 'EEXIST') throw error;
+    }
+
+    let owner = null;
+    let ageMs = 0;
+    try {
+      owner = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      ageMs = Math.max(0, Date.now() - fs.statSync(lockPath).mtimeMs);
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+    }
+
+    const ownerPid = Number(owner?.pid);
+    if (_isProcessAlive(ownerPid)) {
+      return {
+        busy: true,
+        sameSource: owner?.source && String(owner.source) === String(source)
+      };
+    }
+
+    if ((!Number.isInteger(ownerPid) || ownerPid <= 0) && ageMs < INVENTORY_LOCK_STALE_MS) {
+      return null;
+    }
+
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return null;
+    }
+  }
+
+  return null;
+}
+
+async function _acquireInventoryLock(dbPath, source) {
+  const deadline = Date.now() + INVENTORY_LOCK_WAIT_MS;
+  while (true) {
+    const lock = _tryAcquireInventoryLock(dbPath, source);
+    if (lock?.busy) {
+      if (lock.sameSource) return null;
+    } else if (lock) {
+      return lock;
+    }
+    if (Date.now() >= deadline) return null;
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+}
+
+function _releaseInventoryLock(lock) {
+  if (!lock) return;
+  try { fs.closeSync(lock.fd); } catch (_err) {}
+  try { fs.unlinkSync(lock.lockPath); } catch (_err) {}
+}
+
+/**
+ * Remove inventory locks left by workers that are no longer alive.
+ *
+ * A normal worker releases its lock in `_runInventory`'s finally block. This
+ * fallback is needed for `ctx stop` when a worker is terminated before that
+ * block can run. Locks owned by a live PID are intentionally retained.
+ *
+ * @param {string} [dbPath]
+ * @returns {{ removed: string[], retained: string[] }}
+ */
+function cleanupStaleInventoryLocks(dbPath = PATHS?.sessionHistoryIndex) {
+  const targetPath = dbPath ? path.resolve(String(dbPath)) : '';
+  if (!targetPath) return { removed: [], retained: [] };
+
+  const directory = path.dirname(targetPath);
+  const prefix = `${path.basename(targetPath)}.`;
+  let entries;
+  try {
+    entries = fs.readdirSync(directory);
+  } catch (_) {
+    return { removed: [], retained: [] };
+  }
+
+  const removed = [];
+  const retained = [];
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix) || !entry.endsWith('.inventory.lock')) continue;
+    const lockPath = path.join(directory, entry);
+    let owner = null;
+    let ageMs = 0;
+    try {
+      ageMs = Math.max(0, Date.now() - fs.statSync(lockPath).mtimeMs);
+    } catch (_) {
+      retained.push(lockPath);
+      continue;
+    }
+    try {
+      owner = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    } catch (_) {
+      // Keep malformed young locks; an old one is handled by the stale rule.
+    }
+
+    const ownerPid = Number(owner?.pid);
+    if (_isProcessAlive(ownerPid)) {
+      retained.push(lockPath);
+      continue;
+    }
+
+    // A valid but dead owner can be cleaned immediately. Unreadable lock
+    // files remain protected by the normal acquisition path's stale check.
+    if ((Number.isInteger(ownerPid) && ownerPid > 0) || ageMs >= INVENTORY_LOCK_STALE_MS) {
+      try {
+        fs.unlinkSync(lockPath);
+        removed.push(lockPath);
+      } catch (_) {
+        retained.push(lockPath);
+      }
+    } else {
+      retained.push(lockPath);
+    }
+  }
+
+  return { removed, retained };
+}
+
 
 // ---------------------------------------------------------------------------
 // Schema
@@ -49,6 +220,7 @@ CREATE TABLE IF NOT EXISTS session_file (
   message_count        INTEGER NOT NULL DEFAULT 0,
   usage_json           TEXT,
   extra_json           TEXT,
+  parser_version       INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY (source, file_path),
   UNIQUE (source, session_id)
 );
@@ -80,6 +252,9 @@ CREATE TABLE IF NOT EXISTS session_message (
 
 CREATE INDEX IF NOT EXISTS idx_session_message_sid_ord
   ON session_message(source, session_id, ordinal);
+
+CREATE INDEX IF NOT EXISTS idx_session_message_user_number
+  ON session_message(source, session_id, user_message_number, ordinal);
 `;
 
 const FTS_SETUP_SQL = `
@@ -144,27 +319,197 @@ function _ftsQuote(s) {
   return '"' + String(s).replace(/"/g, '""') + '"';
 }
 
-// ---------------------------------------------------------------------------
-// Core: createSessionHistoryIndex
+function _normalizeTypedSessionsResult(result, defaultOperation = 'resolve-driver') {
+  if (!result || typeof result !== 'object') {
+    return null;
+  }
+  if (result.status !== 'failed' && result.status !== 'unsupported') {
+    return null;
+  }
+  if (typeof result.platform !== 'string' || typeof result.capability !== 'string') {
+    return null;
+  }
+  return {
+    ...result,
+    operation: typeof result.operation === 'string' ? result.operation : defaultOperation
+  };
+}
+
+function _isTypedSessionsResult(result) {
+  return !!_normalizeTypedSessionsResult(result);
+}
+
+function _typedSessionsFailure(source, error, operation = 'resolve-driver') {
+  const result = {
+    status: 'failed',
+    platform: source,
+    capability: 'sessions',
+    operation,
+    error: error && error.message ? error.message : String(error)
+  };
+  if (error) {
+    Object.defineProperty(result, 'cause', { value: error, enumerable: false });
+  }
+  return result;
+}
+
+function _typedSessionsUnsupported(source, error, operation = 'resolve-driver') {
+  const result = {
+    status: 'unsupported',
+    platform: source,
+    capability: 'sessions',
+    operation,
+    error: error && error.message ? error.message : String(error)
+  };
+  if (error) {
+    Object.defineProperty(result, 'cause', { value: error, enumerable: false });
+  }
+  return result;
+}
+
+function _getRuntimeSessionsDriver(runtime, source, config = {}) {
+  if (!runtime || typeof runtime.getDriver !== 'function') {
+    return null;
+  }
+
+  try {
+    const driver = runtime.getDriver(source, 'sessions', { config });
+    const typedResult = _normalizeTypedSessionsResult(driver);
+    if (typedResult) {
+      return typedResult;
+    }
+    if (!driver || typeof driver !== 'object') {
+      return null;
+    }
+    if (typeof driver.inventory !== 'function' || typeof driver.parse !== 'function') {
+      return null;
+    }
+    return driver;
+  } catch (error) {
+    return _typedSessionsFailure(source, error);
+  }
+}
+
+function _safeParseJson(value, fallback) {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch (_) {
+    return fallback;
+  }
+}
+
+function _safeParseObject(value) {
+  const parsed = _safeParseJson(value, {});
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {};
+  }
+  return parsed;
+}
+
+
+function _normalizeRuntimeParseResult(result, descriptor = {}, { preservePayloadUpdatedAt = false } = {}) {
+  if (!result || typeof result !== 'object') {
+    return result;
+  }
+
+  if (result.session && Array.isArray(result.messages)) {
+    const sessionExtra = _safeParseObject(result.session.extraJson);
+    const extraJson = JSON.stringify({
+      ...sessionExtra,
+      projectHint: result.session.projectHint || descriptor.projectHint || null,
+      mtimeMs: descriptor.mtimeMs ?? sessionExtra.mtimeMs ?? null
+    });
+    return {
+      ...result,
+      session: {
+        ...result.session,
+        projectHint: result.session.projectHint || descriptor.projectHint || '',
+        projectName: result.session.projectName || result.session.projectHint || descriptor.projectHint || '',
+        projectDisplayName: result.session.projectDisplayName || result.session.projectName || result.session.projectHint || descriptor.projectHint || '',
+        projectFullPath: result.session.projectFullPath || result.session.projectPath || '',
+        updatedAt: preservePayloadUpdatedAt ? (result.session.updatedAt ?? descriptor.mtimeMs ?? null) : descriptor.mtimeMs ?? null,
+        extraJson
+      }
+    };
+  }
+
+  if (result.sessionId) {
+    const projectHint = descriptor.projectHint || result.projectHint || result.projectName || '';
+    const projectName = result.projectName || projectHint || '';
+    const projectDisplayName = result.projectDisplayName || result.projectName || projectHint || '';
+    const resultExtra = _safeParseObject(result.extraJson);
+    const descriptorMtime = descriptor.mtimeMs ?? null;
+
+    return {
+      session: {
+        sessionId: result.sessionId,
+        projectHint,
+        projectName,
+        projectDisplayName,
+        projectFullPath: result.projectFullPath || result.projectPath || '',
+        firstMessage: result.firstMessage || null,
+        gitBranch: result.gitBranch || null,
+        provider: result.provider || null,
+        model: result.model || null,
+        startedAt: result.startedAt || null,
+        updatedAt: descriptorMtime ?? result.updatedAt ?? null,
+        usageJson: result.usageJson || null,
+        extraJson: JSON.stringify({
+          ...resultExtra,
+          projectHint: projectHint || null,
+          mtimeMs: descriptor.mtimeMs ?? resultExtra.mtimeMs ?? null
+        })
+      },
+      messages: Array.isArray(result.messages) ? result.messages : []
+    };
+  }
+
+  return result;
+}
+
+function _adaptRuntimeSessionsDriver(driver) {
+  if (!driver) return null;
+  const unwrap = result => result && result.status === 'ok' ? result.data : result;
+  return {
+    parserVersion: driver.parserVersion,
+    inventory: async (...args) => unwrap(await driver.inventory(...args)),
+    parse: async (descriptor, ...args) => _normalizeRuntimeParseResult(
+      await unwrap(await driver.parse(descriptor, ...args)),
+      descriptor,
+      { preservePayloadUpdatedAt: driver.preservePayloadUpdatedAt === true }
+    )
+  };
+}
 // ---------------------------------------------------------------------------
 
 /**
  * @param {object} [opts]
  * @param {string} [opts.dbPath]
  * @param {object} [opts.adapterRegistry] - source → { inventory, parse }
+ * @param {object} [opts.runtime] - runtime with getDriver(source, capability)
  * @param {Function} [opts.workerRunner] - (source, indexDbPath) => Promise<void>
  * @param {boolean|null} [opts.ftsEnabledOverride] - override FTS detection for tests
  * @returns {object} index API
  */
 function createSessionHistoryIndex(opts = {}) {
   const dbPath = opts.dbPath || PATHS?.sessionHistoryIndex || path.join(PATHS?.base || process.cwd(), 'session-history.sqlite');
-  const adapters = opts.adapterRegistry || require('./session-history-adapters');
+  const explicitProjectsDir = opts.projectsDir;
+  const indexConfig = opts.config || (opts.projectsDir ? { projectsDir: opts.projectsDir } : {});
+  const explicitAdapters = opts.adapterRegistry || null;
+  const adapters = explicitAdapters || {};
+  const runtimeProvided = !explicitAdapters && process.env.NODE_ENV === 'test' && _isUsableRuntime(opts.runtime);
+  const runtime = explicitAdapters ? null : (runtimeProvided ? opts.runtime : platformRuntime.getPlatformRuntime());
   const workerRunner = opts.workerRunner || _defaultWorkerRunner;
   const ftsEnabled = opts.ftsEnabledOverride !== undefined
     ? opts.ftsEnabledOverride
     : null;
   const shouldUseWorker = process.env.NODE_ENV !== 'test' && process.env.CC_TOOL_SESSION_HISTORY_CHILD !== '1';
   let _db = null;
+  /** @type {Map<string, {size: number, mtimeMs: number, checkedAt: number, filePath: string}>} */
+  const fileVersions = new Map();
+  const fileChecks = new Map();
+  const sourceFreshness = new Map();
   let _ftsAvailable = null;
   /** @type {Map<string, Promise<void>>} */
   const _inflight = new Map();
@@ -183,10 +528,68 @@ function createSessionHistoryIndex(opts = {}) {
     }
     return _db;
   }
+  function _parserVersionForSource(source, adapter = null) {
+    if (adapter) return _parserVersionForDriver(adapter);
+    if (explicitAdapters) return _parserVersionForDriver(adapters[source]);
+    const runtimeDriver = _getRuntimeSessionsDriver(runtime, source, indexConfig);
+    return _parserVersionForDriver(runtimeDriver);
+  }
+
+  /**
+   * Check only the persisted inventory timestamp. Inventory owns file checks.
+   *
+   * @param {string} source
+   * @returns {boolean}
+   */
+  function _isSourceFresh(source) {
+    const row = _getDb().prepare(
+      'SELECT last_inventory_ms FROM source_state WHERE source = ?'
+    ).get(source);
+    return Boolean(
+      row?.last_inventory_ms
+      && Date.now() - Number(row.last_inventory_ms) < INDEX_INVENTORY_TTL_MS
+      && !_hasKnownParserMigrationPending(source)
+      && (!explicitAdapters || !_hasParserMigrationPending(source))
+    );
+  }
+
+  function _hasKnownParserMigrationPending(source) {
+    if (explicitAdapters || runtimeProvided) return false;
+    const parserVersion = BUILTIN_SESSION_PARSER_VERSIONS[source];
+    if (!parserVersion) return false;
+    const row = _getDb().prepare(
+      'SELECT 1 AS pending FROM session_file WHERE source = ? AND parser_version <> ? LIMIT 1'
+    ).get(source, parserVersion);
+    return Boolean(row);
+  }
+
+  function _hasParserMigrationPending(source) {
+    const row = _getDb().prepare(
+      'SELECT 1 AS pending FROM session_file WHERE source = ? AND parser_version <> ? LIMIT 1'
+    ).get(source, _parserVersionForSource(source));
+    return Boolean(row);
+  }
+
+  function _hasIndexedData(source) {
+    const row = _getDb().prepare(
+      'SELECT 1 AS indexed FROM session_file WHERE source = ? LIMIT 1'
+    ).get(source);
+    return Boolean(row);
+  }
+
+  function _hasUsableIndexedData(source) {
+    return _hasIndexedData(source)
+      && !_hasKnownParserMigrationPending(source)
+      && (!explicitAdapters || !_hasParserMigrationPending(source));
+  }
 
   function _initSchema(db) {
     db.exec('PRAGMA journal_mode = WAL');
     db.exec(SCHEMA_SQL);
+    const columns = db.prepare('PRAGMA table_info(session_file)').all();
+    if (!columns.some((column) => column.name === 'parser_version')) {
+      db.exec('ALTER TABLE session_file ADD COLUMN parser_version INTEGER NOT NULL DEFAULT 0');
+    }
   }
 
   function _initFts(db) {
@@ -199,28 +602,41 @@ function createSessionHistoryIndex(opts = {}) {
 
   /**
    * @param {string} source
-   * @param {{ force?: boolean, consistency?: string }} [options]
+   * @param {{ force?: boolean, consistency?: string, allowStaleData?: boolean }} [options]
    * @returns {Promise<void>}
    */
   async function ensureSourceIndexed(source, options = {}) {
     const consistency = options.consistency || 'stale-ok';
     const force = options.force === true;
-
+    const allowStaleData = options.allowStaleData === true;
     const key = `ensure:${source}`;
+
+    if (!force && _isSourceFresh(source)) {
+      return;
+    }
+
     if (_inflight.has(key)) {
       if (consistency === 'complete') {
         return _inflight.get(key);
       }
-      const inflight = _inflight.get(key);
-      const timeout = new Promise((resolve) => setTimeout(() => resolve('timeout'), COLD_STALE_WAIT_MS));
-      const result = await Promise.race([inflight, timeout]);
-      if (result === 'timeout') return;
-      return result;
+      // The project directory can safely use the previous rows while a
+      // parser migration or inventory refresh is running. Session reads
+      // retain their existing behavior and wait for migration completion.
+      if (allowStaleData ? _hasIndexedData(source) : _hasUsableIndexedData(source)) {
+        return;
+      }
+      return _inflight.get(key);
     }
 
-    const promise = shouldUseWorker
-      ? workerRunner(source, dbPath, { force })
-      : _runInventory(source, { force });
+    const useWorker = shouldUseWorker && !runtimeProvided && !explicitAdapters;
+    const workerOptions = { force };
+    const workerProjectsDir = source === 'claude'
+      ? (options.config?.projectsDir || explicitProjectsDir)
+      : explicitProjectsDir;
+    if (workerProjectsDir) workerOptions.projectsDir = workerProjectsDir;
+    const promise = useWorker
+      ? workerRunner(source, dbPath, workerOptions)
+      : _runInventory(source, { force, config: options.config || indexConfig });
     _inflight.set(key, promise);
     promise.finally(() => {
       if (_inflight.get(key) === promise) {
@@ -228,166 +644,305 @@ function createSessionHistoryIndex(opts = {}) {
       }
     }).catch(() => {});
 
+    if (consistency === 'stale-ok' && (allowStaleData ? _hasIndexedData(source) : _hasUsableIndexedData(source))) {
+      return;
+    }
+
     if (consistency === 'stale-ok') {
-      const timeout = new Promise((resolve) => setTimeout(() => resolve('timeout'), COLD_STALE_WAIT_MS));
-      const result = await Promise.race([promise, timeout]);
-      if (result === 'timeout') {
-        return;
-      }
+      await Promise.race([
+        promise,
+        new Promise(resolve => setTimeout(resolve, INDEX_COLD_WAIT_MS))
+      ]);
+      return;
     }
 
     await promise;
   }
+  function _isTypedFailureResult(result) {
+    return _isTypedSessionsResult(result);
+  }
+  function _typedFailureToError(result) {
+    const fallbackMessage = result.status === 'unsupported'
+      ? `unsupported ${result.capability}`
+      : 'inventory failed';
+    const cause = result.cause || (result.error instanceof Error ? result.error : new Error(String(result.error || fallbackMessage)));
+    const error = new Error(`Runtime ${result.capability} ${result.operation} ${result.status} on ${result.platform}: ${cause.message}`);
+    error.status = result.status;
+    error.platform = result.platform;
+    error.capability = result.capability;
+    error.operation = result.operation;
+    error.context = result;
+    error.cause = cause;
+    error.failure = result;
+    return error;
+  }
 
-  async function _runInventory(source, { force = false } = {}) {
-    const db = _getDb();
-    const adapter = adapters[source];
-    if (!adapter || !adapter.inventory) {
+  function _recordSourceState(db, source, lastInventoryMs, lastError) {
+    db.prepare(
+      'INSERT INTO source_state(source, last_inventory_ms, last_error) VALUES(?, ?, ?) ON CONFLICT(source) DO UPDATE SET last_inventory_ms = excluded.last_inventory_ms, last_error = excluded.last_error'
+    ).run(source, lastInventoryMs, lastError);
+  }
+
+  async function _runInventory(source, { force = false, config = indexConfig } = {}) {
+    // SQLite's writer lock is database-wide, so source-specific lock files do
+    // not prevent two different sources from entering BEGIN IMMEDIATE at the
+    // same time. Acquire one lock for the whole index before opening/schema
+    // initializing the writer connection.
+    const inventoryLock = await _acquireInventoryLock(dbPath, source);
+    if (!inventoryLock) {
+      // Another process is already doing the expensive work. Existing rows
+      // remain readable, and the next scheduled inventory will observe the
+      // new source_state timestamp once that worker finishes.
       return;
     }
+    let db = null;
+    let errorMsg = null;
+    let stateToRecord = null;
 
-    if (!force) {
-      const row = db.prepare('SELECT last_inventory_ms FROM source_state WHERE source = ?').get(source);
-      if (row && row.last_inventory_ms && (Date.now() - row.last_inventory_ms) < INDEX_INVENTORY_TTL_MS) {
+    try {
+      db = _getDb();
+      if (!force && _isSourceFresh(source)) {
         return;
       }
-    }
+      let adapter = null;
 
-    const descriptors = await adapter.inventory();
-    if (!Array.isArray(descriptors)) return;
+      if (explicitAdapters) {
+        adapter = adapters[source];
+      } else {
+        const runtimeDriver = _getRuntimeSessionsDriver(runtime, source, config);
+        if (_isTypedFailureResult(runtimeDriver)) {
+          throw _typedFailureToError(runtimeDriver);
+        }
 
-    const seen = new Map();
-    for (const d of descriptors) {
-      const prev = seen.get(d.sessionId);
-      if (!prev || d.mtimeMs > prev.mtimeMs || (d.mtimeMs === prev.mtimeMs && d.filePath < prev.filePath)) {
-        seen.set(d.sessionId, d);
+        if (runtimeDriver) {
+          adapter = _adaptRuntimeSessionsDriver(runtimeDriver);
+        } else if (BUILTIN_SESSION_SOURCES.has(source) && adapters[source]) {
+          adapter = adapters[source];
+        } else {
+          throw _typedFailureToError(_typedSessionsUnsupported(source, new Error(`unsupported sessions source: ${source}`)));
+        }
       }
-    }
-
-    const indexedFiles = new Map();
-    const indexedRows = db.prepare('SELECT file_path, size, mtime_ms FROM session_file WHERE source = ?').all(source);
-    for (const r of indexedRows) {
-      indexedFiles.set(r.file_path, r);
-    }
-
-    const toParse = [];
-    const activePaths = new Set();
-    for (const d of seen.values()) {
-      activePaths.add(d.filePath);
-      const idx = indexedFiles.get(d.filePath);
-      if (!idx || idx.size !== d.size || idx.mtime_ms !== d.mtimeMs) {
-        toParse.push(d);
+      const parserVersion = _parserVersionForSource(source, adapter);
+      const inventoryResult = await adapter.inventory({
+        projectsDir: source === 'claude' ? config.projectsDir : explicitProjectsDir
+      });
+      if (_isTypedFailureResult(inventoryResult)) {
+        throw _typedFailureToError(inventoryResult);
       }
-    }
 
-    for (const filePath of indexedFiles.keys()) {
-      if (!activePaths.has(filePath)) {
-        db.prepare('DELETE FROM session_file WHERE source = ? AND file_path = ?').run(source, filePath);
+      const indexedFiles = new Map();
+      for (const row of db.prepare('SELECT file_path, size, mtime_ms, session_id, parser_version FROM session_file WHERE source = ?').all(source)) {
+        indexedFiles.set(row.file_path, {
+          size: row.size,
+          mtime_ms: row.mtime_ms,
+          sessionId: row.session_id,
+          parserVersion: row.parser_version
+        });
       }
-    }
 
-    let errorMsg = null;
-    for (const d of toParse) {
-      try {
-        const preStat = { size: d.size, mtimeMs: d.mtimeMs };
-        const { session, messages } = await adapter.parse(d);
-
-        try {
-          const postStat = fs.statSync(d.filePath);
-          if (postStat.size !== preStat.size || postStat.mtimeMs !== preStat.mtimeMs) {
-            const retry = await adapter.parse(d);
-            const retryStat = fs.statSync(d.filePath);
-            if (retryStat.size !== postStat.size || retryStat.mtimeMs !== postStat.mtimeMs) {
-              const existing = db.prepare('SELECT 1 FROM session_file WHERE source = ? AND file_path = ?').get(source, d.filePath);
-              if (existing) continue;
-              continue;
-            }
-            _upsertSession(db, source, d, retry.session, retry.messages);
-            continue;
-          }
-        } catch (_statErr) {
-          continue;
+      const winnersBySessionId = new Map();
+      for (const descriptor of inventoryResult) {
+        const current = winnersBySessionId.get(descriptor.sessionId);
+        if (!current
+          || descriptor.mtimeMs > current.mtimeMs
+          || (descriptor.mtimeMs === current.mtimeMs && descriptor.filePath < current.filePath)) {
+          winnersBySessionId.set(descriptor.sessionId, descriptor);
         }
+      }
 
-        _upsertSession(db, source, d, session, messages);
-      } catch (err) {
-        const existing = db.prepare('SELECT 1 FROM session_file WHERE source = ? AND file_path = ?').get(source, d.filePath);
-        if (!existing) {
-          errorMsg = (errorMsg ? errorMsg + '; ' : '') + `${d.filePath}: ${err.message}`;
+      const toParse = [];
+      const activePaths = new Set();
+      for (const d of winnersBySessionId.values()) {
+        activePaths.add(d.filePath);
+        const idx = indexedFiles.get(d.filePath);
+        if (!idx
+          || idx.size !== d.size
+          || idx.mtime_ms !== d.mtimeMs
+          || idx.parserVersion !== parserVersion) {
+          toParse.push(d);
         }
       }
-    }
-
-    db.prepare(
-      'INSERT INTO source_state(source, last_inventory_ms, last_error) VALUES(?, ?, ?) ON CONFLICT(source) DO UPDATE SET last_inventory_ms = excluded.last_inventory_ms, last_error = excluded.last_error'
-    ).run(source, Date.now(), errorMsg);
-  }
+      const parseDescriptor = async (d) => {
+        const preFingerprint = { size: d.size, mtimeMs: d.mtimeMs };
+        const parseResult = await adapter.parse({ ...d, projectsDir: config.projectsDir });
+        if (_isTypedFailureResult(parseResult)) throw _typedFailureToError(parseResult);
+        if (!parseResult || typeof parseResult !== 'object' || !parseResult.session || typeof parseResult.session !== 'object' || typeof parseResult.session.sessionId !== 'string' || !parseResult.session.sessionId.trim() || !Array.isArray(parseResult.messages)) {
+          throw new Error('invalid parsed session result');
+        }
 
-  function _upsertSession(db, source, descriptor, session, messages) {
-    try {
-      db.exec('BEGIN IMMEDIATE');
-      db.prepare('DELETE FROM session_file WHERE source = ? AND session_id = ?').run(source, session.sessionId);
+        let postStat;
+        try {
+          postStat = await fs.promises.stat(d.filePath);
+        } catch (_) {
+          return null;
+        }
+        if (postStat.size === preFingerprint.size && postStat.mtimeMs === preFingerprint.mtimeMs) {
+          return { descriptor: d, parseResult };
+        }
+        const retryDescriptor = { ...d, size: postStat.size, mtimeMs: postStat.mtimeMs };
+        const retryResult = await adapter.parse(retryDescriptor);
+        if (_isTypedFailureResult(retryResult)) {
+          throw _typedFailureToError(retryResult);
+        }
+        if (!retryResult || typeof retryResult !== 'object' || !retryResult.session || typeof retryResult.session !== 'object' || typeof retryResult.session.sessionId !== 'string' || !retryResult.session.sessionId.trim() || !Array.isArray(retryResult.messages)) {
+          throw new Error('invalid parsed session result');
+        }
+        let retryStat;
+        try {
+          retryStat = await fs.promises.stat(d.filePath);
+        } catch (_) {
+          return null;
+        }
+        if (retryStat.size !== postStat.size || retryStat.mtimeMs !== postStat.mtimeMs) {
+          return null;
+        }
+        return {
+          descriptor: { ...retryDescriptor, size: retryStat.size, mtimeMs: retryStat.mtimeMs },
+          parseResult: retryResult
+        };
+      };
 
-      db.prepare(`
+      const deletePath = db.prepare('DELETE FROM session_file WHERE source = ? AND file_path = ?');
+      const deleteSession = db.prepare('DELETE FROM session_file WHERE source = ? AND session_id = ?');
+      const insertFile = db.prepare(`
         INSERT INTO session_file(
           source, file_path, size, mtime_ms, session_id,
           project_name, project_display_name, project_full_path,
           first_message, git_branch, provider, model,
-          started_at, updated_at, message_count, usage_json, extra_json
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(
-        source,
-        descriptor.filePath,
-        descriptor.size,
-        descriptor.mtimeMs,
-        session.sessionId,
-        session.projectName || '',
-        session.projectDisplayName || null,
-        session.projectFullPath || null,
-        session.firstMessage || null,
-        session.gitBranch || null,
-        session.provider || null,
-        session.model || null,
-        session.startedAt || null,
-        session.updatedAt || null,
-        messages.length,
-        session.usageJson || null,
-        session.extraJson || null
-      );
+          started_at, updated_at, message_count, usage_json, extra_json,
+          parser_version
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      const insertMessage = db.prepare(`
+        INSERT INTO session_message(
+          source, session_id, ordinal, message_id, role, type, subtype,
+          content, timestamp, model, provider, user_message_number, extra_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
 
-      if (messages.length > 0) {
-        const stmt = db.prepare(`
-          INSERT INTO session_message(
-            source, session_id, ordinal, message_id, role, type, subtype,
-            content, timestamp, model, provider, user_message_number, extra_json
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `);
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        for (const filePath of indexedFiles.keys()) {
+          if (!activePaths.has(filePath)) deletePath.run(source, filePath);
+        }
+        db.exec('COMMIT');
+      } catch (error) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw error;
+      }
 
-        let ordinal = 0;
-        for (const msg of messages) {
-          stmt.run(
-            source,
-            session.sessionId,
-            ordinal,
-            msg.messageId || null,
-            msg.role || null,
-            msg.type || null,
-            msg.subtype || null,
-            msg.content || null,
-            msg.timestamp || null,
-            msg.model || null,
-            msg.provider || null,
-            msg.userMessageNumber != null ? msg.userMessageNumber : null,
-            msg.extraJson || null
-          );
-          ordinal++;
+      const recordParseError = (descriptor, error) => {
+        const detail = `${descriptor.filePath}: ${error.message}`;
+        errorMsg = errorMsg ? `${errorMsg}; ${detail}` : detail;
+      };
+
+      for (let batchStart = 0; batchStart < toParse.length; batchStart += INVENTORY_PARSE_BATCH_SIZE) {
+        const batch = toParse.slice(batchStart, batchStart + INVENTORY_PARSE_BATCH_SIZE);
+        const parsed = new Array(batch.length);
+        let next = 0;
+        const parseWorker = async () => {
+          while (true) {
+            const index = next++;
+            if (index >= batch.length) return;
+            const descriptor = batch[index];
+            try {
+              parsed[index] = { descriptor, value: await parseDescriptor(descriptor) };
+            } catch (error) {
+              parsed[index] = { descriptor, error };
+            }
+          }
+        };
+        await Promise.all(Array.from({ length: Math.min(INVENTORY_PARSE_CONCURRENCY, batch.length) }, parseWorker));
+
+        for (const item of parsed) {
+          if (item?.error) recordParseError(item.descriptor, item.error);
         }
+
+        db.exec('BEGIN IMMEDIATE');
+        try {
+          for (const item of parsed) {
+            if (item?.value) {
+              const { descriptor, parseResult } = item.value;
+              _insertSession({ deletePath, deleteSession, insertFile, insertMessage }, source, descriptor, parseResult.session, parseResult.messages, parserVersion);
+            }
+          }
+          db.exec('COMMIT');
+        } catch (error) {
+          try { db.exec('ROLLBACK'); } catch (_) {}
+          throw error;
+        }
+        // Drop the batch references before parsing the next group. This is
+        // the key difference from the old whole-inventory array: large
+        // session payloads no longer accumulate until the final COMMIT.
       }
 
-      db.exec('COMMIT');
+      stateToRecord = {
+        lastInventoryMs: Date.now(),
+        lastError: errorMsg
+      };
     } catch (err) {
-      try { db.exec('ROLLBACK'); } catch (_) {}
+      errorMsg = err && err.message ? err.message : String(err);
+      stateToRecord = {
+        lastInventoryMs: null,
+        lastError: errorMsg
+      };
       throw err;
+    } finally {
+      if (stateToRecord) {
+        try {
+          if (db) {
+            _recordSourceState(db, source, stateToRecord.lastInventoryMs, stateToRecord.lastError);
+          }
+        } catch (_err) {}
+      }
+      _releaseInventoryLock(inventoryLock);
+    }
+  }
+
+
+  function _insertSession(statements, source, descriptor, session, messages, parserVersion) {
+    const { deletePath, deleteSession, insertFile, insertMessage } = statements;
+    deletePath.run(source, descriptor.filePath);
+    deleteSession.run(source, session.sessionId);
+    insertFile.run(
+      source,
+      descriptor.filePath,
+      descriptor.size,
+      descriptor.mtimeMs,
+      session.sessionId,
+      session.projectName || '',
+      session.projectDisplayName || null,
+      session.projectFullPath || null,
+      session.firstMessage || null,
+      session.gitBranch || null,
+      session.provider || null,
+      session.model || null,
+      session.startedAt || null,
+      session.updatedAt || null,
+      messages.length,
+      session.usageJson || null,
+      session.extraJson || null,
+      parserVersion
+    );
+
+    let ordinal = 0;
+    for (const msg of messages) {
+      insertMessage.run(
+        source,
+        session.sessionId,
+        ordinal,
+        msg.messageId || null,
+        msg.role || null,
+        msg.type || null,
+        msg.subtype || null,
+        msg.content || null,
+        msg.timestamp || null,
+        msg.model || null,
+        msg.provider || null,
+        msg.userMessageNumber != null ? msg.userMessageNumber : null,
+        msg.extraJson || null
+      );
+      ordinal++;
     }
   }
 
@@ -401,7 +956,12 @@ function createSessionHistoryIndex(opts = {}) {
    * @returns {Promise<Array<{name, displayName, fullPath, path, sessionCount, lastUsed, latestSession, source}>>}
    */
   async function listProjects(source, options = {}) {
-    await ensureSourceIndexed(source, { consistency: options.consistency || 'stale-ok' });
+    await ensureSourceIndexed(source, {
+      force: options.force === true,
+      consistency: options.consistency || 'stale-ok',
+      allowStaleData: true,
+      config: options.config
+    });
     const db = _getDb();
 
     const rows = db.prepare(`
@@ -436,7 +996,11 @@ function createSessionHistoryIndex(opts = {}) {
    * @returns {Promise<Array>}
    */
   async function listSessions(source, projectName, options = {}) {
-    await ensureSourceIndexed(source, { consistency: 'stale-ok' });
+    await ensureSourceIndexed(source, {
+      force: options.force === true,
+      consistency: options.consistency || 'stale-ok',
+      config: options.config
+    });
 
     const db = _getDb();
     const rows = db.prepare(`
@@ -445,25 +1009,30 @@ function createSessionHistoryIndex(opts = {}) {
       ORDER BY updated_at DESC
     `).all(source, projectName);
 
-    return rows.map(r => ({
-      sessionId: r.session_id,
-      filePath: r.file_path,
-      size: r.size,
-      mtime: r.mtime_ms,
-      firstMessage: r.first_message,
-      gitBranch: r.git_branch,
-      provider: r.provider,
-      model: r.model,
-      messageCount: r.message_count,
-      tokens: r.usage_json ? JSON.parse(r.usage_json) : null,
-      extra: r.extra_json ? JSON.parse(r.extra_json) : {},
-      source: r.source,
-      projectName: r.project_name,
-      projectDisplayName: r.project_display_name,
-      projectFullPath: r.project_full_path,
-      startedAt: r.started_at,
-      updatedAt: r.updated_at
-    }));
+    return rows.map(r => {
+      const extra = _safeParseObject(r.extra_json);
+
+      return {
+        sessionId: r.session_id,
+        filePath: r.file_path,
+        size: r.size,
+        mtime: r.mtime_ms,
+        firstMessage: r.first_message,
+        gitBranch: r.git_branch,
+        provider: r.provider,
+        model: r.model,
+        messageCount: r.message_count,
+        tokens: _safeParseJson(r.usage_json, null),
+        extra,
+        source: r.source,
+        projectName: r.project_name,
+        projectHint: extra.projectHint || r.project_name,
+        projectDisplayName: r.project_display_name,
+        projectFullPath: r.project_full_path,
+        startedAt: r.started_at,
+        updatedAt: r.updated_at
+      };
+    });
   }
 
   /**
@@ -473,23 +1042,13 @@ function createSessionHistoryIndex(opts = {}) {
    * @returns {Promise<{sessionId, lastModified, size, filePath}|null>}
    */
   async function getSessionStatus(source, sessionId, options = {}) {
-    await ensureSourceIndexed(source, { consistency: 'stale-ok' });
+    await _ensureSessionCurrent(source, sessionId);
     const db = _getDb();
     const row = db.prepare(
       'SELECT session_id, mtime_ms, size, file_path FROM session_file WHERE source = ? AND session_id = ?'
     ).get(source, sessionId);
-
     if (!row) return null;
 
-    // Verify file still exists
-    try {
-      await fs.promises.stat(row.file_path);
-    } catch (_) {
-      // File gone - invalidate and return null
-      db.prepare('DELETE FROM session_file WHERE source = ? AND session_id = ?').run(source, sessionId);
-      return null;
-    }
-
     return {
       sessionId: row.session_id,
       lastModified: row.mtime_ms,
@@ -575,7 +1134,7 @@ function createSessionHistoryIndex(opts = {}) {
         model: r.model,
         provider: r.provider,
         userMessageNumber: r.user_message_number,
-        extra: r.extra_json ? JSON.parse(r.extra_json) : {}
+        extra: _safeParseObject(r.extra_json)
       })),
       metadata: _buildMessageMetadata(sf),
       pagination: {
@@ -594,7 +1153,11 @@ function createSessionHistoryIndex(opts = {}) {
    * @returns {Promise<Array>}
    */
   async function getRecentSessions(source, limit = 5, options = {}) {
-    await ensureSourceIndexed(source, { consistency: 'stale-ok' });
+    await ensureSourceIndexed(source, {
+      force: options.force === true,
+      consistency: options.consistency || 'stale-ok',
+      config: options.config
+    });
     const db = _getDb();
 
     const rows = db.prepare(`
@@ -629,7 +1192,12 @@ function createSessionHistoryIndex(opts = {}) {
    * @returns {Promise<Array>}
    */
   async function searchSessions(source, keyword, options = {}) {
-    await ensureSourceIndexed(source, { consistency: options.consistency || 'complete' });
+    if (!String(keyword || '').trim()) return [];
+    await ensureSourceIndexed(source, {
+      force: options.force === true,
+      consistency: options.consistency || 'complete',
+      config: options.config
+    });
     const db = _getDb();
     const contextLength = options.contextLength || 35;
     const projectName = options.projectName || null;
@@ -641,13 +1209,15 @@ function createSessionHistoryIndex(opts = {}) {
       const needle = String(keyword);
       if ([...needle].length >= 3) {
         const ftsRows = db.prepare(`
-          SELECT sm.source, sm.session_id, sm.ordinal, sm.content, sm.role, sm.type, sm.timestamp
+          SELECT sm.source, sm.session_id, sm.ordinal, sm.content, sm.role, sm.type, sm.timestamp,
+                 sf.project_name, sf.project_display_name, sf.project_full_path,
+                 sf.file_path, sf.first_message, sf.updated_at
           FROM session_message_fts fts
           JOIN session_message sm ON sm.rowid = fts.rowid
           JOIN session_file sf ON sf.source = sm.source AND sf.session_id = sm.session_id
           WHERE sm.source = ? AND session_message_fts MATCH ?
           ${projectName ? 'AND sf.project_name = ?' : ''}
-          ORDER BY sf.updated_at DESC
+          ORDER BY sf.updated_at DESC, sm.ordinal ASC, sm.rowid ASC
           LIMIT 500
         `);
         const params = [source, _ftsQuote(needle)];
@@ -680,20 +1250,26 @@ function createSessionHistoryIndex(opts = {}) {
         idx += lowerKeyword.length;
       }
       if (count === 0) continue;
-
-      if (!matchMap.has(c.session_id)) {
-        const sf = db.prepare('SELECT * FROM session_file WHERE source = ? AND session_id = ?').get(source, c.session_id);
-        if (!sf) continue;
-        matchMap.set(c.session_id, {
-          session: sf,
+      let entry = matchMap.get(c.session_id);
+      if (!entry) {
+        entry = {
+          session: {
+            source: c.source,
+            session_id: c.session_id,
+            project_name: c.project_name,
+            project_display_name: c.project_display_name,
+            project_full_path: c.project_full_path,
+            file_path: c.file_path,
+            first_message: c.first_message,
+            updated_at: c.updated_at
+          },
           matchCount: 0,
           messages: []
-        });
+        };
+        matchMap.set(c.session_id, entry);
       }
 
-      const entry = matchMap.get(c.session_id);
-      // Claude: count every occurrence; Codex/Gemini/OMP: at most 1 per message
-      entry.matchCount += (source === 'claude') ? count : 1;
+      entry.matchCount += source === 'claude' ? count : 1;
       entry.messages.push({
         ordinal: c.ordinal,
         content,
@@ -724,6 +1300,7 @@ function createSessionHistoryIndex(opts = {}) {
 
     // Sort: matchCount DESC, then updated_at DESC
     results.sort((a, b) => {
+
       const cm = b.matchCount - a.matchCount;
       if (cm !== 0) return cm;
       const aRow = matchMap.get(a.sessionId);
@@ -737,20 +1314,50 @@ function createSessionHistoryIndex(opts = {}) {
   }
 
   function _scanMessagesRelational(db, source, keyword, projectName = null) {
-    const lowerKeyword = String(keyword).toLocaleLowerCase();
-    // Use instr for case-insensitive substring matching
-    let sql = `
-      SELECT sm.source, sm.session_id, sm.ordinal, sm.content, sm.role, sm.type, sm.timestamp
+    const useSqlMatch = /^[\x00-\x7F]*$/.test(String(keyword));
+    const select = `
+      SELECT sm.source, sm.session_id, sm.ordinal, sm.content, sm.role, sm.type, sm.timestamp,
+             sf.project_name, sf.project_display_name, sf.project_full_path,
+             sf.file_path, sf.first_message, sf.updated_at
       FROM session_message sm
       JOIN session_file sf ON sf.source = sm.source AND sf.session_id = sm.session_id
-      WHERE sm.source = ? AND instr(lower(sm.content), lower(?)) > 0
+      WHERE sm.source = ?
       ${projectName ? 'AND sf.project_name = ?' : ''}
-      ORDER BY sf.updated_at DESC
-      LIMIT 500
+      ORDER BY sf.updated_at DESC, sm.ordinal ASC, sm.rowid ASC
     `;
-    const params = [source, keyword];
-    if (projectName) params.push(projectName);
-    return db.prepare(sql).all(...params);
+
+    if (useSqlMatch) {
+      const sql = `${select.replace('WHERE sm.source = ?', 'WHERE sm.source = ? AND instr(lower(sm.content), lower(?)) > 0')}\nLIMIT 500`;
+      const params = [source, keyword];
+      if (projectName) params.push(projectName);
+      return db.prepare(sql).all(...params);
+    }
+
+    // SQLite's lower() is ASCII-oriented. Page the broad joined query and
+    // apply the same locale-aware JavaScript matcher used by searchSessions,
+    // collecting at most the 500 matching candidates (not 500 raw rows).
+    const candidates = [];
+    const pageSize = 500;
+    let offset = 0;
+    while (candidates.length < pageSize) {
+      const params = [source];
+      if (projectName) params.push(projectName);
+      params.push(pageSize, offset);
+      const batch = db.prepare(`${select}\nLIMIT ? OFFSET ?`).all(...params);
+      if (batch.length === 0) break;
+      for (const row of batch) {
+        if (_containsLocaleMatch(row.content, keyword)) candidates.push(row);
+        if (candidates.length >= pageSize) break;
+      }
+      if (batch.length < pageSize) break;
+      offset += batch.length;
+    }
+    return candidates;
+  }
+
+  function _containsLocaleMatch(content, keyword) {
+    const lowerKeyword = String(keyword).toLocaleLowerCase();
+    return String(content || '').toLocaleLowerCase().indexOf(lowerKeyword) !== -1;
   }
 
   function _extractContext(content, position, contextLength, keywordLength) {
@@ -778,8 +1385,8 @@ function createSessionHistoryIndex(opts = {}) {
       provider: sf.provider,
       model: sf.model,
       messageCount: sf.message_count,
-      usage: sf.usage_json ? JSON.parse(sf.usage_json) : null,
-      extra: sf.extra_json ? JSON.parse(sf.extra_json) : {}
+      usage: _safeParseObject(sf.usage_json),
+      extra: _safeParseObject(sf.extra_json)
     };
   }
 
@@ -794,17 +1401,41 @@ function createSessionHistoryIndex(opts = {}) {
     ).get(source, sessionId);
     if (!row) return;
 
-    let currentStat;
-    try {
-      currentStat = await fs.promises.stat(row.file_path);
-    } catch (_) {
-      // File gone, session stays indexed as-is
+    const fileKey = `${source}:${row.file_path}`;
+    const now = Date.now();
+    const cached = fileVersions.get(fileKey);
+    if (cached && now - cached.checkedAt < INDEX_INVENTORY_TTL_MS) return;
+
+    const activeCheck = fileChecks.get(fileKey);
+    if (activeCheck) {
+      await activeCheck;
       return;
     }
 
-    if (currentStat.size !== row.size || currentStat.mtimeMs !== row.mtime_ms) {
-      // File changed; force re-index
-      await ensureSourceIndexed(source, { force: true, consistency: 'complete' });
+    const check = (async () => {
+      let currentStat;
+      try {
+        currentStat = await fs.promises.stat(row.file_path);
+      } catch (_) {
+        fileVersions.set(fileKey, { size: -1, mtimeMs: -1, checkedAt: Date.now(), missing: true });
+        db.prepare('DELETE FROM session_file WHERE source = ? AND file_path = ?').run(source, row.file_path);
+        return;
+      }
+
+      fileVersions.set(fileKey, {
+        size: currentStat.size,
+        mtimeMs: currentStat.mtimeMs,
+        checkedAt: Date.now()
+      });
+      if (currentStat.size !== row.size || currentStat.mtimeMs !== row.mtime_ms) {
+        await ensureSourceIndexed(source, { force: true, consistency: 'complete' });
+      }
+    })();
+    fileChecks.set(fileKey, check);
+    try {
+      await check;
+    } finally {
+      if (fileChecks.get(fileKey) === check) fileChecks.delete(fileKey);
     }
   }
 
@@ -819,16 +1450,38 @@ function createSessionHistoryIndex(opts = {}) {
     if (options.deleted && options.sessionId) {
       db.prepare('DELETE FROM session_file WHERE source = ? AND session_id = ?').run(source, options.sessionId);
     }
+    if (options.projectName) {
+      db.prepare('DELETE FROM session_file WHERE source = ? AND project_name = ?').run(source, options.projectName);
+    }
 
     // Mark state as stale
     db.prepare(
       'UPDATE source_state SET last_inventory_ms = NULL WHERE source = ?'
     ).run(source);
+    for (const key of fileVersions.keys()) {
+      if (key.startsWith(`${source}:`)) fileVersions.delete(key);
+    }
+  }
+  function getSourceIndexMeta(source) {
+    const row = _getDb().prepare(
+      'SELECT last_inventory_ms, last_error FROM source_state WHERE source = ?'
+    ).get(source);
+    const generatedAt = row?.last_inventory_ms ? Number(row.last_inventory_ms) : null;
+    const stale = !generatedAt || Date.now() - generatedAt >= INDEX_INVENTORY_TTL_MS;
+    const refreshing = _inflight.has(`ensure:${source}`);
+    return {
+      generatedAt,
+      stale,
+      refreshing,
+      fallback: Boolean(row?.last_error && !_hasUsableIndexedData(source)),
+      error: row?.last_error || null
+    };
   }
-
   function closeSessionHistoryIndex() {
     closeDatabase(dbPath);
     _db = null;
+    fileVersions.clear();
+    fileChecks.clear();
   }
 
   // Build the API object
@@ -842,6 +1495,7 @@ function createSessionHistoryIndex(opts = {}) {
     getRecentSessions,
     searchSessions,
     invalidateSource,
+    getSourceIndexMeta,
     closeSessionHistoryIndex,
   };
 
@@ -858,9 +1512,11 @@ function createSessionHistoryIndex(opts = {}) {
 
 let _defaultIndex = null;
 
-function _getDefaultIndex() {
+function _getDefaultIndex(options = {}) {
   if (!_defaultIndex) {
-    _defaultIndex = createSessionHistoryIndex();
+    _defaultIndex = Object.keys(options).length > 0
+      ? createSessionHistoryIndex({ config: options })
+      : createSessionHistoryIndex();
   }
   return _defaultIndex;
 }
@@ -870,7 +1526,7 @@ async function ensureSourceIndexed(source, options) {
 }
 
 async function listProjects(source, options) {
-  return _getDefaultIndex().listProjects(source, options);
+  return _getDefaultIndex(options).listProjects(source, options);
 }
 
 async function listSessions(source, projectName, options) {
@@ -897,6 +1553,10 @@ async function searchSessions(source, keyword, options) {
   return _getDefaultIndex().searchSessions(source, keyword, options);
 }
 
+function getSourceIndexMeta(source) {
+  return _getDefaultIndex().getSourceIndexMeta(source);
+}
+
 function invalidateSource(source, options) {
   _getDefaultIndex().invalidateSource(source, options);
 }
@@ -926,5 +1586,7 @@ module.exports = {
   getRecentSessions,
   searchSessions,
   invalidateSource,
-  closeSessionHistoryIndex
+  getSourceIndexMeta,
+  closeSessionHistoryIndex,
+  cleanupStaleInventoryLocks,
 };