codex-overleaf-link 2.5.0 → 2.6.0

package/extension/src/shared/sharedSessionBridge.js

@@ -1,7 +1,7 @@
 (function (root, factory) {
-  if (typeof module === 'object' && module.exports) module.exports = factory();
-  else root.CodexOverleafModuleRegistry.define('SharedSessionBridge', [], factory);
-})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./sharedSessionTransfer'));
+  else root.CodexOverleafModuleRegistry.define('SharedSessionBridge', ['SharedSessionTransfer'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : this, function (Transfer) {
   'use strict';
   const MESSAGE = 'codex-overleaf/shared-sessions-v1';
   const LOCK_PORT = 'codex-overleaf/shared-session-lock-v1';
@@ -34,7 +34,7 @@
     }
     function assertScope(value) { capture(value.projectId, value.accountScopeId); }
     const cacheKey = (value, id) => value.accountScopeId + ':' + id;
-    const lockKey = (kind, value) => kind === 'preferences' ? 'preferences' : 'state:' + value.accountScopeId;
+    const lockKey = (kind, value) => kind === 'review' ? 'review:' + JSON.stringify([value.accountScopeId, value.projectId, value.runId]) : kind === 'preferences' ? 'preferences' : 'state:' + value.accountScopeId;
     async function request(method, value, args = {}) {
       assertScope(value);
       const lock = heldLocks.get(lockKey('state', value));
@@ -51,23 +51,24 @@
 
     // Live ports own the locks. Worker/page termination releases them without
     // allowing a stale client to silently fall back to an origin-local lock.
-    async function acquire(kind, value, work) {
+    async function acquire(kind, value, work, onLost) {
       assertScope(value);
       const key = lockKey(kind, value), port = chromeApi.runtime.connect({ name: LOCK_PORT });
       let timer, heartbeat, released = false, lock = null, rejectGrant;
       const granted = new Promise((resolve, reject) => {
         rejectGrant = reject;
         port.onMessage.addListener(message => {
+          if (message?.type === 'busy') { reject(failure('review_busy', 'Another page is reviewing this run. Wait for it to finish.')); return; }
           if (message?.type !== 'granted' || lock || released) return;
           clearTimeout(timer);
-          lock = { token: message.token, lost: false };
+          lock = { token: message.token, deadlineAt: message.deadlineAt, lost: false };
           heldLocks.set(key, lock);
           resolve();
         });
         port.onDisconnect.addListener(() => {
           // Read lastError to consume the runtime's disconnected-port warning.
           void chromeApi.runtime.lastError;
-          if (lock) lock.lost = true;
+          if (lock) { lock.lost = true; if (!released) onLost?.(lock.token); }
           if (!released) reject(failure('storage_lock_lost', 'The shared history lock disconnected.'));
         });
         timer = environment.setTimeout(() => reject(failure('storage_lock_timeout',
@@ -84,12 +85,27 @@
         port.postMessage({ type: 'acquire', kind, scope: value });
         await granted;
         assertScope(value);
-        const result = await work();
+        const assertOwner = () => { assertScope(value); if (lock.lost) throw failure('storage_lock_lost', 'The shared review owner disconnected.'); };
+        assertOwner.token = lock.token;
+        assertOwner.markDispatched = async () => {
+          assertOwner();
+          const lease = await request('review-dispatched', value, { runId: value.runId, reviewToken: lock.token });
+          assertOwner(); assertOwner.deadlineAt = lease.deadlineAt; return lease.deadlineAt;
+        };
+        const result = await work(assertOwner);
         assertScope(value);
         if (lock.lost) throw failure('storage_lock_lost', 'The shared history lock was lost before completion.');
         return result;
       } finally {
         released = true;
+        if (kind === 'review' && lock && !lock.lost) {
+          await new Promise(resolve => {
+            const done = message => { if (message?.type === 'released') { port.onMessage.removeListener(done); environment.clearTimeout(releaseTimer); resolve(); } };
+            const releaseTimer = environment.setTimeout(resolve, 2000);
+            port.onMessage.addListener(done);
+            try { port.postMessage({ type: 'release-review', token: lock.token }); } catch (_) { resolve(); }
+          });
+        }
         environment.clearTimeout(timer);
         environment.clearInterval(heartbeat);
         if (heldLocks.get(key) === lock) heldLocks.delete(key);
@@ -144,7 +160,9 @@
       Object.defineProperty(record, BASE, { value: base, enumerable: true });
       return record;
     }
-    async function list(projectId = '', adopt = true) {
+    // List reads keep a per-record merge base without changing the visible view's
+    // baseline. Hydration explicitly adopts; passive refresh adopts after apply.
+    async function list(projectId = '', adopt = false) {
       const value = capture(projectId);
       await migrate(value);
       const result = []; let after = '';
@@ -169,31 +187,97 @@
       return Boolean(base && (session.updatedAt !== base.updatedAt || session.task !== base.task));
     }
     function wasStored(id) { return baselines.has(cacheKey(capture(), id)); }
+    function acknowledgeReviewBaseline(base, record, receipt, runIds) {
+      if (!base || !receipt) return base;
+      // Only this caller's acknowledged review fields have been submitted.
+      // The envelope base still describes its own view, never the latest read.
+      return { ...base, runs: (base.runs || []).map(run => {
+        const proposed = record.runs?.find(item => item.id === run.id);
+        const saved = receipt.runs?.find(item => item.id === run.id);
+        return runIds.includes(run.id) && proposed && saved
+          && legacy.reviewStateSnapshot(proposed) === legacy.reviewStateSnapshot(saved)
+          ? legacy.copyRunReviewState(run, proposed) : run;
+      }) };
+    }
     async function put(records, options = {}) {
       if (!records.length) return [];
       const value = capture(records[0].projectId, records[0].accountScopeId);
       if (records.some(record => record.projectId !== value.projectId || record.accountScopeId !== value.accountScopeId))
         throw failure('shared_store_scope_mismatch', 'A session batch must belong to one account and project.');
       return withWrite(value, async () => {
-        const entries = records.map(record => ({
-          record: clean(record),
-          base: record[BASE] || baselines.get(cacheKey(value, record.id)) || null
-        }));
-        const written = await request('put', value, { entries, reviewRunIds: options.reviewRunIds || [] });
+        const entries = records.map(record => {
+          let base = record[BASE] || baselines.get(cacheKey(value, record.id)) || null;
+          const receipt = options.reviewReceipts?.find(saved => saved.id === record.id
+            && saved.projectId === record.projectId && saved.accountScopeId === record.accountScopeId);
+          base = acknowledgeReviewBaseline(base, record, receipt, options.reviewRunIds || []);
+          return { record: clean(record), base };
+        });
+        const transfer = await Transfer.encode(entries);
+        const written = await request(transfer.method, value, { ...transfer.payload, reviewRunIds: options.reviewRunIds || [] });
         // Keep the caller's submitted view as its merge baseline. A merged
         // remote change has not necessarily been applied to the visible UI.
-        for (const entry of entries) baselines.set(cacheKey(value, entry.record.id), clean(entry.record));
+        if (options.adopt !== false)
+          for (const entry of entries) baselines.set(cacheKey(value, entry.record.id), clean(entry.record));
         return written;
       });
     }
-    async function get(id) {
+    async function get(id, options = {}) {
       const value = capture();
       await migrate(value);
       const record = await request('get', value, { id });
-      return tag(record, value, !heldLocks.has(lockKey('state', value)));
+      return tag(record, value, options.adopt !== false && !heldLocks.has(lockKey('state', value)));
     }
-    async function erase(method, projectId = '', id) {
-      const value = capture(projectId);
+    async function putSessionReviewState(record, runIds) {
+      const value = capture(record.projectId, record.accountScopeId);
+      const ids = new Set(runIds);
+      const assertOwners = () => {
+        assertScope(value);
+        for (const runId of ids) {
+          const owner = heldLocks.get(lockKey('review', { ...value, runId }));
+          if (!owner || owner.lost) throw failure('storage_lock_lost', 'The shared review owner disconnected.');
+        }
+      };
+      assertOwners();
+      return withWrite(value, async () => {
+        assertOwners();
+        const latest = await request('get', value, { id: record.id });
+        if (!latest) throw failure('shared_session_deleted', 'The session no longer exists.');
+        if (latest.projectId !== value.projectId || latest.accountScopeId !== value.accountScopeId)
+          throw failure('shared_store_scope_mismatch', 'The session does not belong to the captured account and project.');
+        const proposed = new Map((record.runs || []).map(run => [run.id, run]));
+        const identity = run => JSON.stringify(['id', 'runProjectId', 'runAccountScopeId', 'startedAt', 'nativeEventSeq',
+          'codexThreadId', 'codexTurnId', 'executionSnapshot', 'forkSnapshot'].map(key => run[key] ?? null));
+        for (const id of ids) {
+          const current = latest.runs?.find(run => run.id === id), incoming = proposed.get(id);
+          if (!current || !incoming || incoming.runProjectId !== value.projectId
+            || (incoming.runAccountScopeId && incoming.runAccountScopeId !== value.accountScopeId)
+            || identity(current) !== identity(incoming))
+            throw failure('review_context_changed', 'The shared review run is no longer available in its original scope.');
+        }
+        const next = { ...clean(latest), runs: latest.runs.map(run => {
+          if (!ids.has(run.id) || run.undoStatus === 'applied' || ['accepted', 'rejected'].includes(run.trackedChangeStatus)) return run;
+          return legacy.copyRunReviewState(run, proposed.get(run.id));
+        }) };
+        const transfer = await Transfer.encode([{ record: next, base: clean(latest) }]);
+        assertOwners();
+        await request(transfer.method, value, { ...transfer.payload, reviewRunIds: [...ids] });
+        const saved = await request('get', value, { id: record.id });
+        assertOwners();
+        if (!saved || saved.projectId !== value.projectId || saved.accountScopeId !== value.accountScopeId
+          || [...ids].some(id => {
+            const run = saved.runs?.find(run => run.id === id);
+            return !run || identity(run) !== identity(proposed.get(id))
+              || legacy.reviewStateSnapshot(run) !== legacy.reviewStateSnapshot(proposed.get(id));
+          })) throw failure('review_state_not_persisted', 'The review outcome was not durably saved. Check Overleaf before retrying.');
+        // A later envelope retry must also recognize the review already saved,
+        // without adopting any peer envelope fields from this readback.
+        const key = cacheKey(value, record.id), base = baselines.get(key);
+        if (base) baselines.set(key, acknowledgeReviewBaseline(base, record, saved, [...ids]));
+        return saved;
+      });
+    }
+    async function erase(method, projectId = '', id, accountScopeId) {
+      const value = capture(projectId, accountScopeId);
       return withWrite(value, () => request(method, value, { id }));
     }
     function decorate(api) {
@@ -211,7 +295,7 @@
         return record;
       });
       route('getAllSessions', () => list());
-      route('getRecord', (store, id) => store === 'sessions' ? get(id) : api.getRecord(store, id));
+      route('getRecord', (store, id, options) => store === 'sessions' ? get(id, options) : api.getRecord(store, id));
       route('getAllByIndex', async (store, index, value) => {
         if (store !== 'sessions') return api.getAllByIndex(store, index, value);
         const records = await list(index === 'projectId' ? value : '');
@@ -219,14 +303,15 @@
       });
       route('claimSessionsForAccount', async (projectId, accountScopeId, deleted = []) => {
         capture(projectId, accountScopeId);
-        return (await list(projectId)).filter(record => !deleted.includes(record.id));
+        return (await list(projectId, true)).filter(record => !deleted.includes(record.id));
       });
-      route('putRecord', async (store, record) =>
-        store === 'sessions' ? (await put([record]))[0] : api.putRecord(store, record));
+      route('putRecord', async (store, record, options) =>
+        store === 'sessions' ? (await put([record], options))[0] : api.putRecord(store, record));
       route('putRecords', (store, records, options) =>
         store === 'sessions' ? put(records, options) : api.putRecords(store, records));
-      route('deleteRecord', (store, id) =>
-        store === 'sessions' ? erase('delete', '', id) : api.deleteRecord(store, id));
+      route('deleteRecord', (store, id, expectedScope) =>
+        store === 'sessions' ? erase('delete', expectedScope?.projectId || '', id, expectedScope?.accountScopeId)
+          : api.deleteRecord(store, id));
       route('deleteByIndex', async (store, index, value) => {
         if (store !== 'sessions') return api.deleteByIndex(store, index, value);
         if (index === 'projectId') return erase('clear-project', value);
@@ -243,7 +328,7 @@
         for (const record of await api.getAllSessions()) {
           if (record.accountScopeId === value.accountScopeId) await api.deleteRecord('sessions', record.id);
         }
-        for (const store of Object.keys(api.STORES)) if (store !== 'sessions') await api.clearStore(store);
+        await api.clearAuxiliaryStores();
         baselines.clear();
       });
       route('listRecentProjectsAcrossAccount', async options => {
@@ -253,11 +338,17 @@
       });
       Object.assign(wrapped, {
         sharedSessionsEnabled: enabled,
+        withSharedReviewLock: async (input, work) => {
+          const value = { ...capture(input.projectId, input.accountScopeId), runId: input.runId };
+          return acquire('review', value, work, input.onLost);
+        },
+        hasSharedReviewOwner: input => request('review-owner', capture(input.projectId, input.accountScopeId), { runId: input.runId }),
         withSharedLock: withLock,
         readSharedProjectSnapshot: projectId => list(projectId, false),
         adoptSharedSessionBaseline: adopt,
         hasUnpersistedSharedSession: hasLocalChanges,
-        wasSharedSessionStored: wasStored
+        wasSharedSessionStored: wasStored,
+        putSessionReviewState
       });
       return wrapped;
     }

package/extension/src/shared/sharedSessionTransfer.js

@@ -0,0 +1,140 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('SharedSessionTransfer', [], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function () {
+  'use strict';
+  const MAX_WIRE_BYTES = 24 * 1024 * 1024;
+  // The old UTF-16 estimate admitted up to 3 UTF-8 bytes per code unit.
+  // Retain that finite Unicode window without enlarging ordinary ASCII writes.
+  const MAX_RECORD_BYTES = MAX_WIRE_BYTES * 3 / 2;
+  const MAX_RESPONSE_BYTES = MAX_RECORD_BYTES;
+  const MAX_DECODED_BYTES = 2 * MAX_RECORD_BYTES + 64 * 1024;
+  const error = (code, message) => Object.assign(new Error(message), { code });
+  const tooLarge = () => error('shared_session_too_large', 'The session batch exceeds the bounded shared storage transfer limit.');
+  const invalid = () => error('shared_session_transfer_invalid', 'The shared history transfer is invalid or incomplete.');
+  const byteLength = text => new TextEncoder().encode(text).byteLength;
+
+  function serialize(value, limit) {
+    // Count a lower bound during serialization, before a large aggregate string
+    // can be produced. The final UTF-8 check also includes commas and escaping.
+    let lowerBound = 0;
+    const text = JSON.stringify(value, function (key, item) {
+      if (key && !Array.isArray(this)) lowerBound += byteLength(JSON.stringify(key)) + 1;
+      if (typeof item === 'string') {
+        if (item.length > limit) throw tooLarge();
+        lowerBound += byteLength(JSON.stringify(item));
+      } else if (item === null) lowerBound += 4;
+      else if (typeof item === 'number') lowerBound += Number.isFinite(item) ? String(item).length : 4;
+      else if (typeof item === 'boolean') lowerBound += String(item).length;
+      else if (item && typeof item === 'object') lowerBound += 2;
+      if (lowerBound > limit) throw tooLarge();
+      return item;
+    });
+    if (typeof text !== 'string') throw invalid();
+    const bytes = byteLength(text);
+    if (bytes > limit) throw tooLarge();
+    return { text, bytes };
+  }
+
+  function validateRecord(record) {
+    const value = serialize(record, MAX_RECORD_BYTES);
+    if (value.bytes > MAX_WIRE_BYTES && value.text.length * 2 > MAX_WIRE_BYTES) throw tooLarge();
+  }
+
+  function validateResponse(records) { serialize(records, MAX_RESPONSE_BYTES); }
+
+  function validateEntries(entries) {
+    if (!Array.isArray(entries)) throw invalid();
+    for (const entry of entries) {
+      if (!entry || !entry.record || typeof entry.record !== 'object' || Array.isArray(entry.record)) throw invalid();
+      validateRecord(entry.record);
+      if (entry.base != null) {
+        if (typeof entry.base !== 'object' || Array.isArray(entry.base)) throw invalid();
+        // A previously stored merged baseline may be larger than new records;
+        // allow a bounded old base so a smaller candidate can repair it.
+        serialize(entry.base, MAX_DECODED_BYTES);
+      }
+    }
+  }
+
+  async function readLimited(stream, limit) {
+    const reader = stream.getReader(), chunks = [];
+    let length = 0;
+    try {
+      while (true) {
+        const result = await reader.read();
+        if (result.done) break;
+        length += result.value.byteLength;
+        if (length > limit) { await reader.cancel().catch(() => {}); throw tooLarge(); }
+        chunks.push(result.value);
+      }
+    } finally { reader.releaseLock(); }
+    const output = new Uint8Array(length); let offset = 0;
+    for (const chunk of chunks) { output.set(chunk, offset); offset += chunk.byteLength; }
+    return output;
+  }
+
+  function toBase64(bytes) {
+    let text = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(text);
+  }
+  function fromBase64(value) {
+    if (typeof value !== 'string' || !value.length || value.length % 4
+      || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw invalid();
+    const text = atob(value);
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i);
+    return bytes;
+  }
+
+  async function encode(entries, environment = globalThis) {
+    validateEntries(entries);
+    const raw = serialize(entries, MAX_DECODED_BYTES);
+    if (raw.bytes <= MAX_WIRE_BYTES || (raw.bytes <= MAX_RECORD_BYTES && raw.text.length * 2 <= MAX_WIRE_BYTES)) {
+      return { method: 'put', payload: { entries } };
+    }
+    if (typeof environment.CompressionStream !== 'function') {
+      throw error('shared_session_compression_unavailable',
+        'Lossless transfer compression is unavailable. History remains in memory; retry with a supported browser.');
+    }
+    const input = new Blob([raw.text]).stream();
+    const packed = await readLimited(input.pipeThrough(new environment.CompressionStream('gzip')),
+      Math.floor((MAX_WIRE_BYTES - 1024) * 3 / 4));
+    const payload = { encoding: 'gzip-base64', version: 1, decodedBytes: raw.bytes, data: toBase64(packed) };
+    serialize(payload, MAX_WIRE_BYTES);
+    // A distinct method makes an older worker reject rather than acknowledge
+    // an absent `entries` array as a successful empty write.
+    return { method: 'put-compressed', payload };
+  }
+
+  async function decode(message, environment = globalThis) {
+    if (message.method !== 'put-compressed') {
+      const entries = message.method === 'import' ? [{ record: message.record }] : message.entries || [];
+      const raw = serialize(entries, MAX_RECORD_BYTES);
+      if (raw.bytes > MAX_WIRE_BYTES && raw.text.length * 2 > MAX_WIRE_BYTES) throw tooLarge();
+      validateEntries(entries); return entries;
+    }
+    const payload = { encoding: message.encoding, version: message.version, decodedBytes: message.decodedBytes, data: message.data };
+    serialize(payload, MAX_WIRE_BYTES);
+    if (message.entries != null || payload.encoding !== 'gzip-base64' || payload.version !== 1
+      || !Number.isSafeInteger(payload.decodedBytes) || payload.decodedBytes < 1 || payload.decodedBytes > MAX_DECODED_BYTES) throw invalid();
+    if (typeof environment.DecompressionStream !== 'function') throw error('shared_session_compression_unavailable',
+      'Lossless transfer decompression is unavailable. Reload the extension and retry.');
+    let bytes;
+    try {
+      bytes = await readLimited(new Blob([fromBase64(payload.data)]).stream()
+        .pipeThrough(new environment.DecompressionStream('gzip')), MAX_DECODED_BYTES);
+    } catch (failure) {
+      if (['shared_session_too_large', 'shared_session_transfer_invalid'].includes(failure?.code)) throw failure;
+      throw invalid();
+    }
+    if (bytes.byteLength !== payload.decodedBytes) throw invalid();
+    let entries;
+    try { entries = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+    catch (_error) { throw invalid(); }
+    validateEntries(entries);
+    return entries;
+  }
+  return { MAX_WIRE_BYTES, MAX_RECORD_BYTES, MAX_RESPONSE_BYTES, MAX_DECODED_BYTES, byteLength, validateRecord, validateResponse, encode, decode };
+});

package/extension/src/shared/staleGuard.js

@@ -17,7 +17,9 @@
       if (typeof file?.path === 'string') {
         const path = normalizePath(file.path);
         if (path) {
-          lookup.set(path, normalizeText(file.content));
+          // Patch offsets refer to this exact UTF-16 string. Normalize only
+          // for comparisons, never discard the source coordinate system.
+          lookup.set(path, String(file.content ?? ''));
         }
       }
     }
@@ -40,71 +42,181 @@
       };
     }
 
-    const baseContent = baseFileLookup.get(filePath);
-    if (!baseContent || baseContent.trim().length === 0) {
-      if (typeof console !== 'undefined') {
-        console.warn('[codex-overleaf] staleGuard: base empty for', filePath, '→ skipping check');
-      }
-      return { ok: true };
-    }
+    const baseContent = normalizeText(baseFileLookup.get(filePath));
     const current = normalizeText(currentContent);
     if (current !== baseContent) {
-      if (typeof console !== 'undefined') {
-        console.warn('[codex-overleaf] staleGuard: STALE', filePath,
-          'base.length:', baseContent.length, 'current.length:', current.length,
-          'base[0..80]:', JSON.stringify(baseContent.slice(0, 80)),
-          'current[0..80]:', JSON.stringify(current.slice(0, 80)));
+      if (Array.isArray(operation.patches) && operation.patches.length) {
+        const preparedPatches = prepareOperationPatches(operation, currentContent, baseFileLookup);
+        if (preparedPatches.ok) return { ok: true, reconciled: true, strategy: 'change-envelope', preparedPatches };
       }
-      const patchRangeFreshness = checkPatchRangeFreshness(operation, current);
-      if (patchRangeFreshness) {
-        return patchRangeFreshness;
-      }
-      return {
-        ok: false,
-        code: 'stale_snapshot',
-        reasonKey: 'staleSnapshot',
-        reasonParams: { filePath },
-        reason: `${filePath} 在任务执行期间被你或协作者改过，Codex 没有覆盖它。请查看差异后重试。`
-      };
+      return staleSourceChanged(filePath);
     }
 
     return { ok: true };
   }
 
-  function checkPatchRangeFreshness(operation, currentContent) {
+  function staleSourceChanged(filePath) {
+    return {
+      ok: false,
+      code: 'stale_snapshot',
+      reasonKey: 'staleSnapshot',
+      reasonParams: { filePath },
+      reason: `${filePath} 在任务执行期间被你或协作者改过，Codex 没有覆盖它。请查看差异后重试。`
+    };
+  }
+
+  // Rebase only ranges wholly in a common prefix/suffix. All patches use the
+  // same envelope before any of them are applied to the editor.
+  function prepareOperationPatches(operation, currentContent, baseFileLookup) {
+    const path = normalizePath(operation?.path), base = baseFileLookup?.get(path);
+    const current = String(currentContent ?? '');
+    const envelope = typeof base === 'string' ? changedEnvelope(normalizeText(base), normalizeText(current)) : null;
+    const prepared = mapOperationPatches(operation, current, baseFileLookup, envelope);
+    return !prepared.ok && envelope ? staleSourceChanged(path) : prepared;
+  }
+
+  function changedEnvelope(base, current) {
+    if (base === current) return null;
+    let prefix = 0, suffix = 0;
+    while (prefix < base.length && prefix < current.length && base[prefix] === current[prefix]) prefix++;
+    while (suffix < base.length - prefix && suffix < current.length - prefix
+      && base[base.length - suffix - 1] === current[current.length - suffix - 1]) suffix++;
+    return { prefix, end: base.length - suffix, delta: current.length - base.length };
+  }
+
+  function mapEnvelopeRange(from, to, envelope, insertion = from === to) {
+    if (!envelope) return { from, to };
+    if (insertion && (from === envelope.prefix || from === envelope.end)) return null;
+    if (to <= envelope.prefix) return { from, to };
+    if (from >= envelope.end) return { from: from + envelope.delta, to: to + envelope.delta };
+    return null;
+  }
+
+  // Historical checkpoints already refer to observed applied offsets. This
+  // compatibility converter never authorizes a new forward write or rebase.
+  function prepareStoredInversePatches(operation, currentContent, baseFileLookup) {
+    return mapOperationPatches(operation, currentContent, baseFileLookup, null);
+  }
+
+  // Logical LF offsets bridge raw Native and editor coordinates. Expand split
+  // CRLF edges before dispatch; keep unchanged editor line endings intact.
+  function mapOperationPatches(operation, currentContent, baseFileLookup, envelope) {
     const patches = Array.isArray(operation?.patches) ? operation.patches : [];
-    if (!patches.length) {
-      return null;
+    const current = String(currentContent ?? '');
+    const path = normalizePath(operation?.path);
+    const base = baseFileLookup?.get(path);
+    if (!patches.length || typeof base !== 'string' || base === current) {
+      return { ok: true, patches };
+    }
+    const baseMap = lineEndingMap(base);
+    const currentMap = lineEndingMap(current);
+    if (!baseMap.removed.length && !currentMap.removed.length) {
+      if (!envelope) return { ok: true, patches };
+      const mapped = [];
+      let previousTo = 0;
+      for (const patch of patches) {
+        const from = Number(patch?.from), to = Number(patch?.to), expected = String(patch?.expected ?? '');
+        if (!Number.isInteger(from) || !Number.isInteger(to) || from < previousTo || to < from || to > base.length
+          || base.slice(from, to) !== expected) return patchMappingFailure('stale_patch');
+        previousTo = to;
+        const range = mapEnvelopeRange(from, to, envelope);
+        if (!range || current.slice(range.from, range.to) !== expected) return patchMappingFailure('stale_patch');
+        mapped.push({ ...range, expected, insert: String(patch.insert ?? '') });
+      }
+      return { ok: true, patches: mapped };
     }
 
-    const current = normalizeText(currentContent);
-    for (const rawPatch of patches) {
-      const from = Number(rawPatch?.from);
-      const to = Number(rawPatch?.to);
-      const expected = String(rawPatch?.expected ?? '');
-      if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from || to > current.length) {
-        return {
-          ok: false,
-          code: 'stale_patch_range',
-          reasonKey: 'stalePatchLocation',
-          reason: 'Codex 要修改的位置已经无法和当前 Overleaf 内容对齐，所以没有写入。请重新运行任务。'
-        };
+    const groups = [];
+    let previousTo = 0;
+    for (const patch of patches) {
+      const from = Number(patch?.from), to = Number(patch?.to);
+      if (!Number.isInteger(from) || !Number.isInteger(to) || from < previousTo || to < from || to > base.length) {
+        return patchMappingFailure('invalid_patch');
       }
-      if (current.slice(from, to) !== expected) {
-        return {
-          ok: false,
-          code: 'stale_patch_range',
-          reasonKey: 'stalePatchConflict',
-          reason: 'Codex 要修改的具体位置已经被你或协作者改过，所以没有覆盖它。请查看差异后重试。'
-        };
+      if (base.slice(from, to) !== String(patch.expected ?? '')) return patchMappingFailure('stale_patch');
+      previousTo = to;
+      // Check each insertion boundary even if CRLF expansion later merges it
+      // with an adjacent nonempty range.
+      if (!mapEnvelopeRange(baseMap.toLogical(from), baseMap.toLogical(to), envelope, from === to)) {
+        return patchMappingFailure('stale_patch');
       }
+      // Expand only a split CRLF or a new pair formed across an edit edge.
+      // Other neighbouring newlines belong to the editor and stay untouched.
+      let start = from, end = to;
+      const insert = String(patch.insert ?? '');
+      if (base[from - 1] === '\r' && (base[from] === '\n' || insert.startsWith('\n') || (!insert && base[to] === '\n'))) start -= 1;
+      if (base[to] === '\n' && (base[to - 1] === '\r' || insert.endsWith('\r') || (!insert && base[from - 1] === '\r'))) end += 1;
+      const previous = groups[groups.length - 1];
+      if (previous && start <= previous.end) {
+        previous.end = Math.max(previous.end, end);
+        previous.patches.push({ ...patch, from, to });
+      } else groups.push({ start, end, patches: [{ ...patch, from, to }] });
     }
 
-    return {
-      ok: true,
-      reconciled: true,
-      strategy: 'patch-range'
-    };
+    const mapped = [], sourceChanges = [];
+    for (const group of groups) {
+      const range = mapEnvelopeRange(baseMap.toLogical(group.start), baseMap.toLogical(group.end), envelope);
+      if (!range || range.from < 0 || range.to > currentMap.length) return patchMappingFailure('stale_patch');
+      const from = currentMap.toRaw(range.from), to = currentMap.toRaw(range.to);
+      const expected = current.slice(from, to);
+      if (normalizeText(expected) !== normalizeText(base.slice(group.start, group.end))) {
+        return patchMappingFailure('stale_patch');
+      }
+      let insert = base.slice(group.start, group.end);
+      for (const patch of group.patches.slice().sort((left, right) => right.from - left.from)) {
+        if (insert.slice(patch.from - group.start, patch.to - group.start) !== String(patch.expected ?? '')) {
+          return patchMappingFailure('stale_patch');
+        }
+        insert = insert.slice(0, patch.from - group.start) + String(patch.insert ?? '') + insert.slice(patch.to - group.start);
+      }
+      sourceChanges.push({ from: group.start, to: group.end, insert });
+      const sourceEnding = nearestLineEnding(base, group.start);
+      const editorEnding = nearestLineEnding(current, from);
+      if (sourceEnding && editorEnding && sourceEnding !== editorEnding) {
+        insert = normalizeText(insert).replace(/\n/g, editorEnding);
+      }
+      // Leave equal surrounding text out of the dispatch/Track range.
+      let prefix = 0, oldEnd = expected.length, newEnd = insert.length;
+      while (prefix < oldEnd && prefix < newEnd && expected[prefix] === insert[prefix]) prefix += 1;
+      while (oldEnd > prefix && newEnd > prefix && expected[oldEnd - 1] === insert[newEnd - 1]) { oldEnd -= 1; newEnd -= 1; }
+      mapped.push({ from: from + prefix, to: from + oldEnd, expected: expected.slice(prefix, oldEnd), insert: insert.slice(prefix, newEnd) });
+    }
+    // Preserve source coordinates for line-ending-only conversion. A rebased
+    // entry instead advances to its actual verified editor post-image.
+    let sourceContent = base;
+    for (const patch of sourceChanges.reverse()) {
+      sourceContent = sourceContent.slice(0, patch.from) + patch.insert + sourceContent.slice(patch.to);
+    }
+    return { ok: true, patches: mapped, ...(!envelope ? { sourceContent } : {}) };
+  }
+
+  function patchMappingFailure(code) {
+    return { ok: false, code, reason: 'Codex 要修改的位置已经无法和当前 Overleaf 内容对齐，所以没有写入。请重新运行任务。' };
+  }
+
+  function lineEndingMap(text) {
+    const removed = [];
+    for (let index = 0; index < text.length - 1; index += 1) {
+      if (text[index] === '\r' && text[index + 1] === '\n') removed.push(index);
+    }
+    function countBefore(offset, logical) {
+      let low = 0, high = removed.length;
+      while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (removed[middle] - (logical ? middle : 0) < offset) low = middle + 1;
+        else high = middle;
+      }
+      return low;
+    }
+    return { removed, length: text.length - removed.length,
+      toLogical: offset => offset - countBefore(offset, false),
+      toRaw: offset => offset + countBefore(offset, true) };
+  }
+
+  function nearestLineEnding(text, offset) {
+    let newline = text.indexOf('\n', offset);
+    if (newline < 0) newline = text.lastIndexOf('\n', offset - 1);
+    return newline < 0 ? '' : text[newline - 1] === '\r' ? '\r\n' : '\n';
   }
 
   function updateExpectedFileContent(baseFileLookup, filePath, content) {
@@ -112,7 +224,7 @@
     if (!baseFileLookup || !path) {
       return;
     }
-    baseFileLookup.set(path, normalizeText(content));
+    baseFileLookup.set(path, String(content ?? ''));
   }
 
   function removeExpectedFile(baseFileLookup, filePath) {
@@ -152,6 +264,8 @@
   return {
     buildBaseFileLookup,
     checkOperationFreshness,
+    prepareOperationPatches,
+    prepareStoredInversePatches,
     updateExpectedFileContent,
     removeExpectedFile,
     moveExpectedFile,