codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/page/writebackRouter.js

@@ -1,11 +1,12 @@
 (function initCodexOverleafWritebackRouter(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(require('./treeOperations'));
   } else {
-    root.CodexOverleafWritebackRouter = factory();
+    root.CodexOverleafWritebackRouter = factory(root.CodexOverleafTreeOperations);
   }
-})(typeof window !== 'undefined' ? window : globalThis, function writebackRouterFactory() {
+})(typeof window !== 'undefined' ? window : globalThis, function writebackRouterFactory(TreeOperations) {
   'use strict';
+  const { fileTreeMethodNames } = TreeOperations;
 
   function create(deps = {}) {
     const window = deps.window || (typeof globalThis !== 'undefined' ? globalThis : {});
@@ -17,6 +18,7 @@
       ? Math.max(0, Number(deps.writebackOpenSettleMs))
       : 1200;
     const diagnosticsRevision = String(deps.diagnosticsRevision || '');
+    const now = deps.now || Date.now;
     // Cross-world cancel signal reader. Returns the current page-bridge
     // sequence number, which monotonically increments when content-side
     // calls pageBridge.cancelActiveWrite. applyOperationsCore captures the
@@ -269,6 +271,11 @@
         fallbackUserMessage: 'The edit anchor no longer matches current Overleaf content.',
         fallbackNextAction: 'Rerun the task against the current document.'
       },
+      write_operation_failed: {
+        stage: 'write', severity: 'error', defaultRetryable: true,
+        fallbackUserMessage: 'Editor write call failed.',
+        fallbackNextAction: 'Retry after the editor is stable.'
+      },
       write_observed_mismatch: {
         stage: 'verify', severity: 'error', defaultRetryable: false,
         fallbackUserMessage: 'Codex attempted to write, but the content read back from Overleaf did not match the approved change.',
@@ -352,7 +359,9 @@
 
   async function applyOperations(operations, options = {}) {
     if (options.reviewingPolicy === 'no-trace-undo') {
-      return applyOperationsWithNoTraceUndo(operations, options);
+      const Context = window.CodexOverleafReviewContext || (typeof module === 'object' && module.exports ? require('./reviewContext') : null);
+      return Context.create({ window, now, readWriteCancellationSequence, getProjectId: () => treeOperations.getProjectId?.() }, options).run(
+        (scoped, input) => applyOperationsWithNoTraceUndo(operations, { ...input, reviewGuard: scoped.reviewGuard, reviewAwait: scoped.reviewAwait }));
     }
     const hasOperations = (operations || []).length > 0;
     const trackReviewingChanges = options.requireReviewing === true && hasOperations;
@@ -382,6 +391,7 @@
     }
     const result = await applyOperationsCore(operations, {
       ...options,
+      noTraceUndo: false,
       trackReviewingChanges
     });
     return reviewingPolicy
@@ -392,13 +402,16 @@
       : result;
   }
 
-  async function confirmNoTraceUndoEditing() {
+  async function confirmNoTraceUndoEditing(options = {}) {
     let changed = false;
     let toggle = { ok: true, changed: false, enabled: false };
     for (let attempt = 0; attempt < 2; attempt++) {
+      const blocked = options.reviewGuard?.();
+      if (blocked) return blocked;
       if (!isEditingConfirmedForNoTraceUndo(getReviewingState({}))) {
         toggle = await setReviewingEnabled(false, { waitMs: 1800 });
-        if (!toggle.ok) return toggle;
+        if (!toggle.ok && (!['editing_not_confirmed', 'reviewing_disable_failed'].includes(toggle.code)
+          || !isEditingConfirmedForNoTraceUndo(getReviewingState({})))) return toggle;
         changed = changed || toggle.changed === true;
       }
       await delay(180);
@@ -411,8 +424,13 @@
       reason: 'Overleaf Editing mode did not remain confirmed before undo; no undo write was started.' };
   }
 
+  async function awaitReview(options, work) {
+    try { return options.reviewAwait ? await options.reviewAwait(work) : await work(); }
+    catch (error) { if (error?.reviewFailure) return error.reviewFailure; throw error; }
+  }
+
   async function applyOperationsWithNoTraceUndo(operations, options = {}) {
-    const disabled = await confirmNoTraceUndoEditing();
+    const disabled = await awaitReview(options, () => confirmNoTraceUndoEditing(options));
     if (!disabled.ok) return buildNoTraceUndoBlockedResult(operations, disabled);
     const result = await applyOperationsCore(operations, {
       ...options, noTraceUndo: true, trackReviewingChanges: false
@@ -434,33 +452,15 @@
     const safeBaseFiles = normalizeBaseFilesForSafety(options.baseFiles);
     const baseFileLookup = window.CodexOverleafStaleGuard?.buildBaseFileLookup(safeBaseFiles);
     const baseBinaryFileLookup = buildBaseBinaryFileLookup(safeBaseFiles);
-    // Mid-run project-change guard. The pageBridge wrapper already ran the
-    // writeGuard once at entry, but each per-op step here can take 0.5-5s
-    // (openFileByPath, waitForActiveEditorText, save-state verification),
-    // so a multi-op write can span 10-30 seconds total. If the user SPA-
-    // navigates to a different project mid-flight, the remaining operations
-    // would land in the wrong project. Re-check the editor project before
-    // each op and short-circuit the rest of the queue when it diverges.
+    // Recheck project identity between awaited operations and before each write.
     const runProjectId = typeof options.runProjectId === 'string' ? options.runProjectId : '';
     const writeGuardSurface = window.CodexOverleafWriteGuard?.create({
       window,
       document: window.document,
       treeOperations
     });
-    // Cross-world cancel baseline. The user clicks cancel during writeback →
-    // content-side calls pageBridge.cancelActiveWrite → the sequence number
-    // bumps. Two layers of responsiveness:
-    //   1. Between-ops check — short-circuits the next iteration so the
-    //      remaining ops never start.
-    //   2. Race the in-flight op against a cancellation poller (50ms
-    //      interval) so a click DURING a slow op (e.g. inside a 5s
-    //      waitForActiveFile poll) is observed within ~50ms instead of
-    //      having to wait out the op's internal timeout. The op promise
-    //      keeps running in the page world after the race resolves — its
-    //      eventual result is ignored. This is "user-perceived instant
-    //      cancel": the spinner stops, the run settles to cancelled, and
-    //      any DOM mutation already in flight on the op cannot be undone
-    //      from here anyway.
+    // Preserve the actual result of an in-flight operation so its readback and
+    // undo evidence survive cancellation. The checkpoints stop undispatched work.
     const cancelBaselineSequence = readWriteCancellationSequence();
     const cancelledSkipResult = {
       ok: false,
@@ -477,103 +477,78 @@
         changedDocument: false
       }
     };
-    const cancelledInFlightResult = {
-      ...cancelledSkipResult,
-      reason: 'The Codex run was cancelled while an Overleaf write operation was already in flight. The editor may have changed; review the current file before starting a new run.',
-      failure: {
-        ...cancelledSkipResult.failure,
-        severity: 'warning',
-        userMessage: 'The Codex run was cancelled during an in-flight write. The editor may already contain part of that write.',
-        nextAction: 'Review the current Overleaf file before starting a new run.',
-        changedDocument: true
+    const createCandidates = operations.map(normalizeOperationPaths).filter(operation => operation.type === 'create'
+      && operations.filter(other => [other.path, other.to].includes(operation.path)).length === 1);
+    const createBatch = createCandidates.length && typeof deps.beginTextCreateBatch === 'function'
+      ? await deps.beginTextCreateBatch(createCandidates, { isCurrent: () =>
+        treeOperations.getProjectId?.() === runProjectId && readWriteCancellationSequence() === cancelBaselineSequence }) : null;
+    const deferredCreates = [];
+    let haltRemainingOperations = false;
+    const skipTail = (operation, result) => operations.slice(operations.indexOf(operation) + 1)
+      .forEach(tail => skipped.push({ operation: normalizeOperationPaths(tail), result }));
+    const reopenQueue = [];
+    const deadlineFailure = () => Number.isFinite(options.deadlineAt) && now() >= options.deadlineAt
+      ? { ok: false, code: 'writeback_deadline_exceeded', changedDocument: false,
+        reason: 'The undo time budget expired before this operation could start.' } : null;
+    const editOptions = () => ({ baseFileLookup, runProjectId, deadlineAt: options.deadlineAt,
+      reviewGuard: options.reviewGuard, reviewAwait: options.reviewAwait,
+      recheckWriteProject: writeGuardSurface ? () => {
+        const expired = options.reviewGuard?.() || deadlineFailure();
+        return expired ? { applied: [], skipped: [{ operation: {}, result: expired }] }
+          : writeGuardSurface.runWriteGuard({ runProjectId });
+      } : null,
+      trackReviewingChanges: options.trackReviewingChanges === true, noTraceUndo: options.noTraceUndo === true });
+    const record = (operation, result) => {
+      if (result.trackedChangeCapture) trackedChangeCaptures.push(result.trackedChangeCapture);
+      if (operation.type === 'edit' && result.ok && Array.isArray(result.trackedChanges)) {
+        trackedChanges.push(...result.trackedChanges);
       }
+      (result.ok ? applied : skipped).push({ operation, result });
+      options.onOperationResult?.({ operation, result });
     };
-    // 50ms-poller racer using recursive setTimeout. setInterval is NOT
-    // exposed in the test VM context that hosts pageBridge (only setTimeout /
-    // clearTimeout are wired), so this implementation must avoid it. Each
-    // tick re-schedules itself only while the racer has not resolved;
-    // dispose() flips a flag so any tick that fires after dispose is a no-op.
-    // Resolves the first time the cancellation sequence bumps past baseline.
-    function createCancellationRacer() {
-      let resolved = false;
-      let resolveFn;
-      const promise = new Promise(resolve => { resolveFn = resolve; });
-      let timer = null;
-      function tick() {
-        if (resolved) return;
-        if (readWriteCancellationSequence() !== cancelBaselineSequence) {
-          resolved = true;
-          resolveFn();
-          return;
-        }
-        timer = window.setTimeout(tick, 50);
-      }
-      timer = window.setTimeout(tick, 50);
-      return {
-        promise,
-        dispose() {
-          resolved = true;
-          if (timer) window.clearTimeout(timer);
-        }
-      };
-    }
-    const CANCELLED_RACE_SENTINEL = Symbol('writebackRouter.cancelled');
-    async function raceOpAgainstCancellation(opPromise) {
-      // Once an editor operation starts, preserve its actual result and undo
-      // metadata. The loop's pre-operation cancellation check stops the tail.
-      return await opPromise;
-    }
 
     for (const rawOperation of operations) {
-      // Cross-world cancel check. Cheap (synchronous read of a counter),
-      // runs before the writeGuard re-check so a click-cancel that arrived
-      // during the previous op's await microtasks short-circuits before we
-      // burn time on guard / open-file work for the next op.
+      const reviewBlock = options.reviewGuard?.();
+      if (reviewBlock) {
+        skipped.push({ operation: normalizeOperationPaths(rawOperation), result: reviewBlock });
+        skipTail(rawOperation, reviewBlock); break;
+      }
+      // Stop undispatched work when cancellation arrives during an awaited operation.
       if (readWriteCancellationSequence() !== cancelBaselineSequence) {
         skipped.push({ operation: normalizeOperationPaths(rawOperation), result: cancelledSkipResult });
-        const remainingForCancel = operations.slice(operations.indexOf(rawOperation) + 1);
-        for (const tailOperation of remainingForCancel) {
-          skipped.push({ operation: normalizeOperationPaths(tailOperation), result: cancelledSkipResult });
-        }
+        skipTail(rawOperation, cancelledSkipResult);
         break;
       }
-      // Per-op re-check: if a runProjectId was supplied and the page-side
-      // guard is available, verify the editor still shows the same project
-      // before committing the next write. Mismatch → push aborted_project_changed
-      // for THIS op and every remaining op in the queue, then return.
+      // Re-check project ownership before this operation and preserve every skipped tail entry.
       if (runProjectId && writeGuardSurface) {
         const guardBlock = await writeGuardSurface.runWriteGuard({ runProjectId });
         if (guardBlock) {
-          // First push the guard's structured skip for the current op so the
-          // caller can attribute the abort to a real operation path, then
-          // pad the remaining ops with the same failure shape.
+          // Keep the current path and the remaining operations attributable.
           const guardFailure = guardBlock.skipped[0].result;
           skipped.push({ operation: normalizeOperationPaths(rawOperation), result: guardFailure });
-          const remaining = operations.slice(operations.indexOf(rawOperation) + 1);
-          for (const tailOperation of remaining) {
-            skipped.push({ operation: normalizeOperationPaths(tailOperation), result: guardFailure });
-          }
+          skipTail(rawOperation, guardFailure);
           break;
         }
       }
       const operation = normalizeOperationPaths(rawOperation);
-      const pathSafety = validateOperationProjectPaths(operation);
+      const pathSafety = deadlineFailure() || validateOperationProjectPaths(operation);
       if (!pathSafety.ok) {
         skipped.push({ operation, result: pathSafety });
         continue;
       }
-      let raceResult;
+      let result;
       if (operation.type === 'edit') {
-        raceResult = await raceOpAgainstCancellation(applyEditOperation(operation, {
-          baseFileLookup, runProjectId,
-          recheckWriteProject: writeGuardSurface ? () => writeGuardSurface.runWriteGuard({ runProjectId }) : null,
-          trackReviewingChanges: options.trackReviewingChanges === true,
-          noTraceUndo: options.noTraceUndo === true
-        }));
+        result = await applyEditOperation(operation, editOptions());
+        if (isUntouchedOpenFailure(result)) {
+          reopenQueue.push({ operation, result });
+          continue;
+        }
       } else if (['binary-create', 'overwrite-binary'].includes(operation.type)) {
-        raceResult = await raceOpAgainstCancellation(applyBinaryAssetOperation(operation, { baseFileLookup, baseBinaryFileLookup }));
+        result = await applyBinaryAssetOperation(operation, { baseFileLookup, baseBinaryFileLookup });
       } else if (['create', 'rename', 'move', 'delete'].includes(operation.type)) {
-        raceResult = await raceOpAgainstCancellation(applyFileTreeOperation(operation, { baseFileLookup }));
+        result = await applyFileTreeOperation(operation, { baseFileLookup, runProjectId, deadlineAt: options.deadlineAt, reviewGuard: options.reviewGuard, noTraceUndo: options.noTraceUndo === true,
+          createBatch: createBatch?.targets.has(operation.path) ? createBatch : null,
+          retryCreates: options.retryCreates === true });
       } else {
         skipped.push({
           operation,
@@ -584,27 +559,42 @@
         });
         continue;
       }
-      // Cancellation race winner: skip current op + the rest of the queue.
-      // The op promise above keeps running in background; its eventual
-      // result is discarded. The user perceives instant cancel because we
-      // settle the loop here instead of waiting for the op to finish.
-      if (raceResult === CANCELLED_RACE_SENTINEL) {
-        skipped.push({ operation, result: cancelledInFlightResult });
-        const remainingAfterCancel = operations.slice(operations.indexOf(rawOperation) + 1);
-        for (const tailOperation of remainingAfterCancel) {
-          skipped.push({ operation: normalizeOperationPaths(tailOperation), result: cancelledSkipResult });
-        }
-        break;
+      if (operation.type === 'create' && createBatch?.pending.has(operation.path)
+        && !createBatch.blocked.has(operation.path)) {
+        deferredCreates.push({ operation, result });
+        continue;
       }
-      const result = raceResult;
-      if (result.trackedChangeCapture) trackedChangeCaptures.push(result.trackedChangeCapture);
-      if (operation.type === 'edit' && result.ok && Array.isArray(result.trackedChanges)) {
-        trackedChanges.push(...result.trackedChanges);
+      record(operation, result);
+      if (operation.type === 'move' && operation.moveProof && !result.ok) {
+        haltRemainingOperations = true;
+        skipTail(rawOperation, { ok: false, code: 'file_plan_not_completed', changedDocument: false,
+          reason: 'The file move did not finish; the remaining file plan was not started.' }); break;
       }
-      (result.ok ? applied : skipped).push({ operation, result });
     }
 
-    if (applied.length > 0) {
+    // A file that could not be opened mid-batch usually opens once the
+    // previous document has settled: give untouched open failures one pass.
+    if (!haltRemainingOperations && reopenQueue.length && readWriteCancellationSequence() === cancelBaselineSequence
+      && !skipped.some(entry => entry.result?.code === 'aborted_project_changed')) {
+      await delay(deps.reopenRetryDelayMs ?? 1200);
+    }
+    for (const entry of reopenQueue) {
+      const blocked = options.reviewGuard?.() || haltRemainingOperations || readWriteCancellationSequence() !== cancelBaselineSequence
+        || skipped.some(item => item.result?.code === 'aborted_project_changed')
+        || Boolean(runProjectId && writeGuardSurface && await writeGuardSurface.runWriteGuard({ runProjectId }));
+      const result = blocked ? entry.result : await applyEditOperation(entry.operation, editOptions());
+      record(entry.operation, result);
+    }
+
+    if (deferredCreates.length) {
+      const confirmed = await deps.finishTextCreateBatch(createBatch, deferredCreates, applied);
+      for (const entry of confirmed) {
+        (entry.result.ok ? applied : skipped).push(entry);
+        if (entry.result.ok) recordFileTreeOperationSuccess(entry.operation, baseFileLookup);
+        options.onOperationResult?.(entry);
+      }
+    }
+    if (applied.some(entry => entry.result?.changedDocument !== false)) {
       compileBridge.markSourceEdited();
     }
 
@@ -612,44 +602,26 @@
       ok: skipped.length === 0,
       applied,
       skipped,
+      ...(haltRemainingOperations ? { haltRemainingOperations: true } : {}),
       trackedChanges: trackedChangeCaptures.some(capture => capture.state !== 'observed') ? [] : mergeTrackedChangeRefs(trackedChanges),
       trackedChangeCaptures
     };
   }
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+  const isUntouchedOpenFailure = result => result?.ok === false && result.failure?.code === 'target_file_open_failed'
+    && result.failure.changedDocument === false;
 
   async function applyEditOperation(operation, options = {}) {
+    const reviewBlock = options.reviewGuard?.();
+    if (reviewBlock) return reviewBlock;
     const currentPath = getActiveFilePath();
-    const editorReady = await ensureEditorReadyForOperation(operation, options.baseFileLookup, currentPath);
+    const editorReady = await awaitReview(options, () => ensureEditorReadyForOperation(operation, options.baseFileLookup, currentPath));
     if (!editorReady.ok) {
       return editorReady;
     }
 
     if (options.noTraceUndo === true) {
-      const editing = await confirmNoTraceUndoEditing();
+      const editing = await awaitReview(options, () => confirmNoTraceUndoEditing(options));
       if (!editing.ok) return buildNoTraceUndoBlockedResult([operation], editing).skipped[0].result;
     }
     const trackReviewingChanges = options.trackReviewingChanges === true;
@@ -667,7 +639,8 @@
       options.baseFileLookup
     ) || { ok: true };
     if (!freshness.ok) {
-      const ready = await waitForFreshEditorTextForOperation(operation, options.baseFileLookup, 1500);
+      const ready = await awaitReview(options, () => waitForFreshEditorTextForOperation(operation, options.baseFileLookup, 1500));
+      if (options.reviewGuard?.()) return options.reviewGuard();
       if (!ready.ok) {
         const decorated = attachWritebackDebug(freshness, 'stale_guard', operation, options.baseFileLookup, current, {
           initialActivePath: currentPath,
@@ -707,8 +680,11 @@
     }
 
     let nextContent = null;
+    let preparedPatches;
     if (Array.isArray(operation.patches) && operation.patches.length) {
-      const patched = applyTextPatches(current, operation.patches);
+      preparedPatches = window.CodexOverleafStaleGuard?.prepareOperationPatches(operation, current, options.baseFileLookup)
+        || { ok: true, patches: operation.patches };
+      const patched = preparedPatches.ok ? applyTextPatches(current, preparedPatches.patches) : preparedPatches;
       if (!patched.ok) {
         const decorated = attachWritebackDebug(patched, 'apply_text_patches', operation, options.baseFileLookup, current, {
           initialActivePath: currentPath,
@@ -771,19 +747,34 @@
           reason: 'Overleaf left Editing mode before the undo write.' }).skipped[0].result;
     }
 
+    const finalReviewBlock = options.reviewGuard?.();
+    if (finalReviewBlock) return finalReviewBlock;
     const result = Array.isArray(operation.patches) && operation.patches.length
-      ? replaceActiveEditorPatches(operation.patches, nextContent)
+      ? replaceActiveEditorPatches(preparedPatches.patches, nextContent)
       : replaceActiveEditorText(nextContent);
     if (!result.ok) {
       return result;
     }
 
-    const verified = await verifyActiveEditorText(nextContent, operation.path);
+    const verifyWaitMs = Math.min(deps.writeVerifyWaitMs ?? 2500, Number.isFinite(options.deadlineAt)
+      ? Math.max(0, options.deadlineAt - now()) : Infinity);
+    const verified = await verifyActiveEditorText(nextContent, operation.path, verifyWaitMs, current);
     if (!verified.ok) {
       const decorated = attachWritebackDebug(verified, 'write_verification', operation, options.baseFileLookup, readActiveEditorText(), {
         initialActivePath: currentPath,
         editorReadyDebug: editorReady.debug || null
       });
+      const evidence = { originalCode: verified.code || '', writeMethod: result.method || '', writeStarted: true,
+        ...verified.evidence };
+      if (verified.evidence?.observedIsBefore && verified.evidence.activeMatchesTarget) {
+        // The editor still holds exactly the pre-write text: the write never landed, so a retry is safe.
+        decorated.failure = buildPageFailure('write_operation_failed', {
+          file: operation?.path || '', operationType: operation?.type || 'edit', changedDocument: false,
+          userMessage: `Overleaf did not accept the edit to ${operation?.path || 'the target file'}; the document was left unchanged.`,
+          technicalMessage: verified.reason || '', evidence
+        });
+        return decorated;
+      }
       // §9.3 write_observed_mismatch: the write call landed but the readback
       // does not match. changedDocument:true — the editor state moved, just
       // not as Codex expected.
@@ -793,12 +784,7 @@
         changedDocument: true,
         userMessage: `${operation?.path || 'The target file'} did not read back the content Codex wrote; the document state may differ from what was approved.`,
         technicalMessage: verified.reason || '',
-        evidence: {
-          originalCode: verified.code || '',
-          expectedLength: verified.expectedLength,
-          actualLength: verified.actualLength,
-          writeStarted: true
-        }
+        evidence
       });
       return decorated;
     }
@@ -808,12 +794,12 @@
       // Overleaf renders review markers asynchronously after the editor text
       // has already changed. A single 120 ms snapshot intermittently missed
       // those markers, leaving a Reviewing write with Undo but no Accept.
-      // Poll both paths: normal Reviewing writes get a shorter capture window,
-      // while Accept replay keeps the longer safety window used to prove that
-      // it did not create fresh tracked changes.
+      // Complete normal Track attribution while this file is still active.
+      // Slow batches are covered by request receipts; Accept replay retains
+      // its independent safety window proving that no new tracking was added.
       const trackedDiff = trackReviewingChanges
-        ? await captureTrackedWrite({ trackedBefore, captureBaseline, operation, beforeContent: current,
-          postContent: nextContent, runProjectId: options.runProjectId })
+        ? await captureTrackedWrite({ trackedBefore, captureBaseline, operation: { ...operation, patches: preparedPatches?.patches }, beforeContent: current,
+          postContent: nextContent, runProjectId: options.runProjectId, waitMs: deps.trackCaptureWaitMs ?? 35000 })
         : await waitForTrackedChangeDiff(trackedBefore, operationPaths, {
           waitMs: 3600, intervalMs: 180, stopOnFirst: true
         });
@@ -848,7 +834,7 @@
     window.CodexOverleafStaleGuard?.updateExpectedFileContent(
       options.baseFileLookup,
       operation.path,
-      nextContent
+      preparedPatches?.sourceContent ?? nextContent
     );
     return {
       ...result,
@@ -859,8 +845,7 @@
     };
   }
 
-
-  async function verifyActiveEditorText(expected, filePath, waitMs = 1000) {
+  async function verifyActiveEditorText(expected, filePath, waitMs = 1000, before) {
     const deadline = Date.now() + waitMs;
     let actual = readActiveEditorText();
     while (actual !== expected && Date.now() < deadline) {
@@ -877,10 +862,37 @@
       code: 'write_verification_failed',
       reason: `${filePath || '当前文件'} 写入后读回内容和 Codex 预期不一致，已停止把这次操作标记为成功。请刷新 Overleaf 后重试。`,
       expectedLength: String(expected || '').length,
-      actualLength: String(actual || '').length
+      actualLength: String(actual || '').length,
+      evidence: describeReadbackMismatch(expected, actual, before, filePath)
     };
   }
 
+  // Content-free mismatch evidence: offsets, lengths and short hashes only.
+  function describeReadbackMismatch(expected, actual, before, filePath) {
+    const left = String(expected ?? ''), right = String(actual ?? '');
+    let firstDiff = 0;
+    while (firstDiff < left.length && left[firstDiff] === right[firstDiff]) firstDiff += 1;
+    let tail = 0;
+    while (tail < left.length - firstDiff && tail < right.length - firstDiff
+      && left[left.length - 1 - tail] === right[right.length - 1 - tail]) tail += 1;
+    const activePath = getActiveFilePath() || '';
+    return { expectedLength: left.length, actualLength: right.length, firstDiffOffset: firstDiff,
+      expectedDiffLength: left.length - firstDiff - tail, actualDiffLength: right.length - firstDiff - tail,
+      expectedHash: shortHash(left), actualHash: shortHash(right),
+      beforeHash: typeof before === 'string' ? shortHash(before) : '',
+      observedIsBefore: typeof before === 'string' && right === before,
+      activePath, activeMatchesTarget: !filePath || activePath === filePath };
+  }
+
+  function shortHash(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+      hash ^= value.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+  }
+
   async function ensureEditorReadyForOperation(operation, baseFileLookup, initialActivePath) {
     if (!operation?.path) {
       return {
@@ -1158,7 +1170,6 @@
     };
   }
 
-
   async function applyBinaryAssetOperation(operation, options = {}) {
     const freshness = await checkBinaryAssetFreshness(operation, options);
     if (!freshness.ok) {
@@ -1328,9 +1339,7 @@
     return baseFile.size == null || currentSize == null || baseFile.size === currentSize;
   }
 
-  function normalizeBase64(value) {
-    return String(value || '').replace(/\s+/g, '');
-  }
+  const normalizeBase64 = value => String(value || '').replace(/\s+/g, '');
 
   function decodeBase64Bytes(contentBase64) {
     try {
@@ -1376,13 +1385,37 @@
   }
 
   async function applyFileTreeOperation(operation, options = {}) {
+    if (operation.type === 'delete' && operation.undoCreatedFile) {
+      return applyCreatedFileUndo(operation, options);
+    }
     const initialProjectId = treeOperations.getProjectId?.();
     const initialCancellationSequence = readWriteCancellationSequence();
+    if (operation.type === 'move' && operation.moveProof) {
+      if (options.noTraceUndo !== true) return { ok: false, code: 'file_tree_controls_unavailable', changedDocument: false,
+        reason: 'Native file moves are available only to undo a previously recorded move.' };
+      if (typeof deps.moveFile !== 'function') return { ok: false, code: 'file_move_unavailable', changedDocument: false,
+        reason: 'Verified native file moves are unavailable. Reload the extension and Overleaf.' };
+      const result = await deps.moveFile(operation, { noTraceUndo: true, runProjectId: options.runProjectId, deadlineAt: options.deadlineAt,
+        isCurrent: () => treeOperations.getProjectId?.() === initialProjectId
+          && readWriteCancellationSequence() === initialCancellationSequence && !options.reviewGuard?.() });
+      if (result.ok) recordFileTreeOperationSuccess(operation, options.baseFileLookup);
+      return result;
+    }
+    if (operation.type === 'create' && options.createBatch && typeof deps.createTextFile === 'function') {
+      if (options.baseFileLookup?.has(operation.path) && options.retryCreates !== true) {
+        return checkFileTreeOperationFreshness(operation, options.baseFileLookup);
+      }
+      return deps.createTextFile(operation, { batch: options.createBatch,
+        allowExistingMatches: options.retryCreates === true,
+        isCurrent: () => treeOperations.getProjectId?.() === initialProjectId
+          && readWriteCancellationSequence() === initialCancellationSequence && !options.reviewGuard?.() });
+    }
     const freshness = await checkFileTreeOperationFreshness(operation, options.baseFileLookup);
     if (!freshness.ok) {
       return freshness;
     }
 
+    const ownerBlocked = options.reviewGuard?.(); if (ownerBlocked) return ownerBlocked;
     const manager = findFileTreeManager();
     const methodNames = fileTreeMethodNames(operation.type);
 
@@ -1429,14 +1462,14 @@
     const nativeOperation = { create: deps.createTextFile, delete: deps.deleteTextFile }[operation.type];
     if (typeof nativeOperation === 'function' && (operation.type === 'delete' || typeof operation.content === 'string')) {
       const isCurrent = () => Boolean(initialProjectId) && treeOperations.getProjectId?.() === initialProjectId
-        && readWriteCancellationSequence() === initialCancellationSequence;
+        && readWriteCancellationSequence() === initialCancellationSequence && !options.reviewGuard?.();
       const created = await nativeOperation(operation, { isCurrent, expectedContent: options.baseFileLookup?.get(operation.path) });
       if (!created.ok) return created;
       if (!isCurrent() || created.verified !== true || created.verification !== 'overleaf-zip') {
         return { ...fileTreeVerificationFailed(operation, 'Server receipt is missing or stale.'), changedDocument: true };
       }
       recordFileTreeOperationSuccess(operation, options.baseFileLookup);
-      return { ok: true, method: created.method, verified: true };
+      return { ...created, ok: true, method: created.method, verified: true };
     }
     return {
       ok: false,
@@ -1445,6 +1478,43 @@
     };
   }
 
+  async function applyCreatedFileUndo(operation, options = {}) {
+    const projectId = treeOperations.getProjectId?.();
+    const cancellation = readWriteCancellationSequence();
+    const proof = operation.undoCreatedFile;
+    const expected = options.baseFileLookup?.get(operation.path);
+    const text = proof?.v === 1 && proof.kind === 'text' && typeof expected === 'string';
+    const binary = proof?.v === 1 && proof.kind === 'binary' && /^[a-f0-9]{64}$/i.test(proof.sha256 || '');
+    const isCurrent = () => Boolean(projectId) && projectId === options.runProjectId
+      && treeOperations.getProjectId?.() === projectId && readWriteCancellationSequence() === cancellation && !options.reviewGuard?.();
+    if (!isCurrent() || (!text && !binary) || typeof deps.deleteTextFile !== 'function') {
+      return { ok: false, code: 'undo_operation_failed', changedDocument: false,
+        reason: 'Verified created-file deletion is unavailable for this run.' };
+    }
+    if (text && projectPathExists(operation.path)) {
+      const current = await readCurrentTextFileForFreshness(operation.path);
+      if (!current.ok || current.text !== expected || !isCurrent()) {
+        return { ok: false, code: 'undo_operation_failed', changedDocument: false,
+          reason: 'The created file changed after this run and was left untouched.' };
+      }
+    }
+    const result = await deps.deleteTextFile(operation, {
+      isCurrent, undoCreatedFile: true, deadlineAt: options.deadlineAt,
+      expectedContent: text ? expected : undefined,
+      prepareTextPreimage: text ? () => readCurrentTextFileForFreshness(operation.path) : undefined,
+      expectedSha256: binary ? proof.sha256.toLowerCase() : undefined,
+      canDelete: () => isCurrent() && (binary || (treeOperations.getActiveFilePath?.() === operation.path
+        && readActiveEditorText() === expected))
+    });
+    if (!result.ok) return result;
+    if (!isCurrent() || result.verified !== true || result.verification !== 'overleaf-zip') {
+      return { ok: false, code: 'undo_operation_failed', changedDocument: result.changedDocument !== false,
+        reason: 'The created file has no current server deletion receipt.' };
+    }
+    recordFileTreeOperationSuccess(operation, options.baseFileLookup);
+    return result;
+  }
+
   async function verifyFileTreeOperation(operation) {
     await delay(120);
     const sourcePath = operation.path;
@@ -1613,15 +1683,6 @@
     }
   }
 
-  function fileTreeMethodNames(type) {
-    return {
-      create: ['createDoc', 'createFile', 'addDoc', 'addFile'],
-      rename: ['renameEntity', 'renameFile', 'renameDoc'],
-      move: ['moveEntity', 'moveFile', 'moveDoc'],
-      delete: ['deleteEntity', 'deleteFile', 'deleteDoc', 'removeEntity']
-    }[type] || [];
-  }
-
   function normalizeOperationPaths(operation) {
     if (!operation || typeof operation !== 'object') {
       return operation;
@@ -1694,10 +1755,6 @@
   }
 
 
-
-
-
-
   function normalizeTrackedChangeRefs(refs = []) {
     const seen = new Set();
     const normalized = [];
@@ -1756,23 +1813,12 @@
 
     async function applyOperationsForBridge(operationsOrOptions, options = {}) {
       if (Array.isArray(operationsOrOptions)) {
-        // Welcome-panel + write-guard: defense-in-depth
-        // also runs on the array-shaped entry. T2 only guarded the
-        // payload-object branch; if any future caller goes straight to the
-        // array entry without `options.runProjectId`, the router would have
-        // silently dispatched. Mirror the same `editor_project_id_unavailable`
-        // failure shape the payload branch and the page-side guard already
-        // emit.
+        // Both public call shapes require the original project identity.
         const writeGuardBlock = checkWritebackRunProjectId(options);
         if (writeGuardBlock) return writeGuardBlock;
         return applyOperations(operationsOrOptions, options);
       }
       const payload = operationsOrOptions || {};
-      // Welcome-panel + write-guard: defense-in-depth.
-      // The pageBridge wrapper already runs the runProjectId guard, but a
-      // future caller could reach the router directly. A missing or empty
-      // `runProjectId` on the payload-shaped call blocks the write with the
-      // same `editor_project_id_unavailable` shape the page-side guard uses.
       const writeGuardBlock = checkWritebackRunProjectId(payload);
       if (writeGuardBlock) return writeGuardBlock;
       return applyOperations(payload.operations || [], payload);
@@ -1781,10 +1827,7 @@
     function checkWritebackRunProjectId(params) {
       const runProjectId = params && typeof params.runProjectId === 'string' ? params.runProjectId : '';
       if (runProjectId) return null;
-      // operation: {} (not null) — batch-level guard fired before any per-op
-      // dispatch; matches the abortDispatchResult shape in pageBridge.js and
-      // avoids crashing downstream audit / transcript code that reads
-      // operation.path without a null guard.
+      // Keep operation.path safe for downstream readers of batch-level failures.
       return {
         ok: false,
         applied: [],
@@ -1876,9 +1919,7 @@
     };
   }
 
-    // Tracked-changes lifecycle — carved to trackedChangesLifecycle.js in
-    // v1.8.0 (structural-debt phase 7, #117). Loaded just before this file
-    // in the manifest's page-script list; the Node test path requires it.
+    // Tracked lifecycle is loaded by the Page script list or required by Node tests.
     const trackedChangesLifecycleModule = (typeof window !== 'undefined' && window.CodexOverleafTrackedChangesLifecycle)
       || (typeof module === 'object' && module.exports ? require('./trackedChangesLifecycle.js') : null)
       || (typeof globalThis !== 'undefined' ? globalThis.CodexOverleafTrackedChangesLifecycle : null);
@@ -1890,7 +1931,7 @@
       captureTrackedWrite, reconcileTrackedChangeCapture,
       waitForTrackedChangeDiff
     } = trackedChangesLifecycleModule.create({
-      window, confirmReviewWriteback: deps.confirmReviewWriteback,
+      window, now, readWriteCancellationSequence, confirmReviewWriteback: deps.confirmReviewWriteback,
       checkWritebackRunProjectId,
       buildNoTraceUndoBlockedResult,
       buildReviewingRequiredBlockedResult,