codex-overleaf-link 2.1.4 → 2.2.0

package/extension/src/content/projectSessionCleanup.js

@@ -0,0 +1,104 @@
+(function initCodexOverleafProjectSessionCleanup() {
+  'use strict';
+
+  const FRESH_RUNNING_WINDOW_MS = 30 * 60 * 1000;
+
+  function create(deps = {}) {
+    const {
+      tr,
+      getAccountScopeId,
+      showPluginConfirm,
+      showPluginToast,
+      sendBackgroundNative,
+      mutateProjectPanelState,
+      renderRecentProjectsVariant
+    } = deps;
+
+    function isFreshRunningRecord(StorageDb, record) {
+      if (StorageDb.derivePrimaryStatusBadge(record) !== 'running') {
+        return false;
+      }
+      const touched = Date.parse(record.updatedAt || record.lastActivityAt || record.createdAt || '');
+      return !Number.isFinite(touched) || (Date.now() - touched) <= FRESH_RUNNING_WINDOW_MS;
+    }
+
+    async function clearProjectSessions(projectId, projectName) {
+      const StorageDb = window.CodexOverleafStorageDb;
+      const SessionState = window.CodexOverleafSessionState;
+      if (!StorageDb || !SessionState) {
+        return;
+      }
+      const scope = getAccountScopeId();
+      const records = (await StorageDb.getAllByIndex('sessions', 'projectId', projectId))
+        .filter(record => record && (!scope || record.accountScopeId === scope));
+      if (!records.length) {
+        await renderRecentProjectsVariant();
+        return;
+      }
+      if (records.some(record => isFreshRunningRecord(StorageDb, record))) {
+        showPluginToast(tr('recentProjects_clearProject_running'), { status: 'warning', sticky: true });
+        return;
+      }
+      const approved = await showPluginConfirm({
+        title: tr('recentProjects_clearProject_title', { project: projectName }),
+        message: tr('recentProjects_clearProject_message', { count: String(records.length), project: projectName }),
+        confirmLabel: tr('recentProjects_clearProject_confirm'),
+        cancelLabel: tr('confirmDefaultCancel'),
+        destructive: true
+      });
+      if (!approved) {
+        return;
+      }
+      const Migration = window.CodexOverleafStorageMigration;
+      if (Migration?.addSessionTombstones) {
+        await Migration.addSessionTombstones(projectId, records.map(record => record.id));
+      }
+      try {
+        await mutateProjectPanelState(projectId, state => records.reduce(
+          (nextState, record) => SessionState.deleteSession(nextState, record.id),
+          state
+        ));
+      } catch (_error) { /* IndexedDB deletion remains authoritative for the dashboard. */ }
+
+      let removed = 0;
+      let historyFailures = 0;
+      for (const record of records) {
+        try {
+          await StorageDb.deleteRecord('sessions', record.id);
+          removed++;
+        } catch (_error) { /* The remaining record stays visible and can be retried. */ }
+        try {
+          const response = await sendBackgroundNative({
+            method: 'codex.history.clearPlugin',
+            params: { sessionId: record.id, threadId: record.codexThreadId || '' }
+          });
+          if (!response || !response.ok) {
+            historyFailures++;
+          }
+        } catch (_error) {
+          historyFailures++;
+        }
+      }
+      if (removed < records.length) {
+        showPluginToast(tr('recentProjects_clearProject_partial', {
+          removed: String(removed),
+          count: String(records.length)
+        }), { status: 'warning', sticky: true });
+      } else if (historyFailures) {
+        showPluginToast(tr('recentProjects_clearProject_historyPartial', {
+          count: String(historyFailures)
+        }), { status: 'warning', sticky: true });
+      } else {
+        showPluginToast(tr('recentProjects_clearProject_done', {
+          count: String(removed),
+          project: projectName
+        }), { status: 'completed' });
+      }
+      await renderRecentProjectsVariant();
+    }
+
+    return { clearProjectSessions };
+  }
+
+  window.CodexOverleafProjectSessionCleanup = { create };
+})();

package/extension/src/content/providerSettingsCoordinator.js

@@ -10,6 +10,7 @@
       getSelectedModel: options.getSelectedModel || (() => ''),
       getSelectedProviderId: options.getSelectedProviderId || (() => 'builtin'),
       setSelectedProviderId: options.setSelectedProviderId || (() => {}),
+      confirmProviderSwitch: options.confirmProviderSwitch || (() => true),
       clearSelectedModel: options.clearSelectedModel || (() => {}),
       refreshModelOptions: options.refreshModelOptions || (() => {}),
       persistInputs: options.persistInputs || (() => {}),
@@ -38,7 +39,7 @@
     setupCrossTabRefresh(instance, options.window || window);
     return {
       open: () => open(instance),
-      refreshSummary: () => refresh(instance),
+      refreshSummary: () => refreshSummary(instance),
       ensureLoaded: () => ensureLoaded(instance),
       getRunSelection: providerId => instance.loaded
         ? Profiles.buildRunSelection(instance.catalog, providerId || instance.getSelectedProviderId())
@@ -93,9 +94,45 @@
     return instance.catalog;
   }
 
+  async function ensureLoadedWithRetry(instance) {
+    try {
+      return await ensureLoaded(instance);
+    } catch (_firstError) {
+      // Extension reloads can race the first Native Messaging connection.
+      // Keep the persisted project selection visible, then retry once after
+      // the service worker and Native Host have had a chance to reconnect.
+      updateSettingsSummary(instance);
+      await new Promise(resolve => setTimeout(resolve, 800));
+      try {
+        const result = await refresh(instance);
+        return result?.catalog || instance.catalog;
+      } catch (error) {
+        updateSettingsSummary(instance);
+        throw error;
+      }
+    }
+  }
+
+  async function refreshSummary(instance) {
+    // Project state hydrates before the Native Host catalog is guaranteed to
+    // be ready. Project the persisted selection immediately so Settings never
+    // claims Built-in Codex (or stays on a loading placeholder) while the
+    // authoritative catalog request is still pending.
+    updateSettingsSummary(instance);
+    try {
+      await ensureLoadedWithRetry(instance);
+    } catch (_error) {
+      // This card describes the project's saved selection. Native connection
+      // failures are surfaced when Configure is opened, without replacing the
+      // selection with a misleading Built-in/unavailable state.
+    }
+    updateSettingsSummary(instance);
+    return instance.catalog;
+  }
+
   async function syncSessionProvider(instance) {
     try {
-      await ensureLoaded(instance);
+      await ensureLoadedWithRetry(instance);
     } catch (_error) {
       return instance.refreshModelOptions(
         window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, instance.getSelectedProviderId())
@@ -109,22 +146,78 @@
     const requestedProviderId = typeof change.sessionProviderId === 'string' && change.sessionProviderId
       ? change.sessionProviderId
       : previousProviderId;
-    const sessionProviderChanged = requestedProviderId !== previousProviderId;
-    if (sessionProviderChanged) {
+    const projectProviderChanged = requestedProviderId !== previousProviderId;
+    if (projectProviderChanged && change.providerSwitchApproved !== true) {
       const requestedProvider = window.CodexOverleafProviderProfiles.getProviderById(catalog, requestedProviderId);
-      const preferredModelId = requestedProvider?.kind === 'custom'
-        ? requestedProvider.defaultModelId || requestedProvider.models?.[0]?.id || ''
-        : '';
-      instance.setSelectedProviderId(requestedProviderId, preferredModelId);
+      const approved = await instance.confirmProviderSwitch({
+        providerId: requestedProviderId,
+        providerName: requestedProvider?.name || requestedProviderId
+      });
+      if (!approved) {
+        return { cancelled: true };
+      }
     }
     const changedProviderIds = Array.isArray(change.changedProviderIds) ? change.changedProviderIds : [];
-    if (!change.forceSessionRefresh && !sessionProviderChanged && !changedProviderIds.includes(requestedProviderId)) {
+    if (!change.forceSessionRefresh && !projectProviderChanged && !changedProviderIds.includes(requestedProviderId)) {
       return;
     }
-    await instance.refreshModelOptions(
-      window.CodexOverleafProviderProfiles.buildRunSelection(catalog, requestedProviderId)
-    );
+    const loadResult = change.modelsPreloaded === true
+      ? { stale: false, selectedModel: change.preloadedModelId || '' }
+      : await instance.refreshModelOptions(
+        window.CodexOverleafProviderProfiles.buildRunSelection(catalog, requestedProviderId),
+        { persist: false }
+      );
+    if (loadResult?.stale || loadResult?.error) {
+      const error = createClientError(
+        loadResult?.error?.code || 'provider_model_catalog_unavailable',
+        loadResult?.error?.message || 'The provider model catalog could not be loaded.'
+      );
+      error.details = loadResult?.error || {};
+      throw error;
+    }
+    if (projectProviderChanged) {
+      await instance.setSelectedProviderId(requestedProviderId, loadResult?.selectedModel || '');
+    }
     await instance.persistInputs();
+    updateSettingsSummary(instance);
+    return { providerId: requestedProviderId, selectedModel: loadResult?.selectedModel || '' };
+  }
+
+  async function prepareProviderActivation(instance, providerId) {
+    const previousProviderId = instance.getSelectedProviderId() || 'builtin';
+    const provider = window.CodexOverleafProviderProfiles.getProviderById(instance.catalog, providerId);
+    if (providerId !== previousProviderId) {
+      const approved = await instance.confirmProviderSwitch({
+        providerId,
+        providerName: provider?.name || providerId
+      });
+      if (!approved) {
+        return { cancelled: true, previousProviderId };
+      }
+    }
+    const result = await instance.refreshModelOptions(
+      window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, providerId),
+      { persist: false }
+    );
+    if (result?.stale || result?.error) {
+      if (providerId !== previousProviderId) {
+        await instance.refreshModelOptions(
+          window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, previousProviderId),
+          { persist: false }
+        ).catch(() => {});
+      }
+      const error = createClientError(
+        result?.error?.code || 'provider_model_catalog_unavailable',
+        result?.error?.message || 'The provider model catalog could not be loaded.'
+      );
+      error.details = result?.error || {};
+      throw error;
+    }
+    return {
+      cancelled: false,
+      previousProviderId,
+      selectedModel: result?.selectedModel || ''
+    };
   }
 
   async function testProvider(instance, context) {
@@ -264,8 +357,13 @@
   }
 
   async function activateProvider(instance, context) {
-    instance.dialog.setBusy('saving', instance.tx('Activating provider…', '正在启用模型服务…'));
+    let preparation;
     try {
+      preparation = await prepareProviderActivation(instance, context.profileId);
+      if (preparation.cancelled) {
+        return;
+      }
+      instance.dialog.setBusy('saving', instance.tx('Activating provider…', '正在启用模型服务…'));
       const result = await request(instance, 'codex.providers.activate', {
         providerId: context.profileId,
         expectedRevision: context.expectedRevision,
@@ -276,30 +374,59 @@
         updateDialog: true,
         selectedId: context.profileId
       });
-      await notifyChanged(instance, applied.change, { sessionProviderId: context.profileId });
+      await notifyChanged(instance, applied.change, {
+        sessionProviderId: context.profileId,
+        providerSwitchApproved: true,
+        modelsPreloaded: true,
+        preloadedModelId: preparation.selectedModel,
+        requireProjection: true
+      });
       instance.dialog.setBusy('', '');
       instance.dialog.setStatus({
         tone: 'success',
         title: instance.tx('Provider activated.', '模型服务已启用。')
       });
     } catch (error) {
+      if (preparation?.previousProviderId && preparation.previousProviderId !== context.profileId) {
+        await instance.refreshModelOptions(
+          window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, preparation.previousProviderId),
+          { persist: false }
+        ).catch(() => {});
+      }
       instance.dialog.setBusy('failed', formatError(instance, error));
       instance.dialog.setStatus({ tone: 'failed', title: formatError(instance, error) });
     }
   }
 
   async function activateBuiltin(instance) {
-    instance.dialog.setBusy('saving', instance.tx('Activating built-in Codex…', '正在启用内置 Codex…'));
+    let preparation;
     try {
+      preparation = await prepareProviderActivation(instance, 'builtin');
+      if (preparation.cancelled) {
+        return;
+      }
+      instance.dialog.setBusy('saving', instance.tx('Activating built-in Codex…', '正在启用内置 Codex…'));
       const result = await request(instance, 'codex.providers.activate', {
         providerId: 'builtin',
         expectedRevision: 0
       });
       const applied = applyCatalog(instance, result, { updateDialog: true, selectedId: 'builtin' });
-      await notifyChanged(instance, applied.change, { sessionProviderId: 'builtin' });
+      await notifyChanged(instance, applied.change, {
+        sessionProviderId: 'builtin',
+        providerSwitchApproved: true,
+        modelsPreloaded: true,
+        preloadedModelId: preparation.selectedModel,
+        requireProjection: true
+      });
       instance.dialog.setBusy('', '');
       instance.dialog.setStatus({ tone: 'success', title: instance.tx('Built-in Codex is active.', '已启用内置 Codex。') });
     } catch (error) {
+      if (preparation?.previousProviderId && preparation.previousProviderId !== 'builtin') {
+        await instance.refreshModelOptions(
+          window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, preparation.previousProviderId),
+          { persist: false }
+        ).catch(() => {});
+      }
       instance.dialog.setBusy('failed', formatError(instance, error));
     }
   }
@@ -340,13 +467,31 @@
   }
 
   function updateSettingsSummary(instance, override = {}) {
-    const active = window.CodexOverleafProviderProfiles.getActiveProvider(instance.catalog);
-    const summary = override.summary || (active.kind === 'builtin'
-      ? instance.tx('Built-in Codex · default for new sessions', '内置 Codex · 新会话默认')
-      : `${active.name} · ${active.defaultModelId || instance.tx('No model', '未配置模型')} · ${instance.tx('Default for new sessions', '新会话默认')}`);
+    const selectedProviderId = instance.getSelectedProviderId() || 'builtin';
+    const catalogProvider = window.CodexOverleafProviderProfiles.getProviderById(
+      instance.catalog,
+      selectedProviderId
+    );
+    const selectedProvider = catalogProvider?.id === selectedProviderId
+      ? catalogProvider
+      : (selectedProviderId === 'builtin'
+        ? window.CodexOverleafProviderProfiles.getActiveProvider(instance.catalog)
+        : {
+          id: selectedProviderId,
+          name: selectedProviderId,
+          kind: 'custom',
+          defaultModelId: instance.getSelectedModel() || '',
+          wireApiPreference: '',
+          resolvedWireApi: ''
+        });
+    const summary = override.summary || (selectedProvider.kind === 'builtin'
+      ? instance.tx('Built-in Codex · current project', '内置 Codex · 当前项目')
+      : `${selectedProvider.name} · ${instance.getSelectedModel() || selectedProvider.defaultModelId || instance.tx('No model', '未配置模型')} · ${instance.tx('Current project', '当前项目')}`);
     instance.getSettingsPanelInstance()?.setProviderSummary?.({
       summary,
-      tone: override.tone || (active.kind === 'custom' && active.wireApiPreference === 'auto' && !active.resolvedWireApi ? 'warning' : 'ok')
+      tone: override.tone || (selectedProvider.kind === 'custom'
+        && selectedProvider.wireApiPreference === 'auto'
+        && !selectedProvider.resolvedWireApi ? 'warning' : 'ok')
     });
   }
 
@@ -358,7 +503,10 @@
     }
     try {
       await instance.onProviderChanged(instance.catalog, { ...change, ...localChange });
-    } catch (_error) {
+    } catch (error) {
+      if (localChange.requireProjection === true) {
+        throw error;
+      }
       // The authoritative catalog is already saved. A later refresh can retry
       // the local model projection without rolling back the provider change.
     }

package/extension/src/content/providerSettingsDialog.js

@@ -381,7 +381,7 @@
           </label>
           <label class="codex-provider-field">
             <span>${escapeHtml(tx('Maximum output tokens', '最大输出 Token'))}</span>
-            <input type="number" data-provider-field="maxOutputTokens" min="256" max="200000" step="256" value="${Number(draft.maxOutputTokens) || 32768}">
+            <input type="number" data-provider-field="maxOutputTokens" min="256" max="65536" step="256" value="${Number(draft.maxOutputTokens) || 65536}">
           </label>
           <div class="codex-provider-field codex-provider-field--wide">
             <span>${escapeHtml(tx('Anthropic compatibility', 'Anthropic 兼容能力'))}</span>
@@ -736,7 +736,7 @@
       ,anthropicThinkingMode: get('anthropicThinkingMode')?.value || 'budget'
       ,anthropicPromptCaching: Boolean(get('anthropicPromptCaching')?.checked)
       ,impersonateClaudeCode: Boolean(get('impersonateClaudeCode')?.checked)
-      ,maxOutputTokens: Number(get('maxOutputTokens')?.value || 32768)
+      ,maxOutputTokens: Number(get('maxOutputTokens')?.value || 65536)
     };
     const apiKey = String(get('apiKey')?.value || '');
     const secretMutation = instance.secretAction === 'replace' && apiKey

package/extension/src/content/recentProjects.js

@@ -1,12 +1,7 @@
 (function initCodexOverleafRecentProjects() {
   'use strict';
 
-  // Recent-projects dashboard — the cross-project welcome variant carved out
-  // of contentRuntime.js (v1.4.8 structural-debt phase 4): the account-scoped
-  // project-name cache + DOM enrichment, the welcome/empty/degraded states,
-  // row rendering, and the per-project/variant switchers. Code moved verbatim;
-  // runtime collaborators are factory-injected (the account scope id stays in
-  // the runtime and is read through a getter).
+  // Cross-project dashboard: account-scoped names, project rows and sessions.
   function create(deps = {}) {
     const {
       tr,
@@ -24,6 +19,10 @@
       PROJECT_EDITOR_RESERVED_IDS,
       STATUS_BADGE_CLASS
     } = deps;
+    const projectSessionCleanup = window.CodexOverleafProjectSessionCleanup.create({
+      tr, getAccountScopeId: getCachedAccountScopeId, showPluginConfirm, showPluginToast,
+      sendBackgroundNative, mutateProjectPanelState, renderRecentProjectsVariant
+    });
 
   // chrome.storage.local cache key (spec §5.6.3). The cache is keyed by
   // accountScopeId so a second account on the same Chrome profile cannot
@@ -416,9 +415,6 @@
       el.appendChild(textNode(tr('recentProjects_row_projectLinkUnavailable'), 'recent-projects-row-warning'));
     }
     if (!valid) {
-      // Dead entry: the session records behind it carry an empty/garbage
-      // projectId, so it can never be opened or expanded. Offer a cleanup
-      // action that removes those records (and with them, this row).
       var deadWrap = document.createElement('div');
       deadWrap.className = 'recent-projects-row-wrap';
       var deadHead = document.createElement('div');
@@ -438,8 +434,6 @@
       deadWrap.appendChild(deadHead);
       return deadWrap;
     }
-    // Wrap the row with an expand toggle + a lazily-populated session list so
-    // sessions can be managed (delete/rename) without entering the project.
     var wrap = document.createElement('div');
     wrap.className = 'recent-projects-row-wrap';
     wrap.setAttribute('data-project-row-wrap', projectId);
@@ -456,8 +450,20 @@
     expand.textContent = tr('recentProjects_sessions_action');
     var head = document.createElement('div');
     head.className = 'recent-projects-row-head';
+    var clear = document.createElement('button');
+    clear.type = 'button';
+    clear.className = 'recent-projects-row-clear';
+    clear.setAttribute('data-project-clear', '');
+    clear.title = tr('recentProjects_clearProject');
+    clear.setAttribute('aria-label', tr('recentProjects_clearProject'));
+    clear.textContent = '×';
+    clear.addEventListener('click', function (event) {
+      event.stopPropagation();
+      projectSessionCleanup.clearProjectSessions(projectId, name).catch(function () { /* surfaced by the action */ });
+    });
     head.appendChild(el);
     head.appendChild(expand);
+    head.appendChild(clear);
     var sessionsEl = document.createElement('div');
     sessionsEl.className = 'recent-projects-sessions';
     sessionsEl.setAttribute('data-project-sessions', '');
@@ -504,9 +510,11 @@
       return [];
     }
     var records = await StorageDb.getAllByIndex('sessions', 'projectId', projectId);
+    var Persistence = window.CodexOverleafSessionPersistence;
+    var deletedIds = await Persistence.getDeletedSessionIds(projectId);
     var scope = getCachedAccountScopeId();
     return (records || [])
-      .filter(function (record) { return record && (!scope || record.accountScopeId === scope); })
+      .filter(function (record) { return Persistence.isVisibleRecord(record, deletedIds, scope); })
       .sort(function (a, b) {
         return String(b.updatedAt || b.createdAt || '').localeCompare(String(a.updatedAt || a.createdAt || ''));
       });
@@ -723,6 +731,7 @@
     if (!approved) {
       return;
     }
+    await window.CodexOverleafSessionPersistence.addTombstones(projectId, [record.id]);
     try {
       await mutateProjectPanelState(projectId, function (state) {
         return SessionState.deleteSession(state, record.id);
@@ -956,9 +965,11 @@
     try {
       var StorageDb = window.CodexOverleafStorageDb;
       if (StorageDb) {
+        var deletedSessionIdsByProject = await window.CodexOverleafSessionPersistence.loadTombstones();
         rows = await StorageDb.listRecentProjectsAcrossAccount({
           accountScopeId: accountScopeId,
-          limit: showAll ? 500 : pageLimit + 1
+          limit: showAll ? 500 : pageLimit + 1,
+          deletedSessionIdsByProject: deletedSessionIdsByProject
         });
       }
     } catch (_error) {

package/extension/src/content/runController.js

@@ -130,8 +130,8 @@
     });
   }
 
-  function shouldRestrictWritebackToFocus({ focusFiles = [] } = {}) {
-    return normalizeFocusFiles(focusFiles).length > 0;
+  function shouldRestrictWritebackToFocus({ focusFiles = [], focusedPartialSnapshot = false, otWarmStart = false } = {}) {
+    return normalizeFocusFiles(focusFiles).length > 0 && (focusedPartialSnapshot === true || otWarmStart === true);
   }
 
   function isFullSnapshotWarning(warning) {

package/extension/src/content/runGuidanceController.js

@@ -0,0 +1,70 @@
+(function initCodexOverleafRunGuidanceController() {
+  'use strict';
+
+  function create(deps = {}) {
+    function upsert(text, target = {}) {
+      const record = deps.findRunRecord?.(target.recordId, target.sessionId);
+      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;
+    }
+
+    function remove(guidanceId, target = {}) {
+      const record = deps.findRunRecord?.(target.recordId, target.sessionId);
+      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();
+      }
+      return record.events.length !== before;
+    }
+
+    function settleView(view) {
+      const guidance = view?.guidance || view?.root?.querySelector('[data-run-guidance]');
+      if (!guidance || !view?.events) return;
+      view.guidance = guidance;
+      for (const row of view.events.querySelectorAll('[data-kind="guidance"]')) guidance.append(row);
+    }
+
+    function appendToView(event, view) {
+      const text = window.CodexOverleafRunGuidanceView?.getGuidanceText(event);
+      if (!text) return false;
+      const guidance = view.guidance || view.root?.querySelector('[data-run-guidance]');
+      const target = view.terminalStatus ? guidance : view.events;
+      if (!target) return false;
+      view.guidance = guidance;
+      const rendered = deps.renderRunEvent(event);
+      const existing = event.guidanceId
+        ? view.root?.querySelector(`[data-guidance-id="${deps.cssEscape(event.guidanceId)}"]`)
+        : null;
+      if (existing) existing.replaceWith(rendered);
+      else target.append(rendered);
+      deps.bumpUnreadIfDetached?.();
+      return true;
+    }
+
+    return { upsert, remove, settleView, appendToView };
+  }
+
+  window.CodexOverleafRunGuidanceController = { create };
+})();

package/extension/src/content/runGuidanceView.js

@@ -0,0 +1,48 @@
+(function initCodexOverleafRunGuidanceView() {
+  'use strict';
+
+  const LEGACY_GUIDANCE_TITLES = new Set([
+    'Follow-up guidance was delivered to the active Codex turn.',
+    '\u540e\u7eed\u5f15\u5bfc\u5df2\u53d1\u9001\u5230\u5f53\u524d Codex turn\u3002'
+  ]);
+
+  const GUIDANCE_DELIVERY_PREFIX = /^(?:Guidance delivered|Follow-up guidance delivered|引导已发送|后续引导已发送)\s*[:：]\s*/i;
+
+  function normalizeGuidanceText(value) {
+    return String(value || '').trim().replace(GUIDANCE_DELIVERY_PREFIX, '').trim();
+  }
+
+  function getGuidanceText(event = {}) {
+    const detailText = typeof event.detail === 'string' ? event.detail.trim() : '';
+    if (event.kind === 'guidance') {
+      return normalizeGuidanceText(detailText || event.title);
+    }
+    return detailText && LEGACY_GUIDANCE_TITLES.has(String(event.title || ''))
+      ? normalizeGuidanceText(detailText)
+      : '';
+  }
+
+  function renderGuidanceMessage(event, guidanceText, tx) {
+    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);
+    return row;
+  }
+
+  window.CodexOverleafRunGuidanceView = {
+    getGuidanceText,
+    renderGuidanceMessage
+  };
+})();