@inetafrica/open-claudia 2.15.0 → 3.0.0

package/core/state.js

@@ -4,7 +4,11 @@
 
 const fs = require("fs");
 const path = require("path");
-const { STATE_FILE, SESSIONS_FILE, IDENTITIES_FILE, CONFIG_DIR, CHAT_ID, UNIFIED_IDENTITY } = require("./config");
+const crypto = require("crypto");
+const {
+  STATE_FILE, SESSIONS_FILE, IDENTITIES_FILE, CONFIG_DIR, CHAT_ID, UNIFIED_IDENTITY,
+  JOBS_FILE, CRONS_FILE,
+} = require("./config");
 const {
   normalizeCanonicalUserId,
   canonicalForTelegram,
@@ -18,50 +22,492 @@ const {
 } = require("./identity");
 const { currentChannelId, currentCanonicalUserId } = require("./context");
 const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
+const {
+  defaultMigrationSources,
+  markMigrationComponentActivated,
+  markMigrationComponentPrepared,
+  requireMigrationSnapshotForComponent,
+} = require("./migration-backup");
 
-function loadStateFile() {
-  return readJsonWithFallback(STATE_FILE, {});
+const STATE_SCHEMA_VERSION = 3;
+const SESSIONS_SCHEMA_VERSION = 3;
+const MAX_USAGE_ENTRIES = 50;
+const MAX_SESSIONS_PER_PROJECT = 20;
+const MAX_SESSION_CALLBACKS = 200;
+const SESSION_CALLBACK_TTL_MS = 10 * 60 * 1000;
+const PROVIDER_SETTING_KEYS = Object.freeze(["model", "effort", "budget", "permissionMode", "worktree"]);
+const LEGACY_POINTERS = Object.freeze({
+  lastSessionId: "claude",
+  codexSessionId: "codex",
+});
+const REMOVED_PROVIDER_POINTERS = Object.freeze({ cursorSessionId: "cursor" });
+const ACTIVE_PROVIDER_IDS = new Set(["claude", "codex"]);
+const SELECTABLE_SESSION_PROVIDERS = new Set(ACTIVE_PROVIDER_IDS);
+const sessionCallbackTokens = new Map();
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function cloneRecord(value) {
+  return isRecord(value) ? { ...value } : {};
+}
+
+function providerDefaults() {
+  return { model: null, effort: null, budget: null, permissionMode: null, worktree: false };
+}
+
+function normalizeProviderId(providerId, fallback = null) {
+  const value = String(providerId || "").trim().toLowerCase();
+  return ACTIVE_PROVIDER_IDS.has(value) ? value : fallback;
+}
+
+function normalizeProviderSettings(value) {
+  const source = cloneRecord(value);
+  const result = {};
+  for (const providerId of ["claude", "codex"]) {
+    const provider = normalizeProviderId(providerId, null);
+    if (!provider) continue;
+    const settings = cloneRecord(source[providerId]);
+    result[provider] = { ...providerDefaults() };
+    for (const key of PROVIDER_SETTING_KEYS) {
+      if (Object.prototype.hasOwnProperty.call(settings, key)) result[provider][key] = settings[key];
+    }
+  }
+  return result;
+}
+
+function normalizeActiveSessions(value) {
+  const result = {};
+  for (const [projectName, providers] of Object.entries(cloneRecord(value))) {
+    const project = String(projectName || "").trim();
+    if (!project || !isRecord(providers)) continue;
+    const bucket = {};
+    for (const [providerId, sessionId] of Object.entries(providers)) {
+      const provider = normalizeProviderId(providerId, null);
+      if (!provider || !ACTIVE_PROVIDER_IDS.has(provider) || typeof sessionId !== "string" || !sessionId) continue;
+      bucket[provider] = sessionId;
+    }
+    if (Object.keys(bucket).length) result[project] = bucket;
+  }
+  return result;
+}
+
+function boundUsageBySession(value, limit = MAX_USAGE_ENTRIES) {
+  const entries = Object.entries(cloneRecord(value))
+    .filter(([key, usage]) => typeof key === "string" && key && isRecord(usage));
+  return Object.fromEntries(entries.slice(-Math.max(1, limit)));
+}
+
+function freshUsage() {
+  return { turns: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, costUsd: 0, lastInputTokens: 0, liveContextTokens: 0, lastUsageScope: "turn_delta" };
+}
+
+function usageSessionKey(projectName, providerId, sessionId) {
+  const project = String(projectName || "").trim();
+  const provider = normalizeProviderId(providerId, null);
+  if (!project || !provider) return null;
+  return `${project}\u0000${provider}\u0000${sessionId || "new"}`;
+}
+
+function projectNameFrom(value) {
+  if (typeof value === "string") return value.trim() || null;
+  if (isRecord(value)) return String(value.name || "").trim() || null;
+  return null;
+}
+
+function commonSettingsFrom(value) {
+  const settings = cloneRecord(value);
+  for (const key of PROVIDER_SETTING_KEYS) delete settings[key];
+  settings.backend = Object.prototype.hasOwnProperty.call(settings, "backend")
+    ? normalizeProviderId(settings.backend, null)
+    : null;
+  if (!Object.prototype.hasOwnProperty.call(settings, "compactWindow")) settings.compactWindow = null;
+  if (!Object.prototype.hasOwnProperty.call(settings, "recallEngine")) settings.recallEngine = null;
+  return settings;
 }
 
 function mergeSavedState(existing, next) {
+  const mergedProviders = normalizeProviderSettings(existing.providerSettings);
+  for (const [provider, settings] of Object.entries(normalizeProviderSettings(next.providerSettings))) {
+    mergedProviders[provider] = { ...(mergedProviders[provider] || providerDefaults()), ...settings };
+  }
+  const mergedSessions = normalizeActiveSessions(existing.activeSessions);
+  for (const [project, providers] of Object.entries(normalizeActiveSessions(next.activeSessions))) {
+    mergedSessions[project] = { ...(mergedSessions[project] || {}), ...providers };
+  }
   return {
     ...existing,
     ...next,
-    settings: { ...(existing.settings || {}), ...(next.settings || {}) },
-    sessionUsage: { ...(existing.sessionUsage || {}), ...(next.sessionUsage || {}) },
+    settings: { ...commonSettingsFrom(existing.settings), ...commonSettingsFrom(next.settings) },
+    activeSessions: mergedSessions,
+    providerSettings: mergedProviders,
+    usageBySession: boundUsageBySession({
+      ...cloneRecord(existing.usageBySession),
+      ...cloneRecord(next.usageBySession),
+    }),
+    legacyProviderState: {
+      ...cloneRecord(existing.legacyProviderState),
+      ...cloneRecord(next.legacyProviderState),
+      archivedSessionPointers: {
+        ...cloneRecord(existing.legacyProviderState?.archivedSessionPointers),
+        ...cloneRecord(next.legacyProviderState?.archivedSessionPointers),
+      },
+      unresolvedSessionPointers: {
+        ...cloneRecord(existing.legacyProviderState?.unresolvedSessionPointers),
+        ...cloneRecord(next.legacyProviderState?.unresolvedSessionPointers),
+      },
+      archivedActiveSessions: {
+        ...cloneRecord(existing.legacyProviderState?.archivedActiveSessions),
+        ...cloneRecord(next.legacyProviderState?.archivedActiveSessions),
+      },
+      archivedProviderSettings: {
+        ...cloneRecord(existing.legacyProviderState?.archivedProviderSettings),
+        ...cloneRecord(next.legacyProviderState?.archivedProviderSettings),
+      },
+      unresolvedCodexUsageSnapshots: {
+        ...cloneRecord(existing.legacyProviderState?.unresolvedCodexUsageSnapshots),
+        ...cloneRecord(next.legacyProviderState?.unresolvedCodexUsageSnapshots),
+      },
+    },
   };
 }
 
+function migrateSavedUser(value) {
+  const source = cloneRecord(value);
+  const sourceSettings = cloneRecord(source.settings);
+  const settings = commonSettingsFrom(source.settings);
+  const removedSelection = String(sourceSettings.backend || "").toLowerCase() === "cursor";
+  if (removedSelection) settings.backend = null;
+  const provider = normalizeProviderId(settings.backend, null);
+  const providerSettings = normalizeProviderSettings(source.providerSettings);
+  if (provider) {
+    if (!providerSettings[provider]) providerSettings[provider] = providerDefaults();
+    for (const key of PROVIDER_SETTING_KEYS) {
+      if (Object.prototype.hasOwnProperty.call(sourceSettings, key)) {
+        providerSettings[provider][key] = sourceSettings[key];
+      }
+    }
+  }
+
+  const activeSessions = normalizeActiveSessions(source.activeSessions);
+  const project = projectNameFrom(source.currentSession);
+  const legacy = cloneRecord(source.legacyProviderState);
+  const archivedSessionPointers = cloneRecord(legacy.archivedSessionPointers);
+  const unresolvedSessionPointers = cloneRecord(legacy.unresolvedSessionPointers);
+  const archivedActiveSessions = cloneRecord(legacy.archivedActiveSessions);
+  const archivedProviderSettings = cloneRecord(legacy.archivedProviderSettings);
+  for (const [projectName, providers] of Object.entries(cloneRecord(source.activeSessions))) {
+    if (!isRecord(providers) || typeof providers.cursor !== "string" || !providers.cursor) continue;
+    archivedActiveSessions[projectName] = {
+      ...cloneRecord(archivedActiveSessions[projectName]),
+      cursor: providers.cursor,
+    };
+  }
+  if (isRecord(source.providerSettings?.cursor)) {
+    archivedProviderSettings.cursor = {
+      ...cloneRecord(archivedProviderSettings.cursor),
+      ...cloneRecord(source.providerSettings.cursor),
+    };
+  }
+  if (removedSelection) {
+    archivedProviderSettings.cursor = {
+      ...providerDefaults(),
+      ...cloneRecord(archivedProviderSettings.cursor),
+    };
+    for (const key of PROVIDER_SETTING_KEYS) {
+      if (Object.prototype.hasOwnProperty.call(sourceSettings, key)) archivedProviderSettings.cursor[key] = sourceSettings[key];
+    }
+  }
+  let legacyCodexPointerUnresolved = false;
+  let legacyCodexPointerProject = null;
+  for (const [legacyKey, providerId] of Object.entries(LEGACY_POINTERS)) {
+    const sessionId = source[legacyKey];
+    if (typeof sessionId !== "string" || !sessionId) continue;
+    archivedSessionPointers[providerId] = sessionId;
+    if (providerId === "codex") {
+      // The legacy Codex pointer was process-global rather than project-bound.
+      // Only retain it as active when an already provider-aware bucket proves
+      // exactly one project owns the same thread; currentSession is not proof.
+      const owners = Object.entries(activeSessions)
+        .filter(([, providers]) => providers.codex === sessionId)
+        .map(([projectName]) => projectName);
+      if (owners.length !== 1) {
+        unresolvedSessionPointers.codex = sessionId;
+        legacyCodexPointerUnresolved = true;
+      } else legacyCodexPointerProject = owners[0];
+      continue;
+    }
+    if (project) {
+      activeSessions[project] = { ...(activeSessions[project] || {}) };
+      if (!activeSessions[project][providerId]) activeSessions[project][providerId] = sessionId;
+    } else {
+      unresolvedSessionPointers[providerId] = sessionId;
+    }
+  }
+  for (const [legacyKey, providerId] of Object.entries(REMOVED_PROVIDER_POINTERS)) {
+    const sessionId = source[legacyKey];
+    if (typeof sessionId !== "string" || !sessionId) continue;
+    archivedSessionPointers[providerId] = sessionId;
+    if (project) {
+      archivedActiveSessions[project] = {
+        ...cloneRecord(archivedActiveSessions[project]),
+        [providerId]: sessionId,
+      };
+    } else {
+      unresolvedSessionPointers[providerId] = sessionId;
+    }
+  }
+
+  const usageBySession = boundUsageBySession(source.usageBySession);
+  if (isRecord(source.sessionUsage)) {
+    const key = provider === "codex" && typeof source.codexSessionId === "string" && source.codexSessionId
+      ? (legacyCodexPointerUnresolved
+          ? null
+          : usageSessionKey(legacyCodexPointerProject, "codex", source.codexSessionId))
+      : usageSessionKey(project, provider, project ? activeSessions[project]?.[provider] : null);
+    if (key && !usageBySession[key]) usageBySession[key] = { ...freshUsage(), ...source.sessionUsage };
+    else if (!key && !legacy.unresolvedUsage) legacy.unresolvedUsage = { ...source.sessionUsage };
+  }
+  const legacyCodexSnapshots = cloneRecord(source.codexUsageSnapshots);
+  for (const [sessionId, snapshot] of Object.entries(legacyCodexSnapshots)) {
+    if (!isRecord(snapshot)) continue;
+    const owners = Object.entries(activeSessions)
+      .filter(([, providers]) => providers.codex === sessionId)
+      .map(([projectName]) => projectName);
+    if (owners.length === 1) {
+      const key = usageSessionKey(owners[0], "codex", sessionId);
+      usageBySession[key] = {
+        ...freshUsage(),
+        ...cloneRecord(usageBySession[key]),
+        providerUsageSnapshot: { ...snapshot },
+      };
+    } else {
+      legacy.unresolvedCodexUsageSnapshots = {
+        ...cloneRecord(legacy.unresolvedCodexUsageSnapshots),
+        [sessionId]: { ...snapshot },
+      };
+    }
+  }
+
+  const result = {
+    ...source,
+    currentSession: isRecord(source.currentSession) ? { ...source.currentSession } : null,
+    settings,
+    activeSessions,
+    providerSettings,
+    usageBySession: boundUsageBySession(usageBySession),
+    legacyProviderState: {
+      ...legacy,
+      ...(Object.keys(archivedSessionPointers).length ? { archivedSessionPointers } : {}),
+      ...(Object.keys(unresolvedSessionPointers).length ? { unresolvedSessionPointers } : {}),
+      ...(Object.keys(archivedActiveSessions).length ? { archivedActiveSessions } : {}),
+      ...(Object.keys(archivedProviderSettings).length ? { archivedProviderSettings } : {}),
+      ...((removedSelection || legacy.providerSelectionRequired) ? {
+        archivedBackend: legacy.archivedBackend || "cursor",
+        providerSelectionRequired: true,
+      } : {}),
+    },
+    lastCompactedAt: Number.isFinite(source.lastCompactedAt) ? source.lastCompactedAt : 0,
+  };
+  for (const legacyKey of Object.keys(LEGACY_POINTERS)) delete result[legacyKey];
+  for (const legacyKey of Object.keys(REMOVED_PROVIDER_POINTERS)) delete result[legacyKey];
+  delete result.sessionUsage;
+  delete result.codexUsageSnapshots;
+  if (!Object.keys(result.legacyProviderState).length) delete result.legacyProviderState;
+  return result;
+}
+
+function migrateStateDocument(raw, options = {}) {
+  const source = isRecord(raw) ? raw : {};
+  if (Number.isFinite(source.schemaVersion) && source.schemaVersion > STATE_SCHEMA_VERSION) {
+    const error = new Error(`unsupported state schema version: ${source.schemaVersion}`);
+    error.code = "UNSUPPORTED_STATE_SCHEMA";
+    throw error;
+  }
+  const defaultUserId = String(options.defaultUserId || "telegram:");
+  const canonicalize = typeof options.canonicalizeUserId === "function"
+    ? options.canonicalizeUserId
+    : (value) => String(value);
+  const sourceUsers = isRecord(source.users) ? source.users : { [defaultUserId]: source };
+  const users = {};
+  for (const [key, value] of Object.entries(sourceUsers)) {
+    const userId = String(canonicalize(key) || key);
+    const migrated = migrateSavedUser(value);
+    users[userId] = users[userId] ? mergeSavedState(users[userId], migrated) : migrated;
+  }
+  return { schemaVersion: STATE_SCHEMA_VERSION, users };
+}
+
+function loadStateFile() {
+  return readJsonWithFallback(STATE_FILE, {});
+}
+
 // Multi-user state. Legacy top-level shapes are migrated to
 // `{ users: { "<canonicalId>": {...} } }` on load.
+const hadPersistedStateFile = fs.existsSync(STATE_FILE);
 const savedState = (() => {
   const raw = loadStateFile();
-  const users = {};
-  if (raw && raw.users && typeof raw.users === "object") {
-    for (const [key, value] of Object.entries(raw.users)) {
-      const userId = canonicalForStoredUserKey(key);
-      users[userId] = mergeSavedState(users[userId] || {}, value || {});
-    }
-    return { users };
-  }
-  return { users: { [canonicalForTelegram(CHAT_ID || "")]: raw || {} } };
+  return migrateStateDocument(raw, {
+    defaultUserId: canonicalForTelegram(CHAT_ID || ""),
+    canonicalizeUserId: canonicalForStoredUserKey,
+  });
 })();
 
 const userStates = new Map();
 
-function freshSettings() {
-  return { model: null, effort: null, budget: null, permissionMode: null, worktree: false, backend: "claude", compactWindow: null, recallEngine: null };
+let cachedFreshDefaultProvider;
+function freshDefaultProvider() {
+  if (cachedFreshDefaultProvider !== undefined) return cachedFreshDefaultProvider;
+  try {
+    cachedFreshDefaultProvider = require("./providers").selectDefaultProvider().providerId;
+  } catch (_) {
+    cachedFreshDefaultProvider = null;
+  }
+  return cachedFreshDefaultProvider;
 }
 
-function freshUsage() {
-  return { turns: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, costUsd: 0, lastInputTokens: 0, liveContextTokens: 0, lastUsageScope: "turn_delta" };
+function freshSettings(defaultProvider = null) {
+  return {
+    model: null,
+    effort: null,
+    budget: null,
+    permissionMode: null,
+    worktree: false,
+    backend: defaultProvider,
+    compactWindow: null,
+    recallEngine: null,
+  };
+}
+
+function getActiveProvider(state) {
+  return normalizeProviderId(state?.settings?.backend, null);
+}
+
+function getProjectKey(state, projectName) {
+  return projectNameFrom(projectName === undefined ? state?.currentSession : projectName);
+}
+
+function getProviderSession(state, providerId, projectName) {
+  const project = getProjectKey(state, projectName);
+  const provider = normalizeProviderId(providerId, null);
+  if (!state || !project || !provider) return null;
+  const value = state.activeSessions?.[project]?.[provider];
+  return typeof value === "string" && value ? value : null;
+}
+
+function setProviderSession(state, providerId, projectName, sessionId) {
+  const project = getProjectKey(state, projectName);
+  const provider = normalizeProviderId(providerId, null);
+  if (!state || !project || !provider || typeof sessionId !== "string" || !sessionId) {
+    throw new TypeError("provider, project, and sessionId are required");
+  }
+  if (!isRecord(state.activeSessions)) state.activeSessions = {};
+  state.activeSessions[project] = { ...cloneRecord(state.activeSessions[project]), [provider]: sessionId };
+  return sessionId;
+}
+
+function clearProviderSession(state, providerId, projectName) {
+  const project = getProjectKey(state, projectName);
+  const provider = normalizeProviderId(providerId, null);
+  if (!state || !project || !provider || !isRecord(state.activeSessions?.[project])) return false;
+  const bucket = { ...state.activeSessions[project] };
+  if (!Object.prototype.hasOwnProperty.call(bucket, provider)) return false;
+  delete bucket[provider];
+  if (Object.keys(bucket).length) state.activeSessions[project] = bucket;
+  else delete state.activeSessions[project];
+  return true;
+}
+
+function getProviderSettings(state, providerId) {
+  if (!state || typeof state !== "object") throw new TypeError("state is required");
+  const provider = normalizeProviderId(providerId || getActiveProvider(state), null);
+  if (!provider) {
+    const error = new Error("Choose Claude Code or OpenAI Codex before changing provider settings");
+    error.code = "NO_ACTIVE_PROVIDER";
+    throw error;
+  }
+  if (!isRecord(state.providerSettings)) state.providerSettings = {};
+  if (!isRecord(state.providerSettings[provider])) state.providerSettings[provider] = providerDefaults();
+  else state.providerSettings[provider] = { ...providerDefaults(), ...state.providerSettings[provider] };
+  return state.providerSettings[provider];
+}
+
+function getActiveUsage(state) {
+  if (!state || typeof state !== "object") throw new TypeError("state is required");
+  const project = getProjectKey(state);
+  if (!project) {
+    if (!isRecord(state.unscopedUsage)) state.unscopedUsage = freshUsage();
+    return state.unscopedUsage;
+  }
+  const provider = getActiveProvider(state);
+  if (!provider) {
+    if (!isRecord(state.unscopedUsage)) state.unscopedUsage = freshUsage();
+    return state.unscopedUsage;
+  }
+  return getUsageForSession(state, project, provider, getProviderSession(state, provider, project));
+}
+
+function getUsageForSession(state, projectName, providerId, sessionId) {
+  if (!state || typeof state !== "object") throw new TypeError("state is required");
+  const project = getProjectKey(state, projectName);
+  const provider = normalizeProviderId(providerId, null);
+  if (!project || !provider) throw new TypeError("project and provider are required for usage");
+  const key = usageSessionKey(project, provider, sessionId);
+  if (!isRecord(state.usageBySession)) state.usageBySession = {};
+  const usage = isRecord(state.usageBySession[key]) ? state.usageBySession[key] : freshUsage();
+  delete state.usageBySession[key];
+  state.usageBySession[key] = usage;
+  state.usageBySession = boundUsageBySession(state.usageBySession);
+  return state.usageBySession[key];
+}
+
+function attachRuntimeAccessors(state) {
+  for (const key of PROVIDER_SETTING_KEYS) {
+    Object.defineProperty(state.settings, key, {
+      configurable: true,
+      enumerable: true,
+      get() {
+        const provider = getActiveProvider(state);
+        return provider ? getProviderSettings(state, provider)[key] : providerDefaults()[key];
+      },
+      set(value) {
+        const provider = getActiveProvider(state);
+        if (!provider) throw Object.assign(new Error("Choose a provider first"), { code: "NO_ACTIVE_PROVIDER" });
+        getProviderSettings(state, provider)[key] = value;
+      },
+    });
+  }
+  Object.defineProperty(state, "sessionUsage", {
+    configurable: true,
+    enumerable: true,
+    get() { return getActiveUsage(state); },
+    set(value) {
+      const project = getProjectKey(state);
+      if (!project) { state.unscopedUsage = { ...freshUsage(), ...cloneRecord(value) }; return; }
+      const provider = getActiveProvider(state);
+      if (!provider) { state.unscopedUsage = { ...freshUsage(), ...cloneRecord(value) }; return; }
+      const key = usageSessionKey(project, provider, getProviderSession(state, provider, project));
+      delete state.usageBySession[key];
+      state.usageBySession[key] = { ...freshUsage(), ...cloneRecord(value) };
+      state.usageBySession = boundUsageBySession(state.usageBySession);
+    },
+  });
+  return state;
 }
 
 function createUserState(userId) {
   const saved = (savedState.users && savedState.users[userId]) || {};
-  const settings = saved.settings || freshSettings();
-  if (!settings.backend) settings.backend = "claude";
-  return {
+  const hasSavedUser = hadPersistedStateFile
+    && !!savedState.users
+    && Object.prototype.hasOwnProperty.call(savedState.users, userId);
+  const defaults = freshSettings(freshDefaultProvider());
+  const settings = commonSettingsFrom(hasSavedUser ? (saved.settings || {}) : defaults);
+  if (!hasSavedUser) settings.backend = defaults.backend;
+  else if (!settings.backend && !saved.legacyProviderState?.providerSelectionRequired) {
+    settings.backend = freshDefaultProvider();
+  }
+  const state = {
     userId: String(userId),
     channelId: currentChannelId(),
     currentSession: saved.currentSession || null,
@@ -78,15 +524,16 @@ function createUserState(userId) {
     statusMessageChannel: null,
     streamBuffer: "",
     streamInterval: null,
-    lastSessionId: saved.lastSessionId || null,
-    cursorSessionId: saved.cursorSessionId || null,
-    codexSessionId: saved.codexSessionId || null,
-    codexUsageSnapshots: saved.codexUsageSnapshots || {},
+    activeSessions: normalizeActiveSessions(saved.activeSessions),
+    providerSettings: normalizeProviderSettings(saved.providerSettings),
+    usageBySession: boundUsageBySession(saved.usageBySession),
     messageQueue: [],
-    isFirstMessage: !saved.lastSessionId,
+    isFirstMessage: true,
     lastInputWasVoice: false,
-    sessionUsage: saved.sessionUsage || freshUsage(),
     settings,
+    legacyProviderState: cloneRecord(saved.legacyProviderState),
+    pendingCompaction: isRecord(saved.pendingCompaction) ? structuredClone(saved.pendingCompaction) : null,
+    completedCompactions: cloneRecord(saved.completedCompactions),
     onboardingStep: null,
     onboardingData: {},
     pendingVaultUnlock: false,
@@ -98,12 +545,23 @@ function createUserState(userId) {
     isCompacting: false,
     lastCompactedAt: saved.lastCompactedAt || 0,
   };
+  attachRuntimeAccessors(state);
+  state.isFirstMessage = !getProviderSession(state, getActiveProvider(state), getProjectKey(state));
+  return state;
 }
 
 function getUserState(userId) {
   const id = normalizeCanonicalUserId(userId);
   if (!userStates.has(id)) userStates.set(id, createUserState(id));
   const state = userStates.get(id);
+  if (state.pendingCompaction && !state.compactionRecoveryChecked) {
+    state.compactionRecoveryChecked = true;
+    try { recoverPendingCompaction(state); }
+    catch (error) {
+      state.compactionRecoveryChecked = false;
+      throw error;
+    }
+  }
   state.channelId = currentChannelId() || state.channelId;
   return state;
 }
@@ -114,11 +572,12 @@ function currentState() {
 
 function resetSessionUsage(state = currentState()) {
   state.sessionUsage = freshUsage();
-  state.codexUsageSnapshots = {};
 }
 
 function resetSettings(state = currentState()) {
-  state.settings = freshSettings();
+  state.providerSettings = normalizeProviderSettings({});
+  state.settings = commonSettingsFrom(freshSettings(freshDefaultProvider()));
+  attachRuntimeAccessors(state);
 }
 
 // Synchronous single-flight run-lock. Returns true and arms the lock if no turn
@@ -126,101 +585,605 @@ function resetSettings(state = currentState()) {
 // must be NO await between calling this and the work it guards, so two turns for
 // one canonical user (owner's Telegram + Kazee sharing one state under unified
 // identity) can never both acquire and then race the shared state + JSON files.
+// Compaction owns the same admission boundary across its summary/seed gap.
 function acquireRunLock(state = currentState()) {
-  if (state.runningProcess || state.preparingRun) return false;
+  if (state.runningProcess || state.preparingRun || state.isCompacting) return false;
   state.preparingRun = true;
   return true;
 }
 
-function saveState() {
-  const data = { users: { ...(savedState.users || {}) } };
+function migrationSources() {
+  return defaultMigrationSources({
+    configDir: CONFIG_DIR,
+    stateFile: STATE_FILE,
+    sessionsFile: SESSIONS_FILE,
+    jobsFile: JOBS_FILE,
+    cronsFile: CRONS_FILE,
+  });
+}
+
+function serializeCommonSettings(settings) {
+  const result = {};
+  for (const [key, value] of Object.entries(settings || {})) {
+    if (!PROVIDER_SETTING_KEYS.includes(key)) result[key] = value;
+  }
+  result.backend = normalizeProviderId(result.backend, null);
+  if (!Object.prototype.hasOwnProperty.call(result, "compactWindow")) result.compactWindow = null;
+  if (!Object.prototype.hasOwnProperty.call(result, "recallEngine")) result.recallEngine = null;
+  return result;
+}
+
+function serializeUserState(state, existing = {}) {
+  const result = {
+    ...existing,
+    currentSession: state.currentSession,
+    activeSessions: normalizeActiveSessions(state.activeSessions),
+    providerSettings: normalizeProviderSettings(state.providerSettings),
+    usageBySession: boundUsageBySession(state.usageBySession),
+    settings: serializeCommonSettings(state.settings),
+    lastCompactedAt: state.lastCompactedAt || 0,
+    pendingCompaction: isRecord(state.pendingCompaction) ? structuredClone(state.pendingCompaction) : null,
+    completedCompactions: Object.fromEntries(Object.entries(cloneRecord(state.completedCompactions)).slice(-20)),
+  };
+  if (Object.keys(cloneRecord(state.legacyProviderState)).length) result.legacyProviderState = cloneRecord(state.legacyProviderState);
+  else delete result.legacyProviderState;
+  for (const legacyKey of Object.keys(LEGACY_POINTERS)) delete result[legacyKey];
+  for (const legacyKey of Object.keys(REMOVED_PROVIDER_POINTERS)) delete result[legacyKey];
+  delete result.sessionUsage;
+  return result;
+}
+
+function saveState(options = {}) {
+  const sources = migrationSources();
+  let snapshot;
+  try {
+    const disk = loadStateFile();
+    const alreadyProviderAware = Number.isFinite(disk?.schemaVersion)
+      && disk.schemaVersion >= 2
+      && disk.schemaVersion <= STATE_SCHEMA_VERSION
+      && isRecord(disk.users);
+    snapshot = requireMigrationSnapshotForComponent("state", {
+      configDir: CONFIG_DIR,
+      sources,
+      allowSourceMismatch: alreadyProviderAware,
+    });
+    markMigrationComponentPrepared(snapshot.snapshotDir, "state", {
+      configDir: CONFIG_DIR,
+      sources,
+      requireSourceMatch: !alreadyProviderAware,
+    });
+  } catch (e) {
+    console.error("saveState: migration preflight failed:", e.message);
+    if (options.strict) throw e;
+    return false;
+  }
+
+  const data = { schemaVersion: STATE_SCHEMA_VERSION, users: { ...(savedState.users || {}) } };
   for (const [id, s] of userStates) {
-    data.users[id] = {
-      currentSession: s.currentSession,
-      lastSessionId: s.lastSessionId,
-      cursorSessionId: s.cursorSessionId,
-      codexSessionId: s.codexSessionId,
-      codexUsageSnapshots: s.codexUsageSnapshots || {},
-      settings: s.settings,
-      sessionUsage: s.sessionUsage,
-      lastCompactedAt: s.lastCompactedAt || 0,
-    };
+    data.users[id] = serializeUserState(s, data.users[id]);
+  }
+  try {
+    atomicWriteFileSync(STATE_FILE, JSON.stringify(data), { backup: true });
+    if (typeof options.faultInjector === "function") options.faultInjector("after-state-write", { stateFile: STATE_FILE });
+    const persisted = readJsonWithFallback(STATE_FILE, null);
+    if (persisted?.schemaVersion !== STATE_SCHEMA_VERSION || !isRecord(persisted.users)) {
+      const error = new Error("provider-aware state verification failed after write");
+      error.code = "STATE_MIGRATION_WRITE_INVALID";
+      throw error;
+    }
+    markMigrationComponentActivated(snapshot.snapshotDir, "state", { configDir: CONFIG_DIR, sources });
+    savedState.schemaVersion = STATE_SCHEMA_VERSION;
+    savedState.users = data.users;
   }
-  savedState.users = data.users;
-  try { atomicWriteFileSync(STATE_FILE, JSON.stringify(data), { backup: true }); }
-  catch (e) { console.error("saveState: write failed:", e.message); }
+  catch (e) {
+    console.error("saveState: write failed:", e.message);
+    if (options.strict) throw e;
+    return false;
+  }
+  return true;
 }
 
 // ── Sessions ────────────────────────────────────────────────────────
 
-function loadSessions() {
-  const raw = readJsonWithFallback(SESSIONS_FILE, null);
-  if (!raw || typeof raw !== "object") return {};
-  const looksLegacy = Object.values(raw).some((v) => Array.isArray(v));
-  if (looksLegacy) return { [canonicalForTelegram(CHAT_ID || "")]: raw };
-  const migrated = {};
-  for (const [key, value] of Object.entries(raw)) {
-    const userId = canonicalForStoredUserKey(key);
-    migrated[userId] = { ...(migrated[userId] || {}) };
-    for (const [project, list] of Object.entries(value || {})) {
-      migrated[userId][project] = [
-        ...(migrated[userId][project] || []),
-        ...(Array.isArray(list) ? list : []),
-      ].slice(-20);
+function sessionTimestamp(value) {
+  const parsed = Date.parse(value || "");
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : new Date(0).toISOString();
+}
+
+function sessionSortValue(record) {
+  return Date.parse(record?.lastUsed || record?.created || "") || 0;
+}
+
+function normalizeSessionRecord(record, context, options = {}) {
+  if (!isRecord(record) || typeof record.id !== "string" || !record.id) return null;
+  const declaredProvider = String(record.provider || "").trim().toLowerCase();
+  if (declaredProvider === "cursor" || record.archivedProvider === "cursor") {
+    const created = sessionTimestamp(record.created);
+    const lastUsed = sessionTimestamp(record.lastUsed || record.created);
+    return {
+      ...record,
+      id: record.id,
+      provider: "legacy",
+      archivedProvider: "cursor",
+      project: context.project,
+      title: typeof record.title === "string" && record.title ? record.title : "Untitled",
+      created,
+      lastUsed,
+      selectable: false,
+      legacyResolution: "removed-provider",
+    };
+  }
+  let provider = normalizeProviderId(record.provider, null);
+  let selectable = record.selectable !== false;
+  let legacyResolution = record.legacyResolution || null;
+  if (declaredProvider === "legacy") {
+    provider = "legacy";
+    selectable = false;
+  } else if (!SELECTABLE_SESSION_PROVIDERS.has(provider)) {
+    provider = null;
+    if (typeof options.ownsSession === "function") {
+      const matches = [];
+      for (const candidate of ["claude", "codex"]) {
+        try {
+          if (options.ownsSession(candidate, { ...context, sessionId: record.id }) === true) matches.push(candidate);
+        } catch (_) { /* a read-only ownership probe is advisory */ }
+      }
+      if (matches.length === 1) provider = matches[0];
+      else legacyResolution = matches.length > 1 ? "ambiguous-provider" : "unclassified";
+    } else {
+      legacyResolution = "no-provider-probe";
     }
   }
-  return migrated;
+  if (!provider) provider = "legacy";
+  if (provider === "legacy") selectable = false;
+  const created = sessionTimestamp(record.created);
+  const lastUsed = sessionTimestamp(record.lastUsed || record.created);
+  return {
+    ...record,
+    id: record.id,
+    provider,
+    project: context.project,
+    title: typeof record.title === "string" && record.title ? record.title : "Untitled",
+    created,
+    lastUsed,
+    selectable,
+    ...(provider === "legacy" ? { legacyResolution: legacyResolution || "unclassified" } : {}),
+  };
 }
 
-function saveSessions(sessions) {
-  try { atomicWriteFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2), { backup: true }); }
-  catch (e) { console.error("saveSessions: write failed:", e.message); }
+function mergeSessionLists(existing, next) {
+  const records = new Map();
+  for (const record of [...(existing || []), ...(next || [])]) {
+    if (!record) continue;
+    const key = `${record.provider}\u0000${record.id}`;
+    const previous = records.get(key);
+    if (!previous || sessionSortValue(record) >= sessionSortValue(previous)) records.set(key, record);
+  }
+  return [...records.values()]
+    .sort((left, right) => sessionSortValue(left) - sessionSortValue(right))
+    .slice(-MAX_SESSIONS_PER_PROJECT);
 }
 
-function recordSession(userId, projectName, sessionId, title) {
-  const all = loadSessions();
-  const id = normalizeCanonicalUserId(userId);
-  if (!all[id]) all[id] = {};
-  if (!all[id][projectName]) all[id][projectName] = [];
-  const arr = all[id][projectName];
-  const existing = arr.find((s) => s.id === sessionId);
-  if (existing) {
-    if (title) existing.title = title;
-    existing.lastUsed = new Date().toISOString();
-  } else {
-    arr.push({
-      id: sessionId,
-      title: title || "Untitled",
-      created: new Date().toISOString(),
-      lastUsed: new Date().toISOString(),
+function migrateSessionsDocument(raw, options = {}) {
+  const source = isRecord(raw) ? raw : {};
+  if (Number.isFinite(source.schemaVersion) && source.schemaVersion > SESSIONS_SCHEMA_VERSION) {
+    const error = new Error(`unsupported sessions schema version: ${source.schemaVersion}`);
+    error.code = "UNSUPPORTED_SESSIONS_SCHEMA";
+    throw error;
+  }
+  const defaultUserId = String(options.defaultUserId || canonicalForTelegram(CHAT_ID || ""));
+  const canonicalize = typeof options.canonicalizeUserId === "function"
+    ? options.canonicalizeUserId
+    : canonicalForStoredUserKey;
+  const explicitUsers = isRecord(source.users) && (!Number.isFinite(source.schemaVersion) || source.schemaVersion <= SESSIONS_SCHEMA_VERSION);
+  const looksProjectRoot = !explicitUsers && Object.values(source).some((value) => Array.isArray(value));
+  const sourceUsers = explicitUsers ? source.users : (looksProjectRoot ? { [defaultUserId]: source } : source);
+  const users = {};
+  for (const [userKey, projects] of Object.entries(cloneRecord(sourceUsers))) {
+    const userId = String(canonicalize(userKey) || userKey);
+    if (!users[userId]) users[userId] = {};
+    for (const [projectKey, list] of Object.entries(cloneRecord(projects))) {
+      if (!Array.isArray(list)) continue;
+      const project = String(projectKey || "").trim();
+      if (!project) continue;
+      const normalized = list
+        .map((record) => normalizeSessionRecord(record, { userId, project }, options))
+        .filter(Boolean);
+      users[userId][project] = mergeSessionLists(users[userId][project], normalized);
+    }
+  }
+  return { schemaVersion: SESSIONS_SCHEMA_VERSION, users };
+}
+
+function loadSessionsDocument(options = {}) {
+  const raw = readJsonWithFallback(SESSIONS_FILE, {});
+  return migrateSessionsDocument(raw, {
+    defaultUserId: canonicalForTelegram(CHAT_ID || ""),
+    canonicalizeUserId: canonicalForStoredUserKey,
+    ownsSession: options.ownsSession,
+  });
+}
+
+function loadSessions(options = {}) {
+  return loadSessionsDocument(options).users;
+}
+
+function saveSessions(sessions, options = {}) {
+  const document = migrateSessionsDocument(
+    isRecord(sessions?.users)
+      ? sessions
+      : { schemaVersion: SESSIONS_SCHEMA_VERSION, users: sessions || {} },
+    { canonicalizeUserId: canonicalForStoredUserKey },
+  );
+  const sources = migrationSources();
+  let snapshot;
+  try {
+    const disk = readJsonWithFallback(SESSIONS_FILE, {});
+    const alreadyProviderAware = Number.isFinite(disk?.schemaVersion)
+      && disk.schemaVersion >= 2
+      && disk.schemaVersion <= SESSIONS_SCHEMA_VERSION
+      && isRecord(disk.users);
+    snapshot = requireMigrationSnapshotForComponent("sessions", {
+      configDir: CONFIG_DIR,
+      sources,
+      allowSourceMismatch: alreadyProviderAware,
     });
+    markMigrationComponentPrepared(snapshot.snapshotDir, "sessions", {
+      configDir: CONFIG_DIR,
+      sources,
+      requireSourceMatch: !alreadyProviderAware,
+    });
+    atomicWriteFileSync(SESSIONS_FILE, JSON.stringify(document, null, 2), { backup: true });
+    if (typeof options.faultInjector === "function") options.faultInjector("after-sessions-write", { sessionsFile: SESSIONS_FILE });
+    const persisted = JSON.parse(fs.readFileSync(SESSIONS_FILE, "utf8"));
+    if (persisted?.schemaVersion !== SESSIONS_SCHEMA_VERSION || !isRecord(persisted.users)) {
+      const error = new Error("provider-aware sessions verification failed after write");
+      error.code = "SESSIONS_MIGRATION_WRITE_INVALID";
+      throw error;
+    }
+    markMigrationComponentActivated(snapshot.snapshotDir, "sessions", { configDir: CONFIG_DIR, sources });
+  } catch (e) {
+    console.error("saveSessions: write failed:", e.message);
+    if (options.strict) throw e;
+    return false;
+  }
+  return true;
+}
+
+function requiredSessionIdentity(userId, projectName, providerId, sessionId) {
+  const user = normalizeCanonicalUserId(userId);
+  const project = projectNameFrom(projectName);
+  const provider = normalizeProviderId(providerId, null);
+  if (!user || !project || !SELECTABLE_SESSION_PROVIDERS.has(provider) || typeof sessionId !== "string" || !sessionId) {
+    throw new TypeError("canonical user, project, provider, and sessionId are required");
   }
-  all[id][projectName] = arr.slice(-20);
-  saveSessions(all);
+  return { userId: user, project, provider, sessionId };
 }
 
-function getProjectSessions(userId, projectName) {
+function recordSession(userId, projectName, providerId, sessionId, title, options = {}) {
+  const identity = requiredSessionIdentity(userId, projectName, providerId, sessionId);
   const all = loadSessions();
-  return ((all[normalizeCanonicalUserId(userId)] || {})[projectName] || []).slice().reverse();
+  if (!all[identity.userId]) all[identity.userId] = {};
+  const current = Array.isArray(all[identity.userId][identity.project])
+    ? [...all[identity.userId][identity.project]]
+    : [];
+  const existingIndex = current.findIndex((record) => (
+    record?.id === identity.sessionId && record?.provider === identity.provider
+  ));
+  const previous = existingIndex >= 0 ? current.splice(existingIndex, 1)[0] : null;
+  const nowValue = typeof options.now === "function" ? options.now() : new Date();
+  const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+  if (!Number.isFinite(now.getTime())) throw new TypeError("session clock returned an invalid date");
+  const record = {
+    ...(previous || {}),
+    id: identity.sessionId,
+    provider: identity.provider,
+    project: identity.project,
+    title: title || previous?.title || "Untitled",
+    created: previous?.created || now.toISOString(),
+    lastUsed: now.toISOString(),
+    selectable: true,
+    ...(options.lineage ? { lineage: structuredClone(options.lineage) } : {}),
+  };
+  delete record.legacyResolution;
+  current.push(record);
+  all[identity.userId][identity.project] = mergeSessionLists([], current);
+  if (!saveSessions(all, options)) return null;
+  return record;
 }
 
-function getLastProjectSession(userId, projectName) {
-  const sessions = getProjectSessions(userId, projectName);
-  return sessions.length > 0 ? sessions[0] : null;
+function replaceProjectSessions(userId, projectName, records, options = {}) {
+  const user = normalizeCanonicalUserId(userId);
+  const project = projectNameFrom(projectName);
+  if (!user || !project || !Array.isArray(records)) {
+    throw new TypeError("canonical user, project, and session records are required");
+  }
+  const all = loadSessions();
+  if (!all[user]) all[user] = {};
+  all[user][project] = mergeSessionLists([], records.map((record) => (
+    normalizeSessionRecord(record, { userId: user, project }, options)
+  )).filter(Boolean));
+  if (!saveSessions(all, options)) return false;
+  return true;
 }
 
-// Cross-user leakage guard: only resume a Claude session id we have
-// recorded for this user. Stops migration glitches from handing one
-// person's conversation to another.
-function userOwnsClaudeSession(userId, sessionId) {
-  if (!sessionId) return false;
+function getProjectSessions(userId, projectName, providerId = null) {
+  const user = normalizeCanonicalUserId(userId);
+  const project = projectNameFrom(projectName);
+  if (!user || !project) throw new TypeError("canonical user and project are required");
+  const provider = providerId === null || providerId === undefined
+    ? null
+    : normalizeProviderId(providerId, null);
   const all = loadSessions();
-  const bucket = all[normalizeCanonicalUserId(userId)];
-  if (!bucket) return false;
-  for (const list of Object.values(bucket)) {
-    if (Array.isArray(list) && list.some((s) => s && s.id === sessionId)) return true;
+  return ((all[user] || {})[project] || [])
+    .filter((record) => !provider || record.provider === provider)
+    .slice()
+    .sort((left, right) => sessionSortValue(right) - sessionSortValue(left));
+}
+
+function getLastProjectSession(userId, projectName, providerId = null) {
+  const sessions = getProjectSessions(userId, projectName, providerId)
+    .filter((record) => record.selectable !== false && record.provider !== "legacy");
+  return sessions.length > 0 ? sessions[0] : null;
+}
+
+function userOwnsProviderSession(userId, projectName, providerId, sessionId) {
+  let identity;
+  try { identity = requiredSessionIdentity(userId, projectName, providerId, sessionId); }
+  catch (_) { return false; }
+  return getProjectSessions(identity.userId, identity.project, identity.provider).some((record) => (
+    record.id === identity.sessionId && record.selectable !== false && record.provider !== "legacy"
+  ));
+}
+
+function purgeSessionCallbackTokens(now = Date.now()) {
+  for (const [token, record] of sessionCallbackTokens) {
+    if (record.expiresAt <= now) sessionCallbackTokens.delete(token);
+  }
+  while (sessionCallbackTokens.size >= MAX_SESSION_CALLBACKS) {
+    sessionCallbackTokens.delete(sessionCallbackTokens.keys().next().value);
+  }
+}
+
+function createSessionCallbackToken(descriptor, options = {}) {
+  const identity = requiredSessionIdentity(
+    descriptor?.userId,
+    descriptor?.project,
+    descriptor?.provider,
+    descriptor?.sessionId,
+  );
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const ttlMs = Number.isFinite(options.ttlMs) && options.ttlMs > 0
+    ? Math.min(options.ttlMs, 60 * 60 * 1000)
+    : SESSION_CALLBACK_TTL_MS;
+  const tokenFactory = options.tokenFactory || (() => crypto.randomBytes(18).toString("base64url"));
+  purgeSessionCallbackTokens(now);
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const token = String(tokenFactory()).replace(/[^A-Za-z0-9_-]/g, "").slice(0, 48);
+    if (!token || sessionCallbackTokens.has(token)) continue;
+    sessionCallbackTokens.set(token, { ...identity, expiresAt: now + ttlMs });
+    return token;
+  }
+  throw new Error("could not allocate an opaque session callback token");
+}
+
+function consumeSessionCallbackToken(token, expected = {}) {
+  const opaque = String(token || "");
+  const record = sessionCallbackTokens.get(opaque);
+  if (record) sessionCallbackTokens.delete(opaque);
+  const now = Number.isFinite(expected.now) ? expected.now : Date.now();
+  if (!record || record.expiresAt <= now) return { status: "expired", value: null };
+  const userId = normalizeCanonicalUserId(expected.userId);
+  const project = projectNameFrom(expected.project);
+  const provider = normalizeProviderId(expected.provider, null);
+  if (record.userId !== userId || record.project !== project || record.provider !== provider) {
+    return { status: "forbidden", value: null };
+  }
+  return { status: "ok", value: { ...record } };
+}
+
+function compactionError(code, message) {
+  return Object.assign(new Error(message), { name: "CompactionCommitError", code });
+}
+
+function requireCompactionWrite(result, label) {
+  if (result === false || result === null) {
+    throw compactionError("COMPACTION_PERSIST_FAILED", `${label} did not persist`);
+  }
+  return result;
+}
+
+function validateCompactionTransaction(state, transaction) {
+  if (!isRecord(transaction)) throw compactionError("INVALID_COMPACTION", "compaction transaction is required");
+  const identity = requiredSessionIdentity(
+    transaction.canonicalUserId,
+    transaction.project,
+    transaction.provider,
+    transaction.previousSessionId,
+  );
+  if (identity.userId !== normalizeCanonicalUserId(state.userId)) {
+    throw compactionError("COMPACTION_USER_MISMATCH", "compaction belongs to another user");
+  }
+  if (typeof transaction.operationId !== "string" || !transaction.operationId
+      || typeof transaction.newSessionId !== "string" || !transaction.newSessionId) {
+    throw compactionError("INVALID_COMPACTION", "compaction operation and new session IDs are required");
+  }
+  if (transaction.newSessionId === identity.sessionId) {
+    throw compactionError("INVALID_COMPACTION", "compaction seed did not create a fresh provider session");
+  }
+  return {
+    ...transaction,
+    canonicalUserId: identity.userId,
+    project: identity.project,
+    provider: identity.provider,
+    previousSessionId: identity.sessionId,
+  };
+}
+
+function restorePendingCompaction(state, pending, options = {}) {
+  const replaceHistory = options.replaceHistory || replaceProjectSessions;
+  const persistState = options.persistState || saveState;
+  if (pending.previousSessionId) {
+    setProviderSession(state, pending.provider, pending.project, pending.previousSessionId);
+  } else {
+    clearProviderSession(state, pending.provider, pending.project);
+  }
+  if (pending.previousNewUsagePresent) {
+    state.usageBySession[pending.newUsageKey] = structuredClone(pending.previousNewUsage);
+  } else {
+    delete state.usageBySession[pending.newUsageKey];
+  }
+  state.lastCompactedAt = pending.previousLastCompactedAt || 0;
+  state.isFirstMessage = pending.previousIsFirstMessage;
+  if (isRecord(state.completedCompactions)) delete state.completedCompactions[pending.operationId];
+  requireCompactionWrite(
+    replaceHistory(pending.canonicalUserId, pending.project, pending.previousHistory || [], { strict: true }),
+    "compaction history rollback",
+  );
+  state.pendingCompaction = null;
+  requireCompactionWrite(persistState({ strict: true }), "compaction rollback state");
+  return { recovered: true, action: "rolled_back", operationId: pending.operationId };
+}
+
+function recoverPendingCompaction(state, options = {}) {
+  const pending = state?.pendingCompaction;
+  if (!isRecord(pending)) return { recovered: false };
+  const persistState = options.persistState || saveState;
+  if (pending.phase === "committed") {
+    setProviderSession(state, pending.provider, pending.project, pending.newSessionId);
+    state.pendingCompaction = null;
+    requireCompactionWrite(persistState({ strict: true }), "compaction recovery state");
+    return { recovered: true, action: "finalized", operationId: pending.operationId };
+  }
+  return restorePendingCompaction(state, pending, options);
+}
+
+function commitProviderCompaction(state, transaction, options = {}) {
+  const tx = validateCompactionTransaction(state, transaction);
+  if (state.completedCompactions?.[tx.operationId]) {
+    return {
+      committed: true,
+      duplicate: true,
+      operationId: tx.operationId,
+      sessionId: state.completedCompactions[tx.operationId].newSessionId,
+    };
+  }
+  if (state.pendingCompaction) recoverPendingCompaction(state, options);
+  const current = getProviderSession(state, tx.provider, tx.project);
+  if (current !== tx.previousSessionId) {
+    throw compactionError("COMPACTION_POINTER_CHANGED", "active provider session changed before compaction commit");
+  }
+
+  const persistState = options.persistState || saveState;
+  const recordHistory = options.recordHistory || recordSession;
+  const replaceHistory = options.replaceHistory || replaceProjectSessions;
+  const nowValue = typeof options.now === "function" ? options.now() : new Date();
+  const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+  if (!Number.isFinite(now.getTime())) throw compactionError("INVALID_COMPACTION", "compaction clock is invalid");
+  const newUsageKey = usageSessionKey(tx.project, tx.provider, tx.newSessionId);
+  const previousNewUsagePresent = Object.prototype.hasOwnProperty.call(state.usageBySession || {}, newUsageKey);
+  const previousHistory = getProjectSessions(tx.canonicalUserId, tx.project);
+  const pending = {
+    phase: "prepared",
+    operationId: tx.operationId,
+    canonicalUserId: tx.canonicalUserId,
+    project: tx.project,
+    provider: tx.provider,
+    previousSessionId: tx.previousSessionId,
+    newSessionId: tx.newSessionId,
+    newUsageKey,
+    previousNewUsagePresent,
+    previousNewUsage: previousNewUsagePresent ? structuredClone(state.usageBySession[newUsageKey]) : null,
+    previousHistory: structuredClone(previousHistory),
+    previousLastCompactedAt: state.lastCompactedAt || 0,
+    previousIsFirstMessage: !!state.isFirstMessage,
+    preparedAt: now.toISOString(),
+  };
+  state.pendingCompaction = pending;
+  let durableCommitted = false;
+  try {
+    requireCompactionWrite(persistState({ strict: true }), "compaction prepared state");
+    if (typeof options.faultInjector === "function") options.faultInjector("after-compaction-prepare", { transaction: tx });
+    const lineage = {
+      type: "compaction",
+      operationId: tx.operationId,
+      previousSessionId: tx.previousSessionId,
+      newSessionId: tx.newSessionId,
+    };
+    requireCompactionWrite(
+      recordHistory(
+        tx.canonicalUserId,
+        tx.project,
+        tx.provider,
+        tx.newSessionId,
+        tx.title || `Compacted ${now.toLocaleDateString()}`,
+        { strict: true, now: () => now, lineage },
+      ),
+      "compaction history",
+    );
+    if (typeof options.faultInjector === "function") options.faultInjector("after-compaction-history", { transaction: tx });
+
+    setProviderSession(state, tx.provider, tx.project, tx.newSessionId);
+    const nextUsage = {
+      ...freshUsage(),
+      lastCompactedAt: now.getTime(),
+      compactionCheckpoint: {
+        operationId: tx.operationId,
+        previousSessionId: tx.previousSessionId,
+        newSessionId: tx.newSessionId,
+        at: now.toISOString(),
+      },
+    };
+    if (tx.provider === "codex" && isRecord(tx.seedUsage)) {
+      nextUsage.providerUsageSnapshot = {
+        input_tokens: Number(tx.seedUsage.input_tokens) || 0,
+        cached_input_tokens: Number(tx.seedUsage.cached_input_tokens) || 0,
+        output_tokens: Number(tx.seedUsage.output_tokens) || 0,
+      };
+    }
+    state.usageBySession[newUsageKey] = nextUsage;
+    state.lastCompactedAt = now.getTime();
+    if (getActiveProvider(state) === tx.provider && getProjectKey(state) === tx.project) {
+      state.isFirstMessage = false;
+    }
+    state.completedCompactions = {
+      ...cloneRecord(state.completedCompactions),
+      [tx.operationId]: {
+        project: tx.project,
+        provider: tx.provider,
+        previousSessionId: tx.previousSessionId,
+        newSessionId: tx.newSessionId,
+        committedAt: now.toISOString(),
+      },
+    };
+    state.completedCompactions = Object.fromEntries(Object.entries(state.completedCompactions).slice(-20));
+    state.pendingCompaction = { ...pending, phase: "committed", committedAt: now.toISOString() };
+    requireCompactionWrite(persistState({ strict: true }), "compaction committed state");
+    durableCommitted = true;
+    if (typeof options.faultInjector === "function") options.faultInjector("after-compaction-state-commit", { transaction: tx });
+
+    const committedMarker = state.pendingCompaction;
+    state.pendingCompaction = null;
+    try { requireCompactionWrite(persistState({ strict: true }), "compaction marker cleanup"); }
+    catch (_) {
+      // The committed marker is itself durable and restart recovery will only
+      // clear it; never report a successful pointer/history commit as failed.
+      state.pendingCompaction = committedMarker;
+      return { committed: true, duplicate: false, recoveryPending: true, operationId: tx.operationId, sessionId: tx.newSessionId };
+    }
+    return { committed: true, duplicate: false, operationId: tx.operationId, sessionId: tx.newSessionId };
+  } catch (error) {
+    if (durableCommitted) {
+      return { committed: true, duplicate: false, recoveryPending: true, operationId: tx.operationId, sessionId: tx.newSessionId };
+    }
+    try {
+      state.pendingCompaction = pending;
+      restorePendingCompaction(state, pending, { persistState, replaceHistory });
+    } catch (rollbackError) {
+      error.rollbackError = rollbackError;
+    }
+    throw error;
   }
-  return false;
 }
 
 function migrateUserData(fromUserId, toUserId) {
@@ -312,10 +1275,27 @@ function autoLinkOwnerChannel(transport, channelId) {
 }
 
 module.exports = {
+  STATE_SCHEMA_VERSION,
+  SESSIONS_SCHEMA_VERSION,
+  MAX_USAGE_ENTRIES,
+  MAX_SESSIONS_PER_PROJECT,
+  MAX_SESSION_CALLBACKS,
+  SESSION_CALLBACK_TTL_MS,
+  PROVIDER_SETTING_KEYS,
   userStates,
   savedState,
   freshSettings,
   freshUsage,
+  migrateStateDocument,
+  getActiveProvider,
+  getProjectKey,
+  getProviderSession,
+  setProviderSession,
+  clearProviderSession,
+  getProviderSettings,
+  getActiveUsage,
+  getUsageForSession,
+  usageSessionKey,
   createUserState,
   getUserState,
   currentState,
@@ -324,11 +1304,18 @@ module.exports = {
   acquireRunLock,
   saveState,
   loadSessions,
+  loadSessionsDocument,
+  migrateSessionsDocument,
   saveSessions,
   recordSession,
+  replaceProjectSessions,
   getProjectSessions,
   getLastProjectSession,
-  userOwnsClaudeSession,
+  userOwnsProviderSession,
+  createSessionCallbackToken,
+  consumeSessionCallbackToken,
+  commitProviderCompaction,
+  recoverPendingCompaction,
   migrateUserData,
   linkIdentity,
   autoLinkOwnerChannel,