codex-overleaf-link 2.5.0 → 2.5.1

package/extension/src/content/sensitivePreflight.js

@@ -0,0 +1,140 @@
+(function initCodexOverleafSensitivePreflight(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafSensitivePreflight = factory();
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function sensitivePreflightFactory() {
+  'use strict';
+
+  function create({
+    SensitiveScan, normalizeGovernanceRules, isTextSnapshotFile, sendBackgroundNative,
+    getCurrentProjectId, appendRunEvent, appendCompletionReport, showPluginConfirm, tr, tx
+  }) {
+    async function runSensitivePreflight(options) {
+      options = options || {};
+      const { task, project, rules, useExistingMirror = false, guidance = false } = options;
+      const normalizedRules = normalizeGovernanceRules(rules);
+      if (normalizedRules.sensitiveCheckEnabled === false) {
+        return { blocked: false, findings: [] };
+      }
+      if (!SensitiveScan?.scanSensitiveInputs && !useExistingMirror) {
+        return { blocked: false, findings: [] };
+      }
+      let findings = SensitiveScan?.scanSensitiveInputs
+        ? SensitiveScan.scanSensitiveInputs({
+          task,
+          files: guidance ? [] : (project?.files || []).filter(isTextSnapshotFile)
+        })
+        : [];
+      if (useExistingMirror && !guidance) {
+        findings = dedupeSensitiveFindings([
+          ...findings,
+          ...await scanNativeMirrorSensitiveFindings()
+        ]);
+      }
+      if (!findings.length) {
+        return { blocked: false, findings: [] };
+      }
+      options.assertCurrent?.();
+      appendRunEvent({
+        title: tx(
+          `Sensitive content check found ${findings.length} item(s).`,
+          `敏感内容检查发现 ${findings.length} 项。`
+        ),
+        status: 'failed',
+        detail: findings.slice(0, 8).map(finding => ({
+          [tr('detailFile')]: finding.path || finding.source || 'task',
+          [tr('detailReason')]: finding.detectorId,
+          [tx('Preview', '预览')]: finding.preview || '[REDACTED]'
+        }))
+      });
+      if (normalizedRules.sensitiveConfirmAllowed === true) {
+        const approved = await showPluginConfirm({
+          title: tr('sensitiveConfirmTitle'),
+          message: formatSensitiveConfirmMessage(findings),
+          confirmLabel: guidance ? tx('Send guidance', '发送指导') : tr('sensitiveConfirmRun'),
+          cancelLabel: tr('confirmDefaultCancel'),
+          destructive: true
+        });
+        options.assertCurrent?.();
+        return { blocked: !approved, findings };
+      }
+      // Blocking an extra message must not finish the task already in progress.
+      if (guidance) return { blocked: true, findings };
+      appendCompletionReport({
+        conclusion: tx(
+          'This run was blocked before Codex received project context because sensitive content was detected.',
+          '检测到敏感内容，本轮已在向 Codex 发送项目上下文前阻止。'
+        ),
+        status: 'blocked',
+        operations: [],
+        applyResults: [],
+        nextStep: tx(
+          'Remove the sensitive content, narrow @context, or enable explicit sensitive confirmation in Project Settings.',
+          '请移除敏感内容、缩小 @context，或在项目设置里允许敏感内容显式确认。'
+        )
+      });
+      return { blocked: true, findings };
+    }
+
+    function formatSensitiveConfirmMessage(findings = []) {
+      const visible = findings.slice(0, 8).map(finding => {
+        const path = finding.path || finding.source || 'task';
+        return `${path}: ${finding.detectorId || 'sensitive'} (${finding.preview || '[REDACTED]'})`;
+      });
+      return [
+        tr('sensitiveConfirmMessage'),
+        '',
+        ...visible,
+        findings.length > visible.length ? tx(`${findings.length - visible.length} more finding(s).`, `另有 ${findings.length - visible.length} 项。`) : ''
+      ].filter(Boolean).join('\n');
+    }
+
+    async function scanNativeMirrorSensitiveFindings() {
+      try {
+        const response = await sendBackgroundNative({
+          method: 'mirror.scanSensitive',
+          params: { projectId: getCurrentProjectId() }
+        });
+        if (response?.ok) {
+          return Array.isArray(response.result?.findings) ? response.result.findings : [];
+        }
+        return [{
+          detectorId: 'mirror-sensitive-scan-unavailable',
+          source: 'local-mirror',
+          preview: response?.error?.message || 'Could not scan the local mirror before Codex runs.'
+        }];
+      } catch (error) {
+        return [{
+          detectorId: 'mirror-sensitive-scan-unavailable',
+          source: 'local-mirror',
+          preview: error?.message || 'Could not scan the local mirror before Codex runs.'
+        }];
+      }
+    }
+
+    function dedupeSensitiveFindings(findings = []) {
+      const seen = new Set();
+      const deduped = [];
+      for (const finding of findings || []) {
+        const key = [
+          finding?.detectorId || '',
+          finding?.source || '',
+          finding?.path || '',
+          finding?.preview || ''
+        ].join('\u0000');
+        if (seen.has(key)) {
+          continue;
+        }
+        seen.add(key);
+        deduped.push(finding);
+      }
+      return deduped;
+    }
+
+    return { run: runSensitivePreflight };
+  }
+
+  return { create };
+});

package/extension/src/content/sessionForkController.js

@@ -7,15 +7,32 @@
 
   function create(deps = {}) {
     const {
-      SessionState, getState, setState, sendBackgroundNative, saveState,
+      SessionState, getState, setState, getScope, sendBackgroundNative, saveState,
       applyStateToPanel, showPluginToast, tr
     } = deps;
 
     async function forkRunFromNode(runId) {
       const previousState = getState();
+      const skillPreferences = {
+        loadCodexLocalSkills: previousState.loadCodexLocalSkills !== false,
+        loadCodexOverleafSkills: previousState.loadCodexOverleafSkills !== false,
+        codexLocalSkillEnabled: { ...previousState.codexLocalSkillEnabled }
+      };
       const source = findSource(previousState, runId);
       if (!source) return failFork('session_fork_source_missing', tr('forkRunUnavailable'));
-      const { session, run, runIndex } = source;
+      const scope = getScope ? { ...getScope() } : null;
+      const requestedActiveId = previousState.activeSessionId;
+      // The Native request and copied history must describe the same origin,
+      // even when the source session is edited while the request is pending.
+      const { session, run, runIndex } = JSON.parse(JSON.stringify(source));
+      const sameScope = () => {
+        const current = getScope?.();
+        return !scope || ['accountScopeId', 'projectId', 'generation'].every(key => current?.[key] === scope[key]);
+      };
+      const currentSource = () => {
+        const current = findSource(getState(), runId);
+        return current?.session.id === session.id && current.run.codexTurnId === run.codexTurnId;
+      };
       const draftThreadId = run.codexTurnId && run.interruptedDraft?.turnId === run.codexTurnId
         ? run.interruptedDraft.threadId : '';
       // Provider switches replace the session thread, not the selected node's origin.
@@ -25,25 +42,39 @@
       }
       let response;
       try {
+        const resolveLocalSkills = deps.captureLocalSkillIdsForFork || deps.getEnabledCodexLocalSkillIds;
+        const enabledCodexLocalSkillIds = skillPreferences.loadCodexLocalSkills
+          ? captureLocalSkillIds(await resolveLocalSkills?.(skillPreferences)) : [];
+        if (!sameScope() || !currentSource()) return null;
+        if (resolveLocalSkills && !Array.isArray(enabledCodexLocalSkillIds)) {
+          throw codedError('codex_local_skill_unavailable', tr('forkRunFailed'));
+        }
         response = await sendBackgroundNative({
           method: 'codex.thread.fork',
           params: {
             threadId: sourceThreadId,
             lastTurnId: run.codexTurnId,
             speedTier: session.speedTier,
-            loadCodexLocalSkills: previousState.loadCodexLocalSkills !== false,
-            loadCodexOverleafSkills: previousState.loadCodexOverleafSkills !== false
+            loadCodexLocalSkills: skillPreferences.loadCodexLocalSkills,
+            loadCodexOverleafSkills: skillPreferences.loadCodexOverleafSkills,
+            enabledCodexLocalSkillIds
           }
         });
       } catch (error) {
+        if (!sameScope() || !currentSource()) return null;
         return failFork(error?.code || 'session_fork_failed', error?.message || tr('forkRunFailed'));
       }
+      if (!sameScope() || !currentSource()) {
+        if (response?.ok && response.result?.threadId) await clearFork(response.result.threadId);
+        return null;
+      }
       if (!response?.ok || !response.result?.threadId) {
         return failFork(response?.error?.code || 'session_fork_failed', response?.error?.message || tr('forkRunFailed'));
       }
       const copiedRuns = session.runs.slice(0, runIndex + 1).map(copyRunSnapshot);
       const titleBase = String(session.title || copiedRuns[0]?.task || tr('newSessionFallback')).trim();
-      const forkTitle = buildUniqueForkTitle(previousState.sessions, titleBase);
+      const mergeBase = getState();
+      const forkTitle = buildUniqueForkTitle(mergeBase.sessions, titleBase);
       const forked = SessionState.createSession({
         title: forkTitle,
         titleSource: 'manual',
@@ -62,27 +93,55 @@
         forkedFromSessionId: session.id,
         forkedFromRunId: run.id
       });
-      setState(SessionState.normalizePanelState({
-        ...previousState,
-        sessions: [...(previousState.sessions || []), forked],
-        activeSessionId: forked.id
-      }));
+      const activeId = mergeBase.activeSessionId === requestedActiveId
+        ? forked.id : mergeBase.activeSessionId;
+      const installed = SessionState.setActiveSession({
+        ...mergeBase, sessions: [...(mergeBase.sessions || []), forked]
+      }, activeId);
+      const installedSnapshot = JSON.stringify(installed);
+      const forkSnapshot = JSON.stringify(forked);
+      setState(installed);
       try {
+        // Keep the visible composer and active-session owner aligned during save.
+        applyStateToPanel();
         await saveState();
       } catch (error) {
-        setState(previousState);
-        await sendBackgroundNative({
-          method: 'codex.history.clearPlugin',
-          params: { sessionId: forked.id, threadId: response.result.threadId }
-        }).catch(() => null);
-        showPluginToast(error.message || tr('forkRunFailed'), { status: 'failed', sticky: true });
+        if (sameScope()) {
+          const current = getState();
+          const currentFork = current.sessions?.find(item => item.id === forked.id);
+          // Never erase work entered into the fork after its optimistic insert.
+          if (!currentFork || JSON.stringify(currentFork) === forkSnapshot) {
+            if (currentFork) {
+              if (current === installed && JSON.stringify(current) === installedSnapshot) {
+                setState(mergeBase);
+              } else {
+                const remaining = current.sessions.filter(item => item.id !== forked.id);
+                const fallbackId = remaining.some(item => item.id === mergeBase.activeSessionId)
+                  ? mergeBase.activeSessionId : remaining[remaining.length - 1]?.id;
+                setState(SessionState.setActiveSession({ ...current, sessions: remaining },
+                  current.activeSessionId === forked.id ? fallbackId : current.activeSessionId));
+              }
+              try { applyStateToPanel(); } catch (_renderError) { /* Preserve the original failure and finish cleanup. */ }
+            }
+            await clearFork(response.result.threadId, forked.id);
+          }
+          if (sameScope()) showPluginToast(error.message || tr('forkRunFailed'), { status: 'failed', sticky: true });
+        }
         throw error;
       }
-      applyStateToPanel();
+      // Persistence owns its captured scope. A late result cannot render a new
+      // view or delete a thread that may already have been saved in the old one.
+      if (!sameScope() || !getState().sessions?.some(item => item.id === forked.id)) return null;
       showPluginToast(tr('forkRunDone'), { status: 'completed' });
       return forked;
     }
 
+    async function clearFork(threadId, sessionId) {
+      try {
+        await sendBackgroundNative({ method: 'codex.history.clearPlugin', params: { sessionId, threadId } });
+      } catch (_error) { /* Best-effort cleanup must not restore a stale view. */ }
+    }
+
     function failFork(code, message) {
       showPluginToast(message, { status: 'failed', sticky: true });
       throw codedError(code, message);
@@ -91,6 +150,10 @@
     return { forkRunFromNode };
   }
 
+  function captureLocalSkillIds(value) {
+    return Array.isArray(value) ? [...value] : undefined;
+  }
+
   function buildUniqueForkTitle(sessions = [], sourceTitle = '') {
     const fallback = String(sourceTitle || 'New Session').trim() || 'New Session';
     const baseTitle = fallback

package/extension/src/content/sessionManager.js

@@ -201,7 +201,7 @@
         }
       });
       if (!response?.ok) {
-        showPluginToast(tr('deleteSessionHistoryFailedToast', { message: response?.error?.message || 'native host did not return success' }), { status: 'warning', sticky: true });
+        showPluginToast(tr('deleteSessionHistoryFailedToast', { message: response?.error?.message || tr('deleteSessionNativeFailureDetail') }), { status: 'warning', sticky: true });
       } else if (response.result?.skipped) {
         showPluginToast(tr('deleteSessionNoThreadToast'), { status: 'info' });
       } else {

package/extension/src/content/settingsPanel.js

@@ -242,7 +242,7 @@
               </label>
               <p class="codex-set-row-help" data-i18n="loadCodexLocalSkillsHelp">Pull skills from your local Codex installation.</p>
               <button type="button" class="codex-skills-entry" data-skills-entry>
-                <span class="codex-skills-entry-label" data-i18n="codexOverleafSkillsEntry">Codex Overleaf skills</span>
+                <span class="codex-skills-entry-label" data-i18n="skillsManageEntry">Manage skills</span>
                 <span class="codex-skills-entry-summary" data-skills-entry-summary></span>
                 <span class="codex-skills-entry-chevron" aria-hidden="true">›</span>
               </button>
@@ -252,9 +252,9 @@
       </section>
       <section class="codex-custom-instructions-panel codex-skills-panel" data-skills-screen>
         <div class="codex-custom-instructions-head">
-          <button type="button" data-skills-back title="Back" aria-label="Back">‹</button>
+          <button type="button" data-skills-back data-i18n-title="settingsBack" data-i18n-aria-label="settingsBack" title="Back" aria-label="Back">‹</button>
           <div>
-            <div class="codex-custom-instructions-title" data-i18n="codexOverleafSkillsTitle">Codex Overleaf skills</div>
+            <div class="codex-custom-instructions-title" data-i18n="localSkillsTitle">Skills</div>
           </div>
           <span class="codex-set-saved" data-set-saved hidden><svg class="codex-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="m3.5 8 3 3 6-6"/></svg><span data-i18n="settingsSaved">Saved</span></span>
         </div>
@@ -266,6 +266,9 @@
         </div>
         <div class="codex-skills-divider"></div>
         <div class="codex-local-skill-list" data-local-skill-list></div>
+        <div class="codex-skills-divider"></div>
+        <div class="codex-wb-skills-list-title codex-wb-skills-caption" data-i18n="codexLocalSkillsTitle">Local Codex skills</div>
+        <div class="codex-local-skill-list" data-codex-local-skill-list></div>
       </section>
     `;
 
@@ -338,6 +341,7 @@
       setSkillsSummary: text => setSkillsSummary(instance, text),
       setProviderSummary: summary => setProviderSummary(instance, summary),
       refreshNotes: () => updateGovernanceNotes(instance),
+      refreshLocale: () => instance.workbench?.refresh(),
       destroy: () => destroy(instance),
       _instance: instance
     };

package/extension/src/content/settingsWorkbench.js

@@ -243,6 +243,11 @@
       projectFilter.setAttribute('aria-pressed', String(filter === 'project'));
       closeButton.title = t('settingsWorkbenchClose');
       closeButton.setAttribute('aria-label', t('settingsWorkbenchClose'));
+      const skillsBack = skills?.querySelector('[data-skills-back]');
+      if (skillsBack) {
+        skillsBack.title = t('settingsBack');
+        skillsBack.setAttribute('aria-label', t('settingsBack'));
+      }
       for (const [id, tab] of navButtons) {
         tab.hidden = !availablePages.has(id);
         tab.setAttribute('aria-selected', String(id === active));

package/extension/src/content/sharedSessionViewSync.js

@@ -4,11 +4,39 @@
 })(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
 
+  const sameScope = (a, b) => a.accountScopeId === b.accountScopeId
+    && a.projectId === b.projectId && a.generation === b.generation;
+
+  function applySnapshot(options, sessions) {
+    const previous = options.getState(), scope = options.getScope();
+    const next = options.normalize({ ...previous, sessions }, { restoreRunningRuns: false });
+    const unchangedSnapshot = JSON.stringify(next);
+    options.setState(next);
+    try {
+      options.render();
+    } catch (error) {
+      // A callback may replace state, edit it in place or navigate. Restore only
+      // the unchanged view owned by this failed passive application.
+      let unchanged = false;
+      try {
+        unchanged = options.getState() === next && sameScope(scope, options.getScope())
+          && JSON.stringify(options.getState()) === unchangedSnapshot;
+      } catch (_error) { /* Unknown state must not overwrite a newer edit. */ }
+      if (unchanged) {
+        options.setState(previous);
+        // A second render can also fail. The old merge base still protects
+        // subsequent saves, including values from partially restored controls.
+        try { options.render(); } catch (_error) { /* Report the first failure. */ }
+      }
+      throw error;
+    }
+  }
+
   function install(options) {
-    const { Bridge, StorageDb, getScope, getState, isBusy, apply, notice } = options;
+    const { Bridge, StorageDb, getScope, getState, isBusy, notice } = options;
+    const apply = options.apply || (sessions => applySnapshot(options, sessions));
     let saving = 0, version = 0, pending = false, timer = null, refreshing = false, stopped = false;
-    const sameScope = (a, b) => a.accountScopeId === b.accountScopeId
-      && a.projectId === b.projectId && a.generation === b.generation;
+    let retryCount = 0;
     const signature = state => JSON.stringify([state.activeSessionId,
       (state.sessions || []).map(session => [session.id, session.updatedAt, session.task])]);
     function schedule(delay = 250) {
@@ -37,12 +65,21 @@
         const ids = new Set(records.map(record => record.id));
         const newLocal = (local.sessions || []).filter(session =>
           !ids.has(session.id) && !StorageDb.wasSharedSessionStored(session.id));
-        // The data has now been adopted by this view; future writes may use it
-        // as a merge baseline. Snapshot reads alone never advance the baseline.
-        StorageDb.adoptSharedSessionBaseline(records);
+        // Rendering may fail after only part of the composer was updated.
+        // Keep the prior merge base until the complete view accepts the data.
         apply([...records, ...newLocal]);
+        if (stopped || !sameScope(scope, getScope())) return;
+        if (saving || version !== capturedVersion) { pending = true; return; }
+        StorageDb.adoptSharedSessionBaseline(records);
+        retryCount = 0;
       } catch (error) {
         notice?.(error);
+        // One retry can recover transient DOM failures. Local edits, navigation
+        // and persistent failures stop it; another notification starts afresh.
+        if (!stopped && sameScope(scope, getScope()) && version === capturedVersion
+          && signature(getState()) === capturedSignature && retryCount < 1) {
+          retryCount++; pending = true;
+        }
       } finally {
         refreshing = false;
         schedule(1000);
@@ -51,7 +88,7 @@
     const unsubscribe = Bridge.subscribe(change => {
       const scope = getScope();
       if (!change.projectId || change.projectId === scope.projectId) {
-        pending = true; schedule();
+        retryCount = 0; pending = true; schedule();
       }
     });
     return {
@@ -68,5 +105,5 @@
       }
     };
   }
-  return { install };
+  return { install, applySnapshot };
 });

package/extension/src/content/updateIdle.js

@@ -5,9 +5,10 @@
     let lastUserActivityAt = Date.now();
     let stableSavedSince = 0;
     let applying = false;
+    let saveIdentity;
     const documentRef = options.document || root.document;
     const noteActivity = event => {
-      if (event?.target?.closest?.('#codex-overleaf-panel')) return;
+      if (!options.includePanelActivity && event?.target?.closest?.('#codex-overleaf-panel')) return;
       lastUserActivityAt = Date.now();
       stableSavedSince = 0;
     };
@@ -42,6 +43,7 @@
         saveResult = { ok: false, state: 'unavailable' };
       }
       const saved = saveResult?.ok === true && ['verified_saved', 'verified_quiet'].includes(saveResult?.state);
+      if (saveResult?.identity !== saveIdentity) { stableSavedSince = 0; saveIdentity = saveResult?.identity; }
       if (saved) {
         stableSavedSince = stableSavedSince || Date.now();
       } else {
@@ -62,6 +64,7 @@
 
     return {
       buildIdleProbe,
+      noteActivity,
       handleMessage,
       isApplying: () => applying
     };

package/extension/src/content/updateNotice.js

@@ -245,6 +245,7 @@
     if (!currentView) return;
     renderSettings();
     if (!notice) return;
+    notice.setAttribute('aria-label', tx('Stable update', '稳定版更新'));
     if (!currentView.showPanel) {
       notice.hidden = true;
       notice.replaceChildren();
@@ -355,7 +356,14 @@
     let statusText = '';
     let buttonText = tx('Check for updates', '检查更新');
 
-    if (['reload_required', 'reload_tabs_required'].includes(stateName)) {
+    if (stateName === 'idle' && state.code === 'update_cooldown') {
+      const until = Number(state.cooldownUntil || 0);
+      const time = until > 0 && Number.isFinite(until) ? new Date(until).toLocaleString(getLocale() || undefined) : '';
+      statusText = tx(
+        `Update v${latestVersion} is paused after a failed installation. ${time ? `Check again after ${time}.` : 'Check again after its cooldown ends.'}`,
+        `v${latestVersion} 安装失败后已暂停更新。${time ? `请在 ${time} 后再次检查。` : '请在冷却期结束后再次检查。'}`
+      );
+    } else if (['reload_required', 'reload_tabs_required'].includes(stateName)) {
       summaryText = tx(`Installed v${latestVersion}; running extension v${currentVersion}.`, `已安装 v${latestVersion}；扩展当前运行 v${currentVersion}。`);
       statusText = getCopy(state).detail;
       buttonText = stateName === 'reload_required' ? tx('Reload extension', '重新加载扩展') : tx('Refresh Overleaf tabs', '刷新 Overleaf 标签页');
@@ -373,7 +381,7 @@
       statusText = getCopy(state).detail;
       buttonText = tx('Update in progress', '更新进行中');
     } else if (stateName === 'failed' || stateName === 'rolled_back') {
-      statusText = state.message || getCopy(state).detail;
+      statusText = formatUpdateMessage(state) || getCopy(state).detail;
       buttonText = tx('Retry', '重试');
     } else if (stateName === 'committed') {
       summaryText = tx(`Current v${currentVersion}. Update completed successfully.`, `当前版本 v${currentVersion}。更新已成功完成。`);
@@ -443,11 +451,11 @@
     const target = state.latestVersion ? 'v' + state.latestVersion : '';
     if (state.cancelRequested) return {
       eyebrow: tx('Cancelling update', '正在取消更新'), title: target,
-      detail: state.message || tx('Stopping this update and clearing its authorization.', '正在停止本次更新并清理更新授权。')
+      detail: formatUpdateMessage(state) || tx('Stopping this update and clearing its authorization.', '正在停止本次更新并清理更新授权。')
     };
     if (state.recoveryPending) return {
       eyebrow: tx('Checking update recovery', '正在确认更新恢复状态'), title: target,
-      detail: state.message || tx('Waiting for the installed version to be confirmed.', '正在确认实际安装的版本。')
+      detail: formatUpdateMessage(state) || tx('Waiting for the installed version to be confirmed.', '正在确认实际安装的版本。')
     };
     const blocker = blockersCopy(state.blockers?.length ? state.blockers : [state.blocker]);
     return {
@@ -455,11 +463,11 @@
         detail: tx('Reading the latest signed release.', '正在读取最新签名版本。') },
       reload_required: {
         eyebrow: tx('Installed, awaiting reload', '已安装，等待加载'), title: target,
-        detail: state.message || tx('The new files are installed. Reload the extension when Overleaf is saved and idle.', '新版文件已安装，请在 Overleaf 保存并空闲后重新加载扩展。')
+        detail: formatUpdateMessage(state) || tx('The new files are installed. Reload the extension when Overleaf is saved and idle.', '新版文件已安装，请在 Overleaf 保存并空闲后重新加载扩展。')
       },
       reload_tabs_required: {
         eyebrow: tx('Updated runtime is ready', '新版运行组件已就绪'), title: target,
-        detail: state.message || tx('Refresh the saved, idle Overleaf tabs to load the updated panel.', '刷新已保存且空闲的 Overleaf 标签页以加载新版面板。')
+        detail: formatUpdateMessage(state) || tx('Refresh the saved, idle Overleaf tabs to load the updated panel.', '刷新已保存且空闲的 Overleaf 标签页以加载新版面板。')
       },
       manual_install_required: {
         eyebrow: tx('Reinstall needed for this update', '这次更新需要重新安装'),
@@ -509,7 +517,7 @@
       failed: {
         eyebrow: tx('Update could not continue', '更新无法继续'),
         title: target,
-        detail: state.message || tx('Review the update details and retry.', '请查看更新详情后重试。')
+        detail: formatUpdateMessage(state) || tx('Review the update details and retry.', '请查看更新详情后重试。')
       }
     }[state.state] || { eyebrow: '', title: '', detail: '' };
   }
@@ -521,6 +529,45 @@
     return `npm exec --yes codex-overleaf-link@${version} -- install-managed`;
   }
 
+  function formatUpdateMessage(state = {}) {
+    const code = state.code || '';
+    const messages = {
+      update_phase_timeout: ['The update timed out and its download was stopped. Retry when the connection is available.', '更新超时，下载已停止。连接恢复后请重试。'],
+      update_not_applied: ['The update was stopped before installation. Retry when ready.', '更新已在安装前停止，可准备就绪后重试。'],
+      update_recovery_pending: ['The update result is being checked. Recovery has not been confirmed.', '正在确认更新结果，恢复状态尚未确认。'],
+      update_rolled_back: ['The previous version has been restored.', '已恢复上一版本。'],
+      update_not_managed: ['Run install-managed once to enable coordinated automatic updates.', '请先运行一次 install-managed，以启用扩展与本机服务的协调更新。'],
+      update_native_busy: ['Native Host is still processing a Codex task.', 'Native Host 仍在处理 Codex 任务。'],
+      update_revoke_too_late: ['The update is already being installed. Wait for its result.', '更新已进入安装，请等待结果。'],
+      update_cancel_unconfirmed: ['Update cancellation is unconfirmed. Check recovery before retrying.', '尚未确认更新已取消，请先检查恢复状态。'],
+      update_apply_unconfirmed: ['Update installation is unconfirmed. Check recovery before retrying.', '尚未确认更新安装结果，请先检查恢复状态。'],
+      update_rollback_unconfirmed: ['Restoring the previous version is unconfirmed. Check recovery before retrying.', '尚未确认旧版本已恢复，请先检查恢复状态。'],
+      update_reload_unavailable: ['No verified installed update is awaiting reload.', '当前没有已验证且等待重载的更新。'],
+      update_network_cancelled: ['The update download was cancelled.', '更新下载已取消。'],
+      update_apply_failed: ['The update could not be installed. Check recovery and retry.', '无法安装更新，请检查恢复状态后重试。']
+    };
+    if (messages[code]) return tx(...messages[code]);
+    if (['update_health_failed', 'update_request_failed', 'update_failed'].includes(code)) return tx('The updated components could not be confirmed. Check recovery before retrying.', '尚未确认更新后的组件正常，请先检查恢复状态。');
+    if (['update_bootstrap_health_timeout', 'update_bootstrap_reload_failed'].includes(code)) return tx('The updated startup components did not finish restarting and confirming. Check recovery before retrying.', '更新后的启动组件未能完成重启和确认，请先检查恢复状态。');
+    if (['update_bootstrap_source_mismatch', 'update_bootstrap_source_version_mismatch'].includes(code)) return tx('The installed startup files do not match a supported update source. Check recovery before retrying.', '已安装的启动文件与支持的升级来源不一致，请先检查恢复状态。');
+    if (['update_bootstrap_record_missing', 'update_bootstrap_record_invalid', 'update_bootstrap_backup_mismatch', 'update_bootstrap_already_restoring'].includes(code)) return tx('The startup recovery material could not be confirmed. The update result remains unconfirmed.', '尚未确认启动组件的恢复材料有效，更新结果仍待确认。');
+    if (['update_bootstrap_confirmation_pending', 'update_bootstrap_native_restart_required'].includes(code)) return tx('Waiting for the updated startup components and Native Host to finish restarting and confirming.', '正在等待更新后的启动组件和本机服务完成重启及确认。');
+    if (code === 'update_bootstrap_monitor_unavailable') return tx('The update recovery monitor could not start. Check recovery before retrying.', '更新恢复监护程序未能启动，请先检查恢复状态。');
+    if (['update_bootstrap_transaction_mismatch', 'update_bootstrap_transaction_invalid'].includes(code)) return tx('The startup update transaction could not be matched. Check recovery before retrying.', '未能匹配启动组件的更新事务，请先检查恢复状态。');
+    if (code.startsWith('update_bootstrap_')) return tx('The startup update package or installed files could not be verified. Check recovery before retrying.', '无法验证启动组件更新包或已安装文件，请先检查恢复状态。');
+    if (['update_reload_required', 'update_reload_busy'].includes(code)) {
+      const match = /^Reload is waiting for Overleaf to be saved and idle \(([^)]+)\)\.$/.exec(state.message || '');
+      if (match) return blockersCopy(match[1].split(', '));
+    }
+    if (['update_check_timeout', 'update_activation_timeout', 'update_status_timeout'].includes(code)) return tx('The update operation timed out. Check recovery or retry when the connection is available.', '更新操作超时，请检查恢复状态，或在连接恢复后重试。');
+    if (['update_candidate_missing', 'update_candidate_stale', 'update_not_staged', 'update_staged_archive_invalid', 'update_recovery_superseded'].includes(code)) return tx('No current verified update is ready. Check for updates again.', '当前没有已验证且可安装的更新，请重新检查更新。');
+    if (['update_authorization_in_progress', 'update_transaction_in_progress', 'update_transaction_locked'].includes(code)) return tx('Another update operation is in progress. Wait for it to finish.', '另一项更新操作正在进行，请等待其完成。');
+    if (['update_authorization_invalid', 'update_consent_required', 'update_consent_mismatch', 'update_transaction_mismatch', 'update_transaction_state_changed'].includes(code)) return tx('The update authorization or transaction changed. Check for updates and authorize the current candidate again.', '更新授权或事务已变化，请重新检查更新并确认当前候选版本。');
+    if (['update_archive_checksum_invalid', 'update_archive_compressed_limit', 'update_archive_duplicate_path', 'update_archive_file_count_limit', 'update_archive_file_limit', 'update_archive_invalid', 'update_archive_path_forbidden', 'update_archive_path_too_long', 'update_archive_required_file_missing', 'update_archive_total_limit', 'update_archive_truncated', 'update_archive_type_forbidden', 'update_staging_not_empty', 'update_operation_invalid', 'update_bundle_hash_invalid', 'update_bundle_name_invalid', 'update_bundle_size_invalid', 'update_manifest_artifacts_invalid', 'update_manifest_commit_invalid', 'update_manifest_invalid', 'update_manifest_manual_install_invalid', 'update_manifest_origin_mismatch', 'update_manifest_protocol_invalid', 'update_manifest_schema_unsupported', 'update_manifest_timestamp_invalid', 'update_manifest_too_large', 'update_manifest_version_invalid', 'update_signature_algorithm_unsupported', 'update_signature_invalid', 'update_signature_key_invalid', 'update_signature_key_unknown', 'update_signature_too_large', 'update_version_invalid'].includes(code)) return tx('The signed update or archive could not be verified. Check the release details and retry.', '无法验证更新签名或压缩包，请检查发布详情后重试。');
+    if (['update_github_http_error', 'update_github_response_invalid', 'update_asset_missing', 'update_asset_url_forbidden', 'update_release_asset_invalid', 'update_release_manifest_mismatch', 'update_bundle_size_mismatch', 'update_bundle_hash_mismatch', 'update_native_version_mismatch', 'update_extension_version_mismatch', 'update_runtime_manifest_invalid', 'update_runtime_asset_missing', 'update_bootstrap_manifest_invalid', 'update_managed_layout_invalid', 'update_marker_invalid', 'update_current_version_invalid', 'update_health_version_mismatch', 'update_confirmation_unexpected', 'update_rollback_unavailable'].includes(code)) return tx('The update or installed files could not be verified. Check the update details and repair or retry.', '无法验证更新或已安装文件，请检查更新详情后修复或重试。');
+    return state.message || '';
+  }
+
   function blockerCopy(value) {
     return {
       unsaved: tx('Overleaf has not confirmed that this document is saved.', 'Overleaf 尚未确认当前文档已保存。'),
@@ -541,6 +588,7 @@
       tab_unavailable: tx('An Overleaf tab is unavailable for the safety check.', '某个 Overleaf 标签页当前无法完成安全检查。'),
       idle_probe_failed: tx('The Overleaf safety check failed. Reload the affected tab and retry.', 'Overleaf 安全检查失败；请刷新受影响的标签页后重试。'),
       native_project_locked: tx('Native Host still holds a project lock.', 'Native Host 仍持有项目锁。'),
+      native_process_stop_unconfirmed: tx('A previous Codex process has not yet confirmed its exit.', '前一次 Codex 进程尚未确认退出。'),
       native_run_active: tx('Native Host is still processing a task.', 'Native Host 仍在处理任务。'),
       busy: tx('A component is still busy.', '某个组件仍处于忙碌状态。')
     }[value] || tx('Waiting until every Overleaf tab is saved and idle.', '正在等待所有 Overleaf 标签页完成保存并进入空闲状态。');
@@ -555,6 +603,10 @@
   }
 
   function manualReasonText(state = {}) {
+    if (state.code === 'prerelease_promotion_requires_manual_update') {
+      return tx('The installed release candidate has the same version number as the stable release. Reinstall to use the stable release.',
+        '已安装的候选版与稳定版使用相同版本号。请重新安装以使用稳定版。');
+    }
     const reason = state.manualReason || {};
     return tx(reason.en || reason.zh || '', reason.zh || reason.en || '');
   }
@@ -564,5 +616,5 @@
     return /^zh\b/i.test(locale) ? chinese : english;
   }
 
-  return Object.freeze({ mount });
+  return Object.freeze({ mount, refreshLocale: render });
 });