overleaf-review 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/commands/pull.ts
-import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
-import { join as join3 } from "path";
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync4 } from "fs";
+import { join as join4 } from "path";
 
 // src/config.ts
 import "dotenv/config";
@@ -33,7 +33,7 @@ function saveCredentials(creds) {
 }
 
 // src/lib/project-config.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, renameSync, unlinkSync } from "fs";
 import { join as join2 } from "path";
 var REPO_CONFIG_PATH = join2(".overleaf", "config.json");
 function loadProjectConfig() {
@@ -45,7 +45,17 @@ function loadProjectConfig() {
 }
 function saveProjectConfig(cfg) {
   mkdirSync2(".overleaf", { recursive: true });
-  writeFileSync2(REPO_CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+  const temp = `${REPO_CONFIG_PATH}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync2(temp, JSON.stringify(cfg, null, 2) + "\n", { mode: 384 });
+    renameSync(temp, REPO_CONFIG_PATH);
+  } catch (error) {
+    try {
+      unlinkSync(temp);
+    } catch {
+    }
+    throw error;
+  }
   return REPO_CONFIG_PATH;
 }
 
@@ -131,6 +141,15 @@ var OverleafSocket = class {
     const list = this.handlers.get(event) ?? [];
     list.push(handler);
     this.handlers.set(event, list);
+    return () => this.off(event, handler);
+  }
+  /** Remove a previously registered server-pushed event handler. */
+  off(event, handler) {
+    const list = this.handlers.get(event);
+    if (!list) return;
+    const next = list.filter((candidate) => candidate !== handler);
+    if (next.length) this.handlers.set(event, next);
+    else this.handlers.delete(event);
   }
   async connect(projectId) {
     const handshakeUrl = `${this.baseUrl}/socket.io/1/?projectId=${projectId}&t=${Date.now()}`;
@@ -149,8 +168,8 @@ var OverleafSocket = class {
     const wsUrl = `${this.baseUrl.replace(/^http/, "ws")}/socket.io/1/websocket/${sid}`;
     if (this.debug) console.log(`[socket] transports=${transports}; ws=${wsUrl}`);
     this.ws = new WebSocket(wsUrl, { headers: this.browserHeaders });
-    await new Promise((resolve2, reject2) => {
-      this.ws.once("open", () => resolve2());
+    await new Promise((resolve3, reject2) => {
+      this.ws.once("open", () => resolve3());
       this.ws.once("error", reject2);
       this.ws.once("unexpected-response", (_req, response) => {
         let errBody = "";
@@ -175,14 +194,14 @@ var OverleafSocket = class {
   /** Emit an event and resolve with the server's ack payload (array of args). */
   emit(name, args, timeoutMs = 15e3) {
     const id = this.ackId++;
-    return new Promise((resolve2, reject2) => {
+    return new Promise((resolve3, reject2) => {
       const timer = setTimeout(() => {
         this.pendingAcks.delete(id);
         reject2(new Error(`emit('${name}') timed out after ${timeoutMs}ms with no ack`));
       }, timeoutMs);
       this.pendingAcks.set(id, (payload) => {
         clearTimeout(timer);
-        resolve2(payload);
+        resolve3(payload);
       });
       this.send(`5:${id}+::${JSON.stringify({ name, args })}`);
     });
@@ -243,7 +262,7 @@ function collectDocs(rootFolder) {
 }
 async function openProject(opts = {}) {
   const socket = new OverleafSocket(config.baseUrl, config.cookie, { debug: opts.debug ?? false });
-  const pushed = new Promise((resolve2) => socket.on("joinProjectResponse", resolve2));
+  const pushed = new Promise((resolve3) => socket.on("joinProjectResponse", resolve3));
   await socket.connect(config.projectId);
   const first = await Promise.race([
     pushed,
@@ -266,6 +285,41 @@ async function joinDoc(socket, docId) {
   if (err) throw new Error(`joinDoc error: ${JSON.stringify(err)}`);
   return { version, lines: lines ?? [], ranges: ranges ?? {} };
 }
+async function applyOtUpdateAndWait(socket, docId, update, timeoutMs = 3e4) {
+  let timer;
+  let stopApplied = () => {
+  };
+  let stopError = () => {
+  };
+  const applied = new Promise((resolve3, reject2) => {
+    stopApplied = socket.on("otUpdateApplied", (args) => {
+      const event = args[0];
+      if (event?.doc === docId && Number.isSafeInteger(event.v) && event.v >= update.v && !Object.prototype.hasOwnProperty.call(event, "op")) {
+        resolve3();
+      }
+    });
+    stopError = socket.on("otUpdateError", (args) => {
+      const metadata = args[1];
+      if (metadata?.doc_id && metadata.doc_id !== docId) return;
+      reject2(new Error(`Overleaf failed to apply the OT update: ${JSON.stringify(args)}`));
+    });
+    timer = setTimeout(
+      () => reject2(new Error(`OT update for ${docId} was queued but not confirmed within ${timeoutMs}ms`)),
+      timeoutMs
+    );
+  });
+  void applied.catch(() => {
+  });
+  try {
+    const ack = await socket.emit("applyOtUpdate", [docId, update], timeoutMs);
+    if (ack?.[0]) throw new Error(`Overleaf rejected the OT update: ${JSON.stringify(ack[0])}`);
+    await applied;
+  } finally {
+    if (timer) clearTimeout(timer);
+    stopApplied();
+    stopError();
+  }
+}
 
 // src/lib/rest.ts
 var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
@@ -290,7 +344,111 @@ async function getThreads() {
   if (!res.ok) throw new Error(`getThreads ${res.status}: ${(await res.text()).slice(0, 200)}`);
   return res.json();
 }
-async function postThreadMessage(threadId, content, csrf) {
+var RestRequestError = class extends Error {
+  constructor(message, status, responseBody) {
+    super(message);
+    this.status = status;
+    this.responseBody = responseBody;
+    this.name = "RestRequestError";
+  }
+  status;
+  responseBody;
+};
+function threadMessages(thread) {
+  if (!thread || typeof thread !== "object") return [];
+  const messages = thread.messages;
+  return Array.isArray(messages) ? messages.filter((message) => Boolean(message && typeof message === "object")) : [];
+}
+function threadMessageId(message) {
+  const value = message?.id ?? message?._id;
+  return typeof value === "string" && value ? value : void 0;
+}
+function timestampMs(message) {
+  const raw = message.timestamp ?? message.createdAt ?? message.created_at;
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return raw < 1e11 ? raw * 1e3 : raw;
+  }
+  if (typeof raw === "string") {
+    const numeric = Number(raw);
+    if (Number.isFinite(numeric) && raw.trim()) {
+      return numeric < 1e11 ? numeric * 1e3 : numeric;
+    }
+    const parsed = Date.parse(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+function findRecentIdenticalMessage(thread, content, nowMs = Date.now(), windowMs = 5 * 60 * 1e3) {
+  const earliest = nowMs - Math.max(0, windowMs);
+  return threadMessages(thread).filter((message) => {
+    if (message.content !== content) return false;
+    const timestamp = timestampMs(message);
+    return timestamp !== void 0 && timestamp >= earliest && timestamp <= nowMs + 6e4;
+  }).sort((a, b) => (timestampMs(b) ?? 0) - (timestampMs(a) ?? 0))[0];
+}
+function findNewIdenticalMessage(beforeThread, afterThread, content, returnedMessageId) {
+  const after = threadMessages(afterThread);
+  if (returnedMessageId) {
+    return after.find(
+      (message) => threadMessageId(message) === returnedMessageId && message.content === content
+    );
+  }
+  const beforeIds = new Set(
+    threadMessages(beforeThread).map(threadMessageId).filter((id) => Boolean(id))
+  );
+  const candidates = [...after].reverse().filter((message) => {
+    if (message.content !== content) return false;
+    const id = threadMessageId(message);
+    return Boolean(id && !beforeIds.has(id));
+  });
+  return candidates.length === 1 ? candidates[0] : void 0;
+}
+function extractPostedMessageId(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const object = value;
+  for (const key of ["message_id", "messageId"]) {
+    if (typeof object[key] === "string" && object[key]) return object[key];
+  }
+  for (const key of ["message", "data"]) {
+    const nested = object[key];
+    if (nested && typeof nested === "object") {
+      const nestedId = threadMessageId(nested) ?? extractPostedMessageId(nested);
+      if (nestedId) return nestedId;
+    }
+  }
+  return threadMessageId(object);
+}
+async function observePostedThreadMessage(threadId, beforeThread, content, returnedMessageId, options = {}) {
+  const timeoutMs = Math.max(0, options.timeoutMs ?? 5e3);
+  const intervalMs = Math.max(10, options.intervalMs ?? 250);
+  const deadline = Date.now() + timeoutMs;
+  let attempts = 0;
+  let lastThread;
+  let lastError;
+  do {
+    attempts += 1;
+    try {
+      lastThread = (await getThreads())[threadId];
+      const message = findNewIdenticalMessage(
+        beforeThread,
+        lastThread,
+        content,
+        returnedMessageId
+      );
+      if (message) return { message, thread: lastThread, attempts };
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    if (Date.now() >= deadline) break;
+    await new Promise((resolve3) => setTimeout(resolve3, Math.min(intervalMs, deadline - Date.now())));
+  } while (Date.now() <= deadline);
+  return {
+    thread: lastThread,
+    attempts,
+    ...lastError ? { lastError } : {}
+  };
+}
+async function postThreadMessageDetailed(threadId, content, csrf) {
   const res = await fetch(
     `${config.baseUrl}/project/${config.projectId}/thread/${threadId}/messages`,
     {
@@ -299,10 +457,27 @@ async function postThreadMessage(threadId, content, csrf) {
       body: JSON.stringify({ content })
     }
   );
+  const rawBody = await res.text();
   if (!res.ok) {
-    throw new Error(`postThreadMessage ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    throw new RestRequestError(
+      `postThreadMessage ${res.status}: ${rawBody.slice(0, 300)}`,
+      res.status,
+      rawBody.slice(0, 1e3)
+    );
   }
-  return res.status;
+  let responseBody;
+  if (rawBody) {
+    try {
+      responseBody = JSON.parse(rawBody);
+    } catch {
+      responseBody = rawBody.slice(0, 1e3);
+    }
+  }
+  return {
+    status: res.status,
+    messageId: extractPostedMessageId(responseBody),
+    ...responseBody === void 0 ? {} : { responseBody }
+  };
 }
 async function setThreadResolved(docId, threadId, reopen, csrf) {
   const action = reopen ? "reopen" : "resolve";
@@ -390,6 +565,156 @@ function lineContext(lines, line, radius = 1) {
   return out.join("\n");
 }
 
+// src/lib/submission-lock.ts
+import { createHash, randomUUID } from "crypto";
+import {
+  closeSync,
+  existsSync as existsSync2,
+  fsyncSync,
+  mkdirSync as mkdirSync3,
+  openSync,
+  readFileSync as readFileSync3,
+  realpathSync as realpathSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { tmpdir } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+
+// src/lib/workspace-path.ts
+import { existsSync, realpathSync } from "fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "path";
+function isOutside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+function workspaceRelativePath(input, root = process.cwd()) {
+  if (typeof input !== "string" || !input.length) throw new Error("workspace path is empty");
+  if (isAbsolute(input) || /^[\\/]/.test(input) || /^[a-zA-Z]:[\\/]/.test(input)) {
+    throw new Error(`Absolute paths are not allowed: ${input}`);
+  }
+  const portable = input.replace(/\\/g, "/");
+  if (portable.split("/").includes("..")) {
+    throw new Error(`Parent path traversal is not allowed: ${input}`);
+  }
+  const target = resolve(root, ...portable.split("/"));
+  const absoluteRoot = resolve(root);
+  if (isOutside(absoluteRoot, target) || target === absoluteRoot) {
+    throw new Error(`Path must identify a file inside the working tree: ${input}`);
+  }
+  return relative(absoluteRoot, target).split(sep).join("/");
+}
+function workspaceReadPath(input, root = process.cwd()) {
+  const rel = workspaceRelativePath(input, root);
+  const realRoot = realpathSync(root);
+  const lexicalTarget = resolve(root, ...rel.split("/"));
+  const realTarget = realpathSync(lexicalTarget);
+  if (isOutside(realRoot, realTarget) || realTarget === realRoot) {
+    throw new Error(`Path resolves outside the working tree: ${input}`);
+  }
+  return lexicalTarget;
+}
+function workspaceWritePath(input, root = process.cwd()) {
+  const rel = workspaceRelativePath(input, root);
+  const lexicalTarget = resolve(root, ...rel.split("/"));
+  const realRoot = realpathSync(root);
+  if (existsSync(lexicalTarget)) {
+    const target = realpathSync(lexicalTarget);
+    if (isOutside(realRoot, target) || target === realRoot) {
+      throw new Error(`Path resolves outside the working tree: ${input}`);
+    }
+    return lexicalTarget;
+  }
+  let ancestor = dirname(lexicalTarget);
+  while (!existsSync(ancestor)) {
+    const parent = dirname(ancestor);
+    if (parent === ancestor) throw new Error(`Cannot resolve a safe parent for ${input}`);
+    ancestor = parent;
+  }
+  const realAncestor = realpathSync(ancestor);
+  if (isOutside(realRoot, realAncestor)) {
+    throw new Error(`Path has an ancestor outside the working tree: ${input}`);
+  }
+  return lexicalTarget;
+}
+
+// src/lib/submission-lock.ts
+var MUTATION_LOCK_PATH = join3(".overleaf", "mutation.lock");
+function mutationLockPath(root = process.cwd()) {
+  const key = createHash("sha256").update(realpathSync2(root), "utf8").digest("hex").slice(0, 32);
+  return join3(tmpdir(), `overleaf-review-${key}.lock`);
+}
+function acquireMutationLock(projectId, options = {}) {
+  const root = options.root ?? process.cwd();
+  const path = options.path ? workspaceWritePath(options.path, root) : mutationLockPath(root);
+  const displayPath = options.path ?? path;
+  mkdirSync3(dirname2(path), { recursive: true });
+  const token = randomUUID();
+  let fd;
+  try {
+    fd = openSync(path, "wx", 384);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    let owner = "";
+    try {
+      const parsed = JSON.parse(readFileSync3(path, "utf8"));
+      const details = [
+        typeof parsed.pid === "number" ? `pid ${parsed.pid}` : void 0,
+        typeof parsed.startedAt === "string" ? `since ${parsed.startedAt}` : void 0,
+        typeof parsed.projectId === "string" ? `project ${parsed.projectId}` : void 0
+      ].filter(Boolean);
+      if (details.length) owner = ` (${details.join(", ")})`;
+    } catch {
+    }
+    throw new Error(
+      `Another overleaf-review mutation holds ${displayPath}${owner}. Wait for it to finish. If its process crashed, inspect any relevant receipt and live project before removing the lock manually.`,
+      { cause: error }
+    );
+  }
+  try {
+    writeFileSync3(
+      fd,
+      `${JSON.stringify(
+        {
+          token,
+          pid: process.pid,
+          projectId,
+          startedAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+    fsyncSync(fd);
+  } catch (error) {
+    closeSync(fd);
+    if (existsSync2(path)) unlinkSync2(path);
+    throw error;
+  }
+  closeSync(fd);
+  let released = false;
+  return {
+    path,
+    token,
+    release() {
+      if (released) return;
+      try {
+        const current = JSON.parse(readFileSync3(path, "utf8"));
+        if (current.token === token) unlinkSync2(path);
+        released = true;
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          released = true;
+          return;
+        }
+        throw error;
+      }
+    }
+  };
+}
+
 // src/commands/pull.ts
 function buildMemberMap(project) {
   const map = {};
@@ -401,60 +726,71 @@ function buildMemberMap(project) {
   for (const m of project?.members ?? []) add(m);
   return map;
 }
-async function pull(outDir = ".overleaf") {
-  const { socket, project, docs } = await openProject();
-  const members = buildMemberMap(project);
-  const threads = await getThreads();
-  const comments = [];
-  const changes = [];
-  for (const doc of docs) {
-    const state = await joinDoc(socket, doc._id);
-    for (const c of state.ranges.comments ?? []) {
-      const line = offsetToLine(state.lines, c.op.p);
-      const thread = threads[c.op.t] ?? {};
-      comments.push({
-        doc: doc.path,
-        threadId: c.op.t,
-        anchor: c.op.c,
-        line: line + 1,
-        context: lineContext(state.lines, line),
-        resolved: Boolean(thread.resolved),
-        messages: (thread.messages ?? []).map((m) => ({
-          id: m.id,
-          author: m.user?.first_name ?? members[m.user_id] ?? m.user_id,
-          email: m.user?.email,
-          content: m.content,
-          timestamp: m.timestamp
-        }))
-      });
+async function pull(outDir = ".overleaf", options = {}) {
+  let mutationLock;
+  let opened;
+  try {
+    if (options.acquireLock !== false) mutationLock = acquireMutationLock(config.projectId);
+    opened = await openProject();
+    const { socket, project, docs } = opened;
+    const members = buildMemberMap(project);
+    const threads = await getThreads();
+    const comments = [];
+    const changes = [];
+    for (const doc of docs) {
+      const state = await joinDoc(socket, doc._id);
+      for (const c of state.ranges.comments ?? []) {
+        const line = offsetToLine(state.lines, c.op.p);
+        const thread = threads[c.op.t] ?? {};
+        comments.push({
+          doc: doc.path,
+          threadId: c.op.t,
+          anchor: c.op.c,
+          line: line + 1,
+          context: lineContext(state.lines, line),
+          resolved: Boolean(thread.resolved),
+          messages: (thread.messages ?? []).map((m) => ({
+            id: m.id,
+            author: m.user?.first_name ?? members[m.user_id] ?? m.user_id,
+            email: m.user?.email,
+            content: m.content,
+            timestamp: m.timestamp
+          }))
+        });
+      }
+      for (const ch of state.ranges.changes ?? []) {
+        const isInsert = typeof ch.op.i === "string";
+        const line = offsetToLine(state.lines, ch.op.p);
+        changes.push({
+          doc: doc.path,
+          id: ch.id,
+          type: isInsert ? "insert" : "delete",
+          text: isInsert ? ch.op.i : ch.op.d,
+          line: line + 1,
+          context: lineContext(state.lines, line),
+          author: members[ch.metadata?.user_id] ?? ch.metadata?.user_id ?? "unknown",
+          ts: ch.metadata?.ts
+        });
+      }
     }
-    for (const ch of state.ranges.changes ?? []) {
-      const isInsert = typeof ch.op.i === "string";
-      const line = offsetToLine(state.lines, ch.op.p);
-      changes.push({
-        doc: doc.path,
-        id: ch.id,
-        type: isInsert ? "insert" : "delete",
-        text: isInsert ? ch.op.i : ch.op.d,
-        line: line + 1,
-        context: lineContext(state.lines, line),
-        author: members[ch.metadata?.user_id] ?? ch.metadata?.user_id ?? "unknown",
-        ts: ch.metadata?.ts
-      });
+    const data = {
+      project: project?.name ?? "(unknown)",
+      projectId: config.projectId,
+      pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
+      comments,
+      changes
+    };
+    mkdirSync4(outDir, { recursive: true });
+    writeFileSync4(join4(outDir, "reviews.json"), JSON.stringify(data, null, 2) + "\n");
+    writeFileSync4(join4(outDir, "reviews.md"), renderMarkdown(data));
+    return data;
+  } finally {
+    try {
+      opened?.socket.close();
+    } finally {
+      mutationLock?.release();
     }
   }
-  socket.close();
-  const data = {
-    project: project?.name ?? "(unknown)",
-    projectId: config.projectId,
-    pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
-    comments,
-    changes
-  };
-  mkdirSync3(outDir, { recursive: true });
-  writeFileSync3(join3(outDir, "reviews.json"), JSON.stringify(data, null, 2) + "\n");
-  writeFileSync3(join3(outDir, "reviews.md"), renderMarkdown(data));
-  return data;
 }
 function renderMarkdown(d) {
   const L = [];
@@ -505,343 +841,2740 @@ function renderMarkdown(d) {
 }
 
 // src/commands/push.ts
-import { readFileSync as readFileSync3, readdirSync } from "fs";
-import { relative, resolve as resolvePath, sep } from "path";
-import { randomBytes } from "crypto";
+import {
+  mkdirSync as mkdirSync7,
+  readFileSync as readFileSync6,
+  readdirSync as readdirSync2,
+  renameSync as renameSync4,
+  statSync,
+  unlinkSync as unlinkSync5,
+  writeFileSync as writeFileSync7
+} from "fs";
+import { createHash as createHash3 } from "crypto";
+import { dirname as dirname5, relative as relative2, resolve as resolvePath, sep as sep2 } from "path";
 import { diffWordsWithSpace } from "diff";
-function buildOps(remote, local) {
-  const ops = [];
-  let p = 0;
-  for (const part of diffWordsWithSpace(remote, local)) {
-    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;
-    }
+
+// src/lib/document-match.ts
+var AmbiguousDocumentError = class extends Error {
+  constructor(identifier, matches) {
+    super(
+      `Document name "${identifier}" is ambiguous (${matches.map((doc) => doc.path).join(", ")}); use the exact project path.`
+    );
+    this.name = "AmbiguousDocumentError";
   }
-  return ops;
-}
-function preview(op) {
-  const kind = op.i != null ? "insert" : "delete";
-  const text = (op.i ?? op.d ?? "").replace(/\n/g, "\u23CE");
-  const clip = text.length > 60 ? text.slice(0, 60) + "\u2026" : text;
-  return `  ${kind.padEnd(6)} @ ${String(op.p).padStart(5)}  "${clip}"`;
+};
+function matchDocument(identifier, docs) {
+  const exact = docs.filter((doc) => doc.path === identifier);
+  if (exact.length > 1) throw new AmbiguousDocumentError(identifier, exact);
+  if (exact.length === 1) return exact[0];
+  if (identifier.includes("/") || identifier.includes("\\")) return void 0;
+  const basename3 = identifier.replace(/\\/g, "/").split("/").pop() ?? identifier;
+  const matches = docs.filter((doc) => doc.name === basename3);
+  if (matches.length > 1) throw new AmbiguousDocumentError(identifier, matches);
+  return matches[0];
 }
-function toOverleafPath(file) {
-  return relative(process.cwd(), resolvePath(file)).split(sep).join("/");
+
+// src/lib/receipts.ts
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync3,
+  fsyncSync as fsyncSync2,
+  mkdirSync as mkdirSync5,
+  openSync as openSync2,
+  readFileSync as readFileSync4,
+  readdirSync,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync5
+} from "fs";
+import { randomUUID as randomUUID2 } from "crypto";
+import { basename, dirname as dirname3, join as join5 } from "path";
+var RECEIPT_SCHEMA_VERSION = 1;
+var DEFAULT_RECEIPTS_DIR = join5(".overleaf", "receipts");
+function safeFilenamePart(value) {
+  const safe = value.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return safe || "operation";
 }
-var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".overleaf", "tmp", "dist"]);
-function discoverLocalTex(dir = process.cwd(), acc = []) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name)) continue;
-    const full = resolvePath(dir, entry.name);
-    if (entry.isDirectory()) discoverLocalTex(full, acc);
-    else if (entry.name.endsWith(".tex")) acc.push(toOverleafPath(full));
+function writeJsonAtomic(path, value) {
+  const targetDir = dirname3(path);
+  mkdirSync5(targetDir, { recursive: true });
+  const tempPath = join5(
+    targetDir,
+    `.${basename(path)}.${process.pid}.${randomUUID2()}.tmp`
+  );
+  let fd;
+  try {
+    fd = openSync2(tempPath, "wx", 384);
+    writeFileSync5(fd, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+    fsyncSync2(fd);
+    closeSync2(fd);
+    fd = void 0;
+    renameSync2(tempPath, path);
+    let dirFd;
+    try {
+      dirFd = openSync2(targetDir, "r");
+      fsyncSync2(dirFd);
+    } catch {
+    } finally {
+      if (dirFd !== void 0) closeSync2(dirFd);
+    }
+  } finally {
+    if (fd !== void 0) closeSync2(fd);
+    if (existsSync3(tempPath)) unlinkSync3(tempPath);
   }
-  return acc;
 }
-function pickDoc(file, docName, docs, rootDocId, allowRootFallback) {
-  if (docName) return docs.find((d) => d.path === docName || d.name === docName);
-  const rel = toOverleafPath(file);
-  const base = rel.split("/").pop();
-  return docs.find((d) => d.path === rel) ?? docs.find((d) => d.name === base) ?? (allowRootFallback ? docs.find((d) => d._id === rootDocId) ?? docs[0] : void 0);
+function beginReceipt(operation, details, options = {}) {
+  const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+  const operationId = options.operationId ?? randomUUID2();
+  const receipt = {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    operationId,
+    operation,
+    status: "started",
+    startedAt: now,
+    updatedAt: now,
+    details
+  };
+  const dir = options.receiptsDir ?? DEFAULT_RECEIPTS_DIR;
+  const timestamp = now.replace(/[:.]/g, "-");
+  const path = join5(dir, `${timestamp}-${safeFilenamePart(operation)}-${operationId}.json`);
+  writeJsonAtomic(path, receipt);
+  return { path, receipt };
 }
-async function push(opts) {
-  const { socket, project, docs } = await openProject();
-  const files = opts.file ? [opts.file] : discoverLocalTex();
-  if (!files.length) {
-    console.log("No local .tex files found to push.");
-    socket.close();
-    return;
+function updateReceipt(handle, status, details, options = {}) {
+  const receipt = {
+    ...handle.receipt,
+    status,
+    updatedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    details: { ...handle.receipt.details, ...details }
+  };
+  writeJsonAtomic(handle.path, receipt);
+  return { path: handle.path, receipt };
+}
+function readReceipts(receiptsDir = DEFAULT_RECEIPTS_DIR) {
+  let names;
+  try {
+    names = readdirSync(receiptsDir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
   }
-  const plans = [];
-  for (const file of files) {
-    let local;
+  const receipts = [];
+  for (const name of names) {
+    const path = join5(receiptsDir, name);
     try {
-      local = readFileSync3(file, "utf8");
+      const receipt = JSON.parse(readFileSync4(path, "utf8"));
+      if (receipt?.schemaVersion === RECEIPT_SCHEMA_VERSION && typeof receipt.operationId === "string" && typeof receipt.operation === "string" && typeof receipt.updatedAt === "string" && receipt.details && typeof receipt.details === "object") {
+        receipts.push({ path, receipt });
+      }
     } catch {
-      console.log(`- ${file}: cannot read, skipped`);
-      continue;
-    }
-    const doc = pickDoc(file, opts.docName, docs, project.rootDoc_id, Boolean(opts.file));
-    if (!doc) {
-      console.log(`- ${file}: no matching Overleaf doc, skipped`);
-      continue;
     }
-    const state = await joinDoc(socket, doc._id);
-    const ops = buildOps(state.lines.join("\n"), local);
-    if (ops.length) plans.push({ file, doc, ops, version: state.version });
   }
-  if (!plans.length) {
-    console.log("Nothing to push \u2014 local files already match Overleaf.");
-    socket.close();
-    return;
+  return receipts.sort((a, b) => b.receipt.updatedAt.localeCompare(a.receipt.updatedAt));
+}
+
+// src/lib/sync-state.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync5,
+  renameSync as renameSync3,
+  unlinkSync as unlinkSync4,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { dirname as dirname4, join as join6 } from "path";
+var BASE_STATE_SCHEMA_VERSION = 1;
+var BASE_STATE_PATH = join6(".overleaf", "base.json");
+function sha256(text) {
+  return createHash2("sha256").update(text, "utf8").digest("hex");
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = value[key];
+      if (item !== void 0) out[key] = canonicalize(item);
+    }
+    return out;
   }
-  console.log(
-    opts.direct ? "Mode: DIRECT \u2014 plain edits (not marked as suggestions)" : "Mode: SUGGESTIONS \u2014 tracked changes for co-authors to accept/reject"
+  return value;
+}
+function stableJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function sortedRanges(values) {
+  return (values ?? []).map(canonicalize).sort((a, b) => {
+    const left = stableJson(a);
+    const right = stableJson(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+function fingerprintRanges(ranges) {
+  return sha256(
+    stableJson({
+      comments: sortedRanges(ranges.comments),
+      changes: sortedRanges(ranges.changes)
+    })
   );
-  for (const pl of plans) {
-    const ins = pl.ops.filter((o) => o.i != null).length;
-    const del = pl.ops.filter((o) => o.d != null).length;
-    console.log(`
-${pl.file} \u2192 ${pl.doc.path} (v${pl.version}): ${pl.ops.length} op(s), ${ins} ins / ${del} del`);
-    for (const op of pl.ops.slice(0, 12)) console.log(preview(op));
-    if (pl.ops.length > 12) console.log(`  \u2026 and ${pl.ops.length - 12} more`);
-  }
-  if (opts.dryRun) {
-    console.log("\n(dry run \u2014 nothing sent to Overleaf)");
-    socket.close();
-    return;
+}
+function assertBaseState(value, path) {
+  if (!value || typeof value !== "object") throw new Error(`Invalid base state in ${path}`);
+  const state = value;
+  if (state.schemaVersion !== BASE_STATE_SCHEMA_VERSION || typeof state.projectId !== "string" || !state.documents || typeof state.documents !== "object") {
+    throw new Error(
+      `Unsupported or invalid base state in ${path}; run fetch to create a new synchronization base.`
+    );
   }
-  socket.on("otUpdateError", (a) => console.log("!! otUpdateError:", JSON.stringify(a)));
-  for (const pl of plans) {
-    const meta = opts.direct ? {} : { tc: randomBytes(12).toString("hex") };
-    const update = { doc: pl.doc._id, op: pl.ops, v: pl.version, meta };
-    const ack = await socket.emit("applyOtUpdate", [pl.doc._id, update], 2e4);
-    if (ack?.[0]) {
-      socket.close();
-      throw new Error(`Overleaf rejected ${pl.file}: ${JSON.stringify(ack[0])}`);
+  for (const [docId, raw] of Object.entries(state.documents)) {
+    const doc = raw;
+    if (doc.docId !== docId || typeof doc.path !== "string" || typeof doc.text !== "string" || typeof doc.hash !== "string" || doc.hash !== sha256(doc.text)) {
+      throw new Error(`Invalid document ${docId} in ${path}`);
     }
   }
-  let allMatch = true;
-  for (const pl of plans) {
-    const after = await joinDoc(socket, pl.doc._id);
-    if (after.lines.join("\n") !== readFileSync3(pl.file, "utf8")) allMatch = false;
-  }
-  socket.close();
-  const totalOps = plans.reduce((n, p) => n + p.ops.length, 0);
-  const mode = opts.direct ? "direct edit(s)" : "tracked suggestion(s)";
-  console.log(
-    `
-\u2705 Pushed ${totalOps} ${mode} across ${plans.length} file(s) \u2014 verified match: ${allMatch ? "yes" : "\u26A0\uFE0F NO, inspect"}`
-  );
 }
-
-// src/commands/fetch.ts
-import { writeFileSync as writeFileSync4, readFileSync as readFileSync4, mkdirSync as mkdirSync4, existsSync } from "fs";
-import { dirname } from "path";
-async function fetchDocs(opts) {
-  const { socket, docs } = await openProject();
-  const targets = opts.file ? docs.filter((d) => d.path === opts.file || d.name === opts.file) : docs;
-  if (!targets.length) {
-    console.log(`No matching doc for "${opts.file}".`);
-    socket.close();
-    return;
+function loadBaseState(path = BASE_STATE_PATH) {
+  let raw;
+  try {
+    raw = readFileSync5(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
   }
-  let changed = 0;
-  for (const doc of targets) {
-    const state = await joinDoc(socket, doc._id);
-    const remote = state.lines.join("\n");
-    const local = existsSync(doc.path) ? readFileSync4(doc.path, "utf8") : null;
-    if (local === remote) continue;
-    changed++;
-    const delta = local === null ? "(new file)" : `${local.length} \u2192 ${remote.length} chars`;
-    console.log(`  ${doc.path}  ${delta}`);
-    if (!opts.dryRun) {
-      mkdirSync4(dirname(doc.path), { recursive: true });
-      writeFileSync4(doc.path, remote);
-    }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON in ${path}; run fetch to recreate the synchronization base.`);
   }
-  socket.close();
-  if (!changed) {
-    console.log("Already up to date \u2014 local files match Overleaf.");
-    return;
+  assertBaseState(parsed, path);
+  return parsed;
+}
+function saveBaseState(state, path = BASE_STATE_PATH) {
+  mkdirSync6(dirname4(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync6(temp, JSON.stringify(state, null, 2) + "\n", { mode: 384 });
+    renameSync3(temp, path);
+  } catch (error) {
+    try {
+      unlinkSync4(temp);
+    } catch {
+    }
+    throw error;
   }
-  console.log(
-    opts.dryRun ? `
-(dry run \u2014 ${changed} local file(s) would be overwritten)` : `
-\u2705 Fetched ${changed} file(s) from Overleaf.`
-  );
+}
+function mergeBaseDocuments(projectId, documents, path = BASE_STATE_PATH) {
+  const previous = loadBaseState(path);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const state = {
+    schemaVersion: BASE_STATE_SCHEMA_VERSION,
+    projectId,
+    updatedAt: now,
+    documents: previous?.projectId === projectId ? { ...previous.documents } : {}
+  };
+  for (const doc of documents) state.documents[doc.docId] = doc;
+  saveBaseState(state, path);
+  return state;
 }
 
-// src/commands/upload.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { basename } from "path";
-function findFolder(folder, wanted, prefix = "") {
-  for (const f of folder?.folders ?? []) {
-    const path = prefix ? `${prefix}/${f.name}` : f.name;
-    if (f.name === wanted || path === wanted) return f;
-    const deeper = findFolder(f, wanted, path);
-    if (deeper) return deeper;
+// 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;
+    }
   }
-  return void 0;
+  flush();
+  return edits;
 }
-async function upload(paths, folderName) {
-  const { socket, project } = await openProject();
-  socket.close();
-  const root = project?.rootFolder?.[0];
-  if (!root?._id) throw new Error("could not resolve the project root folder");
-  let folderId = root._id;
-  if (folderName) {
-    const found = findFolder(root, folderName);
-    if (!found) throw new Error(`folder not found in project: ${folderName}`);
-    folderId = found._id;
-  }
-  const csrf = await getCsrfToken();
-  for (const path of paths) {
-    const bytes = readFileSync5(path);
-    const res = await uploadFile(folderId, basename(path), bytes, csrf);
-    console.log(`\u2705 Uploaded ${path} \u2192 ${res.entity_type} ${res.entity_id}`);
+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;
 }
-
-// src/commands/comment.ts
-import { randomBytes as randomBytes2 } from "crypto";
-async function comment(opts) {
-  const { socket, project, docs } = await openProject();
-  const doc = opts.docName ? docs.find((d) => d.path === opts.docName || d.name === opts.docName) : docs.find((d) => d._id === project.rootDoc_id) ?? docs[0];
-  if (!doc) {
-    socket.close();
-    throw new Error(`doc not found: ${opts.docName ?? "(root)"}`);
-  }
-  const state = await joinDoc(socket, doc._id);
-  const flat = state.lines.join("\n");
-  const nth = Math.max(1, opts.occurrence ?? 1);
-  let p = -1;
-  let from = 0;
-  for (let i = 0; i < nth; i++) {
-    p = flat.indexOf(opts.anchor, from);
-    if (p < 0) break;
-    from = p + 1;
-  }
-  if (p < 0) {
-    socket.close();
-    throw new Error(`anchor text not found in ${doc.name}: "${opts.anchor}"`);
-  }
-  const threadId = randomBytes2(12).toString("hex");
-  const update = {
-    doc: doc._id,
-    op: [{ p, c: opts.anchor, t: threadId }],
-    v: state.version,
-    meta: {}
-  };
-  const ack = await socket.emit("applyOtUpdate", [doc._id, update], 15e3);
-  socket.close();
-  if (ack?.[0]) throw new Error(`Overleaf rejected the comment op: ${JSON.stringify(ack[0])}`);
-  const csrf = await getCsrfToken();
-  await postThreadMessage(threadId, opts.message, csrf);
-  console.log(`\u2705 Commented on "${opts.anchor}" in ${doc.name}  (thread ${threadId})`);
+function editTouchesEnvelope(edit, start, end) {
+  if (edit.start === edit.end) return edit.start >= start && edit.start <= end;
+  return edit.start <= end && edit.end >= start;
 }
-
-// src/commands/reply.ts
-async function reply(threadId, message) {
-  const csrf = await getCsrfToken();
-  await postThreadMessage(threadId, message, csrf);
-  console.log(`\u2705 Replied to thread ${threadId}`);
+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;
 }
-
-// src/commands/resolve.ts
-async function resolve(threadId, reopen = false) {
-  const { socket, docs } = await openProject();
-  let docId;
-  for (const doc of docs) {
-    const state = await joinDoc(socket, doc._id);
-    if ((state.ranges.comments ?? []).some((c) => c.op?.t === threadId)) {
-      docId = doc._id;
-      break;
+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);
   }
-  socket.close();
-  if (!docId) {
-    throw new Error(
-      `thread ${threadId} not found in any doc's active comments (already resolved threads may not be locatable this way)`
-    );
+  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);
   }
-  const csrf = await getCsrfToken();
-  await setThreadResolved(docId, threadId, reopen, csrf);
-  console.log(`\u2705 Thread ${threadId} ${reopen ? "reopened" : "resolved"}`);
+  return result;
 }
-
-// src/commands/delete-comment.ts
-async function deleteComment(threadId) {
-  const { socket, docs } = await openProject();
-  let docId;
-  for (const doc of docs) {
-    const state = await joinDoc(socket, doc._id);
-    if ((state.ranges.comments ?? []).some((c) => c.op?.t === threadId)) {
-      docId = doc._id;
-      break;
+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 });
     }
   }
-  socket.close();
-  if (!docId) throw new Error(`thread ${threadId} not found in any doc's comments`);
-  const csrf = await getCsrfToken();
-  await deleteThread(docId, threadId, csrf);
-  console.log(`\u2705 Deleted comment thread ${threadId}`);
+  return {
+    text: conflicts.length ? void 0 : applyEdits(live, toApply),
+    localEdits,
+    liveEdits,
+    appliedLocalEdits: toApply,
+    alreadyAppliedLocalEdits,
+    conflicts
+  };
 }
 
-// src/commands/delete-message.ts
-async function deleteThreadMessage(messageId, threadId) {
-  const csrf = await getCsrfToken();
-  let tid = threadId;
-  if (!tid) {
-    const threads = await getThreads();
-    for (const [t, v] of Object.entries(threads)) {
-      if (v.messages?.some((m) => m.id === messageId)) {
-        tid = t;
-        break;
+// src/lib/tracked-overlap.ts
+function spanOverlapsEdit(start, end, edit) {
+  const editIsPoint = edit.start === edit.end;
+  const rangeIsPoint = start === end;
+  if (editIsPoint && rangeIsPoint) return edit.start === start;
+  if (editIsPoint) return edit.start > start && edit.start < end;
+  if (rangeIsPoint) return start >= edit.start && start < edit.end;
+  return edit.start < end && start < edit.end;
+}
+function overlapsEdit(change, edit) {
+  const p = change.op?.p;
+  if (typeof p !== "number") return false;
+  const inserted = typeof change.op?.i === "string" ? change.op.i : void 0;
+  const changeStart = p;
+  const changeEnd = p + (inserted?.length ?? 0);
+  return spanOverlapsEdit(changeStart, changeEnd, edit);
+}
+function findTrackedChangeOverlaps(changes, proposedEdits) {
+  const out = [];
+  for (const change of changes ?? []) {
+    for (const proposedEdit of proposedEdits) {
+      if (overlapsEdit(change, proposedEdit)) {
+        out.push({ changeId: change.id ?? "(unknown)", change, proposedEdit });
       }
     }
   }
-  if (!tid) throw new Error(`message ${messageId} not found in any thread`);
-  await deleteMessage(tid, messageId, csrf);
-  console.log(`\u2705 Deleted message ${messageId} from thread ${tid}`);
+  return out;
+}
+function findCommentOverlaps(comments, proposedEdits) {
+  const out = [];
+  for (const comment2 of comments ?? []) {
+    const p = comment2.op?.p;
+    const anchor = comment2.op?.c;
+    if (typeof p !== "number" || typeof anchor !== "string") continue;
+    for (const proposedEdit of proposedEdits) {
+      if (spanOverlapsEdit(p, p + anchor.length, proposedEdit)) {
+        out.push({
+          threadId: comment2.op?.t ?? comment2.id ?? "(unknown)",
+          position: p,
+          anchor,
+          comment: comment2,
+          proposedEdit
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// src/lib/tracked-changes.ts
+import { randomBytes } from "crypto";
+var TRACKED_CHANGE_SEED_BYTES = 9;
+function createTrackedChangeSeed(bytes = randomBytes) {
+  const entropy = bytes(TRACKED_CHANGE_SEED_BYTES);
+  if (entropy.byteLength !== TRACKED_CHANGE_SEED_BYTES) {
+    throw new Error(
+      `tracked-change seed source returned ${entropy.byteLength} bytes; expected ${TRACKED_CHANGE_SEED_BYTES}`
+    );
+  }
+  return Buffer.from(entropy).toString("hex");
+}
+var TrackedChangeMutationError = class extends Error {
+  constructor(message, result, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.result = result;
+    this.name = "TrackedChangeMutationError";
+  }
+  result;
+};
+function uniqueChangeIds(changeIds) {
+  return [...new Set(changeIds)];
+}
+function changeIdsInRanges(ranges) {
+  return [...new Set(ranges.map((range) => range.id))];
+}
+function remainingChangeIds(ranges, requestedIds) {
+  const present = new Set(changeIdsInRanges(ranges));
+  return uniqueChangeIds(requestedIds).filter((id) => present.has(id));
+}
+function inverseOf(range) {
+  const { p, i, d } = range.op ?? {};
+  if (!Number.isSafeInteger(p) || p < 0) {
+    throw new Error(`tracked change ${range.id} has an invalid position: ${String(p)}`);
+  }
+  if (typeof i === "string" && d === void 0) return { p, d: i, u: true };
+  if (typeof d === "string" && i === void 0) return { p, i: d, u: true };
+  throw new Error(`tracked change ${range.id} does not contain exactly one insert/delete op`);
+}
+function applyUndo(text, op, changeId) {
+  if (op.p > text.length) {
+    throw new Error(
+      `tracked change ${changeId} starts at ${op.p}, beyond document length ${text.length}`
+    );
+  }
+  if ("d" in op) {
+    const actual = text.slice(op.p, op.p + op.d.length);
+    if (actual !== op.d) {
+      throw new Error(
+        `tracked insertion ${changeId} no longer matches document text at ${op.p}: expected ${JSON.stringify(op.d)}, found ${JSON.stringify(actual)}`
+      );
+    }
+    return text.slice(0, op.p) + text.slice(op.p + op.d.length);
+  }
+  return text.slice(0, op.p) + op.i + text.slice(op.p);
+}
+function buildRejectionPlan(currentText, ranges, requestedIds) {
+  const requested = new Set(uniqueChangeIds(requestedIds));
+  const fragments = ranges.filter((range) => requested.has(range.id));
+  fragments.sort((a, b) => b.op.p - a.op.p);
+  const operations = [];
+  let expectedText = currentText;
+  for (const range of fragments) {
+    const inverse = inverseOf(range);
+    expectedText = applyUndo(expectedText, inverse, range.id);
+    operations.push(inverse);
+  }
+  return {
+    changeIds: changeIdsInRanges(fragments),
+    fragmentCount: fragments.length,
+    operations,
+    expectedText
+  };
+}
+
+// src/lib/snapshots.ts
+import { join as join7 } from "path";
+var SNAPSHOTS_DIR = join7(".overleaf", "snapshots");
+function snapshotTimestamp(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+function snapshotRelativePath(timestamp, projectPath, root = process.cwd()) {
+  if (!/^[0-9TZ-]+$/.test(timestamp)) throw new Error(`Invalid snapshot timestamp: ${timestamp}`);
+  const safeProjectPath = workspaceRelativePath(projectPath, root);
+  return workspaceRelativePath(join7(SNAPSHOTS_DIR, timestamp, safeProjectPath), root);
+}
+
+// src/commands/push.ts
+var PUSH_PLAN_SCHEMA_VERSION = 2;
+var PUSH_PLAN_KIND = "overleaf-review-push-plan";
+var PushSubmissionError = class extends Error {
+  constructor(message, receiptPath, status, documents, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.receiptPath = receiptPath;
+    this.status = status;
+    this.documents = documents;
+    this.name = "PushSubmissionError";
+  }
+  receiptPath;
+  status;
+  documents;
+};
+var PushPlanningError = class extends Error {
+  constructor(message, conflicts = [], overlaps = []) {
+    super(message);
+    this.conflicts = conflicts;
+    this.overlaps = overlaps;
+    this.name = "PushPlanningError";
+  }
+  conflicts;
+  overlaps;
+};
+var PushPlanValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PushPlanValidationError";
+  }
+};
+function validatePushOptions(opts) {
+  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) {
+  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;
+    }
+  }
+  const rebuilt = applyOps(source, ops);
+  if (rebuilt !== target) {
+    throw new Error("internal error: generated OT operations do not reconstruct target text");
+  }
+  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 applyOps(source, ops) {
+  let text = source;
+  for (const op of ops) {
+    if (!Number.isSafeInteger(op.p) || op.p < 0 || op.p > text.length) {
+      throw new Error(`invalid operation position ${String(op.p)} for ${text.length}-character text`);
+    }
+    const hasInsert = typeof op.i === "string";
+    const hasDelete = typeof op.d === "string";
+    if (hasInsert === hasDelete) throw new Error("operation must contain exactly one of i or d");
+    if (hasInsert) {
+      text = text.slice(0, op.p) + op.i + text.slice(op.p);
+    } else {
+      const deletion = op.d;
+      const actual = text.slice(op.p, op.p + deletion.length);
+      if (actual !== deletion) {
+        throw new Error(
+          `delete operation mismatch at ${op.p}: expected ${JSON.stringify(deletion)}, found ${JSON.stringify(actual)}`
+        );
+      }
+      text = text.slice(0, op.p) + text.slice(op.p + deletion.length);
+    }
+  }
+  return text;
+}
+function preview(op) {
+  const kind = op.i != null ? "insert" : "delete";
+  const text = (op.i ?? op.d ?? "").replace(/\n/g, "\u23CE");
+  const clip = text.length > 60 ? text.slice(0, 60) + "\u2026" : text;
+  return `  ${kind.padEnd(6)} @ ${String(op.p).padStart(5)}  "${clip}"`;
+}
+function toOverleafPath(file) {
+  return workspaceRelativePath(file);
+}
+var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".overleaf", "tmp", "dist"]);
+function discoverLocalTex(dir = process.cwd(), acc = []) {
+  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name)) continue;
+    const full = resolvePath(dir, entry.name);
+    if (entry.isDirectory()) discoverLocalTex(full, acc);
+    else if (entry.name.endsWith(".tex")) {
+      acc.push(relative2(process.cwd(), full).split(sep2).join("/"));
+    }
+  }
+  return acc;
+}
+function pickDoc(file, docName, docs) {
+  return matchDocument(docName?.replace(/\\/g, "/") ?? toOverleafPath(file), docs);
+}
+function formatConflicts(conflicts) {
+  return conflicts.flatMap(
+    ({ docPath, conflicts: items }) => items.map(
+      ({ local, live, reason }) => reason === "ambiguous-local-anchor" ? `${docPath}: repeated-text anchor for local [${local.start},${local.end}) is ambiguous and its envelope is touched by live [${live.start},${live.end}); refresh and reapply this edit explicitly` : `${docPath}: local [${local.start},${local.end}) overlaps live [${live.start},${live.end})`
+    )
+  ).join("\n  ");
+}
+function serializeOverlaps(overlaps) {
+  return overlaps.map(({ changeId, proposedEdit, change }) => ({
+    changeId,
+    proposedEdit,
+    trackedOp: {
+      p: change.op?.p,
+      i: change.op?.i,
+      d: change.op?.d
+    }
+  })).sort((a, b) => {
+    const left = stableJson(a);
+    const right = stableJson(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+function serializeActiveTrackedRanges(changes) {
+  const ranges = (changes ?? []).map((change, index) => {
+    const id = change?.id;
+    const p = change?.op?.p;
+    const hasInsert = typeof change?.op?.i === "string";
+    const hasDelete = typeof change?.op?.d === "string";
+    if (typeof id !== "string" || !Number.isSafeInteger(p) || p < 0 || hasInsert === hasDelete) {
+      throw new Error(`Overleaf returned an invalid tracked range at index ${index}`);
+    }
+    return {
+      id,
+      op: {
+        p,
+        ...hasInsert ? { i: change.op.i } : { d: change.op.d }
+      },
+      ...change.metadata && typeof change.metadata === "object" ? { metadata: change.metadata } : {}
+    };
+  });
+  return ranges.sort((a, b) => {
+    const left = stableJson(a);
+    const right = stableJson(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+function serializeCommentOverlaps(overlaps) {
+  return overlaps.map(({ threadId, position, anchor, proposedEdit }) => ({
+    threadId,
+    position,
+    anchor,
+    proposedEdit
+  })).sort((a, b) => {
+    const left = stableJson(a);
+    const right = stableJson(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+async function createPlan(opts = {}) {
+  validatePushOptions(opts);
+  if (opts.plan) throw new Error("createPlan does not accept an existing plan");
+  const basePath = opts.basePath ?? BASE_STATE_PATH;
+  const baseState = loadBaseState(basePath);
+  if (baseState && baseState.projectId !== config.projectId && !opts.unsafeNoBase) {
+    throw new PushPlanningError(
+      `Saved base belongs to project ${baseState.projectId}, not ${config.projectId}; run fetch first.`
+    );
+  }
+  const { socket, project, docs } = await openProject();
+  try {
+    const projectId = String(project?._id ?? config.projectId);
+    if (projectId !== config.projectId) {
+      throw new PushPlanningError(
+        `Connected project id ${projectId} does not match configured project ${config.projectId}.`
+      );
+    }
+    const files = opts.file ? [workspaceRelativePath(opts.file)] : discoverLocalTex();
+    if (!files.length) {
+      const emptyPlan = {
+        kind: PUSH_PLAN_KIND,
+        schemaVersion: PUSH_PLAN_SCHEMA_VERSION,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        projectId,
+        projectName: String(project?.name ?? "(unknown)"),
+        direct: Boolean(opts.direct),
+        unsafeNoBase: Boolean(opts.unsafeNoBase),
+        allowOverlap: Boolean(opts.allowOverlap),
+        documents: []
+      };
+      if (opts.planOut) writePushPlan(emptyPlan, opts.planOut);
+      return emptyPlan;
+    }
+    const documents = [];
+    const conflicts = [];
+    const blockedOverlaps = [];
+    for (const file of files) {
+      let local;
+      try {
+        local = readFileSync6(workspaceReadPath(file), "utf8");
+      } catch (error) {
+        throw new Error(`Cannot safely read ${file}: ${error.message}`);
+      }
+      const doc = pickDoc(file, opts.docName, docs);
+      if (!doc) {
+        throw new Error(
+          `No Overleaf document matches ${file}; push it with --file and --doc using the exact project path.`
+        );
+      }
+      const state = await joinDoc(socket, doc._id);
+      const live = state.lines.join("\n");
+      const savedBase = baseState?.projectId === projectId ? baseState.documents[doc._id] : void 0;
+      if (!savedBase && !opts.unsafeNoBase) {
+        throw new PushPlanningError(
+          `No saved synchronization base for ${doc.path}. Run fetch first, or explicitly use \`--unsafe-no-base\` to request legacy two-way behavior.`
+        );
+      }
+      const base = savedBase?.text ?? live;
+      const merge = threeWayMerge(base, local, live);
+      if (merge.conflicts.length) {
+        conflicts.push({ localPath: file, docPath: doc.path, conflicts: merge.conflicts });
+        continue;
+      }
+      const expected = merge.text;
+      const ops = buildOps(live, expected);
+      if (!ops.length) continue;
+      const proposedEdits = buildOperationFootprint(live, expected);
+      const activeTrackedRanges = serializeActiveTrackedRanges(state.ranges.changes);
+      const overlaps = serializeOverlaps(
+        findTrackedChangeOverlaps(state.ranges.changes, proposedEdits)
+      );
+      const commentOverlaps = serializeCommentOverlaps(
+        findCommentOverlaps(state.ranges.comments, proposedEdits)
+      );
+      if (overlaps.length && !opts.allowOverlap) {
+        blockedOverlaps.push({ localPath: file, docPath: doc.path, overlaps });
+        continue;
+      }
+      documents.push({
+        localPath: toOverleafPath(file),
+        docId: doc._id,
+        docPath: doc.path,
+        baseSource: savedBase ? "saved" : "live-unsafe",
+        baseHash: sha256(base),
+        localHash: sha256(local),
+        liveHash: sha256(live),
+        liveVersion: state.version,
+        rangeFingerprint: fingerprintRanges(state.ranges),
+        ops,
+        expectedHash: sha256(expected),
+        tcSeed: opts.direct ? null : createTrackedChangeSeed(),
+        activeTrackedRanges,
+        trackedChangeOverlaps: overlaps,
+        commentOverlaps
+      });
+    }
+    if (conflicts.length || blockedOverlaps.length) {
+      const parts = [];
+      if (conflicts.length) parts.push(`Concurrent edit conflicts:
+  ${formatConflicts(conflicts)}`);
+      if (blockedOverlaps.length) {
+        const lines = blockedOverlaps.flatMap(
+          ({ docPath, overlaps }) => overlaps.map(
+            ({ changeId, proposedEdit }) => `${docPath}: proposed [${proposedEdit.start},${proposedEdit.end}) overlaps change ${changeId}`
+          )
+        );
+        parts.push(
+          `Active tracked-change overlaps:
+  ${lines.join("\n  ")}
+Re-plan with --allow-overlap only after inspecting these changes.`
+        );
+      }
+      throw new PushPlanningError(parts.join("\n\n"), conflicts, blockedOverlaps);
+    }
+    const plan = {
+      kind: PUSH_PLAN_KIND,
+      schemaVersion: PUSH_PLAN_SCHEMA_VERSION,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectId,
+      projectName: String(project?.name ?? "(unknown)"),
+      direct: Boolean(opts.direct),
+      unsafeNoBase: documents.some((doc) => doc.baseSource === "live-unsafe"),
+      allowOverlap: Boolean(opts.allowOverlap),
+      documents
+    };
+    if (opts.planOut) writePushPlan(plan, opts.planOut);
+    return plan;
+  } finally {
+    socket.close();
+  }
+}
+function assertHash(value, field) {
+  if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value)) {
+    throw new PushPlanValidationError(`Invalid ${field} in push plan`);
+  }
+}
+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");
+  }
+  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");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const seenLocalPaths = /* @__PURE__ */ new Set();
+  for (const doc of plan.documents) {
+    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");
+    }
+    try {
+      if (workspaceRelativePath(doc.localPath) !== doc.localPath || workspaceRelativePath(doc.docPath) !== doc.docPath) {
+        throw new Error("path is not normalized");
+      }
+    } catch (error) {
+      throw new PushPlanValidationError(
+        `Unsafe or invalid path in push plan: ${error.message}`
+      );
+    }
+    if (seen.has(doc.docId)) throw new PushPlanValidationError(`Duplicate document ${doc.docId} in plan`);
+    seen.add(doc.docId);
+    if (seenLocalPaths.has(doc.localPath)) {
+      throw new PushPlanValidationError(`Duplicate local path ${doc.localPath} in plan`);
+    }
+    seenLocalPaths.add(doc.localPath);
+    assertHash(doc.baseHash, "baseHash");
+    assertHash(doc.localHash, "localHash");
+    assertHash(doc.liveHash, "liveHash");
+    assertHash(doc.rangeFingerprint, "rangeFingerprint");
+    assertHash(doc.expectedHash, "expectedHash");
+    for (const op of doc.ops) {
+      if (!op || !Number.isSafeInteger(op.p) || op.p < 0 || typeof op.i === "string" === (typeof op.d === "string") || typeof (op.i ?? op.d) === "string" && (op.i ?? op.d).length === 0) {
+        throw new PushPlanValidationError(`Invalid operation in ${doc.docPath}`);
+      }
+    }
+    for (const range of doc.activeTrackedRanges) {
+      if (!range || typeof range.id !== "string" || !Number.isSafeInteger(range.op?.p) || range.op.p < 0 || typeof range.op.i === "string" === (typeof range.op.d === "string") || range.metadata !== void 0 && (!range.metadata || typeof range.metadata !== "object")) {
+        throw new PushPlanValidationError(`Invalid active tracked range in ${doc.docPath}`);
+      }
+    }
+    for (const overlap of doc.trackedChangeOverlaps) {
+      if (!overlap || typeof overlap.changeId !== "string" || !validTextEdit(overlap.proposedEdit) || !Number.isSafeInteger(overlap.trackedOp?.p)) {
+        throw new PushPlanValidationError(`Invalid tracked-change overlap in ${doc.docPath}`);
+      }
+    }
+    for (const overlap of doc.commentOverlaps) {
+      if (!overlap || typeof overlap.threadId !== "string" || !Number.isSafeInteger(overlap.position) || overlap.position < 0 || typeof overlap.anchor !== "string" || !validTextEdit(overlap.proposedEdit)) {
+        throw new PushPlanValidationError(`Invalid comment overlap in ${doc.docPath}`);
+      }
+    }
+    if (plan.direct) {
+      if (doc.tcSeed !== null) throw new PushPlanValidationError("Direct plan must not contain tcSeed");
+    } else if (typeof doc.tcSeed !== "string" || !/^[0-9a-f]{18}$/.test(doc.tcSeed)) {
+      throw new PushPlanValidationError(`Invalid tracked-change seed in ${doc.docPath}`);
+    }
+    if (!plan.allowOverlap && doc.trackedChangeOverlaps.length) {
+      throw new PushPlanValidationError("Plan contains blocked tracked-change overlaps");
+    }
+    if (doc.baseSource === "live-unsafe" && doc.baseHash !== doc.liveHash) {
+      throw new PushPlanValidationError(`Unsafe base must equal planned live text in ${doc.docPath}`);
+    }
+  }
+  return plan;
+}
+function validTextEdit(value) {
+  if (!value || typeof value !== "object") return false;
+  const edit = value;
+  return Boolean(
+    Number.isSafeInteger(edit.start) && Number.isSafeInteger(edit.end) && edit.start >= 0 && edit.end >= edit.start && typeof edit.text === "string"
+  );
+}
+function readPushPlan(path, workspaceRoot = process.cwd()) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync6(workspaceReadPath(path, workspaceRoot), "utf8"));
+  } catch (error) {
+    throw new PushPlanValidationError(`Cannot read push plan ${path}: ${error.message}`);
+  }
+  return validatePushPlan(parsed);
+}
+function writePushPlan(plan, path, workspaceRoot = process.cwd()) {
+  validatePushPlan(plan);
+  const target = workspaceWritePath(path, workspaceRoot);
+  mkdirSync7(dirname5(target), { recursive: true });
+  const temp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync7(temp, JSON.stringify(plan, null, 2) + "\n", { mode: 384 });
+    renameSync4(temp, target);
+  } catch (error) {
+    try {
+      unlinkSync5(temp);
+    } catch {
+    }
+    throw error;
+  }
+}
+function trackedChangeIdsForSeed(seed, count) {
+  return Array.from(
+    { length: count },
+    (_, index) => `${seed}${(index + 1).toString(16).padStart(6, "0")}`
+  );
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function overleafSnapshotHash(text) {
+  return createHash3("sha1").update(`blob ${text.length}\0`, "utf8").update(text, "utf8").digest("hex");
+}
+function validatePlannedIntent(planned, base, local, live) {
+  if (sha256(base) !== planned.baseHash) {
+    throw new PushPlanValidationError(`Synchronization base changed for ${planned.docPath}.`);
+  }
+  if (sha256(local) !== planned.localHash) {
+    throw new PushPlanValidationError(`${planned.localPath} changed after planning.`);
+  }
+  if (sha256(live) !== planned.liveHash) {
+    throw new PushPlanValidationError(`${planned.docPath} text changed after planning.`);
+  }
+  const merge = threeWayMerge(base, local, live);
+  if (merge.conflicts.length || merge.text === void 0) {
+    throw new PushPlanValidationError(
+      `${planned.docPath} no longer has the conflict-free intent recorded by the plan.`
+    );
+  }
+  const expected = merge.text;
+  if (stableJson(buildOps(live, expected)) !== 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) {
+  if (state.version !== planned.liveVersion) {
+    throw new PushPlanValidationError(
+      `${planned.docPath} version changed from ${planned.liveVersion} to ${state.version}; create a new plan.`
+    );
+  }
+  if (fingerprintRanges(state.ranges) !== planned.rangeFingerprint) {
+    throw new PushPlanValidationError(
+      `${planned.docPath} comments or tracked ranges changed after planning; create a new plan.`
+    );
+  }
+  const footprint = buildOperationFootprint(live, expected);
+  const activeTrackedRanges = serializeActiveTrackedRanges(state.ranges.changes);
+  const trackedOverlaps = serializeOverlaps(
+    findTrackedChangeOverlaps(state.ranges.changes, footprint)
+  );
+  const commentOverlaps = serializeCommentOverlaps(
+    findCommentOverlaps(state.ranges.comments, footprint)
+  );
+  if (stableJson(activeTrackedRanges) !== stableJson(planned.activeTrackedRanges)) {
+    throw new PushPlanValidationError(
+      `Active tracked-range data is invalid for ${planned.docPath}; create a new plan.`
+    );
+  }
+  if (stableJson(trackedOverlaps) !== stableJson(planned.trackedChangeOverlaps)) {
+    throw new PushPlanValidationError(
+      `Tracked-change overlap data is invalid for ${planned.docPath}; create a new plan.`
+    );
+  }
+  if (trackedOverlaps.length && !allowOverlap) {
+    throw new PushPlanValidationError(
+      `${planned.docPath} operations overlap active tracked changes; create a plan with --allow-overlap only after inspecting them.`
+    );
+  }
+  if (stableJson(commentOverlaps) !== stableJson(planned.commentOverlaps)) {
+    throw new PushPlanValidationError(
+      `Comment-overlap data is invalid for ${planned.docPath}; create a new plan.`
+    );
+  }
+}
+function baseTextForPlan(plan, planned, live, basePath) {
+  if (planned.baseSource === "live-unsafe") {
+    if (!plan.unsafeNoBase) {
+      throw new PushPlanValidationError(`${planned.docPath} uses an unauthorized unsafe base.`);
+    }
+    return live;
+  }
+  const state = loadBaseState(basePath);
+  const saved = state?.projectId === plan.projectId ? state.documents[planned.docId] : void 0;
+  if (!saved || saved.hash !== planned.baseHash || sha256(saved.text) !== planned.baseHash) {
+    throw new PushPlanValidationError(
+      `Synchronization base for ${planned.docPath} changed after planning; create a new plan.`
+    );
+  }
+  return saved.text;
+}
+async function bindPlanDocument(plan, planned, socket, basePath) {
+  let local;
+  try {
+    local = readFileSync6(workspaceReadPath(planned.localPath), "utf8");
+  } catch (error) {
+    throw new PushPlanValidationError(
+      `Cannot read planned local file ${planned.localPath}: ${errorMessage(error)}`
+    );
+  }
+  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);
+  return { plan: planned, state, expected };
+}
+function verifiedTrackedIds(plan, planned, after) {
+  if (plan.direct) return [];
+  const actualIds = new Set((after.ranges.changes ?? []).map((change) => String(change.id)));
+  if (planned.trackedChangeOverlaps.length) {
+    const ids = [...actualIds].filter(
+      (id) => new RegExp(`^${planned.tcSeed}[0-9a-f]{6}$`).test(id)
+    );
+    if (!ids.length) {
+      throw new Error(
+        `Verification failed for ${planned.docPath}: no tracked ranges with seed ${planned.tcSeed} were created.`
+      );
+    }
+    return ids;
+  }
+  const expectedIds = trackedChangeIdsForSeed(planned.tcSeed, planned.ops.length);
+  const missing = expectedIds.filter((id) => !actualIds.has(id));
+  if (missing.length) {
+    throw new Error(
+      `Verification failed for ${planned.docPath}: tracked ranges were not created for ${missing.join(", ")}.`
+    );
+  }
+  return expectedIds;
+}
+function definitelyRejectedApply(error) {
+  const message = errorMessage(error);
+  return message.includes("Overleaf rejected the OT update") || message.includes("Overleaf failed to apply the OT update");
+}
+function initialReceiptDocuments(plan) {
+  return plan.documents.map((doc) => ({
+    docId: doc.docId,
+    docPath: doc.docPath,
+    localPath: doc.localPath,
+    opCount: doc.ops.length,
+    expectedHash: doc.expectedHash,
+    status: "pending",
+    mutationAttempted: false
+  }));
+}
+function pushReceiptNeedsQuarantine(receipt) {
+  if (receipt.status === "ambiguous") return true;
+  if (receipt.status !== "in_progress") return false;
+  const documents = receipt.details?.documents;
+  return Array.isArray(documents) && documents.some(
+    (document) => Boolean(document) && typeof document === "object" && (document.mutationAttempted === true || typeof document.mutationStartedAt === "string")
+  );
+}
+function receiptDocumentIds(receipt) {
+  const documents = receipt.details?.documents;
+  if (!Array.isArray(documents)) return [];
+  return documents.flatMap((document) => {
+    if (!document || typeof document !== "object") return [];
+    const docId = document.docId;
+    return typeof docId === "string" ? [docId] : [];
+  });
+}
+function quarantinedPlanDocuments(plan, receipts) {
+  const plannedIds = new Set(plan.documents.map((document) => document.docId));
+  const disposition = /* @__PURE__ */ new Map();
+  const newestFirst = [...receipts].sort(
+    (a, b) => String(b.receipt.updatedAt ?? "").localeCompare(String(a.receipt.updatedAt ?? ""))
+  );
+  for (const { receipt } of newestFirst) {
+    if (receipt.operation !== "push" || receipt.details?.projectId !== plan.projectId) {
+      continue;
+    }
+    const reconciles = receipt.status === "succeeded" && receipt.details.acknowledgedAmbiguousRetry === true;
+    const quarantines = pushReceiptNeedsQuarantine(receipt);
+    if (!reconciles && !quarantines) continue;
+    for (const docId of receiptDocumentIds(receipt)) {
+      if (plannedIds.has(docId) && !disposition.has(docId)) {
+        disposition.set(docId, reconciles ? "reconciled" : "quarantined");
+      }
+    }
+  }
+  return plan.documents.filter((document) => disposition.get(document.docId) === "quarantined").map((document) => document.docPath);
+}
+function synchronizeLocalAfterRemote(localPath, plannedLocalHash, remoteText, workspaceRoot = process.cwd()) {
+  const localFile = workspaceReadPath(localPath, workspaceRoot);
+  const currentLocal = readFileSync6(localFile, "utf8");
+  if (sha256(currentLocal) !== plannedLocalHash) {
+    throw new Error(`${localPath} changed while the plan was being submitted; local file left untouched.`);
+  }
+  if (currentLocal === remoteText) return {};
+  const timestamp = `${snapshotTimestamp()}-${process.pid}`;
+  const snapshotPath = snapshotRelativePath(timestamp, localPath, workspaceRoot);
+  const snapshotFile = workspaceWritePath(snapshotPath, workspaceRoot);
+  mkdirSync7(dirname5(snapshotFile), { recursive: true });
+  writeFileSync7(snapshotFile, currentLocal, { flag: "wx", mode: 384 });
+  const target = workspaceWritePath(localPath, workspaceRoot);
+  const temp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync7(temp, remoteText, { mode: statSync(localFile).mode & 511 });
+    if (sha256(readFileSync6(localFile, "utf8")) !== plannedLocalHash) {
+      throw new Error(`${localPath} changed while the plan was being submitted; local file left untouched.`);
+    }
+    renameSync4(temp, target);
+  } catch (error) {
+    try {
+      unlinkSync5(temp);
+    } catch {
+    }
+    throw error;
+  }
+  return { snapshotPath };
+}
+async function submitPlan(planOrPath, opts = {}) {
+  const plan = typeof planOrPath === "string" ? readPushPlan(planOrPath) : validatePushPlan(planOrPath);
+  const totalOps = plan.documents.reduce((sum, doc) => sum + doc.ops.length, 0);
+  const planHash = sha256(stableJson(plan));
+  const receiptDocuments = initialReceiptDocuments(plan);
+  let receipt = beginReceipt(
+    "push",
+    {
+      projectId: plan.projectId,
+      direct: plan.direct,
+      planCreatedAt: plan.createdAt,
+      planHash,
+      totalOps,
+      phase: "preflight",
+      plan,
+      documents: receiptDocuments
+    },
+    { receiptsDir: opts.receiptsDir }
+  );
+  const completed = [];
+  const basePath = opts.basePath ?? BASE_STATE_PATH;
+  let opened;
+  let mutationLock;
+  let unknownMutationOutcome = false;
+  let failureStatus;
+  try {
+    if (plan.projectId !== config.projectId) {
+      throw new PushPlanValidationError(
+        `Plan is for project ${plan.projectId}, but this repository is linked to ${config.projectId}.`
+      );
+    }
+    mutationLock = acquireMutationLock(plan.projectId);
+    const priorReceipts = readReceipts(opts.receiptsDir);
+    const quarantinedDocuments = quarantinedPlanDocuments(plan, priorReceipts);
+    if (quarantinedDocuments.length && !opts.allowAmbiguousRetry) {
+      throw new PushPlanValidationError(
+        `A prior push has an unresolved outcome for: ${quarantinedDocuments.join(", ")}. Wait for delayed updates, inspect Overleaf and its receipt, then create a fresh plan. Only after manual reconciliation may you submit with --acknowledge-ambiguous.`
+      );
+    }
+    if (!plan.documents.length) {
+      receipt = updateReceipt(receipt, "skipped", {
+        phase: "complete",
+        outcome: "empty_plan",
+        documents: receiptDocuments
+      });
+      return {
+        projectId: plan.projectId,
+        direct: plan.direct,
+        totalOps,
+        documents: completed,
+        receiptPath: receipt.path
+      };
+    }
+    opened = await openProject();
+    const { socket, project, docs } = opened;
+    const connectedProjectId = String(project?._id ?? config.projectId);
+    if (connectedProjectId !== plan.projectId) {
+      throw new PushPlanValidationError(
+        `Connected project ${connectedProjectId} does not match plan ${plan.projectId}.`
+      );
+    }
+    const docsById = new Map(docs.map((doc) => [doc._id, doc]));
+    for (const planned of plan.documents) {
+      const doc = docsById.get(planned.docId);
+      if (!doc || doc.path !== planned.docPath) {
+        throw new PushPlanValidationError(
+          `Document ${planned.docPath} (${planned.docId}) no longer exists at its planned path.`
+        );
+      }
+    }
+    for (const planned of plan.documents) {
+      await bindPlanDocument(plan, planned, socket, basePath);
+    }
+    receipt = updateReceipt(receipt, "in_progress", {
+      phase: "applying",
+      preflightVerifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...opts.allowAmbiguousRetry && quarantinedDocuments.length ? {
+        acknowledgedAmbiguousRetry: true,
+        reconciledAmbiguousDocuments: quarantinedDocuments
+      } : {},
+      documents: receiptDocuments
+    });
+    for (let index = 0; index < plan.documents.length; index++) {
+      const planned = plan.documents[index];
+      const { state, expected } = await bindPlanDocument(
+        plan,
+        planned,
+        socket,
+        basePath
+      );
+      receiptDocuments[index] = {
+        ...receiptDocuments[index],
+        status: "applying",
+        mutationAttempted: true,
+        mutationStartedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "applying",
+        currentDocument: planned.docPath,
+        documents: receiptDocuments
+      });
+      unknownMutationOutcome = true;
+      let applyError;
+      try {
+        await applyOtUpdateAndWait(socket, planned.docId, {
+          doc: planned.docId,
+          op: planned.ops,
+          v: state.version,
+          meta: plan.direct ? {} : { tc: planned.tcSeed },
+          hash: overleafSnapshotHash(expected)
+        });
+      } catch (error) {
+        applyError = error;
+      }
+      let after;
+      try {
+        after = await joinDoc(socket, planned.docId);
+      } catch (readbackError) {
+        const definitelyRejected = Boolean(applyError && definitelyRejectedApply(applyError));
+        failureStatus = definitelyRejected ? "failed" : "ambiguous";
+        unknownMutationOutcome = !definitelyRejected;
+        receiptDocuments[index] = {
+          ...receiptDocuments[index],
+          status: failureStatus,
+          ...applyError ? { transportError: errorMessage(applyError) } : {},
+          error: `Readback failed: ${errorMessage(readbackError)}`
+        };
+        throw new Error(
+          `${planned.docPath} could not be verified after its update: ${errorMessage(readbackError)}`
+        );
+      }
+      const afterText = after.lines.join("\n");
+      if (afterText !== expected || sha256(afterText) !== planned.expectedHash) {
+        const definitelyRejected = Boolean(applyError && definitelyRejectedApply(applyError));
+        failureStatus = definitelyRejected ? "failed" : "ambiguous";
+        unknownMutationOutcome = !definitelyRejected;
+        receiptDocuments[index] = {
+          ...receiptDocuments[index],
+          status: failureStatus,
+          afterVersion: after.version,
+          ...applyError ? { transportError: errorMessage(applyError) } : {},
+          error: "Overleaf text does not match the planned result"
+        };
+        throw new Error(
+          `Verification failed for ${planned.docPath}: Overleaf text does not match the planned result.`
+        );
+      }
+      let trackedChangeIds;
+      try {
+        trackedChangeIds = verifiedTrackedIds(plan, planned, after);
+      } catch (error) {
+        const ambiguousTransport = Boolean(applyError && !definitelyRejectedApply(applyError));
+        unknownMutationOutcome = ambiguousTransport;
+        failureStatus = ambiguousTransport ? "ambiguous" : "failed";
+        receiptDocuments[index] = {
+          ...receiptDocuments[index],
+          status: failureStatus,
+          afterVersion: after.version,
+          ...applyError ? { transportError: errorMessage(applyError) } : {},
+          error: errorMessage(error)
+        };
+        throw error;
+      }
+      unknownMutationOutcome = false;
+      try {
+        const localSync = synchronizeLocalAfterRemote(
+          planned.localPath,
+          planned.localHash,
+          afterText
+        );
+        if (localSync.snapshotPath) {
+          receiptDocuments[index] = {
+            ...receiptDocuments[index],
+            localSnapshotPath: localSync.snapshotPath
+          };
+        }
+        const base = {
+          docId: planned.docId,
+          path: planned.docPath,
+          text: afterText,
+          hash: planned.expectedHash,
+          version: after.version,
+          rangeFingerprint: fingerprintRanges(after.ranges),
+          fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        mergeBaseDocuments(plan.projectId, [base], basePath);
+      } catch (error) {
+        failureStatus = "failed";
+        receiptDocuments[index] = {
+          ...receiptDocuments[index],
+          status: "remote_verified_local_failed",
+          afterVersion: after.version,
+          trackedChangeIds,
+          ...applyError ? { transportError: errorMessage(applyError) } : {},
+          error: errorMessage(error)
+        };
+        throw new Error(
+          `${planned.docPath} was verified on Overleaf, but local synchronization failed: ` + errorMessage(error)
+        );
+      }
+      const result = {
+        docId: planned.docId,
+        docPath: planned.docPath,
+        version: after.version,
+        hash: planned.expectedHash,
+        trackedChangeIds
+      };
+      completed.push(result);
+      receiptDocuments[index] = {
+        ...receiptDocuments[index],
+        status: "verified",
+        verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        afterVersion: after.version,
+        trackedChangeIds,
+        ...applyError ? { transportError: errorMessage(applyError) } : {}
+      };
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "applying",
+        completedDocuments: completed.map((doc) => doc.docPath),
+        documents: receiptDocuments
+      });
+    }
+    receipt = updateReceipt(receipt, "succeeded", {
+      phase: "complete",
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      completedDocuments: completed.map((doc) => doc.docPath),
+      documents: receiptDocuments
+    });
+    return {
+      projectId: plan.projectId,
+      direct: plan.direct,
+      totalOps,
+      documents: completed,
+      receiptPath: receipt.path
+    };
+  } catch (error) {
+    const status = failureStatus ?? (unknownMutationOutcome ? "ambiguous" : "failed");
+    receipt = updateReceipt(receipt, status, {
+      phase: status === "ambiguous" ? "mutation_outcome_unknown" : "failed",
+      failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      error: errorMessage(error),
+      completedDocuments: completed.map((doc) => doc.docPath),
+      documents: receiptDocuments
+    });
+    throw new PushSubmissionError(
+      `${errorMessage(error)} Audit receipt: ${receipt.path}`,
+      receipt.path,
+      status,
+      receiptDocuments,
+      error
+    );
+  } finally {
+    try {
+      opened?.socket.close();
+    } finally {
+      mutationLock?.release();
+    }
+  }
+}
+function printPlan(plan) {
+  console.log(
+    plan.direct ? "Mode: DIRECT \u2014 plain edits (not marked as suggestions)" : "Mode: SUGGESTIONS \u2014 tracked changes for co-authors to accept/reject"
+  );
+  for (const doc of plan.documents) {
+    const ins = doc.ops.filter((op) => op.i != null).length;
+    const del = doc.ops.filter((op) => op.d != null).length;
+    console.log(
+      `
+${doc.localPath} \u2192 ${doc.docPath} (v${doc.liveVersion}): ${doc.ops.length} op(s), ${ins} ins / ${del} del`
+    );
+    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) {
+      console.log(
+        `  \u2139\uFE0F  touches comment ${overlap.threadId} @ ${overlap.position}: ${JSON.stringify(overlap.anchor)}`
+      );
+    }
+  }
+}
+async function push(opts) {
+  validatePushOptions(opts);
+  if (opts.plan) {
+    const result2 = await submitPlan(opts.plan, {
+      basePath: opts.basePath,
+      receiptsDir: opts.receiptsDir,
+      allowAmbiguousRetry: opts.allowAmbiguousRetry
+    });
+    console.log(
+      `\u2705 Submitted and verified ${result2.totalOps} ${result2.direct ? "direct edit(s)" : "tracked suggestion(s)"} across ${result2.documents.length} file(s).`
+    );
+    console.log(`Audit receipt: ${result2.receiptPath}`);
+    return;
+  }
+  const plan = await createPlan(opts);
+  if (!plan.documents.length) {
+    console.log("Nothing to push \u2014 no unapplied local edits were found.");
+    if (opts.planOut) console.log(`Saved empty plan to ${opts.planOut}.`);
+    return;
+  }
+  printPlan(plan);
+  if (opts.planOut) {
+    console.log(`
+Saved binding plan to ${opts.planOut}; nothing sent to Overleaf.`);
+    return;
+  }
+  if (opts.dryRun) {
+    console.log("\n(dry run \u2014 nothing sent to Overleaf)");
+    return;
+  }
+  const result = await submitPlan(plan, {
+    basePath: opts.basePath,
+    receiptsDir: opts.receiptsDir,
+    allowAmbiguousRetry: opts.allowAmbiguousRetry
+  });
+  console.log(
+    `
+\u2705 Pushed and verified ${result.totalOps} ${result.direct ? "direct edit(s)" : "tracked suggestion(s)"} across ${result.documents.length} file(s).`
+  );
+  console.log(`Audit receipt: ${result.receiptPath}`);
+}
+
+// src/commands/fetch.ts
+import { writeFileSync as writeFileSync8, readFileSync as readFileSync7, mkdirSync as mkdirSync8, existsSync as existsSync4 } from "fs";
+import { dirname as dirname6 } from "path";
+async function fetchDocs(opts) {
+  const { socket, project, docs } = await openProject();
+  let mutationLock;
+  try {
+    if (!opts.dryRun && opts.acquireLock !== false) {
+      mutationLock = acquireMutationLock(config.projectId);
+    }
+    const projectId = String(project?._id ?? config.projectId);
+    if (projectId !== config.projectId) {
+      throw new Error(
+        `Connected project id ${projectId} does not match configured project ${config.projectId}.`
+      );
+    }
+    const requested = opts.file?.replace(/\\/g, "/");
+    const match = requested ? matchDocument(requested, docs) : void 0;
+    const targets = requested ? match ? [match] : [] : docs;
+    if (!targets.length) {
+      if (requested) {
+        throw new Error(
+          `No matching document for "${opts.file}"; use its exact Overleaf project path.`
+        );
+      }
+      console.log("No Overleaf documents found.");
+      return;
+    }
+    const localTargets = targets.map((doc) => ({
+      doc,
+      localPath: workspaceWritePath(doc.path)
+    }));
+    const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const entries = [];
+    for (const { doc, localPath } of localTargets) {
+      const state = await joinDoc(socket, doc._id);
+      const remote = state.lines.join("\n");
+      const local = existsSync4(localPath) ? readFileSync7(localPath, "utf8") : null;
+      entries.push({
+        doc,
+        localPath,
+        remote,
+        local,
+        base: {
+          docId: doc._id,
+          path: doc.path,
+          text: remote,
+          hash: sha256(remote),
+          version: state.version,
+          rangeFingerprint: fingerprintRanges(state.ranges),
+          fetchedAt
+        }
+      });
+    }
+    const changedEntries = entries.filter((entry) => entry.local !== entry.remote);
+    for (const { doc, local, remote } of changedEntries) {
+      const delta = local === null ? "(new file)" : `${local.length} \u2192 ${remote.length} chars`;
+      console.log(`  ${doc.path}  ${delta}`);
+    }
+    let snapshotRoot;
+    if (!opts.dryRun) {
+      for (const entry of changedEntries) {
+        if (entry.local === null) continue;
+        const current = readFileSync7(entry.localPath, "utf8");
+        if (current !== entry.local) {
+          throw new Error(`${entry.doc.path} changed while fetch was reading the project; retry fetch.`);
+        }
+      }
+      const timestamp = snapshotTimestamp();
+      const snapshotTargets = changedEntries.filter((entry) => entry.local !== null).map((entry) => ({
+        entry,
+        snapshotPath: workspaceWritePath(snapshotRelativePath(timestamp, entry.doc.path))
+      }));
+      for (const { entry, snapshotPath } of snapshotTargets) {
+        mkdirSync8(dirname6(snapshotPath), { recursive: true });
+        writeFileSync8(snapshotPath, entry.local, { mode: 384 });
+      }
+      if (snapshotTargets.length) {
+        snapshotRoot = `${SNAPSHOTS_DIR}/${timestamp}`;
+      }
+      for (const { localPath, remote } of changedEntries) {
+        mkdirSync8(dirname6(localPath), { recursive: true });
+        writeFileSync8(localPath, remote);
+      }
+    }
+    if (!opts.dryRun) mergeBaseDocuments(projectId, entries.map((entry) => entry.base));
+    if (!changedEntries.length) {
+      console.log(
+        opts.dryRun ? "Already up to date \u2014 local files match Overleaf." : `Already up to date \u2014 refreshed synchronization base for ${entries.length} file(s).`
+      );
+      return;
+    }
+    if (snapshotRoot) console.log(`Recoverable local snapshot: ${snapshotRoot}`);
+    console.log(
+      opts.dryRun ? `
+(dry run \u2014 ${changedEntries.length} local file(s) would be overwritten; base unchanged)` : `
+\u2705 Fetched ${changedEntries.length} file(s) from Overleaf and saved their synchronization base.`
+    );
+  } finally {
+    try {
+      socket.close();
+    } finally {
+      mutationLock?.release();
+    }
+  }
+}
+
+// src/commands/upload.ts
+import { readFileSync as readFileSync8 } from "fs";
+import { basename as basename2 } from "path";
+function findFolder(folder, wanted, prefix = "") {
+  for (const f of folder?.folders ?? []) {
+    const path = prefix ? `${prefix}/${f.name}` : f.name;
+    if (f.name === wanted || path === wanted) return f;
+    const deeper = findFolder(f, wanted, path);
+    if (deeper) return deeper;
+  }
+  return void 0;
+}
+async function upload(paths, folderName) {
+  const mutationLock = acquireMutationLock(config.projectId);
+  let socket;
+  try {
+    const opened = await openProject();
+    socket = opened.socket;
+    const { project } = opened;
+    const root = project?.rootFolder?.[0];
+    if (!root?._id) throw new Error("could not resolve the project root folder");
+    let folderId = root._id;
+    if (folderName) {
+      const found = findFolder(root, folderName);
+      if (!found) throw new Error(`folder not found in project: ${folderName}`);
+      folderId = found._id;
+    }
+    const csrf = await getCsrfToken();
+    for (const path of paths) {
+      const bytes = readFileSync8(path);
+      const res = await uploadFile(folderId, basename2(path), bytes, csrf);
+      console.log(`\u2705 Uploaded ${path} \u2192 ${res.entity_type} ${res.entity_id}`);
+    }
+  } finally {
+    try {
+      socket?.close();
+    } finally {
+      mutationLock.release();
+    }
+  }
+}
+
+// src/commands/comment.ts
+import { createHash as createHash4, randomBytes as randomBytes2 } from "crypto";
+var DEFAULT_DUPLICATE_WINDOW_MS = 5 * 60 * 1e3;
+function isRecentAttempt(prior, nowMs, windowMs) {
+  const updatedAt = prior.updatedAt ? Date.parse(prior.updatedAt) : Number.NaN;
+  return Number.isFinite(updatedAt) && updatedAt >= nowMs - Math.max(0, windowMs) && updatedAt <= nowMs + 6e4;
+}
+function shouldQuarantineCommentAnchorRetry(prior, nowMs, windowMs) {
+  return (prior.status === "ambiguous" || prior.status === "in_progress" && Boolean(prior.anchorAttemptedAt)) && isRecentAttempt(prior, nowMs, windowMs);
+}
+function shouldQuarantineCommentRetry(prior, nowMs, windowMs) {
+  if (!prior.postAttemptedAt || prior.status !== "ambiguous" && prior.status !== "in_progress") {
+    return false;
+  }
+  return isRecentAttempt(prior, nowMs, windowMs);
+}
+function findCommentRangeByThreadId(ranges, threadId) {
+  if (!Array.isArray(ranges)) return void 0;
+  return ranges.find(
+    (range) => Boolean(range && typeof range === "object" && range.op?.t === threadId)
+  );
+}
+function findCommentRangesAt(ranges, position, anchor) {
+  if (!Array.isArray(ranges)) return [];
+  return ranges.filter(
+    (range) => Boolean(
+      range && typeof range === "object" && range.op?.p === position && range.op?.c === anchor
+    )
+  );
+}
+function commentRangeAnchorsText(range, text, anchor) {
+  const position = range?.op?.p;
+  return Number.isSafeInteger(position) && position >= 0 && range?.op?.c === anchor && text.slice(position, position + anchor.length) === anchor;
+}
+function commentIntentHash(intent) {
+  const canonical = [
+    intent.projectId,
+    intent.docId,
+    intent.anchor,
+    intent.occurrence,
+    intent.message
+  ];
+  return createHash4("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+function rangeThreadId(range) {
+  const value = range?.op?.t;
+  return typeof value === "string" && value ? value : void 0;
+}
+function rangeSnapshot(range) {
+  return range ? {
+    present: true,
+    position: range.op?.p,
+    anchor: range.op?.c,
+    threadId: range.op?.t
+  } : { present: false };
+}
+function threadSnapshot(thread) {
+  const messages = threadMessages(thread);
+  return {
+    exists: Boolean(thread),
+    messageCount: messages.length,
+    messageIds: messages.map(threadMessageId).filter((id) => Boolean(id))
+  };
+}
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function priorThreadIdForIntent(intentHash, receiptsDir) {
+  const prior = readReceipts(receiptsDir).find(
+    ({ receipt }) => receipt.operation === "comment" && receipt.details.intentHash === intentHash
+  );
+  const threadId = prior?.receipt.details.threadId;
+  const anchorAttemptedAt = prior?.receipt.details.anchorAttemptedAt;
+  const postAttemptedAt = prior?.receipt.details.postAttemptedAt;
+  return {
+    ...typeof threadId === "string" ? { threadId } : {},
+    ...prior ? { receiptPath: prior.path } : {},
+    ...prior ? { status: prior.receipt.status, updatedAt: prior.receipt.updatedAt } : {},
+    ...typeof anchorAttemptedAt === "string" ? { anchorAttemptedAt } : {},
+    ...typeof postAttemptedAt === "string" ? { postAttemptedAt } : {}
+  };
+}
+async function commentWithResult(opts) {
+  const { socket, project, docs } = await openProject();
+  let mutationLock;
+  let receipt;
+  try {
+    mutationLock = acquireMutationLock(config.projectId);
+    const doc = opts.docName ? matchDocument(opts.docName.replace(/\\/g, "/"), docs) : docs.find((d) => d._id === project.rootDoc_id) ?? docs[0];
+    if (!doc) throw new Error(`doc not found: ${opts.docName ?? "(root)"}`);
+    const state = await joinDoc(socket, doc._id);
+    const flat = state.lines.join("\n");
+    const nth = Math.max(1, opts.occurrence ?? 1);
+    let p = -1;
+    let from = 0;
+    for (let i = 0; i < nth; i++) {
+      p = flat.indexOf(opts.anchor, from);
+      if (p < 0) break;
+      from = p + 1;
+    }
+    if (p < 0) {
+      throw new Error(`anchor text not found in ${doc.name}: "${opts.anchor}"`);
+    }
+    const duplicateWindowMs = Math.max(
+      0,
+      opts.duplicateWindowMs ?? DEFAULT_DUPLICATE_WINDOW_MS
+    );
+    const intentHash = commentIntentHash({
+      projectId: config.projectId,
+      docId: doc._id,
+      anchor: opts.anchor,
+      occurrence: nth,
+      message: opts.message
+    });
+    const prior = priorThreadIdForIntent(intentHash, opts.receiptsDir);
+    const threads = await getThreads();
+    const commentRanges = state.ranges.comments ?? [];
+    let duplicateRange;
+    if (!opts.force) {
+      const candidates = findCommentRangesAt(commentRanges, p, opts.anchor).filter(
+        (range) => commentRangeAnchorsText(range, flat, opts.anchor)
+      );
+      const priorRange2 = prior.threadId ? findCommentRangeByThreadId(commentRanges, prior.threadId) : void 0;
+      if (priorRange2 && !candidates.includes(priorRange2)) candidates.push(priorRange2);
+      duplicateRange = candidates.find((range) => {
+        const candidateThreadId = rangeThreadId(range);
+        return Boolean(
+          candidateThreadId && findRecentIdenticalMessage(
+            threads[candidateThreadId],
+            opts.message,
+            Date.now(),
+            duplicateWindowMs
+          )
+        );
+      });
+    }
+    if (duplicateRange) {
+      const threadId2 = rangeThreadId(duplicateRange);
+      const duplicateMessage = findRecentIdenticalMessage(
+        threads[threadId2],
+        opts.message,
+        Date.now(),
+        duplicateWindowMs
+      );
+      const messageId = threadMessageId(duplicateMessage);
+      receipt = beginReceipt(
+        "comment",
+        {
+          projectId: config.projectId,
+          docId: doc._id,
+          doc: doc.path,
+          threadId: threadId2,
+          message: opts.message,
+          anchor: opts.anchor,
+          occurrence: nth,
+          position: p,
+          intentHash,
+          force: false,
+          phase: "preflight"
+        },
+        { receiptsDir: opts.receiptsDir }
+      );
+      receipt = updateReceipt(receipt, "skipped", {
+        phase: "complete",
+        outcome: "recent_identical_comment",
+        anchorRange: rangeSnapshot(duplicateRange),
+        ...messageId ? { messageId } : {},
+        verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return {
+        doc: doc.path,
+        threadId: threadId2,
+        anchorCreated: false,
+        messagePosted: false,
+        duplicate: true,
+        ...messageId ? { messageId } : {},
+        receiptPath: receipt.path
+      };
+    }
+    const priorRangeCandidate = !opts.force && prior.threadId ? findCommentRangeByThreadId(commentRanges, prior.threadId) : void 0;
+    const priorRange = commentRangeAnchorsText(priorRangeCandidate, flat, opts.anchor) ? priorRangeCandidate : void 0;
+    const now = Date.now();
+    if (!opts.force && !priorRange && shouldQuarantineCommentAnchorRetry(prior, now, duplicateWindowMs)) {
+      throw new Error(
+        `A recent comment attempt has an ambiguous anchor outcome (${prior.receiptPath}). Inspect Overleaf before retrying, or use force: true explicitly`
+      );
+    }
+    if (!opts.force && priorRange && shouldQuarantineCommentRetry(prior, now, duplicateWindowMs)) {
+      throw new Error(
+        `A recent comment message attempt has an unverified outcome (${prior.receiptPath}). Inspect the thread before retrying, or use force: true explicitly`
+      );
+    }
+    const canResume = Boolean(
+      priorRange && prior.threadId && threadMessages(threads[prior.threadId]).length === 0
+    );
+    const threadId = canResume ? prior.threadId : randomBytes2(12).toString("hex");
+    let anchorCreated = false;
+    let beforeThread = threads[threadId];
+    receipt = beginReceipt(
+      "comment",
+      {
+        projectId: config.projectId,
+        docId: doc._id,
+        doc: doc.path,
+        threadId,
+        message: opts.message,
+        anchor: opts.anchor,
+        occurrence: nth,
+        position: p,
+        sourceVersion: state.version,
+        intentHash,
+        force: opts.force ?? false,
+        phase: "preflight",
+        beforeThread: threadSnapshot(beforeThread),
+        ...canResume && prior.receiptPath ? { resumedFromReceipt: prior.receiptPath } : {}
+      },
+      { receiptsDir: opts.receiptsDir }
+    );
+    let verifiedRange = canResume ? priorRange : void 0;
+    if (!verifiedRange) {
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "creating_anchor",
+        anchorAttemptedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const update = {
+        doc: doc._id,
+        op: [{ p, c: opts.anchor, t: threadId }],
+        v: state.version,
+        meta: {}
+      };
+      let anchorError;
+      try {
+        await applyOtUpdateAndWait(socket, doc._id, update);
+      } catch (error) {
+        anchorError = error;
+      }
+      let afterAnchorText;
+      try {
+        const afterAnchor = await joinDoc(socket, doc._id);
+        afterAnchorText = afterAnchor.lines.join("\n");
+        verifiedRange = findCommentRangeByThreadId(afterAnchor.ranges.comments, threadId);
+      } catch (readbackError) {
+        receipt = updateReceipt(receipt, "ambiguous", {
+          phase: "anchor_outcome_unknown",
+          ...anchorError ? { transportError: errorMessage2(anchorError) } : {},
+          verificationError: errorMessage2(readbackError)
+        });
+        throw new Error(
+          `Comment anchor outcome is ambiguous; inspect ${receipt.path} before retrying`
+        );
+      }
+      if (!commentRangeAnchorsText(verifiedRange, afterAnchorText ?? "", opts.anchor)) {
+        receipt = updateReceipt(receipt, anchorError ? "ambiguous" : "failed", {
+          phase: anchorError ? "anchor_outcome_unknown" : "anchor_unverified",
+          ...anchorError ? { transportError: errorMessage2(anchorError) } : {},
+          anchorRange: rangeSnapshot(verifiedRange)
+        });
+        throw new Error(
+          `Comment anchor was not visible on readback; inspect ${receipt.path} before retrying`
+        );
+      }
+      anchorCreated = true;
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "anchor_verified",
+        anchorVerifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        anchorRange: rangeSnapshot(verifiedRange),
+        ...anchorError ? { transportError: errorMessage2(anchorError) } : {}
+      });
+    } else {
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "anchor_verified",
+        outcome: "resumed_anchor_only_operation",
+        anchorVerifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        anchorRange: rangeSnapshot(verifiedRange)
+      });
+    }
+    let postError;
+    let postAttempted = false;
+    let responseStatus;
+    let returnedMessageId;
+    try {
+      const csrf = await getCsrfToken();
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "posting_message",
+        postAttemptedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      postAttempted = true;
+      const response = await postThreadMessageDetailed(threadId, opts.message, csrf);
+      responseStatus = response.status;
+      returnedMessageId = response.messageId;
+      receipt = updateReceipt(receipt, "in_progress", {
+        phase: "verifying_message",
+        responseStatus,
+        ...returnedMessageId ? { returnedMessageId } : {},
+        ...response.responseBody === void 0 ? {} : { responseBody: response.responseBody }
+      });
+    } catch (error) {
+      postError = error;
+    }
+    const observed = postAttempted ? await observePostedThreadMessage(
+      threadId,
+      beforeThread,
+      opts.message,
+      returnedMessageId,
+      {
+        timeoutMs: opts.verificationTimeoutMs,
+        intervalMs: opts.verificationIntervalMs
+      }
+    ) : { attempts: 0, thread: beforeThread };
+    const observedMessageId = threadMessageId(observed.message);
+    if (!observed.message) {
+      const definitelyRejected = !postAttempted || postError instanceof RestRequestError && postError.status < 500;
+      receipt = updateReceipt(receipt, definitelyRejected ? "failed" : "ambiguous", {
+        phase: !postAttempted ? "message_preflight_failed" : definitelyRejected ? "message_rejected" : "message_outcome_unknown",
+        anchorRange: rangeSnapshot(verifiedRange),
+        ...postError ? { error: errorMessage2(postError) } : {},
+        ...postError instanceof RestRequestError ? { responseStatus: postError.status, responseBody: postError.responseBody } : responseStatus ? { responseStatus } : {},
+        verificationAttempts: observed.attempts,
+        ...observed.lastError ? { verificationError: observed.lastError } : {},
+        afterThread: threadSnapshot(observed.thread)
+      });
+      const outcome = !postAttempted ? "could not be attempted" : definitelyRejected ? "was rejected" : "has an ambiguous outcome";
+      throw new Error(
+        `Comment message ${outcome}; the anchor may remain. Inspect ${receipt.path} before retrying`
+      );
+    }
+    let finalRange;
+    let finalStateText;
+    try {
+      const finalState = await joinDoc(socket, doc._id);
+      finalStateText = finalState.lines.join("\n");
+      finalRange = findCommentRangeByThreadId(finalState.ranges.comments, threadId);
+    } catch (error) {
+      receipt = updateReceipt(receipt, "ambiguous", {
+        phase: "final_anchor_verification_failed",
+        messageId: observedMessageId,
+        messageVerifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        verificationError: errorMessage2(error)
+      });
+      throw new Error(
+        `Comment message exists, but its anchor could not be rechecked. Inspect ${receipt.path}`
+      );
+    }
+    if (!finalRange || !commentRangeAnchorsText(finalRange, finalStateText ?? "", opts.anchor)) {
+      receipt = updateReceipt(receipt, "failed", {
+        phase: "partial_message_without_anchor",
+        ...observedMessageId ? { messageId: observedMessageId } : {},
+        finalAnchorRange: rangeSnapshot(finalRange)
+      });
+      throw new Error(
+        `Comment message exists but anchor ${threadId} is missing; see ${receipt.path}`
+      );
+    }
+    receipt = updateReceipt(receipt, "succeeded", {
+      phase: "complete",
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      verificationAttempts: observed.attempts,
+      finalAnchorRange: rangeSnapshot(finalRange),
+      afterThread: threadSnapshot(observed.thread),
+      ...postError ? { transportError: errorMessage2(postError) } : {},
+      ...observedMessageId ? { messageId: observedMessageId } : {}
+    });
+    return {
+      doc: doc.path,
+      threadId,
+      anchorCreated,
+      messagePosted: true,
+      duplicate: false,
+      ...observedMessageId ? { messageId: observedMessageId } : {},
+      receiptPath: receipt.path
+    };
+  } catch (error) {
+    if (receipt && receipt.receipt.status !== "failed" && receipt.receipt.status !== "ambiguous" && receipt.receipt.status !== "skipped" && receipt.receipt.status !== "succeeded") {
+      receipt = updateReceipt(receipt, "failed", {
+        phase: "command_failed",
+        error: errorMessage2(error)
+      });
+    }
+    throw error;
+  } finally {
+    try {
+      socket.close();
+    } finally {
+      mutationLock?.release();
+    }
+  }
+}
+async function comment(opts) {
+  const result = await commentWithResult(opts);
+  if (result.duplicate) {
+    console.log(
+      `\u21AA\uFE0F  Skipped duplicate comment on "${opts.anchor}" (thread ${result.threadId})`
+    );
+  } else {
+    console.log(
+      `\u2705 Commented on "${opts.anchor}" in ${result.doc} (thread ${result.threadId}` + (result.messageId ? `, message ${result.messageId}` : "") + ")"
+    );
+  }
+}
+
+// src/commands/reply.ts
+var DEFAULT_DUPLICATE_WINDOW_MS2 = 5 * 60 * 1e3;
+function errorMessage3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function threadSnapshot2(thread) {
+  const messages = threadMessages(thread);
+  return {
+    exists: Boolean(thread),
+    messageCount: messages.length,
+    messageIds: messages.map(threadMessageId).filter((id) => Boolean(id))
+  };
+}
+function recentUnverifiedReply(projectId, threadId, message, windowMs, receiptsDir) {
+  const now = Date.now();
+  const earliest = now - windowMs;
+  const prior = readReceipts(receiptsDir).find(({ receipt }) => {
+    const updatedAt = Date.parse(receipt.updatedAt);
+    return receipt.operation === "reply" && (receipt.status === "ambiguous" || receipt.status === "in_progress" && typeof receipt.details.postAttemptedAt === "string") && receipt.details.projectId === projectId && receipt.details.threadId === threadId && receipt.details.message === message && Number.isFinite(updatedAt) && updatedAt >= earliest && updatedAt <= now + 6e4;
+  });
+  return prior ? { path: prior.path, updatedAt: prior.receipt.updatedAt } : void 0;
+}
+async function replyWithResult(threadId, message, options = {}) {
+  const duplicateWindowMs = Math.max(
+    0,
+    options.duplicateWindowMs ?? DEFAULT_DUPLICATE_WINDOW_MS2
+  );
+  let receipt = beginReceipt(
+    "reply",
+    {
+      projectId: config.projectId,
+      threadId,
+      message,
+      force: options.force ?? false,
+      duplicateWindowMs,
+      phase: "preflight"
+    },
+    { receiptsDir: options.receiptsDir }
+  );
+  let beforeThread;
+  let postAttempted = false;
+  let returnedMessageId;
+  let responseStatus;
+  let mutationLock;
+  try {
+    mutationLock = acquireMutationLock(config.projectId);
+    const threads = await getThreads();
+    beforeThread = threads[threadId];
+    receipt = updateReceipt(receipt, "in_progress", {
+      preflightAt: (/* @__PURE__ */ new Date()).toISOString(),
+      before: threadSnapshot2(beforeThread)
+    });
+    if (!beforeThread) throw new Error(`thread ${threadId} not found`);
+    const duplicate = !options.force ? findRecentIdenticalMessage(beforeThread, message, Date.now(), duplicateWindowMs) : void 0;
+    if (duplicate) {
+      const messageId = threadMessageId(duplicate);
+      receipt = updateReceipt(receipt, "skipped", {
+        phase: "complete",
+        outcome: "recent_identical_message",
+        ...messageId ? { messageId } : {},
+        verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return {
+        threadId,
+        posted: false,
+        duplicate: true,
+        ...messageId ? { messageId } : {},
+        receiptPath: receipt.path
+      };
+    }
+    const priorUnverified = !options.force ? recentUnverifiedReply(
+      config.projectId,
+      threadId,
+      message,
+      duplicateWindowMs,
+      options.receiptsDir
+    ) : void 0;
+    if (priorUnverified) {
+      receipt = updateReceipt(receipt, "skipped", {
+        phase: "blocked_by_prior_ambiguity",
+        outcome: "retry_not_sent",
+        priorReceipt: priorUnverified.path,
+        priorUpdatedAt: priorUnverified.updatedAt
+      });
+      throw new Error(
+        `A recent reply attempt has an unverified outcome (${priorUnverified.path}). Inspect the thread before retrying, or use force: true explicitly`
+      );
+    }
+    const csrf = await getCsrfToken();
+    postAttempted = true;
+    receipt = updateReceipt(receipt, "in_progress", {
+      phase: "posting_message",
+      postAttemptedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const response = await postThreadMessageDetailed(threadId, message, csrf);
+    responseStatus = response.status;
+    returnedMessageId = response.messageId;
+    receipt = updateReceipt(receipt, "in_progress", {
+      phase: "verifying_message",
+      responseStatus,
+      ...returnedMessageId ? { returnedMessageId } : {},
+      ...response.responseBody === void 0 ? {} : { responseBody: response.responseBody }
+    });
+    const observed = await observePostedThreadMessage(
+      threadId,
+      beforeThread,
+      message,
+      returnedMessageId,
+      {
+        timeoutMs: options.verificationTimeoutMs,
+        intervalMs: options.verificationIntervalMs
+      }
+    );
+    const observedMessageId = threadMessageId(observed.message);
+    if (!observed.message) {
+      receipt = updateReceipt(receipt, "ambiguous", {
+        phase: "message_unverified",
+        verificationAttempts: observed.attempts,
+        ...observed.lastError ? { verificationError: observed.lastError } : {},
+        after: threadSnapshot2(observed.thread)
+      });
+      throw new Error(
+        `Overleaf accepted the reply request, but the message was not visible on readback. Outcome is ambiguous; inspect ${receipt.path} before retrying`
+      );
+    }
+    receipt = updateReceipt(receipt, "succeeded", {
+      phase: "complete",
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      verificationAttempts: observed.attempts,
+      after: threadSnapshot2(observed.thread),
+      ...observedMessageId ? { messageId: observedMessageId } : {}
+    });
+    return {
+      threadId,
+      posted: true,
+      duplicate: false,
+      ...observedMessageId ? { messageId: observedMessageId } : {},
+      receiptPath: receipt.path
+    };
+  } catch (error) {
+    if (postAttempted && receipt.receipt.status !== "ambiguous") {
+      const observed = await observePostedThreadMessage(
+        threadId,
+        beforeThread,
+        message,
+        returnedMessageId,
+        {
+          timeoutMs: options.verificationTimeoutMs,
+          intervalMs: options.verificationIntervalMs
+        }
+      );
+      const observedMessageId = threadMessageId(observed.message);
+      if (observed.message) {
+        receipt = updateReceipt(receipt, "succeeded", {
+          phase: "complete",
+          outcome: "verified_after_transport_error",
+          transportError: errorMessage3(error),
+          ...responseStatus ? { responseStatus } : {},
+          verificationAttempts: observed.attempts,
+          verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          after: threadSnapshot2(observed.thread),
+          ...observedMessageId ? { messageId: observedMessageId } : {}
+        });
+        return {
+          threadId,
+          posted: true,
+          duplicate: false,
+          ...observedMessageId ? { messageId: observedMessageId } : {},
+          receiptPath: receipt.path
+        };
+      }
+      const definitelyRejected = error instanceof RestRequestError && error.status < 500;
+      receipt = updateReceipt(receipt, definitelyRejected ? "failed" : "ambiguous", {
+        phase: definitelyRejected ? "message_rejected" : "message_outcome_unknown",
+        error: errorMessage3(error),
+        ...error instanceof RestRequestError ? { responseStatus: error.status, responseBody: error.responseBody } : {},
+        verificationAttempts: observed.attempts,
+        ...observed.lastError ? { verificationError: observed.lastError } : {},
+        after: threadSnapshot2(observed.thread)
+      });
+      const qualification = definitelyRejected ? "failed" : "has an ambiguous outcome";
+      throw new Error(
+        `Reply to thread ${threadId} ${qualification}: ${errorMessage3(error)}. Receipt: ${receipt.path}`
+      );
+    }
+    if (receipt.receipt.status !== "ambiguous" && receipt.receipt.status !== "failed" && receipt.receipt.status !== "skipped" && receipt.receipt.status !== "succeeded") {
+      receipt = updateReceipt(receipt, "failed", {
+        phase: "preflight_failed",
+        error: errorMessage3(error)
+      });
+    }
+    throw error;
+  } finally {
+    mutationLock?.release();
+  }
+}
+async function reply(threadId, message, options = {}) {
+  const result = await replyWithResult(threadId, message, options);
+  if (result.duplicate) {
+    console.log(
+      `\u21AA\uFE0F  Skipped duplicate reply in thread ${threadId}` + (result.messageId ? ` (message ${result.messageId})` : "")
+    );
+  } else {
+    console.log(
+      `\u2705 Replied to thread ${threadId}` + (result.messageId ? ` (message ${result.messageId})` : "")
+    );
+  }
+}
+
+// src/commands/resolve.ts
+async function resolve2(threadId, reopen = false) {
+  const mutationLock = acquireMutationLock(config.projectId);
+  let socket;
+  try {
+    const opened = await openProject();
+    socket = opened.socket;
+    const { docs } = opened;
+    let docId;
+    for (const doc of docs) {
+      const state = await joinDoc(socket, doc._id);
+      if ((state.ranges.comments ?? []).some((c) => c.op?.t === threadId)) {
+        docId = doc._id;
+        break;
+      }
+    }
+    if (!docId) {
+      throw new Error(
+        `thread ${threadId} not found in any doc's active comments (already resolved threads may not be locatable this way)`
+      );
+    }
+    const csrf = await getCsrfToken();
+    await setThreadResolved(docId, threadId, reopen, csrf);
+    console.log(`\u2705 Thread ${threadId} ${reopen ? "reopened" : "resolved"}`);
+  } finally {
+    try {
+      socket?.close();
+    } finally {
+      mutationLock.release();
+    }
+  }
+}
+
+// src/commands/delete-comment.ts
+async function deleteComment(threadId) {
+  const mutationLock = acquireMutationLock(config.projectId);
+  let socket;
+  try {
+    const opened = await openProject();
+    socket = opened.socket;
+    const { docs } = opened;
+    let docId;
+    for (const doc of docs) {
+      const state = await joinDoc(socket, doc._id);
+      if ((state.ranges.comments ?? []).some((c) => c.op?.t === threadId)) {
+        docId = doc._id;
+        break;
+      }
+    }
+    if (!docId) throw new Error(`thread ${threadId} not found in any doc's comments`);
+    const csrf = await getCsrfToken();
+    await deleteThread(docId, threadId, csrf);
+    console.log(`\u2705 Deleted comment thread ${threadId}`);
+  } finally {
+    try {
+      socket?.close();
+    } finally {
+      mutationLock.release();
+    }
+  }
+}
+
+// src/commands/delete-message.ts
+async function deleteThreadMessage(messageId, threadId) {
+  const mutationLock = acquireMutationLock(config.projectId);
+  try {
+    const csrf = await getCsrfToken();
+    let tid = threadId;
+    if (!tid) {
+      const threads = await getThreads();
+      for (const [t, v] of Object.entries(threads)) {
+        if (v.messages?.some((m) => m.id === messageId)) {
+          tid = t;
+          break;
+        }
+      }
+    }
+    if (!tid) throw new Error(`message ${messageId} not found in any thread`);
+    await deleteMessage(tid, messageId, csrf);
+    console.log(`\u2705 Deleted message ${messageId} from thread ${tid}`);
+  } finally {
+    mutationLock.release();
+  }
+}
+
+// src/commands/accept.ts
+var VERIFY_ATTEMPTS = 6;
+var VERIFY_INTERVAL_MS = 200;
+function changesFrom(state) {
+  return state.ranges.changes ?? [];
+}
+async function verifyAcceptedDocument(socket, docId, changeIds) {
+  let last;
+  let lastError;
+  for (let attempt = 0; attempt < VERIFY_ATTEMPTS; attempt++) {
+    try {
+      last = await joinDoc(socket, docId);
+      lastError = void 0;
+      if (!remainingChangeIds(changesFrom(last), changeIds).length) return last;
+    } catch (error) {
+      lastError = error;
+    }
+    if (attempt + 1 < VERIFY_ATTEMPTS) {
+      await new Promise((resolve3) => setTimeout(resolve3, VERIFY_INTERVAL_MS));
+    }
+  }
+  if (!last) throw lastError ?? new Error(`could not read back document ${docId}`);
+  return last;
+}
+function errorMessage4(error) {
+  return error instanceof Error ? error.message : String(error);
 }
-
-// src/commands/accept.ts
 async function accept(changeIds) {
+  const requestedIds = uniqueChangeIds(changeIds);
+  if (!requestedIds.length) throw new Error("no tracked change ids requested");
   const { socket, docs } = await openProject();
-  const byDoc = /* @__PURE__ */ new Map();
-  for (const doc of docs) {
-    const state = await joinDoc(socket, doc._id);
-    const here = (state.ranges.changes ?? []).filter((c) => changeIds.includes(c.id)).map((c) => c.id);
-    if (here.length) byDoc.set(doc._id, here);
-  }
-  socket.close();
-  const found = [...byDoc.values()].flat();
-  const missing = changeIds.filter((id) => !found.includes(id));
-  if (missing.length) console.log(`\u26A0\uFE0F  not found (already accepted/rejected?): ${missing.join(", ")}`);
-  if (!found.length) throw new Error("no matching tracked changes found");
-  const csrf = await getCsrfToken();
-  for (const [docId, ids] of byDoc) await acceptChanges(docId, ids, csrf);
-  console.log(`\u2705 Accepted ${found.length} tracked change(s)`);
+  let mutationLock;
+  const found = /* @__PURE__ */ new Set();
+  const locations = /* @__PURE__ */ new Map();
+  const verifiedDocs = /* @__PURE__ */ new Set();
+  const result = {
+    action: "accept",
+    requestedIds,
+    foundIds: [],
+    missingIds: [],
+    attemptedIds: [],
+    verifiedAbsentIds: [],
+    documents: [],
+    verified: false
+  };
+  const refreshVerifiedIds = () => {
+    const verified = new Set(result.missingIds);
+    for (const id of result.foundIds) {
+      const everyKnownLocationVerified = [...locations.values()].filter((location) => location.ids.includes(id)).every((location) => verifiedDocs.has(location.doc._id));
+      if (everyKnownLocationVerified) verified.add(id);
+    }
+    result.verifiedAbsentIds = requestedIds.filter((id) => verified.has(id));
+    result.verified = result.verifiedAbsentIds.length === requestedIds.length;
+  };
+  try {
+    mutationLock = acquireMutationLock(config.projectId);
+    for (const doc of docs) {
+      const state = await joinDoc(socket, doc._id);
+      const ids = remainingChangeIds(changesFrom(state), requestedIds);
+      if (!ids.length) continue;
+      locations.set(doc._id, { doc, ids });
+      for (const id of ids) found.add(id);
+    }
+    result.foundIds = requestedIds.filter((id) => found.has(id));
+    result.missingIds = requestedIds.filter((id) => !found.has(id));
+    refreshVerifiedIds();
+    if (result.missingIds.length) {
+      console.log(
+        `\u26A0\uFE0F  not found (already accepted/rejected?): ${result.missingIds.join(", ")}`
+      );
+    }
+    if (!result.foundIds.length) {
+      throw new Error("no matching tracked changes found");
+    }
+    let csrf;
+    try {
+      csrf = await getCsrfToken();
+    } catch (error) {
+      throw new TrackedChangeMutationError(
+        `Could not obtain a CSRF token before accepting tracked changes: ${errorMessage4(error)}`,
+        result,
+        error
+      );
+    }
+    for (const { doc, ids } of locations.values()) {
+      let before;
+      try {
+        before = await joinDoc(socket, doc._id);
+      } catch (error) {
+        const outcome2 = {
+          docId: doc._id,
+          docPath: doc.path,
+          requestedIds: ids,
+          attemptedIds: [],
+          fragmentCount: 0,
+          status: "failed",
+          remainingIds: ids,
+          error: errorMessage4(error)
+        };
+        result.documents.push(outcome2);
+        refreshVerifiedIds();
+        throw new TrackedChangeMutationError(
+          `Could not read ${doc.path} before accepting tracked changes`,
+          result,
+          error
+        );
+      }
+      const beforeChanges = changesFrom(before);
+      const presentIds = remainingChangeIds(beforeChanges, ids);
+      const fragmentCount = beforeChanges.filter((range) => presentIds.includes(range.id)).length;
+      if (!presentIds.length) {
+        result.documents.push({
+          docId: doc._id,
+          docPath: doc.path,
+          requestedIds: ids,
+          attemptedIds: [],
+          fragmentCount: 0,
+          beforeVersion: before.version,
+          afterVersion: before.version,
+          status: "already-absent",
+          remainingIds: []
+        });
+        verifiedDocs.add(doc._id);
+        refreshVerifiedIds();
+        continue;
+      }
+      const outcome = {
+        docId: doc._id,
+        docPath: doc.path,
+        requestedIds: ids,
+        attemptedIds: presentIds,
+        fragmentCount,
+        beforeVersion: before.version,
+        status: "failed",
+        remainingIds: presentIds
+      };
+      result.documents.push(outcome);
+      result.attemptedIds = uniqueChangeIds([...result.attemptedIds, ...presentIds]);
+      let mutationError;
+      try {
+        await acceptChanges(doc._id, presentIds, csrf);
+      } catch (error) {
+        mutationError = error;
+      }
+      let after;
+      let readbackError;
+      try {
+        after = await verifyAcceptedDocument(socket, doc._id, ids);
+      } catch (error) {
+        readbackError = error;
+      }
+      if (after) {
+        outcome.afterVersion = after.version;
+        outcome.remainingIds = remainingChangeIds(changesFrom(after), ids);
+      }
+      if (after && !outcome.remainingIds.length) {
+        outcome.status = "verified";
+        if (mutationError) outcome.error = `transport warning: ${errorMessage4(mutationError)}`;
+        verifiedDocs.add(doc._id);
+        refreshVerifiedIds();
+        continue;
+      }
+      const reasons = [];
+      if (mutationError) reasons.push(errorMessage4(mutationError));
+      if (readbackError) reasons.push(`readback failed: ${errorMessage4(readbackError)}`);
+      if (outcome.remainingIds.length) {
+        reasons.push(`change ids still present: ${outcome.remainingIds.join(", ")}`);
+      }
+      outcome.error = reasons.join("; ") || "acceptance could not be verified";
+      refreshVerifiedIds();
+      throw new TrackedChangeMutationError(
+        `Accepted changes in ${doc.path} could not be verified: ${outcome.error}`,
+        result,
+        mutationError ?? readbackError
+      );
+    }
+    refreshVerifiedIds();
+    if (!result.verified) {
+      throw new TrackedChangeMutationError(
+        `Acceptance incomplete; unverified ids: ${requestedIds.filter((id) => !result.verifiedAbsentIds.includes(id)).join(", ")}`,
+        result
+      );
+    }
+    console.log(
+      `\u2705 Accepted ${result.foundIds.length} tracked change(s); verified by readback`
+    );
+    return result;
+  } finally {
+    try {
+      socket.close();
+    } finally {
+      mutationLock?.release();
+    }
+  }
 }
 
 // src/commands/reject.ts
+var VERIFY_ATTEMPTS2 = 6;
+var VERIFY_INTERVAL_MS2 = 200;
+function changesFrom2(state) {
+  return state.ranges.changes ?? [];
+}
+async function verifyRejectedDocument(socket, docId, changeIds, expectedText) {
+  let last;
+  let lastError;
+  for (let attempt = 0; attempt < VERIFY_ATTEMPTS2; attempt++) {
+    try {
+      last = await joinDoc(socket, docId);
+      lastError = void 0;
+      const remaining = remainingChangeIds(changesFrom2(last), changeIds);
+      if (!remaining.length && last.lines.join("\n") === expectedText) return last;
+    } catch (error) {
+      lastError = error;
+    }
+    if (attempt + 1 < VERIFY_ATTEMPTS2) {
+      await new Promise((resolve3) => setTimeout(resolve3, VERIFY_INTERVAL_MS2));
+    }
+  }
+  if (!last) throw lastError ?? new Error(`could not read back document ${docId}`);
+  return last;
+}
+function errorMessage5(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 async function reject(changeIds) {
+  const requestedIds = uniqueChangeIds(changeIds);
+  if (!requestedIds.length) throw new Error("no tracked change ids requested");
   const { socket, docs } = await openProject();
-  const docOf = /* @__PURE__ */ new Map();
-  for (const doc of docs) {
-    const state = await joinDoc(socket, doc._id);
-    for (const c of state.ranges.changes ?? []) {
-      if (changeIds.includes(c.id)) docOf.set(c.id, doc._id);
+  let mutationLock;
+  const found = /* @__PURE__ */ new Set();
+  const locations = /* @__PURE__ */ new Map();
+  const verifiedDocs = /* @__PURE__ */ new Set();
+  const result = {
+    action: "reject",
+    requestedIds,
+    foundIds: [],
+    missingIds: [],
+    attemptedIds: [],
+    verifiedAbsentIds: [],
+    documents: [],
+    verified: false
+  };
+  const refreshVerifiedIds = () => {
+    const verified = new Set(result.missingIds);
+    for (const id of result.foundIds) {
+      const everyKnownLocationVerified = [...locations.values()].filter((location) => location.ids.includes(id)).every((location) => verifiedDocs.has(location.doc._id));
+      if (everyKnownLocationVerified) verified.add(id);
     }
-  }
-  let rejected = 0;
-  for (const id of changeIds) {
-    const docId = docOf.get(id);
-    if (!docId) {
-      console.log(`\u26A0\uFE0F  not found (already accepted/rejected?): ${id}`);
-      continue;
+    result.verifiedAbsentIds = requestedIds.filter((id) => verified.has(id));
+    result.verified = result.verifiedAbsentIds.length === requestedIds.length;
+  };
+  try {
+    mutationLock = acquireMutationLock(config.projectId);
+    for (const doc of docs) {
+      const state = await joinDoc(socket, doc._id);
+      const ids = remainingChangeIds(changesFrom2(state), requestedIds);
+      if (!ids.length) continue;
+      locations.set(doc._id, { doc, ids });
+      for (const id of ids) found.add(id);
+    }
+    result.foundIds = requestedIds.filter((id) => found.has(id));
+    result.missingIds = requestedIds.filter((id) => !found.has(id));
+    refreshVerifiedIds();
+    if (result.missingIds.length) {
+      console.log(
+        `\u26A0\uFE0F  not found (already accepted/rejected?): ${result.missingIds.join(", ")}`
+      );
+    }
+    if (!result.foundIds.length) {
+      throw new Error("no matching tracked changes found");
+    }
+    for (const { doc, ids } of locations.values()) {
+      let before;
+      try {
+        before = await joinDoc(socket, doc._id);
+      } catch (error) {
+        const outcome2 = {
+          docId: doc._id,
+          docPath: doc.path,
+          requestedIds: ids,
+          attemptedIds: [],
+          fragmentCount: 0,
+          status: "failed",
+          remainingIds: ids,
+          error: errorMessage5(error)
+        };
+        result.documents.push(outcome2);
+        refreshVerifiedIds();
+        throw new TrackedChangeMutationError(
+          `Could not read ${doc.path} before rejecting tracked changes`,
+          result,
+          error
+        );
+      }
+      const presentIds = remainingChangeIds(changesFrom2(before), ids);
+      if (!presentIds.length) {
+        result.documents.push({
+          docId: doc._id,
+          docPath: doc.path,
+          requestedIds: ids,
+          attemptedIds: [],
+          fragmentCount: 0,
+          beforeVersion: before.version,
+          afterVersion: before.version,
+          status: "already-absent",
+          textVerified: true,
+          remainingIds: []
+        });
+        verifiedDocs.add(doc._id);
+        refreshVerifiedIds();
+        continue;
+      }
+      let plan;
+      try {
+        plan = buildRejectionPlan(before.lines.join("\n"), changesFrom2(before), presentIds);
+      } catch (error) {
+        const outcome2 = {
+          docId: doc._id,
+          docPath: doc.path,
+          requestedIds: ids,
+          attemptedIds: [],
+          fragmentCount: 0,
+          beforeVersion: before.version,
+          status: "failed",
+          remainingIds: presentIds,
+          error: errorMessage5(error)
+        };
+        result.documents.push(outcome2);
+        refreshVerifiedIds();
+        throw new TrackedChangeMutationError(
+          `Could not safely plan rejection in ${doc.path}: ${errorMessage5(error)}`,
+          result,
+          error
+        );
+      }
+      const outcome = {
+        docId: doc._id,
+        docPath: doc.path,
+        requestedIds: ids,
+        attemptedIds: presentIds,
+        fragmentCount: plan.fragmentCount,
+        beforeVersion: before.version,
+        status: "failed",
+        textVerified: false,
+        remainingIds: presentIds
+      };
+      result.documents.push(outcome);
+      result.attemptedIds = uniqueChangeIds([...result.attemptedIds, ...presentIds]);
+      let mutationError;
+      try {
+        await applyOtUpdateAndWait(socket, doc._id, {
+          doc: doc._id,
+          op: plan.operations,
+          v: before.version,
+          meta: {}
+        });
+      } catch (error) {
+        mutationError = error;
+      }
+      let after;
+      let readbackError;
+      try {
+        after = await verifyRejectedDocument(socket, doc._id, presentIds, plan.expectedText);
+      } catch (error) {
+        readbackError = error;
+      }
+      if (after) {
+        outcome.afterVersion = after.version;
+        outcome.remainingIds = remainingChangeIds(changesFrom2(after), presentIds);
+        outcome.textVerified = after.lines.join("\n") === plan.expectedText;
+      }
+      if (after && !outcome.remainingIds.length && outcome.textVerified) {
+        outcome.status = "verified";
+        if (mutationError) outcome.error = `transport warning: ${errorMessage5(mutationError)}`;
+        verifiedDocs.add(doc._id);
+        refreshVerifiedIds();
+        continue;
+      }
+      const reasons = [];
+      if (mutationError) reasons.push(errorMessage5(mutationError));
+      if (readbackError) reasons.push(`readback failed: ${errorMessage5(readbackError)}`);
+      if (outcome.remainingIds.length) {
+        reasons.push(`change ids still present: ${outcome.remainingIds.join(", ")}`);
+      }
+      if (after && !outcome.textVerified) {
+        reasons.push("final document text did not match the planned rejection");
+      }
+      outcome.error = reasons.join("; ") || "rejection could not be verified";
+      refreshVerifiedIds();
+      throw new TrackedChangeMutationError(
+        `Rejected changes in ${doc.path} could not be verified: ${outcome.error}`,
+        result,
+        mutationError ?? readbackError
+      );
     }
-    const state = await joinDoc(socket, docId);
-    const c = (state.ranges.changes ?? []).find((x) => x.id === id);
-    if (!c) continue;
-    const op = typeof c.op?.i === "string" ? { p: c.op.p, d: c.op.i } : { p: c.op.p, i: c.op.d };
-    const update = { doc: docId, op: [op], v: state.version, meta: {} };
-    const ack = await socket.emit("applyOtUpdate", [docId, update], 15e3);
-    if (ack?.[0]) {
+    refreshVerifiedIds();
+    if (!result.verified) {
+      throw new TrackedChangeMutationError(
+        `Rejection incomplete; unverified ids: ${requestedIds.filter((id) => !result.verifiedAbsentIds.includes(id)).join(", ")}`,
+        result
+      );
+    }
+    console.log(
+      `\u2705 Rejected ${result.foundIds.length} tracked change(s) (${result.documents.reduce((count, doc) => count + doc.fragmentCount, 0)} range fragment(s)); verified by readback`
+    );
+    return result;
+  } finally {
+    try {
       socket.close();
-      throw new Error(`Overleaf rejected the inverse op for ${id}: ${JSON.stringify(ack[0])}`);
+    } finally {
+      mutationLock?.release();
     }
-    rejected++;
   }
-  socket.close();
-  if (!rejected) throw new Error("no matching tracked changes found");
-  console.log(`\u2705 Rejected ${rejected} tracked change(s)`);
 }
 
 // src/commands/login.ts
@@ -893,20 +3626,27 @@ async function captureCookieViaBrowser(baseUrl) {
 
 // src/commands/link.ts
 function link(projectId, baseUrl) {
-  const path = saveProjectConfig({ projectId, ...baseUrl ? { baseUrl } : {} });
-  console.log(`\u2705 Linked this repo to Overleaf project ${projectId} \u2192 ${path}`);
-  console.log("   (safe to commit \u2014 it contains no secrets.)");
+  const mutationLock = acquireMutationLock(projectId);
+  try {
+    const path = saveProjectConfig({ projectId, ...baseUrl ? { baseUrl } : {} });
+    console.log(`\u2705 Linked this repo to Overleaf project ${projectId} \u2192 ${path}`);
+    console.log("   (safe to commit \u2014 it contains no secrets.)");
+  } finally {
+    mutationLock.release();
+  }
 }
 
 // src/cli.ts
 function getFlag(name) {
   const i = process.argv.indexOf(`--${name}`);
-  return i >= 0 ? process.argv[i + 1] : void 0;
+  const value = i >= 0 ? process.argv[i + 1] : void 0;
+  return value && !value.startsWith("--") ? value : void 0;
 }
 function getAll(name) {
   const out = [];
   process.argv.forEach((a, i) => {
-    if (a === `--${name}` && process.argv[i + 1]) out.push(process.argv[i + 1]);
+    const value = process.argv[i + 1];
+    if (a === `--${name}` && value && !value.startsWith("--")) out.push(value);
   });
   return out.flatMap((v) => v.split(",")).map((s) => s.trim()).filter(Boolean);
 }
@@ -917,22 +3657,82 @@ function usage() {
   console.log("  link --project <id>                       Link this repo to an Overleaf project\n");
   console.log("Read:");
   console.log("  pull [--out <dir>]                        Comments + tracked changes \u2192 sidecar\n");
-  console.log("Content (replaces the git bridge \u2014 review-safe):");
-  console.log("  fetch [--file <f>] [--dry-run]            Overleaf text \u2192 local files (read-only)");
+  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("  review submit --plan <plan.json>          Validate, apply, and verify that plan");
+  console.log("       [--acknowledge-ambiguous]             Continue only after manual reconciliation\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");
   console.log("Comments:");
-  console.log("  comment --anchor <text> --message <text> [--doc <name>] [--nth <n>]");
-  console.log("  reply --thread <id> --message <text>      Reply to an existing thread");
+  console.log("  comment --anchor <text> --message <text> [--doc <name>] [--nth <n>] [--force]");
+  console.log("  reply --thread <id> --message <text> [--force]");
   console.log("  resolve --thread <id> [--reopen]          Resolve/reopen a thread");
   console.log("  delete-comment --thread <id>              Delete a whole thread");
   console.log("  delete-message --message-id <id>          Delete a single message\n");
   console.log("Tracked changes:");
   console.log("  push [--file <f>] [--doc <name>] [--direct] [--dry-run]");
+  console.log("       [--plan-out <plan.json> | --plan <plan.json>] [--allow-overlap]");
+  console.log("       [--acknowledge-ambiguous]  (after manually reconciling a prior uncertain push)");
+  console.log("       [--unsafe-no-base]  (legacy escape hatch; disables three-way protection)");
   console.log("        Send local edits as tracked suggestions (--direct = plain edits)");
   console.log("  accept --change <id> [--change <id> \u2026]    Accept collaborators\u2019 changes");
   console.log("  reject --change <id> [--change <id> \u2026]    Reject collaborators\u2019 changes");
   console.log("\n(thread/change ids come from `pull`; --change accepts comma-separated lists too)");
 }
+async function pullAndReport(out, options = {}) {
+  const data = await pull(out, options);
+  console.log(
+    `Pulled ${data.comments.length} comment(s) and ${data.changes.length} tracked change(s) from "${data.project}" \u2192 ${out}/`
+  );
+}
+function pushOptions() {
+  return {
+    file: getFlag("file"),
+    docName: getFlag("doc"),
+    direct: process.argv.includes("--direct"),
+    dryRun: process.argv.includes("--dry-run"),
+    unsafeNoBase: process.argv.includes("--unsafe-no-base"),
+    allowOverlap: process.argv.includes("--allow-overlap"),
+    planOut: getFlag("plan-out"),
+    plan: getFlag("plan"),
+    allowAmbiguousRetry: process.argv.includes("--acknowledge-ambiguous")
+  };
+}
+async function mutateTrackedChanges(action, ids, mutate) {
+  let receipt = beginReceipt(action, {
+    projectId: config.projectId,
+    requestedIds: ids,
+    phase: "preflight"
+  });
+  try {
+    receipt = updateReceipt(receipt, "in_progress", {
+      phase: "mutating",
+      mutationStartedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const result = await mutate(ids);
+    receipt = updateReceipt(receipt, "succeeded", {
+      phase: "complete",
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      result
+    });
+    console.log(`Audit receipt: ${receipt.path}`);
+  } catch (error) {
+    const result = error instanceof TrackedChangeMutationError ? error.result : void 0;
+    const outcomeUnknown = Boolean(result?.attemptedIds.length && !result.verified);
+    receipt = updateReceipt(receipt, outcomeUnknown ? "ambiguous" : "failed", {
+      phase: outcomeUnknown ? "outcome_unknown" : "failed",
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      error: error instanceof Error ? error.message : String(error),
+      ...result ? { result } : {}
+    });
+    throw new Error(
+      `${error instanceof Error ? error.message : String(error)}. Audit receipt: ${receipt.path}`,
+      { cause: error }
+    );
+  }
+}
 async function main() {
   const cmd = process.argv[2];
   switch (cmd) {
@@ -951,20 +3751,43 @@ async function main() {
     }
     case "pull": {
       const out = getFlag("out") ?? ".overleaf";
-      const data = await pull(out);
-      console.log(
-        `Pulled ${data.comments.length} comment(s) and ${data.changes.length} tracked change(s) from "${data.project}" \u2192 ${out}/`
-      );
+      await pullAndReport(out);
       break;
     }
     case "push":
-      await push({
-        file: getFlag("file"),
-        docName: getFlag("doc"),
-        direct: process.argv.includes("--direct"),
-        dryRun: process.argv.includes("--dry-run")
-      });
+      await push(pushOptions());
+      break;
+    case "review": {
+      const reviewCommand = process.argv[3];
+      if (process.argv.includes("--through")) {
+        fail("Section-scoped --through is not implemented; no review action was performed.");
+      }
+      if (reviewCommand === "start") {
+        const file = getFlag("file") ?? getFlag("doc");
+        const mutationLock = acquireMutationLock(config.projectId);
+        try {
+          await fetchDocs({ file, dryRun: false, acquireLock: false });
+          await pullAndReport(getFlag("out") ?? ".overleaf", { acquireLock: false });
+        } finally {
+          mutationLock.release();
+        }
+      } else if (reviewCommand === "plan") {
+        const out = getFlag("out");
+        if (!out) fail("review plan requires --out <plan.json>");
+        await push({ ...pushOptions(), plan: void 0, planOut: out, dryRun: true });
+      } else if (reviewCommand === "submit") {
+        const plan = getFlag("plan");
+        if (!plan) fail("review submit requires --plan <plan.json>");
+        await push({
+          plan,
+          allowAmbiguousRetry: process.argv.includes("--acknowledge-ambiguous")
+        });
+      } else {
+        usage();
+        fail("review requires start, plan, or submit");
+      }
       break;
+    }
     case "fetch":
       await fetchDocs({ file: getFlag("file"), dryRun: process.argv.includes("--dry-run") });
       break;
@@ -988,20 +3811,30 @@ async function main() {
       const message = getFlag("message");
       if (!anchor || !message) fail("comment requires --anchor <text> and --message <text>");
       const nthRaw = getFlag("nth");
-      await comment({ docName: getFlag("doc"), anchor, message, occurrence: nthRaw ? Number(nthRaw) : void 0 });
+      const occurrence = nthRaw === void 0 ? void 0 : Number(nthRaw);
+      if (occurrence !== void 0 && (!Number.isSafeInteger(occurrence) || occurrence < 1)) {
+        fail("comment --nth must be a positive integer");
+      }
+      await comment({
+        docName: getFlag("doc"),
+        anchor,
+        message,
+        occurrence,
+        force: process.argv.includes("--force")
+      });
       break;
     }
     case "reply": {
       const thread = getFlag("thread");
       const message = getFlag("message");
       if (!thread || !message) fail("reply requires --thread <id> and --message <text>");
-      await reply(thread, message);
+      await reply(thread, message, { force: process.argv.includes("--force") });
       break;
     }
     case "resolve": {
       const thread = getFlag("thread");
       if (!thread) fail("resolve requires --thread <id>");
-      await resolve(thread, process.argv.includes("--reopen"));
+      await resolve2(thread, process.argv.includes("--reopen"));
       break;
     }
     case "delete-comment": {
@@ -1019,13 +3852,13 @@ async function main() {
     case "accept": {
       const ids = getAll("change");
       if (!ids.length) fail("accept requires --change <id>");
-      await accept(ids);
+      await mutateTrackedChanges("accept", ids, accept);
       break;
     }
     case "reject": {
       const ids = getAll("change");
       if (!ids.length) fail("reject requires --change <id>");
-      await reject(ids);
+      await mutateTrackedChanges("reject", ids, reject);
       break;
     }
     default: