codex-overleaf-link 2.5.0 → 2.5.1

package/extension/src/content/runGuidanceController.js

@@ -2,40 +2,85 @@
   'use strict';
 
   function create(deps = {}) {
+    // Unacknowledged input is a page-local projection. Only confirmed delivery
+    // joins record.events; the durable queue owns refresh/recovery before that.
+    const pending = new Map();
+    let lastTimestamp = 0;
+    const keyOf = target => JSON.stringify([target.sessionId, target.recordId, target.guidanceId]);
+    const sameScope = scope => !scope || ['accountScopeId', 'projectId', 'generation'].every(key => scope[key] === deps.getScope?.()?.[key]);
+    function ownedRecord(target) {
+      if (!target.sessionId || !target.recordId) return null;
+      if (target.sessionCreatedAt !== undefined && deps.getSessionCreatedAt
+        && deps.getSessionCreatedAt(target.sessionId) !== target.sessionCreatedAt) return null;
+      return deps.findRunRecord?.(target.recordId, target.sessionId) || null;
+    }
+    function nextTimestamp() {
+      lastTimestamp = Math.max(Date.now(), lastTimestamp + 1);
+      return new Date(lastTimestamp).toISOString();
+    }
+    function getPending(run) {
+      return [...pending.values()].filter(token => token.target.recordId === run?.id
+        && (!deps.getActiveSessionId || token.target.sessionId === deps.getActiveSessionId())
+        && sameScope(token.scope) && ownedRecord(token.target)).map(token => token.event);
+    }
+    function refresh(target) {
+      const record = ownedRecord(target);
+      if (!record) return null;
+      const view = deps.getCurrentRunView?.();
+      const root = deps.getRunRoot?.(target) || (view?.recordId === target.recordId
+        && view?.sessionId === target.sessionId ? view.root : null);
+      const container = root?.querySelector('[data-run-guidance]');
+      deps.RunGuidanceView?.reconcileGuidance(container,
+        (record.events || []).concat(getPending(record)), deps.tx, { active: record.status === 'running' });
+      return container;
+    }
+    function refreshSettled(target) {
+      try { refresh(target); } catch (error) { deps.onPresentationError?.(error); }
+    }
+    function preview(text, target = {}) {
+      const title = String(text || '').trim();
+      if (!title || !target.guidanceId || !ownedRecord(target)) return null;
+      const token = { target: { ...target }, scope: deps.getScope?.(), event: { title, status: 'steering', kind: 'guidance',
+        guidanceId: target.guidanceId, timestamp: nextTimestamp(), guidancePending: true } };
+      pending.set(keyOf(target), token);
+      try {
+        const container = refresh(target);
+        const row = container?.querySelector?.(`[data-guidance-id="${deps.cssEscape?.(target.guidanceId) || target.guidanceId}"]`);
+        if (row) deps.revealGuidance?.(row);
+        deps.bumpUnreadIfDetached?.();
+      } catch (error) {
+        if (pending.get(keyOf(target)) === token) pending.delete(keyOf(target));
+        try { refresh(target); } catch { /* preserve the original presentation error */ }
+        throw error;
+      }
+      return token;
+    }
+    function clearPreview(token) {
+      if (!token || pending.get(keyOf(token.target)) !== token) return;
+      pending.delete(keyOf(token.target));
+      if (sameScope(token.scope)) refreshSettled(token.target);
+    }
     function upsert(text, target = {}) {
-      const record = deps.findRunRecord?.(target.recordId, target.sessionId);
+      const record = ownedRecord(target);
       const guidanceId = String(target.guidanceId || '').trim();
       if (!record || !guidanceId) return null;
-      const event = {
-        title: String(text || '').trim(),
-        status: target.status || 'queued',
-        kind: 'guidance',
-        guidanceId,
-        timestamp: new Date().toISOString()
-      };
-      const existing = (record.events || []).find(entry => entry.guidanceId === guidanceId);
-      if (!existing) {
-        deps.appendRunEvent?.(event, record);
-        return event;
-      }
-      Object.assign(existing, event, { timestamp: existing.timestamp || event.timestamp });
-      const view = deps.getCurrentRunView?.();
-      if (view?.recordId === target.recordId) {
-        view.root?.querySelector(`[data-guidance-id="${deps.cssEscape(guidanceId)}"]`)
-          ?.replaceWith(deps.renderRunEvent(existing));
-      }
-      return existing;
+      const existing = (record.events || []).find(entry => entry.kind === 'guidance' && entry.guidanceId === guidanceId);
+      const event = { title: String(text || '').trim(), status: target.status || 'completed', kind: 'guidance', guidanceId,
+        timestamp: existing?.timestamp || target.timestamp || pending.get(keyOf(target))?.event.timestamp || nextTimestamp() };
+      if (existing) Object.assign(existing, event);
+      else record.events = [...(record.events || []), event].slice(-(deps.maxRunEvents || 300));
+      // A late ACK still belongs to the captured run, even if another run is
+      // now active. The coordinator saves it together with queue removal.
+      deps.onRecordChanged?.(target);
+      refreshSettled(target);
+      return existing || event;
     }
-
     function remove(guidanceId, target = {}) {
-      const record = deps.findRunRecord?.(target.recordId, target.sessionId);
+      const record = ownedRecord(target);
       if (!record || !guidanceId) return false;
       const before = (record.events || []).length;
       record.events = (record.events || []).filter(event => event.guidanceId !== guidanceId);
-      const view = deps.getCurrentRunView?.();
-      if (view?.recordId === target.recordId) {
-        view.root?.querySelector(`[data-guidance-id="${deps.cssEscape(guidanceId)}"]`)?.remove();
-      }
+      refreshSettled(target);
       return record.events.length !== before;
     }
 
@@ -64,7 +109,7 @@
       return true;
     }
 
-    return { upsert, remove, settleView, appendToView };
+    return { preview, clearPreview, getPending, upsert, remove, settleView, appendToView };
   }
 
   window.CodexOverleafRunGuidanceController = { create };

package/extension/src/content/runGuidanceView.js

@@ -26,23 +26,72 @@
     const row = document.createElement('div');
     row.className = 'run-guidance-message run-user-message';
     row.dataset.kind = 'guidance';
-    row.dataset.status = event.status || 'completed';
-    if (event.guidanceId) {
-      row.dataset.guidanceId = event.guidanceId;
-    }
     row.setAttribute('role', 'group');
-    row.setAttribute('aria-label', tx('Follow-up guidance', '\u540e\u7eed\u5f15\u5bfc'));
-
     const text = document.createElement('div');
     text.className = 'run-guidance-text';
-    text.textContent = guidanceText;
-
-    row.append(text);
+    const label = document.createElement('div');
+    label.className = 'run-guidance-label';
+    row.append(text, label);
+    updateGuidanceMessage(row, event, guidanceText, tx);
     return row;
   }
 
+  function updateGuidanceMessage(row, event, guidanceText, tx, { active = true } = {}) {
+    row.dataset.status = event.status || 'completed';
+    if (event.guidanceId) row.dataset.guidanceId = event.guidanceId;
+    row.dataset.guidanceTimestamp = event.timestamp || '';
+    const label = tx('Follow-up guidance', '补充指令');
+    const sending = (active || event.guidancePending === true) && ['queued', 'steering'].includes(event.status);
+    const text = row.querySelector('.run-guidance-text');
+    if (text.textContent !== guidanceText) text.textContent = guidanceText;
+    const status = row.querySelector('.run-guidance-label');
+    const statusText = label + (sending ? tx(' · Sending…', ' · 发送中…') : '');
+    if (status.textContent !== statusText) status.textContent = statusText;
+    row.setAttribute('aria-label', statusText);
+  }
+
+  // Stored events and the controller's in-flight projection share a container.
+  // Confirmation updates the same row; removed previews leave no stale bubble.
+  function reconcileGuidance(container, events, tx, options = {}) {
+    if (!container) return;
+    const completedLegacy = new Set(events.filter(event => !event.guidanceId && event.status === 'completed')
+      .map(getGuidanceText).filter(Boolean));
+    const entries = new Map();
+    for (const [index, event] of events.entries()) {
+      const text = getGuidanceText(event);
+      if (!text || (!event.guidanceId && event.status === 'queued' && completedLegacy.has(text))) continue;
+      const key = event.guidanceId ? 'id:' + event.guidanceId : 'legacy:' + index;
+      const previous = entries.get(key);
+      if (previous && event.guidancePending === true && previous.event.guidancePending !== true) continue;
+      entries.set(key, { key, event: previous ? { ...event, timestamp: previous.event.timestamp || event.timestamp } : event, text });
+    }
+    const existing = new Map();
+    for (const row of [...container.children]) {
+      const key = row.dataset.guidanceId ? 'id:' + row.dataset.guidanceId : row.dataset.guidanceKey;
+      if (!key || existing.has(key)) { row.remove(); continue; }
+      existing.set(key, row);
+    }
+    for (const [key, row] of existing) if (!entries.has(key)) row.remove();
+    const known = [...entries.values()].filter(entry => Number.isFinite(Date.parse(entry.event.timestamp)))
+      .sort((a, b) => Date.parse(a.event.timestamp) - Date.parse(b.event.timestamp));
+    let datedIndex = 0;
+    // Keep legacy rows without timestamps in their event-order slots.
+    const ordered = [...entries.values()].map(entry => Number.isFinite(Date.parse(entry.event.timestamp)) ? known[datedIndex++] : entry);
+    let cursor = container.firstChild;
+    for (const entry of ordered) {
+      const row = existing.get(entry.key) || renderGuidanceMessage(entry.event, entry.text, tx);
+      row.dataset.guidanceKey = entry.key;
+      if (entry.event.guidancePending === true) row.dataset.guidancePending = 'true';
+      else delete row.dataset.guidancePending;
+      updateGuidanceMessage(row, entry.event, entry.text, tx, options);
+      if (row !== cursor) container.insertBefore(row, cursor);
+      cursor = row.nextSibling;
+    }
+  }
+
   window.CodexOverleafRunGuidanceView = {
     getGuidanceText,
-    renderGuidanceMessage
+    renderGuidanceMessage,
+    reconcileGuidance
   };
 })();

package/extension/src/content/runQueueScheduler.js

@@ -171,6 +171,25 @@
 
   function createCoordinator(options = {}) {
     let view = null;
+    const guidanceAttempts = new Map();
+    const guidanceKey = (sessionId, itemId) => JSON.stringify([sessionId, itemId]);
+    const matchesGuidanceItem = (item, identity) => item?.id === identity.itemId
+      && item.createdAt === identity.itemCreatedAt && item.text === identity.text
+      && item.clientUserMessageId === identity.clientUserMessageId;
+    const matchesGuidanceScope = expected => {
+      const scope = options.getGuideScope?.();
+      return !expected || ['projectId', 'accountScopeId', 'generation'].every(key => scope?.[key] === expected[key]);
+    };
+    const guideErrorKeys = {
+      codex_turn_not_ready: 'queuedInputGuideNotReady',
+      codex_turn_mismatch: 'queuedInputGuideTurnChanged',
+      codex_steer_empty: 'queuedInputGuideEmpty',
+      codex_steer_too_large: 'queuedInputGuideTooLarge'
+    };
+    function formatGuideError(error) {
+      const key = guideErrorKeys[error?.code];
+      return (key && options.tr?.(key)) || error?.message || options.tr?.('queuedInputGuideFailed');
+    }
     const scheduler = create({
       getQueue: sessionId => options.getSession?.(sessionId)?.pendingInputs || [],
       setQueue: (sessionId, pendingInputs) => options.setQueue?.(sessionId, pendingInputs),
@@ -226,62 +245,143 @@
       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) {
+      const initialScope = options.getGuideScope?.();
+      const guideScope = initialScope ? { ...initialScope } : null;
+      if (!session || !item || item.status !== 'queued' || !run || run.sessionId !== session.id || !binding?.threadId || !binding?.turnId) {
         options.toast?.(options.tr?.('queuedInputGuideUnavailable'), 'warning');
         return;
       }
+      const identity = { requestId: run.nativeRequestId, threadId: binding.threadId, turnId: binding.turnId,
+        projectKey: run.runProjectId, recordId: run.recordId, sessionId: session.id, sessionCreatedAt: session.createdAt,
+        itemId, itemCreatedAt: item.createdAt, text: item.text, clientUserMessageId: item.clientUserMessageId };
+      const attemptKey = guidanceKey(identity.sessionId, itemId);
+      const attempt = { identity, scope: guideScope, previewToken: null };
+      const sameScope = () => matchesGuidanceScope(guideScope);
+      const ownedSession = () => {
+        const latest = options.getSession?.(identity.sessionId);
+        return sameScope() && latest?.createdAt === identity.sessionCreatedAt ? latest : null;
+      };
+      const ownedItemSession = (allowPaused = false) => {
+        const latest = ownedSession();
+        const current = latest?.pendingInputs?.find(entry => entry.id === itemId);
+        return guidanceAttempts.get(attemptKey) === attempt
+          && (current?.status === 'steering' || (allowPaused && current?.status === 'paused'))
+          && matchesGuidanceItem(current, identity) ? latest : null;
+      };
+      function clearPreview() {
+        const token = attempt.previewToken;
+        attempt.previewToken = null;
+        if (token) options.clearGuidancePreview?.(token);
+      }
+      const assertCurrent = () => {
+        const currentRun = options.getCurrentRun?.();
+        if (options.isGuideCancelled?.() || currentRun !== run || options.getActiveSession?.()?.id !== identity.sessionId
+          || currentRun?.nativeRequestId !== identity.requestId
+          || currentRun?.recordId !== identity.recordId || currentRun?.runProjectId !== identity.projectKey
+          || currentRun?.activeTurn?.threadId !== identity.threadId || currentRun?.activeTurn?.turnId !== identity.turnId
+          || !ownedItemSession()) {
+          throw Object.assign(new Error(options.tr?.('queuedInputGuideUnavailable') || 'Guidance is no longer available for this turn.'), { code: 'codex_turn_mismatch' });
+        }
+      };
+      async function restoreUnsent(error) {
+        // No steer was dispatched. Restore only this attempt's still-owned item;
+        // a concurrent removal, replacement or scope switch must stay untouched.
+        clearPreview();
+        const latest = ownedItemSession();
+        if (latest) {
+          options.setQueue?.(identity.sessionId, Queue.returnToQueue(latest.pendingInputs, itemId));
+          render();
+          try {
+            await options.save?.({ queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId } });
+          } catch (recoveryError) {
+            if (error && typeof error === 'object') error.persistenceRecoveryError = recoveryError?.message || String(recoveryError);
+          }
+        }
+      }
       options.setQueue?.(session.id, Queue.markSteering(session.pendingInputs, itemId));
-      render();
-      await options.save?.({
-        queueMutation: { type: 'transition', sessionId: session.id, itemId }
-      });
+      guidanceAttempts.set(attemptKey, attempt);
       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')
+        try {
+          attempt.previewToken = options.previewGuidance?.(identity.text, {
+            guidanceId: itemId, sessionId: identity.sessionId, recordId: identity.recordId,
+            sessionCreatedAt: identity.sessionCreatedAt
+          });
+          render();
+          const preflight = await options.preflightGuide?.({ task: identity.text, assertCurrent });
+          assertCurrent();
+          if (preflight?.blocked) throw Object.assign(new Error('Guidance was blocked before dispatch.'), { guidanceBlocked: true });
+          await options.save?.({
+            queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId }
+          });
+          assertCurrent();
+        } catch (error) {
+          await restoreUnsent(error);
+          if (error?.guidanceBlocked) return { ok: false, blocked: true };
+          throw error;
+        }
+        let response;
+        try {
+          response = await options.sendSteer?.({
+            requestId: identity.requestId,
+            projectKey: identity.projectKey,
+            threadId: identity.threadId,
+            expectedTurnId: identity.turnId,
+            clientUserMessageId: identity.clientUserMessageId,
+            input: [{ type: 'text', text: identity.text }]
+          }, { assertCurrent });
+        } catch (error) {
+          if (error?.requestDispatched === false) { await restoreUnsent(error); throw error; }
+          clearPreview();
+          const latest = ownedItemSession(true);
+          if (latest) {
+            const paused = latest.pendingInputs.map(entry => entry.id === itemId
+              ? { ...entry, status: 'paused', pauseReason: 'steer_delivery_unknown' }
+              : entry);
+            options.setQueue?.(identity.sessionId, Queue.normalizeQueue(paused));
+          }
+          options.toast?.(formatGuideError(error), 'warning');
+          render();
+          if (latest) await options.save?.({
+            queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId }
+          });
+          return;
+        }
+        // Cancellation can pause the owned row while a dispatched steer is
+        // awaiting acknowledgement. A confirmed receipt also consumes that
+        // paused copy, so Resume cannot send an already accepted input again.
+        const latest = ownedItemSession(Boolean(response?.ok));
+        if (latest) options.setQueue?.(
+          identity.sessionId,
+          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'
+          if (ownedSession() && typeof options.appendGuidance === 'function') {
+            options.appendGuidance(identity.text, {
+              guidanceId: itemId, sessionId: identity.sessionId, recordId: identity.recordId,
+              sessionCreatedAt: identity.sessionCreatedAt, status: 'completed',
+              timestamp: attempt.previewToken?.event?.timestamp
             });
-          } else {
+          } else if (ownedSession() && options.getCurrentRun?.() === run) {
             options.appendEvent?.(options.tr?.('queuedInputGuided'), 'completed');
           }
         } else {
-          options.toast?.(response?.error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
+          options.toast?.(formatGuideError(response?.error), 'warning');
         }
+        clearPreview();
         render();
-        await options.save?.({
+        // A Native acknowledgement is final delivery evidence. A later local
+        // save failure must not turn it into an unknown delivery or resend it.
+        if (latest) await options.save?.({
           queueMutation: response?.ok
-            ? { type: 'remove', sessionId: session.id, itemId }
-            : { type: 'transition', sessionId: session.id, itemId }
+            ? { type: 'remove', sessionId: identity.sessionId, itemId }
+            : { type: 'transition', sessionId: identity.sessionId, itemId }
         });
-      } 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');
+        else if (response?.ok && ownedSession()) await options.save?.();
+      } finally {
+        clearPreview();
+        if (guidanceAttempts.get(attemptKey) === attempt) guidanceAttempts.delete(attemptKey);
         render();
-        await options.save?.({
-          queueMutation: { type: 'transition', sessionId: session.id, itemId }
-        });
       }
     }
 
@@ -320,7 +420,7 @@
         view = options.createView?.({
           container,
           tr: options.tr,
-          onGuide: itemId => guide(itemId).catch(error => options.toast?.(error.message, 'warning')),
+          onGuide: itemId => guide(itemId).catch(error => options.toast?.(formatGuideError(error), 'warning')),
           onRemove: remove,
           onResume: resume,
           onToast: message => options.toast?.(message, 'warning')
@@ -331,7 +431,13 @@
       }
       const session = options.getActiveSession?.();
       const run = options.getCurrentRun?.();
-      view?.render?.(session?.pendingInputs || [], {
+      const visibleQueue = (session?.pendingInputs || []).filter(item => {
+        const attempt = guidanceAttempts.get(guidanceKey(session.id, item.id));
+        return !attempt?.previewToken || !['steering', 'paused'].includes(item.status)
+          || !matchesGuidanceScope(attempt.scope)
+          || session.createdAt !== attempt.identity.sessionCreatedAt || !matchesGuidanceItem(item, attempt.identity);
+      });
+      view?.render?.(visibleQueue, {
         running: Boolean(run),
         canGuide: Boolean(run?.activeTurn?.turnId)
       });

package/extension/src/content/runRecoveryActions.js

@@ -0,0 +1,146 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('RunRecoveryActions', [], factory);
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  function formatForceCancelOutcome(response, tx) {
+    if (response?.ok !== true) return tx('Release failed — refresh the tab, then try again.', '释放失败，请刷新页面后重试。');
+    const result = response.result || response;
+    if (result.lockReleased === true) return tx('Force-released — you can retry the run.', '已释放，可以重试本轮任务。');
+    if (result.cancelled === true) return tx('Cancellation requested. Wait for the task to stop before retrying.', '已请求取消，请等待任务停止后再重试。');
+    if (result.cancelled === false) return tx('No active task matched the release request.', '没有发现与释放请求匹配的活动任务。');
+    if (result.sent === true) return tx('Cancellation request sent; release is not yet confirmed.', '取消请求已发送，释放状态尚未确认。');
+    return tx('Release is not yet confirmed. Check the current task before retrying.', '释放状态尚未确认，请检查当前任务后再重试。');
+  }
+
+  function create(deps = {}) {
+    const { tx, failureNotice, refillComposerForRetry, openProjectFileForFailure, showNativeSetupGuidance,
+      openStorageSettings, forceCancelStuckTaskForCurrentProject } = deps;
+    const document = deps.document || globalThis.document;
+    const window = deps.window || globalThis.window;
+
+  const RETRYABLE_FAILURE_CODES = new Set([
+    'native_request_failed', 'codex_timeout', 'codex_no_usable_result',
+    'codex_output_limit', 'stale_source_changed', 'patch_anchor_not_found',
+    'target_editor_not_ready', 'write_timeout', 'partial_write_needs_review',
+    'write_operation_failed'
+  ]);
+  const NATIVE_SETUP_FAILURE_CODES = new Set([
+    'native_bridge_unavailable', 'native_protocol_incompatible'
+  ]);
+  const OPEN_FILE_FAILURE_CODES = new Set([
+    'target_file_not_active', 'target_file_open_failed', 'target_file_not_found'
+  ]);
+  const STORAGE_FAILURE_CODES = new Set([
+    'storage_quota_exceeded', 'run_state_persist_failed'
+  ]);
+  // A missing `codex` binary is fixed in the terminal, not the panel — the
+  // action opens the README troubleshooting section (PATH / login checks).
+  const CODEX_INSTALL_FAILURE_CODES = new Set(['codex_not_found']);
+  const CODEX_CLI_TROUBLESHOOTING_URL = 'https://github.com/Ghqqqq/codex-overleaf-link#faq-and-troubleshooting';
+
+  function buildRecoveryButton(failureCode, label, title) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'run-final-answer__recovery-action';
+    button.dataset.recoveryFor = failureCode;
+    button.textContent = label;
+    if (title) {
+      button.title = title;
+    }
+    return button;
+  }
+
+  function appendEditAndResend(report, run, actionKey) {
+    const retry = buildRecoveryButton(actionKey,
+      tx('Edit & resend', '编辑后重发'),
+      tx('Put this run\u2019s task back into the composer so you can adjust and resend it.', '把本轮任务填回输入框，修改后可直接重发。'));
+    retry.addEventListener('click', clickEvent => {
+      clickEvent.stopPropagation();
+      refillComposerForRetry(run || null);
+    });
+    report.append(retry);
+  }
+
+  function appendRecoveryActionForFailure(report, event, run) {
+    const recovery = failureNotice?.prepareRecovery(report, { openFile: openProjectFileForFailure });
+    const failure = recovery?.failure || event?.failure;
+    const failureCode = failure?.code || '';
+    if (recovery?.handled) return;
+    report = recovery?.target || report;
+    if (RETRYABLE_FAILURE_CODES.has(failureCode) && typeof refillComposerForRetry === 'function') {
+      appendEditAndResend(report, run, failureCode);
+      return;
+    }
+    if (NATIVE_SETUP_FAILURE_CODES.has(failureCode) && typeof showNativeSetupGuidance === 'function') {
+      const fix = buildRecoveryButton(failureCode,
+        tx('Fix the native host', '修复 native host'),
+        tx('Opens the install/update guidance with the copyable command.', '打开安装/更新指引（含可复制命令）。'));
+      fix.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        showNativeSetupGuidance();
+      });
+      report.append(fix);
+      return;
+    }
+    if (OPEN_FILE_FAILURE_CODES.has(failureCode) && failure?.file && typeof openProjectFileForFailure === 'function') {
+      const open = buildRecoveryButton(failureCode,
+        tx(`Open ${failure.file} in Overleaf`, `在 Overleaf 打开 ${failure.file}`), '');
+      open.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        openProjectFileForFailure(failure.file);
+      });
+      report.append(open);
+      return;
+    }
+    if (STORAGE_FAILURE_CODES.has(failureCode) && typeof openStorageSettings === 'function') {
+      const clean = buildRecoveryButton(failureCode,
+        tx('Open history & storage cleanup', '打开历史与存储清理'), '');
+      clean.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        openStorageSettings();
+      });
+      report.append(clean);
+      return;
+    }
+    if (CODEX_INSTALL_FAILURE_CODES.has(failureCode)) {
+      const guide = buildRecoveryButton(failureCode,
+        tx('Codex CLI troubleshooting guide', '查看 Codex CLI 排查指引'),
+        tx('Opens the README section on fixing a missing `codex` command (PATH / login).', '打开 README 中「找不到 codex 命令」的排查说明（PATH／登录）。'));
+      guide.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        window.open(CODEX_CLI_TROUBLESHOOTING_URL, '_blank', 'noopener');
+      });
+      report.append(guide);
+      return;
+    }
+    if (failureCode !== 'codex_project_locked') return;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'run-final-answer__recovery-action';
+    button.dataset.recoveryFor = failureCode;
+    button.textContent = tx('Force-release the stuck task', '强制释放卡住的任务');
+    button.title = tx(
+      'Requests cancellation for this project. A sent request does not confirm that the task has stopped. Use this when refreshing the tab did not free the project.',
+      '请求取消当前项目的任务；请求已发送不代表任务已经停止。刷新页面仍未解除占用时使用。'
+    );
+    button.addEventListener('click', event => {
+      event.stopPropagation();
+      button.disabled = true;
+      button.textContent = tx('Releasing…', '正在释放…');
+      forceCancelStuckTaskForCurrentProject().then(result => {
+        button.textContent = formatForceCancelOutcome(result, tx);
+        button.disabled = result?.ok === true;
+      }).catch(() => {
+        button.disabled = false;
+        button.textContent = tx('Release failed — refresh the tab, then try again.', '释放失败，请刷新页面后重试。');
+      });
+    });
+    report.append(button);
+  }
+
+    return { buildRecoveryButton, appendRecoveryActionForFailure };
+  }
+  return { create, formatForceCancelOutcome };
+});