overleaf-review 0.4.0 → 0.5.0

package/README.md

@@ -128,8 +128,10 @@ first safe push. If an upgraded repository already has unpushed edits, copy or s
 | `pull [--out <dir>]` | Read comments + tracked changes into a sidecar |
 | `fetch [--file <f>] [--dry-run]` | Write Overleaf text locally, snapshot replaced files, and save Base (read-only on Overleaf) |
 | `review start [--file <f>] [--out <dir>]` | Fetch text, save the synchronization base, and pull the review sidecar |
-| `review plan --out <plan.json> [--file <f>] [--doc <name>] [--direct] [--allow-overlap] [--unsafe-no-base]` | Create a complete binding plan without changing Overleaf |
+| `review plan --out <plan.json> [--file <f>] [--edits <blocks.json>] [--doc <name>] [--direct] [--allow-overlap] [--unsafe-no-base]` | Create a complete binding plan without changing Overleaf |
 | `review submit --plan <plan.json> [--acknowledge-ambiguous]` | Submit that plan only if all recorded preconditions still match |
+| `review consolidate --doc <path> --author <user-id> --out <preview.json> [--change <id> …]` | Preview consolidation of existing suggestions and save a full backup; no Overleaf changes |
+| `review consolidate --apply --plan <plan.json>` | Apply and verify a checked consolidation plan for your own suggestions |
 | `upload <path…> [--folder <name>]` | Upload figures / new files into Overleaf |
 | `push [--file <f>] [--doc <name>] [--direct] [--dry-run] [--plan-out <path>] [--plan <path>] [--allow-overlap] [--unsafe-no-base] [--acknowledge-ambiguous]` | Safely merge and send local edits (all changed `.tex` if no `--file`) |
 | `comment --anchor <text> --message <text> [--doc <name>] [--nth <n>] [--force]` | Add an anchored comment; recent identical retries are skipped unless forced |
@@ -155,6 +157,108 @@ overlapping Base→Local and Base→Live edits abort instead of silently undoing
 work. A proposed edit that intersects an active tracked-change range is also blocked by default and
 the relevant change ids are listed.
 
+For intentional sentence or paragraph rewrites, agents should preserve their chosen edit boundaries
+with `--edits`, rather than relying on automatic diff grouping. Edit the local file normally, then
+describe every change in a JSON manifest:
+
+```json
+{
+  "replacements": [
+    {
+      "before": "This is the old paragraph. Its explanation is unclear.",
+      "after": "This is the revised paragraph. Its explanation is clearer."
+    }
+  ]
+}
+```
+
+```sh
+overleaf-review review plan --file main.tex --edits blocks.json --out plan.json
+overleaf-review review submit --plan plan.json
+```
+
+Each block becomes one deletion and/or insertion, even across multiple sentences or LaTeX markup.
+Overleaf controls the resulting review UI; a replacement is generally two tracked ranges, not a
+guaranteed single accept/reject button. Keep typo corrections small, group a coherent rewrite,
+and keep independent decisions separate. Author attribution remains unchanged.
+
+`before` must match the saved Base exactly. Repeated text requires a 1-based `occurrence`.
+Blocks must be separated and must explain the entire local diff. The plan embeds the resolved
+blocks; it never rereads or silently reinterprets the manifest during submission. Concurrent edits
+outside blocks are preserved; any comment, pending suggestion, or concurrent edit touching a block
+stops planning rather than silently fragmenting it. Narrow the block or resolve the conflict.
+`--edits` requires `--file` and a saved base; it cannot be combined with `--direct` or `--unsafe-no-base`.
+
+Without explicit blocks, tracked suggestions group nearby word edits into phrase replacements. For example, rewriting
+“old model predicts low” as “revised model explains high” produces one deletion and one insertion,
+instead of six separate word operations. Isolated corrections stay small. Grouping bridges at most
+three unchanged words (40 characters), limits combined spans to 320 characters, and stops at detected
+sentence/clause boundaries, paragraph breaks, and LaTeX markup. This is a deterministic readability
+heuristic; it does not infer which scientific claims should be accepted together. An existing
+multiword insertion remains a single insertion.
+
+Unchanged comment anchors, tracked ranges, and edits made on Live since Base prevent grouping across
+them. Overlap checks use the full grouped footprint, and submission reproduces the same grouping.
+`--direct` retains the narrower word-level operations. Plans from before this grouping change must
+be regenerated; submitting an old plan does not silently regroup its approved operations.
+
+Planning and submission check a conservative range budget: existing tracked ranges plus proposed
+insert/delete operations must not exceed 2,000 per document. The preview shows both counts.
+Overlap transformations can alter the actual count, so this is a preflight guard rather than an
+exact prediction. Splitting a revision into batches does not remove accumulated pending ranges.
+Grouping applies to new pushes; it does not consolidate or accept suggestions already on Overleaf.
+
+### Consolidation of existing suggestions
+
+`review consolidate --doc main.tex --author <user-id> --out .overleaf/consolidation.json`
+captures the live text, all document ranges, and project comment threads. It reconstructs the text
+with that author's selected suggestions rejected, then plans a grouped revision back to the current
+proposed text. By default it considers all current suggestions by that author, including older
+fragments; repeat `--change` to select a subset. Use the author user ID from range metadata.
+
+The artifact records both text hashes, a reverse/forward reconstruction proof, projected range
+counts, and any comment or unselected-suggestion blockers. It preserves the *current pending
+proposal*, not a historical review state before older suggestions were absorbed. Consolidation
+would assign new IDs and timestamps. Counts remain projections until server transformations are
+verified. Touching comment anchors or unselected changes blocks the candidate; these are not
+automatically removed or accepted.
+
+For offline analysis, use `--snapshot <file.json>` instead of `--doc`. The snapshot must contain
+`projectId`, `docId`, `docPath`, `version`, `text`, `ranges: { changes, comments }`, and `threads`;
+the preview embeds this complete object as `backup`. A normal review sidecar alone is insufficient.
+
+Planning sends nothing. Inspect the complete plan, then apply it separately:
+
+```sh
+overleaf-review review consolidate --apply --plan .overleaf/consolidation.json
+```
+
+Only suggestions owned by the authenticated account can be reapplied. Blocked/no-reduction plans
+cannot be submitted. The command reproduces the plan from its backup and requires unchanged text,
+document version, ranges, and project threads. It journals the full snapshot before sending undo
+and reapply operations together in one update. It never accepts suggestions as a prerequisite.
+
+Verification checks the proposed text, text with selected suggestions rejected, text with all
+suggestions rejected, disappearance of old IDs, new-ID attribution, reduced range count, and
+unchanged unselected ranges, comment anchors and thread messages. New IDs and timestamps are
+expected. Any uncertain send or failed verification quarantines subsequent attempts: inspect the
+receipt and live document before manually reconciling it; there is no automatic rollback/retry.
+Reusing an already successful plan reports its receipt without sending it again.
+
+Coordinate a quiet editing window for consolidation. Overleaf has no conditional transaction
+covering text, ranges and threads, so preflight cannot prevent every last-moment collaborator race;
+readback detects discrepancies but cannot make an already-sent operation un-happen. A backup is
+recovery evidence, not a promise of automatic review-history restoration.
+
+Development check `npm run probe:consolidation-model` exercises pinned upstream range logic in
+memory without accessing an Overleaf project. The opt-in `npm run probe:review-live -- --project
+<id> --confirm-test-project` creates and retains a new scratch document in the specified test
+project, verifies consolidation and protected review state, and checks that existing documents
+were unchanged. It does not require or spoof another account. Foreign-author preservation is also
+covered by the upstream model check. Never run this probe against a manuscript project.
+
+### Push overrides and submission
+
 Use `--allow-overlap` only after inspecting those tracked changes. `--unsafe-no-base` is a deliberate
 legacy escape hatch that treats the current Live document as Base; it loses the protection against
 co-author edits made since your local file was obtained. `--direct` changes how the validated ops

package/dist/cli.js

@@ -537,6 +537,7 @@ async function validateSession(baseUrl, session2) {
     redirect: "follow"
   });
   const html = await res.text();
+  if (!res.ok) throw new Error(`Session validation failed (HTTP ${res.status}); log in again or check access.`);
   const looksLikeLogin = res.url.includes("/login") || /name="ol-page"\s+content="login"/.test(html) || html.includes('id="loginForm"');
   if (looksLikeLogin) {
     throw new Error("Session cookie is invalid or expired (got the login page).");
@@ -544,6 +545,33 @@ async function validateSession(baseUrl, session2) {
   const m = html.match(/name="ol-usersEmail"\s+content="([^"]+)"/) ?? html.match(/"email":"([^"@]+@[^"]+)"/);
   return m ? m[1] : "your Overleaf account";
 }
+function accountIdFromSettings(html) {
+  const tag = html.match(/<meta\b[^>]*\bname=["']ol-user["'][^>]*>/i)?.[0];
+  const encoded = tag?.match(/\bcontent=(?:"([^"]*)"|'([^']*)')/i);
+  if (!encoded) throw new Error("Authenticated account ID not found; refusing author-sensitive mutation.");
+  const json = (encoded[1] ?? encoded[2]).replace(/&(?:quot|apos|amp|lt|gt|#\d+|#x[0-9a-f]+);/gi, (entity) => {
+    const named = { "&quot;": '"', "&apos;": "'", "&amp;": "&", "&lt;": "<", "&gt;": ">" };
+    if (named[entity.toLowerCase()]) return named[entity.toLowerCase()];
+    const hex = entity.toLowerCase().startsWith("&#x");
+    return String.fromCodePoint(parseInt(entity.slice(hex ? 3 : 2, -1), hex ? 16 : 10));
+  });
+  const user = JSON.parse(json);
+  const id = user?.id ?? user?._id;
+  if (user?.id && user?._id && user.id !== user._id) throw new Error("Conflicting authenticated account IDs.");
+  if (typeof id !== "string" || !/^[0-9a-f]{24}$/i.test(id)) {
+    throw new Error("Invalid authenticated account ID; refusing author-sensitive mutation.");
+  }
+  return id;
+}
+async function getAuthenticatedUserId() {
+  const res = await fetch(`${config.baseUrl}/user/settings`, {
+    headers: headers(),
+    redirect: "error",
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) throw new Error(`Account verification failed (HTTP ${res.status}); refresh login.`);
+  return accountIdFromSettings(await res.text());
+}
 
 // src/lib/anchors.ts
 function offsetToLine(lines, offset) {
@@ -852,8 +880,292 @@ import {
 } from "fs";
 import { createHash as createHash3 } from "crypto";
 import { dirname as dirname5, relative as relative2, resolve as resolvePath, sep as sep2 } from "path";
+
+// src/lib/review-edits.ts
 import { diffWordsWithSpace } from "diff";
 
+// src/lib/three-way.ts
+import { diffChars } from "diff";
+function textEdits(base, target) {
+  const edits = [];
+  let basePos = 0;
+  let pending;
+  const flush = () => {
+    if (!pending) return;
+    if (pending.start !== pending.end || pending.text.length) edits.push(pending);
+    pending = void 0;
+  };
+  for (const part of diffChars(base, target)) {
+    if (!part.added && !part.removed) {
+      flush();
+      basePos += part.value.length;
+      continue;
+    }
+    pending ??= { start: basePos, end: basePos, text: "" };
+    if (part.removed) {
+      pending.end += part.value.length;
+      basePos += part.value.length;
+    } else {
+      pending.text += part.value;
+    }
+  }
+  flush();
+  return edits;
+}
+function sameEdit(a, b) {
+  return a.start === b.start && a.end === b.end && a.text === b.text;
+}
+function reverseCodePoints(text) {
+  return Array.from(text).reverse().join("");
+}
+function ambiguousEditAnchors(base, target) {
+  const forward = textEdits(base, target);
+  const reverse = textEdits(reverseCodePoints(base), reverseCodePoints(target)).map((edit) => ({
+    start: base.length - edit.end,
+    end: base.length - edit.start,
+    text: reverseCodePoints(edit.text)
+  })).sort((a, b) => a.start - b.start || a.end - b.end);
+  const ambiguities = [];
+  const count = Math.max(forward.length, reverse.length);
+  for (let index = 0; index < count; index++) {
+    const forwardEdit = forward[index] ?? reverse[index];
+    const reverseEdit = reverse[index] ?? forward[index];
+    if (sameEdit(forwardEdit, reverseEdit)) continue;
+    ambiguities.push({
+      forward: forwardEdit,
+      reverse: reverseEdit,
+      envelopeStart: Math.min(forwardEdit.start, reverseEdit.start),
+      envelopeEnd: Math.max(
+        forwardEdit.start,
+        forwardEdit.end,
+        reverseEdit.start,
+        reverseEdit.end
+      )
+    });
+  }
+  return ambiguities;
+}
+function editTouchesEnvelope(edit, start, end) {
+  if (edit.start === edit.end) return edit.start >= start && edit.start <= end;
+  return edit.start <= end && edit.end >= start;
+}
+function editsConflict(a, b) {
+  const aInsert = a.start === a.end;
+  const bInsert = b.start === b.end;
+  if (aInsert && bInsert) return a.start === b.start;
+  if (aInsert) return a.start > b.start && a.start < b.end;
+  if (bInsert) return b.start > a.start && b.start < a.end;
+  return a.start < b.end && b.start < a.end;
+}
+function mapBasePosition(position, liveEdits, includeInsertionAtPosition) {
+  let mapped = position;
+  for (const edit of liveEdits) {
+    if (edit.start === edit.end) {
+      if (edit.start < position || includeInsertionAtPosition && edit.start === position) {
+        mapped += edit.text.length;
+      }
+      continue;
+    }
+    if (edit.end <= position) mapped += edit.text.length - (edit.end - edit.start);
+  }
+  return mapped;
+}
+function applyEdits(source, edits) {
+  let result = source;
+  const ordered = edits.map((edit, index) => ({ edit, index })).sort(
+    (a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.index - a.index
+  );
+  for (const { edit } of ordered) {
+    result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+  }
+  return result;
+}
+function threeWayMerge(base, local, live) {
+  const localEdits = textEdits(base, local);
+  const liveEdits = textEdits(base, live);
+  const ambiguousAnchors = ambiguousEditAnchors(base, local);
+  const conflicts = [];
+  const alreadyAppliedLocalEdits = [];
+  const toApply = [];
+  for (const localEdit of localEdits) {
+    if (liveEdits.some((liveEdit) => sameEdit(localEdit, liveEdit))) {
+      alreadyAppliedLocalEdits.push(localEdit);
+      continue;
+    }
+    const ambiguity = ambiguousAnchors.find((candidate) => sameEdit(candidate.forward, localEdit));
+    if (ambiguity) {
+      const touching = liveEdits.filter(
+        (liveEdit) => editTouchesEnvelope(liveEdit, ambiguity.envelopeStart, ambiguity.envelopeEnd)
+      );
+      if (touching.length) {
+        for (const liveEdit of touching) {
+          conflicts.push({ local: localEdit, live: liveEdit, reason: "ambiguous-local-anchor" });
+        }
+        continue;
+      }
+    }
+    const overlapping = liveEdits.filter((liveEdit) => editsConflict(localEdit, liveEdit));
+    if (overlapping.length) {
+      for (const liveEdit of overlapping) {
+        conflicts.push({ local: localEdit, live: liveEdit, reason: "overlapping-edits" });
+      }
+      continue;
+    }
+    if (localEdit.start === localEdit.end) {
+      const point = mapBasePosition(localEdit.start, liveEdits, false);
+      toApply.push({ start: point, end: point, text: localEdit.text });
+    } else {
+      const start = mapBasePosition(localEdit.start, liveEdits, true);
+      const end = mapBasePosition(localEdit.end, liveEdits, false);
+      toApply.push({ start, end, text: localEdit.text });
+    }
+  }
+  return {
+    text: conflicts.length ? void 0 : applyEdits(live, toApply),
+    localEdits,
+    liveEdits,
+    appliedLocalEdits: toApply,
+    alreadyAppliedLocalEdits,
+    conflicts
+  };
+}
+
+// src/lib/review-edits.ts
+var MAX_GAP_CHARS = 40;
+var MAX_GAP_WORDS = 3;
+var MAX_GROUP_CHARS = 320;
+var BOUNDARY = /[.!?;:](?:["'”’\)\]]*)\s|[.!?;:]$|\r?\n\s*\r?\n|[\\$%{}&]/u;
+function buildReviewEdits(source, target, options = {}) {
+  if (options.explicitEdits) {
+    const edits2 = validateExplicitEdits(source, options.explicitEdits);
+    if (applyTextEdits(source, edits2) !== target) throw new Error("Explicit blocks do not reconstruct the intended file.");
+    for (const edit of edits2) {
+      if (options.protectedSpans?.some((span) => edit.start <= span.end && span.start <= edit.end)) {
+        throw new Error("Explicit block touches a comment, pending suggestion, or concurrent edit; narrow the block or resolve the conflict first.");
+      }
+    }
+    return edits2;
+  }
+  const edits = [];
+  let sourcePos = 0;
+  let pending;
+  const flush = () => {
+    if (pending) edits.push(pending);
+    pending = void 0;
+  };
+  for (const part of diffWordsWithSpace(source, target)) {
+    if (!part.added && !part.removed) {
+      flush();
+      sourcePos += part.value.length;
+    } else {
+      pending ??= { start: sourcePos, end: sourcePos, text: "" };
+      if (part.removed) {
+        sourcePos += part.value.length;
+        pending.end = sourcePos;
+      } else {
+        pending.text += part.value;
+      }
+    }
+  }
+  flush();
+  if (options.group === false) return edits;
+  const groups = [];
+  for (const edit of edits) {
+    const previous = groups[groups.length - 1];
+    if (!previous) {
+      groups.push({ ...edit });
+      continue;
+    }
+    const gap = source.slice(previous.end, edit.start);
+    const protectedGap = options.protectedSpans?.some(
+      (span) => span.start === span.end ? span.start >= previous.end && span.start <= edit.start : span.start < edit.start && span.end > previous.end
+    );
+    const canGroup = !protectedGap && gap.length <= MAX_GAP_CHARS && (gap.match(/\S+/gu)?.length ?? 0) <= MAX_GAP_WORDS && !BOUNDARY.test(source.slice(previous.start, edit.start)) && !BOUNDARY.test(previous.text + gap) && edit.end - previous.start <= MAX_GROUP_CHARS && previous.text.length + gap.length + edit.text.length <= MAX_GROUP_CHARS;
+    if (canGroup) {
+      previous.end = edit.end;
+      previous.text += gap + edit.text;
+    } else {
+      groups.push({ ...edit });
+    }
+  }
+  return groups;
+}
+function validateExplicitEdits(source, value) {
+  if (!Array.isArray(value) || !value.length) throw new Error("Explicit blocks must be a nonempty array.");
+  let previousEnd = -1;
+  return value.map((edit) => {
+    if (!edit || !Number.isSafeInteger(edit.start) || !Number.isSafeInteger(edit.end) || edit.start < 0 || edit.end < edit.start || edit.end > source.length || typeof edit.text !== "string" || edit.start <= previousEnd || source.slice(edit.start, edit.end) === edit.text) {
+      throw new Error("Explicit blocks must be valid, ordered, separated replacements with a text change.");
+    }
+    previousEnd = edit.end;
+    return { start: edit.start, end: edit.end, text: edit.text };
+  });
+}
+function applyTextEdits(source, edits) {
+  for (const edit of [...edits].reverse()) {
+    source = source.slice(0, edit.start) + edit.text + source.slice(edit.end);
+  }
+  return source;
+}
+function parseReplacementManifest(base, value) {
+  const manifest = value;
+  if (!Array.isArray(manifest?.replacements) || !manifest.replacements.length) {
+    throw new Error("Replacement manifest requires a nonempty replacements array.");
+  }
+  const edits = manifest.replacements.map((block) => {
+    if (!block || typeof block.before !== "string" || !block.before.length || typeof block.after !== "string" || block.occurrence !== void 0 && (!Number.isSafeInteger(block.occurrence) || block.occurrence < 1)) {
+      throw new Error("Each replacement requires nonempty before, after text, and optionally a positive occurrence.");
+    }
+    const matches = [];
+    for (let p = base.indexOf(block.before); p !== -1; p = base.indexOf(block.before, p + 1)) matches.push(p);
+    if (!matches.length || matches.length > 1 && block.occurrence === void 0) {
+      throw new Error("Replacement before text is absent or ambiguous in the saved base; specify occurrence for repeated text.");
+    }
+    const start = matches[(block.occurrence ?? 1) - 1];
+    if (start === void 0) throw new Error("Replacement occurrence is absent from the saved base.");
+    return { start, end: start + block.before.length, text: block.after };
+  }).sort((a, b) => a.start - b.start);
+  return validateExplicitEdits(base, edits);
+}
+function bindExplicitEdits(base, local, live, edits, options) {
+  const checked = validateExplicitEdits(base, edits);
+  if (applyTextEdits(base, checked) !== local) {
+    throw new Error("Replacement manifest must describe every local change exactly.");
+  }
+  const changes = textEdits(base, live);
+  const mapped = checked.map((edit) => {
+    let offset = 0;
+    for (const change of changes) {
+      if (change.start <= edit.end && edit.start <= change.end) {
+        throw new Error("A concurrent edit touches an explicit replacement block; refresh and re-plan.");
+      }
+      if (change.end < edit.start) offset += change.text.length - (change.end - change.start);
+    }
+    return { ...edit, start: edit.start + offset, end: edit.end + offset };
+  });
+  return { ...options, explicitEdits: mapped };
+}
+function reviewGroupingOptions(base, live, ranges, direct = false) {
+  const protectedSpans = [];
+  for (const range of ranges.changes ?? []) {
+    if (typeof range.op?.p === "number") {
+      protectedSpans.push({ start: range.op.p, end: range.op.p + (range.op.i?.length ?? 0) });
+    }
+  }
+  for (const range of ranges.comments ?? []) {
+    if (typeof range.op?.p === "number") {
+      protectedSpans.push({ start: range.op.p, end: range.op.p + (range.op.c?.length ?? 0) });
+    }
+  }
+  let offset = 0;
+  for (const edit of textEdits(base, live)) {
+    const start = edit.start + offset;
+    protectedSpans.push({ start, end: start + edit.text.length });
+    offset += edit.text.length - (edit.end - edit.start);
+  }
+  return { group: !direct, protectedSpans };
+}
+
 // src/lib/document-match.ts
 var AmbiguousDocumentError = class extends Error {
   constructor(identifier, matches) {
@@ -1078,152 +1390,6 @@ function mergeBaseDocuments(projectId, documents, path = BASE_STATE_PATH) {
   return state;
 }
 
-// src/lib/three-way.ts
-import { diffChars } from "diff";
-function textEdits(base, target) {
-  const edits = [];
-  let basePos = 0;
-  let pending;
-  const flush = () => {
-    if (!pending) return;
-    if (pending.start !== pending.end || pending.text.length) edits.push(pending);
-    pending = void 0;
-  };
-  for (const part of diffChars(base, target)) {
-    if (!part.added && !part.removed) {
-      flush();
-      basePos += part.value.length;
-      continue;
-    }
-    pending ??= { start: basePos, end: basePos, text: "" };
-    if (part.removed) {
-      pending.end += part.value.length;
-      basePos += part.value.length;
-    } else {
-      pending.text += part.value;
-    }
-  }
-  flush();
-  return edits;
-}
-function sameEdit(a, b) {
-  return a.start === b.start && a.end === b.end && a.text === b.text;
-}
-function reverseCodePoints(text) {
-  return Array.from(text).reverse().join("");
-}
-function ambiguousEditAnchors(base, target) {
-  const forward = textEdits(base, target);
-  const reverse = textEdits(reverseCodePoints(base), reverseCodePoints(target)).map((edit) => ({
-    start: base.length - edit.end,
-    end: base.length - edit.start,
-    text: reverseCodePoints(edit.text)
-  })).sort((a, b) => a.start - b.start || a.end - b.end);
-  const ambiguities = [];
-  const count = Math.max(forward.length, reverse.length);
-  for (let index = 0; index < count; index++) {
-    const forwardEdit = forward[index] ?? reverse[index];
-    const reverseEdit = reverse[index] ?? forward[index];
-    if (sameEdit(forwardEdit, reverseEdit)) continue;
-    ambiguities.push({
-      forward: forwardEdit,
-      reverse: reverseEdit,
-      envelopeStart: Math.min(forwardEdit.start, reverseEdit.start),
-      envelopeEnd: Math.max(
-        forwardEdit.start,
-        forwardEdit.end,
-        reverseEdit.start,
-        reverseEdit.end
-      )
-    });
-  }
-  return ambiguities;
-}
-function editTouchesEnvelope(edit, start, end) {
-  if (edit.start === edit.end) return edit.start >= start && edit.start <= end;
-  return edit.start <= end && edit.end >= start;
-}
-function editsConflict(a, b) {
-  const aInsert = a.start === a.end;
-  const bInsert = b.start === b.end;
-  if (aInsert && bInsert) return a.start === b.start;
-  if (aInsert) return a.start > b.start && a.start < b.end;
-  if (bInsert) return b.start > a.start && b.start < a.end;
-  return a.start < b.end && b.start < a.end;
-}
-function mapBasePosition(position, liveEdits, includeInsertionAtPosition) {
-  let mapped = position;
-  for (const edit of liveEdits) {
-    if (edit.start === edit.end) {
-      if (edit.start < position || includeInsertionAtPosition && edit.start === position) {
-        mapped += edit.text.length;
-      }
-      continue;
-    }
-    if (edit.end <= position) mapped += edit.text.length - (edit.end - edit.start);
-  }
-  return mapped;
-}
-function applyEdits(source, edits) {
-  let result = source;
-  const ordered = edits.map((edit, index) => ({ edit, index })).sort(
-    (a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.index - a.index
-  );
-  for (const { edit } of ordered) {
-    result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
-  }
-  return result;
-}
-function threeWayMerge(base, local, live) {
-  const localEdits = textEdits(base, local);
-  const liveEdits = textEdits(base, live);
-  const ambiguousAnchors = ambiguousEditAnchors(base, local);
-  const conflicts = [];
-  const alreadyAppliedLocalEdits = [];
-  const toApply = [];
-  for (const localEdit of localEdits) {
-    if (liveEdits.some((liveEdit) => sameEdit(localEdit, liveEdit))) {
-      alreadyAppliedLocalEdits.push(localEdit);
-      continue;
-    }
-    const ambiguity = ambiguousAnchors.find((candidate) => sameEdit(candidate.forward, localEdit));
-    if (ambiguity) {
-      const touching = liveEdits.filter(
-        (liveEdit) => editTouchesEnvelope(liveEdit, ambiguity.envelopeStart, ambiguity.envelopeEnd)
-      );
-      if (touching.length) {
-        for (const liveEdit of touching) {
-          conflicts.push({ local: localEdit, live: liveEdit, reason: "ambiguous-local-anchor" });
-        }
-        continue;
-      }
-    }
-    const overlapping = liveEdits.filter((liveEdit) => editsConflict(localEdit, liveEdit));
-    if (overlapping.length) {
-      for (const liveEdit of overlapping) {
-        conflicts.push({ local: localEdit, live: liveEdit, reason: "overlapping-edits" });
-      }
-      continue;
-    }
-    if (localEdit.start === localEdit.end) {
-      const point = mapBasePosition(localEdit.start, liveEdits, false);
-      toApply.push({ start: point, end: point, text: localEdit.text });
-    } else {
-      const start = mapBasePosition(localEdit.start, liveEdits, true);
-      const end = mapBasePosition(localEdit.end, liveEdits, false);
-      toApply.push({ start, end, text: localEdit.text });
-    }
-  }
-  return {
-    text: conflicts.length ? void 0 : applyEdits(live, toApply),
-    localEdits,
-    liveEdits,
-    appliedLocalEdits: toApply,
-    alreadyAppliedLocalEdits,
-    conflicts
-  };
-}
-
 // src/lib/tracked-overlap.ts
 function spanOverlapsEdit(start, end, edit) {
   const editIsPoint = edit.start === edit.end;
@@ -1361,7 +1527,7 @@ function snapshotRelativePath(timestamp, projectPath, root = process.cwd()) {
 }
 
 // src/commands/push.ts
-var PUSH_PLAN_SCHEMA_VERSION = 2;
+var PUSH_PLAN_SCHEMA_VERSION = 4;
 var PUSH_PLAN_KIND = "overleaf-review-push-plan";
 var PushSubmissionError = class extends Error {
   constructor(message, receiptPath, status, documents, cause) {
@@ -1392,22 +1558,22 @@ var PushPlanValidationError = class extends Error {
   }
 };
 function validatePushOptions(opts) {
+  if (opts.edits && (opts.plan || !opts.file || opts.direct || opts.unsafeNoBase)) {
+    throw new Error("--edits requires --file and a saved base, and cannot be combined with --plan, --direct or --unsafe-no-base.");
+  }
   if (opts.docName && !opts.file) {
     throw new Error("--doc requires --file; bulk pushes cannot map multiple local files to one document.");
   }
 }
-function buildOps(source, target) {
+function buildOps(source, target, options = {}) {
   const ops = [];
-  let p = 0;
-  for (const part of diffWordsWithSpace(source, target)) {
-    if (part.added) {
-      ops.push({ p, i: part.value });
-      p += part.value.length;
-    } else if (part.removed) {
-      ops.push({ p, d: part.value });
-    } else {
-      p += part.value.length;
-    }
+  let offset = 0;
+  for (const edit of buildReviewEdits(source, target, options)) {
+    const p = edit.start + offset;
+    const deleted = source.slice(edit.start, edit.end);
+    if (deleted) ops.push({ p, d: deleted });
+    if (edit.text) ops.push({ p, i: edit.text });
+    offset += edit.text.length - deleted.length;
   }
   const rebuilt = applyOps(source, ops);
   if (rebuilt !== target) {
@@ -1415,31 +1581,8 @@ function buildOps(source, target) {
   }
   return ops;
 }
-function buildOperationFootprint(source, target) {
-  const edits = [];
-  let sourcePos = 0;
-  let pending;
-  const flush = () => {
-    if (!pending) return;
-    if (pending.start !== pending.end || pending.text.length) edits.push(pending);
-    pending = void 0;
-  };
-  for (const part of diffWordsWithSpace(source, target)) {
-    if (!part.added && !part.removed) {
-      flush();
-      sourcePos += part.value.length;
-      continue;
-    }
-    pending ??= { start: sourcePos, end: sourcePos, text: "" };
-    if (part.removed) {
-      pending.end += part.value.length;
-      sourcePos += part.value.length;
-    } else {
-      pending.text += part.value;
-    }
-  }
-  flush();
-  return edits;
+function buildOperationFootprint(source, target, options = {}) {
+  return buildReviewEdits(source, target, options);
 }
 function applyOps(source, ops) {
   let text = source;
@@ -1549,6 +1692,7 @@ function serializeCommentOverlaps(overlaps) {
 }
 async function createPlan(opts = {}) {
   validatePushOptions(opts);
+  const manifest = opts.edits ? JSON.parse(readFileSync6(workspaceReadPath(opts.edits), "utf8")) : void 0;
   if (opts.plan) throw new Error("createPlan does not accept an existing plan");
   const basePath = opts.basePath ?? BASE_STATE_PATH;
   const baseState = loadBaseState(basePath);
@@ -1612,10 +1756,14 @@ async function createPlan(opts = {}) {
         continue;
       }
       const expected = merge.text;
-      const ops = buildOps(live, expected);
+      const explicitEdits = manifest ? parseReplacementManifest(base, manifest) : void 0;
+      let grouping = reviewGroupingOptions(base, live, state.ranges, opts.direct);
+      if (explicitEdits) grouping = bindExplicitEdits(base, local, live, explicitEdits, grouping);
+      const ops = buildOps(live, expected, grouping);
       if (!ops.length) continue;
-      const proposedEdits = buildOperationFootprint(live, expected);
+      const proposedEdits = buildOperationFootprint(live, expected, grouping);
       const activeTrackedRanges = serializeActiveTrackedRanges(state.ranges.changes);
+      assertTrackedRangeBudget(activeTrackedRanges.length, ops.length, Boolean(opts.direct), doc.path);
       const overlaps = serializeOverlaps(
         findTrackedChangeOverlaps(state.ranges.changes, proposedEdits)
       );
@@ -1627,6 +1775,7 @@ async function createPlan(opts = {}) {
         continue;
       }
       documents.push({
+        ...explicitEdits ? { explicitEdits } : {},
         localPath: toOverleafPath(file),
         docId: doc._id,
         docPath: doc.path,
@@ -1688,7 +1837,7 @@ function validatePushPlan(value) {
   if (!value || typeof value !== "object") throw new PushPlanValidationError("Push plan is not an object");
   const plan = value;
   if (plan.kind !== PUSH_PLAN_KIND || plan.schemaVersion !== PUSH_PLAN_SCHEMA_VERSION) {
-    throw new PushPlanValidationError("Unsupported push-plan kind or schema version");
+    throw new PushPlanValidationError("Unsupported push-plan kind or schema version; create a new plan with the current tool.");
   }
   if (typeof plan.projectId !== "string" || typeof plan.projectName !== "string" || typeof plan.createdAt !== "string" || typeof plan.direct !== "boolean" || typeof plan.unsafeNoBase !== "boolean" || typeof plan.allowOverlap !== "boolean" || !Array.isArray(plan.documents)) {
     throw new PushPlanValidationError("Push plan is missing required fields");
@@ -1696,6 +1845,7 @@ function validatePushPlan(value) {
   const seen = /* @__PURE__ */ new Set();
   const seenLocalPaths = /* @__PURE__ */ new Set();
   for (const doc of plan.documents) {
+    if (doc?.explicitEdits !== void 0 && (!Array.isArray(doc.explicitEdits) || !doc.explicitEdits.length || !doc.explicitEdits.every(validTextEdit) || plan.direct || doc.baseSource !== "saved")) throw new PushPlanValidationError("Invalid explicit replacement blocks in push plan.");
     if (!doc || typeof doc.localPath !== "string" || typeof doc.docId !== "string" || typeof doc.docPath !== "string" || doc.baseSource !== "saved" && doc.baseSource !== "live-unsafe" || !Number.isSafeInteger(doc.liveVersion) || doc.liveVersion < 0 || !Array.isArray(doc.ops) || doc.ops.length === 0 || !Array.isArray(doc.activeTrackedRanges) || !Array.isArray(doc.trackedChangeOverlaps) || !Array.isArray(doc.commentOverlaps)) {
       throw new PushPlanValidationError("Push plan contains an invalid document");
     }
@@ -1797,7 +1947,7 @@ function errorMessage(error) {
 function overleafSnapshotHash(text) {
   return createHash3("sha1").update(`blob ${text.length}\0`, "utf8").update(text, "utf8").digest("hex");
 }
-function validatePlannedIntent(planned, base, local, live) {
+function validatePlannedIntent(planned, base, local, live, grouping = reviewGroupingOptions(base, live, {})) {
   if (sha256(base) !== planned.baseHash) {
     throw new PushPlanValidationError(`Synchronization base changed for ${planned.docPath}.`);
   }
@@ -1814,14 +1964,14 @@ function validatePlannedIntent(planned, base, local, live) {
     );
   }
   const expected = merge.text;
-  if (stableJson(buildOps(live, expected)) !== stableJson(planned.ops) || sha256(expected) !== planned.expectedHash) {
+  if (stableJson(buildOps(live, expected, grouping)) !== stableJson(planned.ops) || sha256(expected) !== planned.expectedHash) {
     throw new PushPlanValidationError(
       `Operations in ${planned.docPath} do not match its saved Base\u2192Local intent.`
     );
   }
   return expected;
 }
-function validateReviewBinding(planned, state, live, expected, allowOverlap) {
+function validateReviewBinding(planned, state, live, expected, allowOverlap, grouping) {
   if (state.version !== planned.liveVersion) {
     throw new PushPlanValidationError(
       `${planned.docPath} version changed from ${planned.liveVersion} to ${state.version}; create a new plan.`
@@ -1832,7 +1982,7 @@ function validateReviewBinding(planned, state, live, expected, allowOverlap) {
       `${planned.docPath} comments or tracked ranges changed after planning; create a new plan.`
     );
   }
-  const footprint = buildOperationFootprint(live, expected);
+  const footprint = buildOperationFootprint(live, expected, grouping);
   const activeTrackedRanges = serializeActiveTrackedRanges(state.ranges.changes);
   const trackedOverlaps = serializeOverlaps(
     findTrackedChangeOverlaps(state.ranges.changes, footprint)
@@ -1889,10 +2039,22 @@ async function bindPlanDocument(plan, planned, socket, basePath) {
   const state = await joinDoc(socket, planned.docId);
   const live = state.lines.join("\n");
   const base = baseTextForPlan(plan, planned, live, basePath);
-  const expected = validatePlannedIntent(planned, base, local, live);
-  validateReviewBinding(planned, state, live, expected, plan.allowOverlap);
+  let grouping = reviewGroupingOptions(base, live, state.ranges, plan.direct);
+  if (planned.explicitEdits) grouping = bindExplicitEdits(base, local, live, planned.explicitEdits, grouping);
+  const expected = validatePlannedIntent(planned, base, local, live, grouping);
+  validateReviewBinding(planned, state, live, expected, plan.allowOverlap, grouping);
+  assertTrackedRangeBudget(state.ranges.changes?.length ?? 0, planned.ops.length, plan.direct, planned.docPath);
   return { plan: planned, state, expected };
 }
+var MAX_TRACKED_RANGES = 2e3;
+function assertTrackedRangeBudget(activeCount, operationCount, direct, docPath) {
+  if (direct || operationCount === 0) return;
+  if (activeCount + operationCount > MAX_TRACKED_RANGES) {
+    throw new PushPlanValidationError(
+      `${docPath}: ${activeCount} active tracked ranges + ${operationCount} proposed operations exceeds the conservative ${MAX_TRACKED_RANGES}-range budget. Overleaf rejects documents with too many tracked changes. Reduce the revision or arrange review of existing suggestions before submitting; smaller batches do not remove accumulated ranges.`
+    );
+  }
+}
 function verifiedTrackedIds(plan, planned, after) {
   if (plan.direct) return [];
   const actualIds = new Set((after.ranges.changes ?? []).map((change) => String(change.id)));
@@ -2268,6 +2430,11 @@ function printPlan(plan) {
       `
 ${doc.localPath} \u2192 ${doc.docPath} (v${doc.liveVersion}): ${doc.ops.length} op(s), ${ins} ins / ${del} del`
     );
+    if (!plan.direct) {
+      console.log(
+        `  Tracked-range budget: ${doc.activeTrackedRanges.length} existing + ${doc.ops.length} proposed operations / ${MAX_TRACKED_RANGES}. A phrase replacement uses one deletion and one insertion.`
+      );
+    }
     for (const op of doc.ops.slice(0, 12)) console.log(preview(op));
     if (doc.ops.length > 12) console.log(`  \u2026 and ${doc.ops.length - 12} more`);
     for (const overlap of doc.commentOverlaps) {
@@ -2468,6 +2635,330 @@ async function upload(paths, folderName) {
   }
 }
 
+// src/commands/consolidate.ts
+import { readFileSync as readFileSync9 } from "fs";
+
+// src/lib/consolidation.ts
+function checkedSnapshot(value) {
+  const snapshot = value;
+  if (!snapshot || typeof snapshot.projectId !== "string" || !snapshot.projectId || typeof snapshot.docId !== "string" || !snapshot.docId || typeof snapshot.docPath !== "string" || !Number.isSafeInteger(snapshot.version) || snapshot.version < 0 || typeof snapshot.text !== "string" || !Array.isArray(snapshot.ranges?.changes) || !Array.isArray(snapshot.ranges?.comments) || !snapshot.threads || typeof snapshot.threads !== "object" || Array.isArray(snapshot.threads)) throw new Error("Consolidation requires a full document snapshot: projectId, docId, docPath, version, text, ranges and threads.");
+  for (const range of snapshot.ranges.changes) {
+    const op = range?.op;
+    if (typeof range?.id !== "string" || !range.id || !op || !Number.isSafeInteger(op.p) || op.p < 0 || op.p > snapshot.text.length || typeof op.i === "string" === (typeof op.d === "string") || !(op.i ?? op.d)?.length || typeof op.i === "string" && snapshot.text.slice(op.p, op.p + op.i.length) !== op.i) throw new Error("Snapshot contains an invalid or stale tracked range.");
+  }
+  for (const range of snapshot.ranges.comments) {
+    const op = range?.op;
+    if (!op || !Number.isSafeInteger(op.p) || op.p < 0 || op.p > snapshot.text.length || typeof op.c !== "string" || typeof op.t !== "string" || snapshot.text.slice(op.p, op.p + op.c.length) !== op.c) throw new Error("Snapshot contains an invalid or stale comment anchor.");
+  }
+  return snapshot;
+}
+function touches(start, end, range) {
+  return start <= range.end && range.start <= end;
+}
+function protectedRanges(snapshot, selected) {
+  const ranges = [
+    ...snapshot.ranges.changes.filter((range) => !selected.has(range.id)).map((range) => ({
+      start: range.op.p,
+      end: range.op.p + (range.op.i?.length ?? 0),
+      kind: "unselected-change",
+      id: range.id
+    })),
+    ...snapshot.ranges.comments.map((range) => ({
+      start: range.op.p,
+      end: range.op.p + range.op.c.length,
+      kind: "comment",
+      id: range.op.t
+    }))
+  ];
+  return ranges.map((range) => ({ ...range, originalStart: range.start, originalEnd: range.end }));
+}
+function planConsolidation(value, authorId, requestedIds) {
+  const snapshot = structuredClone(checkedSnapshot(value));
+  if (!authorId) throw new Error("Choose the author id whose suggestions should be consolidated.");
+  const selectedIds = [...new Set(requestedIds ?? snapshot.ranges.changes.filter((range) => range.metadata?.user_id === authorId).map((range) => range.id))];
+  if (!selectedIds.length) throw new Error("No tracked changes match the selected author.");
+  const selected = new Set(selectedIds);
+  for (const id of selected) {
+    const fragments = snapshot.ranges.changes.filter((range) => range.id === id);
+    if (!fragments.length) throw new Error(`Tracked change ${id} is absent from the snapshot.`);
+    if (fragments.some((range) => range.metadata?.user_id !== authorId)) {
+      throw new Error(`Tracked change ${id} includes a different or unknown author.`);
+    }
+  }
+  const undo = buildRejectionPlan(snapshot.text, snapshot.ranges.changes, selectedIds);
+  const protectedState = protectedRanges(snapshot, selected);
+  const blockers = [];
+  for (const op of undo.operations) {
+    for (const range of protectedState) {
+      if (touches(op.p, op.p + ("d" in op ? op.d.length : 0), range)) {
+        blockers.push({ kind: range.kind, id: range.id, phase: "undo" });
+      }
+      const offset = "i" in op ? op.i.length : -op.d.length;
+      if (op.p < range.start) {
+        range.start += offset;
+        range.end += offset;
+      }
+    }
+  }
+  const grouping = { protectedSpans: protectedState };
+  const reapply = buildOps(undo.expectedText, snapshot.text, grouping);
+  const footprint = buildOperationFootprint(undo.expectedText, snapshot.text, grouping);
+  for (const edit of footprint) {
+    for (const range of protectedState) {
+      if (touches(edit.start, edit.end, range)) {
+        blockers.push({ kind: range.kind, id: range.id, phase: "reapply" });
+      }
+    }
+  }
+  if (applyOps(undo.expectedText, reapply) !== snapshot.text) {
+    throw new Error("Grouped revisions do not reconstruct the proposed text.");
+  }
+  const newRanges = [];
+  let delta = 0;
+  for (const [index, edit] of footprint.entries()) {
+    const p = edit.start + delta;
+    const deleted = undo.expectedText.slice(edit.start, edit.end);
+    if (edit.text) newRanges.push({ id: `preview-insert-${index}`, op: { p, i: edit.text } });
+    if (deleted) newRanges.push({ id: `preview-delete-${index}`, op: { p: p + edit.text.length, d: deleted } });
+    delta += edit.text.length - deleted.length;
+  }
+  const reconstructed = buildRejectionPlan(snapshot.text, newRanges, newRanges.map((range) => range.id));
+  if (reconstructed.expectedText !== undo.expectedText) {
+    throw new Error("Grouped revisions do not preserve the text beneath the selected suggestions.");
+  }
+  const beforeCount = snapshot.ranges.changes.length;
+  const projectedCount = beforeCount - undo.fragmentCount + reapply.length;
+  const uniqueBlockers = [...new Map(blockers.map((blocker) => [JSON.stringify(blocker), blocker])).values()];
+  return {
+    kind: "overleaf-review-consolidation-plan",
+    schemaVersion: 2,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status: uniqueBlockers.length ? "blocked" : projectedCount >= beforeCount ? "no-reduction" : "ready",
+    authorId,
+    selectedIds,
+    beforeCount,
+    selectedFragmentCount: undo.fragmentCount,
+    projectedCount,
+    projectedReduction: beforeCount - projectedCount,
+    blockers: uniqueBlockers,
+    binding: {
+      projectId: snapshot.projectId,
+      docId: snapshot.docId,
+      version: snapshot.version,
+      textHash: sha256(snapshot.text),
+      rangeFingerprint: fingerprintRanges(snapshot.ranges),
+      threadsHash: sha256(stableJson(snapshot.threads))
+    },
+    textProof: {
+      proposedHash: sha256(snapshot.text),
+      selectedRejectedHash: sha256(undo.expectedText),
+      selectedRejectedText: undo.expectedText,
+      forwardVerified: true,
+      reverseVerified: true
+    },
+    candidate: uniqueBlockers.length ? null : { undo: undo.operations, reapply },
+    backup: snapshot,
+    limitations: [
+      "Only review consolidate --apply accepts this artifact; review submit does not.",
+      "Preserves the current pending proposal, not an earlier historical review state.",
+      "Projected count assumes isolated ranges; server transformations need sandbox verification.",
+      "Consolidation would create new change IDs and timestamps for the selected author."
+    ]
+  };
+}
+function validateConsolidationPlan(value) {
+  const plan = value;
+  if (!plan || plan.kind !== "overleaf-review-consolidation-plan" || plan.schemaVersion !== 2 || !Array.isArray(plan.selectedIds) || !plan.selectedIds.every((id) => typeof id === "string") || typeof plan.authorId !== "string" || typeof plan.createdAt !== "string") {
+    throw new Error("Unsupported consolidation plan; create a new plan.");
+  }
+  const expected = planConsolidation(plan.backup, plan.authorId, plan.selectedIds);
+  if (stableJson({ ...plan, createdAt: "" }) !== stableJson({ ...expected, createdAt: "" })) {
+    throw new Error("Consolidation plan was altered or cannot be reproduced from its backup.");
+  }
+  if (plan.status !== "ready" || !plan.candidate || plan.projectedCount > MAX_TRACKED_RANGES) {
+    throw new Error("Consolidation is blocked, does not reduce ranges, or exceeds the range budget.");
+  }
+  rejectedText(plan.backup);
+  return plan;
+}
+function rejectedText(snapshot) {
+  return buildRejectionPlan(
+    snapshot.text,
+    snapshot.ranges.changes,
+    snapshot.ranges.changes.map((range) => range.id)
+  ).expectedText;
+}
+function assertConsolidationBinding(plan, live) {
+  checkedSnapshot(live);
+  if (live.projectId !== plan.backup.projectId || live.docId !== plan.backup.docId || live.docPath !== plan.backup.docPath || live.version !== plan.backup.version || live.text !== plan.backup.text || stableJson(live.ranges) !== stableJson(plan.backup.ranges) || stableJson(live.threads) !== stableJson(plan.backup.threads)) {
+    throw new Error("Document, version, review ranges or threads changed after consolidation planning; re-plan.");
+  }
+}
+function verifyConsolidation(plan, value, seed) {
+  const after = checkedSnapshot(value);
+  const before = plan.backup;
+  if (!/^[0-9a-f]{18}$/.test(seed) || after.projectId !== before.projectId || after.docId !== before.docId || after.docPath !== before.docPath || after.version !== before.version + 1 || after.text !== before.text) {
+    throw new Error("Consolidation text, identity or document version failed verification.");
+  }
+  const selected = new Set(plan.selectedIds);
+  if (after.ranges.changes.some((range) => selected.has(range.id))) throw new Error("Old tracked-change IDs remain after consolidation.");
+  const originalOther = before.ranges.changes.filter((range) => !selected.has(range.id));
+  const otherIds = new Set(originalOther.map((range) => range.id));
+  const actualOther = after.ranges.changes.filter((range) => otherIds.has(range.id));
+  const fresh = after.ranges.changes.filter((range) => !otherIds.has(range.id));
+  const canonical = (ranges) => stableJson(ranges.map((range) => stableJson(range)).sort());
+  if (canonical(originalOther) !== canonical(actualOther) || canonical(before.ranges.comments) !== canonical(after.ranges.comments) || stableJson(before.threads) !== stableJson(after.threads)) {
+    throw new Error("Comments, threads or unselected suggestions changed during consolidation.");
+  }
+  if (fresh.some((range) => !new RegExp(`^${seed}[0-9a-f]{6}$`).test(range.id) || range.metadata?.user_id !== plan.authorId) || after.ranges.changes.length > plan.projectedCount || after.ranges.changes.length >= plan.beforeCount) {
+    throw new Error("Consolidated range count or author attribution failed verification.");
+  }
+  const changeIds = [...new Set(fresh.map((range) => range.id))];
+  if (buildRejectionPlan(after.text, after.ranges.changes, changeIds).expectedText !== plan.textProof.selectedRejectedText || rejectedText(after) !== rejectedText(before)) {
+    throw new Error("Consolidation changed the text beneath pending suggestions.");
+  }
+  return { changeIds, rangeCount: after.ranges.changes.length };
+}
+
+// src/lib/consolidation-submit.ts
+async function submitConsolidation(value, transport) {
+  const plan = validateConsolidationPlan(value);
+  const planHash = sha256(stableJson(plan));
+  const options = { receiptsDir: transport.receiptsDir };
+  const relevant = readReceipts(transport.receiptsDir).filter((handle) => handle.receipt.operation === "consolidate" && handle.receipt.details.projectId === plan.binding.projectId && handle.receipt.details.docId === plan.binding.docId);
+  const uncertain = relevant.find((handle) => handle.receipt.status === "ambiguous" || handle.receipt.status === "in_progress");
+  if (uncertain) {
+    throw new Error(`Earlier consolidation has an uncertain outcome. Inspect and reconcile ${uncertain.path}; no automatic retry was sent.`);
+  }
+  const prior = relevant.find((handle) => handle.receipt.status === "succeeded" && handle.receipt.details.planHash === planHash);
+  if (prior) return { receiptPath: prior.path, alreadyApplied: true };
+  let receipt = beginReceipt("consolidate", {
+    projectId: plan.binding.projectId,
+    docId: plan.binding.docId,
+    docPath: plan.backup.docPath,
+    planHash,
+    plan,
+    phase: "preflight"
+  }, options);
+  let attempted = false;
+  try {
+    if (await transport.accountId() !== plan.authorId) {
+      throw new Error("Consolidation can only reapply suggestions belonging to the authenticated account.");
+    }
+    const before = await transport.snapshot();
+    assertConsolidationBinding(plan, before);
+    const seed = createTrackedChangeSeed();
+    if (before.ranges.changes.some((range) => range.id.startsWith(seed))) {
+      throw new Error("Tracked-change seed collision; create a fresh consolidation attempt.");
+    }
+    const update = {
+      doc: before.docId,
+      v: before.version,
+      op: [...plan.candidate.undo, ...plan.candidate.reapply],
+      meta: { tc: seed },
+      hash: overleafSnapshotHash(before.text)
+    };
+    receipt = updateReceipt(receipt, "in_progress", {
+      phase: "sending",
+      before,
+      seed,
+      update,
+      mutationStartedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    attempted = true;
+    await transport.send(update);
+    const after = await transport.snapshot();
+    receipt = updateReceipt(receipt, "in_progress", { phase: "verifying", after });
+    const result = verifyConsolidation(plan, after, seed);
+    receipt = updateReceipt(receipt, "succeeded", { phase: "complete", result });
+    return { receiptPath: receipt.path, alreadyApplied: false, ...result };
+  } catch (error) {
+    receipt = updateReceipt(receipt, attempted ? "ambiguous" : "failed", {
+      phase: attempted ? "outcome_unknown" : "preflight_failed",
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw new Error(`${error instanceof Error ? error.message : String(error)}. Receipt: ${receipt.path}. ` + (attempted ? "Do not retry or auto-rollback; inspect live review state and the saved backup first." : "Nothing sent."), { cause: error });
+  }
+}
+
+// src/commands/consolidate.ts
+async function readConsolidationSnapshot(opened, doc) {
+  if (String(opened.project?._id) !== config.projectId) throw new Error("Connected project identity could not be verified.");
+  const before = await joinDoc(opened.socket, doc._id);
+  const threads = await getThreads();
+  const after = await joinDoc(opened.socket, doc._id);
+  const afterThreads = await getThreads();
+  if (before.version !== after.version || before.lines.join("\n") !== after.lines.join("\n") || stableJson(before.ranges) !== stableJson(after.ranges) || stableJson(threads) !== stableJson(afterThreads)) {
+    throw new Error("The document or review state changed during snapshot capture.");
+  }
+  return {
+    projectId: config.projectId,
+    docId: doc._id,
+    docPath: doc.path,
+    version: after.version,
+    text: after.lines.join("\n"),
+    ranges: { changes: after.ranges.changes ?? [], comments: after.ranges.comments ?? [] },
+    threads: afterThreads
+  };
+}
+async function consolidateApply(path) {
+  const plan = validateConsolidationPlan(JSON.parse(readFileSync9(workspaceReadPath(path), "utf8")));
+  if (config.projectId !== plan.binding.projectId) throw new Error("Consolidation plan belongs to a different project.");
+  const lock = acquireMutationLock(config.projectId);
+  let opened;
+  try {
+    opened = await openProject();
+    const project = opened;
+    const doc = project.docs.find((doc2) => doc2._id === plan.binding.docId && doc2.path === plan.backup.docPath);
+    if (!doc) throw new Error("Planned consolidation document is absent or renamed.");
+    const result = await submitConsolidation(plan, {
+      accountId: getAuthenticatedUserId,
+      snapshot: () => readConsolidationSnapshot(project, doc),
+      send: (update) => applyOtUpdateAndWait(project.socket, doc._id, update)
+    });
+    console.log(result.alreadyApplied ? "This consolidation plan was already applied; nothing resent." : `Verified consolidation: ${plan.beforeCount} \u2192 ${result.rangeCount} tracked ranges. Both text views and protected review state preserved.`);
+    console.log(`Audit receipt and backup: ${result.receiptPath}`);
+  } finally {
+    try {
+      opened?.socket.close();
+    } finally {
+      lock.release();
+    }
+  }
+}
+async function consolidatePreview(options) {
+  let snapshot;
+  if (options.snapshot) {
+    snapshot = JSON.parse(readFileSync9(workspaceReadPath(options.snapshot), "utf8"));
+  } else {
+    if (!options.doc) throw new Error("Consolidation requires --doc or --snapshot.");
+    const projectId = config.projectId;
+    const lock = acquireMutationLock(projectId);
+    let opened;
+    try {
+      opened = await openProject();
+      const doc = matchDocument(options.doc, opened.docs);
+      if (!doc) throw new Error(`Document not found: ${options.doc}`);
+      snapshot = await readConsolidationSnapshot(opened, doc);
+    } finally {
+      try {
+        opened?.socket.close();
+      } finally {
+        lock.release();
+      }
+    }
+  }
+  const plan = planConsolidation(snapshot, options.author, options.changeIds);
+  writeJsonAtomic(workspaceWritePath(options.out), plan);
+  console.log(`Consolidation dry run for ${snapshot.docPath}: ${plan.status}`);
+  console.log(`Tracked ranges: ${plan.beforeCount} \u2192 ${plan.projectedCount} projected (${plan.selectedFragmentCount} selected).`);
+  for (const blocker of plan.blockers) {
+    console.log(`  Blocked by ${blocker.kind} ${blocker.id} during ${blocker.phase}.`);
+  }
+  console.log(`Full backup and text proofs saved to ${options.out}.`);
+  console.log("Nothing sent to Overleaf. Inspect the plan before review consolidate --apply --plan <file>.");
+}
+
 // src/commands/comment.ts
 import { createHash as createHash4, randomBytes as randomBytes2 } from "crypto";
 var DEFAULT_DUPLICATE_WINDOW_MS = 5 * 60 * 1e3;
@@ -3597,6 +4088,9 @@ async function login(opts) {
   const path = saveCredentials({ baseUrl, session2: cookie });
   console.log(`
 \u2705 Logged in as ${account}. Saved to ${path} (chmod 600).`);
+  if (process.env.OVERLEAF_SESSION2 && process.env.OVERLEAF_SESSION2 !== cookie) {
+    console.warn("An OVERLEAF_SESSION2 override is still set (possibly in .env). Remove or update it to use this saved login.");
+  }
 }
 async function captureCookieViaBrowser(baseUrl) {
   let chromium;
@@ -3660,8 +4154,12 @@ function usage() {
   console.log("Safe review workflow:");
   console.log("  review start [--file <f>] [--out <dir>]   Fetch text/base, then pull review data");
   console.log("  review plan --out <plan.json> [options]   Save a complete binding push plan");
+  console.log("       --file <f> --edits <blocks.json>     Preserve explicit before/after blocks");
   console.log("  review submit --plan <plan.json>          Validate, apply, and verify that plan");
   console.log("       [--acknowledge-ambiguous]             Continue only after manual reconciliation\n");
+  console.log("  review consolidate --doc <path> --author <user-id> --out <preview.json>");
+  console.log("       [--snapshot <snapshot.json>] [--change <id> \u2026]  Plan only");
+  console.log("  review consolidate --apply --plan <plan.json>  Apply a checked consolidation\n");
   console.log("Content (replaces the git bridge):");
   console.log("  fetch [--file <f>] [--dry-run]            Overleaf text \u2192 local files + saved base");
   console.log("  upload <path\u2026> [--folder <name>]          Upload figures / new files to Overleaf\n");
@@ -3689,6 +4187,7 @@ async function pullAndReport(out, options = {}) {
 }
 function pushOptions() {
   return {
+    edits: getFlag("edits"),
     file: getFlag("file"),
     docName: getFlag("doc"),
     direct: process.argv.includes("--direct"),
@@ -3771,6 +4270,28 @@ async function main() {
         } finally {
           mutationLock.release();
         }
+      } else if (reviewCommand === "consolidate") {
+        if (process.argv.includes("--submit")) fail("Use review consolidate --apply --plan <file>.");
+        if (process.argv.includes("--apply")) {
+          const plan = getFlag("plan");
+          if (!plan || process.argv.slice(4).some((arg) => arg.startsWith("--") && !["--apply", "--plan"].includes(arg))) {
+            fail("Consolidation apply requires only --apply --plan <file>; create a new plan to change its scope.");
+          }
+          await consolidateApply(plan);
+          break;
+        }
+        if (getFlag("plan")) fail("--plan requires --apply for consolidation.");
+        const author = getFlag("author");
+        const out = getFlag("out");
+        if (!author || !out) fail("review consolidate requires --author <user-id> and --out <preview.json>");
+        const changeIds = getAll("change");
+        await consolidatePreview({
+          author,
+          out,
+          doc: getFlag("doc"),
+          snapshot: getFlag("snapshot"),
+          changeIds: changeIds.length ? changeIds : void 0
+        });
       } else if (reviewCommand === "plan") {
         const out = getFlag("out");
         if (!out) fail("review plan requires --out <plan.json>");
@@ -3784,7 +4305,7 @@ async function main() {
         });
       } else {
         usage();
-        fail("review requires start, plan, or submit");
+        fail("review requires start, plan, submit, or consolidate");
       }
       break;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overleaf-review",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The missing review layer for Overleaf's Git bridge — sync comments and tracked changes between Overleaf and your local repo.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,8 @@
     "probe:read": "tsx src/probes/01-read-ranges.ts",
     "probe:comment": "tsx src/probes/02-write-comment.ts",
     "probe:track": "tsx src/probes/03-write-track-change.ts",
+    "probe:consolidation-model": "tsx src/probes/04-consolidation-model.ts",
+    "probe:review-live": "tsx src/probes/05-review-live.ts",
     "typecheck": "tsc --noEmit",
     "test": "tsx --test test/*.test.ts",
     "check": "npm run typecheck && npm test && npm run build"