codex-overleaf-link 2.3.5 → 2.3.6

package/extension/src/page/overleafRealtimeObserver.js

@@ -2,6 +2,9 @@
   if (typeof module === 'object' && module.exports) {
     module.exports = factory(root);
   } else {
+    if (typeof root.CodexOverleafRealtimeObserver?.dispose === 'function') {
+      root.CodexOverleafRealtimeObserver.dispose();
+    }
     root.CodexOverleafRealtimeObserver = factory(root);
   }
 })(typeof globalThis !== 'undefined' ? globalThis : window, function overleafRealtimeObserverFactory(root) {
@@ -12,8 +15,34 @@
   const BASELINE_REFRESH_EVENT_TYPES = ['click', 'focusin', 'change'];
   const CHANNEL_KEY_PATTERN = /socket|websocket|channel|realtime|collab|share|ot|doc|editor|connection|event|broadcast|presence/i;
   const SENSITIVE_KEY_PATTERN = /^(content|previousContent|nextContent|text|body|raw|rawContent|source|sourceText)$/i;
+  const LIMITS = Object.freeze({ maxFileBytes: 1024 * 1024, maxEvents: 64, maxQueuedBytes: 4 * 1024 * 1024 });
+  const encoder = typeof TextEncoder === 'function' ? new TextEncoder() : null;
+  const ownedObservers = new WeakMap();
 
   function create(deps = {}) {
+    const documentRef = Object.prototype.hasOwnProperty.call(deps, 'document')
+      ? deps.document
+      : getDefaultDocument();
+    dispose(documentRef);
+    const observer = createObserver(deps);
+    if (documentRef && ['object', 'function'].includes(typeof documentRef)) {
+      ownedObservers.set(documentRef, observer);
+    }
+    return observer;
+  }
+
+  function dispose(documentRef = getDefaultDocument()) {
+    if (!documentRef || !['object', 'function'].includes(typeof documentRef)) return;
+    const previous = ownedObservers.get(documentRef);
+    if (!previous) return;
+    try {
+      previous.stop();
+    } finally {
+      ownedObservers.delete(documentRef);
+    }
+  }
+
+  function createObserver(deps = {}) {
     const pageWindow = deps.window || getDefaultWindow();
     const pageDocument = Object.prototype.hasOwnProperty.call(deps, 'document')
       ? deps.document
@@ -21,6 +50,9 @@
     const events = [];
     let activePath = '';
     let lastContent = '';
+    let baselineByteCount = 0;
+    let queuedTextBytes = 0;
+    let coalescedEventCount = 0;
     let running = false;
     let listenersAttached = false;
     let statusName = 'off';
@@ -31,6 +63,7 @@
 
     function start(_params = {}) {
       clearQueuedEvents();
+      coalescedEventCount = 0;
       channelCandidates = collectChannelCandidates(pageWindow);
       if (!canAttachDocumentListeners()) {
         running = false;
@@ -40,13 +73,15 @@
 
       running = true;
       refreshActiveBaseline();
-      attachDocumentListeners();
+      if (running) attachDocumentListeners();
       return getStatus();
     }
 
     function stop() {
       detachDocumentListeners();
       clearQueuedEvents();
+      lastContent = '';
+      baselineByteCount = 0;
       running = false;
       statusName = 'off';
       statusReason = '';
@@ -61,6 +96,9 @@
         strategy: STRATEGY_ACTIVE_EDITOR,
         activePath,
         queuedEventCount: events.length,
+        queuedTextBytes,
+        baselineByteCount,
+        coalescedEventCount,
         lastEventAt,
         lastErrorCode,
         channelCandidates: cloneChannelCandidates(channelCandidates)
@@ -72,13 +110,60 @@
     }
 
     function drainEvents() {
+      // Capture-phase input can precede the editor transaction; paste, undo
+      // and collaboration updates may dispatch no DOM input at all. The
+      // existing bounded poll samples committed text before draining.
+      if (running) handleEditorInput();
       const drained = events.slice();
       clearQueuedEvents();
-      return drained;
+      if (!drained.length) return [];
+      const otText = resolveOtText(deps, pageWindow, root);
+      if (typeof otText?.normalizeObservedTextEvent !== 'function') {
+        stopObservation('missing_ot_text');
+        return [];
+      }
+      const normalized = [];
+      for (const pending of drained) {
+        let event;
+        const { previousBytes, nextBytes, ...input } = pending;
+        try { event = otText.normalizeObservedTextEvent(input); } catch (_error) { /* fail closed below */ }
+        if (!event || event.ok !== true) {
+          stopObservation(event?.reason || 'normalize_observed_text_event_failed');
+          return [];
+        }
+        normalized.push(sanitizeObservedEvent(event));
+      }
+      return normalized;
     }
 
     function clearQueuedEvents() {
       events.length = 0;
+      queuedTextBytes = 0;
+    }
+
+    function stopObservation(reason) {
+      stop();
+      markUnavailable(reason);
+    }
+
+    function queueObservedChange(event, previousBytes, nextBytes) {
+      const tail = events[events.length - 1];
+      const merge = tail?.path === event.path && tail.nextContent === event.previousContent;
+      const pending = { ...event, previousContent: merge ? tail.previousContent : event.previousContent,
+        previousBytes: merge ? tail.previousBytes : previousBytes, nextBytes };
+      const remainingBytes = queuedTextBytes - (merge ? tail.previousBytes + tail.nextBytes : 0);
+      const noChange = pending.previousContent === pending.nextContent;
+      const nextLength = events.length - (merge ? 1 : 0) + (noChange ? 0 : 1);
+      const nextTotal = remainingBytes + (noChange ? 0 : pending.previousBytes + pending.nextBytes);
+      if (nextLength > LIMITS.maxEvents || nextTotal > LIMITS.maxQueuedBytes) {
+        stopObservation('ot_queue_limit');
+        return false;
+      }
+      if (merge) { events.pop(); coalescedEventCount += 1; }
+      if (!noChange) events.push(pending);
+      queuedTextBytes = nextTotal;
+      lastEventAt = event.observedAt;
+      return true;
     }
 
     function canAttachDocumentListeners() {
@@ -118,12 +203,14 @@
 
       const textResult = readEditorText();
       if (!textResult.ok) {
-        markUnavailable(textResult.reason);
+        if (textResult.reason === 'ot_file_limit') stopObservation(textResult.reason);
+        else markUnavailable(textResult.reason);
         return false;
       }
 
       activePath = pathResult.path;
       lastContent = textResult.text;
+      baselineByteCount = textResult.bytes;
       markObserving();
       return true;
     }
@@ -144,16 +231,19 @@
 
       const textResult = readEditorText();
       if (!textResult.ok) {
-        markUnavailable(textResult.reason);
+        if (textResult.reason === 'ot_file_limit') stopObservation(textResult.reason);
+        else markUnavailable(textResult.reason);
         return;
       }
 
       activePath = pathResult.path;
       lastContent = textResult.text;
+      baselineByteCount = textResult.bytes;
       markObserving();
     }
 
-    function handleEditorInput() {
+    function handleEditorInput(inputEvent) {
+      if (inputEvent?.target?.closest?.('#codex-overleaf-panel')) return;
       if (!running) {
         return;
       }
@@ -166,7 +256,8 @@
 
       const textResult = readEditorText();
       if (!textResult.ok) {
-        markUnavailable(textResult.reason);
+        if (textResult.reason === 'ot_file_limit') stopObservation(textResult.reason);
+        else markUnavailable(textResult.reason);
         return;
       }
 
@@ -175,6 +266,7 @@
         // Fallback for file switches that were not preceded by a selection/focus event.
         activePath = pathResult.path;
         lastContent = nextContent;
+        baselineByteCount = textResult.bytes;
         markObserving();
         return;
       }
@@ -185,34 +277,25 @@
       }
 
       const observedAt = resolveObservedAt();
-      const otText = resolveOtText(deps, pageWindow, root);
-      if (!otText || typeof otText.normalizeObservedTextEvent !== 'function') {
-        markUnavailable('missing_ot_text');
-        return;
-      }
-
-      const event = otText.normalizeObservedTextEvent({
+      const queued = queueObservedChange({
         path: activePath,
         previousContent: lastContent,
         nextContent,
         observedAt,
         source: STRATEGY_ACTIVE_EDITOR
-      });
-      if (event && event.ok === true) {
-        const queuedEvent = sanitizeObservedEvent(event);
-        events.push(queuedEvent);
-        lastEventAt = queuedEvent.observedAt || observedAt;
+      }, baselineByteCount, textResult.bytes);
+      if (queued) {
+        lastContent = nextContent;
+        baselineByteCount = textResult.bytes;
         markObserving();
-      } else {
-        lastErrorCode = event?.reason || 'normalize_observed_text_event_failed';
       }
-      lastContent = nextContent;
     }
 
     function handleActivePathUnavailable(reason) {
       if (reason === 'missing_active_path') {
         activePath = '';
         lastContent = '';
+        baselineByteCount = 0;
       }
       markUnavailable(reason);
     }
@@ -252,9 +335,17 @@
         };
       }
       try {
+        const text = deps.readActiveEditorText();
+        if (typeof text !== 'string') {
+          return { ok: false, reason: 'missing_editor_content' };
+        }
+        const bytes = text.length > LIMITS.maxFileBytes ? LIMITS.maxFileBytes + 1
+          : encoder ? encoder.encode(text).byteLength : text.length * 3;
+        if (bytes > LIMITS.maxFileBytes) return { ok: false, reason: 'ot_file_limit' };
         return {
           ok: true,
-          text: String(deps.readActiveEditorText() ?? '')
+          text,
+          bytes
         };
       } catch (_error) {
         return {
@@ -444,7 +535,6 @@
 
   function normalizePath(value) {
     return String(value || '')
-      .replace(/\s+/g, ' ')
       .replace(/\\/g, '/')
       .trim()
       .replace(/^\/+/, '');
@@ -485,7 +575,9 @@
   }
 
   return {
+    LIMITS,
     collectChannelCandidates,
-    create
+    create,
+    dispose
   };
 });

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.3.5';
+  const BUILD_TARGET_VERSION = '2.3.6';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/i18n.js

@@ -40,20 +40,31 @@
       diagnosticsPageSubtitle: 'Current file, write access, track changes',
       diagnosticsSnapshotTitle: 'Check Project Read',
       diagnosticsSnapshotSubtitle: 'Full project, assets, read source',
-      diagnosticsOtTitle: 'Check Experimental OT Mirror',
+      diagnosticsOtTitle: 'Check OT Mirror',
       diagnosticsOtSubtitle: 'Status, fresh files, fallback',
       diagnosticsExportTitle: 'Export Diagnostics',
       diagnosticsExportSubtitle: 'Redacted audit and environment bundle',
       diagnosticsExportDone: 'Diagnostics bundle exported.',
-      diagnosticsOtSummaryEnabled: 'Experimental OT is enabled. Codex will use the OT-warmed mirror only when matching files are fresh; otherwise it falls back to the normal project read path.',
-      diagnosticsOtSummaryDisabled: 'Experimental OT is disabled, so Codex is using the normal project read path.',
-      diagnosticsOtNextStep: 'If you expected OT warm reads, turn on OT and wait for the status to show Live before relying on it.',
-      experimentalOtMenuTitle: 'Experimental OT Mirror',
-      experimentalOtMenuSubtitle: 'Experimental — speeds up reading the file you are editing; Codex falls back to normal reading whenever unsure.',
-      experimentalOtConfirmTitle: 'Experimental OT Mirror',
-      experimentalOtConfirmMessage: 'Experimental: tracks the current Overleaf editor and warms the local mirror so Codex can read recent focused-file edits faster. Codex uses it only when file scope is clear and the mirror is fresh; otherwise it falls back to normal project reading.',
+      diagnosticsOtSummaryEnabled: 'OT Mirror is enabled. Codex will use the OT-warmed mirror only when matching files are fresh; otherwise it falls back to the normal project read path.',
+      diagnosticsOtSummaryDisabled: 'OT Mirror is disabled, so Codex is using the normal project read path.',
+      diagnosticsOtNextStep: 'Observer status describes warming availability. File scope and freshness are checked again before each run.',
+      experimentalOtMenuTitle: 'OT Mirror',
+      otSettingsTitle: 'Project cache',
+      contextLoadingTitle: 'Context loading',
+      runFeedbackFailedTitle: 'Needs attention',
+      runFeedbackPartialTitle: 'Partially completed',
+      runFeedbackUnconfirmedTitle: 'Write status needs review',
+      runFeedbackGeneric: 'Open the run details for the reported cause and the next step.',
+      runFeedbackUnconfirmed: 'Some changes may already be in Overleaf. Check the document before retrying.',
+      runFeedbackUnconfirmedResult: 'Not fully confirmed. Review Overleaf before retrying.',
+      runFeedbackReviewFile: 'Review {file} in Overleaf',
+      runFeedbackReviewDetails: 'Review run details',
+      runFeedbackDetailsUnavailable: 'Detailed steps are unavailable for this older run.',
+      experimentalOtMenuSubtitle: 'Warms recent edits to the active text file locally. File scope and freshness are checked before reuse.',
+      experimentalOtConfirmTitle: 'Enable OT Mirror?',
+      experimentalOtConfirmMessage: 'Observes the active text editor and warms its local mirror. This is read-only with respect to Overleaf and does not upload assets. Each run checks file scope and freshness before reuse; normal project reading remains the fallback.',
       experimentalOtConfirmEnable: 'Turn on',
-      experimentalOtEnabledToast: 'Experimental OT Mirror is on. Use @file for the cleanest warm-mirror test.',
+      experimentalOtEnabledToast: 'OT Mirror requested for this project. Its status shows whether warming is available.',
       diagnosticsSnapshotLoading: 'Checking whether the extension can read the full Overleaf project.',
       diagnosticsSnapshotErrorSummary: 'Overleaf may still be loading, or the page API did not return project files yet.',
       diagnosticsNativeLoading: 'Checking whether local Codex, Native Host, and LaTeX tools are available.',
@@ -326,18 +337,27 @@
       requireReviewingTitle: 'When enabled, Codex checks or switches Overleaf Reviewing/Track Changes before writing. Deletes still require confirmation.',
       autoCompile: 'Compile',
       autoCompileTitle: 'After Codex writes, click Overleaf Recompile and record the compile result for this task. Ask mode will not trigger it.',
-      experimentalOtWarmMirror: 'Experimental OT warm mirror',
+      experimentalOtWarmMirror: 'OT warm mirror',
       experimentalOtWarmMirrorShort: 'OT',
-      experimentalOtWarmMirrorTitle: 'Experimental read-only OT mirror warming. If unavailable, stale, or inconsistent, Codex falls back to the normal project read path.',
+      experimentalOtWarmMirrorTitle: 'Read-only local text warming. File scope and freshness are checked before reuse; normal project reading remains the fallback.',
       otStatus: 'OT status',
-      otFreshFiles: 'OT fresh files',
-      otFallback: 'Fallback',
+      otFreshFiles: 'Files with recent OT evidence',
+      otFallback: 'Read fallback',
       otStatusOff: 'Off',
-      otStatusStarting: 'Start',
-      otStatusObserving: 'Live',
-      otStatusUnavailable: 'N/A',
-      otStatusStale: 'Stale',
-      otStatusInconsistent: 'Check',
+      otStatusStarting: 'Connecting',
+      otStatusObserving: 'Observing current editor',
+      otStatusUnavailable: 'Unavailable',
+      otStatusStale: 'Warming paused; awaiting verification',
+      otStatusInconsistent: 'Needs verification',
+      otFailureBridge: 'The page connection needs to be restored. Reload the extension and Overleaf before retrying.',
+      otFailureObserver: 'The editor observer is unavailable. The next run will try normal project reading.',
+      otFailureEditor: 'The active editor could not be read. Warming is paused; the next run will try normal project reading.',
+      otFailureFileLimit: 'This file exceeds the 1 MiB warming limit. The next run will try normal project reading.',
+      otFailureQueueLimit: 'The mirror queue reached its limit. Warming is paused; the next run will try normal project reading.',
+      otFailureExpired: 'The observation is too old to reuse. The next run will try normal project reading.',
+      otFailureMirror: 'The mirror update was not fully confirmed. The next run will try normal project reading.',
+      otFailureGeneric: 'Mirror warming could not continue. The next run will try normal project reading.',
+      otFailureNextStep: 'Resolve the reported cause, then enable OT again. If the page connection is unavailable, reload the extension and Overleaf first.',
       modelSourceFallback: 'fallback',
       modelSourceDiscovered: 'discovered',
       modelSourceFailed: 'failed',
@@ -560,20 +580,31 @@
       diagnosticsPageSubtitle: '当前文件、写入能力、留痕状态',
       diagnosticsSnapshotTitle: '检查项目读取',
       diagnosticsSnapshotSubtitle: '完整项目、资源文件、读取来源',
-      diagnosticsOtTitle: '检查实验性 OT Mirror',
+      diagnosticsOtTitle: '检查 OT Mirror',
       diagnosticsOtSubtitle: '状态、新鲜文件、回退路径',
       diagnosticsExportTitle: '导出诊断信息',
       diagnosticsExportSubtitle: '已脱敏的审计和环境信息包',
       diagnosticsExportDone: '诊断信息已导出。',
-      diagnosticsOtSummaryEnabled: '实验性 OT 已开启。只有匹配文件是新鲜状态时，Codex 才会使用 OT 预热 mirror；否则会回退到常规项目读取路径。',
-      diagnosticsOtSummaryDisabled: '实验性 OT 已关闭，Codex 会使用常规项目读取路径。',
-      diagnosticsOtNextStep: '如果你希望使用 OT 预热读取，请开启 OT，并等状态显示为“实时”后再依赖它。',
-      experimentalOtMenuTitle: '实验性 OT Mirror',
-      experimentalOtMenuSubtitle: '实验性——加快读取你正在编辑的文件；拿不准时自动回退到普通读取。',
-      experimentalOtConfirmTitle: '实验性 OT Mirror',
-      experimentalOtConfirmMessage: '实验性：实时跟踪当前 Overleaf 编辑器，把改动预热到本地 mirror，让 Codex 更快读到最近的当前文件改动。只有文件范围明确且 mirror 新鲜时才会使用；否则自动回退到普通项目读取。',
+      diagnosticsOtSummaryEnabled: 'OT Mirror 已开启。只有匹配文件是新鲜状态时，Codex 才会使用 OT 预热镜像；否则会回退到常规项目读取路径。',
+      diagnosticsOtSummaryDisabled: 'OT Mirror 已关闭，Codex 会使用常规项目读取路径。',
+      diagnosticsOtNextStep: '观测状态说明预热是否可用；每次任务开始前仍会重新校验文件范围和新鲜度。',
+      experimentalOtMenuTitle: 'OT Mirror',
+      otSettingsTitle: '项目缓存',
+      contextLoadingTitle: '上下文加载',
+      runFeedbackFailedTitle: '需要处理',
+      runFeedbackPartialTitle: '部分完成',
+      runFeedbackUnconfirmedTitle: '写入状态待确认',
+      runFeedbackGeneric: '可在本轮详情中查看具体原因和后续处理方式。',
+      runFeedbackUnconfirmed: '部分改动可能已经写入 Overleaf，重试前请先检查文档。',
+      runFeedbackUnconfirmedResult: '结果尚未完全确认，请检查 Overleaf 后再决定是否重试。',
+      runFeedbackReviewFile: '在 Overleaf 检查 {file}',
+      runFeedbackReviewDetails: '查看运行步骤',
+      runFeedbackDetailsUnavailable: '这条历史记录没有可展开的详细步骤。',
+      experimentalOtMenuSubtitle: '在本地预热当前文本文件的最近改动，复用前重新校验文件范围和新鲜度。',
+      experimentalOtConfirmTitle: '开启 OT Mirror？',
+      experimentalOtConfirmMessage: '观测当前文本编辑器并预热本地镜像。此功能不会写回 Overleaf，也不负责上传资产。每次任务复用前都会校验文件范围和新鲜度，不满足条件时尝试常规项目读取。',
       experimentalOtConfirmEnable: '开启',
-      experimentalOtEnabledToast: '实验性 OT Mirror 已开启。使用 @file 可以最清楚地测试 warm mirror。',
+      experimentalOtEnabledToast: '已为当前项目请求开启 OT Mirror，可用情况见状态提示。',
       diagnosticsSnapshotLoading: '确认插件能否读取完整 Overleaf 项目。',
       diagnosticsSnapshotErrorSummary: '这通常是 Overleaf 页面还没加载完成，或者当前页面接口暂时没有返回项目文件。',
       diagnosticsNativeLoading: '确认本机 Codex、Native Host 和 LaTeX 工具是否可用。',
@@ -846,18 +877,27 @@
       requireReviewingTitle: '开启后，写入前会确认并尝试切到 Overleaf Reviewing/Track Changes；删除仍需确认。',
       autoCompile: '编译',
       autoCompileTitle: 'Codex 写入后自动点击 Overleaf Recompile，并把编译结果记录到本轮任务。只问不改时不会触发。',
-      experimentalOtWarmMirror: '实验性 OT 预热镜像',
+      experimentalOtWarmMirror: 'OT 预热镜像',
       experimentalOtWarmMirrorShort: 'OT',
-      experimentalOtWarmMirrorTitle: '实验性只读 OT 镜像预热；不可用、过期或不一致时会回退到常规项目读取。',
+      experimentalOtWarmMirrorTitle: '只读本地文本预热；复用前校验文件范围和新鲜度，常规项目读取作为回退路径。',
       otStatus: 'OT 状态',
-      otFreshFiles: 'OT 新鲜文件',
-      otFallback: '回退',
-      otStatusOff: '关',
-      otStatusStarting: '启动',
-      otStatusObserving: '实时',
-      otStatusUnavailable: '不可用',
-      otStatusStale: '过期',
-      otStatusInconsistent: '需检查',
+      otFreshFiles: '近期有 OT 校验证据的文件',
+      otFallback: '读取回退',
+      otStatusOff: '未开启',
+      otStatusStarting: '正在连接',
+      otStatusObserving: '正在观测当前编辑器',
+      otStatusUnavailable: '暂不可用',
+      otStatusStale: '预热暂缓，等待重新校验',
+      otStatusInconsistent: '需重新校验',
+      otFailureBridge: '页面连接需要恢复，请先重新加载扩展并刷新 Overleaf，再重试。',
+      otFailureObserver: '编辑器观察器暂不可用，下次任务将尝试常规项目读取。',
+      otFailureEditor: '当前编辑器内容尚不可读，预热已暂停；下次任务将尝试常规项目读取。',
+      otFailureFileLimit: '文件超过 1 MiB 预热上限，下次任务将尝试常规项目读取。',
+      otFailureQueueLimit: '镜像队列达到容量上限，预热已暂停；下次任务将尝试常规项目读取。',
+      otFailureExpired: '观测记录已过期，下次任务将尝试常规项目读取。',
+      otFailureMirror: '镜像更新尚未完整确认，下次任务将尝试常规项目读取。',
+      otFailureGeneric: '镜像预热未能继续，下次任务将尝试常规项目读取。',
+      otFailureNextStep: '处理所显示的原因后重新开启 OT；若页面连接不可用，请先重新加载扩展并刷新 Overleaf。',
       modelSourceFallback: '备用列表',
       modelSourceDiscovered: '已发现',
       modelSourceFailed: '获取失败',

package/extension/src/shared/managedUpdateProjection.js

@@ -26,7 +26,7 @@
   ]);
 
   const PHASE_TIMEOUTS = Object.freeze({
-    checking: 30 * 1000,
+    checking: 60 * 1000,
     downloading: 2 * 60 * 1000,
     applying: 90 * 1000,
     awaiting_health: 2 * 60 * 1000,

package/extension/src/shared/otText.js

@@ -279,7 +279,6 @@
 
   function normalizePath(value) {
     return String(value || '')
-      .replace(/\s+/g, ' ')
       .replace(/\\/g, '/')
       .trim()
       .replace(/^\/+/, '');

package/extension/src/shared/sessionState.js

@@ -5,12 +5,13 @@
       require('./settlementFacts'),
       require('./runInputQueue'),
       require('./lineReferences'),
-      require('./pathRedaction')
+      require('./pathRedaction'),
+      require('./sessionTitle')
     );
   } else {
     root.CodexOverleafModuleRegistry.define(
       'SessionState',
-      ['I18n', 'SettlementFacts', 'RunInputQueue', 'LineReferences', 'PathRedaction'],
+      ['I18n', 'SettlementFacts', 'RunInputQueue', 'LineReferences', 'PathRedaction', 'SessionTitle'],
       factory
     );
   }
@@ -19,7 +20,8 @@
   SettlementFacts,
   RunInputQueue,
   LineReferences,
-  PathRedaction
+  PathRedaction,
+  SessionTitle
 ) {
   'use strict';
 
@@ -402,6 +404,12 @@
       ) {
         next.title = session.title;
         next.titleSource = 'manual';
+      } else if (session.titleSource === 'auto' && patch.titleSource !== 'manual'
+        && typeof patch.title === 'string' && patch.title.trim() && session.runs?.length
+        && SessionTitle.isGeneric(sanitizeAutoTitle(patch.title))
+        && !SessionTitle.isGeneric(sanitizeAutoTitle(session.title))) {
+        next.title = session.title;
+        next.titleSource = 'auto';
       }
       return normalizeSession({
         ...next
@@ -472,12 +480,7 @@
   }
 
   function deriveSessionTitle(runs, task) {
-    const taskTitle = sanitizeAutoTitle(task);
-    if (taskTitle) {
-      return taskTitle;
-    }
-    const firstRunTask = Array.isArray(runs) && runs.length ? runs[0]?.task : '';
-    return sanitizeAutoTitle(firstRunTask);
+    return SessionTitle.derive(runs, task, { sanitize: sanitizeAssistantVisibleText, maxChars: SESSION_AUTO_TITLE_CHARS });
   }
 
   // Rename a session with the placeholder/derived-title ghost guard (mirrors
@@ -519,21 +522,14 @@
     if (titleSource === 'manual') {
       return normalizeTextField(rawTitle === LEGACY_DEFAULT_SESSION_TITLE ? '' : rawTitle, STORAGE_DEFAULT_LIMITS.sessionTitleChars);
     }
-    return sanitizeAutoTitle(rawTitle === LEGACY_DEFAULT_SESSION_TITLE ? '' : rawTitle) || derivedTitle || '';
+    const current = sanitizeAutoTitle(rawTitle === LEGACY_DEFAULT_SESSION_TITLE ? '' : rawTitle);
+    if (!current || SessionTitle.isGeneric(current)) return derivedTitle || current || '';
+    if (current.endsWith('…') && derivedTitle.startsWith(current.slice(0, -1))) return derivedTitle;
+    return current;
   }
 
   function sanitizeAutoTitle(value) {
-    const title = sanitizeAssistantVisibleText(value)
-      .replace(/@file:[^\s]+/g, ' ')
-      .replace(/@(context|compile-log)\b/g, ' ')
-      .replace(/\s+/g, ' ')
-      .trim();
-    if (!title) {
-      return '';
-    }
-    return title.length > SESSION_AUTO_TITLE_CHARS
-      ? `${title.slice(0, SESSION_AUTO_TITLE_CHARS - 1)}…`
-      : title;
+    return SessionTitle.fromPrompt(value, { sanitize: sanitizeAssistantVisibleText, maxChars: SESSION_AUTO_TITLE_CHARS });
   }
 
   function isDisplayableSession(session) {