agentel 0.2.8 → 0.3.0

package/src/session-store.js

@@ -0,0 +1,405 @@
+"use strict";
+
+// SQLite-backed session metadata index.
+//
+// Why this exists:
+//   listSessions used to walk every *.metadata.json under the archive on each
+//   read (~85ms warm for 3,900 sessions on the dev archive). A JSON
+//   session-list index later replaced the walk, but parsing the 22MB file
+//   still cost ~125ms on every cold list-endpoint hit. SQLite gives us
+//   indexed ORDER BY / WHERE / GROUP BY with sub-millisecond reads and
+//   incremental upserts on import.
+//
+// Source of truth: still the *.metadata.json files on disk. This DB is a
+// derived cache, rebuildable any time. If it goes missing/corrupt the
+// archive.js fallback rebuilds it by walking the filesystem.
+//
+// Schema is a hybrid: hot columns are extracted so SQL can index/sort/group;
+// everything else is stored as an opaque JSON blob in session_json. This
+// avoids maintaining 30+ ALTER-able columns as session metadata evolves.
+
+const fs = require("fs");
+const path = require("path");
+const { ensureDir } = require("./paths");
+
+const SESSION_STORE_VERSION = 2;
+
+let _Database = null;
+let _driverLoaded = false;
+let _driverLoadError = null;
+let _driverBroken = false;
+
+const _connState = {
+  path: "",
+  ino: 0,
+  db: null,
+  prepared: null,
+  broken: false
+};
+
+function loadDriver() {
+  if (_driverLoaded) return _driverBroken ? null : _Database;
+  _driverLoaded = true;
+  try {
+    _Database = require("better-sqlite3");
+  } catch (error) {
+    _Database = null;
+    _driverLoadError = error;
+  }
+  return _Database;
+}
+
+function markDriverBroken() {
+  _driverBroken = true;
+  _Database = null;
+  closeConnection();
+}
+
+function closeConnection() {
+  if (_connState.db) {
+    try { _connState.db.close(); } catch { /* ignore */ }
+  }
+  _connState.db = null;
+  _connState.prepared = null;
+  _connState.path = "";
+  _connState.ino = 0;
+  _connState.broken = false;
+}
+
+/**
+ * Path to the sessions SQLite file inside an archive root. Kept as its own
+ * file so an FTS rebuild (different version, different cadence) does not
+ * disturb the session index.
+ */
+function sessionStorePath(archiveRoot) {
+  return path.join(archiveRoot, "indexes", "sessions", "sessions.sqlite");
+}
+
+const SCHEMA_SQL = [
+  "CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);",
+  "CREATE TABLE IF NOT EXISTS sessions (",
+  "  session_id TEXT PRIMARY KEY,",
+  "  metadata_path TEXT NOT NULL,",
+  "  mtime_ms INTEGER NOT NULL,",
+  "  size INTEGER NOT NULL,",
+  "  started_at TEXT,",
+  "  ended_at TEXT,",
+  "  provider TEXT,",
+  "  source_type TEXT,",
+  "  repo_canonical TEXT,",
+  "  scope_canonical TEXT,",
+  "  storage_scope TEXT,",
+  "  conversation_kind TEXT,",
+  "  is_subagent INTEGER NOT NULL DEFAULT 0,",
+  // source_path is the original importer-side path the session came from
+  // (e.g. a Cursor agent-transcripts folder). Used by the Cursor/Devin
+  // multi-session-store provider flow to supersede prior snapshots written
+  // under the same source.
+  "  source_path TEXT,",
+  "  session_json TEXT NOT NULL",
+  ");",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_started_at_desc ON sessions(started_at DESC);",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_provider ON sessions(provider);",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_repo_canonical ON sessions(repo_canonical);",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_is_subagent ON sessions(is_subagent);",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_metadata_path ON sessions(metadata_path);",
+  "CREATE INDEX IF NOT EXISTS idx_sessions_provider_source_path ON sessions(provider, source_path);"
+].join("\n");
+
+/**
+ * Open or reuse a connection. Returns null if the driver is unavailable
+ * (the caller then falls back to the JSON / filesystem path). A wedged
+ * driver (ABI mismatch surfacing at first `new Database()`) latches so we
+ * do not re-attempt on every call.
+ */
+function openConnection(archiveRoot) {
+  if (_driverBroken) return null;
+  const Driver = loadDriver();
+  if (!Driver) return null;
+  const filePath = sessionStorePath(archiveRoot);
+  let stat = null;
+  try { stat = fs.statSync(filePath); } catch { stat = null; }
+  if (_connState.db && _connState.path === filePath && stat && _connState.ino === stat.ino) {
+    return _connState;
+  }
+  closeConnection();
+  ensureDir(path.dirname(filePath));
+  let db;
+  try {
+    db = new Driver(filePath);
+  } catch (error) {
+    if (isAbiMismatch(error)) {
+      // Wedged native binding — latch so we don't retry this process. The
+      // archive.js fallback path takes over.
+      markDriverBroken();
+      return null;
+    }
+    // Any other failure (truncated file, partial write from an OS crash,
+    // unreadable bytes, schema mismatch SQLite can't parse) means the file
+    // on disk is unusable. Since this DB is a derived cache rebuildable
+    // from *.metadata.json files, unlink so the next caller gets a fresh
+    // db instead of pinning the broken state for the rest of the process.
+    try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+    try { fs.unlinkSync(`${filePath}-wal`); } catch { /* ignore */ }
+    try { fs.unlinkSync(`${filePath}-shm`); } catch { /* ignore */ }
+    return null;
+  }
+  try {
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    db.pragma("temp_store = MEMORY");
+    // Derived cache: bumping SESSION_STORE_VERSION wipes the sessions table
+    // so we can change the schema without writing ALTERs. The on-disk
+    // metadata.json files are the source of truth; the next list call
+    // repopulates from a filesystem walk.
+    let storedVersion = "";
+    try {
+      const row = db.prepare("SELECT value FROM meta WHERE key = 'version'").get();
+      storedVersion = String(row?.value || "");
+    } catch {
+      // meta table may not exist on a fresh db — fine.
+    }
+    if (storedVersion && storedVersion !== String(SESSION_STORE_VERSION)) {
+      try { db.exec("DROP TABLE IF EXISTS sessions"); } catch { /* ignore */ }
+    }
+    db.exec(SCHEMA_SQL);
+    upsertMeta(db, "version", String(SESSION_STORE_VERSION));
+    upsertMeta(db, "archive_root", archiveRoot);
+  } catch (error) {
+    // Schema setup failed — the file is likely partially populated or has
+    // an unreadable on-disk schema header. Unlink so the next caller gets
+    // a clean DB instead of pinning this broken state for the process.
+    try { db.close(); } catch { /* ignore */ }
+    try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+    try { fs.unlinkSync(`${filePath}-wal`); } catch { /* ignore */ }
+    try { fs.unlinkSync(`${filePath}-shm`); } catch { /* ignore */ }
+    return null;
+  }
+  let nextStat = null;
+  try { nextStat = fs.statSync(filePath); } catch { nextStat = null; }
+  _connState.path = filePath;
+  _connState.ino = nextStat?.ino || 0;
+  _connState.db = db;
+  _connState.prepared = new Map();
+  _connState.broken = false;
+  return _connState;
+}
+
+function isAbiMismatch(error) {
+  const message = String(error?.message || "");
+  return /NODE_MODULE_VERSION|was compiled against a different Node\.js version/i.test(message);
+}
+
+function prepareCached(state, sql) {
+  let stmt = state.prepared.get(sql);
+  if (!stmt) {
+    stmt = state.db.prepare(sql);
+    state.prepared.set(sql, stmt);
+  }
+  return stmt;
+}
+
+function upsertMeta(db, key, value) {
+  db.prepare("INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+
+function entryToRowParams(entry) {
+  const session = entry.session || {};
+  const isSubagent = /_subagent$/.test(String(session.conversationKind || "")) ? 1 : 0;
+  return {
+    session_id: session.sessionId || "",
+    metadata_path: entry.metadataPath || session.metadataPath || "",
+    mtime_ms: Math.trunc(Number(entry.mtimeMs) || 0),
+    size: Math.trunc(Number(entry.size) || 0),
+    started_at: session.startedAt || "",
+    ended_at: session.endedAt || "",
+    provider: session.provider || "",
+    source_type: session.sourceType || "",
+    repo_canonical: session.repoCanonical || "",
+    scope_canonical: session.scopeCanonical || "",
+    storage_scope: session.storageScope || "",
+    conversation_kind: session.conversationKind || "",
+    is_subagent: isSubagent,
+    source_path: session.sourcePath || "",
+    session_json: JSON.stringify(session)
+  };
+}
+
+function rowToEntry(row) {
+  if (!row || !row.session_json) return null;
+  let session = null;
+  try { session = JSON.parse(row.session_json); } catch { return null; }
+  if (!session || typeof session !== "object") return null;
+  return {
+    metadataPath: row.metadata_path || "",
+    mtimeMs: Number(row.mtime_ms) || 0,
+    size: Number(row.size) || 0,
+    session
+  };
+}
+
+const ROW_INSERT_SQL =
+  "INSERT INTO sessions(" +
+  "  session_id, metadata_path, mtime_ms, size, started_at, ended_at, provider, source_type, " +
+  "  repo_canonical, scope_canonical, storage_scope, conversation_kind, is_subagent, source_path, session_json" +
+  ") VALUES(" +
+  "  @session_id, @metadata_path, @mtime_ms, @size, @started_at, @ended_at, @provider, @source_type, " +
+  "  @repo_canonical, @scope_canonical, @storage_scope, @conversation_kind, @is_subagent, @source_path, @session_json" +
+  ") ON CONFLICT(session_id) DO UPDATE SET " +
+  "  metadata_path = excluded.metadata_path, mtime_ms = excluded.mtime_ms, size = excluded.size, " +
+  "  started_at = excluded.started_at, ended_at = excluded.ended_at, provider = excluded.provider, " +
+  "  source_type = excluded.source_type, repo_canonical = excluded.repo_canonical, " +
+  "  scope_canonical = excluded.scope_canonical, storage_scope = excluded.storage_scope, " +
+  "  conversation_kind = excluded.conversation_kind, is_subagent = excluded.is_subagent, " +
+  "  source_path = excluded.source_path, session_json = excluded.session_json";
+
+const ROW_SELECT_ALL_SQL =
+  "SELECT session_id, metadata_path, mtime_ms, size, session_json FROM sessions";
+
+const ROW_DELETE_SQL = "DELETE FROM sessions WHERE session_id = ?";
+const ROW_DELETE_BY_PATH_SQL = "DELETE FROM sessions WHERE metadata_path = ?";
+// Used by the Cursor/Devin provider flow to evict prior snapshots written
+// for the same (provider, source_path) before upserting the fresh one.
+const ROW_DELETE_BY_SOURCE_PATH_SQL =
+  "DELETE FROM sessions WHERE provider = ? AND source_path = ? AND source_path != '' AND session_id != ?";
+
+/**
+ * Bulk-replace the entire sessions table from a rebuilt entry list. Used by
+ * the filesystem-walk fallback after it scans the archive. Done in a single
+ * transaction so concurrent readers either see the old or new set.
+ */
+function replaceAllSessions(entries, archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return false;
+  const insertStmt = prepareCached(state, ROW_INSERT_SQL);
+  try {
+    const replace = state.db.transaction(function (rows) {
+      state.db.exec("DELETE FROM sessions");
+      // Track actually-inserted rows rather than rows.length so the count
+      // meta reflects what's queryable in the sessions table. Entries that
+      // lack session_id or metadata_path are skipped above and must not
+      // count toward the stored total.
+      let inserted = 0;
+      for (const entry of rows) {
+        if (!entry || !entry.session) continue;
+        const params = entryToRowParams(entry);
+        if (!params.session_id || !params.metadata_path) continue;
+        insertStmt.run(params);
+        inserted += 1;
+      }
+      upsertMeta(state.db, "count", String(inserted));
+      upsertMeta(state.db, "updated_at", new Date().toISOString());
+    });
+    replace(entries);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Single-row upsert used from writeSession after a session is committed to
+ * disk. Cheap path: one INSERT ... ON CONFLICT, no walk.
+ */
+function upsertSession(entry, archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return false;
+  if (!entry || !entry.session) return false;
+  const params = entryToRowParams(entry);
+  if (!params.session_id || !params.metadata_path) return false;
+  try {
+    prepareCached(state, ROW_INSERT_SQL).run(params);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete by session id or by metadata path. Either is sufficient since both
+ * are indexed; both are accepted because callers may know only one.
+ */
+function deleteSession({ sessionId, metadataPath }, archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return false;
+  try {
+    if (sessionId) prepareCached(state, ROW_DELETE_SQL).run(sessionId);
+    if (metadataPath) prepareCached(state, ROW_DELETE_BY_PATH_SQL).run(metadataPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cursor/Devin replace-old-snapshot path: evict every prior session row that
+ * shares (provider, source_path) with the incoming session, except the
+ * incoming session itself. Returns the count of deleted rows for observability.
+ */
+function deleteSameSourceSessions({ provider, sourcePath, keepSessionId }, archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return 0;
+  if (!provider || !sourcePath) return 0;
+  try {
+    const result = prepareCached(state, ROW_DELETE_BY_SOURCE_PATH_SQL).run(provider, sourcePath, keepSessionId || "");
+    return Number(result?.changes || 0);
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Read all session entries from the store. Returns null when the store is
+ * unavailable or empty so the caller can fall back to the JSON file / a
+ * filesystem walk and then populate the store.
+ */
+function readAllSessions(archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return null;
+  let rows;
+  try {
+    rows = prepareCached(state, ROW_SELECT_ALL_SQL).all();
+  } catch {
+    return null;
+  }
+  if (!rows.length) return null;
+  const entries = rows.map(rowToEntry).filter(Boolean);
+  return entries.length ? entries : null;
+}
+
+function countSessions(archiveRoot) {
+  const state = openConnection(archiveRoot);
+  if (!state) return null;
+  try {
+    const row = prepareCached(state, "SELECT COUNT(*) AS c FROM sessions").get();
+    return row?.c || 0;
+  } catch {
+    return null;
+  }
+}
+
+function storeAvailable(archiveRoot) {
+  return Boolean(openConnection(archiveRoot));
+}
+
+function resetStateForTests() {
+  closeConnection();
+  _driverBroken = false;
+  _driverLoaded = false;
+  _Database = null;
+  _driverLoadError = null;
+}
+
+module.exports = {
+  SESSION_STORE_VERSION,
+  sessionStorePath,
+  replaceAllSessions,
+  upsertSession,
+  deleteSession,
+  deleteSameSourceSessions,
+  readAllSessions,
+  countSessions,
+  storeAvailable,
+  closeConnection,
+  resetStateForTests
+};

package/src/source-watch.js

@@ -0,0 +1,293 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+// Filesystem events are triggers, not data: an event only marks its source
+// dirty, so watcher memory stays O(sources) no matter how fast agents write.
+// The first event for a source opens a fixed-delay coalesce window and later
+// events fold into it, so a continuously writing session cannot starve its
+// own import (a trailing-edge debounce would).
+const DEFAULT_COALESCE_MS = 3 * 1000;
+// SQLite-backed stores churn their WAL while the app is open, including for
+// state unrelated to conversations, so they get a wider window.
+const SQLITE_COALESCE_MS = 20 * 1000;
+// Roots that don't exist yet (tool not installed) or whose watcher died are
+// re-checked on this cadence.
+const WATCH_RETRY_MS = 5 * 60 * 1000;
+
+function homeDir(env = process.env) {
+  return env.HOME || env.USERPROFILE || os.homedir();
+}
+
+function geminiHome(env, home) {
+  return env.AGENTLOG_GEMINI_HOME_DIR || env.GEMINI_HOME || path.join(home, ".gemini");
+}
+
+function claudeAppSupportRoot(env, home) {
+  return env.CLAUDE_APP_SUPPORT || path.join(home, "Library", "Application Support", "Claude");
+}
+
+function root(dir, options = {}) {
+  return {
+    dir: path.resolve(dir),
+    recursive: options.recursive !== false,
+    filter: options.filter || null,
+    coalesceMs: options.coalesceMs || DEFAULT_COALESCE_MS
+  };
+}
+
+function sqliteStateDbFilter(name) {
+  return path.basename(name).startsWith("state.vscdb");
+}
+
+// Watch roots per import source, mirroring the importer path resolution in
+// src/importers.js (including its env overrides) without loading that module:
+// the supervisor process should stay small, and a root that drifts slightly
+// from what the importer reads only costs a no-op import or falls back to the
+// heartbeat poll. Sources with no entry (aider scans whole project trees;
+// watching those would fire on every git operation in every repo) stay on the
+// polling cadence.
+function watchRootsForSource(source, env = process.env) {
+  const home = homeDir(env);
+  switch (source) {
+    case "codex-cli":
+    case "codex-desktop":
+    case "codex-sdk": {
+      const codexHome = env.CODEX_HOME || path.join(home, ".codex");
+      return [root(path.join(codexHome, "sessions")), root(path.join(codexHome, "archived_sessions"))];
+    }
+    case "claude":
+      return [root(path.join(home, ".claude", "projects"))];
+    case "claude-code-desktop":
+      return [root(path.join(claudeAppSupportRoot(env, home), "claude-code-sessions"))];
+    case "claude-cowork":
+      return [root(path.join(claudeAppSupportRoot(env, home), "local-agent-mode-sessions"))];
+    case "gemini-cli":
+      // Antigravity homes live inside the Gemini home; exclude them so an
+      // Antigravity session doesn't ping the Gemini importer.
+      return [root(geminiHome(env, home), { filter: (name) => !name.startsWith("antigravity") })];
+    case "antigravity":
+      return [root(env.AGENTLOG_ANTIGRAVITY_HOME_DIR || path.join(geminiHome(env, home), "antigravity"))];
+    case "antigravity-cli":
+      return [root(env.AGENTLOG_ANTIGRAVITY_CLI_HOME_DIR || path.join(geminiHome(env, home), "antigravity-cli"))];
+    case "antigravity-ide":
+      return [root(env.AGENTLOG_ANTIGRAVITY_IDE_HOME_DIR || path.join(geminiHome(env, home), "antigravity-ide"))];
+    case "devin-cli": {
+      const db = env.AGENTLOG_DEVIN_SESSIONS_DB || path.join(home, ".local", "share", "devin", "cli", "sessions.db");
+      return [root(path.dirname(db), { recursive: false, coalesceMs: SQLITE_COALESCE_MS })];
+    }
+    case "devin-desktop": {
+      const appRoots = [
+        path.join(home, "Library", "Application Support", "Devin"),
+        path.join(home, ".config", "Devin")
+      ];
+      return appRoots.flatMap((appRoot) => [
+        root(path.join(appRoot, "User", "acp-events")),
+        root(path.join(appRoot, "User", "globalStorage"), {
+          recursive: false,
+          filter: sqliteStateDbFilter,
+          coalesceMs: SQLITE_COALESCE_MS
+        })
+      ]);
+    }
+    case "windsurf": {
+      const windsurfHome =
+        env.AGENTLOG_WINDSURF_HOME_DIR ||
+        env.AGENTLOG_CODEIUM_WINDSURF_HOME_DIR ||
+        path.join(env.AGENTLOG_CODEIUM_HOME_DIR || path.join(home, ".codeium"), "windsurf");
+      return [root(windsurfHome)];
+    }
+    case "copilot-cli": {
+      if (env.AGENTLOG_COPILOT_SESSION_STATE_DIR) return [root(env.AGENTLOG_COPILOT_SESSION_STATE_DIR)];
+      const copilotHome = env.AGENTLOG_COPILOT_HOME || env.COPILOT_HOME || path.join(home, ".copilot");
+      return [root(path.join(copilotHome, "session-state"))];
+    }
+    case "factory": {
+      if (env.AGENTLOG_FACTORY_SESSIONS_DIR) return [root(env.AGENTLOG_FACTORY_SESSIONS_DIR)];
+      return [root(path.join(env.FACTORY_HOME_OVERRIDE || home, ".factory", "sessions"))];
+    }
+    case "grok-build": {
+      if (env.AGENTLOG_GROK_SESSIONS_DIR) return [root(env.AGENTLOG_GROK_SESSIONS_DIR)];
+      const grokHome = env.AGENTLOG_GROK_HOME || env.GROK_HOME || path.join(home, ".grok");
+      return [root(path.join(grokHome, "sessions"))];
+    }
+    case "pi": {
+      const explicit = env.AGENTLOG_PI_SESSION_DIR || env.PI_CODING_AGENT_SESSION_DIR;
+      if (explicit) return [root(explicit)];
+      const agentDir = env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent");
+      return [root(path.join(agentDir, "sessions"))];
+    }
+    case "cursor": {
+      const globalStorage =
+        env.AGENTLOG_CURSOR_GLOBAL_STORAGE_DIR ||
+        path.join(home, "Library", "Application Support", "Cursor", "User", "globalStorage");
+      const workspaceStorage =
+        env.AGENTLOG_CURSOR_WORKSPACE_STORAGE_DIR ||
+        path.join(home, "Library", "Application Support", "Cursor", "User", "workspaceStorage");
+      return [
+        root(globalStorage, { recursive: false, filter: sqliteStateDbFilter, coalesceMs: SQLITE_COALESCE_MS }),
+        root(workspaceStorage, { filter: sqliteStateDbFilter, coalesceMs: SQLITE_COALESCE_MS })
+      ];
+    }
+    case "cline": {
+      // VS Code variants only; JetBrains installs rely on the heartbeat poll.
+      const appData = env.APPDATA || env.AppData;
+      return [
+        path.join(home, "Library", "Application Support", "Code", "User", "globalStorage", "saoudrizwan.claude-dev"),
+        path.join(home, "Library", "Application Support", "Code - Insiders", "User", "globalStorage", "saoudrizwan.claude-dev"),
+        path.join(home, ".config", "Code", "User", "globalStorage", "saoudrizwan.claude-dev"),
+        appData ? path.join(appData, "Code", "User", "globalStorage", "saoudrizwan.claude-dev") : ""
+      ]
+        .filter(Boolean)
+        .map((dir) => root(dir));
+    }
+    case "opencode-cli":
+    case "opencode-desktop":
+    case "opencode-web": {
+      const configured = env.AGENTLOG_OPENCODE_DATA_DIR || env.OPENCODE_DATA_DIR;
+      if (configured) return [root(configured)];
+      const cliRoot = path.join(home, ".local", "share", "opencode");
+      if (source === "opencode-cli") return [root(cliRoot)];
+      const desktopRoots = [
+        path.join(home, "Library", "Application Support", "ai.opencode.desktop"),
+        path.join(home, "Library", "Application Support", "opencode"),
+        path.join(home, ".local", "share", "ai.opencode.app"),
+        path.join(home, "Library", "Application Support", "ai.opencode.app")
+      ];
+      const roots = source === "opencode-web" ? [cliRoot, ...desktopRoots] : desktopRoots;
+      return roots.map((dir) => root(dir));
+    }
+    default:
+      return [];
+  }
+}
+
+// Watches the source roots and reports dirty sources after their coalesce
+// window. Roots are deduped so sources sharing a directory (codex-cli and
+// codex-desktop both read ~/.codex/sessions) share one OS watch. Returns a
+// handle: isWatched(source) tells the supervisor whether the source can rely
+// on events (true while roots are merely missing — nothing to import then
+// either — false once a watch attempt errors), refresh() retries missing or
+// dead watches, close() tears everything down.
+function startSourceWatchers(sources, env, onSourceDirty, options = {}) {
+  const coalesceOverrideMs = options.coalesceMs || 0;
+  const retryMs = options.retryMs || WATCH_RETRY_MS;
+  const onLog = typeof options.onLog === "function" ? options.onLog : () => {};
+
+  const byDir = new Map();
+  const sourcesWithRoots = new Set();
+  const failedSources = new Set();
+  for (const source of sources || []) {
+    for (const entry of watchRootsForSource(source, env)) {
+      sourcesWithRoots.add(source);
+      const existing = byDir.get(entry.dir);
+      if (existing) {
+        existing.recursive = existing.recursive || entry.recursive;
+        existing.subscribers.push({ source, filter: entry.filter, coalesceMs: entry.coalesceMs });
+      } else {
+        byDir.set(entry.dir, {
+          dir: entry.dir,
+          recursive: entry.recursive,
+          watcher: null,
+          subscribers: [{ source, filter: entry.filter, coalesceMs: entry.coalesceMs }]
+        });
+      }
+    }
+  }
+
+  const timers = new Map();
+  let closed = false;
+
+  function markDirty(source, coalesceMs) {
+    if (closed || timers.has(source)) return;
+    const timer = setTimeout(() => {
+      timers.delete(source);
+      if (!closed) onSourceDirty(source);
+    }, coalesceOverrideMs || coalesceMs);
+    if (typeof timer.unref === "function") timer.unref();
+    timers.set(source, timer);
+  }
+
+  function handleEvent(entry, filename) {
+    const name = typeof filename === "string" ? filename : "";
+    for (const subscriber of entry.subscribers) {
+      // A null filename means the platform couldn't say what changed; treat
+      // it as a match rather than risk missing activity.
+      if (subscriber.filter && name && !subscriber.filter(name)) continue;
+      markDirty(subscriber.source, subscriber.coalesceMs);
+    }
+  }
+
+  function markEntryFailed(entry, error) {
+    for (const subscriber of entry.subscribers) failedSources.add(subscriber.source);
+    onLog(`watch failed for ${entry.dir}: ${error.message}`);
+  }
+
+  function attach(entry) {
+    if (entry.watcher || closed) return;
+    let stat = null;
+    try {
+      stat = fs.statSync(entry.dir);
+    } catch {
+      return; // Missing root: nothing to import from it yet; refresh retries.
+    }
+    if (!stat.isDirectory()) return;
+    try {
+      const watcher = fs.watch(entry.dir, { recursive: entry.recursive, persistent: false });
+      watcher.on("change", (eventType, filename) => handleEvent(entry, filename));
+      watcher.on("error", () => {
+        // Watches die when the root is replaced; refresh re-attaches.
+        try {
+          watcher.close();
+        } catch {}
+        entry.watcher = null;
+      });
+      entry.watcher = watcher;
+    } catch (error) {
+      markEntryFailed(entry, error);
+    }
+  }
+
+  function refresh() {
+    if (closed) return;
+    for (const entry of byDir.values()) attach(entry);
+  }
+
+  refresh();
+  const retryTimer = setInterval(refresh, retryMs);
+  if (typeof retryTimer.unref === "function") retryTimer.unref();
+
+  return {
+    isWatched(source) {
+      return sourcesWithRoots.has(source) && !failedSources.has(source);
+    },
+    activeWatchCount() {
+      let count = 0;
+      for (const entry of byDir.values()) if (entry.watcher) count += 1;
+      return count;
+    },
+    refresh,
+    close() {
+      closed = true;
+      clearInterval(retryTimer);
+      for (const timer of timers.values()) clearTimeout(timer);
+      timers.clear();
+      for (const entry of byDir.values()) {
+        if (!entry.watcher) continue;
+        try {
+          entry.watcher.close();
+        } catch {}
+        entry.watcher = null;
+      }
+    }
+  };
+}
+
+module.exports = {
+  DEFAULT_COALESCE_MS,
+  SQLITE_COALESCE_MS,
+  startSourceWatchers,
+  watchRootsForSource
+};