codex-overleaf-link 2.5.0 → 2.6.0

package/extension/src/page/fileMover.js

@@ -0,0 +1,256 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafFileMover = factory();
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  function create(deps = {}) {
+    const { window, document, treeOperations, snapshotRouter, textFileCreator } = deps;
+    const normalizePath = deps.normalizeSafeProjectPath || window.CodexOverleafProjectFiles?.normalizeSafeProjectPath;
+    const delay = deps.delay || (ms => new Promise(resolve => window.setTimeout(resolve, ms)));
+    const error = (code, message) => Object.assign(new Error(message), { code });
+    const parent = path => path.split('/').slice(0, -1).join('/');
+    const basename = path => path.split('/').pop();
+    const join = (folder, name) => [folder, name].filter(Boolean).join('/');
+    function entities() {
+      treeOperations.invalidateDomProjectPathCache?.();
+      const root = document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+      const unique = new Map();
+      for (const row of root?.querySelectorAll?.('[role="treeitem"]') || []) {
+        const entity = row.querySelector?.(':scope > .entity[data-file-id]')
+          || row.querySelector?.('[data-file-type][data-file-id]');
+        const id = entity?.dataset?.fileId || entity?.getAttribute?.('data-file-id');
+        const type = entity?.dataset?.fileType || entity?.getAttribute?.('data-file-type');
+        const path = normalizePath?.(treeOperations.readProjectPathFromNode?.(row));
+        if (id && path && ['doc', 'file', 'folder'].includes(type)) unique.set(type + ':' + id + ':' + path, { id, path, type });
+      }
+      return [...unique.values()];
+    }
+    function at(path, type) {
+      const found = entities().filter(entry => entry.path === path && (!type || entry.type === type));
+      return found.length === 1 ? found[0] : null;
+    }
+    function folderId(path, projectId) {
+      if (path) return at(path, 'folder')?.id || '';
+      for (const root of [window._ide, window.Overleaf, window.overleaf, window.OL]) {
+        const project = root?.project;
+        if ((project?._id || project?.id) !== projectId) continue;
+        const folder = Array.isArray(project.rootFolder) ? project.rootFolder[0] : project.rootFolder;
+        if (folder?._id || folder?.id) return folder._id || folder.id;
+      }
+      return '';
+    }
+    async function digest(file, kind) {
+      let bytes;
+      if (kind === 'text' && typeof file?.content === 'string') bytes = new TextEncoder().encode(file.content);
+      else if (kind === 'binary' && typeof file?.contentBase64 === 'string') {
+        bytes = Uint8Array.from((window.atob || globalThis.atob)(file.contentBase64), char => char.charCodeAt(0));
+      } else throw error('file_move_source_unavailable', 'The source contents could not be verified.');
+      const hash = await (window.crypto || globalThis.crypto).subtle.digest('SHA-256', bytes);
+      return [...new Uint8Array(hash)].map(byte => byte.toString(16).padStart(2, '0')).join('');
+    }
+    function csrfToken() {
+      const meta = document.querySelector('meta[name="ol-csrfToken"], meta[name="csrf-token"], meta[name="_csrf"]');
+      let value = meta ? meta.content : window.csrfToken || window._csrf;
+      if (['json', 'number'].includes(meta?.dataset?.type)) {
+        try { value = JSON.parse(value); } catch (_error) { return ''; }
+      }
+      if (meta?.dataset?.type === 'boolean') return '';
+      return typeof value === 'string' && value.length > 0 && value.length <= 4096 && !/[\0\r\n]/.test(value) ? value : '';
+    }
+
+    // Compatibility consumer for identity-bound moves recorded by older builds.
+    // New mirror diffs never produce metadata moves.
+    async function moveFile(operation, options = {}) {
+      const source = normalizePath?.(operation?.path), target = normalizePath?.(operation?.to);
+      const proof = operation?.moveProof;
+      const projectId = options.runProjectId;
+      const entity = value => typeof value === 'string' && value.length > 0 && value.length <= 160 && !/[\0\r\n]/.test(value);
+      if (options.noTraceUndo !== true || !entity(proof?.sourceEntityId) || !entity(proof?.targetEntityId)
+        || proof.sourceEntityId !== proof.targetEntityId) return { ok: false, code: 'file_tree_controls_unavailable', changedDocument: false,
+        reason: 'A recorded same-entity move is required before its location can be restored.' };
+      const deadline = Math.min(Date.now() + 90000, Number.isFinite(options.deadlineAt) ? options.deadlineAt : Infinity);
+      const createdDirectories = [], completed = [];
+      let entityId = '', entityType = '', attempted = false, currentPath = source;
+      const assertCurrent = () => {
+        if (!projectId || treeOperations.getProjectId() !== projectId) throw error('aborted_project_changed', 'The project changed during the file move.');
+        if (options.isCurrent?.() === false) throw error('codex_cancelled', 'The file move was cancelled.');
+        if (Date.now() >= deadline) throw error('file_move_deadline_exceeded', 'The file move verification deadline was reached.');
+      };
+      const inspectRemainingDirectories = async () => {
+        if (!Array.isArray(proof.createdDirectories) || !proof.createdDirectories.length) return {};
+        try {
+          const directoryCleanup = await textFileCreator?.cleanupCreatedDirectories?.(proof.createdDirectories, {
+            projectId, isCurrent: () => { assertCurrent(); return true; }
+          });
+          if (directoryCleanup) return { directoryCleanup };
+        } catch (_error) { /* The verified file move remains complete; only its directory inspection is unresolved. */ }
+        return { directoryCleanup: { ok: false, removed: [], remaining: proof.createdDirectories, requiresExplicitCleanup: true } };
+      };
+      const observedPath = () => {
+        if (treeOperations.getProjectId() !== projectId) return '';
+        const found = entities().filter(entry => entry.id === entityId && entry.type === entityType);
+        return found.length === 1 ? found[0].path : '';
+      };
+      const snapshot = async () => {
+        assertCurrent(); snapshotRouter.invalidateCache?.();
+        const result = await snapshotRouter.fetchProjectZipSnapshot({ force: true, maxAgeMs: 0, serverOnly: true,
+          includeContent: true, includeBinaryFiles: true, writebackVerification: true,
+          zipTimeoutMs: Math.max(1, Math.min(30000, deadline - Date.now())) });
+        assertCurrent();
+        const skipped = [...(result?.skipped || []), ...(result?.capabilities?.skipped || [])];
+        if (!result?.ok || !Array.isArray(result.files) || result.partialSnapshot === true
+          || result.pathIdentityComplete === false || result.capabilities?.pathIdentityComplete === false
+          || skipped.some(file => file?.unknownPath || ['zip_path_invalid', 'zip_path_duplicate'].includes(file?.reason))
+          || result.capabilities?.fullProjectSnapshot === false || (result.id && result.id !== projectId)) {
+          throw error('file_move_source_unavailable', 'A complete server source snapshot is required to move a file.');
+        }
+        return result;
+      };
+      const contains = (data, path) => data.files.some(file => file.path === path)
+        || [...(data.skipped || []), ...(data.capabilities?.skipped || [])].some(file => file.path === path);
+      const verify = async (path, data) => {
+        assertCurrent();
+        const entity = at(path);
+        if (!entity || !['doc', 'file'].includes(entity.type) || (entityId && entity.id !== entityId)
+          || (entityType && entity.type !== entityType) || (proof.entityType && entity.type !== proof.entityType)
+          || (proof.sourceEntityId && entity.id !== proof.sourceEntityId)) {
+          throw error('file_move_identity_changed', 'The exact source file identity changed or is unavailable.');
+        }
+        const file = data.files.find(file => file.path === path);
+        if (await digest(file, proof.kind) !== proof.sha256.toLowerCase()) {
+          throw error('stale_source_changed', 'The source file changed after Codex read it.');
+        }
+        assertCurrent();
+        if (at(path)?.id !== entity.id || at(path)?.type !== entity.type) throw error('file_move_identity_changed', 'The source file identity changed while checking its contents.');
+        return entity;
+      };
+      const checkStep = async step => {
+        const data = await snapshot(); await verify(step.from, data);
+        if (contains(data, step.to) || at(step.to)) throw error('file_move_target_exists', 'The destination or an intermediate move path is occupied.');
+        if (step.action === 'move' && folderId(parent(step.to), projectId) !== step.folderId) {
+          throw error('file_move_folder_changed', 'The destination folder identity changed.');
+        }
+        assertCurrent();
+      };
+      const confirmStep = async step => {
+        for (let i = 0; i < 8; i++) {
+          const data = await snapshot();
+          if (!contains(data, step.from) && contains(data, step.to) && at(step.to)?.id === entityId) {
+            await verify(step.to, data); currentPath = step.to; return true;
+          }
+          if (i < 7) await delay(Math.min(250 * (i + 1), 1000));
+        }
+        return false;
+      };
+      const send = async step => {
+        await checkStep(step);
+        const csrf = csrfToken();
+        if (!csrf) throw error('file_move_identity_unavailable', 'The page request identity is unavailable. Reload Overleaf before moving files.');
+        const Controller = window.AbortController || globalThis.AbortController;
+        const controller = new Controller();
+        const timer = window.setTimeout(() => controller.abort(), Math.max(1, deadline - Date.now()));
+        let response, transportError;
+        try {
+          assertCurrent(); attempted = true;
+          response = await window.fetch(`/project/${encodeURIComponent(projectId)}/${entityType}/${encodeURIComponent(entityId)}/${step.action}`, {
+            method: 'POST', credentials: 'same-origin', signal: controller.signal,
+            headers: { 'Content-Type': 'application/json', 'X-Csrf-Token': csrf, Accept: 'application/json' },
+            body: JSON.stringify(step.action === 'rename' ? { name: basename(step.to) } : { folder_id: step.folderId })
+          });
+        } catch (caught) { transportError = caught; }
+        finally { window.clearTimeout(timer); }
+        assertCurrent();
+        if (await confirmStep(step)) return;
+        if (response && !response.ok && response.status >= 400 && response.status < 500 && response.status !== 408) {
+          const rejected = error('file_move_rejected', 'Overleaf rejected the file move.');
+          rejected.definitive = true; throw rejected;
+        }
+        const unknown = error('file_move_unconfirmed', transportError
+          ? 'The move response was lost. Check the file location before retrying.'
+          : 'The move result could not be confirmed. Check the file location before retrying.');
+        unknown.receiptUnconfirmed = true; throw unknown;
+      };
+      try {
+        assertCurrent();
+        if (!source || !target || source === target || operation.type !== 'move' || proof?.v !== 1
+          || !['text', 'binary'].includes(proof.kind) || !/^[a-f0-9]{64}$/i.test(proof.sha256 || '')) {
+          throw error('invalid_project_path', 'A verified source, different destination and content hash are required for a move.');
+        }
+        if (parent(source)) await textFileCreator?.prepareUploadParent?.(parent(source), { createMissing: false, isCurrent: () => { assertCurrent(); return true; } });
+        let data = await snapshot();
+        if (!contains(data, source) && proof.sourceEntityId && at(target)?.id === proof.sourceEntityId) {
+          entityId = proof.sourceEntityId; entityType = at(target).type;
+          await verify(target, data);
+          return { ok: true, verified: true, verification: 'overleaf-zip', idempotent: true, changedDocument: false,
+            method: 'overleaf.entity-move', moveProof: { ...proof, targetEntityId: entityId }, ...await inspectRemainingDirectories() };
+        }
+        const sourceEntity = await verify(source, data); entityId = sourceEntity.id; entityType = sourceEntity.type;
+        if (contains(data, target) || at(target)) throw error('file_move_target_exists', 'The move destination already exists.');
+        const originalParent = parent(source), destinationParent = parent(target);
+        const originalFolderId = originalParent === destinationParent ? '' : folderId(originalParent, projectId);
+        if (originalParent !== destinationParent && !originalFolderId) throw error('file_move_folder_changed', 'The original folder identity is unavailable.');
+        if (destinationParent && originalParent !== destinationParent && !folderId(destinationParent, projectId)) {
+          await textFileCreator?.prepareUploadParent?.(destinationParent, { createMissing: true, isCurrent: () => { assertCurrent(); return true; },
+            onCreatedDirectory: proof => createdDirectories.push(proof) });
+        }
+        const destinationFolderId = originalParent === destinationParent ? '' : folderId(destinationParent, projectId);
+        if (originalParent !== destinationParent && !destinationFolderId) throw error('file_move_folder_changed', 'The destination folder identity is unavailable.');
+        data = await snapshot(); await verify(source, data);
+        const steps = [];
+        const rename = to => { steps.push({ action: 'rename', from: currentPath, to }); currentPath = to; };
+        const move = to => { steps.push({ action: 'move', from: currentPath, to, folderId: destinationFolderId, fromFolderId: originalFolderId }); currentPath = to; };
+        if (originalParent === destinationParent) rename(target);
+        else if (basename(source) === basename(target)) move(target);
+        else if (!contains(data, join(originalParent, basename(target))) && !at(join(originalParent, basename(target)))) {
+          rename(join(originalParent, basename(target))); move(target);
+        } else if (!contains(data, join(destinationParent, basename(source))) && !at(join(destinationParent, basename(source)))) {
+          move(join(destinationParent, basename(source))); rename(target);
+        } else {
+          const token = window.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16);
+          if (!token) throw error('file_move_target_exists', 'An unoccupied intermediate name could not be reserved safely.');
+          const extension = basename(source).match(/\.[^.]+$/)?.[0] || '';
+          const temporary = 'codex-move-' + token + extension;
+          if ([originalParent, destinationParent].some(folder => contains(data, join(folder, temporary)) || at(join(folder, temporary)))) {
+            throw error('file_move_target_exists', 'The temporary move path is occupied. Retry on a fresh project snapshot.');
+          }
+          rename(join(originalParent, temporary)); move(join(destinationParent, temporary)); rename(target);
+        }
+        currentPath = source;
+        for (const step of steps) { await send(step); completed.push(step); }
+        return { ok: true, verified: true, verification: 'overleaf-zip', changedDocument: true, method: 'overleaf.entity-move',
+          moveProof: { v: 1, kind: proof.kind, sha256: proof.sha256.toLowerCase(), sourceEntityId: entityId, targetEntityId: entityId, entityType },
+          ...await inspectRemainingDirectories(),
+          ...(createdDirectories.length ? { createdDirectories } : {}) };
+      } catch (caught) {
+        let rolledBack = false;
+        // Only a definite refusal permits compensation. A lost response may
+        // still be in flight; never replay or reverse that uncertain mutation.
+        if (caught.definitive && completed.length && treeOperations.getProjectId() === projectId && options.isCurrent?.() !== false) {
+          try {
+            for (const prior of completed.slice().reverse()) {
+              await send({ action: prior.action, from: prior.to, to: prior.from, folderId: prior.fromFolderId });
+            }
+            rolledBack = true;
+          } catch (_rollbackError) { /* Preserve the verified entity and report its location for recovery. */ }
+        }
+        const observed = entityId ? observedPath() : '';
+        const changedDocument = attempted || createdDirectories.length > 0;
+        const reason = rolledBack ? 'The move was not completed; the original file location was restored.' : caught.message;
+        const moveRecovery = attempted && !rolledBack ? { v: 1, projectId, kind: proof?.kind, sha256: proof?.sha256,
+          entityId, entityType, sourcePath: source, targetPath: target, observedPath: observed } : null;
+        return { ok: false, code: rolledBack ? 'file_move_rolled_back' : caught.code || 'file_move_failed', reason,
+          changedDocument, rolledBack, receiptUnconfirmed: caught.receiptUnconfirmed === true,
+          ...(createdDirectories.length ? { createdDirectories } : {}),
+          ...(moveRecovery ? { moveRecovery } : {}),
+          failure: { code: caught.code || 'file_move_failed', stage: attempted ? 'verify' : 'preflight',
+            severity: changedDocument ? 'warning' : 'blocked', terminalState: changedDocument ? 'needs_review' : 'blocked',
+            changedDocument, retryable: false, file: observed || source,
+            ...(moveRecovery ? { evidence: { moveRecovery } } : {}),
+            userMessage: reason, nextAction: changedDocument ? 'Check the file location before retrying.' : 'Read the project again before retrying.' } };
+      }
+    }
+    return { moveFile };
+  }
+  return { create };
+});

package/extension/src/page/overleafCapabilities.js

@@ -16,6 +16,7 @@
     const checkpointWrite = hasCheckpointCapability(deps);
     const compileCapture = Boolean(deps.compileState?.capturedRequestTemplate);
     const reviewingControl = Boolean(deps.findReviewingActivationControl?.());
+    const upgradeModal = Boolean(deps.findUpgradeModal?.());
 
     if (!editorRead) {
       warnings.push('没有识别到当前 Overleaf 编辑器，Codex 不能读取当前文件。');
@@ -47,7 +48,9 @@
         trigger: compileCapture
       },
       reviewing: {
-        control: reviewingControl
+        control: reviewingControl,
+        upgradeModal,
+        confirmed: !upgradeModal && deps.reviewingConfirmed === true
       },
       warnings
     };

package/extension/src/page/ownedDirectoryCleanup.js

@@ -0,0 +1,94 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafOwnedDirectoryCleanup = factory();
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+  function create(deps = {}) {
+    const { document, treeOperations, delay, now, readServerSnapshot,
+      assertVerificationOwner, normalizeDomText, normalizeSafeProjectPath } = deps;
+    const { invalidateDomProjectPathCache } = treeOperations;
+    function folderIdentity(row) {
+      const entity = row?.querySelector?.('[data-file-type="folder"]');
+      return ['data-file-id', 'data-folder-id', 'data-entity-id']
+        .map(name => entity?.getAttribute?.(name) || row?.getAttribute?.(name) || '').find(Boolean) || '';
+    }
+    // Resolve every path component within its direct native child group. A
+    // collapsed/ambiguous tree is unknown, never proof that a folder is absent.
+    function locateOwnedFolder(path) {
+      let group = document.querySelector('[data-testid="file-tree-list-root"], .file-tree-list[role="tree"]');
+      const parts = path.split('/');
+      for (let index = 0; index < parts.length; index++) {
+        if (!group?.children) throw new Error('The native folder tree is unavailable.');
+        const inner = Array.from(group.children).find(node => node.classList?.contains('file-tree-folder-list-inner')) || group;
+        const matches = Array.from(inner.children).filter(node => node.getAttribute?.('role') === 'treeitem'
+          && node.querySelector?.('[data-file-type="folder"]') && normalizeDomText(node.getAttribute('aria-label')) === parts[index]);
+        if (matches.length > 1) throw new Error('The folder path is ambiguous.');
+        if (!matches.length) return null;
+        const row = matches[0];
+        if (index === parts.length - 1) return row;
+        if (row.getAttribute('aria-expanded') !== 'true') throw new Error('The ancestor folder must be expanded before cleanup.');
+        const sibling = row.nextElementSibling;
+        group = sibling?.getAttribute('role') === 'tree' ? sibling : row.querySelector('[role="tree"]');
+      }
+      return null;
+    }
+    // Native folder Delete can remove a subtree. Read/empty checks cannot
+    // make that mutation conditional on the subtree staying empty. Retain the
+    // proof for explicit native cleanup; never click Delete automatically.
+    async function cleanupCreatedDirectories(proofs, options = {}) {
+      const items = Array.isArray(proofs) ? proofs : [];
+      const removed = [], completed = new Set(), failures = [], review = [];
+      for (const proof of items.slice().sort((a, b) => String(b?.path || '').split('/').length - String(a?.path || '').split('/').length)) {
+        try {
+          const path = normalizeSafeProjectPath(proof?.path);
+          if (proof?.v !== 1 || !path || path !== proof.path || !proof.projectId || !proof.nativeFolderId
+            || (options.projectId && proof.projectId !== options.projectId)) throw new Error('The created folder identity is not proven.');
+          const assertCurrent = () => assertVerificationOwner(proof.projectId, options.isCurrent);
+          const exactRow = () => {
+            const row = locateOwnedFolder(path);
+            if (row && folderIdentity(row) !== proof.nativeFolderId) throw new Error('The created folder identity changed.');
+            return row;
+          };
+          assertCurrent();
+          for (let depth = 1; depth <= path.split('/').length; depth++) {
+            const prefix = path.split('/').slice(0, depth).join('/'), row = locateOwnedFolder(prefix);
+            if (!row) break;
+            if (prefix === path && folderIdentity(row) !== proof.nativeFolderId) throw new Error('The created folder identity changed.');
+            if (row.getAttribute('aria-expanded') === 'true') continue;
+            const toggle = row.querySelector('.folder-expand-collapse-button');
+            if (!toggle) throw new Error('The folder cannot be expanded safely.');
+            assertCurrent(); toggle.click();
+            const deadline = now() + 5000;
+            while (locateOwnedFolder(prefix)?.getAttribute('aria-expanded') !== 'true') {
+              assertCurrent(); if (now() >= deadline) throw new Error('The folder expansion was not confirmed.');
+              await delay(100); invalidateDomProjectPathCache();
+            }
+          }
+          exactRow();
+          const snapshot = await readServerSnapshot({ projectId: proof.projectId, isCurrent: options.isCurrent, includeBinaryFiles: true });
+          assertCurrent();
+          const row = exactRow();
+          const entries = [...snapshot.files, ...(snapshot.skipped || []), ...(snapshot.capabilities?.skipped || [])];
+          const serverHasEntries = entries.some(entry => String(entry?.path || '').startsWith(path + '/'));
+          if (!row) {
+            if (serverHasEntries) throw new Error('Server entries remain under the folder path; absence is unconfirmed.');
+            completed.add(proof); removed.push({ ...proof, alreadyAbsent: true, verification: 'overleaf-native-tree-and-zip' }); continue;
+          }
+          const sibling = row.nextElementSibling;
+          const group = sibling?.getAttribute('role') === 'tree' ? sibling : row.querySelector('[role="tree"]');
+          if (row.getAttribute('aria-expanded') !== 'true' || !group?.children) throw new Error('The folder contents are unknown.');
+          const inner = Array.from(group.children).find(node => node.classList?.contains('file-tree-folder-list-inner')) || group;
+          const empty = inner.children.length === 0 && !serverHasEntries;
+          review.push({ ...proof, empty, requiresExplicitCleanup: true });
+          failures.push({ path, code: empty ? 'directory_requires_explicit_cleanup' : 'created_directory_not_empty',
+            reason: empty ? 'The new empty folder remains. Review and remove it through Overleaf if appropriate.'
+              : 'The created folder contains entries or unread files and was left untouched.' });
+        } catch (error) { failures.push({ path: proof?.path || '', code: error?.code || 'created_directory_cleanup_unconfirmed', reason: error?.message || '' }); }
+      }
+      return { ok: completed.size === items.length, removed, remaining: items.filter(item => !completed.has(item)),
+        failures, review, requiresExplicitCleanup: review.length > 0, changedDocument: false };
+    }
+    return { folderIdentity, cleanupCreatedDirectories };
+  }
+  return { create };
+});

package/extension/src/page/referenceProjects.js

@@ -113,6 +113,7 @@
         }, { projectId, signal: controller.signal });
         if (controller.signal.aborted) throw failure('reference_read_cancelled', 'Reference reading was cancelled.');
         if (!snapshot?.ok) throw failure('reference_project_unavailable', snapshot?.reason || 'The reference project could not be read.');
+        if (snapshot.pathIdentityComplete === false) throw failure('reference_project_incomplete', 'Some ZIP file identities could not be read unambiguously.');
         const files = (snapshot.files || []).filter(file => /\.tex$/i.test(file.path || ''));
         if (!files.length) throw failure('reference_project_empty', 'This project contains no readable TeX files.');
         if (files.length > 1000 || files.some(file => typeof file.content !== 'string')) {

package/extension/src/page/reviewContext.js

@@ -0,0 +1,113 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafReviewContext = api;
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  const cancelledOwners = new Map();
+  function cancelOwner(token) {
+    if (typeof token !== 'string' || !token || token.length > 256) return false;
+    for (const [id, until] of cancelledOwners) if (until <= Date.now()) cancelledOwners.delete(id);
+    cancelledOwners.set(token, Date.now() + 120000); return true;
+  }
+
+  // One context per request. The small response reserve lets an expired review
+  // return its known partial evidence before the caller's transport timer fires.
+  function create(deps, input = {}) {
+    const now = deps.now || Date.now;
+    const timers = typeof deps.window?.setTimeout === 'function' ? deps.window : globalThis;
+    const started = now(), limit = input.deadlineAt == null ? started + 120000 : input.deadlineAt;
+    const deadlineAt = Number.isFinite(limit) ? limit - Math.min(250, Math.max(0, limit - started) / 10) : started;
+    const cancellation = deps.readWriteCancellationSequence?.();
+    const appliedLists = new Set(), observations = new Map();
+    let stopped = null, mutationStarted = false;
+    const params = { ...input, deadlineAt };
+    const failure = (code, reason) => ({ ok: false, code, reason, changedDocument: false,
+      failure: { code: code === 'codex_cancelled' ? 'codex_run_cancelled' : 'tracked_changes_remain',
+        stage: 'reviewing', severity: 'blocked', terminalState: 'blocked', changedDocument: false,
+        userMessage: reason, nextAction: 'Check the retained per-file results in Overleaf before retrying.',
+        evidence: { originalCode: code, writeStarted: false } } });
+    function check() {
+      if (stopped) return stopped;
+      if (params.reviewOwnerToken && cancelledOwners.has(params.reviewOwnerToken))
+        return stopped = failure('codex_cancelled', 'The Undo owner disconnected; no further review writes were started.');
+      if (!Number.isFinite(limit) || now() >= deadlineAt)
+        return stopped = failure('writeback_deadline_exceeded', 'The review time budget expired; no further review writes were started.');
+      if (typeof deps.readWriteCancellationSequence === 'function' && deps.readWriteCancellationSequence() !== cancellation)
+        return stopped = failure('codex_cancelled', 'The review was cancelled; no further review writes were started.');
+      const project = deps.getProjectId?.() || /\/project\/([^/?#]+)/.exec(deps.window?.location?.pathname || '')?.[1];
+      if (!params.runProjectId || (project && project !== params.runProjectId))
+        return stopped = failure('aborted_project_changed', 'The original review project is no longer active.');
+      const blocked = deps.checkWritebackRunProjectId?.(params);
+      if (blocked) return stopped = blocked.skipped?.[0]?.result || blocked;
+      return null;
+    }
+    function assert() {
+      const blocked = check();
+      if (blocked) throw Object.assign(new Error(blocked.reason || blocked.code), { reviewFailure: blocked });
+    }
+    async function wait(work) {
+      assert();
+      let timer;
+      try {
+        const timeout = new Promise((_, reject) => {
+          timer = timers.setTimeout(() => {
+            const blocked = check() || failure('writeback_deadline_exceeded', 'The review time budget expired.');
+            stopped = blocked;
+            reject(Object.assign(new Error(blocked.reason), { reviewFailure: blocked }));
+          }, Math.max(0, deadlineAt - now()));
+        });
+        const result = await Promise.race([Promise.resolve().then(() => { assert(); return work(); }), timeout]);
+        assert();
+        return result;
+      } finally { if (timer != null) timers.clearTimeout(timer); }
+    }
+    const remember = entry => {
+      if (entry.result?.changedDocument === true || entry.result?.failure?.changedDocument === true) mutationStarted = true;
+      const ref = entry.trackedChange || { path: entry.operation?.path || '', key: 'snapshot-undo:' + (entry.operation?.path || ''), id: '' };
+      observations.set(ref.path + '\0' + (ref.key || ref.id || ''), { trackedChange: ref, result: entry.result });
+    };
+    const scoped = { ...deps, reviewGuard: check, reviewAwait: work => wait(work),
+      reviewDeadlineAt: deadlineAt,
+      createReviewApplied() { const list = []; appliedLists.add(list); return list; } };
+    for (const name of ['openFileByPath', 'setReviewingEnabled', 'verifyActiveEditorText']) {
+      if (typeof deps[name] === 'function') scoped[name] = (...args) => wait(() => deps[name](...args));
+    }
+    scoped.delay = ms => wait(() => deps.delay(Math.min(ms, Math.max(0, deadlineAt - now()))));
+    if (typeof deps.readActiveEditorText === 'function') scoped.readActiveEditorText = (...args) => { assert(); return deps.readActiveEditorText(...args); };
+    if (typeof deps.clickNode === 'function') scoped.clickNode = (...args) => { assert(); mutationStarted = true; return deps.clickNode(...args); };
+    for (const name of ['applyOperationsCore', 'applyOperationsWithNoTraceUndo']) {
+      if (typeof deps[name] !== 'function') continue;
+      scoped[name] = async (operations, options = {}) => {
+        assert();
+        const result = await deps[name](operations, { ...options, deadlineAt,
+          reviewGuard: check, reviewAwait: work => wait(work),
+          onOperationResult(entry) { remember(entry); options.onOperationResult?.(entry); } });
+        for (const entry of result.applied || []) remember(entry);
+        // Preserve a completed in-flight result even if cancellation just arrived.
+        return result;
+      };
+    }
+    if (typeof deps.confirmReviewWriteback === 'function') scoped.confirmReviewWriteback = async (original, result) => {
+      for (const entry of result.applied || []) remember(entry);
+      return deps.confirmReviewWriteback({ ...original, deadlineAt, reviewGuard: check, reviewAwait: work => wait(work) }, result);
+    };
+    async function run(work) {
+      try { assert(); return await work(scoped, params); }
+      catch (error) {
+        if (!error?.reviewFailure) throw error;
+        for (const list of appliedLists) for (const entry of list) remember(entry);
+        const applied = [...observations.values()].filter(entry => entry.result?.ok !== false);
+        const path = deps.getActiveFilePath?.() || '';
+        const changedDocument = mutationStarted || applied.some(entry => entry.result?.changedDocument !== false);
+        const blocked = { ...error.reviewFailure, changedDocument,
+          failure: { ...error.reviewFailure.failure, changedDocument,
+            evidence: { ...error.reviewFailure.failure?.evidence, writeStarted: changedDocument } } };
+        return { ok: false, applied, skipped: [{ trackedChange: { path }, result: blocked }] };
+      }
+    }
+    return Object.freeze({ run, check, assert, wait, params, scoped });
+  }
+  return Object.freeze({ create, cancelOwner });
+});

package/extension/src/page/saveState.js

@@ -311,16 +311,18 @@
         expected.set(path, entry.result.verifiedContent);
       }
     }
-    const deadline = now() + Math.max(0, timeoutMs);
+    const deadline = Math.min(now() + Math.max(0, timeoutMs), params.deadlineAt == null ? Infinity
+      : Number.isFinite(params.deadlineAt) ? params.deadlineAt : now());
     let attempts = 0;
     if (expected.size && typeof readSnapshot === 'function') {
       do {
-        if (!params.runProjectId || getProjectId() !== params.runProjectId) break;
+        if (now() >= deadline || params.reviewGuard?.() || !params.runProjectId || getProjectId() !== params.runProjectId) break;
         try {
-          const snapshot = await readSnapshot({ force: true, maxAgeMs: 0,
+          const read = () => readSnapshot({ force: true, maxAgeMs: 0,
             zipTimeoutMs: Math.max(1, Math.min(8000, deadline - now())) });
+          const snapshot = params.reviewAwait ? await params.reviewAwait(read) : await read();
           attempts++;
-          if (getProjectId() !== params.runProjectId) break;
+          if (now() >= deadline || params.reviewGuard?.() || getProjectId() !== params.runProjectId) break;
           if (snapshot?.ok === true && Array.from(expected).every(([path, content]) =>
             snapshot.files?.some(file => file.path === path && file.source === 'overleaf-zip'
               && file.content === content))) {