agentel 0.2.8 → 0.3.1

package/src/supervisor.js

@@ -6,12 +6,102 @@ const { spawn } = require("child_process");
 const { ensureBaseDirs, paths, readJson, writeJson } = require("./paths");
 const { effectiveImportSources, loadConfig } = require("./config");
 const { startCollector } = require("./collector");
+const { startSourceWatchers } = require("./source-watch");
 const { hasRemoteTarget } = require("./sync");
 
 let tickRunning = false;
 const CHILD_MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
 const CHILD_TIMEOUT_MS = 10 * 60 * 1000;
 const CHILD_KILL_GRACE_MS = 2000;
+// Backoff so an idle machine doesn't spawn import/index children every 30s
+// forever: after a few empty imports a source drops to a slower cadence and
+// snaps back to every tick as soon as an import finds activity. Failing
+// sources back off exponentially so a permanently broken source doesn't
+// burn a child process (and a log line) per tick.
+const SOURCE_IDLE_TICKS_BEFORE_BACKOFF = 4;
+const SOURCE_IDLE_INTERVAL_MS = 5 * 60 * 1000;
+const SOURCE_ERROR_BACKOFF_MIN_MS = 60 * 1000;
+const SOURCE_ERROR_BACKOFF_MAX_MS = 30 * 60 * 1000;
+// Sources covered by filesystem watchers don't need the fast poll at all:
+// events mark them pending (imported on the next tick, triggered
+// immediately), and this heartbeat poll only backstops dropped events —
+// fs.watch loses events under load and emits nothing on network volumes.
+const WATCHED_SOURCE_HEARTBEAT_MS = 15 * 60 * 1000;
+const INDEX_MIN_INTERVAL_MS = 10 * 60 * 1000;
+// Memory files change rarely and the backup is a stat+hash sweep, so a
+// moderate cadence keeps provider memories continuously archived without
+// meaningful cost.
+const MEMORY_BACKUP_INTERVAL_MS = 15 * 60 * 1000;
+
+// Per-run tick state. Owned by runSupervisorForeground so direct tick()
+// callers (tests, one-shot runs) always start fresh.
+function createTickState() {
+  return {
+    sources: new Map(),
+    lastIndexAt: 0,
+    indexDirty: true,
+    lastMemoryBackupAt: 0,
+    pendingSources: new Set(),
+    tickAgain: false,
+    watch: null,
+    nextNotifyCheckAt: 0
+  };
+}
+
+function sourceTickStateFor(state, source) {
+  let sourceState = state.sources.get(source);
+  if (!sourceState) {
+    sourceState = { nextEligibleAt: 0, idleTicks: 0, failures: 0, idleLogged: false };
+    state.sources.set(source, sourceState);
+  }
+  return sourceState;
+}
+
+// Returns true when the source just transitioned into idle backoff (so the
+// caller can log the transition once instead of every tick).
+function applySourceImportOutcome(sourceState, activity, now) {
+  sourceState.failures = 0;
+  if (activity > 0) {
+    sourceState.idleTicks = 0;
+    sourceState.nextEligibleAt = 0;
+    sourceState.idleLogged = false;
+    return false;
+  }
+  sourceState.idleTicks += 1;
+  if (sourceState.idleTicks < SOURCE_IDLE_TICKS_BEFORE_BACKOFF) return false;
+  sourceState.nextEligibleAt = now + SOURCE_IDLE_INTERVAL_MS;
+  const firstTime = !sourceState.idleLogged;
+  sourceState.idleLogged = true;
+  return firstTime;
+}
+
+// Watched sources skip idle backoff entirely: filesystem events snap them
+// back via pendingSources, so after any import they rest until the heartbeat.
+function applyWatchedSourceImportOutcome(sourceState, now) {
+  sourceState.failures = 0;
+  sourceState.idleTicks = 0;
+  sourceState.idleLogged = false;
+  sourceState.nextEligibleAt = now + WATCHED_SOURCE_HEARTBEAT_MS;
+}
+
+// Pending filesystem activity bypasses idle/heartbeat scheduling but not
+// error backoff, so a chatty source that fails to import doesn't retry on
+// every coalesce window.
+function sourceEligibleForImport(sourceState, pending, now) {
+  if (now >= sourceState.nextEligibleAt) return true;
+  return pending && sourceState.failures === 0;
+}
+
+// Returns the backoff delay in ms applied after a failed import.
+function applySourceImportFailure(sourceState, now) {
+  sourceState.failures += 1;
+  const backoffMs = Math.min(
+    SOURCE_ERROR_BACKOFF_MAX_MS,
+    SOURCE_ERROR_BACKOFF_MIN_MS * 2 ** (sourceState.failures - 1)
+  );
+  sourceState.nextEligibleAt = now + backoffMs;
+  return backoffMs;
+}
 
 function startSupervisorDetached(env = process.env) {
   const p = paths(env);
@@ -37,57 +127,152 @@ async function runSupervisorForeground(env = process.env) {
   });
   if (collector) log(`collector listening on ${loadConfig(env).collector.otlpEndpoint}`, env);
 
+  const tickState = createTickState();
+
   let stopping = false;
   const stop = () => {
     if (stopping) return;
     stopping = true;
     log("supervisor stopping", env);
+    if (tickState.watch) tickState.watch.close();
     removeSupervisorPidIfOwned(process.pid, env);
     process.exit(0);
   };
   process.on("SIGTERM", stop);
   process.on("SIGINT", stop);
 
-  await tick(env);
+  const runTick = () => {
+    if (stopping) return;
+    tick(env, tickState)
+      .catch((error) => log(`tick failed: ${error.message}`, env))
+      .finally(() => {
+        // Sources marked dirty while a tick ran get picked up right away
+        // instead of waiting for the interval.
+        if (tickState.tickAgain && !stopping) {
+          tickState.tickAgain = false;
+          runTick();
+        }
+      });
+  };
+
+  try {
+    const sources = effectiveImportSources(loadConfig(env));
+    tickState.watch = startSourceWatchers(
+      Array.isArray(sources) && sources.length ? sources : [],
+      env,
+      (source) => {
+        tickState.pendingSources.add(source);
+        if (tickRunning) {
+          tickState.tickAgain = true;
+          return;
+        }
+        runTick();
+      },
+      { onLog: (message) => log(message, env) }
+    );
+    const active = tickState.watch.activeWatchCount();
+    if (active) log(`watching ${active} source root(s) for changes`, env);
+  } catch (error) {
+    log(`source watch disabled: ${error.message}`, env);
+  }
+
+  await tick(env, tickState);
+  if (tickState.tickAgain) {
+    tickState.tickAgain = false;
+    runTick();
+  }
   const timer = setInterval(() => {
     if (tickRunning) {
       log("tick skipped: previous tick still running", env);
       return;
     }
-    tick(env).catch((error) => log(`tick failed: ${error.message}`, env));
+    runTick();
   }, 30 * 1000);
 
   await new Promise(() => {});
 }
 
-async function tick(env) {
+async function tick(env, state = createTickState()) {
   tickRunning = true;
   try {
+    const now = Date.now();
     try {
       const cfg = loadConfig(env);
       const sources = effectiveImportSources(cfg);
       const importSources = Array.isArray(sources) && sources.length ? sources : ["all"];
       for (const source of importSources) {
+        const sourceState = sourceTickStateFor(state, source);
+        const pending = state.pendingSources.has(source);
+        if (!sourceEligibleForImport(sourceState, pending, now)) continue;
+        state.pendingSources.delete(source);
         try {
           const imports = await importSourceInChild(source, cfg, env);
+          let activity = 0;
           for (const result of imports) {
+            activity += (Number(result.imported) || 0) + (Number(result.pruned) || 0);
             const summary = supervisorImportResultLog(result, source);
             if (summary) log(summary, env);
             if (result.errors?.length) log(`${result.provider} import errors from ${source}: ${result.errors.length}`, env);
           }
+          if (activity > 0) state.indexDirty = true;
+          if (state.watch && state.watch.isWatched(source)) {
+            applyWatchedSourceImportOutcome(sourceState, now);
+          } else if (applySourceImportOutcome(sourceState, activity, now)) {
+            log(`${source} import idle: slowing to ${formatDuration(SOURCE_IDLE_INTERVAL_MS)} cadence until new activity`, env);
+          }
         } catch (error) {
-          log(`${source} history import skipped: ${error.message}`, env);
+          const backoffMs = applySourceImportFailure(sourceState, now);
+          log(`${source} history import skipped: ${error.message} (retrying in ${formatDuration(backoffMs)})`, env);
         }
       }
     } catch (error) {
       log(`history import skipped: ${error.message}`, env);
     }
 
+    if (state.indexDirty || now - state.lastIndexAt >= INDEX_MIN_INTERVAL_MS) {
+      try {
+        const result = await reindexInChild(env);
+        if (result.index?.docCount != null) log(`index ready (${result.index.docCount} chunk(s))`, env);
+      } catch (error) {
+        log(`index skipped: ${error.message}`, env);
+      } finally {
+        // Advance the clock even on failure so a persistent indexing error
+        // backs off to INDEX_MIN_INTERVAL_MS instead of retrying every tick.
+        state.lastIndexAt = now;
+        state.indexDirty = false;
+      }
+    }
+
     try {
-      const result = await reindexInChild(env);
-      if (result.index?.docCount != null) log(`index ready (${result.index.docCount} chunk(s))`, env);
+      const cfg = loadConfig(env);
+      if (cfg.notify?.slack?.enabled) {
+        // New archive writes (queue file present) trigger a pass right away;
+        // otherwise re-check when the soonest quiet window can elapse.
+        const queueWaiting = fs.existsSync(path.join(paths(env).state, "slack-notify-queue.jsonl"));
+        if (queueWaiting || now >= state.nextNotifyCheckAt) {
+          const result = await slackNotifyInChild(env);
+          const nextCheckMs = Math.max(30 * 1000, Number(result?.nextCheckMs) || 5 * 60 * 1000);
+          state.nextNotifyCheckAt = now + nextCheckMs;
+          if (result?.posted) log(`slack notify posted ${result.posted} session summar${result.posted === 1 ? "y" : "ies"}`, env);
+          for (const message of result?.errors || []) log(`slack notify error: ${message}`, env);
+        }
+      }
     } catch (error) {
-      log(`index skipped: ${error.message}`, env);
+      log(`slack notify skipped: ${error.message}`, env);
+    }
+
+    if (now - state.lastMemoryBackupAt >= MEMORY_BACKUP_INTERVAL_MS) {
+      try {
+        const summaries = await memoryBackupInChild(env);
+        const changed = summaries.reduce((sum, item) => sum + (Number(item.changed) || 0), 0);
+        if (changed > 0) log(`memory backup captured ${changed} change(s)`, env);
+      } catch (error) {
+        log(`memory backup skipped: ${error.message}`, env);
+      } finally {
+        // Advance even on failure so a persistent error backs off to the
+        // backup interval instead of retrying every tick.
+        state.lastMemoryBackupAt = now;
+      }
     }
 
     try {
@@ -124,6 +309,38 @@ try {
   return runJsonChild(script, env, `${source} import`, title);
 }
 
+function memoryBackupInChild(env = process.env) {
+  const title = childProcessTitle("memory-backup");
+  const script = `
+process.title = ${JSON.stringify(title)};
+(async () => {
+  const { collectMemoryBackup } = require(${JSON.stringify(path.join(__dirname, "memory-sources"))});
+  const summaries = await collectMemoryBackup(process.env);
+  process.stdout.write(JSON.stringify(summaries));
+})().catch((error) => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+});
+`;
+  return runJsonChild(script, env, "memory backup", title);
+}
+
+function slackNotifyInChild(env = process.env) {
+  const title = childProcessTitle("slack-notify");
+  const script = `
+process.title = ${JSON.stringify(title)};
+(async () => {
+  const { runSlackNotify } = require(${JSON.stringify(path.join(__dirname, "slack-notify"))});
+  const result = await runSlackNotify(process.env);
+  process.stdout.write(JSON.stringify(result));
+})().catch((error) => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+});
+`;
+  return runJsonChild(script, env, "slack notify", title);
+}
+
 function reindexInChild(env = process.env) {
   const title = childProcessTitle("index");
   const script = `
@@ -350,6 +567,11 @@ function log(message, env = process.env) {
 }
 
 module.exports = {
+  applySourceImportFailure,
+  applySourceImportOutcome,
+  applyWatchedSourceImportOutcome,
+  createTickState,
+  sourceEligibleForImport,
   runSupervisorForeground,
   startSupervisorDetached,
   stopSupervisor,
@@ -359,7 +581,9 @@ module.exports = {
   removeSupervisorPidIfOwned,
   shouldRunScheduledSync,
   importSourceInChild,
+  memoryBackupInChild,
   reindexInChild,
+  slackNotifyInChild,
   runJsonChild,
   syncInChild,
   tick

package/src/sync.js

@@ -526,6 +526,7 @@ function listLocalArchiveObjects(env = process.env, prefix = "agentlog") {
     const stat = safeStat(file);
     if (!stat || !stat.isFile()) return;
     const relative = path.relative(root, file).split(path.sep).join("/");
+    if (!syncableArchiveObject(relative)) return;
     const key = [normalizePrefix(prefix), relative].filter(Boolean).join("/");
     objects.push({
       file,
@@ -538,6 +539,11 @@ function listLocalArchiveObjects(env = process.env, prefix = "agentlog") {
   return objects.sort((a, b) => a.key.localeCompare(b.key));
 }
 
+function syncableArchiveObject(relative) {
+  const key = String(relative || "").replace(/\\/g, "/");
+  return !key.startsWith("indexes/");
+}
+
 function listDirectoryObjects(root) {
   const objects = [];
   walk(root, (file) => {

package/src/unavailable-sources.js

@@ -0,0 +1,358 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { isWebChatProvider, listSessions } = require("./archive");
+const { ensureDir, readJson } = require("./paths");
+const { HISTORY_PROVIDER_OPTIONS, IMPORT_SOURCE_ORDER } = require("./sources");
+
+const CLAUDE_CODE_REPAIR_COMMAND = "agentlog repair claude-code-backups";
+const CLAUDE_CODE_REPAIR_PREVIEW_COMMAND = `${CLAUDE_CODE_REPAIR_COMMAND} --dry-run`;
+
+function preservedArchiveSession(session) {
+  return preservedWebChatSession(session) || sessionHasUnavailableSource(session);
+}
+
+function preservedWebChatSession(session) {
+  if (isWebChatProvider(session?.provider, session?.sourceType)) return true;
+  return /^\[(chatgpt|claude)\]conversations\//i.test(String(session?.scopeCanonical || ""));
+}
+
+function unavailableSourceSessions(env = process.env) {
+  return listSessions(env).filter((session) => !preservedWebChatSession(session) && sessionHasUnavailableSource(session));
+}
+
+function sessionHasUnavailableSource(session) {
+  return unavailableSourcePaths(session).length > 0;
+}
+
+function unavailableSourcePaths(session) {
+  return requiredSourcePaths(session).filter((sourcePath) => !safeSourceStat(sourcePath));
+}
+
+function requiredSourcePaths(session) {
+  const values = [filesystemSourcePath(session?.sourcePath)];
+  if (sessionMayNeedAuxiliaryTranscripts(session)) {
+    for (const record of sessionRawRecords(session)) {
+      const sourcePath = filesystemSourcePath(record?.originalPath || record?.sourcePath);
+      if (auxiliaryTranscriptSourcePath(sourcePath)) values.push(sourcePath);
+    }
+  }
+  return [...new Set(values.filter(Boolean).map((value) => path.resolve(value)))];
+}
+
+function sessionMayNeedAuxiliaryTranscripts(session) {
+  const provider = String(session?.provider || "");
+  const sourceType = String(session?.sourceType || "");
+  return provider === "claude_code" || provider === "claude_desktop" || provider === "claude_sdk" || sourceType.startsWith("claude-");
+}
+
+function auxiliaryTranscriptSourcePath(sourcePath) {
+  if (!sourcePath) return false;
+  return /(?:^|[\\/])audit\.jsonl$/i.test(sourcePath) || /\.jsonl(?:\.zst)?$/i.test(sourcePath);
+}
+
+function filesystemSourcePath(value) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  const hashIndex = text.indexOf("#");
+  const base = hashIndex > 0 ? text.slice(0, hashIndex) : text;
+  if (!base) return "";
+  if (path.isAbsolute(base)) return path.resolve(base);
+  if (path.win32.isAbsolute(base)) return base;
+  return "";
+}
+
+function sessionRawRecords(session) {
+  const records = Array.isArray(session?.rawFiles) ? [...session.rawFiles] : [];
+  if (session?.rawPath) {
+    const manifest = readJson(path.join(session.rawPath, "manifest.json"), null);
+    for (const record of Array.isArray(manifest?.files) ? manifest.files : []) {
+      records.push(record);
+    }
+  }
+  return records;
+}
+
+function summarizeUnavailableSourceSessions(sessions, options = {}) {
+  const selected = (Array.isArray(sessions) ? sessions : []).filter((session) =>
+    !preservedWebChatSession(session) && (options.includeAvailable || sessionHasUnavailableSource(session))
+  );
+  const breakdown = unavailableSourceBreakdown(selected);
+  const totalMissingSources = breakdown.reduce((sum, row) => sum + row.missingSources, 0);
+  const claudeCodeRepair = summarizeClaudeCodeBackupRepair(selected, options.env || process.env);
+  return {
+    totalSessions: selected.length,
+    totalMissingSources,
+    breakdown,
+    claudeCodeRepair
+  };
+}
+
+function unavailableSourceBreakdown(sessions) {
+  const byKey = new Map();
+  for (const session of sessions || []) {
+    const source = sourceForSession(session);
+    const provider = String(session?.provider || "unknown");
+    const sourceType = String(session?.sourceType || "unknown");
+    const key = `${source}\0${provider}\0${sourceType}`;
+    const existing = byKey.get(key) || {
+      source,
+      provider,
+      sourceType,
+      sessions: 0,
+      missingSources: 0
+    };
+    existing.sessions++;
+    existing.missingSources += unavailableSourcePaths(session).length;
+    byKey.set(key, existing);
+  }
+  return [...byKey.values()].sort(compareSourceBreakdownRows);
+}
+
+function sourceForSession(session) {
+  const provider = String(session?.provider || "");
+  const sourceType = String(session?.sourceType || "");
+  const exact = SOURCE_BY_PROVIDER_AND_TYPE.get(`${provider}\0${sourceType}`);
+  if (exact) return exact;
+  const sourceOption = HISTORY_PROVIDER_OPTIONS.find((item) => item.provider === provider && item.sourceType === sourceType);
+  if (sourceOption?.source) return sourceOption.source;
+  return SOURCE_BY_PROVIDER.get(provider) || sourceType || provider || "unknown";
+}
+
+function compareSourceBreakdownRows(a, b) {
+  const left = sourceOrder(a.source);
+  const right = sourceOrder(b.source);
+  return left - right
+    || a.source.localeCompare(b.source)
+    || a.provider.localeCompare(b.provider)
+    || a.sourceType.localeCompare(b.sourceType);
+}
+
+function sourceOrder(source) {
+  const index = IMPORT_SOURCE_ORDER.indexOf(source);
+  return index === -1 ? 999 : index;
+}
+
+function summarizeClaudeCodeBackupRepair(sessions, env = process.env) {
+  const plan = planClaudeCodeBackupRepair(env, { sessions, dryRun: true });
+  return {
+    candidateSessions: plan.candidateSessions,
+    restoreSessions: plan.restoreSessions,
+    restoreCount: plan.restoreCount,
+    existingCount: plan.existingCount,
+    missingBackupCount: plan.missingBackupCount,
+    command: CLAUDE_CODE_REPAIR_COMMAND,
+    previewCommand: CLAUDE_CODE_REPAIR_PREVIEW_COMMAND
+  };
+}
+
+function planClaudeCodeBackupRepair(env = process.env, options = {}) {
+  const roots = claudeCodeSourceRoots(env);
+  const sessions = (Array.isArray(options.sessions) ? options.sessions : unavailableSourceSessions(env))
+    .filter(claudeCodeBackupRepairSession);
+  const seenTargets = new Set();
+  const actions = [];
+  const skipped = [];
+  for (const session of sessions) {
+    let sessionActionCount = 0;
+    for (const record of sessionRawRecords(session)) {
+      const targetPath = filesystemSourcePath(record?.originalPath || record?.sourcePath);
+      if (!targetPath || !isInsideAnyRoot(targetPath, roots)) continue;
+      const targetKey = path.resolve(targetPath);
+      if (seenTargets.has(targetKey)) {
+        skipped.push(skipRecord(session, record, targetPath, "duplicate-target"));
+        continue;
+      }
+      seenTargets.add(targetKey);
+      const backupPath = backupPathForRawRecord(record);
+      if (!backupPath || !safeSourceStat(backupPath)?.isFile()) {
+        skipped.push(skipRecord(session, record, targetPath, "missing-backup"));
+        continue;
+      }
+      const targetStat = safeSourceStat(targetPath);
+      if (targetStat && !options.overwrite) {
+        skipped.push(skipRecord(session, record, targetPath, "target-exists", backupPath));
+        continue;
+      }
+      actions.push({
+        sessionId: session.sessionId || "",
+        title: session.title || "",
+        sourceType: session.sourceType || "",
+        provider: session.provider || "",
+        targetPath,
+        backupPath,
+        size: Number(record?.size || 0) || safeSourceStat(backupPath)?.size || 0,
+        mtime: record?.mtime || ""
+      });
+      sessionActionCount++;
+    }
+    if (!sessionActionCount) {
+      const sourcePath = filesystemSourcePath(session?.sourcePath);
+      if (sourcePath && isInsideAnyRoot(sourcePath, roots)) {
+        skipped.push({
+          sessionId: session.sessionId || "",
+          targetPath: sourcePath,
+          reason: "no-restorable-raw-backup"
+        });
+      }
+    }
+  }
+  const restoreSessionIds = new Set(actions.map((item) => item.sessionId).filter(Boolean));
+  return {
+    dryRun: Boolean(options.dryRun),
+    overwrite: Boolean(options.overwrite),
+    sourceRoots: roots,
+    candidateSessions: sessions.length,
+    restoreSessions: restoreSessionIds.size,
+    restoreCount: actions.length,
+    existingCount: skipped.filter((item) => item.reason === "target-exists").length,
+    missingBackupCount: skipped.filter((item) => item.reason === "missing-backup" || item.reason === "no-restorable-raw-backup").length,
+    duplicateCount: skipped.filter((item) => item.reason === "duplicate-target").length,
+    actions,
+    skipped
+  };
+}
+
+function repairClaudeCodeBackups(env = process.env, options = {}) {
+  const plan = planClaudeCodeBackupRepair(env, options);
+  if (options.dryRun) return { ...plan, restored: 0 };
+  let restored = 0;
+  for (const action of plan.actions) {
+    if (!isInsideAnyRoot(action.targetPath, plan.sourceRoots)) continue;
+    if (safeSourceStat(action.targetPath) && !options.overwrite) continue;
+    ensureDir(path.dirname(action.targetPath));
+    fs.copyFileSync(action.backupPath, action.targetPath);
+    try {
+      fs.chmodSync(action.targetPath, 0o600);
+    } catch {
+      // Best-effort permissions normalization.
+    }
+    if (action.mtime) {
+      const mtime = new Date(action.mtime);
+      if (Number.isFinite(mtime.getTime())) {
+        try {
+          fs.utimesSync(action.targetPath, mtime, mtime);
+        } catch {
+          // Best-effort timestamp preservation.
+        }
+      }
+    }
+    restored++;
+  }
+  return { ...plan, restored };
+}
+
+function claudeCodeBackupRepairSession(session) {
+  return String(session?.provider || "") === "claude_code";
+}
+
+function claudeCodeSourceRoots(env = process.env) {
+  const home = env && env.HOME ? env.HOME : os.homedir();
+  return [
+    path.join(home, ".claude", "projects"),
+    path.join(home, ".claude", "file-history")
+  ];
+}
+
+function backupPathForRawRecord(record) {
+  const candidates = [record?.archivedPath, record?.sharedRawPath]
+    .map(filesystemSourcePath)
+    .filter(Boolean);
+  return candidates.find((candidate) => safeSourceStat(candidate)?.isFile()) || "";
+}
+
+function skipRecord(session, record, targetPath, reason, backupPath = "") {
+  return {
+    sessionId: session?.sessionId || "",
+    title: session?.title || "",
+    sourceType: session?.sourceType || "",
+    provider: session?.provider || "",
+    targetPath,
+    backupPath: backupPath || backupPathForRawRecord(record),
+    reason
+  };
+}
+
+function isInsideAnyRoot(value, roots) {
+  return roots.some((root) => isSameOrInside(value, root));
+}
+
+function isSameOrInside(value, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(value));
+  if (relative === "") return true;
+  // Entry names may legitimately start with ".." (e.g. "..foo"), so only an
+  // exact ".." segment marks the path as outside the root.
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function safeSourceStat(target) {
+  try {
+    return fs.statSync(target);
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(error.code)) return null;
+    throw error;
+  }
+}
+
+const SOURCE_BY_PROVIDER_AND_TYPE = new Map([
+  ["codex\0cli-history", "codex-cli"],
+  ["claude_code\0cli-history", "claude"],
+  ["claude_sdk\0claude-sdk-history", "claude-sdk"],
+  ["claude_desktop\0claude-code-desktop-metadata", "claude-code-desktop"],
+  ["claude_desktop\0claude-workspace-desktop", "claude-cowork"],
+  ["cursor\0cursor-workspace-sqlite", "cursor"],
+  ["cursor\0cursor-global-sqlite", "cursor"],
+  ["cursor\0cursor-raw-sqlite-salvage", "cursor"],
+  ["cursor\0cursor-agent-transcripts", "cursor"],
+  ["opencode\0opencode-history", "opencode-cli"],
+  ["opencode\0opencode-sqlite-history", "opencode-cli"],
+  ["opencode\0opencode-cli-sqlite-history", "opencode-cli"],
+  ["opencode\0opencode-desktop-sqlite-history", "opencode-desktop"],
+  ["opencode\0opencode-web-sqlite-history", "opencode-web"],
+  ["antigravity_cli\0antigravity-cli-brain", "antigravity-cli"],
+  ["antigravity_ide\0antigravity-ide-brain", "antigravity-ide"],
+  ...HISTORY_PROVIDER_OPTIONS
+    .filter((item) => item.provider && item.sourceType)
+    .map((item) => [`${item.provider}\0${item.sourceType}`, item.source])
+]);
+
+const SOURCE_BY_PROVIDER = {
+  aider: "aider",
+  antigravity: "antigravity",
+  antigravity_cli: "antigravity-cli",
+  antigravity_ide: "antigravity-ide",
+  chatgpt: "chatgpt",
+  claude_code: "claude",
+  claude_sdk: "claude-sdk",
+  claude_web: "claude-web",
+  cline: "cline",
+  copilot: "copilot-cli",
+  cursor: "cursor",
+  devin: "devin-cli",
+  factory: "factory",
+  gemini_cli: "gemini-cli",
+  grok: "grok-build",
+  pi: "pi",
+  windsurf: "windsurf"
+};
+
+module.exports = {
+  CLAUDE_CODE_REPAIR_COMMAND,
+  CLAUDE_CODE_REPAIR_PREVIEW_COMMAND,
+  claudeCodeSourceRoots,
+  filesystemSourcePath,
+  planClaudeCodeBackupRepair,
+  preservedArchiveSession,
+  preservedWebChatSession,
+  repairClaudeCodeBackups,
+  requiredSourcePaths,
+  sessionHasUnavailableSource,
+  sessionRawRecords,
+  sourceForSession,
+  summarizeUnavailableSourceSessions,
+  unavailableSourceBreakdown,
+  unavailableSourcePaths,
+  unavailableSourceSessions
+};