codex-overleaf-link 2.3.5 → 2.4.0

package/extension/src/backgroundUpdateCoordinator.js

@@ -4,6 +4,7 @@
   const UPDATE_STATE_KEY = 'codex-overleaf-managed-update-state-v1';
   const CONSENT_STATE_KEY = 'codex-overleaf-update-consent-v1';
   const UPDATE_RELOAD_TABS_KEY = 'codex-overleaf-managed-update-tabs-v1';
+  const MANUAL_RELOAD_TABS_KEY = 'codex-overleaf-manual-runtime-reload-v1';
   const CHECK_ALARM = 'codex-overleaf-consent-update-check';
   const IDLE_ALARM = 'codex-overleaf-consent-update-idle';
   const WATCHDOG_ALARM = 'codex-overleaf-consent-update-watchdog';
@@ -12,7 +13,7 @@
   const CHECK_INTERVAL_MINUTES = 24 * 60;
   const SNOOZE_MS = 24 * 60 * 60 * 1000;
   const CANDIDATE_MAX_AGE_MS = 5 * 60 * 1000;
-  const CHECK_REQUEST_TIMEOUT_MS = 15 * 1000;
+  const CHECK_REQUEST_TIMEOUT_MS = 55 * 1000;
   const ACTIVATION_TIMEOUT_MS = 20 * 1000;
   const ACTIVATION_POLL_MS = 250;
   const FAST_IDLE_RETRY_MS = 4000;
@@ -31,7 +32,8 @@
     'codex-overleaf/consent-update-check',
     'codex-overleaf/consent-update-install',
     'codex-overleaf/consent-update-later',
-    'codex-overleaf/consent-update-dismiss'
+    'codex-overleaf/consent-update-dismiss',
+    'codex-overleaf/consent-update-reload'
   ]);
 
   const policy = root.CodexOverleafUpdateConsent;
@@ -41,6 +43,10 @@
   let policyTail = Promise.resolve();
   let idleRetryTimer = null;
   let activationPromise = null;
+  let runtimeStatus = null;
+  let runtimeStatusAt = 0;
+  let runtimeStatusRead = null;
+  let runtimeReloadMessage = '';
 
   function init(options = {}) {
     if (initialized || !policy || !revocation) return;
@@ -92,6 +98,7 @@
     await reconcileRecoveryState();
     await settleTerminalConsent();
     await armLegacyGuard();
+    await finishManualRuntimeReload();
     await publishView();
     const updateState = await getUpdateState();
     if (['staged', 'waiting_for_idle'].includes(updateState.state)) {
@@ -129,6 +136,8 @@
         return postponeUpdate();
       case 'codex-overleaf/consent-update-dismiss':
         return dismissCompletedUpdate();
+      case 'codex-overleaf/consent-update-reload':
+        return reloadInstalledRuntime();
       default:
         throw codedError('unknown_update_action', 'Unknown update action.');
     }
@@ -648,11 +657,86 @@
   }
 
   async function getView() {
-    const [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
-    return policy.deriveViewModel(state, consent, {
+    let [state, consent] = await Promise.all([getUpdateState(), getConsentState()]);
+    const busy = state.state === 'checking' || policy.isExecutionState(state.state) || consent.authorizationId;
+    const runtime = busy ? { state: 'transaction_active' } : await readRuntimeStatus();
+    if (runtime.state === 'aligned' && ['failed', 'rolled_back'].includes(state.state) &&
+        policy.compareStableVersions(state.latestVersion || state.currentVersion, runtime.installedVersion) <= 0) {
+      state = await setUpdateState({ ...state, state: 'idle', currentVersion: runtime.installedVersion,
+        latestVersion: runtime.installedVersion, code: '', message: '', transactionId: '', blocker: '', blockers: [] });
+    }
+    const view = policy.deriveViewModel(state, consent, {
       currentVersion: currentVersion(),
       now: Date.now()
     });
+    view.runtime = runtime;
+    const pending = (await chrome.storage.local.get(MANUAL_RELOAD_TABS_KEY))?.[MANUAL_RELOAD_TABS_KEY];
+    const pagesPending = runtime.state === 'aligned' && pending?.targetVersion === runtime.installedVersion && pending.tabIds?.length;
+    if (runtime.state === 'reload_required' || pagesPending) {
+      view.showPanel = true;
+      view.state = { ...state, state: pagesPending ? 'reload_tabs_required' : 'reload_required',
+        currentVersion: runtime.extensionVersion, latestVersion: runtime.installedVersion,
+        code: 'update_reload_required', message: runtimeReloadMessage };
+      view.badge = { text: 'UP', color: '#3578bd' };
+    }
+    return view;
+  }
+
+  async function readRuntimeStatus(force = false) {
+    if (!root.CodexOverleafUpdateRuntimeIdentity) return { state: 'unknown' };
+    if (!force && runtimeStatus && Date.now() - runtimeStatusAt < 5000) return runtimeStatus;
+    if (runtimeStatusRead) return runtimeStatusRead;
+    runtimeStatusRead = withTimeout(requestNative('update.status'), 4000,
+      codedError('update_status_timeout', 'Installed version inspection timed out.')).then(status => {
+      runtimeStatusAt = Date.now();
+      runtimeStatus = root.CodexOverleafUpdateRuntimeIdentity.inspectInstalledRuntime(status, {
+        extensionVersion: chrome.runtime.getManifest().version, runtimeVersion: currentVersion()
+      });
+      return runtimeStatus;
+    }).catch(() => ({ state: 'unknown' })).finally(() => { runtimeStatusRead = null; });
+    return runtimeStatusRead;
+  }
+
+  async function requireReloadSafePoint() {
+    const tabs = await chrome.tabs.query({ url: OVERLEAF_MATCHES });
+    const probes = await Promise.all(tabs.filter(isUsableEditorTab).map(tab => probeTabIdle(tab.id)));
+    const nativeGate = await requestNative('update.canApply').then(result => ({ ok: true, result }))
+      .catch(error => ({ ok: false, error: safeError(error) }));
+    const blockers = root.CodexOverleafUpdateStatus?.collectBlockers(probes, nativeGate) || ['busy'];
+    if (nativeBridge?.getPendingState?.().executionRequests > 0) blockers.push('background_execution_pending');
+    if (blockers.length) {
+      runtimeReloadMessage = 'Reload is waiting for Overleaf to be saved and idle (' + blockers.join(', ') + ').';
+      throw codedError('update_reload_busy', runtimeReloadMessage);
+    }
+    runtimeReloadMessage = '';
+    return tabs.filter(tab => Number.isInteger(tab.id) && !tab.discarded && tab.status !== 'unloaded');
+  }
+
+  async function reloadInstalledRuntime() {
+    const runtime = await readRuntimeStatus(true);
+    if (runtime.state === 'aligned') { await finishManualRuntimeReload(); return getView(); }
+    if (runtime.state !== 'reload_required') throw codedError('update_reload_unavailable', 'No verified installed update is awaiting reload.');
+    const tabs = await requireReloadSafePoint();
+    await chrome.storage.local.set({ [MANUAL_RELOAD_TABS_KEY]: {
+      targetVersion: runtime.installedVersion, tabIds: tabs.map(tab => tab.id)
+    } });
+    setTimeout(() => chrome.runtime.reload(), 0);
+    return getView();
+  }
+
+  async function finishManualRuntimeReload() {
+    const pending = (await chrome.storage.local.get(MANUAL_RELOAD_TABS_KEY))?.[MANUAL_RELOAD_TABS_KEY];
+    if (!pending || !Array.isArray(pending.tabIds)) return;
+    const runtime = await readRuntimeStatus(true);
+    if (runtime.state !== 'aligned' || runtime.installedVersion !== pending.targetVersion) return;
+    let tabs;
+    try { tabs = await requireReloadSafePoint(); } catch (_error) { return; }
+    const remaining = [];
+    for (const tab of tabs.filter(tab => pending.tabIds.includes(tab.id))) {
+      try { await chrome.tabs.reload(tab.id); } catch (_error) { remaining.push(tab.id); }
+    }
+    if (remaining.length) await chrome.storage.local.set({ [MANUAL_RELOAD_TABS_KEY]: { ...pending, tabIds: remaining } });
+    else await chrome.storage.local.remove(MANUAL_RELOAD_TABS_KEY);
   }
 
   async function publishView() {

package/extension/src/content/activeTurnControl.js

@@ -123,6 +123,7 @@
           const raw = entry?.event || {};
           if (raw.type === 'codex.turn.bound') {
             session.codexThreadId = String(raw.detail?.threadId || session.codexThreadId || '');
+            record.codexThreadId = String(raw.detail?.threadId || record.codexThreadId || '');
             record.codexTurnId = String(raw.detail?.turnId || record.codexTurnId || '');
             record.nativeEventSeq = sequence;
             continue;

package/extension/src/content/assetTransferBroker.js

@@ -139,8 +139,10 @@
       // recordUndoFromApply classify a successful Track write as legacy Undo,
       // which hides Accept and prevents the lifecycle from surviving reload.
       merged.trackedChanges.push(...(Array.isArray(result?.trackedChanges) ? result.trackedChanges : []));
+      if (result?.trackedChangeCaptures?.length) (merged.trackedChangeCaptures ||= []).push(...result.trackedChangeCaptures);
       if (result?.ok !== true) merged.ok = false;
     }
+    if (merged.trackedChangeCaptures?.some(capture => capture.state !== 'observed')) merged.trackedChanges = [];
     if (merged.skipped.length) merged.ok = false;
     return merged;
   }

package/extension/src/content/contentRuntime.js

@@ -51,8 +51,7 @@
     'codex.providers.delete',
     'task.run',
     'mirror.sync',
-    'mirror.patchFiles',
-    'mirror.confirmWriteback',
+    'mirror.patchFiles', 'mirror.confirmWriteback', 'mirror.invalidate',
     'mirror.scanSensitive',
     'codex.history.clearPlugin',
     'skills.list',
@@ -418,6 +417,8 @@
   const runTimelineView = Modules.RunTimelineView.create({
     RunGuidanceView: Modules.RunGuidanceView,
     RunResultActions: runResultActions,
+    RunScrollLayout: Modules.RunScrollLayout,
+    RunFailureNotice: Modules.RunFailureNotice,
     tr,
     tx,
     getLocale,
@@ -581,6 +582,7 @@
     RUN_SNAPSHOT_ZIP_TIMEOUT_MS,
     getState: () => state,
     getCurrentRunView: () => currentRunView,
+    appendRunRecordEvent,
     onMirrorRefreshSettled: runSettlementPersistence.settleMirrorRefresh
   });
   const {
@@ -788,6 +790,7 @@
     },
     saveState,
     saveStateSoon,
+    onProjectFilesReady: refreshHistoricalProjectReferences,
     updateActiveSession,
     callPageBridge,
     getCurrentProjectId,
@@ -835,6 +838,7 @@
   });
 
   let panel = null;
+  let probeStatusSnapshot = null;
   let panelRendererInstance = null;
   let sessionPanelInstance = null;
   let settingsPanelInstance = null;
@@ -1031,7 +1035,7 @@
     providerSettingsCoordinator.syncSessionProvider().catch(() => {});
     syncOtWarmMirrorController().catch(error => {
       updateOtStatusDisplay('unavailable');
-      appendPlainLog(tx(`Failed to sync experimental OT warm mirror: ${error.message}`, `同步实验性 OT 预热镜像失败：${error.message}`));
+      appendPlainLog(tx(`Failed to sync OT warm mirror: ${error.message}`, `同步 OT 预热镜像失败：${error.message}`));
     });
     await refreshProbe({ quiet: true });
   }
@@ -1274,6 +1278,7 @@
           onProvidersOpen: () => providerSettingsCoordinator.open(),
           onClearAllHistory: () => clearAllHistoryWithConfirm(),
           onHistoryOpen: () => renderAuditHistoryPanel(),
+          onStorageOpen: () => refreshStorageUsageSummary(),
           onHistoryFilter: () => applyAuditHistoryFilter(),
           // Experimental OT mirror: a single visible switch whose click is
           // intercepted so the confirm-before-enable flow still runs.
@@ -1444,9 +1449,6 @@
   function renderAttachmentPreviewList(attachments = [], container, options = {}) {
     return composerAttachmentController.renderAttachmentPreviewList(attachments, container, options);
   }
-
-
-
   function applyLocaleToPanel() {
     if (!panel) {
       return;
@@ -1535,6 +1537,17 @@
     updateModelDisplay();
     renderSessionList();
     renderContextSelection();
+    const probeStatus = panel.querySelector('[data-probe-status]');
+    if (probeStatus?.dataset.refreshing === 'true') probeStatus.textContent = tr('refreshProbeLoading');
+    else if (probeStatus && probeStatusSnapshot?.projectId === getCurrentProjectId()) {
+      const { failed, probe, userInitiated } = probeStatusSnapshot;
+      const text = failed ? tr('refreshProbeFailed') : formatProbeStatusBar(probe);
+      probeStatus.textContent = userInitiated && !failed ? tr('refreshProbeDone', { status: text }) : text;
+      if (!failed) updateExistingProbeNotice(probe);
+    }
+    updateSkillsEntrySummary();
+    providerSettingsCoordinator.renderSummary();
+    if (settingsPanelInstance?.container?.querySelector('[data-storage-card]')?.open) refreshStorageUsageSummary();
   }
 
   function setElementTitleAndAria(selector, title, ariaLabel) {
@@ -1764,9 +1777,7 @@
     return contextTrayController.setContextStatus(text);
   }
 
-  function resetContextProject() {
-    return contextTrayController.resetContextProject();
-  }
+  function resetContextProject() { return contextTrayController.resetContextProject(); }
 
   async function runTask(options = {}) {
     // Barrier on a still-flying background mirror refresh from the previous
@@ -2393,7 +2404,7 @@
         }
 
         await saveState();
-        applyStateToPanel();
+        applyStateToPanel({ preserveScroll: true });
       } catch (persistenceError) {
         appendRunEvent({
           title: tx('Codex result was generated, but saving local session history failed.', 'Codex 结果已生成，但保存本地会话记录失败。'),
@@ -2473,14 +2484,15 @@
       setRunning(false);
       nativeChannel.clearActiveRequest();
       stopRunElapsedTick();
-      if (isExperimentalOtEnabled()) {
-        await resumeOtWarmMirror('run-settled');
-      }
       await flushQueuedSaveState().catch(() => {});
       currentRunView = null;
       runCancellationRequested = false;
       runCancellationController = null;
       activeTurnControl.release(settlement.requestId);
+      if (isExperimentalOtEnabled()) {
+        try { await resumeOtWarmMirror('run-settled'); }
+        catch (_error) { updateOtStatusDisplay('unavailable'); }
+      }
       if (settlement.requestId) {
         activeTurnControl.acknowledge(settlement.requestId).catch(() => {});
       }
@@ -4943,6 +4955,7 @@
   }
 
   async function refreshProbe(options = {}) {
+    const projectId = getCurrentProjectId();
     const userInitiated = options.userInitiated === true;
     if (userInitiated) {
       setRefreshProbeLoading(true);
@@ -4958,6 +4971,8 @@
       const probe = await callPageBridge('probe', {
         manualOverride: state?.requireReviewing === false
       });
+      if (projectId !== getCurrentProjectId()) return null;
+      probeStatusSnapshot = { projectId, probe, userInitiated };
       const status = panel?.querySelector('[data-probe-status]');
       if (status) {
         status.textContent = userInitiated
@@ -4976,6 +4991,8 @@
       if (!userInitiated) {
         throw error;
       }
+      if (projectId !== getCurrentProjectId()) return null;
+      probeStatusSnapshot = { projectId, failed: true };
       const status = panel?.querySelector('[data-probe-status]');
       if (status) {
         status.textContent = tr('refreshProbeFailed');
@@ -5553,6 +5570,7 @@
           title: session.title || '',
           titleSource: session.titleSource || 'auto',
           focusFiles: session.focusFiles || [],
+          projectReferenceFiles: session.projectReferenceFiles || [],
           codexThreadId: session.codexThreadId || '',
           createdAt: session.createdAt,
           updatedAt: session.updatedAt,
@@ -5960,15 +5978,7 @@
   }
 
   function getRenderedModelEntries() {
-    return Array.from(panel?.querySelector('[data-model]')?.options || []).map(option => ({
-      id: option.value,
-      label: option.textContent,
-      reasoningEfforts: (option.dataset.reasoningEfforts || '').split(',').filter(Boolean),
-      defaultReasoningEffort: option.dataset.defaultReasoningEffort || '',
-      reasoningPresentation: option.dataset.reasoningPresentation || '',
-      speedTiers: (option.dataset.speedTiers || 'standard').split(',').filter(Boolean),
-      defaultSpeedTier: option.dataset.defaultSpeedTier || 'standard'
-    }));
+    return Modules.ModelPickerSupport.getRenderedModelEntries(panel);
   }
 
   async function selectMode(mode) {
@@ -6069,7 +6079,7 @@
     saveStateSoon();
   }
 
-  function applyStateToPanel() {
+  function applyStateToPanel(options = {}) {
     applyPanelTheme(getThemePreference());
     if ((state.providerId || 'builtin') === 'builtin' && !modelSelectHasOption(state.model)) {
       renderModelOptions(getModelCatalog().FALLBACK_MODELS, state.model);
@@ -6105,7 +6115,8 @@
     syncModeControls();
     applySessionLabel();
     renderSessionList();
-    renderRunHistory();
+    renderRunHistory(options);
+    getTrackedChangeCaptureController().schedule();
     renderContextSelection();
     renderContextSummary();
     // v1.8.0 C4: refresh recovery — small attachments persisted in state are
@@ -6195,7 +6206,7 @@
       undoExpectedFiles: [],
       undoStatus: '',
       queueItemId,
-      nativeRequestId: '',
+      nativeRequestId: '', codexThreadId: '',
       codexTurnId: '',
       nativeEventSeq: 0,
       executionSnapshot: executionSnapshot
@@ -6362,7 +6373,7 @@
     currentRunView.activeTurn = { threadId, turnId };
     const record = findRunRecord(currentRunView.recordId, currentRunView.sessionId);
     if (record) {
-      record.codexTurnId = turnId;
+      record.codexThreadId = threadId; record.codexTurnId = turnId;
       record.nativeEventSeq = Math.max(Number(record.nativeEventSeq || 0), Number(journalSeq || 0));
     }
     if (threadId) {
@@ -6736,6 +6747,13 @@
     return files;
   }
 
+  function refreshHistoricalProjectReferences(project) {
+    if (!project?.id || String(project.id) !== getCurrentProjectId()) return;
+    state = updateActiveSession(state, { projectReferenceFiles: captureProjectReferenceFiles(project) });
+    saveStateSoon();
+    if (!currentRunView && !trackedChangeInFlight.size) renderRunHistory({ preserveScroll: true });
+  }
+
   function persistCurrentProjectReferenceFiles(project) {
     const projectFiles = captureProjectReferenceFiles(project);
     if (currentRunView) {
@@ -6867,6 +6885,7 @@
         runProjectId: getRunProjectIdForWriteback(run)
       });
       const undoApplied = isUndoResultEffectivelyApplied(run, result);
+      writebackOrchestrator.invalidateMirrorAfterUndo(runId, getRunProjectIdForWriteback(run), result);
       appendUndoReviewingPolicyEvent(runId, result.reviewingPolicy);
       appendRunRecordEvent(runId, {
         title: tr('undoResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 }),
@@ -6929,11 +6948,16 @@
     });
 
     let result;
+    let trackedUndoPostFilesAtDispatch;
     try {
+      trackedUndoPostFilesAtDispatch = buildTrackedUndoPostFiles(run);
       result = await callPageBridge('rejectTrackedChanges', {
         trackedChanges: run.undoTrackedChanges || [],
         expectedFiles: run.undoExpectedFiles || [],
-        postFiles: buildTrackedUndoPostFiles(run),
+        postFiles: trackedUndoPostFilesAtDispatch,
+        untrackedUndo: run.executionSnapshot
+          ? run.executionSnapshot.requireReviewing === false && ['submitted', 'legacy-captured'].includes(run.executionSnapshot.source)
+          : getTrackedChangeCaptureController().hasLegacyUntrackedCheckpoint(run),
         // Welcome-panel + write-guard:
         // bind the reject to the run's original project. If the user has
         // navigated away the page-side guard refuses with
@@ -6945,6 +6969,7 @@
         trackedChangeInFlight.delete(runId);
       }
     }
+    writebackOrchestrator.invalidateMirrorAfterUndo(runId, getRunProjectIdForWriteback(run), result);
     appendRunRecordEvent(runId, {
       title: trackedUndo
         ? tr('undoTrackedResult', { applied: result.applied?.length || 0, skipped: result.skipped?.length || 0 })
@@ -6964,7 +6989,8 @@
     });
     if (lifecycleReject) {
       WritebackSettlement.attachUndoNotVerifiedFailure(run, result, {
-        buildFailure: buildContentFailure
+        buildFailure: buildContentFailure,
+        postFiles: trackedUndoPostFilesAtDispatch
       });
       applyTrackedChangeSettlement(runId, 'reject', result);
       return;
@@ -7178,6 +7204,25 @@
     return WritebackSettlement.attachVerifiedContentToOperation(operation, result);
   }
 
+  let trackedChangeCaptureController = null;
+  function getTrackedChangeCaptureController() {
+    return trackedChangeCaptureController ||= Modules.TrackedChangeCaptureController.create({
+      getRuns: () => (state.sessions || []).flatMap(session => session.runs || []),
+      getProjectId: () => window.location.pathname.match(/^\/project\/([^/]+)/)?.[1] || '',
+      buildExpectedFilesAfterOperations, normalizeTrackedChanges: normalizeApplyTrackedChanges, callPageBridge,
+      persist: () => flushQueuedSaveState({ preserveRunActionPayload: true }),
+      refresh: run => refreshRunCardControls(run.id),
+      notify: (run, kind, detail) => appendRunRecordEvent(run.id, {
+        title: {
+          pending: tx('Files written; confirming tracked changes.', '文件已写入，正在确认留痕记录。'),
+          observed: tx('Tracked changes confirmed; Accept is available.', '留痕记录已确认，可以接受改动。'),
+          needs_review: tx('Tracked changes could not be safely attributed. Review them in Overleaf; Undo is preserved.', '留痕归属尚未确认，请在 Overleaf 审阅；原有撤销能力已保留。')
+        }[kind], status: 'info', detail
+      }),
+      onError: error => appendPlainLog(tx('Tracked-change confirmation unavailable: ', '留痕确认暂不可用：') + error.message)
+    });
+  }
+
   function recordUndoFromApply(project, applyResult) {
     const appliedEntries = getAppliedEntries(applyResult);
     if (!currentRunView?.recordId || !appliedEntries.length) {
@@ -7221,6 +7266,7 @@
       if (combinedTrackedChanges.length) {
         record.trackedChangeStatus = 'pending';
       }
+      getTrackedChangeCaptureController().record(record, applyResult?.trackedChangeCaptures);
       refreshRunCardControls(record.id);
       if (combinedTrackedChanges.length) {
         appendRunEvent({
@@ -7285,38 +7331,12 @@
     return WritebackSettlement.normalizeApplyTrackedChanges(changes);
   }
 
-  function selectExpectedFilesForTrackedUndo(
-    project,
-    operations = [],
-    trackedChanges = [],
-    previousExpectedFiles = []
-  ) {
-    return WritebackSettlement.selectExpectedFilesForTrackedUndo(
-      project,
-      operations,
-      trackedChanges,
-      previousExpectedFiles
-    );
+  function selectExpectedFilesForTrackedUndo(project, operations = [], trackedChanges = [], previousExpectedFiles = []) {
+    return WritebackSettlement.selectExpectedFilesForTrackedUndo(project, operations, trackedChanges, previousExpectedFiles);
   }
 
   function buildTrackedUndoPostFiles(run) {
-    const expectedFiles = Array.isArray(run?.undoExpectedFiles) ? run.undoExpectedFiles : [];
-    const appliedOperations = Array.isArray(run?.appliedOperations) ? run.appliedOperations : [];
-    if (!expectedFiles.length || !appliedOperations.length) {
-      return [];
-    }
-
-    const postFilesByPath = buildExpectedFilesAfterOperations(
-      { files: expectedFiles },
-      appliedOperations
-    );
-    const expectedPaths = new Set(expectedFiles.map(file => file?.path).filter(Boolean));
-    return Array.from(postFilesByPath.entries())
-      .filter(([path, content]) => expectedPaths.has(path) && typeof content === 'string')
-      .map(([path, content]) => ({
-        path,
-        content
-      }));
+    return getTrackedChangeCaptureController().buildPostFiles(run);
   }
 
   function hasTrackedEditorUndo(run) {

package/extension/src/content/contextTray.js

@@ -22,6 +22,7 @@
     setState = () => {},
     saveState = null,
     saveStateSoon = () => {},
+    onProjectFilesReady = () => {},
     updateActiveSession = defaultUpdateActiveSession,
     callPageBridge = () => Promise.resolve({ ok: false }),
     getCurrentProjectId = () => '',
@@ -201,6 +202,7 @@
         renderContextFiles(contextProject);
         if (isExactContextFileListProject(contextProject)) {
           setContextSyncState('exact-ready');
+          onProjectFilesReady(contextProject);
         } else if (contextSyncState !== 'partial') {
           setContextSyncState('exact-loading');
           void enhanceContextFilesFromExactSnapshot({ loadId: contextLoadId });
@@ -224,6 +226,7 @@
         contextProject = project;
         setContextSyncState(isExactContextFileListProject(project) ? 'exact-ready' : 'exact-loading');
         renderContextFiles(project);
+        if (isExactContextFileListProject(project)) onProjectFilesReady(project);
         if (!isExactContextFileListProject(project)) {
           void enhanceContextFilesFromExactSnapshot({
             force: Boolean(options.force),
@@ -292,6 +295,7 @@
         contextProject = project;
         setContextSyncState('exact-ready');
         renderContextFiles(project);
+        onProjectFilesReady(project);
       } catch (_error) {
         // The page file tree remains usable when the optional exact ZIP list is unavailable.
         if (loadId === contextLoadId) {

package/extension/src/content/diagnosticsController.js

@@ -359,7 +359,7 @@
     if (!options.collectOnly) {
       showDiagnosticsLoading(tr('diagnosticsOtTitle'), tr('diagnosticsLoading'));
     }
-    // OT warm mirror is experimental and off by default. When it is disabled
+    // OT warm mirror is opt-in and off by default. When it is disabled
     // there is nothing live to probe, so report a clean, healthy "disabled"
     // state instead of querying (then warning about) absent OT metadata — or
     // degrading to the generic "could not run" error if a probe throws. A
@@ -374,6 +374,14 @@
         nextStep: '',
         technical: ''
       };
+      const mirrorState = getOtWarmMirrorState?.() || {};
+      if (mirrorState.failureActive && mirrorState.lastFailure) {
+        const failure = mirrorState.lastFailure;
+        disabledResult.status = 'warning';
+        disabledResult.summary = tr(otWarmMirrorController.getFailureMessageKey(failure.code));
+        disabledResult.nextStep = tr('otFailureNextStep');
+        disabledResult.technical = `lastErrorCode: ${failure.code}\nphase: ${failure.phase}\nfailedAt: ${new Date(failure.at).toISOString()}`;
+      }
       if (options.collectOnly) {
         return disabledResult;
       }
@@ -434,6 +442,7 @@
     const queuedEventCount = normalizeOtDiagnosticsCount(otStatus?.queuedEventCount);
     const lastEventAt = formatOtDiagnosticValue(otStatus?.lastEventAt, tr('noneValue'));
     const warmMirrorState = getOtWarmMirrorState() || {};
+    const failureActive = warmMirrorState.failureActive === true;
     const lastOtPatchAt = formatOtDiagnosticValue(mirrorStatus?.lastOtPatchAt || warmMirrorState.lastPatchAt, tr('noneValue'));
     const lastOtErrorCode = formatOtDiagnosticValue(mirrorStatus?.lastOtErrorCode || warmMirrorState.lastErrorCode, tr('noneValue'));
     const lastErrorCode = formatOtDiagnosticValue(otStatus?.lastErrorCode || otStatus?.reason || otStatus?.error, tr('noneValue'));
@@ -445,13 +454,14 @@
     const bridgeFailed = otStatus?.ok === false;
     const focusFiles = getActiveFocusFiles();
     const otWarmStart = otWarmMirrorController?.canUseOtWarmStart?.({ enabled, focusFiles, mirrorStatus }) || { ok: false };
-    const fallback = !enabled || statusValue !== 'observing' || bridgeFailed || otWarmStart?.ok !== true;
+    const fallback = !enabled || failureActive || statusValue !== 'observing' || bridgeFailed || otWarmStart?.ok !== true;
 
     return {
       title: tr('diagnosticsOtTitle'),
       subtitle: tr('diagnosticsOtSubtitle'),
       status: enabled && !fallback && !bridgeFailed ? 'completed' : (enabled || bridgeFailed ? 'warning' : 'completed'),
-      summary: tr(enabled ? 'diagnosticsOtSummaryEnabled' : 'diagnosticsOtSummaryDisabled'),
+      summary: tr(failureActive ? otWarmMirrorController.getFailureMessageKey(warmMirrorState.lastErrorCode)
+        : enabled ? 'diagnosticsOtSummaryEnabled' : 'diagnosticsOtSummaryDisabled'),
       bullets: [
         `${tr('otStatus')}: ${formatOtStatusLabel(statusValue)}`,
         `${tr('otFreshFiles')}: ${otFreshFileCount}`,
@@ -631,6 +641,10 @@
         lines.push(`CodeMirror: docLength=${view.docLength || 0}; dispatch=${Boolean(view.hasDispatch)}; source=${view.source || 'unknown'}`);
       }
     }
+    const capture = probe?.trackedChangeCapture;
+    if (capture) lines.push(tx('Tracked ledger: ', '留痕记录：')
+      + 'source=' + capture.source + '; ready=' + capture.ready + '; count=' + capture.count
+      + '; doc=' + (capture.docId || 'none') + '; adapter=' + capture.adapter + '; reason=' + (capture.reason || 'none'));
     const projectDiagnostics = probe?.projectDiagnostics;
     if (projectDiagnostics) {
       lines.push(`Project records: ${projectDiagnostics.docRecordCount || 0}; roots=${(projectDiagnostics.internalRootKeys || []).slice(0, 6).join(', ') || 'none'}`);