codex-overleaf-link 2.1.1 → 2.1.3

package/README.md

@@ -3,7 +3,7 @@
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-2.1.1-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-2.1.3-blue" alt="version">
     <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="platform">
     <img src="https://img.shields.io/badge/chrome-MV3-green" alt="chrome manifest v3">
     <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version">
@@ -38,14 +38,14 @@ One command installs the managed native host **and** managed extension runtime.
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.1.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.1/install.sh)"
+CODEX_OVERLEAF_REF=v2.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.3/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.1/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v2.1.1'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.3/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v2.1.3'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -56,7 +56,7 @@ Then, in the `chrome://extensions` tab the script opened: enable **Developer mod
 `npm exec` installs the same managed native host and extension runtime without keeping a source checkout. Use it if you prefer a pinned npm package.
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- install-managed
+npm exec --yes codex-overleaf-link@2.1.3 -- install-managed
 ```
 
 Then, in `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the managed extension path printed by the command. The Release extension zip remains available for explicitly unmanaged/manual installations.
@@ -86,9 +86,9 @@ npm installs, updates, and uninstalls the coordinated managed extension/native p
 
 | Action | Command |
 |--------|---------|
-| Install / update | `npm exec --yes codex-overleaf-link@2.1.1 -- install-managed` |
-| Diagnose | `npm exec --yes codex-overleaf-link@2.1.1 -- doctor` |
-| Uninstall | `npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed` |
+| Install / update | `npm exec --yes codex-overleaf-link@2.1.3 -- install-managed` |
+| Diagnose | `npm exec --yes codex-overleaf-link@2.1.3 -- doctor` |
+| Uninstall | `npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed` |
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
 
@@ -98,13 +98,13 @@ Managed installations discover signed stable updates automatically and apply the
 
 ## GitHub Release Artifacts
 
-The v2.1.1 GitHub Release contains:
+The v2.1.3 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v2.1.1.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v2.1.1.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-2.1.1.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v2.1.1` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v2.1.1` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v2.1.3.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v2.1.3.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-2.1.3.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v2.1.3` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v2.1.3` when run directly from the release artifact.
 - `uninstall-native-host.mjs`: native host uninstaller that removes the Chrome Native Messaging manifest, bridge executable, and runtime copy.
 - `nativeHostPlatform.js`, `manifest.js`, `runtimeInstaller.js`: helper files required by the loose uninstaller asset.
 - `SHA256SUMS` and `release-manifest.json`: checksum and artifact metadata for release verification.
@@ -115,7 +115,7 @@ The v2.1.1 GitHub Release contains:
 Remove the native host (use `--browser chromium` on Linux Chromium):
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed
+npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed
 ```
 
 The same command works on Windows PowerShell. If you installed from a manual checkout or source installer, you can also run `npm run uninstall:native` inside the repo, use `node ~/.codex-overleaf/source/scripts/uninstall-native-host.mjs` on macOS / Linux, or use `node $env:LOCALAPPDATA\CodexOverleaf\source\scripts\uninstall-native-host.mjs` on Windows PowerShell.
@@ -150,13 +150,13 @@ Then remove the extension from `chrome://extensions`. To delete local data: on m
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v2.1.1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.1/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v2.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v2.1.3/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed --browser chromium
+npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed --browser chromium
 ```
 
 ## Features
@@ -292,7 +292,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Re-run any [native host installer](#install), reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This also fixes extension/native version mismatch and native protocol mismatch.
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- install-managed
+npm exec --yes codex-overleaf-link@2.1.3 -- install-managed
 ```
 
 **The Windows popup or panel shows a Bash recovery command**
@@ -341,8 +341,8 @@ Use this matrix for release-candidate signoff and compatibility reports. Record
 | Browser/channel/version | Google Chrome channel and version. | Google Chrome channel and version. | Google Chrome channel and version. | Chromium channel/package and version. |
 | Install mode | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout; native host installed with `--browser chromium`. |
 | Extension id | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. |
-| Installer/update command | `npm exec --yes codex-overleaf-link@2.1.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- install-managed --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-managed --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@2.1.3 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- install-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- install-managed --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed` | `npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-managed --browser chromium` |
 | Manifest/registry path | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` -> `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
 | Bridge/runtime/source path | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `%LOCALAPPDATA%\CodexOverleaf\codex-overleaf-bridge.cmd`; runtime `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime`; source `%LOCALAPPDATA%\CodexOverleaf\source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. |
 | Node/Git/Codex/TeX | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. |
@@ -378,7 +378,7 @@ Contributions are welcome. Please open an issue before submitting large changes
 The recommended v1.9 installation owns one stable unpacked-extension directory and a versioned native-host directory:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- install-managed
+npm exec --yes codex-overleaf-link@2.1.3 -- install-managed
 ```
 
 Load the printed extension path once from `chrome://extensions`. Starting with the next signed stable release, Codex Overleaf Link checks GitHub Releases automatically, downloads and verifies the coordinated extension/native-host bundle, waits until every connected Overleaf tab is saved and idle, and then updates both components together. A failed health check restores the previous version automatically.
@@ -388,11 +388,11 @@ The stable updater ignores drafts and prereleases, performs no telemetry, and ca
 The legacy native-only installer remains available for source or unmanaged extension directories:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- install-native
+npm exec --yes codex-overleaf-link@2.1.3 -- install-native
 ```
 
 Legacy native-only installations can be removed with:
 
 ```bash
-npm exec --yes codex-overleaf-link@2.1.1 -- uninstall-native
+npm exec --yes codex-overleaf-link@2.1.3 -- uninstall-native
 ```

package/extension/bootstrap/manifest.template.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Codex Overleaf Link",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Connect the active Overleaf project to a local Codex bridge.",
   "icons": {
     "16": "assets/icons/icon16.png",

package/extension/src/content/contentRuntime.js

@@ -1,6 +1,5 @@
 (function initCodexOverleafContentRuntime(root) {
   'use strict';
-
   function init() {
   'use strict';
 
@@ -438,7 +437,7 @@
     saveState,
     saveStateSoon,
     readPanelInputs,
-    applyStateToPanel,
+    applyStateToPanel, syncSessionProvider: () => providerSettingsCoordinator.syncSessionProvider(),
     getPanel: () => panel,
     getState: () => state,
     setState: next => { state = next; },
@@ -569,7 +568,8 @@
     tr,
     tx,
     getLocale,
-    sendBackgroundNative,
+    sendBackgroundNative, getProviderSelection: () => providerSettingsCoordinator.getRunSelection(state?.providerId)
+      || { providerId: state?.providerId || 'builtin', providerRevision: 0 },
     readSelectedSpeedInput,
     getRenderedModelEntries,
     persistPanelInputs,
@@ -603,8 +603,8 @@
     document,
     window,
     getSettingsPanelInstance: () => settingsPanelInstance,
-    getSelectedModel: () => state?.model || '',
-    clearSelectedModel: () => { if (state) state.model = ''; },
+    getSelectedModel: () => state?.model || '', getSelectedProviderId: () => state?.providerId || 'builtin',
+    setSelectedProviderId: providerId => { state = updateActiveSession(state, { providerId: providerId || 'builtin' }); },
     refreshModelOptions: loadModelOptions, persistInputs: persistPanelInputs
   });
   // v1.8.1 D3: the dashboard was a one-shot render — another tab finishing a
@@ -898,9 +898,7 @@
         }
       })
       .catch(() => { /* fail-closed inside refreshAccountScopeId */ });
-    loadModelOptions().catch(error => {
-      applyFallbackModelOptions(resolveSelectedModel(), error);
-    });
+    providerSettingsCoordinator.syncSessionProvider().catch(() => {});
     syncOtWarmMirrorController().catch(error => {
       updateOtStatusDisplay('unavailable');
       appendPlainLog(tx(`Failed to sync experimental OT warm mirror: ${error.message}`, `同步实验性 OT 预热镜像失败：${error.message}`));
@@ -2935,7 +2933,7 @@
     });
     return {
       ...params,
-      providerSelection: providerSettingsCoordinator.getRunSelection()
+      providerSelection: providerSettingsCoordinator.getRunSelection(state?.providerId)
     };
   }
 
@@ -2949,6 +2947,7 @@
       sessionId: input.sessionId || '',
       turnId: currentRunView?.recordId || '',
       mode: input.mode || state?.mode || '',
+      ...providerSettingsCoordinator.getProviderSnapshot(state?.providerId),
       model: state?.model || '',
       reasoningEffort: state?.reasoningEffort || '',
       speedTier: state?.speedTier || '',
@@ -5967,7 +5966,7 @@
       const { prefs, sessions, activeSessionId } = await Migration.runMigrationIfNeeded(projectId, legacyKey);
 
       return {
-        model: prefs.model || '',
+        model: prefs.model || '', providerId: prefs.providerId || 'builtin',
         reasoningEffort: prefs.reasoningEffort || '',
         speedTier: prefs.speedTier || '',
         mode: prefs.mode || '',
@@ -5992,7 +5991,7 @@
           runs: Array.isArray(session.runs) ? session.runs : [],
           history: Array.isArray(session.history) ? session.history : [],
           task: typeof session.task === 'string' ? session.task : '',
-          mode: session.mode || prefs.mode || 'confirm',
+          mode: session.mode || prefs.mode || 'confirm', providerId: session.providerId || 'builtin',
           model: session.model || prefs.model || 'gpt-5.4',
           reasoningEffort: session.reasoningEffort || prefs.reasoningEffort || 'high',
           speedTier: session.speedTier || prefs.speedTier || 'standard',
@@ -6012,7 +6011,7 @@
       const fallback = stored[storageKey] || stored[LEGACY_STORAGE_KEY] || {};
       if (fallback?.__codexOverleafCompactFallback === true) {
         return {
-          mode: fallback.mode || '',
+          mode: fallback.mode || '', providerId: fallback.providerId || 'builtin',
           model: fallback.model || '',
           reasoningEffort: fallback.reasoningEffort || '',
           speedTier: fallback.speedTier || '',
@@ -6453,7 +6452,7 @@
 
   function applyStateToPanel() {
     applyPanelTheme(getThemePreference());
-    if (!modelSelectHasOption(state.model)) {
+    if ((state.providerId || 'builtin') === 'builtin' && !modelSelectHasOption(state.model)) {
       renderModelOptions(getModelCatalog().FALLBACK_MODELS, state.model);
     }
     panel.querySelector('[data-model]').value = state.model;
@@ -6545,6 +6544,7 @@
       id: createRunId(),
       task,
       mode,
+      ...providerSettingsCoordinator.getProviderSnapshot(state?.providerId),
       model,
       reasoningEffort,
       speedTier,

package/extension/src/content/modelPicker.js

@@ -13,6 +13,7 @@
       tx,
       getLocale,
       sendBackgroundNative,
+      getProviderSelection,
       readSelectedSpeedInput,
       getRenderedModelEntries,
       persistPanelInputs,
@@ -33,6 +34,7 @@
     } = Support;
 
   let modelDiscovery = { status: 'fallback', source: 'fallback', fetchedAt: '' };
+  let modelLoadGeneration = 0;
 
   function getModelDiscovery() {
     return modelDiscovery;
@@ -96,7 +98,9 @@
     updateModelDisplay();
     await persistPanelInputs();
   }
-  async function loadModelOptions() {
+  async function loadModelOptions(providerSelection) {
+    const generation = ++modelLoadGeneration;
+    const selection = providerSelection || getProviderSelection?.() || null;
     const selectedModel = resolveSelectedModel();
     const modelCatalog = getModelCatalog();
     const fallbackModels = modelCatalog.FALLBACK_MODELS;
@@ -104,8 +108,19 @@
     try {
       const response = await sendBackgroundNative({
         method: 'codex.models',
-        params: {}
+        params: selection ? { providerSelection: selection } : {}
       });
+      if (generation !== modelLoadGeneration) {
+        return { stale: true };
+      }
+      const responseProviderId = response?.result?.providerId || '';
+      if (selection?.providerId && responseProviderId && responseProviderId !== selection.providerId) {
+        return { stale: true };
+      }
+      if (selection?.providerId && selection.providerId !== 'builtin'
+        && Number(response?.result?.providerRevision) !== Number(selection.providerRevision)) {
+        return { stale: true };
+      }
       const currentSelectedModel = resolveSelectedModel() || selectedModel;
       const hasDiscoveredModels = response?.ok
         && Array.isArray(response.result?.models)
@@ -121,17 +136,25 @@
         applyUnavailableModelOptions({ code: 'provider_model_catalog_invalid', message: 'The active provider returned no usable models.' });
         return;
       }
-      renderModelOptions(normalized.models, retainedSelectedModel);
+      renderModelOptions(normalized.models, retainedSelectedModel, { allowUnknownSelected: false });
       modelDiscovery = {
         status: hasDiscoveredModels && !normalized.usedFallback ? 'discovered' : 'fallback',
         source: hasDiscoveredModels ? response.result?.source || 'unknown' : 'fallback',
         fetchedAt: hasDiscoveredModels ? response.result?.fetchedAt || '' : '',
         errorCode: hasDiscoveredModels ? '' : response?.error?.code || '',
-        errorMessage: hasDiscoveredModels ? '' : response?.error?.message || ''
+        errorMessage: hasDiscoveredModels ? '' : response?.error?.message || '',
+        providerId: responseProviderId || selection?.providerId || 'builtin',
+        providerRevision: Number(response?.result?.providerRevision || selection?.providerRevision || 0)
       };
       updateModelDisplay();
+      await persistPanelInputs();
+      return { stale: false, providerId: modelDiscovery.providerId };
     } catch (error) {
+      if (generation !== modelLoadGeneration) {
+        return { stale: true };
+      }
       applyUnavailableModelOptions(error);
+      return { stale: false, error };
     }
   }
 
@@ -140,14 +163,13 @@
     if (modelSelect) {
       modelSelect.textContent = '';
       const option = document.createElement('option');
-      option.value = '';
+      option.value = resolveSelectedModel();
       option.textContent = tx('Models unavailable', '模型不可用');
       option.disabled = true;
       modelSelect.append(option);
       modelSelect.value = '';
       modelSelect.disabled = true;
     }
-    if (getState()) getState().model = '';
     modelDiscovery = {
       status: 'unavailable',
       source: 'custom-provider',
@@ -182,7 +204,7 @@
     return Support.getModelCatalog({ getPanel });
   }
 
-  function renderModelOptions(models, selectedModel) {
+  function renderModelOptions(models, selectedModel, options = {}) {
     const modelSelect = getPanel()?.querySelector('[data-model]');
     if (!modelSelect) {
       return;
@@ -219,7 +241,7 @@
       }
     }
 
-    if (selectedId && !renderedSelected) {
+    if (selectedId && !renderedSelected && options.allowUnknownSelected !== false) {
       const option = document.createElement('option');
       option.value = selectedId;
       option.textContent = `${selectedId} (custom)`;

package/extension/src/content/providerSettingsCoordinator.js

@@ -8,6 +8,8 @@
       sendBackgroundNative: options.sendBackgroundNative,
       getSettingsPanelInstance: options.getSettingsPanelInstance || (() => null),
       getSelectedModel: options.getSelectedModel || (() => ''),
+      getSelectedProviderId: options.getSelectedProviderId || (() => 'builtin'),
+      setSelectedProviderId: options.setSelectedProviderId || (() => {}),
       clearSelectedModel: options.clearSelectedModel || (() => {}),
       refreshModelOptions: options.refreshModelOptions || (() => {}),
       persistInputs: options.persistInputs || (() => {}),
@@ -38,7 +40,12 @@
       open: () => open(instance),
       refreshSummary: () => refresh(instance),
       ensureLoaded: () => ensureLoaded(instance),
-      getRunSelection: () => instance.loaded ? Profiles.buildRunSelection(instance.catalog) : null,
+      getRunSelection: providerId => instance.loaded
+        ? Profiles.buildRunSelection(instance.catalog, providerId || instance.getSelectedProviderId())
+        : null,
+      getProviderSnapshot: providerId => getProviderSnapshot(instance, providerId),
+      isProviderAvailable: providerId => Boolean(Profiles.getProviderById(instance.catalog, providerId)),
+      syncSessionProvider: () => syncSessionProvider(instance),
       getCatalog: () => instance.catalog,
       destroy: () => destroy(instance),
       _instance: instance
@@ -86,19 +93,33 @@
     return instance.catalog;
   }
 
+  async function syncSessionProvider(instance) {
+    try {
+      await ensureLoaded(instance);
+    } catch (_error) {
+      return instance.refreshModelOptions(
+        window.CodexOverleafProviderProfiles.buildRunSelection(instance.catalog, instance.getSelectedProviderId())
+      );
+    }
+    return reconcileProviderSelection(instance, instance.catalog, { forceSessionRefresh: true });
+  }
+
   async function reconcileProviderSelection(instance, catalog, change = {}) {
-    if (!change.activeProviderChanged && !change.activeModelCatalogChanged) {
-      return;
+    const previousProviderId = instance.getSelectedProviderId() || 'builtin';
+    const requestedProviderId = typeof change.sessionProviderId === 'string' && change.sessionProviderId
+      ? change.sessionProviderId
+      : previousProviderId;
+    const sessionProviderChanged = requestedProviderId !== previousProviderId;
+    if (sessionProviderChanged) {
+      instance.setSelectedProviderId(requestedProviderId);
     }
-    const previousModel = instance.getSelectedModel();
-    const activeProvider = window.CodexOverleafProviderProfiles.getActiveProvider(catalog);
-    const previousModelUnavailable = activeProvider.kind === 'custom'
-      && previousModel
-      && !activeProvider.models.some(model => model.id === previousModel);
-    if (change.activeProviderChanged || previousModelUnavailable) {
-      instance.clearSelectedModel();
+    const changedProviderIds = Array.isArray(change.changedProviderIds) ? change.changedProviderIds : [];
+    if (!change.forceSessionRefresh && !sessionProviderChanged && !changedProviderIds.includes(requestedProviderId)) {
+      return;
     }
-    await instance.refreshModelOptions();
+    await instance.refreshModelOptions(
+      window.CodexOverleafProviderProfiles.buildRunSelection(catalog, requestedProviderId)
+    );
     await instance.persistInputs();
   }
 
@@ -174,7 +195,9 @@
         updateDialog: true,
         selectedId: result.savedProviderId
       });
-      await notifyChanged(instance, applied.change);
+      await notifyChanged(instance, applied.change, action.activate === true
+        ? { sessionProviderId: result.savedProviderId }
+        : {});
       instance.dialog.setBusy('', '');
       const fellBackToBuiltin = previousCatalog.activeProviderId === result.savedProviderId
         && result.activeProviderId === 'builtin'
@@ -249,7 +272,7 @@
         updateDialog: true,
         selectedId: context.profileId
       });
-      await notifyChanged(instance, applied.change);
+      await notifyChanged(instance, applied.change, { sessionProviderId: context.profileId });
       instance.dialog.setBusy('', '');
       instance.dialog.setStatus({
         tone: 'success',
@@ -269,7 +292,7 @@
         expectedRevision: 0
       });
       const applied = applyCatalog(instance, result, { updateDialog: true, selectedId: 'builtin' });
-      await notifyChanged(instance, applied.change);
+      await notifyChanged(instance, applied.change, { sessionProviderId: 'builtin' });
       instance.dialog.setBusy('', '');
       instance.dialog.setStatus({ tone: 'success', title: instance.tx('Built-in Codex is active.', '已启用内置 Codex。') });
     } catch (error) {
@@ -315,22 +338,22 @@
   function updateSettingsSummary(instance, override = {}) {
     const active = window.CodexOverleafProviderProfiles.getActiveProvider(instance.catalog);
     const summary = override.summary || (active.kind === 'builtin'
-      ? instance.tx('Built-in Codex is active', '当前使用内置 Codex')
-      : `${active.name} · ${active.defaultModelId || instance.tx('No model', '未配置模型')} · ${instance.tx('Active', '使用中')}`);
+      ? instance.tx('Built-in Codex · default for new sessions', '内置 Codex · 新会话默认')
+      : `${active.name} · ${active.defaultModelId || instance.tx('No model', '未配置模型')} · ${instance.tx('Default for new sessions', '新会话默认')}`);
     instance.getSettingsPanelInstance()?.setProviderSummary?.({
       summary,
       tone: override.tone || (active.kind === 'custom' && active.wireApiPreference === 'auto' && !active.resolvedWireApi ? 'warning' : 'ok')
     });
   }
 
-  async function notifyChanged(instance, change = emptyCatalogChange()) {
+  async function notifyChanged(instance, change = emptyCatalogChange(), localChange = {}) {
     try {
       instance.channel?.postMessage?.({ type: 'provider-settings-changed', change, at: Date.now() });
     } catch (_error) {
       // Revision checks remain authoritative when BroadcastChannel is unavailable.
     }
     try {
-      await instance.onProviderChanged(instance.catalog, change);
+      await instance.onProviderChanged(instance.catalog, { ...change, ...localChange });
     } catch (_error) {
       // The authoritative catalog is already saved. A later refresh can retry
       // the local model projection without rolling back the provider change.
@@ -356,9 +379,19 @@
   function describeCatalogChange(previous, next) {
     const previousActive = window.CodexOverleafProviderProfiles.getActiveProvider(previous);
     const nextActive = window.CodexOverleafProviderProfiles.getActiveProvider(next);
+    const providerIds = new Set([
+      ...(previous.providers || []).map(provider => provider.id),
+      ...(next.providers || []).map(provider => provider.id)
+    ]);
+    const changedProviderIds = Array.from(providerIds).filter(providerId => {
+      const previousProvider = window.CodexOverleafProviderProfiles.getProviderById(previous, providerId);
+      const nextProvider = window.CodexOverleafProviderProfiles.getProviderById(next, providerId);
+      return modelCatalogSignature(previousProvider) !== modelCatalogSignature(nextProvider);
+    });
     return {
       activeProviderChanged: previousActive.id !== nextActive.id,
-      activeModelCatalogChanged: modelCatalogSignature(previousActive) !== modelCatalogSignature(nextActive)
+      activeModelCatalogChanged: modelCatalogSignature(previousActive) !== modelCatalogSignature(nextActive),
+      changedProviderIds
     };
   }
 
@@ -377,7 +410,32 @@
   }
 
   function emptyCatalogChange() {
-    return { activeProviderChanged: false, activeModelCatalogChanged: false };
+    return { activeProviderChanged: false, activeModelCatalogChanged: false, changedProviderIds: [] };
+  }
+
+  function getProviderSnapshot(instance, providerId) {
+    const requestedId = providerId || instance.getSelectedProviderId() || 'builtin';
+    const provider = window.CodexOverleafProviderProfiles.getProviderById(instance.catalog, requestedId);
+    if (!provider) {
+      return {
+        providerId: requestedId,
+        providerName: 'Unavailable provider',
+        providerRevision: 0,
+        providerEndpointHost: ''
+      };
+    }
+    let endpointHost = '';
+    try {
+      endpointHost = provider.baseUrl ? new URL(provider.baseUrl).host : '';
+    } catch (_error) {
+      endpointHost = '';
+    }
+    return {
+      providerId: provider.id,
+      providerName: provider.name || provider.id,
+      providerRevision: provider.revision || 0,
+      providerEndpointHost: endpointHost
+    };
   }
 
   function formatError(instance, error) {

package/extension/src/content/sessionManager.js

@@ -28,6 +28,7 @@
       saveStateSoon,
       readPanelInputs,
       applyStateToPanel,
+      syncSessionProvider,
       getPanel,
       getState,
       setState,
@@ -98,6 +99,7 @@
     }
     const session = createSession({
       mode: getState().mode,
+      providerId: getState().providerId || 'builtin',
       model: getState().model,
       reasoningEffort: getState().reasoningEffort,
       speedTier: getState().speedTier,
@@ -108,8 +110,9 @@
       sessions: [...(getState().sessions || []), session].slice(-20),
       activeSessionId: session.id
     }));
-    await saveState();
     applyStateToPanel();
+    await syncSessionProvider?.();
+    await saveState();
     getPanel().querySelector('[data-task]')?.focus();
   }
 
@@ -130,8 +133,9 @@
     }
     readPanelInputs();
     setState(setActiveSession(getState(), sessionId));
-    await saveState();
     applyStateToPanel();
+    await syncSessionProvider?.();
+    await saveState();
   }
 
   async function deleteSessionWithConfirm(sessionId) {

package/extension/src/shared/auditRecords.js

@@ -31,6 +31,10 @@
       createdAt: redactSecretLikeText(stringField(input.createdAt)) || now,
       completedAt: '',
       mode: redactSecretLikeText(stringField(input.mode)),
+      providerId: redactSecretLikeText(stringField(input.providerId)) || 'builtin',
+      providerName: redactSecretLikeText(stringField(input.providerName)),
+      providerRevision: finiteNumber(input.providerRevision) || 0,
+      providerEndpointHost: redactSecretLikeText(stringField(input.providerEndpointHost)),
       model: redactSecretLikeText(stringField(input.model)),
       reasoningEffort: redactSecretLikeText(stringField(input.reasoningEffort)),
       speedTier: redactSecretLikeText(stringField(input.speedTier)),
@@ -85,6 +89,10 @@
       createdAt: redactSecretLikeText(stringField(input.createdAt)) || new Date().toISOString(),
       completedAt: redactSecretLikeText(stringField(input.completedAt)),
       mode: redactSecretLikeText(stringField(input.mode)),
+      providerId: redactSecretLikeText(stringField(input.providerId)) || 'builtin',
+      providerName: redactSecretLikeText(stringField(input.providerName)),
+      providerRevision: finiteNumber(input.providerRevision) || 0,
+      providerEndpointHost: redactSecretLikeText(stringField(input.providerEndpointHost)),
       model: redactSecretLikeText(stringField(input.model)),
       reasoningEffort: redactSecretLikeText(stringField(input.reasoningEffort)),
       speedTier: redactSecretLikeText(stringField(input.speedTier)),

package/extension/src/shared/compatibility.js

@@ -12,7 +12,7 @@
   const MIN_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_EXTENSION_VERSION = '1.0.0';
-  const BUILD_TARGET_VERSION = '2.1.1';
+  const BUILD_TARGET_VERSION = '2.1.3';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/providerProfiles.js

@@ -175,11 +175,23 @@
       || buildBuiltinProvider();
   }
 
-  function buildRunSelection(catalog = {}) {
-    const active = getActiveProvider(catalog);
+  function getProviderById(catalog = {}, providerId = '') {
+    const normalized = normalizeCatalog(catalog);
+    const requestedId = normalizeText(providerId) || normalized.activeProviderId || BUILTIN_PROVIDER_ID;
+    if (requestedId === BUILTIN_PROVIDER_ID) {
+      return normalized.providers.find(provider => provider.id === BUILTIN_PROVIDER_ID)
+        || buildBuiltinProvider();
+    }
+    return normalized.providers.find(provider => provider.id === requestedId) || null;
+  }
+
+  function buildRunSelection(catalog = {}, providerId = '') {
+    const normalized = normalizeCatalog(catalog);
+    const requestedId = normalizeText(providerId) || normalized.activeProviderId || BUILTIN_PROVIDER_ID;
+    const provider = getProviderById(normalized, requestedId);
     return {
-      providerId: active.id,
-      providerRevision: active.revision || 0
+      providerId: requestedId,
+      providerRevision: provider?.revision || 0
     };
   }
 
@@ -277,6 +289,7 @@
     buildEmptyDraft,
     buildRunSelection,
     getActiveProvider,
+    getProviderById,
     normalizeCatalog,
     normalizeProvider
   };

package/extension/src/shared/sessionState.js

@@ -13,6 +13,7 @@
 
   const DEFAULT_PANEL_STATE = {
     mode: 'confirm',
+    providerId: 'builtin',
     model: 'gpt-5.4',
     reasoningEffort: 'high',
     speedTier: 'standard',
@@ -177,6 +178,7 @@
       ...legacySession,
       task: state.task,
       mode: state.mode,
+      providerId: 'builtin',
       model: state.model,
       reasoningEffort: state.reasoningEffort,
       speedTier: state.speedTier,
@@ -208,6 +210,9 @@
       runs,
       task: sanitizeAssistantVisibleText(session.task),
       mode: VALID_MODES.has(session.mode) ? session.mode : fallbackState.mode,
+      providerId: typeof session.providerId === 'string' && session.providerId.trim()
+        ? session.providerId.trim()
+        : 'builtin',
       model: typeof session.model === 'string' && session.model ? session.model : fallbackState.model,
       reasoningEffort: VALID_REASONING.has(session.reasoningEffort)
         ? session.reasoningEffort
@@ -237,6 +242,7 @@
         id: `recovered_${session.id}_${index}`,
         task,
         mode: session.mode,
+        providerId: session.providerId || 'builtin',
         model: session.model,
         reasoningEffort: session.reasoningEffort,
         speedTier: session.speedTier,
@@ -269,6 +275,7 @@
     if (!active) {
       const session = createSession({
         mode: state.mode,
+        providerId: state.providerId,
         model: state.model,
         reasoningEffort: state.reasoningEffort,
         speedTier: state.speedTier,
@@ -283,12 +290,16 @@
       id: active.id,
       history: Array.isArray(active.history) ? active.history.slice(-10) : [],
       focusFiles: normalizeFocusFiles(active.focusFiles),
-      codexThreadId: active.codexThreadId || ''
+      codexThreadId: active.codexThreadId || '',
+      providerId: active.providerId || 'builtin'
     };
     state.runs = Array.isArray(active.runs) ? active.runs : [];
     state.task = typeof active.task === 'string' ? active.task : '';
     state.focusFiles = normalizeFocusFiles(active.focusFiles);
     state.mode = VALID_MODES.has(active.mode) ? active.mode : DEFAULT_PANEL_STATE.mode;
+    state.providerId = typeof active.providerId === 'string' && active.providerId
+      ? active.providerId
+      : 'builtin';
     state.model = typeof active.model === 'string' && active.model ? active.model : DEFAULT_PANEL_STATE.model;
     state.reasoningEffort = VALID_REASONING.has(active.reasoningEffort)
       ? active.reasoningEffort
@@ -318,6 +329,9 @@
       runs,
       task: sanitizeAssistantVisibleText(overrides.task),
       mode: VALID_MODES.has(overrides.mode) ? overrides.mode : DEFAULT_PANEL_STATE.mode,
+      providerId: typeof overrides.providerId === 'string' && overrides.providerId.trim()
+        ? overrides.providerId.trim()
+        : 'builtin',
       model: typeof overrides.model === 'string' && overrides.model ? overrides.model : DEFAULT_PANEL_STATE.model,
       reasoningEffort: VALID_REASONING.has(overrides.reasoningEffort)
         ? overrides.reasoningEffort
@@ -404,6 +418,7 @@
     if (!remaining.length) {
       const replacement = createSession({
         mode: state.mode,
+        providerId: state.providerId,
         model: state.model,
         reasoningEffort: state.reasoningEffort,
         speedTier: state.speedTier,
@@ -589,6 +604,10 @@
       id: run.id,
       task: sanitizeAssistantVisibleText(run.task) || 'untitled task',
       mode: typeof run.mode === 'string' ? run.mode : '',
+      providerId: typeof run.providerId === 'string' && run.providerId ? run.providerId : 'builtin',
+      providerName: typeof run.providerName === 'string' ? run.providerName : '',
+      providerRevision: Number.isFinite(Number(run.providerRevision)) ? Number(run.providerRevision) : 0,
+      providerEndpointHost: typeof run.providerEndpointHost === 'string' ? run.providerEndpointHost : '',
       model: typeof run.model === 'string' ? run.model : '',
       reasoningEffort: typeof run.reasoningEffort === 'string' ? run.reasoningEffort : '',
       speedTier: typeof run.speedTier === 'string' ? run.speedTier : '',

package/extension/src/shared/storageDb.js

@@ -6,7 +6,7 @@
   }
 })(typeof globalThis !== 'undefined' ? globalThis : window, function storageDbFactory(StorageRunActions) {
   'use strict';
-  if (!StorageRunActions?.compactRunsForStorage || !StorageRunActions?.compactRunActionPayload) {
+  if (!StorageRunActions?.compactRunsForStorage || !StorageRunActions?.compactRunActionPayload || !StorageRunActions?.compactProviderSnapshot) {
     throw new Error('Codex Overleaf storage run-action helpers are unavailable.');
   }
   // IndexedDB versions are monotonic; v2.0 RC profiles have already opened v3.
@@ -275,7 +275,7 @@
       history: compactHistoryForStorage(input.history),
       runs: compactRunsForStorage(input.runs, options),
       task: normalizeDisplayTextForStorage(input.task, SESSION_STORAGE_LIMITS.taskChars),
-      mode: typeof input.mode === 'string' ? input.mode : '',
+      mode: typeof input.mode === 'string' ? input.mode : '', providerId: typeof input.providerId === 'string' && input.providerId ? input.providerId : 'builtin',
       model: typeof input.model === 'string' ? input.model : '',
       reasoningEffort: typeof input.reasoningEffort === 'string' ? input.reasoningEffort : '',
       speedTier: typeof input.speedTier === 'string' ? input.speedTier : '',
@@ -402,7 +402,7 @@
       turnId: typeof input.turnId === 'string' ? input.turnId : '',
       createdAt: typeof input.createdAt === 'string' ? input.createdAt : now,
       completedAt: typeof input.completedAt === 'string' ? input.completedAt : '',
-      mode: typeof input.mode === 'string' ? input.mode : '',
+      mode: typeof input.mode === 'string' ? input.mode : '', ...StorageRunActions.compactProviderSnapshot(input),
       model: typeof input.model === 'string' ? input.model : '',
       reasoningEffort: typeof input.reasoningEffort === 'string' ? input.reasoningEffort : '',
       speedTier: typeof input.speedTier === 'string' ? input.speedTier : '',
@@ -426,7 +426,7 @@
 
   function extractLightweightPrefs(state, projectId) {
     var prefs = {
-      storageSchemaVersion: TARGET_SCHEMA_VERSION,
+      storageSchemaVersion: TARGET_SCHEMA_VERSION, providerId: typeof state.providerId === 'string' && state.providerId ? state.providerId : 'builtin',
       model: typeof state.model === 'string' ? state.model : '',
       reasoningEffort: typeof state.reasoningEffort === 'string' ? state.reasoningEffort : '',
       speedTier: typeof state.speedTier === 'string' ? state.speedTier : '',
@@ -647,7 +647,7 @@
     var compact = {
       id: run.id,
       task: normalizeDisplayTextForStorage(run.task || 'untitled task', SESSION_STORAGE_LIMITS.taskChars),
-      mode: typeof run.mode === 'string' ? redactSecretLikeText(run.mode) : '',
+      mode: typeof run.mode === 'string' ? redactSecretLikeText(run.mode) : '', ...StorageRunActions.compactProviderSnapshot(run),
       model: normalizeTextField(run.model, 80),
       reasoningEffort: typeof run.reasoningEffort === 'string' ? redactSecretLikeText(run.reasoningEffort) : '',
       speedTier: typeof run.speedTier === 'string' ? redactSecretLikeText(run.speedTier) : '',

package/extension/src/shared/storageMigration.js

@@ -81,6 +81,7 @@
       runs: Array.isArray(legacy.runs) ? legacy.runs : [],
       task: typeof legacy.task === 'string' ? legacy.task : '',
       mode: typeof legacy.mode === 'string' ? legacy.mode : legacyBlob.mode || '',
+      providerId: typeof legacy.providerId === 'string' && legacy.providerId ? legacy.providerId : 'builtin',
       model: typeof legacy.model === 'string' ? legacy.model : legacyBlob.model || '',
       reasoningEffort: typeof legacy.reasoningEffort === 'string' ? legacy.reasoningEffort : legacyBlob.reasoningEffort || '',
       speedTier: typeof legacy.speedTier === 'string' ? legacy.speedTier : legacyBlob.speedTier || '',

package/extension/src/shared/storageRunActions.js

@@ -92,8 +92,18 @@
     return value.length * 2;
   }
 
+  function compactProviderSnapshot(value) {
+    return {
+      providerId: typeof value.providerId === 'string' && value.providerId ? value.providerId : 'builtin',
+      providerName: typeof value.providerName === 'string' ? value.providerName : '',
+      providerRevision: Number.isFinite(Number(value.providerRevision)) ? Number(value.providerRevision) : 0,
+      providerEndpointHost: typeof value.providerEndpointHost === 'string' ? value.providerEndpointHost : ''
+    };
+  }
+
   return {
     compactRunsForStorage: compactRunsForStorage,
-    compactRunActionPayload: compactRunActionPayload
+    compactRunActionPayload: compactRunActionPayload,
+    compactProviderSnapshot: compactProviderSnapshot
   };
 });

package/native-host/src/codexRuntimeIdentity.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const RUNTIME_ENV_KEY = 'CODEX_OVERLEAF_CODEX_RUNTIME_JSON';
+const MAX_CODEX_CANDIDATES = 8;
+const VERSION_TIMEOUT_MS = 700;
+
+function buildCodexRuntimeIdentity(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const delimiter = options.delimiter || (platform === 'win32' ? ';' : path.delimiter);
+  const selectedPath = String(options.selectedPath || '').trim();
+  const discovered = discoverCodexCandidates(options.pathValue || env.PATH || '', {
+    delimiter,
+    env,
+    platform
+  });
+  const candidatePaths = selectedPath
+    ? [selectedPath, ...discovered.filter(candidate => !sameExecutablePath(candidate, selectedPath, platform))]
+    : discovered;
+  const candidates = candidatePaths.slice(0, MAX_CODEX_CANDIDATES).map((candidatePath, index) => ({
+    path: candidatePath,
+    displayPath: compactHomePath(candidatePath, env, platform),
+    version: readCodexVersion(candidatePath, { env, platform }),
+    source: classifyCodexSource(candidatePath),
+    selected: index === 0 && Boolean(selectedPath)
+  }));
+  const selected = candidates.find(candidate => candidate.selected) || null;
+
+  return {
+    schemaVersion: 1,
+    selected,
+    candidates,
+    multipleInstallations: candidates.length > 1,
+    selectedBy: selected ? 'path-order' : 'not-found'
+  };
+}
+
+function discoverCodexCandidates(pathValue, options = {}) {
+  const platform = options.platform || process.platform;
+  const delimiter = options.delimiter || (platform === 'win32' ? ';' : path.delimiter);
+  const extensions = executableExtensions(options.env || process.env, platform);
+  const seen = new Set();
+  const result = [];
+
+  for (const rawSegment of String(pathValue || '').split(delimiter)) {
+    const segment = rawSegment.trim();
+    if (!segment) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(segment, `codex${extension}`);
+      const key = platform === 'win32' ? candidate.toLowerCase() : candidate;
+      if (seen.has(key) || !isExecutableFile(candidate, platform)) continue;
+      seen.add(key);
+      result.push(candidate);
+      break;
+    }
+  }
+  return result;
+}
+
+function executableExtensions(env, platform) {
+  if (platform !== 'win32') return [''];
+  const configured = String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .map(value => value.trim().toLowerCase())
+    .filter(Boolean);
+  return ['', ...new Set(configured)];
+}
+
+function isExecutableFile(candidate, platform) {
+  try {
+    if (!fs.statSync(candidate).isFile()) return false;
+    fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readCodexVersion(candidatePath, options = {}) {
+  if (!candidatePath) return '';
+  const platform = options.platform || process.platform;
+  const result = spawnSync(candidatePath, ['--version'], {
+    encoding: 'utf8',
+    env: options.env || process.env,
+    maxBuffer: 64 * 1024,
+    shell: platform === 'win32' && /\.(?:cmd|bat)$/i.test(candidatePath),
+    timeout: VERSION_TIMEOUT_MS,
+    windowsHide: true
+  });
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`.trim();
+  const match = output.match(/\bcodex(?:-cli)?\s+v?([^\s]+)/i);
+  return match ? match[1] : '';
+}
+
+function classifyCodexSource(candidatePath) {
+  const normalized = normalizeSlashes(candidatePath).toLowerCase();
+  let resolved = normalized;
+  try {
+    resolved = normalizeSlashes(fs.realpathSync(candidatePath)).toLowerCase();
+  } catch {
+    // Keep the visible path when a symlink target cannot be resolved.
+  }
+  if (normalized.includes('/applications/chatgpt.app/')) return 'chatgpt-app';
+  if (normalized.includes('/applications/codex.app/')) return 'codex-app';
+  if (normalized.includes('/.nvm/versions/node/')) return 'npm-nvm';
+  if (resolved.includes('/node_modules/@openai/codex')) return 'npm-global';
+  if (normalized.includes('/opt/homebrew/') || normalized.includes('/homebrew/')) return 'homebrew-prefix';
+  if (normalized.includes('/.npm-global/')) return 'npm-global';
+  return 'path';
+}
+
+function compactHomePath(candidatePath, env = process.env, platform = process.platform) {
+  const home = String(env.HOME || env.USERPROFILE || os.homedir() || '');
+  if (!home) return candidatePath;
+  const caseFold = value => platform === 'win32' ? value.toLowerCase() : value;
+  const normalizedCandidate = path.normalize(candidatePath);
+  const normalizedHome = path.normalize(home);
+  if (caseFold(normalizedCandidate) === caseFold(normalizedHome)) return '~';
+  if (caseFold(normalizedCandidate).startsWith(`${caseFold(normalizedHome)}${path.sep}`)) {
+    return `~${path.sep}${normalizedCandidate.slice(normalizedHome.length + 1)}`;
+  }
+  return candidatePath;
+}
+
+function serializeCodexRuntimeIdentity(identity) {
+  return JSON.stringify(identity || emptyIdentity());
+}
+
+function getCodexRuntimeIdentityFromEnv(env = process.env) {
+  try {
+    const parsed = JSON.parse(String(env[RUNTIME_ENV_KEY] || ''));
+    if (parsed && typeof parsed === 'object' && Array.isArray(parsed.candidates)) return parsed;
+  } catch {
+    // Fall through to the legacy single-path representation.
+  }
+  const selectedPath = String(env.CODEX_OVERLEAF_CODEX_PATH || '').trim();
+  const selected = selectedPath ? {
+    path: selectedPath,
+    displayPath: compactHomePath(selectedPath, env, env.CODEX_OVERLEAF_PLATFORM || process.platform),
+    version: String(env.CODEX_OVERLEAF_CODEX_VERSION || ''),
+    source: String(env.CODEX_OVERLEAF_CODEX_SOURCE || classifyCodexSource(selectedPath)),
+    selected: true
+  } : null;
+  return {
+    schemaVersion: 1,
+    selected,
+    candidates: selected ? [selected] : [],
+    multipleInstallations: false,
+    selectedBy: selected ? 'legacy-path' : 'not-found'
+  };
+}
+
+function buildCodexRuntimeEvent(env = process.env) {
+  const identity = getCodexRuntimeIdentityFromEnv(env);
+  const selected = identity.selected;
+  if (!selected) return null;
+  const version = selected.version || 'unknown version';
+  const candidateCount = identity.candidates.length;
+  return {
+    type: 'codex.runtime.selected',
+    title: identity.multipleInstallations
+      ? `Using Codex CLI ${version}; ${candidateCount} installations were detected.`
+      : `Using Codex CLI ${version}.`,
+    status: 'completed',
+    detail: {
+      path: selected.displayPath || selected.path,
+      version: selected.version || '',
+      source: selected.source || 'path',
+      selectedBy: identity.selectedBy || 'path-order',
+      multipleInstallations: identity.multipleInstallations === true,
+      warningCode: identity.multipleInstallations ? 'multiple_codex_installations' : '',
+      candidates: identity.candidates.map(candidate => ({
+        path: candidate.displayPath || candidate.path,
+        version: candidate.version || '',
+        source: candidate.source || 'path',
+        selected: candidate.selected === true
+      })),
+      technical: true
+    }
+  };
+}
+
+function sameExecutablePath(left, right, platform) {
+  const normalize = value => path.normalize(String(value || ''));
+  return platform === 'win32'
+    ? normalize(left).toLowerCase() === normalize(right).toLowerCase()
+    : normalize(left) === normalize(right);
+}
+
+function normalizeSlashes(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function emptyIdentity() {
+  return {
+    schemaVersion: 1,
+    selected: null,
+    candidates: [],
+    multipleInstallations: false,
+    selectedBy: 'not-found'
+  };
+}
+
+module.exports = {
+  RUNTIME_ENV_KEY,
+  buildCodexRuntimeEvent,
+  buildCodexRuntimeIdentity,
+  discoverCodexCandidates,
+  getCodexRuntimeIdentityFromEnv,
+  readCodexVersion,
+  serializeCodexRuntimeIdentity
+};

package/native-host/src/nativeDoctor.js

@@ -56,6 +56,7 @@ async function runDoctor(options = {}) {
       errors: []
     },
     bridge: null,
+    codex: null,
     ping: {
       attempted: false
     },
@@ -106,6 +107,10 @@ async function runDoctor(options = {}) {
   body.ping = pingResult;
 
   if (body.ping.ok) {
+    body.codex = sanitizeCodexRuntime(
+      rawPingResponse?.result?.environment?.codex,
+      pathOptions
+    );
     body.compatibility = sanitizeCompatibility(
       evaluateNativeCompatibility(rawPingResponse, { version: PACKAGE_VERSION })
     );
@@ -206,6 +211,19 @@ function formatDoctorHuman(body = {}) {
     lines.push(`Native compatibility: ${body.compatibility.classification || 'unknown'}`);
     lines.push(`Native version: ${body.compatibility.nativeVersion || 'unknown'}`);
   }
+  if (body.codex) {
+    lines.push(`Codex status: ${body.codex.ok ? 'available' : 'not found'}`);
+    lines.push(`Codex path: ${body.codex.path || 'unknown'}`);
+    lines.push(`Codex version: ${body.codex.version || 'unknown'}`);
+    lines.push(`Codex source: ${body.codex.source || 'unknown'}`);
+    if (body.codex.multipleInstallations) {
+      lines.push('Warning: multiple Codex installations detected.');
+      lines.push('Codex candidates:');
+      for (const candidate of body.codex.candidates) {
+        lines.push(`  ${candidate.selected ? '*' : '-'} ${candidate.path || 'unknown'} (${candidate.version || 'unknown'}, ${candidate.source || 'path'})`);
+      }
+    }
+  }
   if (body.ping?.ok === false) {
     lines.push(`Ping: failed (${body.ping.error || 'unknown error'})`);
   } else if (body.ping?.ok === true) {
@@ -255,6 +273,28 @@ function normalizeDiagnosticPath(targetPath, options = {}) {
   return value;
 }
 
+function sanitizeCodexRuntime(codex, pathOptions) {
+  if (!codex || typeof codex !== 'object') return null;
+  const normalizeCodexPath = value => {
+    const normalized = normalizeDiagnosticPath(value, pathOptions);
+    return normalized.includes('<absolute-path>') ? String(value || '') : normalized;
+  };
+  return {
+    ok: codex.ok === true,
+    path: normalizeCodexPath(codex.path || ''),
+    version: String(codex.version || ''),
+    source: String(codex.source || ''),
+    selectedBy: String(codex.selectedBy || ''),
+    multipleInstallations: codex.multipleInstallations === true,
+    candidates: Array.isArray(codex.candidates) ? codex.candidates.map(candidate => ({
+      path: normalizeCodexPath(candidate?.path || ''),
+      version: String(candidate?.version || ''),
+      source: String(candidate?.source || ''),
+      selected: candidate?.selected === true
+    })) : []
+  };
+}
+
 function finalizeDoctorResult(body) {
   const classification = classifyDoctorResult(body);
   body.ok = classification.ok;

package/native-host/src/nativeEnvironment.js

@@ -4,6 +4,11 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const {
+  buildCodexRuntimeIdentity,
+  getCodexRuntimeIdentityFromEnv,
+  serializeCodexRuntimeIdentity
+} = require('./codexRuntimeIdentity');
 
 const TOOL_NAMES = ['codex', 'latexmk', 'pdflatex', 'xelatex', 'lualatex', 'bibtex', 'biber'];
 const LATEX_TOOL_NAMES = ['latexmk', 'pdflatex', 'xelatex', 'lualatex', 'bibtex', 'biber'];
@@ -32,6 +37,16 @@ function buildNativeRuntimeEnv(baseEnv = process.env, options = {}) {
   for (const tool of TOOL_NAMES) {
     env[getToolEnvName(tool)] = resolveExecutable(tool, env.PATH, { ...runtimeOptions, env }) || '';
   }
+  const codexRuntime = buildCodexRuntimeIdentity({
+    selectedPath: env.CODEX_OVERLEAF_CODEX_PATH,
+    pathValue: env.PATH,
+    delimiter: runtimeOptions.delimiter,
+    env,
+    platform: runtimeOptions.platform
+  });
+  env.CODEX_OVERLEAF_CODEX_RUNTIME_JSON = serializeCodexRuntimeIdentity(codexRuntime);
+  env.CODEX_OVERLEAF_CODEX_VERSION = codexRuntime.selected?.version || '';
+  env.CODEX_OVERLEAF_CODEX_SOURCE = codexRuntime.selected?.source || '';
 
   return env;
 }
@@ -200,13 +215,25 @@ function resolveExecutable(name, pathValue, options = {}) {
 }
 
 function summarizeNativeEnvironment(env = process.env, options = {}) {
+  const codexRuntime = getCodexRuntimeIdentityFromEnv(env);
+  const selectedCodex = codexRuntime.selected || {};
   const runtimeOptions = { ...options, platform: getNativeRuntimePlatform({ ...options, env }) };
   const availableLatex = LATEX_TOOL_NAMES.filter(tool => Boolean(env[getToolEnvName(tool)]));
   const missingLatex = LATEX_TOOL_NAMES.filter(tool => !env[getToolEnvName(tool)]);
   return {
     codex: {
       ok: Boolean(env.CODEX_OVERLEAF_CODEX_PATH),
-      path: env.CODEX_OVERLEAF_CODEX_PATH || ''
+      path: env.CODEX_OVERLEAF_CODEX_PATH || '',
+      version: selectedCodex.version || '',
+      source: selectedCodex.source || '',
+      selectedBy: codexRuntime.selectedBy || 'not-found',
+      multipleInstallations: codexRuntime.multipleInstallations === true,
+      candidates: codexRuntime.candidates.map(candidate => ({
+        path: candidate.displayPath || candidate.path || '',
+        version: candidate.version || '',
+        source: candidate.source || 'path',
+        selected: candidate.selected === true
+      }))
     },
     latex: {
       ok: availableLatex.length > 0,

package/native-host/src/providerRuntime.js

@@ -213,12 +213,24 @@ function cancelProviderTest(operationId) {
 
 function resolveProviderModels(params = {}, env = process.env, resolveBuiltInModels) {
   const state = loadProviderState(env);
-  if (state.public.activeProviderId === 'builtin') {
-    return resolveBuiltInModels(params, env);
+  const selection = params.providerSelection;
+  const requestedProviderId = selection?.providerId || state.public.activeProviderId || 'builtin';
+  if (requestedProviderId === 'builtin') {
+    const result = resolveBuiltInModels(params, env);
+    const attachProvider = value => ({
+      ...(value || {}),
+      providerId: 'builtin',
+      providerRevision: 0,
+      providerName: 'Built-in Codex'
+    });
+    return result && typeof result.then === 'function' ? result.then(attachProvider) : attachProvider(result);
   }
-  const profile = state.public.profiles.find(item => item.id === state.public.activeProviderId);
+  const profile = state.public.profiles.find(item => item.id === requestedProviderId);
   if (!profile) {
-    throw providerError('provider_not_found', 'The active provider no longer exists.');
+    throw providerError('provider_not_found', 'The selected provider no longer exists.');
+  }
+  if (selection?.providerId && Number(selection.providerRevision) !== profile.revision) {
+    throw providerError('provider_revision_conflict', 'The selected provider changed. Refresh its model list and retry.');
   }
   return {
     providerId: profile.id,
@@ -245,10 +257,8 @@ function resolveRunProvider(params = {}, env = process.env) {
   const state = loadProviderState(env);
   const selection = params.providerSelection;
   const activeProviderId = state.public.activeProviderId || 'builtin';
-  if (selection?.providerId && selection.providerId !== activeProviderId) {
-    throw providerError('provider_revision_conflict', 'The active provider changed in another tab. Refresh and retry.');
-  }
-  if (activeProviderId === 'builtin') {
+  const requestedProviderId = selection?.providerId || activeProviderId;
+  if (requestedProviderId === 'builtin') {
     return {
       modelId: params.model || '',
       reasoningEffort: params.reasoningEffort || '',
@@ -256,15 +266,15 @@ function resolveRunProvider(params = {}, env = process.env) {
       providerSelection: { providerId: 'builtin', providerRevision: 0 }
     };
   }
-  const profile = state.public.profiles.find(item => item.id === activeProviderId);
+  const profile = state.public.profiles.find(item => item.id === requestedProviderId);
   if (!profile) {
-    throw providerError('provider_not_found', 'The active provider no longer exists.');
+    throw providerError('provider_not_found', 'The selected provider no longer exists.');
   }
   if (!selection?.providerId) {
     throw providerError('provider_selection_unavailable', 'The active provider has not been confirmed by this Overleaf tab. Wait for Provider settings to load and retry.');
   }
   if (Number(selection.providerRevision) !== profile.revision) {
-    throw providerError('provider_revision_conflict', 'The active provider changed in another tab. Refresh and retry.');
+    throw providerError('provider_revision_conflict', 'The selected provider changed. Refresh its model list and retry.');
   }
   const endpointHost = getEndpointHost(profile.baseUrl);
   if (profile.endpointDisclosureHost !== endpointHost || profile.endpointDisclosureBaseUrl !== profile.baseUrl) {
@@ -302,7 +312,9 @@ function resolveRunProvider(params = {}, env = process.env) {
       reasoningEffort,
       upstreamResponseMode: validDiagnostic ? diagnostic.upstreamResponseMode : ''
     }),
-    providerSelection: { providerId: profile.id, providerRevision: profile.revision }
+    providerSelection: { providerId: profile.id, providerRevision: profile.revision },
+    providerName: profile.name,
+    providerEndpointHost: endpointHost
   };
 }
 
@@ -315,9 +327,10 @@ async function resolveRunProviderForRun(params = {}, env = process.env, options
     }
   }
   const state = loadProviderState(env);
-  const profile = state.public.profiles.find(item => item.id === state.public.activeProviderId);
+  const requestedProviderId = params.providerSelection?.providerId || state.public.activeProviderId || 'builtin';
+  const profile = state.public.profiles.find(item => item.id === requestedProviderId);
   if (!profile) {
-    throw providerError('provider_not_found', 'The active provider no longer exists.');
+    throw providerError('provider_not_found', 'The selected provider no longer exists.');
   }
   const modelId = String(params.model || profile.defaultModelId).trim();
   options.emit?.({

package/native-host/src/taskRunnerRuntime.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { buildCodexRuntimeEvent } = require('./codexRuntimeIdentity');
+
 const { spawn } = require('node:child_process');
 const crypto = require('node:crypto');
 const { buildOperationSummary, splitDeletePlan } = require('../../extension/src/shared/summary');
@@ -157,6 +159,10 @@ async function handleCodexRun(request, env, emit) {
       'Codex CLI was not found. Install Codex or make sure the `codex` command is available in your login shell.'
     );
   }
+  const codexRuntimeEvent = buildCodexRuntimeEvent(env);
+  if (codexRuntimeEvent && typeof emit === 'function') {
+    emit(codexRuntimeEvent);
+  }
 
   const projectKey = resolveProjectKey(params);
   const lockToken = acquireProjectLock(projectKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-overleaf-link",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Cross-platform Chrome bridge that connects Codex to the active Overleaf project.",
   "license": "MIT",
   "type": "commonjs",