codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/shared/storageDb.js

@@ -1,18 +1,25 @@
 (function initStorageDb(root, factory) {
   if (typeof module === 'object' && module.exports) {
     module.exports = factory(require('./storageRunActions'), require('./runInputQueue'),
-      require('./settlementFacts'), require('./storageSessionClaims'), require('./sessionState'));
+      require('./settlementFacts'), require('./storageSessionClaims'), require('./sessionState'), require('./runActivityModel'), require('./sharedSessionBridge'), require('./subagentActivityModel'), require('./storageValuePruning'), require('./composerAttachmentDraft'), require('./sharedSessionTransfer'));
   } else {
     root.CodexOverleafModuleRegistry.define('StorageDb', [
       'StorageRunActions',
       'RunInputQueue',
       'SettlementFacts',
       'StorageSessionClaims',
-      'SessionState'
+      'SessionState',
+      'RunActivityModel',
+      'SharedSessionBridge',
+      'SubagentActivityModel',
+      'StorageValuePruning',
+      'ComposerAttachmentDraft',
+      'SharedSessionTransfer'
     ], factory);
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function storageDbFactory(StorageRunActions, RunInputQueue, SettlementFacts, StorageSessionClaims, SessionState) {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function storageDbFactory(StorageRunActions, RunInputQueue, SettlementFacts, StorageSessionClaims, SessionState, RunActivityModel, SharedSessionBridge, SubagentActivityModel, StorageValuePruning, ComposerAttachmentDraft, SharedSessionTransfer) {
   'use strict';
+  const { removeEmptySummaryFields, removeEmptyFields } = StorageValuePruning;
   if (!StorageRunActions?.compactRunsForStorage || !StorageRunActions?.compactRunActionPayload || !StorageRunActions?.compactProviderSnapshot || !StorageRunActions?.compactRunExecutionSnapshot || !StorageRunActions?.compactStructuredEventValue || !StorageRunActions?.hashString || !RunInputQueue?.compactForStorage || !SettlementFacts?.compactSettlementFacts || !StorageSessionClaims?.createSessionClaimer) {
     throw new Error('Codex Overleaf storage run-action helpers are unavailable.');
   }
@@ -135,6 +142,7 @@
     });
   }
   var claimSessionsForAccount = StorageSessionClaims.createSessionClaimer(openDb, function () { return IDBKeyRange; });
+  var composerDraftStore = ComposerAttachmentDraft.createStore(openDb);
 
   function putRecord(storeName, record) {
     return openDb().then(function (db) {
@@ -232,17 +240,7 @@
   }
 
   function clearAllStores() {
-    return openDb().then(function (db) {
-      var storeNames = Object.keys(STORES);
-      return new Promise(function (resolve, reject) {
-        var tx = db.transaction(storeNames, 'readwrite');
-        for (var i = 0; i < storeNames.length; i++) {
-          tx.objectStore(storeNames[i]).clear();
-        }
-        tx.oncomplete = function () { resolve(); };
-        tx.onerror = function (event) { reject(event.target.error); };
-      });
-    });
+    return composerDraftStore.clear(Object.keys(STORES));
   }
 
   // --- Record builders ---
@@ -272,14 +270,17 @@
     var lastActivityAt = typeof input.lastActivityAt === 'string' && input.lastActivityAt
       ? input.lastActivityAt
       : updatedAt;
-    return {
+    var record = {
       id: input.id || generateId('ses'),
       projectId: input.projectId || '',
       title: normalizeSessionTitleForStorage(input.title, titleSource),
       titleSource: titleSource,
       codexThreadId: typeof input.codexThreadId === 'string' ? input.codexThreadId : '',
+      forkedFromSessionId: normalizeTextField(input.forkedFromSessionId, 160),
+      forkedFromRunId: normalizeTextField(input.forkedFromRunId, 160),
       status: typeof input.status === 'string' && input.status ? input.status : 'active',
       focusFiles: normalizePathList(input.focusFiles),
+      selectionContext: SessionState.normalizeSelectionContext(input.selectionContext),
       projectReferenceFiles: SessionState.normalizeProjectReferenceFiles(input.projectReferenceFiles),
       pendingInputs: RunInputQueue.compactForStorage(input.pendingInputs, {
         normalizeField: normalizeTextField,
@@ -287,7 +288,8 @@
         normalizePaths: normalizePathList
       }),
       history: compactHistoryForStorage(input.history),
-      runs: compactRunsForStorage(input.runs, options),
+      runs: compactRunsForStorage(input.runs, { preserveRunActionPayload: false,
+        deferDirectoryCleanup: options.preserveRunActionPayload === true || options.deferDirectoryCleanup === true }),
       task: normalizeDisplayTextForStorage(input.task, SESSION_STORAGE_LIMITS.taskChars),
       mode: normalizeCurrentMode(input.mode), providerId: typeof input.providerId === 'string' && input.providerId ? input.providerId : 'builtin',
       model: typeof input.model === 'string' ? input.model : '',
@@ -301,6 +303,23 @@
       accountScopeUnavailable: accountScopeUnavailable,
       safeTaskSummary: safeTaskSummary
     };
+    if (options.preserveRunActionPayload === true) {
+      // Count the real display record before allocating recovery space. Adding
+      // older checkpoints must not make an otherwise valid history unwritable.
+      var metadataText = JSON.stringify(record), metadataBytes = SharedSessionTransfer.byteLength(metadataText);
+      record.runs = compactRunsForStorage(input.runs, { ...options,
+        canRetainActionPayload: function (bytes, chars) {
+          var totalBytes = metadataBytes + bytes + 4096, totalChars = metadataText.length + chars + 4096;
+          return totalBytes <= SharedSessionTransfer.MAX_WIRE_BYTES
+            || (totalBytes <= SharedSessionTransfer.MAX_RECORD_BYTES && totalChars * 2 <= SharedSessionTransfer.MAX_WIRE_BYTES);
+        } });
+    }
+    for (var run of record.runs) SessionState.pruneRunRecoveryScope(run, record);
+    return record;
+  }
+
+  function compactSessionBatchActions(records, options) {
+    return StorageRunActions.compactSessionBatchActions(records, options, buildSessionRecord, SharedSessionTransfer);
   }
 
   function resolveAccountScopeId(input) {
@@ -411,6 +430,7 @@
     var now = new Date().toISOString();
     return {
       id: input.id || generateId('aud'),
+      accountScopeId: typeof input.accountScopeId === 'string' ? input.accountScopeId : '',
       projectId: typeof input.projectId === 'string' ? input.projectId : '',
       sessionId: typeof input.sessionId === 'string' ? input.sessionId : '',
       turnId: typeof input.turnId === 'string' ? input.turnId : '',
@@ -460,7 +480,8 @@
       customInstructionsByProject: normalizeStringMap(state.customInstructionsByProject),
       governanceRulesByProject: normalizeGovernanceRulesMap(state.governanceRulesByProject),
       selectedLocalSkillIdsByProject: normalizeStringListMap(state.selectedLocalSkillIdsByProject),
-      codexOverleafSkillEnabled: normalizeCodexOverleafSkillEnabledMap(state.codexOverleafSkillEnabled)
+      codexOverleafSkillEnabled: normalizeCodexOverleafSkillEnabledMap(state.codexOverleafSkillEnabled),
+      codexLocalSkillEnabled: SessionState.normalizeCodexLocalSkillEnabled(state.codexLocalSkillEnabled)
     };
     return prefs;
   }
@@ -513,7 +534,7 @@
         continue;
       }
       result[key] = typeof value[rawKey] === 'string'
-        ? normalizeTextField(value[rawKey], CUSTOM_INSTRUCTIONS_MAX_CHARS)
+        ? normalizeDisplayTextForStorage(value[rawKey], CUSTOM_INSTRUCTIONS_MAX_CHARS)
         : '';
     }
     return result;
@@ -634,9 +655,9 @@
   function normalizeSessionTitleForStorage(value, titleSource) {
     var title = typeof value === 'string' ? value.trim() : '';
     if (titleSource === 'manual') {
-      return normalizeTextField(title === LEGACY_DEFAULT_SESSION_TITLE ? '' : title, SESSION_STORAGE_LIMITS.sessionTitleChars);
+      return normalizeDisplayTextForStorage(title === LEGACY_DEFAULT_SESSION_TITLE ? '' : title, SESSION_STORAGE_LIMITS.sessionTitleChars);
     }
-    return normalizeTextField(title === LEGACY_DEFAULT_SESSION_TITLE ? '' : title, SESSION_STORAGE_LIMITS.sessionTitleChars);
+    return normalizeDisplayTextForStorage(title === LEGACY_DEFAULT_SESSION_TITLE ? '' : title, SESSION_STORAGE_LIMITS.sessionTitleChars);
   }
 
   function compactHistoryForStorage(history) {
@@ -654,22 +675,27 @@
   function compactRunsForStorage(runs, options) {
     return StorageRunActions.compactRunsForStorage(runs, options, SESSION_STORAGE_LIMITS.maxRunsPerSession, compactRunForStorage);
   }
-  function compactRunForStorage(run, keepActionPayload) {
-    var actionPayload = StorageRunActions.compactRunActionPayload(run, keepActionPayload);
+  function compactRunForStorage(run, keepActionPayload, preparedActionPayload) {
+    run = SessionState.recoverRecordedRunFailure(run);
+    var actionPayload = preparedActionPayload || StorageRunActions.compactRunActionPayload(run, keepActionPayload);
     var compact = {
+      ...SessionState.pickWritebackRecovery(run),
       id: run.id,
+      forkSnapshot: run.forkSnapshot === true,
+      forkSourceRunId: normalizeTextField(run.forkSourceRunId, 160),
       task: normalizeDisplayTextForStorage(run.task || 'untitled task', SESSION_STORAGE_LIMITS.taskChars),
       mode: typeof run.mode === 'string' ? redactSecretLikeText(run.mode) : '', ...StorageRunActions.compactProviderSnapshot(run),
       ...StorageRunActions.compactRunExecutionSnapshot(run, function (text) { return normalizeTextField(text, 4096); }),
       model: normalizeTextField(run.model, 80),
       reasoningEffort: typeof run.reasoningEffort === 'string' ? redactSecretLikeText(run.reasoningEffort) : '',
       speedTier: typeof run.speedTier === 'string' ? redactSecretLikeText(run.speedTier) : '',
-      status: normalizeRunStatus(run.status),
+      status: SessionState.normalizeRunStatus(run.status, run),
       statusText: normalizeDisplayTextForStorage(run.statusText, SESSION_STORAGE_LIMITS.statusTextChars),
       runProjectId: normalizeProjectPrefKey(run.runProjectId),
       startedAt: typeof run.startedAt === 'string' ? redactSecretLikeText(run.startedAt) : '',
       finishedAt: typeof run.finishedAt === 'string' ? redactSecretLikeText(run.finishedAt) : '',
       events: compactRunEventsForStorage(run.events),
+      ...(run.subagents?.length ? { subagents: SubagentActivityModel.normalize(run.subagents, sanitizeAssistantVisibleText) } : {}),
       attachments: compactRunAttachmentsForStorage(run.attachments),
       appliedOperations: actionPayload.appliedOperations,
       undoOperations: actionPayload.undoOperations,
@@ -677,7 +703,10 @@
       undoTrackedChanges: actionPayload.undoTrackedChanges,
       undoExpectedFiles: actionPayload.undoExpectedFiles,
       ...(actionPayload.trackedChangeCaptures ? { trackedChangeCaptures: actionPayload.trackedChangeCaptures } : {}),
+      ...(actionPayload.pendingDirectoryCleanup ? { pendingDirectoryCleanup: actionPayload.pendingDirectoryCleanup } : {}),
+      ...(actionPayload.recoveryRetention ? { recoveryRetention: SessionState.normalizeRecoveryRetention(actionPayload.recoveryRetention) } : {}),
       undoStatus: normalizeDisplayTextForStorage(run.undoStatus, SESSION_STORAGE_LIMITS.statusTextChars),
+      ...(run.undoOwnerProtocol === 1 ? { undoOwnerProtocol: 1 } : {}),
       nativeRequestId: normalizeTextField(run.nativeRequestId, 160),
       codexThreadId: normalizeTextField(run.codexThreadId, 160), codexTurnId: normalizeTextField(run.codexTurnId, 160),
       nativeEventSeq: Number.isFinite(Number(run.nativeEventSeq)) ? Number(run.nativeEventSeq) : 0,
@@ -716,9 +745,17 @@
           status: normalizeEventStatus(event.status),
           timestamp: typeof event.timestamp === 'string' ? redactSecretLikeText(event.timestamp) : '',
           kind: typeof event.kind === 'string' ? redactSecretLikeText(event.kind) : 'activity',
+          guidanceId: normalizeTextField(event.guidanceId, 160),
           streamKey: typeof event.streamKey === 'string' ? redactSecretLikeText(event.streamKey) : '',
           streamRole: typeof event.streamRole === 'string' ? redactSecretLikeText(event.streamRole) : ''
         };
+        // Persist the bounded display projection, never the raw tool payload.
+        // Hydration uses the same model; dropping this metadata demotes tools
+        // to hidden diagnostics after an otherwise successful history reload.
+        var activity = RunActivityModel.capture(event, sanitizeAssistantVisibleText);
+        if (activity) compact.activity = activity;
+        var streamPhase = RunActivityModel.normalizePhase(event.streamPhase);
+        if (streamPhase) compact.streamPhase = streamPhase;
         if (event.subagent === true) {
           compact.subagent = true;
         }
@@ -744,7 +781,7 @@
 
   // Deep-copies a known-safe structured event value (the completion-report
   // {conclusion, body, meta[]} payload, or a FailureReason object) preserving
-  // its shape while redacting + truncating every string field. Bounded depth +
+  // its shape while applying display-path rules and string limits. Bounded depth +
   // breadth so a pathological value can't blow up the stored record.
   function compactStructuredEventValueForStorage(value, depth) {
     return StorageRunActions.compactStructuredEventValue(value, {
@@ -787,7 +824,11 @@
   }
 
   function normalizeDisplayTextForStorage(value, maxChars) {
-    return normalizeTextField(value, maxChars);
+    var text = sanitizeAssistantVisibleText(value);
+    if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
+      return text;
+    }
+    return text.slice(0, Math.max(0, maxChars - 1)) + '…';
   }
 
   function summarizeStructuredValueForStorage(value, maxChars) {
@@ -914,25 +955,6 @@
       .trim(), maxChars || SESSION_STORAGE_LIMITS.pathChars);
   }
 
-  function normalizeRunStatus(status) {
-    // Welcome-panel + write-guard: the run-status
-    // enum gained three post-navigation values. The storage normalizer must
-    // accept them so a settled run round-trips intact through `buildSessionRecord`.
-    // Unknown legacy values fall through to `completed` (the historical default).
-    return [
-      'pending',
-      'running',
-      'completed',
-      'failed',
-      'background_completed',
-      'needs_review_after_navigation',
-      'abandoned_after_navigation',
-      // v1.8.1: reload-orphaned runs settle to 'interrupted' (v1.7.6); the
-      // storage round-trip must not rewrite them to a false 'completed'.
-      'interrupted'
-    ].indexOf(status) !== -1 ? status : 'completed';
-  }
-
   function normalizeEventStatus(status) {
     return VALID_EVENT_STATUSES[status] ? status : 'info';
   }
@@ -1016,7 +1038,7 @@
   }
 
   function normalizeTextField(value, maxChars) {
-    var text = sanitizeAssistantVisibleText(value);
+    var text = sanitizeAssistantVisibleText(redactSecretLikeText(value));
     if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
       return text;
     }
@@ -1027,7 +1049,8 @@
     if (typeof value !== 'string' || !value) {
       return '';
     }
-    var text = redactSecretLikeText(value);
+    // Preserve conversation examples and quotations through save/reload.
+    var text = value;
     if (!mightContainLocalReferenceText(text)) {
       return text;
     }
@@ -1106,37 +1129,7 @@
     return 'error';
   }
 
-  function removeEmptySummaryFields(value) {
-    var result = {};
-    var keys = Object.keys(value || {});
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      var item = value[key];
-      if (item === undefined || item === '' || item === null) {
-        continue;
-      }
-      if (Array.isArray(item) && item.length === 0) {
-        continue;
-      }
-      if (item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length === 0) {
-        continue;
-      }
-      result[key] = item;
-    }
-    return result;
-  }
 
-  function removeEmptyFields(value) {
-    var result = {};
-    var keys = Object.keys(value);
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      if (value[key] !== undefined && value[key] !== '') {
-        result[key] = value[key];
-      }
-    }
-    return result;
-  }
 
   // Welcome-panel + write-guard: the Recent-projects
   // dashboard variant calls `listRecentProjectsAcrossAccount` to get the
@@ -1328,7 +1321,7 @@
   }
   var hashString = StorageRunActions.hashString;
 
-  return {
+  return SharedSessionBridge.decorate({
     TARGET_SCHEMA_VERSION: TARGET_SCHEMA_VERSION,
     DB_NAME: DB_NAME,
     STORES: STORES,
@@ -1342,7 +1335,13 @@
     deleteByIndex: deleteByIndex,
     clearStore: clearStore,
     clearAllStores: clearAllStores,
+    clearAuxiliaryStores: function () { return composerDraftStore.clear(Object.keys(STORES).filter(name => name !== 'sessions')); },
+    readComposerAttachmentDraft: composerDraftStore.read,
+    writeComposerAttachmentDraft: composerDraftStore.write,
     buildSessionRecord: buildSessionRecord,
+    compactSessionBatchActions: compactSessionBatchActions,
+    projectRetentionWarnings: StorageRunActions.projectRetentionWarnings,
+    projectRetentionUpdates: StorageRunActions.projectRetentionUpdates,
     mergeSessionReviewState: StorageRunActions.mergeSessionReviewState,
     buildTurnRecord: buildTurnRecord,
     buildEventRecord: buildEventRecord,
@@ -1355,5 +1354,5 @@
     filterRecentProjectsAcrossAccount: filterRecentProjectsAcrossAccount,
     derivePrimaryStatusBadge: derivePrimaryStatusBadge,
     getAllSessions: getAllSessions
-  };
+  });
 });

package/extension/src/shared/storageMigration.js

@@ -8,6 +8,7 @@
   'use strict';
 
   var PREFS_KEY = 'codexOverleafPrefs';
+  var LEGACY_MIGRATION_PREFIX = 'codexOverleafLegacyPanelMigration:';
   var SESSION_TOMBSTONES_KEY = 'codexOverleafSessionTombstones';
   var SESSION_TOMBSTONE_ENTRY_PREFIX = 'codexOverleafSessionTombstone:v2:';
   var MAX_DELETED_SESSION_IDS_PER_PROJECT = 100;
@@ -50,6 +51,9 @@
   }
 
   function withProjectPreferenceLock(projectId, work) {
+    if (StorageDb.sharedSessionsEnabled?.()) {
+      return StorageDb.withSharedLock('preferences', { projectId: projectId }, work);
+    }
     var lockName = 'codex-overleaf-project-prefs:' + compactScopePart(projectId);
     var lockManager = typeof navigator !== 'undefined' && navigator && navigator.locks;
     if (lockManager && typeof lockManager.request === 'function') {
@@ -136,118 +140,77 @@
 
   function runMigrationIfNeeded(projectId, legacyStorageKey, accountScopeId) {
     projectId = normalizeProjectPrefKey(projectId);
-    var normalizedAccountScopeId = normalizeTextField(accountScopeId, PROJECT_PREF_KEY_MAX_CHARS);
-    if (!normalizedAccountScopeId || !projectId) {
-      return Promise.resolve({
-        prefs: normalizePrefs({}),
-        sessions: [],
-        activeSessionId: '',
-        migrated: false,
-        reason: 'account_scope_unavailable'
-      });
-    }
-    return withProjectPreferenceLock(projectId, function () {
-      return chrome.storage.local.get(null).then(function (stored) {
-        var claimed = claimLegacyProjectPreferences(
-          stored[PREFS_KEY] || {},
-          normalizedAccountScopeId,
-          projectId
-        );
-        var storedPrefs = claimed.prefs;
-        var persistClaim = claimed.changed
-          ? chrome.storage.local.set({ [PREFS_KEY]: storedPrefs })
-          : Promise.resolve();
-        return persistClaim.then(function () {
-          var prefs = buildProjectPreferenceView(
-            storedPrefs,
-            normalizedAccountScopeId,
-            projectId
-          );
-          var tombstones = collectSessionTombstones(stored);
-          var deletedSessionIds = getDeletedSessionIds(tombstones, projectId);
-          var schemaVersion = prefs.storageSchemaVersion || 0;
-
-          if (schemaVersion >= StorageDb.TARGET_SCHEMA_VERSION) {
-            var activeSessionByProject = prefs.activeSessionByProject || {};
-            var activeSessionId = activeSessionByProject[projectId] || '';
-            if (typeof StorageDb.claimSessionsForAccount !== 'function') {
-              return Promise.reject(Object.assign(
-                new Error('Atomic legacy-session claiming is unavailable.'),
-                { code: 'scoped_claim_unavailable' }
-              ));
-            }
-            return StorageDb.claimSessionsForAccount(
-              projectId,
-              normalizedAccountScopeId,
-              deletedSessionIds
-            ).then(function (visibleSessions) {
-              var visibleActiveSessionId = visibleSessions.some(function (session) {
-                return session && session.id === activeSessionId;
-              })
-                ? activeSessionId
-                : visibleSessions.length
-                  ? visibleSessions[visibleSessions.length - 1].id
-                  : '';
-              return {
-                prefs: prefs,
-                sessions: visibleSessions,
-                activeSessionId: visibleActiveSessionId,
-                migrated: false
-              };
-            });
-          }
-
-          // Migration v0 → v1
-          var legacyBlob = stored[legacyStorageKey] || {};
-          var legacySessions = Array.isArray(legacyBlob.sessions) ? legacyBlob.sessions : [];
-          var migratedSessions = [];
-
-          for (var i = 0; i < legacySessions.length; i++) {
-            var legacy = legacySessions[i];
-            if (!legacy || !legacy.id) { continue; }
-            if (deletedSessionIds.indexOf(legacy.id) !== -1) { continue; }
-            var record = StorageDb.buildSessionRecord(
-              buildLegacySessionRecordInput(projectId, legacyBlob, legacy, normalizedAccountScopeId)
-            );
-            migratedSessions.push(record);
-          }
-
-          var putPromise = migratedSessions.length
-            ? StorageDb.putRecords('sessions', migratedSessions)
-            : Promise.resolve([]);
-
-          return putPromise.then(function () {
-            var newPrefs = StorageDb.extractLightweightPrefs(legacyBlob, projectId);
-            newPrefs.activeSessionByProject = StorageDb.buildActiveSessionByProject(
-              {},
-              projectId,
-              legacyBlob.activeSessionId || (migratedSessions.length ? migratedSessions[migratedSessions.length - 1].id : '')
-            );
-            var mergedPrefs = mergeScopedProjectPreferences(
-              storedPrefs,
-              newPrefs,
-              normalizedAccountScopeId,
-              projectId
-            );
-            var prefsView = buildProjectPreferenceView(
-              mergedPrefs,
-              normalizedAccountScopeId,
-              projectId
-            );
-
-            return chrome.storage.local.set({ [PREFS_KEY]: mergedPrefs }).then(function () {
-              return chrome.storage.local.remove(legacyStorageKey).catch(function () {});
-            }).then(function () {
-              return {
-                prefs: prefsView,
-                sessions: migratedSessions,
-                activeSessionId: prefsView.activeSessionByProject[projectId] || '',
-                migrated: true
-              };
-            });
-          });
+    var account = normalizeTextField(accountScopeId, PROJECT_PREF_KEY_MAX_CHARS);
+    if (!account || !projectId) return Promise.resolve({ prefs: normalizePrefs({}), sessions: [],
+      activeSessionId: '', migrated: false, reason: 'account_scope_unavailable' });
+    return withProjectPreferenceLock(projectId, async function () {
+      var stored = await chrome.storage.local.get(null);
+      var claimed = claimLegacyProjectPreferences(stored[PREFS_KEY] || {}, account, projectId);
+      var storedPrefs = claimed.prefs;
+      if (claimed.changed) await chrome.storage.local.set({ [PREFS_KEY]: storedPrefs });
+      var prefs = buildProjectPreferenceView(storedPrefs, account, projectId);
+      var deleted = getDeletedSessionIds(collectSessionTombstones(stored), projectId);
+      var markerKey = LEGACY_MIGRATION_PREFIX + encodeURIComponent(String(legacyStorageKey || ''));
+      var marker = stored[markerKey];
+      var legacyBlob = stored[legacyStorageKey];
+      var hasLegacy = Boolean(legacyBlob && typeof legacyBlob === 'object' && !Array.isArray(legacyBlob));
+      var schemaCurrent = (prefs.storageSchemaVersion || 0) >= StorageDb.TARGET_SCHEMA_VERSION;
+      if (marker && (marker.projectId !== projectId || marker.sourceKey !== legacyStorageKey || !marker.accountScopeId)) {
+        throw Object.assign(new Error('The legacy history source has a conflicting migration identity.'), { code: 'legacy_migration_scope_conflict' });
+      }
+      if (typeof StorageDb.claimSessionsForAccount !== 'function') {
+        throw Object.assign(new Error('Atomic legacy-session claiming is unavailable.'), { code: 'scoped_claim_unavailable' });
+      }
+      var visible = await StorageDb.claimSessionsForAccount(projectId, account, deleted);
+      function result(currentPrefs, sessions, migrated) {
+        var wanted = currentPrefs.activeSessionByProject?.[projectId] || '';
+        return { prefs: currentPrefs, sessions: sessions,
+          activeSessionId: sessions.some(session => session.id === wanted) ? wanted : sessions.at(-1)?.id || '',
+          migrated: migrated };
+      }
+      if ((schemaCurrent && !hasLegacy) || marker?.complete || (marker && marker.accountScopeId !== account)) {
+        return result(prefs, visible, false);
+      }
+      legacyBlob = hasLegacy ? legacyBlob : {};
+      var legacySessions = Array.isArray(legacyBlob.sessions) ? legacyBlob.sessions : [];
+      var owners = new Set([legacyBlob.accountScopeId, legacyBlob.__codexOverleafFallbackAccountScopeId,
+        ...legacySessions.map(session => session?.accountScopeId)].filter(value => typeof value === 'string' && value));
+      if ([...owners].some(owner => owner !== account)) return result(prefs, visible, false);
+      // The shared preferences lock serializes this source claim across accounts.
+      // Keep it after a write failure; only its owner can finish the import.
+      if (hasLegacy && !marker) {
+        marker = { sourceKey: legacyStorageKey, projectId: projectId, accountScopeId: account, complete: false };
+        await chrome.storage.local.set({ [markerKey]: marker });
+      }
+      var existingIds = new Set(visible.map(session => session.id));
+      var incoming = legacySessions.filter(session => session?.id && !deleted.includes(session.id) && !existingIds.has(session.id))
+        .map(session => StorageDb.buildSessionRecord(buildLegacySessionRecordInput(projectId, legacyBlob, session, account)));
+      var written = incoming.length ? await StorageDb.putRecords('sessions', incoming) : [];
+      if (incoming.length && (!Array.isArray(written) || incoming.some(session => !written.some(record =>
+        record.id === session.id && record.accountScopeId === account && record.projectId === projectId)))) {
+        throw Object.assign(new Error('Legacy history was not confirmed in the main session store.'), { code: 'legacy_migration_not_persisted' });
+      }
+      var sessions = [...visible, ...written];
+      var newPrefs = StorageDb.extractLightweightPrefs(legacyBlob, projectId);
+      if (schemaCurrent) {
+        // A later project's import must not reset current global preferences.
+        var legacyPrefs = newPrefs;
+        newPrefs = Object.assign({}, legacyPrefs, prefs);
+        PROJECT_SCOPED_PREF_MAPS.forEach(function (name) {
+          newPrefs[name] = Object.assign({}, legacyPrefs[name] || {}, prefs[name] || {});
         });
-      });
+      }
+      var currentActive = prefs.activeSessionByProject?.[projectId];
+      var activeId = sessions.some(session => session.id === currentActive) ? currentActive
+        : legacyBlob.activeSessionId || sessions.at(-1)?.id || '';
+      newPrefs.activeSessionByProject = StorageDb.buildActiveSessionByProject({}, projectId, activeId);
+      var mergedPrefs = mergeScopedProjectPreferences(storedPrefs, newPrefs, account, projectId);
+      await chrome.storage.local.set({ [PREFS_KEY]: mergedPrefs });
+      // Completion is per source and owner, independent of the global schema.
+      // A failed cleanup cannot replay old content or transfer it to another account.
+      if (hasLegacy) await chrome.storage.local.set({ [markerKey]: { ...marker, complete: true } });
+      await chrome.storage.local.remove(legacyStorageKey).catch(function () {});
+      return result(buildProjectPreferenceView(mergedPrefs, account, projectId), sessions, true);
     });
   }