codex-overleaf-link 2.5.0 → 2.5.1

package/extension/src/page/binaryAssetUploader.js

@@ -42,6 +42,9 @@
       if (!/^[a-f0-9]{64}$/i.test(String(params.sha256 || ''))) {
         return failure('binary_asset_hash_invalid', 'Asset SHA-256 is missing or invalid.');
       }
+      if (params.overwrite === true && !/^[a-f0-9]{64}$/i.test(String(params.previousSha256 || ''))) {
+        return failure('binary_asset_baseline_missing', 'The original binary version is unavailable. Read the project again before replacing this file.');
+      }
       pruneReceipts();
       if (transfers.has(transferId) || receipts.has(transferId)) {
         return failure('binary_upload_transfer_conflict', 'Asset transfer ID is already in use.');
@@ -54,9 +57,11 @@
         path: projectPath,
         size,
         sha256: String(params.sha256).toLowerCase(),
+        previousSha256: params.overwrite === true ? String(params.previousSha256).toLowerCase() : '',
         mimeType: String(params.mimeType || 'application/octet-stream'),
         projectId: treeOperations.getProjectId(),
         overwrite: params.overwrite === true,
+        createdDirectories: [], folderChanged: false, fileUploadAttempted: false,
         chunks: [],
         received: 0
       });
@@ -96,11 +101,19 @@
       transfer.promise = commitOnce(params).catch(error => ({
         ...failure(error.code || 'binary_upload_failed', error.message),
         changedDocument: transfer.mutationAttempted === true
-      })).then(result => {
-        transfer.result = result;
+      })).then(async result => {
+        if (result.ok !== true && transfer.createdDirectories.length && typeof deps.cleanupCreatedDirectories === 'function') {
+          try {
+            const cleanup = await deps.cleanupCreatedDirectories(transfer.createdDirectories, {
+              projectId: transfer.projectId, isCurrent: () => treeOperations.getProjectId() === transfer.projectId && receipts.get(id) === transfer
+            });
+            transfer.createdDirectories = cleanup.remaining || transfer.createdDirectories;
+          } catch (_error) { /* Retain ownership proofs when cleanup cannot be confirmed. */ }
+        }
+        transfer.result = { ...result, ...directoryFacts(transfer, result.ok !== true) };
         transfer.finishedAt = Date.now();
         transfer.chunks = [];
-        return result;
+        return transfer.result;
       });
       return transfer.promise;
     }
@@ -112,11 +125,12 @@
         || treeOperations.getProjectId() !== transfer.projectId) {
         return failure('binary_upload_receipt_missing', 'Asset upload receipt is unavailable for this project.');
       }
-      if (transfer.result?.ok !== true && transfer.mutationAttempted === true) {
+      if (transfer.result?.ok !== true && transfer.fileUploadAttempted === true) {
         const evidence = await waitForPath(transfer, {}, 2500).catch(() => null);
         if (evidence?.hashVerified === true) {
           transfer.result = { ok: true, written: true, path: transfer.path,
-            changedDocument: true, method: 'remote-hash-reconciliation' };
+            changedDocument: true, method: 'remote-hash-reconciliation', ...directoryFacts(transfer),
+            entityId: evidence.observed?.id || readTreeEntityId(evidence.observed), sha256: transfer.sha256 };
         }
       }
       return { ok: true, transferId: transfer.id, runProjectId: transfer.projectId,
@@ -156,17 +170,22 @@
             assertTransferProject(transfer);
             const overwriteVerified = hashVerified || result?.confirmedByTransport === true;
             if (result?.ok && observed && overwriteVerified) {
-              return { ok: true, written: true, path: transfer.path, method: result.method, changedDocument: true };
+              return { ok: true, written: true, path: transfer.path, method: result.method, changedDocument: true,
+                entityId: observed.id || observed._id || observed.entityId || observed.fileId || '', sha256: transfer.sha256 };
             }
             if (result?.ok && observed && !overwriteVerified) errors.push('Overleaf did not expose enough evidence to verify the binary replacement.');
             if (result?.reason) errors.push(result.reason);
           } catch (error) {
+            if (error?.code?.startsWith('binary_asset_baseline_')) return {
+              ...failure(error.code, error.message), changedDocument: transfer.mutationAttempted === true
+            };
             errors.push(error.message);
           }
           // Once submission may have happened, changing transports can duplicate
           // or overwrite a successful upload. Reconcile the same attempt instead.
           if (transfer.mutationAttempted === true) {
-            const evidence = await waitForPath(transfer, {}, 12000).catch(() => null);
+            const evidence = transfer.fileUploadAttempted === true
+              ? await waitForPath(transfer, {}, 12000).catch(() => null) : null;
             if (evidence?.hashVerified === true) {
               return { ok: true, written: true, path: transfer.path,
                 method: 'remote-hash-reconciliation', changedDocument: true };
@@ -194,6 +213,12 @@
       }
     }
 
+    function directoryFacts(transfer, requireCleanup = false) {
+      return { createdDirectories: transfer.createdDirectories.map(proof => ({ ...proof })),
+        folderChanged: transfer.folderChanged === true, fileUploadAttempted: transfer.fileUploadAttempted === true,
+        directoryCleanupRequired: requireCleanup && transfer.createdDirectories.length > 0 };
+    }
+
     async function uploadWithMultipart(file, transfer) {
       const projectId = treeOperations.getProjectId();
       if (!projectId || typeof windowRef.fetch !== 'function') return { ok: false, reason: 'Project upload endpoint is unavailable.' };
@@ -208,7 +233,11 @@
       const headers = csrf ? { 'X-CSRF-Token': csrf } : {};
       const query = folderId ? `?folder_id=${encodeURIComponent(folderId)}` : '';
       assertTransferProject(transfer);
+      await assertBinaryBaseline(transfer);
+      if (parentPath && await findFolderId(parentPath) !== folderId) throw baselineError('The target folder changed before replacement.');
+      assertTransferProject(transfer);
       transfer.mutationAttempted = true;
+      transfer.fileUploadAttempted = true;
       const response = await windowRef.fetch(`/project/${encodeURIComponent(projectId)}/upload${query}`, {
         method: 'POST', body: form, credentials: 'same-origin', headers
       });
@@ -231,15 +260,24 @@
 
     async function uploadWithDom(file, transfer) {
       const parentPath = transfer.path.split('/').slice(0, -1).join('/');
-      if (typeof deps.prepareUploadParent !== 'function') {
+      if (typeof deps.prepareUploadParent !== 'function' || typeof deps.isUploadParentCurrent !== 'function') {
         return { ok: false, reason: 'Verified folder selection is unavailable for asset upload.' };
       }
-      await deps.prepareUploadParent(parentPath, {
+      transfer.uploadParent = await deps.prepareUploadParent(parentPath, {
         createMissing: true,
-        onMutation: () => { transfer.mutationAttempted = true; },
+        onMutation: () => { transfer.mutationAttempted = true; transfer.folderChanged = true; },
+        onCreatedDirectory: proof => {
+          if (proof?.v !== 1 || proof.projectId !== transfer.projectId || typeof proof.path !== 'string'
+            || !transfer.path.startsWith(proof.path + '/')) return;
+          const next = { v: 1, projectId: proof.projectId, path: proof.path, nativeFolderId: String(proof.nativeFolderId || ''),
+            ownershipConfirmed: proof.ownershipConfirmed === true, observedAfterCreate: proof.observedAfterCreate === true };
+          const index = transfer.createdDirectories.findIndex(value => value.path === proof.path);
+          if (index >= 0) transfer.createdDirectories[index] = next; else transfer.createdDirectories.push(next);
+        },
         isCurrent: () => treeOperations.getProjectId() === transfer.projectId && transfers.get(transfer.id) === transfer
       });
       assertTransferProject(transfer);
+      transfer.uploadParentPath = parentPath;
       let input = findFileInput();
       if (!input) {
         const button = findUploadButton();
@@ -251,8 +289,13 @@
       const data = new windowRef.DataTransfer();
       data.items.add(file);
       assertTransferProject(transfer);
+      await assertBinaryBaseline(transfer);
+      assertTransferProject(transfer);
+      if (deps.isUploadParentCurrent(parentPath, transfer.uploadParent) !== true) throw baselineError('The selected upload folder changed before submission.');
+      if (input.isConnected === false || findFileInput() !== input) throw baselineError('The upload input changed before submission.');
       assignFilesToInput(input, data.files, windowRef);
       transfer.mutationAttempted = true;
+      transfer.fileUploadAttempted = true;
       input.dispatchEvent(new windowRef.Event('input', { bubbles: true }));
       input.dispatchEvent(new windowRef.Event('change', { bubbles: true }));
       await clickReplaceIfShown(transfer);
@@ -265,10 +308,14 @@
       for (const name of ['uploadFile', 'uploadAsset', 'createBinaryFile', 'createFile', 'addFile']) {
         if (typeof manager[name] !== 'function') continue;
         try {
+          await assertBinaryBaseline(transfer);
+          assertTransferProject(transfer);
+          if (treeOperations.findFileTreeManager() !== manager) throw baselineError('The upload manager changed before submission.');
           transfer.mutationAttempted = true;
+          transfer.fileUploadAttempted = true;
           await manager[name](transfer.path, file);
           return { ok: true, method: `fileTreeManager.${name}`, confirmedByTransport: true };
-        } catch (error) { return { ok: false, reason: error.message }; }
+        } catch (error) { if (error?.code?.startsWith('binary_asset_baseline_')) throw error; return { ok: false, reason: error.message }; }
       }
       return { ok: false, reason: 'Legacy file-tree manager has no compatible asset method.' };
     }
@@ -322,9 +369,84 @@
       await delay(180);
       assertTransferProject(transfer);
       if (!transfer.overwrite) return;
-      const button = Array.from(documentRef.querySelectorAll('[role="dialog"] button')).find(node => !isCodexOwnedNode(node)
-        && /replace|overwrite|替换|覆盖/i.test(node.textContent || ''));
-      if (button) button.click();
+      const candidates = () => Array.from(documentRef.querySelectorAll('[role="dialog"] button')).filter(node => !isCodexOwnedNode(node)
+        && /^(replace|overwrite|替换|覆盖)(?:\b|\s|$)/i.test(String(node.textContent || '').trim()));
+      const buttons = candidates();
+      if (!buttons.length) return;
+      const matchesTarget = node => {
+        const dialog = node.closest?.('[role="dialog"]');
+        const text = String(dialog?.textContent || '');
+        return [transfer.path, transfer.path.split('/').pop()].some(path =>
+          new RegExp('(^|[^\\w./-])' + path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '($|[^\\w./-])').test(text));
+      };
+      const intended = buttons.filter(matchesTarget);
+      if (intended.length !== 1) throw baselineError('The replacement dialog could not be bound to the target file.');
+      const button = intended[0], dialog = button.closest('[role="dialog"]');
+      await assertBinaryBaseline(transfer);
+      assertTransferProject(transfer);
+      if (deps.isUploadParentCurrent(transfer.uploadParentPath, transfer.uploadParent) !== true) throw baselineError('The selected upload folder changed before replacement confirmation.');
+      const current = candidates().filter(matchesTarget);
+      if (current.length !== 1 || current[0] !== button || button.isConnected === false
+        || button.closest('[role="dialog"]') !== dialog) throw baselineError('The replacement dialog changed before confirmation.');
+      button.click();
+    }
+    async function binaryIdentity(transfer) {
+      assertTransferProject(transfer);
+      const nativeRoot = documentRef.querySelector?.('[data-testid="file-tree-list-root"]');
+      // The generic adapter may resolve a root basename to another folder.
+      // Only the native ancestry or an exact metadata path can bind old bytes.
+      const node = nativeRoot ? findNativeTreeNode(transfer.path, 'file') : null;
+      let id = readTreeEntityId(node);
+      if (!id) {
+        const list = await snapshotRouter?.buildProjectFileList({ force: true, maxAgeMs: 0, preferLightweight: true, allowZipFallback: false });
+        const file = list?.files?.find(file => file.path === transfer.path);
+        id = file?.id || file?._id || file?.entityId || file?.fileId || '';
+      }
+      assertTransferProject(transfer);
+      return id;
+    }
+    async function assertBinaryBaseline(transfer) {
+      if (!transfer.overwrite) return;
+      const { id, digest } = await readBaselineDigest(transfer);
+      assertTransferProject(transfer);
+      if (digest !== transfer.previousSha256) throw baselineError('The binary file changed since Codex read it. Read the project again before replacing it.');
+      transfer.previousEntityId = id;
+    }
+    function baselineError(message) { return Object.assign(new Error(message), { code: 'binary_asset_baseline_changed' }); }
+    async function readBaselineDigest(transfer) {
+      const controller = new AbortController();
+      let timer, reader;
+      const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => {
+        controller.abort(); reader?.cancel().catch(() => {});
+        reject(baselineError('Reading the original binary file timed out.'));
+      }, 8000); });
+      try {
+        return await Promise.race([timeout, (async () => {
+          const id = await binaryIdentity(transfer);
+          if (controller.signal.aborted) throw baselineError('Reading the original binary file timed out.');
+          if (!id || (transfer.previousEntityId && transfer.previousEntityId !== id)) throw baselineError('The binary file identity changed before replacement.');
+          const response = await windowRef.fetch(`/project/${encodeURIComponent(transfer.projectId)}/file/${encodeURIComponent(id)}`, {
+            credentials: 'same-origin', cache: 'no-store', signal: controller.signal
+          });
+          if (!response.ok || Number(response.headers?.get?.('content-length')) > MAX_ASSET_BYTES) throw baselineError('The original binary file is unavailable or exceeds the read limit.');
+          let bytes;
+          if (response.body?.getReader) {
+            reader = response.body.getReader(); const chunks = []; let size = 0;
+            for (;;) { const chunk = await reader.read(); if (chunk.done) break;
+              size += chunk.value.byteLength;
+              if (size > MAX_ASSET_BYTES) throw baselineError('The original binary file exceeds the read limit.');
+              chunks.push(chunk.value);
+            }
+            bytes = joinChunks(chunks, size);
+          } else bytes = new Uint8Array(await response.arrayBuffer());
+          if (bytes.byteLength > MAX_ASSET_BYTES) throw baselineError('The original binary file exceeds the read limit.');
+          const digest = await sha256Hex(bytes, windowRef.crypto);
+          if (await binaryIdentity(transfer) !== id) throw baselineError('The binary file identity changed while its original bytes were read.');
+          assertTransferProject(transfer);
+          if (controller.signal.aborted) throw baselineError('Reading the original binary file timed out.');
+          return { id, digest };
+        })()]);
+      } finally { clearTimeout(timer); controller.abort(); reader?.cancel().catch(() => {}); }
     }
     function readTreeEntityId(node) {
       const owner = node?.closest?.('[data-entity-id], [data-file-id], [data-folder-id], [data-id]');

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/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')) {