codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/content/writebackOrchestrator.js

@@ -63,6 +63,8 @@
   let writebackSettlement;
   let injectedWritebackSettlement;
   let assetTransferBroker;
+  let stageWritebackRecovery;
+  let settleWritebackRecovery;
 
   function buildSettlement(input = {}) {
     return writebackSettlement?.settle instanceof Function
@@ -98,7 +100,24 @@
     return pending;
   }
 
+  function selectionViolationNextStep() {
+    return tx('Select the intended region again and request only changes within it. Valid written parts can be undone.',
+      '请重新选择目标范围，仅请求修改该范围。已写入的合法部分可撤销。');
+  }
+
+  function buildWithheldEntry(change) {
+    const reason = writebackController.formatUnsupportedLocalChangeReason(change, getLocale());
+    const nextAction = change.reason === 'selection_scope_violation' ? selectionViolationNextStep()
+      : tx('The main agent must review the withheld file before syncing it.', '主代理需核对未同步文件后再写回。');
+    return { operation: { type: 'create', path: change.path }, result: { ok: false,
+      code: change.reason, reason, changedDocument: false, failure: { code: change.reason,
+        stage: 'preflight', severity: 'blocked', retryable: false, terminalState: 'blocked', changedDocument: false,
+        userMessage: reason, nextAction } } };
+  }
+
   async function applySyncChangesToOverleaf(syncChanges = [], project = {}, options = {}) {
+    const activeRun = getCurrentRunView?.();
+    const saveTarget = { runProjectId: activeRun?.runProjectId || '', recordId: activeRun?.recordId || '', sessionId: activeRun?.sessionId || '' };
     const runMode = options.mode || getState().mode;
     const runRequireReviewing = typeof options.requireReviewing === 'boolean'
       ? options.requireReviewing
@@ -106,6 +125,23 @@
     const assistantMessage = cleanFinalAnswer(options.assistantMessage || getAssistantAnswerForCurrentRun());
     const unsupportedChanges = Array.isArray(options.unsupportedChanges) ? options.unsupportedChanges : [];
     appendUnsupportedLocalChanges(unsupportedChanges);
+    const withheldOnly = unsupportedChanges.filter(change => ['subagent_unfinished_output', 'subagent_unauthorized_edit', 'selection_scope_violation'].includes(change.reason));
+    if (runMode !== 'ask' && !syncChanges.length && withheldOnly.length) {
+      const skipped = withheldOnly.map(buildWithheldEntry);
+      const hasSelectionViolation = withheldOnly.some(change => change.reason === 'selection_scope_violation');
+      const applied = { ok: false, applied: [], skipped };
+      appendCompletionReport({ conclusion: assistantMessage || tx('Some generated changes were blocked.', '部分生成的改动已被阻止。'),
+        status: 'failed', operations: [], applyResults: [applied], mode: runMode,
+        nextStep: hasSelectionViolation
+          ? selectionViolationNextStep()
+          : tx('The main agent must review and adopt the withheld files before syncing them.', '主代理需核对并接管未同步文件后再写回。') });
+      return { summaryLine: hasSelectionViolation
+          ? tx('Changes outside the selection were blocked.', '选区外改动已被阻止。')
+          : tx('Generated files are awaiting review.', '生成文件待核对。'), hasSkippedOperations: true,
+        applied, settlement: buildSettlement({ operations: [], applyResult: applied }),
+        audit: buildAuditSummaryFromApply({ operations: [], applyResults: [applied], resultStatus: 'completed_with_skips' }) };
+    }
+
     // Guard on the immutable submitted mode, not the mutable panel state.
     if (options.mode === 'ask' && ((syncChanges || []).length || unsupportedChanges.length)) {
       appendRunEvent({
@@ -148,7 +184,16 @@
     }
     let operations = buildSyncApplyOperations(syncChanges, project);
     let visibleSyncChanges = syncChanges || [];
-    let additionalSkippedEntries = [];
+    // A previous Native build can still report inferred metadata moves.
+    // Forward sync never promotes them to a new file or a new capability.
+    let additionalSkippedEntries = operations.filter(operation => operation.type === 'move').map(operation => ({
+      operation,
+      result: { ok: false, code: 'file_tree_controls_unavailable', changedDocument: false,
+        reason: tx('Automatic file moves are unavailable. Handle the path change in Overleaf before retrying.',
+          '暂不支持自动移动文件，请先在 Overleaf 中处理路径变化后再重试。') }
+    }));
+    operations = operations.filter(operation => operation.type !== 'move');
+    if (additionalSkippedEntries.length) visibleSyncChanges = filterSyncChangesByOperations(syncChanges, operations);
     let skippedFilesForAudit = additionalSkippedEntries;
     let appliedFilesForAudit = [];
     const pathSafety = partitionUnsafeProjectPathOperations(operations);
@@ -173,13 +218,20 @@
       visibleSyncChanges = filterSyncChangesByOperations(syncChanges, operations);
     }
     if (!operations.length) {
+      const blockedSettlement = buildSettlement({
+        operations: buildSyncApplyOperations(syncChanges, project),
+        applyResult: { ok: additionalSkippedEntries.length === 0, applied: [], skipped: additionalSkippedEntries }
+      });
+      const blockedFailure = blockedSettlement
+        ? writebackSettlement.projectRunSettlement({ settlement: blockedSettlement.facts }).primaryFailure : undefined;
       appendRunEvent({
         title: tx('Codex did not produce file changes that need to sync back to Overleaf.', 'Codex 没有产生需要同步回 Overleaf 的文件改动。'),
         status: 'completed'
       });
       appendCompletionReport({
         conclusion: assistantMessage || tx('Codex finished locally. There are no changes to sync back to Overleaf.', 'Codex 已完成本地处理，没有需要同步回 Overleaf 的改动。'),
-        status: runMode === 'ask' ? tr('modeAsk') : 'completed',
+        status: additionalSkippedEntries.length ? 'failed' : runMode === 'ask' ? tr('modeAsk') : 'completed',
+        failure: blockedFailure,
         operations: [],
         applyResults: additionalSkippedEntries.length ? [{ ok: false, applied: [], skipped: additionalSkippedEntries }] : [],
         unchangedReason: additionalSkippedEntries.find(item => item?.result?.reason)?.result.reason
@@ -190,14 +242,7 @@
       return {
         summaryLine: assistantMessage || tx('No changes to sync', '没有需要同步的改动'),
         hasSkippedOperations: additionalSkippedEntries.length > 0,
-        settlement: buildSettlement({
-          operations: buildSyncApplyOperations(syncChanges, project),
-          applyResult: {
-            ok: additionalSkippedEntries.length === 0,
-            applied: [],
-            skipped: additionalSkippedEntries
-          }
-        }),
+        settlement: blockedSettlement,
         audit: buildAuditSummaryFromApply({
           operations: buildSyncApplyOperations(syncChanges, project),
           applyResults: additionalSkippedEntries.length ? [{ ok: false, applied: [], skipped: additionalSkippedEntries }] : [],
@@ -240,13 +285,20 @@
     additionalSkippedEntries.push(...binaryDecision.skipped);
 
     if (!operations.length) {
+      const approvalSettlement = buildSettlement({
+        operations: buildSyncApplyOperations(syncChanges, project),
+        applyResult: { ok: additionalSkippedEntries.length === 0, applied: [], skipped: additionalSkippedEntries }
+      });
+      const approvalFailure = approvalSettlement
+        ? writebackSettlement.projectRunSettlement({ settlement: approvalSettlement.facts }).primaryFailure : undefined;
       appendRunEvent({
         title: tx('No approved file changes remain to sync back to Overleaf.', '没有剩余已确认的文件改动需要同步回 Overleaf。'),
         status: 'completed'
       });
       appendCompletionReport({
         conclusion: assistantMessage || tx('No approved changes were written back to Overleaf.', '没有已确认的改动写回 Overleaf。'),
-        status: runMode === 'ask' ? tr('modeAsk') : 'completed',
+        status: additionalSkippedEntries.length ? 'failed' : runMode === 'ask' ? tr('modeAsk') : 'completed',
+        failure: approvalFailure,
         operations: [],
         applyResults: additionalSkippedEntries.length ? [{ ok: false, applied: [], skipped: additionalSkippedEntries }] : [],
         unchangedReason: additionalSkippedEntries.find(item => item?.result?.reason)?.result.reason
@@ -257,14 +309,7 @@
       return {
         summaryLine: tx('No changes applied', '没有应用改动'),
         hasSkippedOperations: additionalSkippedEntries.length > 0,
-        settlement: buildSettlement({
-          operations: buildSyncApplyOperations(syncChanges, project),
-          applyResult: {
-            ok: additionalSkippedEntries.length === 0,
-            applied: [],
-            skipped: additionalSkippedEntries
-          }
-        }),
+        settlement: approvalSettlement,
         audit: buildAuditSummaryFromApply({
           operations: buildSyncApplyOperations(syncChanges, project),
           applyResults: additionalSkippedEntries.length ? [{ ok: false, applied: [], skipped: additionalSkippedEntries }] : [],
@@ -312,6 +357,13 @@
         })
       };
     }
+    const writebackActivityId = 'overleaf-writeback:' + Date.now().toString(36);
+    appendRunEvent({
+      title: tx('Syncing approved changes to Overleaf.', '正在将已批准的改动同步到 Overleaf。'),
+      status: 'running',
+      activity: { v: 1, kind: 'sync', id: writebackActivityId, state: 'running', paths: operations.map(operation => operation.path).filter(Boolean) }
+    });
+    await stageWritebackRecovery?.(operations, saveTarget, runRequireReviewing, project);
     const applied = operations.length
       ? mergeApplyResultSkipped(await assetTransferBroker.applyOperations({
         operations,
@@ -321,10 +373,15 @@
         // Welcome-panel + write-guard:
         // immutable per-run project id, checked by the page-side guard
         // against `_ide.project._id` before any mutation.
-        runProjectId: getCurrentRunView()?.runProjectId || ''
+        runProjectId: getCurrentRunView()?.runProjectId || '',
+        retryCreates: options.retryCreates === true
       }), additionalSkippedEntries)
       : mergeApplyResultSkipped({ ok: true, applied: [], skipped: [] }, additionalSkippedEntries);
     const hasConfirmedApplyResult = hasApplyResultEntries(applied);
+    for (const change of unsupportedChanges.filter(item => ['subagent_unfinished_output', 'subagent_unauthorized_edit', 'selection_scope_violation'].includes(item.reason))) {
+      applied.skipped.push(buildWithheldEntry(change));
+      applied.ok = false;
+    }
     // Record the apply result + undo checkpoint IMMEDIATELY, before any
     // cancellable verify/mirror awaits below. A user-cancel during the
     // post-write save-verify or mirror refresh throws codex_cancelled; if undo
@@ -333,7 +390,7 @@
     // landed in Overleaf. The manual-confirm path already records undo right
     // after its write — match that ordering here (v1.6.2).
     appendApplyResult(applied);
-    recordUndoFromApply(project, applied);
+    await recordUndoFromApply(project, applied);
     const skippedEntries = getSkippedEntries(applied);
     if (skippedEntries.length) {
       appendPartialWritebackWarning(applied);
@@ -342,36 +399,37 @@
       renderReadOnlyDiffReview(getAppliedSyncChanges(syncChanges, applied));
     }
     const appliedPaths = getAppliedOperationPaths(applied);
+    appendRunEvent({
+      title: tx('Overleaf writeback returned its result.', 'Overleaf 写回已返回结果。'),
+      status: !hasConfirmedApplyResult || skippedEntries.length ? 'warning' : 'completed',
+      activity: { v: 1, kind: 'sync', id: writebackActivityId,
+        state: !hasConfirmedApplyResult || skippedEntries.length ? 'warning' : 'completed',
+        paths: operations.map(operation => operation.path).filter(Boolean),
+        written: appliedPaths.length, skipped: skippedEntries.length }
+    });
     // Only probe save-state + refresh the mirror when real writes landed. A
     // zero-write run (every operation skipped) has nothing to save-verify, so
     // skip the ~5s probe and its misleading "could not verify saved" warning
     // (v1.6.2).
-    const saveVerification = appliedPaths.length
-      ? await verifyPostWriteSaveState()
-      : {
-        ok: false,
-        state: 'not_checked',
-        reason: 'No applied writeback operations were returned.'
-      };
+    const confirmation = appliedPaths.length
+      ? await verifyPostWriteSaveState(applied, project, saveTarget)
+      : { verification: { ok: false, state: 'not_checked', reason: 'No applied writeback operations were returned.' } };
+    const saveVerification = confirmation.verification;
+    await settleWritebackRecovery?.(applied, project, saveVerification, saveTarget);
     if (appliedPaths.length) {
-      appendPostWriteSaveVerificationWarning(saveVerification);
+      appendPostWriteSaveVerificationWarning(saveVerification, saveTarget);
+      appendRunEvent({ kind: 'technical', title: 'Post-write save confirmation', status: 'info', detail: saveVerification });
     }
     // v1.7.5: the mirror refresh (zip snapshot + mirror.sync, often the
     // slowest post-write step) no longer blocks the completion report. The
     // pending promise is exposed so undoRun and the next runTask barrier on
     // it — a mirror.sync landing AFTER an undo would otherwise push the
     // pre-undo snapshot as the local baseline.
-    const mirrorSettlementTarget = getCurrentRunView?.();
-    pendingMirrorRefresh = refreshProjectMirrorAfterWriteback(project, applied, saveVerification)
-      .catch(error => {
-        appendRunEvent({
-          title: tx(
-            `Overleaf was written, but the background workspace refresh failed: ${error.message}. The next run will reread the project.`,
-            `Overleaf 已写入，但后台刷新本地 workspace 失败：${error.message}。下一轮会重新读取项目。`
-          ),
-          status: 'failed'
-        });
-        return 'failed';
+    const mirrorSettlementTarget = saveTarget;
+    pendingMirrorRefresh = refreshProjectMirrorAfterWriteback(project, applied, saveVerification, { target: saveTarget, snapshot: confirmation.snapshot })
+      .catch(async error => {
+        appendRunRecordEvent(saveTarget.recordId, { kind: 'technical', title: 'Mirror refresh requires a fresh read', status: 'info', detail: { reason: error.message } });
+        return invalidateWritebackMirror(saveTarget);
       })
       .then(state => {
         if (typeof onMirrorRefreshSettled !== 'function') return;
@@ -388,7 +446,8 @@
     const compileSummary = appliedPaths.length
       ? await autoRecompileAfterWriteback(appliedPaths, saveVerification, {
         autoRecompile: options.autoRecompile,
-        mode: runMode
+        mode: runMode,
+        runProjectId: saveTarget.runProjectId
       }).catch(error => {
         appendRunEvent({
           title: tx(`Post-write compile failed: ${error.message}`, `写后编译出错：${error.message}`),
@@ -435,6 +494,7 @@
       compileErrors: compileSummary?.status === 'failed' && Array.isArray(compileSummary.errors)
         ? compileSummary.errors
         : undefined,
+      saveVerification,
       // Promote the primary per-operation skip failure to the run level when
       // the writeback failed outright: target-file and write-stage codes only
       // ever exist inside applied.skipped[], and without this promotion the
@@ -475,104 +535,100 @@
     };
   }
 
-  async function verifyPostWriteSaveState() {
-    try {
-      const result = await callPageBridge('waitForSaveState', {
-        deadlineMs: 5000,
-        requirePositiveSignal: true
-      });
-      if (result?.state === 'verified_saved') {
-        return {
-          ...result,
-          ok: true,
-          state: 'verified_saved'
-        };
-      }
-      if (result?.ok === true && !result?.state) {
-        return {
-          ...result,
-          ok: false,
-          state: 'verified_quiet'
-        };
-      }
-      if (result?.state === 'unknown_timeout' || result?.state === 'unavailable') {
-        return {
-          ...result,
-          ok: false
-        };
-      }
-      return {
-        ...result,
-        ok: false,
-        state: 'unknown_timeout'
-      };
-    } catch (error) {
-      return {
-        ok: false,
-        state: 'unavailable',
-        reason: error.message
-      };
-    }
+  async function verifyPostWriteSaveState(applied, project, target = {}) {
+    return writebackController.confirmPostWriteSave({
+      applied, project, runProjectId: target.runProjectId,
+      assertCurrent() {
+        if (!target.runProjectId || getCurrentProjectId() !== target.runProjectId) {
+          throw Object.assign(new Error('The Overleaf project changed during save confirmation.'), { code: 'aborted_project_changed', changedDocument: true });
+        }
+        if (target.recordId && getCurrentRunView()?.recordId !== target.recordId) {
+          throw Object.assign(new Error('The run stopped during save confirmation.'), { code: 'codex_cancelled', changedDocument: true });
+        }
+      },
+      readSaveState: params => callPageBridge('waitForSaveState', { ...params, runProjectId: target.runProjectId }),
+      readSnapshot: params => callPageBridge('getProjectSnapshot', { ...params, runProjectId: target.runProjectId })
+    });
   }
 
-  function appendPostWriteSaveVerificationWarning(saveVerification = {}) {
-    if (saveVerification?.state === 'verified_saved') {
-      return;
-    }
-    appendRunEvent({
-      title: tx(
-        'Files were written or attempted in Overleaf, but Codex could not verify that Overleaf saved them. Local mirror refresh was skipped.',
-        '文件已写入或尝试写入 Overleaf，但 Codex 未能确认 Overleaf 已保存；已跳过本地 mirror 刷新。'
-      ),
-      status: 'warning'
-    });
+  function appendPostWriteSaveVerificationWarning(saveVerification = {}, target = {}) {
+    if (saveVerification.state === 'verified_saved') return;
+    // Missing confirmation is represented once in the report, with a check action.
+    if (saveVerification.signal !== 'offline') return;
+    const title = saveVerification.signal === 'offline'
+      ? tx('Overleaf is offline. Keep this page open and reconnect so the changes can be saved.',
+        'Overleaf 当前离线。请保持页面开启，恢复连接后等待改动保存。')
+      : tx('Saving these changes is not yet confirmed. Keep this page open and check Overleaf’s save and connection status.',
+        '尚未确认本次改动已保存。请保持页面开启，检查 Overleaf 的保存和连接状态。');
+    if (target.recordId) appendRunRecordEvent(target.recordId, { title, status: 'warning' });
+    else appendRunEvent({ title, status: 'warning' });
   }
 
-  // v1.8.0: text-only writebacks confirm the mirror in place. The written
-  // content ORIGINATED in the local workspace, so after a verified writeback
-  // the workspace already equals Overleaf; only the baseline hashes and
-  // freshness metadata are stale. mirror.confirmWriteback re-hashes the
-  // written files without re-downloading the project. Anything unusual —
-  // tree ops, binary writes, dirty mirror, an older native host without the
-  // method — falls back to the full zip resync below.
-  const MIRROR_CONFIRMABLE_OPERATION_TYPES = new Set(['edit']);
-
-  async function tryConfirmMirrorWriteback(applied) {
-    const entries = Array.isArray(applied?.applied) ? applied.applied : [];
-    if (!entries.length) {
-      return false;
-    }
-    const paths = [];
-    for (const entry of entries) {
-      const operation = entry?.operation || {};
-      if (!MIRROR_CONFIRMABLE_OPERATION_TYPES.has(operation.type) || !operation.path) {
-        return false;
+  async function invalidateWritebackMirror(target = {}) {
+    let invalidated = false;
+    try {
+      if (target.runProjectId) {
+        const response = await sendBackgroundNative({ method: 'mirror.invalidate', params: { projectId: target.runProjectId } });
+        invalidated = response?.ok === true && response.result?.invalidated === true;
       }
-      paths.push(operation.path);
+    } catch (_error) { /* An unavailable host cannot acknowledge invalidation. */ }
+    let pageInvalidated = getCurrentProjectId() !== target.runProjectId;
+    if (!pageInvalidated) {
+      resetContextProject();
+      try {
+        const response = await callPageBridge('invalidateProjectSnapshot', { invalidateFileList: true, runProjectId: target.runProjectId });
+        pageInvalidated = response?.ok === true;
+      } catch (_error) { /* Leave the failure visible if both caches cannot be fenced. */ }
     }
+    if (invalidated && pageInvalidated) return 'not-attempted';
+    const event = {
+      title: tx('The local project cache could not be reset. Check the local connection before starting another task.',
+        '本地项目缓存未能重置。请检查本地连接后再开始下一轮任务。'),
+      status: 'warning'
+    };
+    if (target.recordId) appendRunRecordEvent(target.recordId, event);
+    else appendRunEvent(event);
+    return 'failed';
+  }
+
+  // Text-only confirmation requires the page's verified post-image digest.
+  // Local files can change after writeback; Native must match those digests
+  // before advancing its baseline. Missing evidence and non-text/tree writes
+  // retain the authoritative ZIP fallback below.
+
+  async function tryConfirmMirrorWriteback(applied, runProjectId) {
     try {
+      if (!runProjectId || getCurrentProjectId() !== runProjectId) return false;
+      const proof = await writebackController.buildMirrorWritebackConfirmation?.(applied);
+      if (!proof || getCurrentProjectId() !== runProjectId) return false;
       const response = await sendBackgroundNative({
         method: 'mirror.confirmWriteback',
         params: {
-          projectId: getCurrentProjectId(),
-          paths: Array.from(new Set(paths))
+          projectId: runProjectId,
+          ...proof
         }
       });
-      return response?.ok === true && response?.result?.ok === true;
+      const confirmations = Array.isArray(response?.result?.confirmed) ? response.result.confirmed : [];
+      const confirmed = new Map(confirmations.map(file => [file?.path, file?.hash]));
+      return getCurrentProjectId() === runProjectId && response?.ok === true && response?.result?.ok === true
+        && confirmations.length === proof.expectedFiles.length
+        && confirmed.size === proof.expectedFiles.length
+        && proof.expectedFiles.every(file => confirmed.get(file.path) === file.sha256);
     } catch (error) {
       return false;
     }
   }
 
-  async function refreshProjectMirrorAfterWriteback(project = {}, applied = {}, saveVerification = {}) {
+  async function refreshProjectMirrorAfterWriteback(project = {}, applied = {}, saveVerification = {}, confirmation = {}) {
+    const target = confirmation.target || {};
     if (saveVerification?.state !== 'verified_saved') {
-      return 'not-attempted';
+      return invalidateWritebackMirror(target);
     }
     if (!Array.isArray(applied?.applied) || !applied.applied.length) {
       return 'not-attempted';
     }
 
-    if (await tryConfirmMirrorWriteback(applied)) {
+    if (!confirmation.snapshot && await tryConfirmMirrorWriteback(applied, target.runProjectId)) {
       appendRunEvent({
         title: tx(
           'Local Codex workspace confirmed in place (no project re-download needed). The next run starts from the latest content.',
@@ -588,10 +644,13 @@
       status: 'running'
     });
 
-    await callPageBridge('invalidateProjectSnapshot', {
+    if (!target.runProjectId || getCurrentProjectId() !== target.runProjectId) return invalidateWritebackMirror(target);
+    if (!confirmation.snapshot) await callPageBridge('invalidateProjectSnapshot', {
+      runProjectId: target.runProjectId,
       invalidateFileList: true
     });
-    const freshProject = sanitizeRunProjectSnapshot(await callPageBridge('getProjectSnapshot', {
+    const freshProject = confirmation.snapshot || sanitizeRunProjectSnapshot(await callPageBridge('getProjectSnapshot', {
+      runProjectId: target.runProjectId,
       force: true,
       maxAgeMs: 0,
       preferLightweight: true,
@@ -603,23 +662,18 @@
       zipTimeoutMs: RUN_SNAPSHOT_ZIP_TIMEOUT_MS,
       focusFiles: getAppliedOperationPaths(applied)
     }));
-    if (!freshProject?.files?.length || freshProject?.capabilities?.fullProjectSnapshot === false) {
-      appendRunEvent({
-        title: tx(
-          'Overleaf was written, but the full project was not read. The local Codex workspace baseline was not refreshed; the next run will reread it.',
-          'Overleaf 已写入，但没有读到完整项目；暂不刷新本地 Codex workspace baseline，下一轮会重新读取。'
-        ),
-        status: 'failed'
-      });
-      return 'failed';
+    if (getCurrentProjectId() !== target.runProjectId || freshProject?.id !== target.runProjectId
+      || !freshProject?.files?.length || freshProject?.capabilities?.fullProjectSnapshot === false
+      || freshProject?.capabilities?.skipped?.length) {
+      return invalidateWritebackMirror(target);
     }
 
-    const syncedProject = mergeVerifiedAppliedFiles(freshProject, project, applied);
+    const syncedProject = confirmation.snapshot || mergeVerifiedAppliedFiles(freshProject, project, applied);
     resetContextProject();
     const response = await sendBackgroundNative({
       method: 'mirror.sync',
       params: {
-        projectId: getCurrentProjectId(),
+        projectId: target.runProjectId,
         project: syncedProject
       }
     });
@@ -631,15 +685,7 @@
       return 'complete';
     }
 
-    const message = response?.error?.message || tx('native host did not respond', 'native host 没有响应');
-    appendRunEvent({
-      title: tx(
-        `Overleaf was written, but refreshing the local workspace failed: ${message}`,
-        `Overleaf 已写入，但刷新本地 workspace 失败：${message}`
-      ),
-      status: 'failed'
-    });
-    return 'failed';
+    return invalidateWritebackMirror(target);
   }
 
   function mergeVerifiedAppliedFiles(freshProject = {}, originalProject = {}, applied = {}) {
@@ -660,6 +706,8 @@
     return writebackController.formatUnsupportedLocalChangeSummary(changes, getLocale());
   }
 
+  const serverProvenSave = verification => ['overleaf-zip', 'server-receipts'].includes(verification?.source);
+
   async function autoRecompileAfterWriteback(writtenPaths = [], saveVerification = {}, options = {}) {
     if (options.autoRecompile === false
       || (options.autoRecompile === undefined && getState().autoRecompile === false)) return null;
@@ -671,7 +719,10 @@
     const hasCompilableFile = writtenPaths.some(filePath => CompileAdapter.isCompilableFile(filePath));
     if (!hasCompilableFile) return null;
 
+    const compileActivityId = 'overleaf-compile:' + Date.now().toString(36);
+    const activity = (state, output = '') => ({ v: 1, kind: 'compile', id: compileActivityId, state, target: 'Overleaf', output });
     appendRunEvent({
+      activity: activity('running'),
       title: saveVerification?.state !== 'verified_saved'
         ? tx(
           'Post-write compile: Overleaf save was not verified, but Auto Compile is on. Triggering Overleaf Recompile and letting Overleaf wait for the latest save.',
@@ -687,9 +738,10 @@
     try {
       const result = await callPageBridge('triggerCompile', {
         preferUiClick: true,
-        waitForSaveMs: 5000,
-        requireVerifiedSave: saveVerification?.state === 'verified_saved',
-        runProjectId: getCurrentRunView()?.runProjectId || getCurrentProjectId()
+        // Server-side proof (ZIP or save receipts) already settles the save; don't also demand the UI indicator.
+        waitForSaveMs: serverProvenSave(saveVerification) ? 0 : 5000,
+        requireVerifiedSave: saveVerification?.state === 'verified_saved' && !serverProvenSave(saveVerification),
+        runProjectId: options.runProjectId || getCurrentRunView()?.runProjectId || getCurrentProjectId()
       });
       if (result?.ok) {
         let logResult = null;
@@ -698,79 +750,42 @@
             triggerIfStale: false,
             maxAgeMs: 30000,
             waitForSaveMs: 0,
-            runProjectId: getCurrentRunView()?.runProjectId || getCurrentProjectId()
+            runProjectId: options.runProjectId || getCurrentRunView()?.runProjectId || getCurrentProjectId()
           });
         } catch (_error) {
           logResult = null;
         }
         const compile = result.compile;
         if (compile?.status === 'success') {
-          appendRunEvent({ title: tx('Compile succeeded.', '编译成功。'), status: 'completed' });
+          appendRunEvent({ title: tx('Compile succeeded.', '编译成功。'), status: 'completed',
+            activity: activity('completed', [...(logResult?.errors || []), ...(logResult?.warnings || [])].slice(0, 5).map(CompileAdapter.formatCompileDiagnosticForSummary).join('\n')) });
         } else if (compile?.status === 'triggered') {
-          appendRunEvent({ title: tx('Overleaf compile was triggered. The page will continue showing progress.', '已触发 Overleaf 编译；页面会继续显示编译进度。'), status: 'completed' });
+          appendRunEvent({ title: tx('Overleaf compile was triggered. The page will continue showing progress.', '已触发 Overleaf 编译；页面会继续显示编译进度。'), status: 'completed', activity: activity('triggered') });
         } else {
-          appendRunEvent({ title: tx(`Compile finished with status: ${compile?.status || 'unknown'}`, `编译完成，状态：${compile?.status || '未知'}`), status: 'completed' });
+          appendRunEvent({ title: tx(`Compile finished with status: ${compile?.status || 'unknown'}`, `编译完成，状态：${compile?.status || '未知'}`), status: 'completed', activity: activity(compile?.status === 'failed' ? 'failed' : 'unknown') });
         }
         return buildPostWriteCompileSummary({ result, logResult });
       } else {
-        const reason = result?.reason || tx('unknown reason', '未知原因');
-        appendRunEvent({ title: tx(`Post-write compile did not succeed: ${reason}`, `写后编译未成功：${reason}`), status: 'failed' });
+        const reason = CompileAdapter.localizeCompileReason(result?.reason, getLocale()) || tx('unknown reason', '未知原因');
+        appendRunEvent({ title: tx(`Post-write compile did not succeed: ${reason}`, `写后编译未成功：${reason}`), status: 'failed', activity: activity('failed', reason) });
         return buildPostWriteCompileSummary({ result });
       }
     } catch (error) {
-      appendRunEvent({ title: tx(`Post-write compile failed: ${error.message}`, `写后编译出错：${error.message}`), status: 'failed' });
+      const reason = CompileAdapter.localizeCompileReason(error.message, getLocale());
+      appendRunEvent({ title: tx(`Post-write compile failed: ${reason}`, `写后编译出错：${reason}`), status: 'failed', activity: activity('failed', reason) });
       return buildPostWriteCompileSummary({ error });
     }
   }
 
-  function buildPostWriteCompileSummary({ result = null, logResult = null, error = null } = {}) {
-    const logAvailable = logResult?.ok === true;
-    const errors = logAvailable && Array.isArray(logResult.errors)
-      ? logResult.errors.slice(0, 5).map(formatCompileDiagnosticForSummary)
-      : [];
-    const warnings = logAvailable && Array.isArray(logResult.warnings)
-      ? logResult.warnings.slice(0, 5).map(formatCompileDiagnosticForSummary)
-      : [];
-    if (error) {
-      return {
-        status: 'failed',
-        reason: error?.message || 'Post-write compile failed.',
-        errors,
-        warnings,
-        logAvailable
-      };
-    }
-    if (!result?.ok) {
-      return {
-        status: 'failed',
-        reason: result?.reason || 'Post-write compile did not succeed.',
-        errors,
-        warnings,
-        logAvailable
-      };
-    }
-    return {
-      status: result.compile?.status || 'triggered',
-      reason: result.reason || '',
-      errors,
-      warnings,
-      logAvailable
-    };
+  function buildPostWriteCompileSummary(input = {}) {
+    return compileAdapter.buildPostWriteCompileSummary(input);
   }
 
-  // First structured per-operation failure among the skipped writeback
-  // entries — the run-level failure the completion report promotes.
+  // Use the same normalized failure selection as settlement and its UI, while
+  // preserving the selected producer's full evidence on the historical report.
   function promoteWritebackSkippedFailure(applied) {
-    for (const entry of getSkippedEntries(applied)) {
-      const failure = entry?.result?.failure || entry?.failure;
-      if (failure?.code) {
-        if (!failure.file && entry?.path) {
-          return { ...failure, file: entry.path };
-        }
-        return failure;
-      }
-    }
-    return null;
+    const failures = writebackSettlement.collectFailuresFromResult(applied);
+    return writebackSettlement.selectPrimaryFailure(failures);
   }
 
   function appendCompileSummaryToConclusion(conclusion, compileSummary) {
@@ -800,9 +815,10 @@
         )
         : tx('Post-write compile was triggered; Overleaf may still be updating the result.', '已触发写后编译；Overleaf 可能仍在更新结果。');
     } else if (compileSummary.status === 'failed') {
+      const reason = compileAdapter.localizeCompileReason(compileSummary.reason, getLocale());
       summary = tx(
-        `Post-write compile check failed: ${compileSummary.reason || 'unknown reason'}`,
-        `写后编译检查失败：${compileSummary.reason || '未知原因'}`
+        `Post-write compile check failed: ${reason || 'unknown reason'}`,
+        `写后编译检查失败：${reason || '未知原因'}`
       );
     } else {
       summary = tx(
@@ -813,10 +829,6 @@
     return [conclusion, '', summary].filter(Boolean).join('\n');
   }
 
-  function formatCompileDiagnosticForSummary(value) {
-    const text = String(value || '').replace(/\s+/g, ' ').trim();
-    return text.length > 180 ? `${text.slice(0, 179)}...` : text;
-  }
 
   async function resolveCompileLogContext() {
     try {
@@ -891,6 +903,8 @@
       getCurrentRunView,
     } = deps);
     assetTransferBroker = deps.assetTransferBroker;
+    stageWritebackRecovery = deps.stageWritebackRecovery;
+    settleWritebackRecovery = deps.settleWritebackRecovery;
     onMirrorRefreshSettled = deps.onMirrorRefreshSettled;
     writebackSettlement = deps.writebackSettlement;
     compileAdapter = deps.compileAdapter;