agentel 0.2.6 → 0.3.0

package/src/search.js

@@ -4,21 +4,32 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
-const { ensureConversationMarkdown, listSessions, readEvents, readTranscript, sessionHistoryTime } = require("./archive");
+const { ensureConversationMarkdown, listSessions, listSessionsSnapshot, readEvents, readTranscript, sessionHistoryTime } = require("./archive");
 const { EVENT_KINDS, renderEventText } = require("./canonical-events");
 const { loadConfig } = require("./config");
 const { paths, ensureDir, readJson, writeJson } = require("./paths");
 const { canonicalRepo } = require("./repo");
 
-const INDEX_VERSION = 3;
+const INDEX_VERSION = 8;
 const INDEX_STALE_CHECK_TTL_MS = 5000;
-const SQLITE_QUERY_TIMEOUT_MS = 5000;
-const SQLITE_BUILD_BATCH_SIZE = 100;
+const SQLITE_BUILD_BATCH_SIZE = 500;
 const RIPGREP_SEARCH_TIMEOUT_MS = 8000;
 const RIPGREP_BATCH_FILE_COUNT = 200;
 const MARKDOWN_MATCHES_PER_FILE = 3;
 const FTS_SEARCH_BATCH_SIZE = 250;
 const FTS_MAX_SCAN_ROWS = 5000;
+// Most queries find `limit` distinct sessions within the first few hundred
+// ranked rows — broader terms used to hit FTS_MAX_SCAN_ROWS unconditionally,
+// which forced FTS5 to read ~5000 rows from the 469MB index even when the
+// answer was in the first 200. Try a cheap primary scan first and only
+// re-query at the wide cap if dedupe leaves fewer than `limit` sessions.
+const FTS_PRIMARY_SCAN_MULTIPLIER = 100;
+// Tool *output* (Bash stdout, file dumps, test logs) is high-volume and
+// low-signal: the useful part (error strings, the head of a diff, the start
+// of a stack trace) is front-loaded. We still index tool.completed events so
+// those head matches are findable, but cap the indexed/excerpt text so a
+// 50k-line log doesn't add dozens of chunk docs and inflate every BM25 scan.
+const TOOL_COMPLETED_INDEX_MAX_CHARS = 600;
 const _indexCache = {
   path: "",
   mtimeMs: 0,
@@ -33,20 +44,83 @@ const _ftsCache = {
   checkedAtMs: 0,
   available: false
 };
+// Read-only better-sqlite3 connection cache for the FTS sidecar. Reopened when
+// the file inode changes (atomic rename during rebuild). Prepared statements
+// are cached on the connection by SQL text.
+const _ftsReadConn = {
+  path: "",
+  mtimeMs: 0,
+  size: 0,
+  ino: 0,
+  db: null,
+  prepared: null
+};
+let _betterSqlite3 = null;
+let _betterSqlite3Loaded = false;
+let _betterSqlite3LoadError = null;
+// Latched true once `new Database()` throws at runtime (e.g. ABI mismatch
+// after Node version change). Once latched, loadBetterSqlite3 returns null
+// permanently so callers take the spawn fallback instead of repeatedly
+// crashing in the constructor.
+let _betterSqlite3Broken = false;
+
+/**
+ * Lazily load better-sqlite3. Returns the constructor or null when the native
+ * binding is unavailable; call sites then fall back to the legacy `sqlite3`
+ * subprocess path. The load attempt is cached so missing optional builds do
+ * not re-try `require()` on every query.
+ *
+ * Two failure modes are handled here:
+ *   1. `require("better-sqlite3")` itself throws (no native binding shipped).
+ *   2. The require succeeds but `new Database()` later throws because the
+ *      native .node file was built against a different Node ABI (e.g. nvm
+ *      flipped versions). The lower-level openFts*Db helpers call
+ *      `markBetterSqlite3Broken()` when that happens, after which we
+ *      permanently return null here so callers consistently take the spawn
+ *      fallback instead of repeatedly hitting the same constructor crash.
+ */
+function loadBetterSqlite3() {
+  if (_betterSqlite3Broken) return null;
+  if (_betterSqlite3Loaded) return _betterSqlite3;
+  _betterSqlite3Loaded = true;
+  try {
+    _betterSqlite3 = require("better-sqlite3");
+  } catch (error) {
+    _betterSqlite3 = null;
+    _betterSqlite3LoadError = error;
+  }
+  return _betterSqlite3;
+}
+
+function betterSqlite3LoadError() {
+  return _betterSqlite3LoadError;
+}
+
+function markBetterSqlite3Broken(error) {
+  _betterSqlite3Broken = true;
+  if (error && !_betterSqlite3LoadError) _betterSqlite3LoadError = error;
+}
+
+function resetBetterSqlite3State() {
+  // Test-only: clear the load+broken latches so a test can simulate fresh
+  // module load with different `require` behavior. Not part of any public
+  // API contract.
+  _betterSqlite3 = null;
+  _betterSqlite3Loaded = false;
+  _betterSqlite3LoadError = null;
+  _betterSqlite3Broken = false;
+}
 
 function buildIndex(env = process.env) {
-  const sessions = listSessions(env);
+  const snapshot = listSessionsSnapshot(env);
+  const sessions = snapshot.sessions;
   const docs = [];
   const postings = Object.create(null);
   const df = Object.create(null);
   let totalLength = 0;
 
   for (const session of sessions) {
-    if (session.conversationPath && !fs.existsSync(session.conversationPath)) ensureConversationMarkdown(session, env);
-    const events = readEvents(session);
-    const eventDocs = events.length ? docsForEvents(session, events) : [];
-    if (!eventDocs.length) ensureConversationMarkdown(session, env);
-    const sourceDocs = eventDocs.length ? eventDocs : docsForTranscript(session, readTranscript(session.transcriptPath));
+    const sourceDocs = canonicalDocsForSession(session);
     for (const sourceDoc of sourceDocs) {
       const indexText = normalizeIndexText(sourceDoc.text);
       if (!indexText) continue;
@@ -76,6 +150,7 @@ function buildIndex(env = process.env) {
   const index = {
     version: INDEX_VERSION,
     builtAt: new Date().toISOString(),
+    sessionFingerprint: snapshot.fingerprint,
     docCount: docs.length,
     avgDocLength: docs.length ? totalLength / docs.length : 0,
     df,
@@ -104,6 +179,7 @@ function summarizeIndex(index) {
   return {
     version: index.version,
     builtAt: index.builtAt,
+    sessionFingerprint: index.sessionFingerprint,
     docCount: index.docCount,
     avgDocLength: index.avgDocLength,
     summaryOnly: true
@@ -120,6 +196,7 @@ function readIndexSummary(indexPath) {
     const summary = {
       version: readJsonHeaderNumber(header, "version"),
       builtAt: readJsonHeaderString(header, "builtAt"),
+      sessionFingerprint: readJsonHeaderString(header, "sessionFingerprint"),
       docCount: readJsonHeaderNumber(header, "docCount"),
       avgDocLength: readJsonHeaderNumber(header, "avgDocLength"),
       summaryOnly: true
@@ -147,59 +224,69 @@ function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+const FTS_SCHEMA_SQL = [
+  "CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);",
+  "CREATE TABLE docs(",
+  "  rowid INTEGER PRIMARY KEY,",
+  "  doc_id TEXT,",
+  "  session_id TEXT,",
+  "  provider TEXT,",
+  "  source_type TEXT,",
+  "  conversation_kind TEXT,",
+  "  is_subagent INTEGER,",
+  "  repo_canonical TEXT,",
+  "  repo_display TEXT,",
+  "  scope_canonical TEXT,",
+  "  storage_scope TEXT,",
+  "  cwd TEXT,",
+  "  title TEXT,",
+  "  started_at TEXT,",
+  "  occurred_at TEXT,",
+  "  role TEXT,",
+  "  event_id TEXT,",
+  "  event_kind TEXT,",
+  "  message_index INTEGER,",
+  "  path TEXT,",
+  "  matched_text TEXT",
+  ");",
+  "CREATE VIRTUAL TABLE docs_fts USING fts5(text, tokenize='unicode61', prefix='2 3 4');"
+].join("\n");
+
+function cleanupFtsTmpFiles(tmpPath) {
+  for (const file of [tmpPath, `${tmpPath}-journal`, `${tmpPath}-wal`, `${tmpPath}-shm`]) {
+    try {
+      fs.rmSync(file, { force: true });
+    } catch {
+      // Best effort cleanup before rebuilding the sidecar index.
+    }
+  }
+}
+
 function buildFtsIndex(index, env = process.env) {
   const ftsPath = paths(env).ftsIndex;
   const tmpPath = `${ftsPath}.${process.pid}.tmp`;
+  let handle = null;
   try {
     ensureDir(path.dirname(ftsPath));
-    for (const file of [tmpPath, `${tmpPath}-journal`, `${tmpPath}-wal`, `${tmpPath}-shm`]) {
-      try {
-        fs.rmSync(file, { force: true });
-      } catch {
-        // Best effort cleanup before rebuilding the sidecar index.
-      }
-    }
-    runSqliteScript(tmpPath, [
-      "PRAGMA journal_mode=OFF;",
-      "PRAGMA synchronous=OFF;",
-      "CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);",
-      "CREATE TABLE docs(",
-      "  rowid INTEGER PRIMARY KEY,",
-      "  doc_id TEXT,",
-      "  session_id TEXT,",
-      "  provider TEXT,",
-      "  source_type TEXT,",
-      "  repo_canonical TEXT,",
-      "  repo_display TEXT,",
-      "  scope_canonical TEXT,",
-      "  cwd TEXT,",
-      "  title TEXT,",
-      "  started_at TEXT,",
-      "  occurred_at TEXT,",
-      "  role TEXT,",
-      "  event_id TEXT,",
-      "  event_kind TEXT,",
-      "  message_index INTEGER,",
-      "  path TEXT,",
-      "  matched_text TEXT",
-      ");",
-      "CREATE VIRTUAL TABLE docs_fts USING fts5(text, tokenize='unicode61', prefix='2 3 4');",
-      `INSERT INTO meta(key, value) VALUES ('version', ${sqliteString(String(INDEX_VERSION))});`,
-      `INSERT INTO meta(key, value) VALUES ('builtAt', ${sqliteString(index.builtAt || "")});`,
-      `INSERT INTO meta(key, value) VALUES ('docCount', ${sqliteString(String(index.docCount || 0))});`
-	    ].join("\n"));
-
-    insertFtsDocs(tmpPath, index.docs || [], 1);
-    runSqliteScript(tmpPath, "INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
+    cleanupFtsTmpFiles(tmpPath);
+    handle = openFtsBuildDb(tmpPath);
+    execFtsBuildSql(handle, FTS_SCHEMA_SQL);
+    insertFtsMetaRows(handle, [
+      { key: "version", value: String(INDEX_VERSION) },
+      { key: "builtAt", value: index.builtAt || "" },
+      { key: "sessionFingerprint", value: index.sessionFingerprint || "" },
+      { key: "docCount", value: String(index.docCount || 0) }
+    ]);
+    insertFtsDocs(handle, tmpPath, index.docs || [], 1);
+    execFtsBuildSql(handle, "INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
+    closeFtsBuildDb(handle);
+    handle = null;
     fs.renameSync(tmpPath, ftsPath);
     rememberFtsCache(ftsPath, true);
     return true;
   } catch {
-    try {
-      fs.rmSync(tmpPath, { force: true });
-    } catch {
-      // Ignore optional FTS cleanup failure.
-    }
+    if (handle) closeFtsBuildDb(handle);
+    cleanupFtsTmpFiles(tmpPath);
     try {
       fs.rmSync(ftsPath, { force: true });
     } catch {
@@ -211,56 +298,27 @@ function buildFtsIndex(index, env = process.env) {
 }
 
 function buildFtsIndexSummary(env = process.env) {
+  const snapshot = listSessionsSnapshot(env);
   const ftsPath = paths(env).ftsIndex;
   const tmpPath = `${ftsPath}.${process.pid}.tmp`;
   const builtAt = new Date().toISOString();
   let docCount = 0;
   let totalLength = 0;
+  let handle = null;
   try {
     ensureDir(path.dirname(ftsPath));
-    for (const file of [tmpPath, `${tmpPath}-journal`, `${tmpPath}-wal`, `${tmpPath}-shm`]) {
-      try {
-        fs.rmSync(file, { force: true });
-      } catch {
-        // Best effort cleanup before rebuilding the sidecar index.
-      }
-    }
-    runSqliteScript(tmpPath, [
-      "PRAGMA journal_mode=OFF;",
-      "PRAGMA synchronous=OFF;",
-      "CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);",
-      "CREATE TABLE docs(",
-      "  rowid INTEGER PRIMARY KEY,",
-      "  doc_id TEXT,",
-      "  session_id TEXT,",
-      "  provider TEXT,",
-      "  source_type TEXT,",
-      "  repo_canonical TEXT,",
-      "  repo_display TEXT,",
-      "  scope_canonical TEXT,",
-      "  cwd TEXT,",
-      "  title TEXT,",
-      "  started_at TEXT,",
-      "  occurred_at TEXT,",
-      "  role TEXT,",
-      "  event_id TEXT,",
-      "  event_kind TEXT,",
-      "  message_index INTEGER,",
-      "  path TEXT,",
-      "  matched_text TEXT",
-      ");",
-      "CREATE VIRTUAL TABLE docs_fts USING fts5(text, tokenize='unicode61', prefix='2 3 4');",
-      `INSERT INTO meta(key, value) VALUES ('version', ${sqliteString(String(INDEX_VERSION))});`,
-      `INSERT INTO meta(key, value) VALUES ('builtAt', ${sqliteString(builtAt)});`
-    ].join("\n"));
+    cleanupFtsTmpFiles(tmpPath);
+    handle = openFtsBuildDb(tmpPath);
+    execFtsBuildSql(handle, FTS_SCHEMA_SQL);
+    insertFtsMetaRows(handle, [
+      { key: "version", value: String(INDEX_VERSION) },
+      { key: "builtAt", value: builtAt },
+      { key: "sessionFingerprint", value: snapshot.fingerprint || "" }
+    ]);
 
     let batch = [];
-    for (const session of listSessions(env)) {
-      if (session.conversationPath && !fs.existsSync(session.conversationPath)) ensureConversationMarkdown(session, env);
-      const events = readEvents(session);
-      const eventDocs = events.length ? docsForEvents(session, events) : [];
-      if (!eventDocs.length) ensureConversationMarkdown(session, env);
-      const sourceDocs = eventDocs.length ? eventDocs : docsForTranscript(session, readTranscript(session.transcriptPath));
+    for (const session of snapshot.sessions) {
+      const sourceDocs = canonicalDocsForSession(session);
       for (const sourceDoc of sourceDocs) {
         const indexText = normalizeIndexText(sourceDoc.text);
         if (!indexText) continue;
@@ -278,25 +336,22 @@ function buildFtsIndexSummary(env = process.env) {
             length: tokens.length
           });
           if (batch.length >= SQLITE_BUILD_BATCH_SIZE) {
-            insertFtsDocs(tmpPath, batch, docCount - batch.length + 1);
+            insertFtsDocs(handle, tmpPath, batch, docCount - batch.length + 1);
             batch = [];
           }
         }
       }
     }
-    if (batch.length) insertFtsDocs(tmpPath, batch, docCount - batch.length + 1);
-    runSqliteScript(tmpPath, [
-      `INSERT INTO meta(key, value) VALUES ('docCount', ${sqliteString(String(docCount))});`,
-      "INSERT INTO docs_fts(docs_fts) VALUES('optimize');"
-    ].join("\n"));
+    if (batch.length) insertFtsDocs(handle, tmpPath, batch, docCount - batch.length + 1);
+    insertFtsMetaRows(handle, [{ key: "docCount", value: String(docCount) }]);
+    execFtsBuildSql(handle, "INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
+    closeFtsBuildDb(handle);
+    handle = null;
     fs.renameSync(tmpPath, ftsPath);
     rememberFtsCache(ftsPath, true);
   } catch (error) {
-    try {
-      fs.rmSync(tmpPath, { force: true });
-    } catch {
-      // Ignore optional FTS cleanup failure.
-    }
+    if (handle) closeFtsBuildDb(handle);
+    cleanupFtsTmpFiles(tmpPath);
     try {
       fs.rmSync(ftsPath, { force: true });
     } catch {
@@ -308,68 +363,272 @@ function buildFtsIndexSummary(env = process.env) {
   return {
     version: INDEX_VERSION,
     builtAt,
+    sessionFingerprint: snapshot.fingerprint,
     docCount,
     avgDocLength: docCount ? totalLength / docCount : 0,
     summaryOnly: true
   };
 }
 
-function insertFtsDocs(dbPath, docs, rowidStart = 1) {
-  for (let start = 0; start < docs.length; start += SQLITE_BUILD_BATCH_SIZE) {
-    const statements = ["BEGIN;"];
-    const batch = docs.slice(start, start + SQLITE_BUILD_BATCH_SIZE);
-    for (let offset = 0; offset < batch.length; offset++) {
-      const rowid = rowidStart + start + offset;
-      const doc = batch[offset];
-      statements.push(
-        `INSERT INTO docs(rowid, doc_id, session_id, provider, source_type, repo_canonical, repo_display, scope_canonical, cwd, title, started_at, occurred_at, role, event_id, event_kind, message_index, path, matched_text) VALUES (` +
-          [
-            rowid,
-            sqliteString(doc.id || ""),
-            sqliteString(doc.sessionId || ""),
-            sqliteString(doc.provider || ""),
-            sqliteString(doc.sourceType || ""),
-            sqliteString(doc.repoCanonical || ""),
-            sqliteString(doc.repoDisplay || ""),
-            sqliteString(doc.scopeCanonical || ""),
-            sqliteString(doc.cwd || ""),
-            sqliteString(doc.title || ""),
-            sqliteString(doc.startedAt || ""),
-            sqliteString(doc.occurredAt || ""),
-            sqliteString(doc.role || ""),
-            sqliteString(doc.eventId || ""),
-            sqliteString(doc.eventKind || ""),
-            Number.isFinite(Number(doc.messageIndex)) ? Number(doc.messageIndex) : "NULL",
-            sqliteString(doc.path || ""),
-            sqliteString(doc.matchedText || "")
-          ].join(", ") +
-          ");"
-      );
-      statements.push(`INSERT INTO docs_fts(rowid, text) VALUES (${rowid}, ${sqliteString(doc.text || "")});`);
+const FTS_DOCS_INSERT_SQL =
+  "INSERT INTO docs(rowid, doc_id, session_id, provider, source_type, conversation_kind, is_subagent, repo_canonical, repo_display, scope_canonical, storage_scope, cwd, title, started_at, occurred_at, role, event_id, event_kind, message_index, path, matched_text) " +
+  "VALUES (@rowid, @doc_id, @session_id, @provider, @source_type, @conversation_kind, @is_subagent, @repo_canonical, @repo_display, @scope_canonical, @storage_scope, @cwd, @title, @started_at, @occurred_at, @role, @event_id, @event_kind, @message_index, @path, @matched_text)";
+const FTS_FTS_INSERT_SQL = "INSERT INTO docs_fts(rowid, text) VALUES (@rowid, @text)";
+
+function docInsertParams(doc, rowid) {
+  return {
+    rowid,
+    doc_id: doc.id || "",
+    session_id: doc.sessionId || "",
+    provider: doc.provider || "",
+    source_type: doc.sourceType || "",
+    conversation_kind: doc.conversationKind || "",
+    // Precompute the subagent flag once at index time using the same JS
+    // predicate the rest of the codebase uses. Querying an integer column is
+    // ~50x faster than `NOT GLOB '*_subagent'`, which scans every row's
+    // string char-by-char because of the leading wildcard.
+    is_subagent: isSubagentSession(doc) ? 1 : 0,
+    repo_canonical: doc.repoCanonical || "",
+    repo_display: doc.repoDisplay || "",
+    scope_canonical: doc.scopeCanonical || "",
+    storage_scope: doc.storageScope || "",
+    cwd: doc.cwd || "",
+    title: doc.title || "",
+    started_at: doc.startedAt || "",
+    occurred_at: doc.occurredAt || "",
+    role: doc.role || "",
+    event_id: doc.eventId || "",
+    event_kind: doc.eventKind || "",
+    message_index: Number.isFinite(Number(doc.messageIndex)) ? Number(doc.messageIndex) : null,
+    path: doc.path || "",
+    matched_text: doc.matchedText || ""
+  };
+}
+
+function insertFtsMetaRows(handle, rows) {
+  if (handle.kind === "native") {
+    const stmt = handle.db.prepare("INSERT INTO meta(key, value) VALUES (?, ?)");
+    const insertMany = handle.db.transaction((items) => {
+      for (const row of items) stmt.run(row.key, row.value);
+    });
+    insertMany(rows);
+    return;
+  }
+  const sql = rows
+    .map((row) => `INSERT INTO meta(key, value) VALUES ('${String(row.key).replace(/'/g, "''")}', '${String(row.value).replace(/'/g, "''")}');`)
+    .join("\n");
+  legacyRunSqliteScript(handle.dbPath, sql);
+}
+
+function insertFtsDocs(handleOrPath, dbPathHint, docs, rowidStart = 1) {
+  // Backwards-compatible call shape: tests/external callers may pass
+  // (dbPath, docs, rowidStart). When the first argument looks like a path
+  // we open a short-lived build connection just for this batch.
+  let handle = handleOrPath && typeof handleOrPath === "object" && handleOrPath.kind ? handleOrPath : null;
+  let docsArg = docs;
+  let rowidArg = rowidStart;
+  let openedHere = false;
+  if (!handle) {
+    handle = openFtsBuildDb(handleOrPath);
+    openedHere = true;
+    docsArg = dbPathHint;
+    rowidArg = docs ?? 1;
+  }
+  try {
+    if (handle.kind === "native") {
+      const docStmt = handle.db.prepare(FTS_DOCS_INSERT_SQL);
+      const ftsStmt = handle.db.prepare(FTS_FTS_INSERT_SQL);
+      const insertMany = handle.db.transaction((items) => {
+        for (let offset = 0; offset < items.length; offset++) {
+          const rowid = rowidArg + offset;
+          const doc = items[offset];
+          docStmt.run(docInsertParams(doc, rowid));
+          ftsStmt.run({ rowid, text: doc.text || "" });
+        }
+      });
+      // Chunk to avoid pathological transaction sizes; better-sqlite3 handles
+      // ~10k inserts/transaction comfortably but we keep batches bounded for
+      // memory and progress observability.
+      for (let start = 0; start < docsArg.length; start += SQLITE_BUILD_BATCH_SIZE) {
+        const slice = docsArg.slice(start, start + SQLITE_BUILD_BATCH_SIZE);
+        insertMany(slice);
+        rowidArg += slice.length;
+      }
+      return;
+    }
+    // Legacy spawn path. Same text-script semantics as before, just without
+    // the helper rename.
+    for (let start = 0; start < docsArg.length; start += SQLITE_BUILD_BATCH_SIZE) {
+      const statements = ["BEGIN;"];
+      const batch = docsArg.slice(start, start + SQLITE_BUILD_BATCH_SIZE);
+      for (let offset = 0; offset < batch.length; offset++) {
+        const rowid = rowidArg + start + offset;
+        const doc = batch[offset];
+        const sqlString = (value) => `'${String(value == null ? "" : value).replace(/'/g, "''")}'`;
+        statements.push(
+          "INSERT INTO docs(rowid, doc_id, session_id, provider, source_type, conversation_kind, is_subagent, repo_canonical, repo_display, scope_canonical, storage_scope, cwd, title, started_at, occurred_at, role, event_id, event_kind, message_index, path, matched_text) VALUES (" +
+            [
+              rowid,
+              sqlString(doc.id || ""),
+              sqlString(doc.sessionId || ""),
+              sqlString(doc.provider || ""),
+              sqlString(doc.sourceType || ""),
+              sqlString(doc.conversationKind || ""),
+              isSubagentSession(doc) ? 1 : 0,
+              sqlString(doc.repoCanonical || ""),
+              sqlString(doc.repoDisplay || ""),
+              sqlString(doc.scopeCanonical || ""),
+              sqlString(doc.storageScope || ""),
+              sqlString(doc.cwd || ""),
+              sqlString(doc.title || ""),
+              sqlString(doc.startedAt || ""),
+              sqlString(doc.occurredAt || ""),
+              sqlString(doc.role || ""),
+              sqlString(doc.eventId || ""),
+              sqlString(doc.eventKind || ""),
+              Number.isFinite(Number(doc.messageIndex)) ? Number(doc.messageIndex) : "NULL",
+              sqlString(doc.path || ""),
+              sqlString(doc.matchedText || "")
+            ].join(", ") +
+            ");"
+        );
+        statements.push(`INSERT INTO docs_fts(rowid, text) VALUES (${rowid}, '${String(doc.text || "").replace(/'/g, "''")}');`);
+      }
+      statements.push("COMMIT;");
+      legacyRunSqliteScript(handle.dbPath, statements.join("\n"));
     }
-    statements.push("COMMIT;");
-    runSqliteScript(dbPath, statements.join("\n"));
+  } finally {
+    if (openedHere) closeFtsBuildDb(handle);
   }
 }
 
-function runSqliteScript(dbPath, script) {
+/**
+ * Open a fresh write connection for index builds. Build paths run inside
+ * spawned child processes (`buildIndexInChild`) so the connection is
+ * short-lived and not cached.
+ */
+function openFtsBuildDb(dbPath) {
+  const Database = loadBetterSqlite3();
+  if (Database) {
+    // `new Database()` can throw on ABI mismatch (different Node version
+    // than the one better-sqlite3 was compiled for). Without this guard the
+    // exception propagates up to buildFtsIndex's catch block, which then
+    // deletes the FTS index file — hard-breaking search until next reindex.
+    // Falling back to the spawn path preserves search instead.
+    try {
+      const db = new Database(dbPath);
+      db.pragma("journal_mode = OFF");
+      db.pragma("synchronous = OFF");
+      db.pragma("temp_store = MEMORY");
+      db.pragma("locking_mode = EXCLUSIVE");
+      return { kind: "native", db };
+    } catch (error) {
+      markBetterSqlite3Broken(error);
+      // Fall through to spawn handle.
+    }
+  }
+  return { kind: "spawn", dbPath };
+}
+
+function closeFtsBuildDb(handle) {
+  if (handle?.kind === "native") {
+    try { handle.db.close(); } catch { /* ignore */ }
+  }
+}
+
+function execFtsBuildSql(handle, sql) {
+  if (handle.kind === "native") {
+    handle.db.exec(sql);
+    return;
+  }
+  legacyRunSqliteScript(handle.dbPath, sql);
+}
+
+/**
+ * Open or reuse a read-only connection for the FTS sidecar. The connection is
+ * invalidated when the on-disk file's inode/size/mtime changes — the index
+ * rebuild atomically renames a fresh DB into place, so the inode flips and
+ * any stale prepared statements are dropped.
+ */
+function openFtsReadDb(ftsPath, stat) {
+  const Database = loadBetterSqlite3();
+  if (!Database) return null;
+  if (
+    _ftsReadConn.db &&
+    _ftsReadConn.path === ftsPath &&
+    _ftsReadConn.ino === stat.ino &&
+    _ftsReadConn.mtimeMs === stat.mtimeMs &&
+    _ftsReadConn.size === stat.size
+  ) {
+    return _ftsReadConn;
+  }
+  closeFtsReadDb();
+  let db;
+  try {
+    db = new Database(ftsPath, { readonly: true, fileMustExist: true });
+    db.pragma("query_only = ON");
+  } catch (error) {
+    // ABI-mismatch crashes look like ordinary throws here. Latch the module
+    // as broken so other readers/builders take the spawn path immediately
+    // instead of repeatedly hitting the same crash.
+    markBetterSqlite3Broken(error);
+    return null;
+  }
+  _ftsReadConn.path = ftsPath;
+  _ftsReadConn.ino = stat.ino;
+  _ftsReadConn.mtimeMs = stat.mtimeMs;
+  _ftsReadConn.size = stat.size;
+  _ftsReadConn.db = db;
+  _ftsReadConn.prepared = new Map();
+  return _ftsReadConn;
+}
+
+function closeFtsReadDb() {
+  if (_ftsReadConn.db) {
+    try { _ftsReadConn.db.close(); } catch { /* ignore */ }
+  }
+  _ftsReadConn.path = "";
+  _ftsReadConn.ino = 0;
+  _ftsReadConn.mtimeMs = 0;
+  _ftsReadConn.size = 0;
+  _ftsReadConn.db = null;
+  _ftsReadConn.prepared = null;
+}
+
+function prepareFtsStatement(conn, sql) {
+  let stmt = conn.prepared.get(sql);
+  if (!stmt) {
+    stmt = conn.db.prepare(sql);
+    conn.prepared.set(sql, stmt);
+  }
+  return stmt;
+}
+
+/**
+ * Last-resort fallback: spawn the system `sqlite3` binary. Only used when the
+ * better-sqlite3 native binding could not be loaded (older Node, missing build
+ * toolchain). Pricing this path stays in line with the pre-PR-1 behavior so
+ * users without a toolchain are not regressed.
+ */
+function legacyRunSqliteScript(dbPath, script) {
   const result = spawnSync("sqlite3", [dbPath], {
     argv0: "agentlog-sqlite",
     input: script,
     encoding: "utf8",
     maxBuffer: 1024 * 1024 * 20,
-    timeout: SQLITE_QUERY_TIMEOUT_MS
+    timeout: 5000
   });
   if (result.error) throw result.error;
   if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || "sqlite3 failed").trim());
 }
 
-function sqliteJson(dbPath, query) {
-  const result = spawnSync("sqlite3", [dbPath, "-json", query], {
+function legacySqliteJson(dbPath, query, params = []) {
+  const inlined = inlineSqlParams(query, params);
+  const result = spawnSync("sqlite3", [dbPath, "-json", inlined], {
     argv0: "agentlog-sqlite",
     encoding: "utf8",
     maxBuffer: 1024 * 1024 * 20,
-    timeout: SQLITE_QUERY_TIMEOUT_MS
+    timeout: 5000
   });
   if (result.error || result.status !== 0) return null;
   try {
@@ -379,8 +638,25 @@ function sqliteJson(dbPath, query) {
   }
 }
 
-function sqliteString(value) {
-  return `'${String(value == null ? "" : value).replace(/'/g, "''")}'`;
+/**
+ * Substitute `?` placeholders for the legacy spawn fallback. Not used by the
+ * better-sqlite3 path — that path passes params directly to prepared
+ * statements. Quoting matches the prior `sqliteString` semantics.
+ */
+function inlineSqlParams(query, params) {
+  if (!params || !params.length) return query;
+  let index = 0;
+  return query.replace(/\?/g, () => {
+    if (index >= params.length) return "?";
+    const value = params[index++];
+    if (value == null) return "NULL";
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+    return `'${String(value).replace(/'/g, "''")}'`;
+  });
+}
+
+function escapeSqlLike(value) {
+  return String(value).replace(/[\\%_]/g, (match) => `\\${match}`);
 }
 
 function rememberFtsCache(ftsPath, available) {
@@ -395,6 +671,21 @@ function rememberFtsCache(ftsPath, available) {
   _ftsCache.size = stat?.size || 0;
   _ftsCache.checkedAtMs = Date.now();
   _ftsCache.available = Boolean(available && stat);
+  if (!available || !stat) closeFtsReadDb();
+}
+
+function readFtsMeta(ftsPath, stat) {
+  const conn = openFtsReadDb(ftsPath, stat);
+  if (conn) {
+    try {
+      const stmt = prepareFtsStatement(conn, "SELECT key, value FROM meta WHERE key IN ('version', 'docCount', 'sessionFingerprint')");
+      return stmt.all();
+    } catch {
+      closeFtsReadDb();
+      return null;
+    }
+  }
+  return legacySqliteJson(ftsPath, "SELECT key, value FROM meta WHERE key IN ('version', 'docCount', 'sessionFingerprint');");
 }
 
 function ftsIndexAvailable(env = process.env, options = {}) {
@@ -404,6 +695,7 @@ function ftsIndexAvailable(env = process.env, options = {}) {
     stat = fs.statSync(ftsPath);
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
+    closeFtsReadDb();
     return false;
   }
   if (
@@ -415,7 +707,7 @@ function ftsIndexAvailable(env = process.env, options = {}) {
   ) {
     return true;
   }
-  const rows = sqliteJson(ftsPath, "SELECT key, value FROM meta WHERE key IN ('version', 'docCount');");
+  const rows = readFtsMeta(ftsPath, stat);
   if (!rows || !rows.some((row) => row.key === "version" && Number(row.value) === INDEX_VERSION)) {
     rememberFtsCache(ftsPath, false);
     return false;
@@ -432,13 +724,20 @@ function docsForEvents(session, events) {
   const indexedKinds = new Set([
     EVENT_KINDS.PROMPT_SUBMITTED,
     EVENT_KINDS.RESPONSE_GENERATED,
-    EVENT_KINDS.TOOL_CALLED
+    EVENT_KINDS.TOOL_CALLED,
+    EVENT_KINDS.TOOL_COMPLETED
   ]);
   return events
     .filter((event) => indexedKinds.has(event.kind))
     .map((event) => {
-      const renderedText = renderEventText(event);
+      let renderedText = renderEventText(event);
       if (!String(renderedText || "").trim()) return null;
+      // Cap tool output to its head only. The first ~600 chars hold the
+      // error message / first lines of a diff / start of a stack trace;
+      // the tail is verbose machine output with near-zero recall value.
+      if (event.kind === EVENT_KINDS.TOOL_COMPLETED && renderedText.length > TOOL_COMPLETED_INDEX_MAX_CHARS) {
+        renderedText = `${renderedText.slice(0, TOOL_COMPLETED_INDEX_MAX_CHARS)} [truncated]`;
+      }
       return {
         id: event.eventId,
         eventId: event.eventId,
@@ -447,9 +746,11 @@ function docsForEvents(session, events) {
         sessionId: session.sessionId,
         provider: event.provider || session.provider,
         sourceType: event.sourceType || session.sourceType || "",
+        conversationKind: session.conversationKind || "",
         repoCanonical: event.repoCanonical || session.repoCanonical || "",
         repoDisplay: displayRepoLabel(session),
         scopeCanonical: event.scopeCanonical || session.scopeCanonical || "",
+        storageScope: session.storageScope || "",
         cwd: session.cwd || "",
         title: session.title || event.indexed?.title || "",
         eventTitle: event.indexed?.title || "",
@@ -465,6 +766,11 @@ function docsForEvents(session, events) {
     .filter(Boolean);
 }
 
+function canonicalDocsForSession(session) {
+  const events = readEvents(session);
+  return events.length ? docsForEvents(session, events) : [];
+}
+
 function docsForTranscript(session, messages) {
   const docs = [];
   for (const message of messages) {
@@ -473,9 +779,11 @@ function docsForTranscript(session, messages) {
       sessionId: session.sessionId,
       provider: session.provider,
       sourceType: session.sourceType || "",
+      conversationKind: session.conversationKind || "",
       repoCanonical: session.repoCanonical || "",
       repoDisplay: displayRepoLabel(session),
       scopeCanonical: session.scopeCanonical || "",
+      storageScope: session.storageScope || "",
       cwd: session.cwd || "",
       title: session.title || "",
       startedAt: session.startedAt,
@@ -539,11 +847,12 @@ function rememberIndexCache(indexPath, index) {
 }
 
 function searchPastSessions(query, options = {}, env = process.env) {
+  const allowMarkdownFallback = Boolean(options.markdownFallback || options.legacyMarkdownFallback || options.allowMarkdownFallback);
   try {
     const eventResults = searchIndexedSessions(query, options, env);
-    if (eventResults.length || options.skipMarkdownFallback) return eventResults;
+    if (eventResults.length || !allowMarkdownFallback || options.skipMarkdownFallback) return eventResults;
   } catch {
-    if (options.skipMarkdownFallback) return [];
+    if (!allowMarkdownFallback || options.skipMarkdownFallback) return [];
     // Fall through to the legacy markdown path below.
   }
   return searchMarkdownSessions(query, options, env);
@@ -553,6 +862,7 @@ function searchMarkdownSessions(query, options = {}, env = process.env) {
   const limit = Math.max(1, Math.min(Number(options.limit || 10), 50));
   const maxMatches = Math.max(limit * 8, 40);
   const includeWebChats = Boolean(options.includeWebChats);
+  const includeSubagents = Boolean(options.includeSubagents || options.include_subagents);
   const filter = normalizeSessionFilter(options);
   const repo = filter.repo || inferCallingRepo(options.cwd || process.cwd());
   const since = parseSinceFilter(options.since);
@@ -561,7 +871,7 @@ function searchMarkdownSessions(query, options = {}, env = process.env) {
   if (!queryTokens.length && !phrase) return [];
 
   const sessions = listSessions(env).filter((session) => {
-    if (!matchesSessionFilter(session, { ...filter, includeWebChats, since })) return false;
+    if (!matchesSessionFilter(session, { ...filter, includeWebChats, includeSubagents, since })) return false;
     const conversationPath = ensureConversationMarkdown(session, env);
     const searchPath = conversationPath || session.transcriptPath;
     session._searchPath = searchPath;
@@ -619,22 +929,23 @@ function searchMarkdownSessions(query, options = {}, env = process.env) {
 function searchIndexedSessions(query, options = {}, env = process.env) {
   const limit = Math.max(1, Math.min(Number(options.limit || 10), 50));
   const includeWebChats = Boolean(options.includeWebChats);
+  const includeSubagents = Boolean(options.includeSubagents || options.include_subagents);
   const filter = normalizeSessionFilter(options);
   const repo = filter.repo || inferCallingRepo(options.cwd || process.cwd());
   const since = parseSinceFilter(options.since);
   const queryTokens = tokenize(query);
   const phrase = String(query || "").trim().toLowerCase();
   if (!queryTokens.length && !phrase) return [];
-  const ftsResults = searchFtsSessions(query, queryTokens, { limit, includeWebChats, filter, repo, since, options }, env);
+  const ftsResults = searchFtsSessions(query, queryTokens, { limit, includeWebChats, includeSubagents, filter, repo, since, options }, env);
   if (ftsResults) return ftsResults;
-  if (options.skipJsonIndex) return [];
+  if (options.skipJsonIndex || !(options.legacyJsonIndex || options.allowJsonIndex)) return [];
   const index = loadIndex(env, { noRebuild: Boolean(options.noRebuild) });
   if (!index) return [];
 
   const scored = [];
   const candidates = candidateDocsForQuery(index, queryTokens, phrase);
   for (const { doc, docIndex } of candidates) {
-    if (!matchesSessionFilter(doc, { ...filter, includeWebChats, since })) continue;
+    if (!matchesSessionFilter(doc, { ...filter, includeWebChats, includeSubagents, since })) continue;
 
     let score = bm25Score(doc, queryTokens, index, docIndex, candidates.termFrequencies);
     if (phrase && doc.text.toLowerCase().includes(phrase)) score += 2.5;
@@ -668,34 +979,43 @@ function searchIndexedSessions(query, options = {}, env = process.env) {
   }));
 }
 
+function dedupeFtsRowsBySession(rows, context) {
+  const bySession = new Map();
+  for (const row of rows) {
+    const doc = ftsRowToDoc(row);
+    if (!matchesSessionFilter(doc, { ...context.filter, includeWebChats: context.includeWebChats, includeSubagents: context.includeSubagents, since: context.since })) continue;
+    if (!context.options.repo && context.repo && doc.repoCanonical === context.repo) {
+      row.rank = Number(row.rank || 0) - 0.05;
+    }
+    if (!bySession.has(doc.sessionId)) bySession.set(doc.sessionId, { doc, row });
+    if (bySession.size >= context.limit) break;
+  }
+  return bySession;
+}
+
 function searchFtsSessions(query, queryTokens, context, env = process.env) {
   const ftsPath = paths(env).ftsIndex;
   if (!ftsIndexAvailable(env, { noStaleCheck: Boolean(context.options.noRebuild || context.options.allowStaleFts) })) return null;
   const matchQuery = ftsMatchQuery(query);
   if (!matchQuery) return [];
-  const bySession = new Map();
-  const batchSize = Math.max(context.limit * 20, FTS_SEARCH_BATCH_SIZE);
-  const maxScanRows = Math.max(batchSize, Math.min(FTS_MAX_SCAN_ROWS, context.limit * 500));
-  let offset = 0;
-  while (offset < maxScanRows && bySession.size < context.limit) {
-    const rows = ftsSearchRows(ftsPath, matchQuery, {
-      limit: Math.min(batchSize, maxScanRows - offset),
-      offset,
-      context
-    });
+  // Single bounded prefix in rank order — FTS5 with bm25 + OFFSET is quadratic,
+  // so we pull one shot and dedupe in JS. Two-tier scan: primary is small and
+  // fast (limit*100, typically 1000), wide cap is only used if dedupe couldn't
+  // fill `limit` distinct sessions from the primary.
+  const primaryScanLimit = Math.max(context.limit * FTS_PRIMARY_SCAN_MULTIPLIER, FTS_SEARCH_BATCH_SIZE);
+  const wideScanLimit = Math.max(primaryScanLimit, Math.min(FTS_MAX_SCAN_ROWS, context.limit * 500));
+
+  let rows = ftsSearchRows(ftsPath, matchQuery, { limit: primaryScanLimit, offset: 0, context });
+  if (!rows) return null;
+  let bySession = dedupeFtsRowsBySession(rows, context);
+  if (bySession.size < context.limit && primaryScanLimit < wideScanLimit) {
+    // Under-filled (e.g. broad term where many top-ranked docs collapse onto
+    // the same session, or filters reject most of the primary set). Re-query
+    // at the wide cap. SQLite re-evaluates the MATCH but the surrounding
+    // prepared statement + OS page cache make the second pass cheap.
+    rows = ftsSearchRows(ftsPath, matchQuery, { limit: wideScanLimit, offset: 0, context });
     if (!rows) return null;
-    if (!rows.length) break;
-    offset += rows.length;
-    for (const row of rows) {
-      const doc = ftsRowToDoc(row);
-      if (!matchesSessionFilter(doc, { ...context.filter, includeWebChats: context.includeWebChats, since: context.since })) continue;
-      if (!context.options.repo && context.repo && doc.repoCanonical === context.repo) {
-        row.rank = Number(row.rank || 0) - 0.05;
-      }
-      if (!bySession.has(doc.sessionId)) bySession.set(doc.sessionId, { doc, row });
-      if (bySession.size >= context.limit) break;
-    }
-    if (rows.length < batchSize) break;
+    bySession = dedupeFtsRowsBySession(rows, context);
   }
   return [...bySession.values()].slice(0, context.limit).map(({ doc, row }) => ({
     session_id: doc.sessionId,
@@ -719,31 +1039,75 @@ function searchFtsSessions(query, queryTokens, context, env = process.env) {
 }
 
 function ftsSearchRows(ftsPath, matchQuery, options) {
-  const clauses = [`docs_fts MATCH ${sqliteString(matchQuery)}`];
   const filter = options.context?.filter || {};
-  if (filter.provider) clauses.push(`d.provider = ${sqliteString(filter.provider)}`);
   const sourceTypes = filter.sourceTypes?.length ? filter.sourceTypes : filter.sourceType ? [filter.sourceType] : [];
-  if (sourceTypes.length) clauses.push(`d.source_type IN (${sourceTypes.map(sqliteString).join(", ")})`);
+  const params = [matchQuery];
+  const clauses = ["docs_fts MATCH ?"];
+  if (filter.provider) {
+    clauses.push("d.provider = ?");
+    params.push(filter.provider);
+  }
+  if (sourceTypes.length) {
+    clauses.push(`d.source_type IN (${sourceTypes.map(() => "?").join(", ")})`);
+    for (const value of sourceTypes) params.push(value);
+  }
+  if (!options.context?.includeSubagents) {
+    // Precomputed integer flag (set in docInsertParams). Equivalent to the
+    // old `NOT GLOB '*_subagent'` but a 1-byte compare instead of a
+    // leading-wildcard string scan over every FTS-matched row.
+    clauses.push("(d.is_subagent IS NULL OR d.is_subagent = 0)");
+  }
   if (options.context?.since) {
-    const since = sqliteString(options.context.since.toISOString());
-    clauses.push(`(d.started_at >= ${since} OR (d.started_at = '' AND d.occurred_at >= ${since}))`);
+    const since = options.context.since.toISOString();
+    clauses.push("(d.started_at >= ? OR (d.started_at = '' AND d.occurred_at >= ?))");
+    params.push(since, since);
+  }
+  if (filter.repo) {
+    const repo = String(filter.repo).toLowerCase();
+    const repoLike = `%${escapeSqlLike(repo)}%`;
+    const repoColumns = ["d.repo_canonical", "d.repo_display", "d.scope_canonical", "d.cwd"];
+    clauses.push(
+      "(" +
+        repoColumns.map((column) => `(LOWER(${column}) = ? OR LOWER(${column}) LIKE ? ESCAPE '\\')`).join(" OR ") +
+        ")"
+    );
+    for (const column of repoColumns) {
+      void column;
+      params.push(repo, repoLike);
+    }
+  }
+  const limit = Math.max(1, Number(options.limit) || FTS_SEARCH_BATCH_SIZE);
+  const offset = Math.max(0, Number(options.offset) || 0);
+  // LIMIT/OFFSET stay parameterized so a single prepared-statement shape
+  // covers every page; the filter shape varies by query so its SQL is built
+  // per call but the resulting prepared statement is cached on the connection.
+  const sql = [
+    "SELECT",
+    "  d.doc_id, d.session_id, d.provider, d.source_type, d.conversation_kind, d.is_subagent, d.repo_canonical, d.repo_display,",
+    "  d.scope_canonical, d.storage_scope, d.cwd, d.title, d.started_at, d.occurred_at, d.role,",
+    "  d.event_id, d.event_kind, d.message_index, d.path, d.matched_text,",
+    "  snippet(docs_fts, 0, '', '', '...', 32) AS excerpt,",
+    "  bm25(docs_fts) AS rank",
+    "FROM docs_fts",
+    "JOIN docs d ON d.rowid = docs_fts.rowid",
+    `WHERE ${clauses.join(" AND ")}`,
+    "ORDER BY rank ASC, d.occurred_at DESC, d.started_at DESC",
+    "LIMIT ? OFFSET ?"
+  ].join("\n");
+  params.push(limit, offset);
+
+  let stat;
+  try { stat = fs.statSync(ftsPath); } catch { return null; }
+  const conn = openFtsReadDb(ftsPath, stat);
+  if (conn) {
+    try {
+      return prepareFtsStatement(conn, sql).all(...params);
+    } catch {
+      closeFtsReadDb();
+      return null;
+    }
   }
-  return sqliteJson(
-    ftsPath,
-    [
-      "SELECT",
-      "  d.doc_id, d.session_id, d.provider, d.source_type, d.repo_canonical, d.repo_display,",
-      "  d.scope_canonical, d.cwd, d.title, d.started_at, d.occurred_at, d.role,",
-      "  d.event_id, d.event_kind, d.message_index, d.path, d.matched_text,",
-      "  snippet(docs_fts, 0, '', '', '...', 32) AS excerpt,",
-      "  bm25(docs_fts) AS rank",
-      "FROM docs_fts",
-      "JOIN docs d ON d.rowid = docs_fts.rowid",
-      `WHERE ${clauses.join(" AND ")}`,
-      "ORDER BY rank ASC, d.occurred_at DESC, d.started_at DESC",
-      `LIMIT ${Math.max(1, Number(options.limit) || FTS_SEARCH_BATCH_SIZE)} OFFSET ${Math.max(0, Number(options.offset) || 0)};`
-    ].join("\n")
-  );
+  return legacySqliteJson(ftsPath, sql, params);
 }
 
 function ftsRowToDoc(row) {
@@ -752,9 +1116,12 @@ function ftsRowToDoc(row) {
     sessionId: row.session_id || "",
     provider: row.provider || "",
     sourceType: row.source_type || "",
+    conversationKind: row.conversation_kind || "",
+    isSubagent: row.is_subagent == null ? undefined : Number(row.is_subagent),
     repoCanonical: row.repo_canonical || "",
     repoDisplay: row.repo_display || "",
     scopeCanonical: row.scope_canonical || "",
+    storageScope: row.storage_scope || "",
     cwd: row.cwd || "",
     title: row.title || "",
     startedAt: row.started_at || "",
@@ -980,11 +1347,16 @@ function inferCallingRepo(cwd) {
 }
 
 function listHistorySessions(options = {}, env = process.env) {
+  return listHistorySessionsFromSessions(listSessions(env), options);
+}
+
+function listHistorySessionsFromSessions(sessions, options = {}) {
   const since = parseSinceFilter(options.since);
   const includeWebChats = options.includeWebChats !== false;
+  const includeSubagents = Boolean(options.includeSubagents || options.include_subagents);
   const filter = normalizeSessionFilter(options);
-  return listSessions(env)
-    .filter((session) => matchesSessionFilter(session, { ...filter, includeWebChats, since }))
+  return (Array.isArray(sessions) ? sessions : [])
+    .filter((session) => matchesSessionFilter(session, { ...filter, includeWebChats, includeSubagents, since }))
     .map(historySessionSummary)
     .sort((a, b) => String(historySessionSortTime(b)).localeCompare(String(historySessionSortTime(a))));
 }
@@ -1005,6 +1377,7 @@ function historySessionSummary(session) {
     chat_display_name: session.chatDisplayName || undefined,
     chat_project_path: session.chatProjectPath || undefined,
     conversation_kind: session.conversationKind || undefined,
+    parent_composer_id: session.parentComposerId || undefined,
     pinned: Boolean(session.pinned) || undefined,
     cwd: session.cwd || undefined,
     title: session.title || undefined,
@@ -1017,9 +1390,25 @@ function historySessionSummary(session) {
     usage: session.usage || undefined,
     estimatedUsage: session.estimatedUsage || undefined,
     models: session.models || undefined,
+    toolUsage: session.toolUsage || undefined,
+    outputTokenWork: session.outputTokenWork || undefined,
+    outcomes: session.outcomes || undefined,
     cursorCommandTypeCounts: session.cursorCommandTypeCounts || undefined,
+    codexTurnContext: session.sessionSummary?.codexTurnContext || undefined,
+    sidecarEffort: session.sessionSummary?.claudeCodeSidecar?.effort || undefined,
+    claudeTasks: session.sessionSummary?.claudeTasks
+      ? { count: session.sessionSummary.claudeTasks.count, completed: session.sessionSummary.claudeTasks.completed }
+      : undefined,
+    cursorFileHistory: session.sessionSummary?.cursorFileHistory
+      ? { snapshots: session.sessionSummary.cursorFileHistory.snapshots, bytes: session.sessionSummary.cursorFileHistory.bytes }
+      : undefined,
+    artifactCount: Array.isArray(session.artifacts) && session.artifacts.length ? session.artifacts.length : undefined,
+    artifactBytes: Array.isArray(session.artifacts) && session.artifacts.length
+      ? session.artifacts.reduce((sum, item) => sum + (Number(item?.bytes) || 0), 0)
+      : undefined,
     conversation: session.conversationPath,
-    transcript: session.transcriptPath
+    transcript: session.transcriptPath,
+    events: session.eventPath
   };
 }
 
@@ -1042,6 +1431,7 @@ function displayRepoLabel(session) {
 function displayScopeLabel(scope) {
   return {
     "claude-desktop/uncategorized": "Claude Desktop (uncategorized)",
+    "claude-cowork/uncategorized": "Claude Cowork (uncategorized)",
     "claude-code-desktop/uncategorized": "Claude Code Desktop (uncategorized)"
   }[scope] || scope;
 }
@@ -1077,6 +1467,10 @@ function listRecentSessions(limit = 20, options = {}, env = process.env) {
   return listHistorySessions(options, env).slice(0, limit);
 }
 
+function listRecentSessionsFromSessions(sessions, limit = 20, options = {}) {
+  return listHistorySessionsFromSessions(sessions, options).slice(0, limit);
+}
+
 function normalizeSessionFilter(options = {}) {
   const providerInput = options.provider || options.source || "";
   const normalizedProvider = normalizeProviderFilter(providerInput);
@@ -1097,6 +1491,8 @@ function normalizeProviderFilter(value) {
     claude_cli: { provider: "claude_code" },
     claude_desktop: { provider: "claude_desktop" },
     claude_code_desktop: { provider: "claude_desktop", sourceType: "claude-code-desktop-metadata", sourceTypes: ["claude-code-desktop-metadata"] },
+    claude_cowork: { provider: "claude_desktop", sourceType: "claude-workspace-desktop", sourceTypes: ["claude-workspace-desktop"] },
+    claude_cowork_desktop: { provider: "claude_desktop", sourceType: "claude-workspace-desktop", sourceTypes: ["claude-workspace-desktop"] },
     claude_workspace: { provider: "claude_desktop", sourceType: "claude-workspace-desktop", sourceTypes: ["claude-workspace-desktop"] },
     claude_workspace_desktop: { provider: "claude_desktop", sourceType: "claude-workspace-desktop", sourceTypes: ["claude-workspace-desktop"] },
     claude_sdk: { provider: "claude_sdk" },
@@ -1113,10 +1509,21 @@ function normalizeProviderFilter(value) {
     aider: { provider: "aider", sourceType: "aider-chat-history", sourceTypes: ["aider-chat-history"] },
     devin: { provider: "devin" },
     devin_cli: { provider: "devin", sourceType: "devin-cli-history", sourceTypes: ["devin-cli-history"] },
+    devin_desktop: { provider: "devin", sourceType: "devin-desktop-acp-events", sourceTypes: ["devin-desktop-acp-events"] },
     gemini: { provider: "gemini_cli" },
     gemini_cli: { provider: "gemini_cli" },
     windsurf: { provider: "windsurf" },
     antigravity: { provider: "antigravity" },
+    antigravity_cli: { provider: "antigravity_cli" },
+    antigravity_ide: { provider: "antigravity_ide" },
+    copilot: { provider: "copilot" },
+    copilot_cli: { provider: "copilot" },
+    factory: { provider: "factory" },
+    factory_droid: { provider: "factory" },
+    droid: { provider: "factory" },
+    grok: { provider: "grok" },
+    grok_build: { provider: "grok" },
+    pi: { provider: "pi" },
     chatgpt: { provider: "chatgpt" },
     claude_web: { provider: "claude_web" },
     claude_ai: { provider: "claude_web" }
@@ -1128,6 +1535,7 @@ function matchesSessionFilter(session, filter) {
   if (filter.provider && session.provider !== filter.provider) return false;
   const sourceTypes = filter.sourceTypes?.length ? filter.sourceTypes : filter.sourceType ? [filter.sourceType] : [];
   if (sourceTypes.length && !sourceTypes.includes(session.sourceType)) return false;
+  if (!filter.includeSubagents && isSubagentSession(session)) return false;
   if (!filter.includeWebChats && session.scopeCanonical && session.storageScope !== "local") return false;
   if (filter.repo && !matchesRepoFilter(session, filter.repo)) return false;
   if (filter.since) {
@@ -1138,6 +1546,10 @@ function matchesSessionFilter(session, filter) {
   return true;
 }
 
+function isSubagentSession(session) {
+  return /_subagent$/.test(String(session?.conversationKind || session?.conversation_kind || ""));
+}
+
 function matchesRepoFilter(session, repoFilter) {
   const wanted = String(repoFilter || "").toLowerCase();
   if (!wanted) return true;
@@ -1202,22 +1614,24 @@ function rebuildIndexSummary(env = process.env, options = {}) {
 }
 
 function indexIsStale(indexPath, env = process.env) {
-  let indexStat;
-  try {
-    indexStat = fs.statSync(indexPath);
-  } catch {
-    return true;
-  }
-  for (const session of listSessions(env)) {
+  const expected = listSessionsSnapshot(env).fingerprint;
+  const actual = indexSessionFingerprint(indexPath, env);
+  return !actual || actual !== expected;
+}
+
+function indexSessionFingerprint(indexPath, env = process.env) {
+  const ftsPath = paths(env).ftsIndex;
+  if (path.resolve(indexPath) === path.resolve(ftsPath)) {
+    let stat;
     try {
-      if (fs.statSync(session.transcriptPath).mtimeMs > indexStat.mtimeMs) return true;
-      if (fs.statSync(session.metadataPath).mtimeMs > indexStat.mtimeMs) return true;
-      if (session.eventPath && fs.existsSync(session.eventPath) && fs.statSync(session.eventPath).mtimeMs > indexStat.mtimeMs) return true;
+      stat = fs.statSync(ftsPath);
     } catch {
-      return true;
+      return "";
     }
+    const rows = readFtsMeta(ftsPath, stat);
+    return rows?.find((row) => row.key === "sessionFingerprint")?.value || "";
   }
-  return false;
+  return readIndexSummary(indexPath)?.sessionFingerprint || "";
 }
 
 function parseSinceFilter(value) {
@@ -1258,11 +1672,23 @@ module.exports = {
   buildIndexSummary,
   chunkText,
   listHistorySessions,
+  listHistorySessionsFromSessions,
   listRecentSessions,
+  listRecentSessionsFromSessions,
   loadIndex,
   readIndexSummary,
+  rebuildIndexSummary,
   reindexIfNeeded,
   sessionHistoryTime,
   searchPastSessions,
-  tokenize
+  tokenize,
+  // Test-only handles so we can simulate native-binding failures without
+  // touching the on-disk .node file. Not part of any public contract.
+  _searchInternals: {
+    openFtsBuildDb,
+    openFtsReadDb,
+    loadBetterSqlite3,
+    markBetterSqlite3Broken,
+    resetBetterSqlite3State
+  }
 };