codex-overleaf-link 2.4.1 → 2.5.0

package/extension/src/content/trackedChangeCaptureController.js

@@ -10,8 +10,10 @@
     const cancelTimer = deps.clearTimeout || clearTimeout;
     let timer = null, busy = false, disposed = false;
     const runs = () => deps.getRuns() || [];
+    const mergedRecovery = capture => capture?.source === 'native'
+      && capture.state === 'needs_review' && ['capture_timeout', 'capture_expired'].includes(capture.reason);
     const pending = run => Array.isArray(run.trackedChangeCaptures)
-      && run.trackedChangeCaptures.some(capture => capture.state === 'pending');
+      && run.trackedChangeCaptures.some(capture => capture.state === 'pending' || mergedRecovery(capture));
     const terminal = run => ['accepted', 'rejected'].includes(run.trackedChangeStatus)
       || run.undoStatus === 'applied' || run.forkSnapshot === true;
     function buildPostFiles(run) {
@@ -78,9 +80,10 @@
           const postFiles = buildPostFiles(run);
           for (let i = 0; i < captures.length; i++) {
             const capture = captures[i];
-            if (capture.state !== 'pending') continue;
+            const recoverMerged = mergedRecovery(capture);
+            if (capture.state !== 'pending' && !recoverMerged) continue;
             const expected = postFiles.find(file => file.path === capture.path);
-            if (newer || !expected || now() >= capture.expiresAt || run.status === 'cancelled') {
+            if (newer || !expected || (!recoverMerged && now() >= capture.expiresAt) || run.status === 'cancelled') {
               capture.state = 'needs_review';
               capture.reason = newer ? 'capture_superseded' : !expected ? 'capture_baseline_missing'
                 : run.status === 'cancelled' ? 'capture_cancelled' : 'capture_expired';
@@ -129,6 +132,7 @@
           if (changed) {
             run.trackedChangeCaptures = captures;
             await deps.persist();
+            deps.refresh?.(run);
             if (!pending(run)) deps.notify?.(run, 'needs_review', {
               reasons: captures.filter(capture => capture.state !== 'observed').map(capture => capture.reason)
             });

package/extension/src/content/updateNotice.js

@@ -11,6 +11,8 @@
   let currentView = null;
   let mountedPanel = null;
   let actionInFlight = false;
+  let cancellationInFlight = false;
+  let actionSequence = 0;
   let listenerInstalled = false;
   let getLocale = () => '';
   let settingsRoot = null;
@@ -68,42 +70,62 @@
 
   async function handleClick(event) {
     const action = event.target?.closest?.('[data-update-notice-action]')?.dataset?.updateNoticeAction;
-    if (!action || actionInFlight) return;
+    if (!action) return;
+    if (action === 'release-notes') {
+      const version = currentView?.state?.latestVersion || '';
+      window.open('https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v' + version, '_blank', 'noopener');
+      return;
+    }
     if (action === 'copy-manual') {
       try {
         await navigator.clipboard.writeText(manualUpdateCommand(currentView?.state));
         manualCommandCopied = true;
         render();
-        setTimeout(() => {
-          manualCommandCopied = false;
-          render();
-        }, 1800);
-      } catch (_error) {
-        manualCommandCopied = false;
-      }
+        setTimeout(() => { manualCommandCopied = false; render(); }, 1800);
+      } catch (_) { manualCommandCopied = false; }
       return;
     }
+    return runUpdateAction(action);
+  }
+
+  async function runUpdateAction(action) {
+    const cancelling = action === 'cancel' || action === 'later';
+    if (cancellationInFlight || ((actionInFlight || settingsActionInFlight) && !cancelling)) return;
+    const sequence = ++actionSequence;
     actionInFlight = true;
+    settingsActionInFlight = true;
+    cancellationInFlight = cancelling;
     render();
     try {
-      currentView = await request({
+      const view = await request({
+        check: 'codex-overleaf/consent-update-check',
         install: 'codex-overleaf/consent-update-install',
         retry: 'codex-overleaf/consent-update-check',
         later: 'codex-overleaf/consent-update-later',
+        cancel: 'codex-overleaf/consent-update-cancel',
+        recover: 'codex-overleaf/consent-update-recover',
         dismiss: 'codex-overleaf/consent-update-dismiss',
         reload: 'codex-overleaf/consent-update-reload'
       }[action]);
+      if (sequence === actionSequence) currentView = view;
     } catch (error) {
-      currentView = await reconcileAfterActionError(error, {
-        action,
-        fallbackMessage: tx('Update failed.', '更新失败。')
-      });
+      if (sequence === actionSequence) {
+        const view = await reconcileAfterActionError(error, {
+          action, fallbackMessage: tx('Update action failed.', '更新操作失败。')
+        });
+        if (sequence === actionSequence) currentView = view;
+      }
     } finally {
-      actionInFlight = false;
-      render();
+      if (sequence === actionSequence) {
+        actionInFlight = false;
+        settingsActionInFlight = false;
+        cancellationInFlight = false;
+        render();
+      }
     }
   }
 
+
   async function request(type) {
     if (!type) throw new Error('Unknown update action.');
     const response = await chrome.runtime.sendMessage({ type });
@@ -164,8 +186,9 @@
     restartWatchdog = setTimeout(async () => {
       try {
         const view = await request('codex-overleaf/consent-update-get-state');
-        if (view?.state && !ACTIVE_UPDATE_STATES.has(view.state.state)) {
+        if (view?.state) {
           currentView = view;
+          if (ACTIVE_UPDATE_STATES.has(view.state.state)) scheduleRestartWatchdog();
         } else {
           currentView = buildFailedView('update_recovery_timeout', tx(
             'The update did not finish restarting. Retry or use the manual recovery command.',
@@ -206,37 +229,18 @@
     renderSettings();
   }
 
-  async function handleSettingsAction() {
-    if (settingsActionInFlight) return;
-    settingsActionInFlight = true;
-    renderSettings();
-    const stateName = currentView?.state?.state || 'idle';
-    let requestedAction = 'check';
-    try {
-      if (['reload_required', 'reload_tabs_required'].includes(stateName)) {
-        requestedAction = 'reload';
-        currentView = await request('codex-overleaf/consent-update-reload');
-      } else if (stateName === 'update_available') {
-        requestedAction = 'install';
-        currentView = await request('codex-overleaf/consent-update-install');
-      } else if (['failed', 'rolled_back'].includes(stateName)) {
-        currentView = await request('codex-overleaf/consent-update-check');
-      } else if (!ACTIVE_UPDATE_STATES.has(stateName)) {
-        currentView = await request('codex-overleaf/consent-update-check');
-      } else {
-        return;
-      }
-    } catch (error) {
-      currentView = await reconcileAfterActionError(error, {
-        action: requestedAction,
-        fallbackMessage: tx('Update check failed.', '更新检查失败。')
-      });
-    } finally {
-      settingsActionInFlight = false;
-      render();
+  function handleSettingsAction() {
+    const state = currentView?.state || {};
+    if (state.recoveryPending) return runUpdateAction('recover');
+    if (state.cancelRequested || ['checking', 'downloading', 'staged', 'waiting_for_idle'].includes(state.state)) {
+      return runUpdateAction('cancel');
     }
+    if (['reload_required', 'reload_tabs_required'].includes(state.state)) return runUpdateAction('reload');
+    if (state.state === 'update_available') return runUpdateAction('install');
+    if (!ACTIVE_UPDATE_STATES.has(state.state)) return runUpdateAction('check');
   }
 
+
   function render() {
     if (!currentView) return;
     renderSettings();
@@ -270,7 +274,24 @@
     detail.textContent = copy.detail;
     body.append(eyebrow, title, detail);
 
-    if (state.state === 'failed') {
+    if (state.state === 'manual_install_required') {
+      const steps = document.createElement('ol');
+      steps.className = 'codex-update-notice-steps';
+      for (const text of [
+        tx('Run this once in a terminal:', '在终端运行一次：'),
+        tx('Reload the extension in chrome://extensions, then refresh Overleaf.', '在 chrome://extensions 里重新加载扩展，再刷新 Overleaf。')
+      ]) steps.append(Object.assign(document.createElement('li'), { textContent: text }));
+      const command = document.createElement('code');
+      command.className = 'codex-update-notice-command';
+      command.textContent = manualUpdateCommand(state);
+      steps.firstElementChild.append(command);
+      const keep = document.createElement('span');
+      keep.className = 'codex-update-notice-recovery';
+      keep.textContent = tx('Sessions, settings, provider keys and project mirrors are kept.', '会话、设置、模型服务的密钥和项目镜像都会保留。');
+      body.append(steps, keep);
+    }
+
+    if (state.state === 'failed' && !state.cancelRequested && !state.recoveryPending) {
       const recovery = document.createElement('span');
       recovery.className = 'codex-update-notice-recovery';
       recovery.textContent = tx('Manual recovery:', '手动恢复：');
@@ -280,7 +301,7 @@
       body.append(recovery, command);
     }
 
-    if (!['update_available', 'failed', 'rolled_back', 'reload_required', 'reload_tabs_required'].includes(state.state)) {
+    if (!['update_available', 'manual_install_required', 'failed', 'rolled_back', 'reload_required', 'reload_tabs_required'].includes(state.state)) {
       const bar = document.createElement('div');
       bar.className = 'codex-update-notice-progress' + (progress.determinate ? '' : ' is-indeterminate');
       bar.setAttribute('role', 'progressbar');
@@ -302,7 +323,9 @@
       button.dataset.updateNoticeAction = action.id;
       button.className = action.primary ? 'is-primary' : '';
       button.textContent = action.label;
-      button.disabled = actionInFlight;
+      button.disabled = action.id === 'cancel'
+        ? cancellationInFlight || (state.cancelRequested && !state.code)
+        : actionInFlight || settingsActionInFlight;
       actions.append(button);
     }
     notice.replaceChildren(body, actions);
@@ -343,6 +366,9 @@
       summaryText = tx(`Stable v${latestVersion} is available.`, `稳定版本 v${latestVersion} 已可用。`);
       statusText = tx('Ready to download and verify.', '已可下载并验证。');
       buttonText = tx('Update now', '立即更新');
+    } else if (stateName === 'manual_install_required') {
+      summaryText = tx(`v${latestVersion} is available but needs a one-time reinstall.`, `v${latestVersion} 已发布，但需要重新安装一次。`);
+      statusText = manualReasonText(state) || getCopy(state).detail;
     } else if (ACTIVE_UPDATE_STATES.has(stateName)) {
       statusText = getCopy(state).detail;
       buttonText = tx('Update in progress', '更新进行中');
@@ -358,11 +384,29 @@
     status.textContent = statusText;
     status.hidden = !statusText;
     button.textContent = buttonText;
-    button.disabled = settingsActionInFlight || stateName === 'checking' || ACTIVE_UPDATE_STATES.has(stateName);
+    const cancellable = state.cancelRequested || ['checking', 'downloading', 'staged', 'waiting_for_idle'].includes(stateName);
+    if (state.recoveryPending) {
+      button.textContent = tx('Check recovery', '检查恢复状态');
+      button.disabled = actionInFlight || settingsActionInFlight;
+    } else if (cancellable) {
+      button.textContent = state.cancelRequested && !state.code
+        ? tx('Cancelling…', '正在取消…')
+        : state.cancelRequested ? tx('Retry cancellation', '重试取消') : tx('Cancel update', '取消更新');
+      button.disabled = cancellationInFlight || (state.cancelRequested && !state.code);
+    } else {
+      button.disabled = actionInFlight || settingsActionInFlight || ACTIVE_UPDATE_STATES.has(stateName);
+    }
   }
 
   function visibleActions(state) {
-    if (actionInFlight) return [];
+    const value = currentView?.state || {};
+    if (value.recoveryPending) return [{ id: 'recover', label: tx('Check recovery', '检查恢复状态'), primary: true }];
+    if (value.cancelRequested || ['checking', 'downloading'].includes(state)) {
+      return [{ id: 'cancel', label: value.cancelRequested
+        ? value.code ? tx('Retry cancellation', '重试取消') : tx('Cancelling…', '正在取消…')
+        : tx('Cancel update', '取消更新'), primary: false }];
+    }
+    if (actionInFlight && !['staged', 'waiting_for_idle'].includes(state)) return [];
     if (['reload_required', 'reload_tabs_required'].includes(state)) {
       return [{ id: 'reload', label: state === 'reload_required'
         ? tx('Reload extension', '重新加载扩展') : tx('Refresh Overleaf tabs', '刷新 Overleaf 标签页'), primary: true }];
@@ -374,7 +418,14 @@
       ];
     }
     if (['staged', 'waiting_for_idle'].includes(state)) {
-      return [{ id: 'later', label: tx('Later', '稍后'), primary: false }];
+      return [{ id: 'cancel', label: tx('Cancel update', '取消更新'), primary: false }];
+    }
+    if (state === 'manual_install_required') {
+      return [
+        { id: 'later', label: tx('Later', '稍后'), primary: false },
+        { id: 'release-notes', label: tx('Release notes', '发布说明'), primary: false },
+        { id: 'copy-manual', label: manualCommandCopied ? tx('Copied', '已复制') : tx('Copy command', '复制命令'), primary: true }
+      ];
     }
     if (['failed', 'rolled_back'].includes(state)) {
       return [
@@ -390,8 +441,18 @@
 
   function getCopy(state) {
     const target = state.latestVersion ? 'v' + state.latestVersion : '';
+    if (state.cancelRequested) return {
+      eyebrow: tx('Cancelling update', '正在取消更新'), title: target,
+      detail: state.message || tx('Stopping this update and clearing its authorization.', '正在停止本次更新并清理更新授权。')
+    };
+    if (state.recoveryPending) return {
+      eyebrow: tx('Checking update recovery', '正在确认更新恢复状态'), title: target,
+      detail: state.message || tx('Waiting for the installed version to be confirmed.', '正在确认实际安装的版本。')
+    };
     const blocker = blockersCopy(state.blockers?.length ? state.blockers : [state.blocker]);
     return {
+      checking: { eyebrow: tx('Checking for updates', '正在检查更新'), title: target,
+        detail: tx('Reading the latest signed release.', '正在读取最新签名版本。') },
       reload_required: {
         eyebrow: tx('Installed, awaiting reload', '已安装，等待加载'), title: target,
         detail: state.message || tx('The new files are installed. Reload the extension when Overleaf is saved and idle.', '新版文件已安装，请在 Overleaf 保存并空闲后重新加载扩展。')
@@ -400,6 +461,11 @@
         eyebrow: tx('Updated runtime is ready', '新版运行组件已就绪'), title: target,
         detail: state.message || tx('Refresh the saved, idle Overleaf tabs to load the updated panel.', '刷新已保存且空闲的 Overleaf 标签页以加载新版面板。')
       },
+      manual_install_required: {
+        eyebrow: tx('Reinstall needed for this update', '这次更新需要重新安装'),
+        title: target,
+        detail: manualReasonText(state) || tx('This release changes what Chrome lets the extension do, so Update now cannot apply it.', '这一版改动了 Chrome 授予扩展的权限，无法通过“立即更新”完成。')
+      },
       update_available: {
         eyebrow: tx('Update available', '发现新版本'),
         title: target,
@@ -488,6 +554,11 @@
     );
   }
 
+  function manualReasonText(state = {}) {
+    const reason = state.manualReason || {};
+    return tx(reason.en || reason.zh || '', reason.zh || reason.en || '');
+  }
+
   function tx(english, chinese) {
     const locale = String(getLocale() || document.documentElement?.lang || 'en');
     return /^zh\b/i.test(locale) ? chinese : english;

package/extension/src/content/writebackController.js

@@ -227,6 +227,11 @@
       ? changeOrReason
       : { reason: changeOrReason };
     const reason = change.reason;
+    if (reason === 'selection_scope_violation') {
+      return isEnglish
+        ? 'The local changes exceeded the captured selection. No changes from this task were written back.'
+        : '本地改动超出了已附加的选区，本轮改动未写回。';
+    }
     if (reason === 'generated_artifact') {
       return isEnglish
         ? 'LaTeX build artifact; not written back by default.'
@@ -240,6 +245,11 @@
     if (reason === 'binary_payload_exceeds_native_message_limit') {
       return formatBinaryPayloadLimitReason(change, locale);
     }
+    if (reason === 'subagent_unfinished_output') {
+      return isEnglish
+        ? 'The subagent did not finish; the main agent must review and adopt this file before it can sync.'
+        : '子代理未正常完成，主代理需核对并接管该文件后才能同步。';
+    }
     if (reason === 'subagent_unauthorized_edit') {
       return isEnglish
         ? "A subagent's change to this file was withheld from Overleaf — it either fell outside the subagent's assigned files or the subagent did not finish cleanly."
@@ -290,10 +300,257 @@
     return (syncChanges || []).filter(change => appliedPaths.has(change.path));
   }
 
+
+  // Verify the server revision independently of editor overlays. No writes or retries
+  // of writes are performed here; a missing acknowledgement never becomes success.
+  function buildSavedWritebackExpectations(applied = {}, project = {}) {
+    const expected = new Map();
+    const original = new Map((project.files || []).map(file => [file.path, file]));
+    const unsupported = [];
+    for (const entry of getAppliedEntries(applied)) {
+      const operation = entry?.operation || {};
+      const result = entry?.result || {};
+      const path = operation.path;
+      if (!path || result.ok === false) { unsupported.push(path || 'unknown'); continue; }
+      if (operation.type === 'delete') { expected.set(path, { absent: true }); continue; }
+      if (operation.type === 'rename' || operation.type === 'move') {
+        const content = typeof result.verifiedContent === 'string'
+          ? result.verifiedContent : original.get(path)?.content;
+        if (!operation.to || typeof content !== 'string') { unsupported.push(path); continue; }
+        if (operation.to !== path) expected.set(path, { absent: true });
+        expected.set(operation.to, { content });
+        continue;
+      }
+      if (operation.type === 'binary-create' || operation.type === 'overwrite-binary') {
+        const hash = operation.sha256 || operation.assetRef?.sha256;
+        if (/^[a-f0-9]{64}$/i.test(hash || '')) expected.set(path, { sha256: hash.toLowerCase() });
+        else if (typeof operation.contentBase64 === 'string'
+          && (operation.contentBase64 || !operation.assetRef || operation.size === 0)) {
+          expected.set(path, { contentBase64: operation.contentBase64.replace(/\s/g, '') });
+        } else unsupported.push(path);
+        continue;
+      }
+      const content = typeof result.verifiedContent === 'string' ? result.verifiedContent
+        : operation.type === 'create' && typeof operation.content === 'string' ? operation.content
+          : operation.type === 'edit' && typeof operation.replaceAll === 'string' ? operation.replaceAll : undefined;
+      if (typeof content === 'string') expected.set(path, { content });
+      else unsupported.push(path);
+    }
+    return { expected, unsupported };
+  }
+
+  async function matchSavedWritebackSnapshot(snapshot, expectations, projectId) {
+    if (snapshot?.id !== projectId || snapshot?.ok === false
+      || snapshot?.capabilities?.method !== 'overleaf-zip'
+      || snapshot.capabilities.fullProjectSnapshot !== true || !Array.isArray(snapshot.files)
+      || snapshot.files.some(file => file?.source !== 'overleaf-zip')) {
+      return { matched: false, reason: 'authoritative_snapshot_unavailable' };
+    }
+    if (!expectations.expected.size || expectations.unsupported.length) {
+      return { matched: false, reason: 'expected_content_unavailable' };
+    }
+    const byPath = new Map(snapshot.files.map(file => [file.path, file]));
+    for (const [path, expected] of expectations.expected) {
+      const file = byPath.get(path);
+      if (expected.absent) {
+        if (file || snapshot.capabilities.skipped?.length) return { matched: false, reason: 'server_content_mismatch', path };
+        continue;
+      }
+      if (!file) return { matched: false, reason: 'server_content_mismatch', path };
+      if (typeof expected.content === 'string') {
+        if (file.content !== expected.content) return { matched: false, reason: 'server_content_mismatch', path };
+      } else {
+        if (typeof file.contentBase64 !== 'string') return { matched: false, reason: 'server_binary_unavailable', path };
+        if (expected.contentBase64 !== undefined) {
+          if (file.contentBase64.replace(/\s/g, '') !== expected.contentBase64) return { matched: false, reason: 'server_content_mismatch', path };
+        } else {
+          const hash = await binaryDigest(file.contentBase64);
+          if (!hash) return { matched: false, reason: 'binary_digest_unavailable', path };
+          if (hash !== expected.sha256) return { matched: false, reason: 'server_content_mismatch', path };
+        }
+      }
+    }
+    return { matched: true };
+  }
+
+  async function confirmPostWriteSave(options = {}) {
+    const { applied, project, runProjectId, assertCurrent, readSaveState, readSnapshot } = options;
+    if (!runProjectId || typeof assertCurrent !== 'function') {
+      return { verification: { ok: false, state: 'unavailable', signal: 'context_missing' } };
+    }
+    const now = options.now || Date.now;
+    const deadline = now() + 90000;
+    const attempts = [];
+    const isInterruption = error => ['codex_cancelled', 'aborted_project_changed', 'editor_project_id_unavailable'].includes(error?.code)
+      || error?.name === 'AbortError';
+    const probe = async duration => {
+      assertCurrent();
+      try {
+        const result = await readSaveState({ deadlineMs: Math.max(0, Math.min(duration, deadline - now())), requirePositiveSignal: true });
+        assertCurrent();
+        return result || { ok: false, state: 'unavailable', signal: 'unavailable' };
+      } catch (error) {
+        if (isInterruption(error)) throw error;
+        assertCurrent();
+        return { ok: false, state: 'unavailable', signal: 'unavailable', reason: String(error?.message || error).slice(0, 800) };
+      }
+    };
+    const receiptExpectations = buildSavedWritebackExpectations(applied, project);
+    assertCurrent();
+    if (await receiptsConfirmExpectedFiles(applied, receiptExpectations, runProjectId)) {
+      assertCurrent();
+      return { verification: { ok: true, state: 'verified_saved', source: 'server-receipts' } };
+    }
+    const primary = await probe(1500);
+    if (primary.ok === true && primary.state === 'verified_saved') {
+      return { verification: { ...primary, source: 'save-indicator' } };
+    }
+    const expectations = buildSavedWritebackExpectations(applied, project);
+    let lastReason = '';
+    if (primary.signal !== 'offline' && expectations.expected.size && !expectations.unsupported.length) {
+      for (let attempt = 0; attempt < 3 && deadline - now() > 1000; attempt++) {
+        assertCurrent();
+        try {
+          const snapshot = await readSnapshot({
+            force: true, maxAgeMs: 0, zipOnly: true, serverOnly: true,
+            includeBinaryFiles: true, allowEditorNavigation: false, requireFullProject: true,
+            zipTimeoutMs: Math.max(1, Math.min(30000, deadline - now())),
+            saveCheckId: String(now()) + '-' + attempt + '-' + Math.random().toString(36).slice(2, 8)
+          });
+          assertCurrent();
+          const match = await matchSavedWritebackSnapshot(snapshot, expectations, runProjectId);
+          assertCurrent();
+          attempts.push({ attempt: attempt + 1, result: match.matched ? 'matched' : match.reason, path: match.path || '' });
+          if (match.matched) return {
+            verification: { ok: true, state: 'verified_saved', source: 'overleaf-zip', recovered: true,
+              primary: { state: primary.state, signal: primary.signal, reason: primary.reason }, attempts },
+            snapshot
+          };
+          lastReason = match.reason;
+        } catch (error) {
+          if (isInterruption(error)) throw error;
+          assertCurrent();
+          lastReason = String(error?.message || error).slice(0, 800);
+          attempts.push({ attempt: attempt + 1, result: 'snapshot_unavailable', reason: lastReason });
+        }
+      }
+    }
+    const final = primary.signal === 'offline' ? primary : await probe(2000);
+    if (final.ok === true && final.state === 'verified_saved') {
+      return { verification: { ...final, source: 'save-indicator', recovered: true, attempts } };
+    }
+    return { verification: {
+      ok: false, state: final.state === 'unavailable' ? 'unavailable' : 'unknown_timeout',
+      signal: final.signal || primary.signal || 'unavailable',
+      reason: final.reason || primary.reason || 'No positive save evidence was available.',
+      recoveryReason: lastReason || (expectations.unsupported.length ? 'expected_content_unavailable' : ''),
+      attempts
+    } };
+  }
+
+  async function bytesDigest(bytes) {
+    if (!globalThis.crypto?.subtle) return '';
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+  }
+
+  async function textDigest(content) {
+    return typeof TextEncoder === 'function' ? bytesDigest(new TextEncoder().encode(content)) : '';
+  }
+
+  async function binaryDigest(contentBase64) {
+    if (typeof contentBase64 !== 'string' || typeof atob !== 'function') return '';
+    let bytes;
+    try { bytes = Uint8Array.from(atob(contentBase64.replace(/\s/g, '')), value => value.charCodeAt(0)); }
+    catch (_error) { return ''; }
+    return bytesDigest(bytes);
+  }
+
+  async function receiptsConfirmExpectedFiles(applied, expectations, projectId) {
+    if (!expectations.expected.size || expectations.unsupported.length) return false;
+    const entries = getAppliedEntries(applied);
+    for (const [path, expected] of expectations.expected) {
+      if (typeof expected.content !== 'string') return false;
+      const receipt = [...entries].reverse().find(entry => entry.operation?.path === path)?.result?.saveReceipt;
+      if (receipt?.v !== 1 || receipt.source !== 'overleaf-zip' || receipt.projectId !== projectId
+        || receipt.path !== path || !Number.isFinite(Date.parse(receipt.verifiedAt || ''))
+        || !/^[a-f0-9]{64}$/.test(receipt.sha256 || '') || receipt.sha256 !== await textDigest(expected.content)) return false;
+    }
+    return true;
+  }
+
+  async function buildSaveCheck(applied, project, owner) {
+    const expectations = buildSavedWritebackExpectations(applied, project);
+    if (expectations.unsupported.length) return null;
+    const files = [];
+    for (const [path, expected] of expectations.expected) {
+      if (expected.absent) files.push({ path, absent: true });
+      else if (typeof expected.content === 'string') {
+        const sha256 = await textDigest(expected.content);
+        if (!sha256) return null;
+        files.push({ path, sha256, kind: 'text' });
+      } else {
+        const sha256 = expected.sha256 || await binaryDigest(expected.contentBase64);
+        if (!sha256) return null;
+        files.push({ path, sha256, kind: 'binary' });
+      }
+    }
+    return files.length ? { ...owner, v: 1, files } : null;
+  }
+
+  async function confirmSaveCheck(check, options) {
+    if (!check?.projectId || !Array.isArray(check.files) || !check.files.length
+      || check.files.some(file => !file?.path || (file.absent !== true && !/^[a-f0-9]{64}$/i.test(file.sha256 || '')))) {
+      return { ok: false, state: 'unavailable', reason: 'expected_content_unavailable' };
+    }
+    const now = options.now || Date.now, deadline = now() + 90000;
+    let reason = 'server_snapshot_unavailable';
+    for (let attempt = 0; attempt < 3 && now() < deadline; attempt++) {
+      options.assertCurrent();
+      let snapshot;
+      try {
+        snapshot = await options.readSnapshot({ force: true, maxAgeMs: 0, zipOnly: true, serverOnly: true,
+          includeBinaryFiles: true, allowEditorNavigation: false, requireFullProject: true,
+          zipTimeoutMs: Math.min(30000, Math.max(1, deadline - now())), saveCheckId: String(now()) + '-' + attempt });
+      } catch (error) {
+        if (['codex_cancelled', 'aborted_project_changed', 'editor_project_id_unavailable'].includes(error?.code)
+          || error?.name === 'AbortError') throw error;
+        options.assertCurrent();
+        continue;
+      }
+      options.assertCurrent();
+      if (snapshot?.ok === false || snapshot?.id !== check.projectId
+        || snapshot.capabilities?.fullProjectSnapshot !== true
+        || snapshot.capabilities?.method !== 'overleaf-zip' || !Array.isArray(snapshot.files)) continue;
+      const files = new Map(snapshot.files.map(file => [file.path, file]));
+      let matched = true;
+      for (const expected of check.files) {
+        const file = files.get(expected.path);
+        if (expected.absent) { if (file || snapshot.capabilities.skipped?.length) matched = false; continue; }
+        if (!file || file.source !== 'overleaf-zip') { matched = false; continue; }
+        const kind = typeof file.content === 'string' ? 'text'
+          : typeof file.contentBase64 === 'string' ? 'binary' : '';
+        if (!kind || (expected.kind && expected.kind !== kind)) { matched = false; continue; }
+        const hash = kind === 'binary' ? await binaryDigest(file.contentBase64) : await textDigest(file.content);
+        if (!hash || hash !== expected.sha256.toLowerCase()) matched = false;
+      }
+      options.assertCurrent();
+      if (matched) return { ok: true, state: 'verified_saved', source: 'overleaf-zip' };
+      reason = 'server_content_mismatch';
+    }
+    return { ok: false, state: 'unknown_timeout', reason };
+  }
+
   return {
+    confirmPostWriteSave,
+    buildSaveCheck,
+    confirmSaveCheck,
+    buildSavedWritebackExpectations,
+    matchSavedWritebackSnapshot,
     buildSyncApplyOperations,
     computeSingleTextPatch,
     formatUnsupportedLocalChangeSummary,
+    formatUnsupportedLocalChangeReason,
     getAppliedOperationPaths,
     getAppliedSyncChanges,
     getSyncChangePatches,