codex-overleaf-link 2.2.1 → 2.3.1

package/extension/src/content/providerSettingsDialog.js

@@ -5,11 +5,16 @@
   const CODEX_BLOSSOM_PATH = 'M13.798 23.976a5.7 5.7 0 0 1-2.26-.456 6.1 6.1 0 0 1-1.903-1.27 5.7 5.7 0 0 1-1.88.311 5.75 5.75 0 0 1-2.95-.79 6.2 6.2 0 0 1-2.188-2.159q-.81-1.366-.809-3.045 0-.695.19-1.51a6.4 6.4 0 0 1-1.475-2.038A5.95 5.95 0 0 1 0 10.573Q0 9.278.547 8.08q.547-1.2 1.523-2.062a5.5 5.5 0 0 1 2.307-1.223A5.7 5.7 0 0 1 5.472 2.35 6.1 6.1 0 0 1 7.565.623 5.8 5.8 0 0 1 10.206 0q1.19 0 2.26.456a6.1 6.1 0 0 1 1.903 1.27 5.7 5.7 0 0 1 1.88-.311q1.594 0 2.95.79a6 6 0 0 1 2.165 2.159q.832 1.366.832 3.045 0 .695-.19 1.51a6.3 6.3 0 0 1 1.475 2.062q.523 1.15.523 2.422a5.9 5.9 0 0 1-.547 2.493q-.547 1.2-1.546 2.086a5.4 5.4 0 0 1-2.284 1.199 5.56 5.56 0 0 1-1.118 2.445 5.9 5.9 0 0 1-2.07 1.727 5.8 5.8 0 0 1-2.64.623m-5.876-2.997q1.19 0 2.07-.504l4.472-2.589a.53.53 0 0 0 .238-.455v-2.062L8.945 18.7a.96.96 0 0 1-1.047 0l-4.496-2.613a.7.7 0 0 1-.024.168v.287q0 1.224.571 2.254a4.24 4.24 0 0 0 1.642 1.583q1.047.6 2.331.599m.238-3.908a.6.6 0 0 0 .262.072q.118 0 .238-.072l1.784-1.031-5.734-3.357q-.522-.312-.523-.935V6.545a4.3 4.3 0 0 0-1.903 1.63 4.25 4.25 0 0 0-.714 2.398q0 1.176.595 2.254.594 1.08 1.546 1.63zm5.638 5.323q1.26 0 2.284-.576a4.3 4.3 0 0 0 1.618-1.582q.595-1.008.595-2.254v-5.179a.47.47 0 0 0-.238-.431l-1.808-1.055v6.689q0 .624-.524.935l-4.496 2.613a4.3 4.3 0 0 0 2.57.84m.904-8.776v-3.26l-2.688-1.535-2.712 1.535v3.26l2.712 1.535zM7.756 5.97q0-.623.523-.935l4.496-2.613a4.3 4.3 0 0 0-2.569-.84q-1.26 0-2.284.576A4.3 4.3 0 0 0 6.304 3.74q-.57 1.008-.57 2.254v5.155q0 .287.237.455l1.785 1.055zM19.84 17.43a4.16 4.16 0 0 0 1.88-1.63 4.33 4.33 0 0 0 .713-2.397q0-1.176-.595-2.254-.594-1.08-1.546-1.63l-4.449-2.59q-.143-.096-.261-.072a.46.46 0 0 0-.238.072L13.56 7.936l5.758 3.38a.9.9 0 0 1 .38.384q.143.216.143.528zM15.059 5.25q.524-.335 1.047 0l4.52 2.662V7.48q0-1.15-.57-2.181A4.14 4.14 0 0 0 18.46 3.62q-1.023-.623-2.379-.623-1.19 0-2.07.503L9.54 6.09a.53.53 0 0 0-.238.455v2.062z';
 
   function create(options = {}) {
+    const Profiles = options.ProviderProfiles;
+    if (!Profiles) {
+      throw new Error('Provider settings dialog requires provider profiles.');
+    }
     const instance = {
+      Profiles,
       document: options.document || document,
       tx: options.tx || ((english) => english),
       callbacks: options.callbacks || {},
-      catalog: window.CodexOverleafProviderProfiles.normalizeCatalog({}),
+      catalog: Profiles.normalizeCatalog({}),
       selectedId: 'builtin',
       draft: null,
       dirty: false,
@@ -108,7 +113,7 @@
   }
 
   function setCatalog(instance, catalog, selectedId) {
-    instance.catalog = window.CodexOverleafProviderProfiles.normalizeCatalog(catalog || {});
+    instance.catalog = instance.Profiles.normalizeCatalog(catalog || {});
     const nextId = selectedId || (
       instance.catalog.providers.some(provider => provider.id === instance.selectedId)
         ? instance.selectedId
@@ -151,8 +156,8 @@
       '第三方实验性'
     );
     instance.root.querySelector('[data-provider-dialog-subtitle]').textContent = tx(
-      'Configure experimental third-party integrations used by future Codex runs. Compatibility varies by provider and gateway.',
-      '配置后续 Codex 任务使用的实验性第三方集成；兼容性取决于具体模型服务与网关。'
+      "Configure experimental third-party integrations used by this project's future Codex runs. Compatibility varies by provider and gateway.",
+      '配置当前项目后续 Codex 任务使用的实验性第三方集成；兼容性取决于具体模型服务与网关。'
     );
     renderProviderList(instance);
     renderDetail(instance);
@@ -165,10 +170,10 @@
     const list = instance.root.querySelector('[data-provider-list]');
     const rows = instance.catalog.providers.map(provider => {
       const selected = provider.id === instance.selectedId;
-      const active = provider.id === instance.catalog.activeProviderId;
+      const active = provider.id === getCurrentProjectProviderId(instance);
       const diagnosticCount = Object.values(provider.modelDiagnostics || {}).filter(item => item.status === 'tested').length;
       const status = active
-        ? tx('Active', '使用中')
+        ? tx('Current project', '当前项目')
         : diagnosticCount
           ? tx(`Tested ${diagnosticCount}/${Math.max(1, provider.models.length)}`, `已测试 ${diagnosticCount}/${Math.max(1, provider.models.length)}`)
           : provider.kind === 'custom'
@@ -207,7 +212,7 @@
       .map(model => model.id)
       .filter(id => id !== draft.defaultModelId)
       .join('\n');
-    const active = provider.id && provider.id === instance.catalog.activeProviderId;
+    const active = provider.id && provider.id === getCurrentProjectProviderId(instance);
     const acceptedHost = getEndpointHost(draft.baseUrl);
     const secretSavedAt = formatSecretSavedAt(instance, provider.secretUpdatedAt);
     const disclosureSatisfied = Boolean(
@@ -219,9 +224,9 @@
       <div class="codex-provider-detail-titleline">
         <div>
           <h3>${escapeHtml(draft.name || tx('Custom provider', '自定义模型服务'))}</h3>
-          <p>${escapeHtml(active ? tx('Used by new Codex runs', '新 Codex 任务将使用此服务') : tx('Saved provider profile', '已保存的模型服务配置'))}</p>
+          <p>${escapeHtml(active ? tx('Used by new runs in this project', '当前项目的新任务将使用此服务') : tx('Saved provider profile', '已保存的模型服务配置'))}</p>
         </div>
-        ${active ? `<span class="codex-provider-active-badge">${escapeHtml(tx('Active', '使用中'))}</span>` : ''}
+        ${active ? `<span class="codex-provider-active-badge">${escapeHtml(tx('Current project', '当前项目'))}</span>` : ''}
       </div>
       <div class="codex-provider-form-grid">
         <label class="codex-provider-field">
@@ -440,7 +445,7 @@
 
   function renderBuiltinDetail(instance, detail) {
     const tx = instance.tx;
-    const active = instance.catalog.activeProviderId === 'builtin';
+    const active = getCurrentProjectProviderId(instance) === 'builtin';
     detail.innerHTML = `
       <div class="codex-provider-builtin">
         <span class="codex-provider-builtin-mark" aria-hidden="true">
@@ -452,12 +457,19 @@
           '使用本地 Codex CLI 管理的身份验证、模型目录和服务配置。'
         ))}</p>
         ${active
-          ? `<span class="codex-provider-active-badge">${escapeHtml(tx('Active', '使用中'))}</span>`
-          : `<button type="button" class="codex-provider-primary-button" data-provider-action="activate-builtin">${escapeHtml(tx('Use built-in Codex', '使用内置 Codex'))}</button>`}
+          ? `<span class="codex-provider-active-badge">${escapeHtml(tx('Current project', '当前项目'))}</span>`
+          : `<button type="button" class="codex-provider-primary-button" data-provider-action="activate-builtin">${escapeHtml(tx('Use for this project', '用于当前项目'))}</button>`}
       </div>
     `;
   }
 
+  function getCurrentProjectProviderId(instance) {
+    const providerId = instance.callbacks.getCurrentProjectProviderId?.();
+    return typeof providerId === 'string' && providerId.trim()
+      ? providerId.trim()
+      : 'builtin';
+  }
+
   function renderFooter(instance) {
     const actions = instance.root.querySelector('[data-provider-footer-actions]');
     const provider = getSelectedProvider(instance);
@@ -466,7 +478,7 @@
       actions.innerHTML = `<button type="button" class="codex-provider-secondary-button" data-provider-action="close">${escapeHtml(tx('Close', '关闭'))}</button>`;
       return;
     }
-    const active = provider.id && provider.id === instance.catalog.activeProviderId;
+    const active = provider.id && provider.id === getCurrentProjectProviderId(instance);
     const isNew = !provider.id;
     const destinationChanged = active && getCurrentBaseUrl(instance) !== provider.endpointDisclosureBaseUrl;
     const actionState = getFooterActionState({
@@ -485,8 +497,8 @@
       <span class="codex-provider-footer-spacer"></span>
       <button type="button" class="codex-provider-secondary-button" data-provider-action="close">${escapeHtml(tx('Cancel', '取消'))}</button>
       ${actionState.showSave ? `<button type="button" class="codex-provider-secondary-button" data-provider-action="save"${saveDisabled}>${escapeHtml(tx('Save', '保存'))}</button>` : ''}
-      ${actionState.showSaveAndUse ? `<button type="button" class="codex-provider-primary-button" data-provider-action="save-use"${saveDisabled}>${escapeHtml(tx('Save and use', '保存并使用'))}</button>` : ''}
-      ${actionState.showUse ? `<button type="button" class="codex-provider-primary-button" data-provider-action="use"${useDisabled}>${escapeHtml(tx('Use', '使用'))}</button>` : ''}
+      ${actionState.showSaveAndUse ? `<button type="button" class="codex-provider-primary-button" data-provider-action="save-use"${saveDisabled}>${escapeHtml(tx('Save and use for this project', '保存并用于当前项目'))}</button>` : ''}
+      ${actionState.showUse ? `<button type="button" class="codex-provider-primary-button" data-provider-action="use"${useDisabled}>${escapeHtml(tx('Use for this project', '用于当前项目'))}</button>` : ''}
     `;
   }
 
@@ -677,7 +689,7 @@
     }
     instance.selectedId = id;
     instance.draft = id === '__new__'
-      ? window.CodexOverleafProviderProfiles.buildEmptyDraft()
+      ? instance.Profiles.buildEmptyDraft()
       : null;
     instance.dirty = false;
     delete instance.root.dataset.dirty;
@@ -689,7 +701,7 @@
   }
 
   function readContext(instance) {
-    const provider = getSelectedProvider(instance) || window.CodexOverleafProviderProfiles.buildEmptyDraft();
+    const provider = getSelectedProvider(instance) || instance.Profiles.buildEmptyDraft();
     const get = name => instance.root.querySelector(`[data-provider-field="${name}"]`);
     const defaultModelId = String(get('defaultModelId')?.value || '').trim();
     const modelIds = [defaultModelId, ...String(get('additionalModels')?.value || '').split(/\r?\n/)]
@@ -759,7 +771,7 @@
 
   function getSelectedProvider(instance) {
     if (instance.selectedId === '__new__') {
-      return instance.draft || window.CodexOverleafProviderProfiles.buildEmptyDraft();
+      return instance.draft || instance.Profiles.buildEmptyDraft();
     }
     return instance.catalog.providers.find(provider => provider.id === instance.selectedId)
       || instance.catalog.providers.find(provider => provider.id === 'builtin');

package/extension/src/content/recentProjects.js

@@ -17,11 +17,13 @@
       sendBackgroundNative,
       PANEL_STATE_BASE_KEY,
       PROJECT_EDITOR_RESERVED_IDS,
-      STATUS_BADGE_CLASS
+      STATUS_BADGE_CLASS,
+      ProjectSessionCleanup, SessionPersistence, SessionState, StorageDb, StorageKeys, StorageMigration
     } = deps;
-    const projectSessionCleanup = window.CodexOverleafProjectSessionCleanup.create({
+    const projectSessionCleanup = ProjectSessionCleanup.create({
       tr, getAccountScopeId: getCachedAccountScopeId, showPluginConfirm, showPluginToast,
-      sendBackgroundNative, mutateProjectPanelState, renderRecentProjectsVariant
+      sendBackgroundNative, mutateProjectPanelState, renderRecentProjectsVariant,
+      SessionState, StorageDb, StorageMigration
     });
 
   // chrome.storage.local cache key (spec §5.6.3). The cache is keyed by
@@ -496,7 +498,6 @@
   }
 
   function sessionRecordDisplayTitle(record) {
-    var SessionState = window.CodexOverleafSessionState;
     if (record && typeof record.title === 'string' && record.title.trim()) {
       return record.title.trim();
     }
@@ -505,12 +506,11 @@
   }
 
   async function loadProjectSessionRecords(projectId) {
-    var StorageDb = window.CodexOverleafStorageDb;
     if (!StorageDb) {
       return [];
     }
     var records = await StorageDb.getAllByIndex('sessions', 'projectId', projectId);
-    var Persistence = window.CodexOverleafSessionPersistence;
+    var Persistence = SessionPersistence;
     var deletedIds = await Persistence.getDeletedSessionIds(projectId);
     var scope = getCachedAccountScopeId();
     return (records || [])
@@ -521,7 +521,6 @@
   }
 
   async function renderProjectSessions(sessionsEl, projectId) {
-    var StorageDb = window.CodexOverleafStorageDb;
     sessionsEl.innerHTML = '';
     var sessionsLoading = document.createElement('div');
     sessionsLoading.className = 'recent-projects-loading';
@@ -544,7 +543,6 @@
   }
 
   function renderProjectSessionRow(sessionsEl, projectId, record) {
-    var StorageDb = window.CodexOverleafStorageDb;
     var running = Boolean(StorageDb)
       && settleDashboardRunStatus(StorageDb.derivePrimaryStatusBadge(record), record.updatedAt || record.lastActivityAt) === 'running';
     var row = document.createElement('div');
@@ -614,17 +612,21 @@
   }
 
   async function activateSessionAndOpenProject(projectId, record) {
-    var Migration = window.CodexOverleafStorageMigration;
+    var Migration = StorageMigration;
     try {
       if (Migration && Migration.loadPrefs && Migration.savePrefs) {
-        var prefs = await Migration.loadPrefs();
+        var accountScopeId = getCachedAccountScopeId();
+        if (!accountScopeId) {
+          throw new Error('Account scope is unavailable.');
+        }
+        var prefs = await Migration.loadPrefs(accountScopeId, projectId);
         prefs = prefs && typeof prefs === 'object' ? prefs : {};
         var map = prefs.activeSessionByProject && typeof prefs.activeSessionByProject === 'object'
           ? prefs.activeSessionByProject
           : {};
         map[projectId] = record.id;
         prefs.activeSessionByProject = map;
-        await Migration.savePrefs(prefs);
+        await Migration.savePrefs(prefs, accountScopeId, projectId);
       }
     } catch (_error) { /* fall through: opening the project still works */ }
     openProjectFromRow(projectId);
@@ -636,7 +638,6 @@
   // panel-state blob is deliberately left alone — an empty projectId would
   // map getProjectStorageKey onto the global legacy key.
   async function cleanupDeadProjectEntry(projectId) {
-    var StorageDb = window.CodexOverleafStorageDb;
     if (!StorageDb) {
       return;
     }
@@ -684,7 +685,6 @@
   }
 
   function projectPanelStateKey(projectId) {
-    var StorageKeys = window.CodexOverleafStorageKeys;
     return StorageKeys.getProjectStorageKey(PANEL_STATE_BASE_KEY, 'https://www.overleaf.com/project/' + projectId);
   }
 
@@ -694,7 +694,6 @@
   // NOTE: if the project is open in another tab, that tab's in-memory state
   // wins on its next save; the IndexedDB record mutation below still holds.
   async function mutateProjectPanelState(projectId, mutate) {
-    var SessionState = window.CodexOverleafSessionState;
     var key = projectPanelStateKey(projectId);
     var stored = await chrome.storage.local.get(key);
     var blob = stored && stored[key];
@@ -709,8 +708,6 @@
   }
 
   async function deleteDashboardSession(sessionsEl, projectId, record) {
-    var StorageDb = window.CodexOverleafStorageDb;
-    var SessionState = window.CodexOverleafSessionState;
     // v1.8.1 P1b: ANY record whose stored badge is 'running' gets the
     // stronger confirm — even one the 30-minute heuristic settled to
     // interrupted. Activity timestamps are only bumped once a minute during
@@ -731,7 +728,7 @@
     if (!approved) {
       return;
     }
-    await window.CodexOverleafSessionPersistence.addTombstones(projectId, [record.id]);
+    await SessionPersistence.addTombstones(projectId, [record.id]);
     try {
       await mutateProjectPanelState(projectId, function (state) {
         return SessionState.deleteSession(state, record.id);
@@ -773,8 +770,6 @@
   }
 
   function beginDashboardSessionRename(sessionsEl, projectId, record, row, titleEl) {
-    var SessionState = window.CodexOverleafSessionState;
-    var StorageDb = window.CodexOverleafStorageDb;
     if (row.querySelector('input')) {
       return;
     }
@@ -816,8 +811,6 @@
   }
 
   async function commitDashboardSessionRename(sessionsEl, projectId, record, rawTitle) {
-    var SessionState = window.CodexOverleafSessionState;
-    var StorageDb = window.CodexOverleafStorageDb;
     if (!SessionState) {
       return;
     }
@@ -963,9 +956,8 @@
     // there really is more than one page of projects.
     var pageLimit = 10;
     try {
-      var StorageDb = window.CodexOverleafStorageDb;
       if (StorageDb) {
-        var deletedSessionIdsByProject = await window.CodexOverleafSessionPersistence.loadTombstones();
+        var deletedSessionIdsByProject = await SessionPersistence.loadTombstones();
         rows = await StorageDb.listRecentProjectsAcrossAccount({
           accountScopeId: accountScopeId,
           limit: showAll ? 500 : pageLimit + 1,

package/extension/src/content/runGuidanceController.js

@@ -47,7 +47,7 @@
     }
 
     function appendToView(event, view) {
-      const text = window.CodexOverleafRunGuidanceView?.getGuidanceText(event);
+      const text = deps.RunGuidanceView?.getGuidanceText(event);
       if (!text) return false;
       const guidance = view.guidance || view.root?.querySelector('[data-run-guidance]');
       const target = view.terminalStatus ? guidance : view.events;

package/extension/src/content/runQueueScheduler.js

@@ -2,7 +2,7 @@
   if (typeof module === 'object' && module.exports) {
     module.exports = factory(require('../shared/runInputQueue'));
   } else {
-    root.CodexOverleafRunQueueScheduler = factory(root.CodexOverleafRunInputQueue);
+    root.CodexOverleafModuleRegistry.define('RunQueueScheduler', ['RunInputQueue'], factory);
   }
 })(typeof window !== 'undefined' ? window : globalThis, function runQueueSchedulerFactory(Queue) {
   'use strict';
@@ -19,18 +19,49 @@
     }
 
     async function afterSettlement({ sessionId, status, queueItemId = '', continueQueue = false } = {}) {
-      let queue = options.getQueue?.(sessionId) || [];
-      if (status === 'completed') {
-        queue = dequeue(queue, queueItemId, { sessionId, reason: 'completed' });
-      } else if (continueQueue) {
-        queue = dequeue(queue, queueItemId, { sessionId, reason: 'continue_queue' });
-      } else if (queue.length) {
-        queue = Queue.pauseAll(queue, status || 'run_did_not_complete');
+      const originalQueue = options.getQueue?.(sessionId) || [];
+      const shouldContinue = status === 'completed' || continueQueue;
+      const shouldRemove = Boolean(queueItemId && shouldContinue);
+      const claimedItem = shouldRemove
+        ? originalQueue.find(item => item?.id === queueItemId)
+        : null;
+      if (shouldRemove) {
+        await options.persist?.({
+          queueMutation: {
+            type: 'remove',
+            sessionId,
+            itemId: queueItemId,
+            claimToken: claimedItem?.claimToken
+          }
+        });
+        const latestQueue = options.getQueue?.(sessionId) || originalQueue;
+        options.setQueue?.(
+          sessionId,
+          dequeue(latestQueue, queueItemId, {
+            sessionId,
+            reason: status === 'completed' ? 'completed' : 'continue_queue'
+          })
+        );
+      } else if (!shouldContinue) {
+        const paused = originalQueue.length
+          ? Queue.pauseAll(originalQueue, status || 'run_did_not_complete')
+          : originalQueue;
+        options.setQueue?.(sessionId, paused);
+        try {
+          await options.persist?.({
+            queueMutation: { type: 'transition', sessionId }
+          });
+        } catch (error) {
+          const latestQueue = options.getQueue?.(sessionId) || paused;
+          options.setQueue?.(
+            sessionId,
+            Queue.pauseAll(latestQueue, status || 'run_did_not_complete')
+          );
+          throw error;
+        }
       }
-      options.setQueue?.(sessionId, queue);
-      await options.persist?.();
       options.onChange?.(sessionId);
-      if (status === 'completed' || continueQueue) {
+      if (shouldContinue) {
         scheduleOne(sessionId);
       }
     }
@@ -39,15 +70,33 @@
       if (scheduling || options.isRunning?.() || options.canStart?.(sessionId) === false) {
         return false;
       }
-      const claimed = Queue.claimNext(options.getQueue?.(sessionId) || [], {
-        randomUUID: options.randomUUID
-      });
-      if (!claimed.ok) {
+      const initialQueue = options.getQueue?.(sessionId) || [];
+      if (!initialQueue.some(item => item?.status === 'queued')) {
         return false;
       }
       scheduling = true;
-      options.setQueue?.(sessionId, claimed.queue);
-      Promise.resolve(options.persist?.())
+      let claimed = null;
+      Promise.resolve(options.prepareClaim?.(sessionId))
+        .then(() => {
+          claimed = Queue.claimNext(options.getQueue?.(sessionId) || initialQueue, {
+            randomUUID: options.randomUUID,
+            resolveExecutionSnapshot: options.resolveExecutionSnapshot
+          });
+          if (!claimed.ok) {
+            const error = new Error(claimed.error?.message || claimed.error?.code || 'queue_claim_failed');
+            error.code = claimed.error?.code || 'queue_claim_failed';
+            throw error;
+          }
+          options.setQueue?.(sessionId, claimed.queue);
+          return options.persist?.({
+            queueMutation: {
+              type: 'claim',
+              sessionId,
+              itemId: claimed.item.id,
+              claimToken: claimed.item.claimToken
+            }
+          });
+        })
         .then(() => {
           options.onChange?.(sessionId);
           scheduling = false;
@@ -55,27 +104,64 @@
         })
         .catch(error => {
           scheduling = false;
-          const paused = Queue.pauseAll(options.getQueue?.(sessionId) || claimed.queue, error?.code || 'start_failed');
+          const paused = Queue.pauseAll(
+            options.getQueue?.(sessionId) || claimed?.queue || initialQueue,
+            error?.code || 'start_failed'
+          );
           options.setQueue?.(sessionId, paused);
           options.onChange?.(sessionId);
-          return options.persist?.();
+          return Promise.resolve(options.persist?.({
+            queueMutation: claimed?.item?.id
+              ? {
+                type: 'release',
+                sessionId,
+                itemId: claimed.item.id,
+                claimToken: claimed.item.claimToken
+              }
+              : { type: 'transition', sessionId }
+          })).catch(() => undefined);
         });
       return true;
     }
 
     async function markExecuting(sessionId, itemId, _runId) {
       const queue = options.getQueue?.(sessionId) || [];
+      const item = queue.find(entry => entry?.id === itemId);
+      try {
+        await options.persist?.({
+          queueMutation: { type: 'remove', sessionId, itemId, claimToken: item?.claimToken }
+        });
+      } catch (error) {
+        const latestQueue = options.getQueue?.(sessionId) || queue;
+        options.setQueue?.(
+          sessionId,
+          Queue.pauseAll(latestQueue, error?.code || 'queue_promotion_persistence_failed')
+        );
+        options.onChange?.(sessionId);
+        try {
+          await options.persist?.({
+            queueMutation: { type: 'restore', sessionId, itemId, claimToken: item?.claimToken }
+          });
+        } catch (recoveryError) {
+          if (error && typeof error === 'object') {
+            error.persistenceRecoveryError = recoveryError?.message || String(recoveryError);
+          }
+        }
+        throw error;
+      }
+      const latestQueue = options.getQueue?.(sessionId) || queue;
       options.setQueue?.(
         sessionId,
-        dequeue(queue, itemId, { sessionId, runId: _runId, reason: 'executing' })
+        dequeue(latestQueue, itemId, { sessionId, runId: _runId, reason: 'executing' })
       );
-      await options.persist?.();
       options.onChange?.(sessionId);
     }
 
     async function resume(sessionId) {
       options.setQueue?.(sessionId, Queue.resumeAll(options.getQueue?.(sessionId) || []));
-      await options.persist?.();
+      await options.persist?.({
+        queueMutation: { type: 'transition', sessionId }
+      });
       options.onChange?.(sessionId);
       scheduleOne(sessionId);
     }
@@ -88,7 +174,7 @@
     const scheduler = create({
       getQueue: sessionId => options.getSession?.(sessionId)?.pendingInputs || [],
       setQueue: (sessionId, pendingInputs) => options.setQueue?.(sessionId, pendingInputs),
-      persist: () => options.save?.(),
+      persist: persistenceOptions => options.save?.(persistenceOptions),
       isRunning: () => Boolean(options.getCurrentRun?.()),
       canStart: sessionId => options.canStart?.(sessionId) !== false,
       start: (item, sessionId) => startQueuedInput(item, sessionId),
@@ -97,6 +183,8 @@
         sessionId: context.sessionId,
         recordId: item.sourceRunId || ''
       }),
+      prepareClaim: options.prepareClaim,
+      resolveExecutionSnapshot: options.resolveExecutionSnapshot,
       randomUUID: options.randomUUID
     });
 
@@ -128,7 +216,9 @@
       // active turn, or until the scheduler promotes it to the next run.
       options.clearTask?.();
       render();
-      options.saveSoon?.();
+      options.saveSoon?.({
+        queueMutation: { type: 'enqueue', sessionId: session.id, itemId: result.item.id }
+      });
     }
 
     async function guide(itemId) {
@@ -142,7 +232,9 @@
       }
       options.setQueue?.(session.id, Queue.markSteering(session.pendingInputs, itemId));
       render();
-      await options.save?.();
+      await options.save?.({
+        queueMutation: { type: 'transition', sessionId: session.id, itemId }
+      });
       try {
         const response = await options.sendSteer?.({
           requestId: run.nativeRequestId,
@@ -174,7 +266,11 @@
           options.toast?.(response?.error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
         }
         render();
-        await options.save?.();
+        await options.save?.({
+          queueMutation: response?.ok
+            ? { type: 'remove', sessionId: session.id, itemId }
+            : { type: 'transition', sessionId: session.id, itemId }
+        });
       } catch (error) {
         const latest = options.getSession?.(session.id);
         const paused = (latest?.pendingInputs || []).map(entry => entry.id === itemId
@@ -183,7 +279,9 @@
         options.setQueue?.(session.id, Queue.normalizeQueue(paused));
         options.toast?.(error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
         render();
-        await options.save?.();
+        await options.save?.({
+          queueMutation: { type: 'transition', sessionId: session.id, itemId }
+        });
       }
     }
 
@@ -201,7 +299,9 @@
       }
       options.setQueue?.(session.id, Queue.remove(session.pendingInputs || [], itemId));
       render();
-      options.saveSoon?.();
+      options.saveSoon?.({
+        queueMutation: { type: 'remove', sessionId: session.id, itemId }
+      });
     }
 
     function resume() {
@@ -242,7 +342,7 @@
         error.code = 'queue_session_not_active';
         throw error;
       }
-      options.applyQueuedInput?.(item);
+      await options.applyQueuedInput?.(item);
       await options.run?.(item);
     }
 

package/extension/src/content/runSettlementPersistence.js

@@ -0,0 +1,51 @@
+(function initCodexOverleafRunSettlementPersistence(root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafRunSettlementPersistence = api;
+})(typeof window !== 'undefined' ? window : globalThis, function runSettlementPersistenceFactory() {
+  'use strict';
+
+  function create(options = {}) {
+    const Settlement = options.writebackSettlement;
+
+    function findTarget(recordId, sessionId) {
+      return typeof options.findRunRecord === 'function'
+        ? options.findRunRecord(recordId, sessionId)
+        : null;
+    }
+
+    function applyToCurrentRun(settlement) {
+      const view = options.getCurrentRunView?.();
+      if (!settlement || !view?.recordId) return;
+      const record = findTarget(view.recordId, view.sessionId);
+      if (!record) return;
+      Object.assign(record, Settlement.applySettlementTransition(record, settlement));
+    }
+
+    function settleMirrorRefresh(result = {}) {
+      const record = findTarget(result.recordId, result.sessionId);
+      if (!record) return;
+      if (result.runProjectId && result.runProjectId !== options.getCurrentProjectId?.()) return;
+      const existing = record.settlement && typeof record.settlement === 'object'
+        ? record.settlement
+        : record.settlementFacts;
+      if (!existing || typeof existing !== 'object') return;
+      record.settlement = Settlement.compactSettlementFacts({
+        ...existing,
+        evidence: {
+          ...(existing.evidence || {}),
+          mirrored: result.state
+        }
+      });
+      delete record.settlementFacts;
+      options.saveStateSoon?.();
+    }
+
+    return Object.freeze({
+      applyToCurrentRun,
+      settleMirrorRefresh
+    });
+  }
+
+  return Object.freeze({ create });
+});