codex-overleaf-link 2.1.5 → 2.2.0

package/extension/src/content/runQueueScheduler.js

@@ -0,0 +1,260 @@
+(function initCodexOverleafRunQueueScheduler(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('../shared/runInputQueue'));
+  } else {
+    root.CodexOverleafRunQueueScheduler = factory(root.CodexOverleafRunInputQueue);
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function runQueueSchedulerFactory(Queue) {
+  'use strict';
+
+  function create(options = {}) {
+    let scheduling = false;
+
+    function dequeue(queue, itemId, context = {}) {
+      const item = itemId ? queue.find(entry => entry.id === itemId) : null;
+      if (item) {
+        options.onDequeued?.(item, context);
+      }
+      return itemId ? Queue.remove(queue, itemId) : queue;
+    }
+
+    async function afterSettlement({ sessionId, status, queueItemId = '', continueQueue = false } = {}) {
+      let queue = options.getQueue?.(sessionId) || [];
+      if (status === 'completed') {
+        queue = dequeue(queue, queueItemId, { sessionId, reason: 'completed' });
+      } else if (continueQueue) {
+        queue = dequeue(queue, queueItemId, { sessionId, reason: 'continue_queue' });
+      } else if (queue.length) {
+        queue = Queue.pauseAll(queue, status || 'run_did_not_complete');
+      }
+      options.setQueue?.(sessionId, queue);
+      await options.persist?.();
+      options.onChange?.(sessionId);
+      if (status === 'completed' || continueQueue) {
+        scheduleOne(sessionId);
+      }
+    }
+
+    function scheduleOne(sessionId) {
+      if (scheduling || options.isRunning?.() || options.canStart?.(sessionId) === false) {
+        return false;
+      }
+      const claimed = Queue.claimNext(options.getQueue?.(sessionId) || [], {
+        randomUUID: options.randomUUID
+      });
+      if (!claimed.ok) {
+        return false;
+      }
+      scheduling = true;
+      options.setQueue?.(sessionId, claimed.queue);
+      Promise.resolve(options.persist?.())
+        .then(() => {
+          options.onChange?.(sessionId);
+          scheduling = false;
+          return options.start?.(claimed.item, sessionId);
+        })
+        .catch(error => {
+          scheduling = false;
+          const paused = Queue.pauseAll(options.getQueue?.(sessionId) || claimed.queue, error?.code || 'start_failed');
+          options.setQueue?.(sessionId, paused);
+          options.onChange?.(sessionId);
+          return options.persist?.();
+        });
+      return true;
+    }
+
+    async function markExecuting(sessionId, itemId, _runId) {
+      const queue = options.getQueue?.(sessionId) || [];
+      options.setQueue?.(
+        sessionId,
+        dequeue(queue, itemId, { sessionId, runId: _runId, reason: 'executing' })
+      );
+      await options.persist?.();
+      options.onChange?.(sessionId);
+    }
+
+    async function resume(sessionId) {
+      options.setQueue?.(sessionId, Queue.resumeAll(options.getQueue?.(sessionId) || []));
+      await options.persist?.();
+      options.onChange?.(sessionId);
+      scheduleOne(sessionId);
+    }
+
+    return { afterSettlement, markExecuting, resume, scheduleOne };
+  }
+
+  function createCoordinator(options = {}) {
+    let view = null;
+    const scheduler = create({
+      getQueue: sessionId => options.getSession?.(sessionId)?.pendingInputs || [],
+      setQueue: (sessionId, pendingInputs) => options.setQueue?.(sessionId, pendingInputs),
+      persist: () => options.save?.(),
+      isRunning: () => Boolean(options.getCurrentRun?.()),
+      canStart: sessionId => options.canStart?.(sessionId) !== false,
+      start: (item, sessionId) => startQueuedInput(item, sessionId),
+      onChange: () => render(),
+      onDequeued: (item, context) => options.removeGuidance?.(item.id, {
+        sessionId: context.sessionId,
+        recordId: item.sourceRunId || ''
+      }),
+      randomUUID: options.randomUUID
+    });
+
+    function queueComposerInput() {
+      options.readInputs?.();
+      const text = String(options.getTask?.() || '').trim();
+      if (!text) {
+        return;
+      }
+      if (options.hasAttachments?.()) {
+        options.toast?.(options.tr?.('queuedInputAttachmentsUnsupported'), 'warning');
+        return;
+      }
+      const session = options.getActiveSession?.();
+      const result = Queue.enqueue(session?.pendingInputs || [], {
+        text,
+        sourceRunId: options.getCurrentRun?.()?.recordId || '',
+        payload: options.capturePayload?.() || {}
+      }, {
+        randomUUID: options.randomUUID
+      });
+      if (!result.ok) {
+        options.toast?.(options.tr?.('queuedInputError_' + (result.error?.code || 'queue_full')), 'warning');
+        return;
+      }
+      options.setQueue?.(session.id, result.queue);
+      // A queued follow-up has not reached the active model turn yet. Keep it
+      // exclusively in the queue UI until the user explicitly guides the
+      // active turn, or until the scheduler promotes it to the next run.
+      options.clearTask?.();
+      render();
+      options.saveSoon?.();
+    }
+
+    async function guide(itemId) {
+      const session = options.getActiveSession?.();
+      const item = (session?.pendingInputs || []).find(entry => entry.id === itemId);
+      const run = options.getCurrentRun?.();
+      const binding = run?.activeTurn;
+      if (!session || !item || !run || run.sessionId !== session.id || !binding?.threadId || !binding?.turnId) {
+        options.toast?.(options.tr?.('queuedInputGuideUnavailable'), 'warning');
+        return;
+      }
+      options.setQueue?.(session.id, Queue.markSteering(session.pendingInputs, itemId));
+      render();
+      await options.save?.();
+      try {
+        const response = await options.sendSteer?.({
+          requestId: run.nativeRequestId,
+          projectKey: run.runProjectId,
+          threadId: binding.threadId,
+          expectedTurnId: binding.turnId,
+          clientUserMessageId: item.clientUserMessageId,
+          input: [{ type: 'text', text: item.text }]
+        });
+        const latest = options.getSession?.(session.id);
+        options.setQueue?.(
+          session.id,
+          response?.ok
+            ? Queue.remove(latest?.pendingInputs || [], itemId)
+            : Queue.returnToQueue(latest?.pendingInputs || [], itemId, response?.error?.code || 'steer_failed')
+        );
+        if (response?.ok) {
+          if (typeof options.appendGuidance === 'function') {
+            options.appendGuidance(item.text, {
+              guidanceId: item.id,
+              sessionId: session.id,
+              recordId: run.recordId,
+              status: 'completed'
+            });
+          } else {
+            options.appendEvent?.(options.tr?.('queuedInputGuided'), 'completed');
+          }
+        } else {
+          options.toast?.(response?.error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
+        }
+        render();
+        await options.save?.();
+      } catch (error) {
+        const latest = options.getSession?.(session.id);
+        const paused = (latest?.pendingInputs || []).map(entry => entry.id === itemId
+          ? { ...entry, status: 'paused', pauseReason: 'steer_delivery_unknown' }
+          : entry);
+        options.setQueue?.(session.id, Queue.normalizeQueue(paused));
+        options.toast?.(error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
+        render();
+        await options.save?.();
+      }
+    }
+
+    function remove(itemId) {
+      const session = options.getActiveSession?.();
+      if (!session) {
+        return;
+      }
+      const item = (session.pendingInputs || []).find(entry => entry.id === itemId);
+      if (item) {
+        options.removeGuidance?.(item.id, {
+          sessionId: session.id,
+          recordId: item.sourceRunId || ''
+        });
+      }
+      options.setQueue?.(session.id, Queue.remove(session.pendingInputs || [], itemId));
+      render();
+      options.saveSoon?.();
+    }
+
+    function resume() {
+      const session = options.getActiveSession?.();
+      if (session) {
+        scheduler.resume(session.id).catch(error => options.toast?.(error.message, 'warning'));
+      }
+    }
+
+    function render() {
+      const container = options.getContainer?.();
+      if (!container) {
+        return;
+      }
+      if (!view || view.container !== container) {
+        view = options.createView?.({
+          container,
+          tr: options.tr,
+          onGuide: itemId => guide(itemId).catch(error => options.toast?.(error.message, 'warning')),
+          onRemove: remove,
+          onResume: resume
+        });
+        if (view) {
+          view.container = container;
+        }
+      }
+      const session = options.getActiveSession?.();
+      const run = options.getCurrentRun?.();
+      view?.render?.(session?.pendingInputs || [], {
+        running: Boolean(run),
+        canGuide: Boolean(run?.activeTurn?.turnId)
+      });
+    }
+
+    async function startQueuedInput(item, sessionId) {
+      if (options.canStart?.(sessionId) === false || options.getCurrentRun?.()) {
+        const error = new Error('Queued input cannot start in the current session.');
+        error.code = 'queue_session_not_active';
+        throw error;
+      }
+      options.applyQueuedInput?.(item);
+      await options.run?.(item);
+    }
+
+    return {
+      guide,
+      queueComposerInput,
+      remove,
+      render,
+      resume,
+      scheduler
+    };
+  }
+
+  return { create, createCoordinator };
+});

package/extension/src/content/runTimelineView.js

@@ -1,6 +1,7 @@
 (function initCodexOverleafRunTimelineView() {
   'use strict';
 
+  const RunGuidanceView = window.CodexOverleafRunGuidanceView;
   // Run-timeline view — the timeline render pipeline carved out of
   // contentRuntime.js (v1.4.6 structural-debt phase 2): the scroll engine +
   // jump-to-latest button, the live-elapsed tick and collapsed-header summary,
@@ -43,7 +44,6 @@
     } = deps;
 
   let logAutoFollow = true;
-  let runSearchQuery = '';
   let userScrollIntentUntil = 0;
   // Scroll engine: a single rAF coalesces a burst of scroll requests into one
   // write per frame (streaming can fire ~25/sec); `scrollLogPendingForce`
@@ -308,86 +308,12 @@
       truncated.textContent = tr('runsTruncatedNote');
       log.append(truncated);
     }
-    // In-session search (v1.8.0): filter run cards by task or report text.
-    // Rendered with the same >= 3 threshold as the turn navigator; filtering
-    // is pure display (hidden attribute), state is kept across re-renders.
-    if (runs.length < 3 && runSearchQuery) {
-      // No search box is rendered below this threshold — a stale query from a
-      // bigger session would silently blank this log with no way to clear it.
-      runSearchQuery = '';
-    }
-    if (runs.length >= 3) {
-      const search = document.createElement('input');
-      search.type = 'search';
-      search.className = 'run-search';
-      search.setAttribute('data-run-search', '');
-      search.placeholder = tr('runSearchPlaceholder');
-      search.setAttribute('aria-label', tr('runSearchPlaceholder'));
-      search.value = runSearchQuery;
-      search.addEventListener('input', () => {
-        runSearchQuery = search.value;
-        applyRunSearchFilter(log);
-      });
-      log.append(search);
-    }
-    // Turn navigation (v1.7.5): once the log holds enough turns that
-    // scroll-hunting hurts, offer a jump-to-turn dropdown pinned above them.
-    if (runs.length >= 3) {
-      const nav = document.createElement('select');
-      nav.className = 'run-turn-nav';
-      nav.setAttribute('data-run-turn-nav', '');
-      nav.setAttribute('aria-label', tr('runTurnNavLabel'));
-      const placeholder = document.createElement('option');
-      placeholder.value = '';
-      placeholder.textContent = tr('runTurnNavLabel');
-      nav.append(placeholder);
-      runs.forEach((run, index) => {
-        const option = document.createElement('option');
-        option.value = run.id;
-        option.textContent = `#${index + 1} ${String(run.task || '').replace(/\s+/g, ' ').slice(0, 48)}`;
-        nav.append(option);
-      });
-      nav.addEventListener('change', () => {
-        if (!nav.value) {
-          return;
-        }
-        const card = log.querySelector(`[data-run-id="${cssEscape(nav.value)}"]`);
-        card?.scrollIntoView({ block: 'start' });
-        nav.value = '';
-      });
-      log.append(nav);
-    }
     for (const run of runs) {
       log.append(renderRunCard(run));
     }
-    if (runSearchQuery) {
-      applyRunSearchFilter(log);
-    }
     scrollLogToBottom({ force: true });
   }
 
-  // Case-insensitive substring match over the run's task text and its
-  // report/event narration. Empty query shows everything again.
-  function applyRunSearchFilter(log) {
-    const query = String(runSearchQuery || '').trim().toLowerCase();
-    const state = getState();
-    const matchingIds = new Set();
-    if (query) {
-      for (const run of state.runs || []) {
-        const haystack = [
-          run.task || '',
-          ...(run.events || []).map(event => `${event.title || ''} ${typeof event.detail === 'string' ? event.detail : ''}`)
-        ].join(' ').toLowerCase();
-        if (haystack.includes(query)) {
-          matchingIds.add(run.id);
-        }
-      }
-    }
-    for (const card of log.querySelectorAll('[data-run-id]')) {
-      card.hidden = Boolean(query) && !matchingIds.has(card.dataset.runId);
-    }
-  }
-
   function renderRunCard(run) {
     const root = document.createElement('section');
     root.className = 'transcript-turn run-card';
@@ -404,6 +330,7 @@
       <div class="transcript-turn-main">
         <div class="run-attachments codex-attachment-preview-list" data-run-attachments hidden></div>
         <div class="run-prompt" data-run-task></div>
+        <div class="run-guidance-list" data-run-guidance></div>
         <div class="run-turn-meta">
           <button type="button" data-run-accept hidden title="Accept this run's tracked changes in Overleaf">Accept changes</button>
           <button type="button" data-run-undo hidden title="Undo this run's writes to Overleaf">Undo</button>
@@ -413,19 +340,25 @@
             <span class="run-status" data-run-status></span>
             <span class="run-scan" aria-hidden="true"></span>
           </summary>
-          <div class="run-activity-list" data-run-events></div>
         </details>
+        <div class="run-activity-list" data-run-events></div>
         <div class="run-report" data-run-report aria-live="polite" hidden></div>
       </div>
     `;
 
     renderAttachmentPreviewList(run.attachments, root.querySelector('[data-run-attachments]'), { readonly: true });
-    root.querySelector('[data-run-task]').textContent = run.task || '';
+    const runTask = root.querySelector('[data-run-task]');
+    runTask.classList.add('run-user-message');
+    runTask.textContent = run.task || '';
     root.querySelector('[data-run-status]').textContent = getRunStatusText(run);
     const process = root.querySelector('[data-run-process]');
     process.open = run.status === 'running';
 
+    const guidance = root.querySelector('[data-run-guidance]');
     const events = root.querySelector('[data-run-events]');
+    const eventListId = `codex-run-events-${String(run.id || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '-')}`;
+    events.id = eventListId;
+    root.querySelector('[data-run-process-summary]')?.setAttribute('aria-controls', eventListId);
     const report = root.querySelector('[data-run-report]');
     if ((run.events || []).length >= 300) {
       const truncated = document.createElement('div');
@@ -433,12 +366,28 @@
       truncated.textContent = tr('eventsTruncatedNote');
       events.append(truncated);
     }
+    const guidanceTarget = run.status === 'running' ? events : guidance;
+    const renderedGuidanceIds = new Set();
+    const completedLegacyGuidance = new Set((run.events || [])
+      .filter(event => event.kind === 'guidance' && !event.guidanceId && event.status === 'completed')
+      .map(event => event.title));
     for (const event of run.events || []) {
       if (event.kind === 'report') {
         report.hidden = false;
         report.replaceChildren(renderCompletionReport(event, run));
       } else if (event.kind === 'technical') {
         continue;
+      } else if (RunGuidanceView.getGuidanceText(event)) {
+        if (event.guidanceId && renderedGuidanceIds.has(event.guidanceId)) {
+          continue;
+        }
+        if (!event.guidanceId && event.status === 'queued' && completedLegacyGuidance.has(event.title)) {
+          continue;
+        }
+        if (event.guidanceId) {
+          renderedGuidanceIds.add(event.guidanceId);
+        }
+        guidanceTarget.append(renderRunEvent(event));
       } else if (event.kind === 'stream') {
         upsertStreamEvent({ events }, event);
       } else {
@@ -465,7 +414,11 @@
   }
 
   function renderRunEvent(event) {
-    return renderActivityLine(sanitizeRunEventForRender(event));
+    const normalized = sanitizeRunEventForRender(event);
+    const guidanceText = RunGuidanceView.getGuidanceText(normalized);
+    return guidanceText
+      ? RunGuidanceView.renderGuidanceMessage(normalized, guidanceText, tx)
+      : renderActivityLine(normalized);
   }
 
   function upsertStreamEvent(view, event) {
@@ -481,7 +434,7 @@
       const text = existing.querySelector('[data-stream-text]');
       if (text) {
         if (event.streamRole === 'assistant') {
-          renderMarkdownBlockText(text, event.title || '');
+          renderMarkdownBlockText(text, event.title || '', { streaming: event.status === 'running' });
         } else {
           renderMarkdownInlineText(text, event.title || '');
         }
@@ -503,7 +456,7 @@
     text.className = 'run-stream-text';
     text.dataset.streamText = '';
     if (event.streamRole === 'assistant') {
-      renderMarkdownBlockText(text, event.title || '');
+      renderMarkdownBlockText(text, event.title || '', { streaming: event.status === 'running' });
     } else {
       renderMarkdownInlineText(text, event.title || '');
     }

package/extension/src/content/sessionManager.js

@@ -159,7 +159,7 @@
         return;
       }
       setState(deleteSession(getState(), sessionId));
-      await saveState();
+      await saveState({ deletedSessionIds: [sessionId] });
       applyStateToPanel();
       showPluginToast(tr('deleteSessionDeletedToast'), { status: 'info' });
       return;
@@ -186,7 +186,7 @@
     }
 
     setState(deleteSession(getState(), sessionId));
-    await saveState();
+    await saveState({ deletedSessionIds: [sessionId] });
     applyStateToPanel();
 
     try {

package/extension/src/content/sessionPersistence.js

@@ -0,0 +1,62 @@
+(function initCodexOverleafSessionPersistence() {
+  'use strict';
+
+  function migration() {
+    return window.CodexOverleafStorageMigration;
+  }
+
+  async function loadTombstones() {
+    return migration()?.loadSessionTombstones?.() || {};
+  }
+
+  async function getDeletedSessionIds(projectId) {
+    const Migration = migration();
+    return Migration?.getDeletedSessionIds?.(await loadTombstones(), projectId) || [];
+  }
+
+  async function addTombstones(projectId, sessionIds) {
+    return migration()?.addSessionTombstones?.(projectId, sessionIds) || loadTombstones();
+  }
+
+  function isVisibleRecord(record, deletedIds, accountScopeId) {
+    return Boolean(record)
+      && !(deletedIds || []).includes(record.id)
+      && (!accountScopeId || record.accountScopeId === accountScopeId);
+  }
+
+  async function writeSessions(options = {}) {
+    const { StorageDb, projectId } = options;
+    const Migration = options.Migration || migration();
+    const requested = (Array.isArray(options.deletedSessionIds) ? options.deletedSessionIds : [])
+      .filter(id => typeof id === 'string' && id);
+    const tombstones = requested.length && Migration?.addSessionTombstones
+      ? await Migration.addSessionTombstones(projectId, requested)
+      : await Migration?.loadSessionTombstones?.() || {};
+    const deleted = new Set(requested);
+    for (const id of Migration?.getDeletedSessionIds?.(tombstones, projectId) || []) deleted.add(id);
+    const sessionRecords = (options.sessionRecords || []).filter(record => !deleted.has(record.id));
+    const existingSessions = await StorageDb.getAllByIndex('sessions', 'projectId', projectId);
+    const deletedExisting = existingSessions.filter(record => deleted.has(record.id));
+    if (deletedExisting.length) {
+      await Promise.all(deletedExisting.map(record => StorageDb.deleteRecord('sessions', record.id)));
+    }
+    const existingById = new Map(existingSessions
+      .filter(record => !deleted.has(record.id))
+      .map(record => [record.id, record]));
+    const writable = sessionRecords.filter(record => {
+      const existing = existingById.get(record.id);
+      if (!existing) return true;
+      return (Date.parse(record.updatedAt || '') || 0) >= (Date.parse(existing.updatedAt || '') || 0);
+    });
+    if (writable.length) await StorageDb.putRecords('sessions', writable);
+    return writable;
+  }
+
+  window.CodexOverleafSessionPersistence = {
+    loadTombstones,
+    getDeletedSessionIds,
+    addTombstones,
+    isVisibleRecord,
+    writeSessions
+  };
+})();

package/extension/src/content/settingsPanel.js

@@ -154,7 +154,7 @@
             <div class="codex-set-card codex-provider-settings-entry">
               <div class="codex-provider-settings-entry-copy">
                 <p class="codex-set-row-help" data-i18n="providerSettingsHelp">Configure experimental third-party model APIs. Compatibility varies by provider and gateway.</p>
-                <p class="codex-provider-settings-summary" data-provider-settings-summary data-tone="ok" data-i18n="providerSettingsBuiltin">Built-in Codex is active</p>
+                <p class="codex-provider-settings-summary" data-provider-settings-summary data-tone="loading">${t(instance, 'providerSettingsLoading')}</p>
               </div>
               <button type="button" class="codex-set-btn" data-provider-settings-open data-i18n="providerSettingsConfigure">Configure</button>
             </div>

package/extension/src/content/updateNotice.js

@@ -9,7 +9,10 @@
   let getLocale = () => '';
   let settingsRoot = null;
   let settingsActionInFlight = false;
+  let restartWatchdog = null;
+  let manualCommandCopied = false;
   const ACTIVE_UPDATE_STATES = new Set(['downloading', 'staged', 'waiting_for_idle', 'applying', 'awaiting_health']);
+  const RESTART_WATCHDOG_MS = 30 * 1000;
 
   function mount(panelLike, options = {}) {
     if (typeof options.getLocale === 'function') {
@@ -60,6 +63,20 @@
   async function handleClick(event) {
     const action = event.target?.closest?.('[data-update-notice-action]')?.dataset?.updateNoticeAction;
     if (!action || actionInFlight) return;
+    if (action === 'copy-manual') {
+      try {
+        await navigator.clipboard.writeText(manualUpdateCommand(currentView?.state));
+        manualCommandCopied = true;
+        render();
+        setTimeout(() => {
+          manualCommandCopied = false;
+          render();
+        }, 1800);
+      } catch (_error) {
+        manualCommandCopied = false;
+      }
+      return;
+    }
     actionInFlight = true;
     render();
     try {
@@ -121,6 +138,7 @@
   }
 
   function buildRestartingView() {
+    scheduleRestartWatchdog();
     return {
       ...(currentView || {}),
       state: {
@@ -134,6 +152,43 @@
     };
   }
 
+  function scheduleRestartWatchdog() {
+    clearTimeout(restartWatchdog);
+    restartWatchdog = setTimeout(async () => {
+      try {
+        const view = await request('codex-overleaf/consent-update-get-state');
+        if (view?.state && !ACTIVE_UPDATE_STATES.has(view.state.state)) {
+          currentView = view;
+        } else {
+          currentView = buildFailedView('update_recovery_timeout', tx(
+            'The update did not finish restarting. Retry or use the manual recovery command.',
+            '更新重启未能完成。请重试或使用手动恢复命令。'
+          ));
+        }
+      } catch (_error) {
+        currentView = buildFailedView('update_recovery_timeout', tx(
+          'The update did not finish restarting. Retry or use the manual recovery command.',
+          '更新重启未能完成。请重试或使用手动恢复命令。'
+        ));
+      }
+      render();
+    }, RESTART_WATCHDOG_MS);
+  }
+
+  function buildFailedView(code, message) {
+    return {
+      ...(currentView || {}),
+      state: {
+        ...(currentView?.state || {}),
+        state: 'failed',
+        code,
+        message
+      },
+      progress: { value: 0, determinate: true, phase: 'failed' },
+      showPanel: true
+    };
+  }
+
   function bindSettingsControls(panel) {
     settingsRoot = panel;
     const button = panel.querySelector?.('[data-check-updates]');
@@ -184,6 +239,10 @@
 
     const focusedAction = document.activeElement?.dataset?.updateNoticeAction || '';
     const state = currentView.state || {};
+    if (state.state !== 'awaiting_health') {
+      clearTimeout(restartWatchdog);
+      restartWatchdog = null;
+    }
     const progress = currentView.progress || {};
     const copy = getCopy(state);
     notice.hidden = false;
@@ -201,6 +260,16 @@
     detail.textContent = copy.detail;
     body.append(eyebrow, title, detail);
 
+    if (state.state === 'failed') {
+      const recovery = document.createElement('span');
+      recovery.className = 'codex-update-notice-recovery';
+      recovery.textContent = tx('Manual recovery:', '手动恢复：');
+      const command = document.createElement('code');
+      command.className = 'codex-update-notice-command';
+      command.textContent = manualUpdateCommand(state);
+      body.append(recovery, command);
+    }
+
     if (!['update_available', 'failed', 'rolled_back'].includes(state.state)) {
       const bar = document.createElement('div');
       bar.className = 'codex-update-notice-progress' + (progress.determinate ? '' : ' is-indeterminate');
@@ -290,7 +359,10 @@
       return [{ id: 'later', label: tx('Later', '稍后'), primary: false }];
     }
     if (['failed', 'rolled_back'].includes(state)) {
-      return [{ id: 'retry', label: tx('Retry', '重试'), primary: true }];
+      return [
+        { id: 'copy-manual', label: manualCommandCopied ? tx('Copied', '已复制') : tx('Copy command', '复制命令'), primary: false },
+        { id: 'retry', label: tx('Retry', '重试'), primary: true }
+      ];
     }
     if (state === 'committed') {
       return [{ id: 'dismiss', label: tx('Done', '完成'), primary: true }];
@@ -350,6 +422,13 @@
     }[state.state] || { eyebrow: '', title: '', detail: '' };
   }
 
+  function manualUpdateCommand(state = {}) {
+    const version = /^\d+\.\d+\.\d+$/.test(String(state.latestVersion || ''))
+      ? state.latestVersion
+      : 'latest';
+    return `npm exec --yes codex-overleaf-link@${version} -- install-managed`;
+  }
+
   function blockerCopy(value) {
     return {
       unsaved: tx('Overleaf has not confirmed that this document is saved.', 'Overleaf 尚未确认当前文档已保存。'),