isomorphic-jj 1.8.0 → 1.9.2

package/src/api/repository.js

@@ -16,8 +16,9 @@ import { BackgroundOps } from '../core/background-ops.js';
 import { UserConfig } from '../core/user-config.js';
 import { IsomorphicGitBackend } from '../backend/isomorphic-git-backend.js';
 import { JJError } from '../utils/errors.js';
-import { generateChangeId } from '../utils/id-generation.js';
-import path from 'path';
+import { generateChangeId, randomHex } from '../utils/id-generation.js';
+import * as path from '../utils/posix-path.js';
+import { mkdirp } from '../utils/mkdirp.js';
 
 /**
  * Create and initialize a JJ repository instance
@@ -116,7 +117,7 @@ export async function createJJ(options) {
             break;
           }
 
-          const content = await fs.promises.readFile(fullPath, 'utf-8');
+          const content = await fs.promises.readFile(fullPath, 'utf8');
           fileSnapshot[filePath] = content;
           totalSnapshotSize += stats.size;
         } catch (error) {
@@ -130,6 +131,266 @@ export async function createJJ(options) {
     return fileSnapshot;
   };
 
+  /**
+   * Fully sync the working directory to a target file snapshot: writes
+   * every file the target has (create/update), AND deletes every currently
+   * tracked file the target does NOT have.
+   *
+   * Both edit() and new() used to only overlay the target's files on top of
+   * whatever was already on disk, so a file that existed in the previously
+   * checked-out change but not in the target leaked into the next
+   * snapshot — see issue #30. undo()/redo() had the same gap restoring
+   * file state — see issue #29. This is the one place that does it
+   * correctly, used by all four.
+   *
+   * @param {Record<string, string>} targetSnapshot - path -> file content
+   * @returns {Promise<void>}
+   */
+  const syncWorkingCopyFiles = async (targetSnapshot) => {
+    const snapshot = targetSnapshot || {};
+    const currentFiles = await workingCopy.listFiles();
+
+    // Remove files that aren't part of the target.
+    for (const filePath of currentFiles) {
+      if (!(filePath in snapshot)) {
+        try {
+          const fullPath = path.join(dir, filePath);
+          await fs.promises.unlink(fullPath);
+        } catch (error) {
+          // Already gone / inaccessible — fine, we just want it absent.
+        }
+        await workingCopy.untrackFile(filePath);
+      }
+    }
+
+    // Write/update every file the target has.
+    for (const [filePath, content] of Object.entries(snapshot)) {
+      const fullPath = path.join(dir, filePath);
+      const pathParts = filePath.split('/');
+      if (pathParts.length > 1) {
+        const fullDirPath = path.join(dir, pathParts.slice(0, -1).join('/'));
+        await mkdirp(fs, fullDirPath);
+      }
+      await fs.promises.writeFile(fullPath, content, 'utf8');
+
+      const stats = await fs.promises.stat(fullPath);
+      await workingCopy.trackFile(filePath, {
+        mtime: stats.mtime,
+        size: stats.size,
+        mode: stats.mode,
+      });
+    }
+  };
+
+  /**
+   * Compute the ChangeGraph/file/conflicts state that existed right after
+   * `landingOp` finished — i.e. what undo()/redo()/operations.restore()
+   * need to re-establish when winding the repository forward or back to
+   * that point (see issue #29).
+   *
+   * Every operation that mutates EXISTING change records in place records
+   * (additively — most operations touch none of this and that's fine,
+   * there's nothing to reverse for them):
+   *   - changeSnapshot: { [changeId]: fullRecordBeforeThisOpRan }
+   *   - view.fileSnapshot: on-disk file state right BEFORE this op ran
+   *   - conflictsSnapshot: ConflictModel state right BEFORE this op ran
+   *
+   * Deliberately NOT reverted: changes an operation newly *created* (via
+   * graph.addChange() — new(), squash()'s synthetic empty working-copy
+   * change, ...). Undoing their creation only un-refs them (restores the
+   * working-copy pointer/heads that made them reachable) — it does not
+   * delete the change record — matching real jj, where an "unreachable"
+   * change stays resolvable by its change id (hidden, not gone) until
+   * explicitly gc'd, and this package's own history-editing tests rely on
+   * exactly that: rebasing onto a change created by a since-undone new()
+   * must still work.
+   *
+   * "The state right after landingOp" is therefore exactly what the FIRST
+   * operation after landingOp recorded as ITS "before" state, merged across
+   * every operation between landingOp and the current head in case
+   * different operations touched different changeIds (a single op's own
+   * snapshot only covers what IT touched). Concretely, per field:
+   *   - changeSnapshot: first (earliest / closest-to-landingOp) entry per
+   *     changeId wins — later entries in the range reflect that changeId's
+   *     state at a LATER point than we're restoring to.
+   *   - fileSnapshot / conflictsSnapshot: the first op in the range that
+   *     recorded one, since whole-state snapshots aren't per-changeId and
+   *     an op that didn't record one simply didn't change that state.
+   *
+   * This same helper backs undo() (landingOp = the parent of whatever's
+   * being undone), redo() (landingOp = the operation a prior undo()
+   * reverted), and operations.restore() (landingOp = the target operation
+   * itself) — one reversal primitive, not three.
+   *
+   * @param {Array<any>} ops - Full chronological operation list (oplog.list())
+   * @param {any} landingOp - The operation whose resulting state to recompute
+   * @returns {{
+   *   changeSnapshotToApply: Record<string, any>,
+   *   fileSnapshot: Record<string, string>|undefined,
+   *   conflictsSnapshot: any,
+   * }}
+   */
+  const computeGraphReversal = (/** @type {any[]} */ ops, /** @type {any} */ landingOp) => {
+    const landingIndex = ops.findIndex((op) => op.id === landingOp.id);
+
+    /** @type {Record<string, any>} */
+    const changeSnapshotToApply = {};
+    /** @type {Record<string, string>|undefined} */
+    let fileSnapshot;
+    /** @type {any} */
+    let conflictsSnapshot;
+
+    for (let i = landingIndex + 1; i < ops.length; i++) {
+      const op = ops[i];
+
+      if (op.changeSnapshot) {
+        for (const [changeId, snapshot] of Object.entries(op.changeSnapshot)) {
+          if (!(changeId in changeSnapshotToApply)) {
+            changeSnapshotToApply[changeId] = snapshot;
+          }
+        }
+      }
+
+      // `!= null` (not `!== undefined`) on purpose: some operations record
+      // an explicit `null` for "I ran, and I deliberately took no snapshot"
+      // (e.g. describe() of a non-working-copy revision) — that's exactly
+      // as uninformative as never having set the field, so keep scanning
+      // rather than "finding" a null snapshot.
+      if (fileSnapshot === undefined && op.view && op.view.fileSnapshot != null) {
+        fileSnapshot = op.view.fileSnapshot;
+      }
+
+      if (conflictsSnapshot === undefined && op.conflictsSnapshot != null) {
+        conflictsSnapshot = op.conflictsSnapshot;
+      }
+    }
+
+    return { changeSnapshotToApply, fileSnapshot, conflictsSnapshot };
+  };
+
+  /**
+   * Apply a reversal computed by computeGraphReversal() to the live graph,
+   * working-copy files, and conflict state. Does NOT touch the working-copy
+   * pointer or bookmarks — callers set those from the landing op's own
+   * `view` directly (pointers, unlike file/graph/conflict content, are
+   * already correct as recorded, see computeGraphReversal's doc comment).
+   *
+   * @param {ReturnType<typeof computeGraphReversal>} reversal
+   * @returns {Promise<void>}
+   */
+  const applyGraphReversal = async (reversal) => {
+    await graph.load();
+    for (const [changeId, snapshot] of Object.entries(reversal.changeSnapshotToApply)) {
+      if (await graph.getChange(changeId)) {
+        // Bypass the git-sync middleware (baseGraph, not the wrapped
+        // `graph`): undo/restore are pure reverts, and `snapshot` already
+        // carries the change's ORIGINAL commitId from before the reverted
+        // operation(s) ran. Going through graph.updateChange() would fire
+        // onUpdateChange -> syncChangeToGit(), which mints a brand-new
+        // commit (and thus a new commitId) from the CURRENT tree instead
+        // of restoring the one that was actually there — see issue #37(c):
+        // "undo/restore give reverted commits new commit IDs". Writing the
+        // snapshot verbatim via baseGraph puts the original commitId back.
+        await baseGraph.updateChange(snapshot);
+      }
+    }
+
+    if (reversal.fileSnapshot !== undefined) {
+      await syncWorkingCopyFiles(reversal.fileSnapshot);
+    }
+
+    await conflicts.load();
+    if (reversal.conflictsSnapshot !== undefined) {
+      conflicts.conflicts = new Map(Object.entries(reversal.conflictsSnapshot.conflicts || {}));
+      conflicts.fileConflicts = new Map(
+        Object.entries(reversal.conflictsSnapshot.fileConflicts || {})
+      );
+      await conflicts.save();
+    }
+    // Else: no operation in the reverted range touched conflicts — leave
+    // current conflict state alone. (Previously undo() unconditionally
+    // cleared ALL conflicts whenever the op being undone hadn't recorded
+    // its own conflictsSnapshot, which is nearly every non-merge() op —
+    // undoing an unrelated describe() would silently wipe conflicts from
+    // an earlier, unrelated merge(). Fixed as part of issue #29.)
+  };
+
+  /**
+   * Re-parent every child of `changeId` onto `newParents` instead — used
+   * when a change is being elided from the graph (abandon(), issue #30;
+   * converge(), issue #32) so its children don't end up pointing at
+   * something no longer meant to be there. Mutates `changeSnapshot` in
+   * place, adding each touched child's PRE-reparent record so the caller's
+   * own oplog entry lets undo()/redo()/operations.restore() reverse this
+   * too (the same mechanism the caller already uses for the elided
+   * change's own snapshot).
+   *
+   * @param {string} changeId - The change being elided
+   * @param {string[]} newParents - What its children should point at instead
+   * @param {Record<string, any>} changeSnapshot - Accumulator to add each touched child's pre-state to
+   * @returns {Promise<void>}
+   */
+  const reparentChildrenOnto = async (changeId, newParents, changeSnapshot) => {
+    const childIds = graph.getChildren(changeId);
+    for (const childId of childIds) {
+      const child = await graph.getChange(childId);
+      if (!child) continue;
+      changeSnapshot[childId] = structuredClone(child);
+      const reparented = child.parents.flatMap((/** @type {string} */ p) =>
+        p === changeId ? newParents : [p]
+      );
+      // De-dupe (e.g. the child could already have one of the new parents
+      // as another of its own parents) while preserving first-seen order.
+      child.parents = [...new Set(reparented)];
+      await graph.updateChange(child);
+    }
+  };
+
+  /**
+   * Determine which operation a fresh undo() call should revert, matching
+   * real jj's progressive-undo semantics (`jj-undo(1)`: "If used once after
+   * a normal operation, this will undo that last operation by restoring its
+   * parent. If jj undo is used repeatedly, it will restore increasingly
+   * older operations, going further back into the past.").
+   *
+   * The raw op-log parent chain can't answer this directly once undo/redo
+   * bookkeeping operations are mixed into the log: an 'undo' operation's
+   * own parent is the operation it just undid, so naively targeting
+   * `ops[ops.length - 1]` on a SECOND undo() would undo the undo (toggle
+   * back to the future) instead of stepping one further step into the past
+   * — this was issue #29's "undo() twice only undoes the undo" bug.
+   *
+   * @param {Array<any>} ops - Full chronological operation list
+   * @returns {any} The operation object undo() should revert
+   */
+  const resolveUndoTarget = (ops) => {
+    const head = ops[ops.length - 1];
+    const findOp = (/** @type {any} */ id) => ops.find((op) => op.id === id);
+
+    if (head.eventType === 'undo') {
+      // We're stepping further into the past: what should be undone now is
+      // the operation right BEFORE the one `head` already undid — not
+      // head's own parent, which IS the operation head undid (targeting it
+      // again would just toggle back to the present).
+      const previouslyUndone = head.targetOpId && findOp(head.targetOpId);
+      const stepBack = previouslyUndone && findOp(previouslyUndone.parents[0]);
+      return stepBack || previouslyUndone || head;
+    }
+
+    if (head.eventType === 'redo') {
+      // A redo re-established some earlier operation as current; a fresh
+      // undo right after it should behave exactly as if that operation
+      // were freshly current and had never been touched by undo/redo at
+      // all — i.e. undo it again (real jj: redo "moves in the direction of
+      // the future"; undoing right after simply resumes stepping back).
+      const redoneUndo = head.redoOf && findOp(head.redoOf);
+      const target = redoneUndo && redoneUndo.targetOpId && findOp(redoneUndo.targetOpId);
+      return target || head;
+    }
+
+    return head;
+  };
+
   /**
    * Automatic working-copy snapshot (v1.6).
    *
@@ -314,6 +575,25 @@ export async function createJJ(options) {
         }
       },
 
+      // Used by undo()/redo()/operations.restore() to reverse an
+      // addChange() when winding the graph back — see issue #29. No Git
+      // sync hook: a change created after the operation being reverted was
+      // never pushed anywhere to unwind, and the Git backend has no
+      // "forget this commit" operation (nor should it — Git objects are
+      // content-addressed and harmless to leave orphaned).
+      deleteChange: (/** @type {any} */ changeId) => baseGraph.deleteChange(changeId),
+
+      // See issue #32 / converge(): a divergent copy is another commit
+      // claiming an existing changeId; no Git sync hook, for the same
+      // reason addChange()'s primary copy already goes through
+      // onAddChange() when it's first created — the divergent copy needs
+      // no additional sync of its own.
+      addDivergentCopy: (/** @type {any} */ change) => baseGraph.addDivergentCopy(change),
+      getDivergentSiblings: (/** @type {any} */ changeId) =>
+        baseGraph.getDivergentSiblings(changeId),
+      deleteDivergentCopy: (/** @type {any} */ changeId, /** @type {any} */ commitId) =>
+        baseGraph.deleteDivergentCopy(changeId, commitId),
+
       // Delegate other operations
       init: () => baseGraph.init(),
     };
@@ -471,6 +751,20 @@ export async function createJJ(options) {
     /**
      * Write a file to the working copy
      *
+     * Note (issue #30): this does NOT update the working-copy change's
+     * `commitId`/`fileSnapshot` — those stay as they were until the next
+     * command that snapshots the working copy (describe(), new(), edit(),
+     * status(), or any other call that goes through
+     * autoSnapshotWorkingCopy()/snapshot()). This is intentional, not a
+     * bug: jj has no staging area, but it also doesn't recompute a git
+     * tree/commit hash on every single file write (that would mean
+     * hashing on every keystroke of an external editor) — real jj only
+     * takes a fresh working-copy snapshot when an actual `jj` command
+     * runs. write() is the equivalent of editing a file with your OS's own
+     * tools outside of jj entirely; describe()/new()/edit()/status()/etc.
+     * are the equivalent of running a jj command, which is what triggers
+     * the (auto) snapshot in both real jj and here.
+     *
      * @param {Record<string, any>} args - Arguments
      * @returns {Promise<Object>} File information including path, size, and mode
      */
@@ -494,7 +788,7 @@ export async function createJJ(options) {
       if (pathParts.length > 1) {
         const dirPath = pathParts.slice(0, -1).join('/');
         const fullDirPath = `${dir}/${dirPath}`;
-        await fs.promises.mkdir(fullDirPath, { recursive: true });
+        await mkdirp(fs, fullDirPath);
       }
 
       // Write the file
@@ -552,7 +846,7 @@ export async function createJJ(options) {
         const fullPath = path.join(dir, args.path);
         try {
           if (encoding === 'utf-8' || encoding === 'utf8') {
-            return await fs.promises.readFile(fullPath, 'utf-8');
+            return await fs.promises.readFile(fullPath, 'utf8');
           } else {
             return await fs.promises.readFile(fullPath);
           }
@@ -774,7 +1068,7 @@ export async function createJJ(options) {
       if (pathParts.length > 1) {
         const dirPath = pathParts.slice(0, -1).join('/');
         const fullDirPath = path.join(dir, dirPath);
-        await fs.promises.mkdir(fullDirPath, { recursive: true });
+        await mkdirp(fs, fullDirPath);
       }
 
       // Create writable stream
@@ -887,7 +1181,7 @@ export async function createJJ(options) {
       // Ensure destination directory exists
       const toDir = toPath.substring(0, toPath.lastIndexOf('/'));
       try {
-        await fs.promises.mkdir(toDir, { recursive: true });
+        await mkdirp(fs, toDir);
       } catch (error) {
         throw new JJError(
           'FILE_SYSTEM_ERROR',
@@ -1005,6 +1299,51 @@ export async function createJJ(options) {
       // TODO: Prevent creating cycles in the change graph
       // For now, we'll allow it but it should be validated
 
+      // Snapshot BEFORE mutating so undo()/redo()/operations.restore() can
+      // reverse the reparenting — see issue #29.
+      const changeSnapshotBefore = structuredClone(change);
+
+      // Three-way merge against the OLD base before reparenting (issue #31):
+      // real jj's rebase re-derives the rebased change's content as
+      // (old base, old commit, new base) — if a sibling changed the same
+      // lines differently, that's a genuine conflict, not something
+      // reparenting-and-copying-verbatim can silently paper over. This
+      // reuses the exact same detectConflicts() machinery merge() already
+      // uses (see merge(), a few hundred lines down) rather than
+      // duplicating three-way-merge logic a third time in this codebase.
+      const oldParentId = change.parents[0];
+      const oldParentChange = oldParentId ? await graph.getChange(oldParentId) : null;
+      const baseFiles = new Map(
+        Object.entries((oldParentChange && oldParentChange.fileSnapshot) || {})
+      );
+      const leftFiles = new Map(Object.entries(change.fileSnapshot || {}));
+      const rightFiles = new Map(Object.entries(newParentChange.fileSnapshot || {}));
+
+      await conflicts.load();
+      const conflictsSnapshot = {
+        conflicts: Object.fromEntries(conflicts.conflicts),
+        fileConflicts: Object.fromEntries(conflicts.fileConflicts),
+      };
+
+      const detectedConflicts = oldParentChange
+        ? await conflicts.detectConflicts({
+            baseFiles,
+            leftFiles,
+            rightFiles,
+            drivers: {},
+            // Not necessarily the checked-out working copy, so don't let
+            // merge drivers write to disk on its behalf.
+            workingCopyDir: /** @type {any} */ (null),
+            baseChange: oldParentId,
+            leftChange: changeId,
+            rightChange: newParent,
+          })
+        : [];
+
+      for (const conflict of detectedConflicts) {
+        await conflicts.addConflict(conflict);
+      }
+
       // Update parent
       change.parents = [newParent];
       await graph.updateChange(change);
@@ -1015,6 +1354,8 @@ export async function createJJ(options) {
         user: await getUserOplogInfo(),
         description: `move change ${changeId.slice(0, 8)} to ${newParent.slice(0, 8)}`,
         parents: [],
+        changeSnapshot: { [changeId]: changeSnapshotBefore },
+        conflictsSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -1023,7 +1364,7 @@ export async function createJJ(options) {
         },
       });
 
-      return change;
+      return { ...change, conflicts: detectedConflicts };
     },
 
     /**
@@ -1208,7 +1549,7 @@ export async function createJJ(options) {
               break;
             }
 
-            const content = await fs.promises.readFile(fullPath, 'utf-8');
+            const content = await fs.promises.readFile(fullPath, 'utf8');
             fileSnapshot[filePath] = content;
             totalSnapshotSize += stats.size;
           } catch (error) {
@@ -1406,6 +1747,8 @@ export async function createJJ(options) {
 
       // Snapshot filesystem BEFORE operation (for undo) unless preserveSnapshot is true
       let fileSnapshot;
+      /** @type {Record<string, any>} */
+      const changeSnapshot = {};
       if (!args.preserveSnapshot) {
         fileSnapshot = await snapshotFilesystem();
 
@@ -1414,6 +1757,10 @@ export async function createJJ(options) {
         const currentChangeId = workingCopy.getCurrentChangeId();
         const currentChange = await graph.getChange(currentChangeId);
         if (currentChange && fileSnapshot) {
+          // Snapshot BEFORE mutating so undo()/redo() can revert this
+          // in-place update too, not just the pointer/new-change creation
+          // below — see issue #29.
+          changeSnapshot[currentChangeId] = structuredClone(currentChange);
           currentChange.fileSnapshot = fileSnapshot;
           await graph.updateChange(currentChange);
         }
@@ -1441,6 +1788,7 @@ export async function createJJ(options) {
       const user = /** @type {any} */ (userConfig.getUser());
 
       // Initialize with parent's file snapshot
+      /** @type {Record<string, string>} */
       let initialSnapshot = {};
       if (parents && parents.length > 0) {
         const parent = await graph.getChange(parents[0]);
@@ -1484,10 +1832,19 @@ export async function createJJ(options) {
       // Handle insertBefore: rebase target to have new change as parent
       if (args.insertBefore) {
         const targetChange = await graph.getChange(args.insertBefore);
+        changeSnapshot[args.insertBefore] = structuredClone(targetChange);
         targetChange.parents = [newChangeId];
         await graph.updateChange(targetChange);
       }
 
+      // Sync the working directory to the new change's snapshot: write
+      // everything it has AND remove anything it doesn't (issue #30 — this
+      // used to never touch disk at all, so `new({ parents: [...] })`
+      // targeting anything other than the current head silently left the
+      // OLD working copy's files in place instead of checking out the new
+      // parent's).
+      await syncWorkingCopyFiles(initialSnapshot);
+
       await workingCopy.setCurrentChange(newChangeId);
 
       // Record operation with filesystem snapshot
@@ -1500,6 +1857,13 @@ export async function createJJ(options) {
         },
         description: `new change ${newChangeId.slice(0, 8)}`,
         parents: [],
+        // See issue #29: lets undo()/redo()/operations.restore() reverse
+        // the existing records this op updated in place (the old
+        // working-copy change's refreshed fileSnapshot, and insertBefore's
+        // target's reparented parents). The newly created change itself
+        // (newChangeId) is intentionally NOT torn down on undo — see
+        // computeGraphReversal's doc comment.
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -1880,6 +2244,13 @@ export async function createJJ(options) {
 
       const previousChangeId = workingCopy.getCurrentChangeId();
 
+      /** @type {Record<string, any>} */
+      const changeSnapshot = {};
+
+      // Capture disk state right before we touch anything, for undo() —
+      // see issue #29.
+      const fileSnapshotBeforeSwitch = await snapshotFilesystem();
+
       // CRITICAL FIX: Clean working directory BEFORE snapshotting to prevent cross-branch pollution
       // Remove files that don't belong to the current changeId before we snapshot it
       if (previousChangeId !== args.changeId) {
@@ -1901,13 +2272,14 @@ export async function createJJ(options) {
               }
             }
           }
-        }
 
-        // Now snapshot the CLEAN working directory (no pollution!)
-        const currentSnapshot = await snapshotFilesystem();
-        if (currentSnapshot && Object.keys(currentSnapshot).length > 0) {
-          previousChange.fileSnapshot = currentSnapshot;
-          await graph.updateChange(previousChange);
+          // Now snapshot the CLEAN working directory (no pollution!)
+          const currentSnapshot = await snapshotFilesystem();
+          if (currentSnapshot && Object.keys(currentSnapshot).length > 0) {
+            changeSnapshot[previousChangeId] = structuredClone(previousChange);
+            previousChange.fileSnapshot = currentSnapshot;
+            await graph.updateChange(previousChange);
+          }
         }
       }
 
@@ -1920,38 +2292,17 @@ export async function createJJ(options) {
         timestamp: new Date().toISOString(),
       });
 
-      // Restore files from the change's snapshot to working directory
-      if (change.fileSnapshot) {
-        for (const [filePath, content] of Object.entries(change.fileSnapshot)) {
-          try {
-            const fullPath = path.join(dir, filePath);
-
-            // Ensure directory exists
-            const pathParts = filePath.split('/');
-            if (pathParts.length > 1) {
-              const dirPath = pathParts.slice(0, -1).join('/');
-              const fullDirPath = path.join(dir, dirPath);
-              await fs.promises.mkdir(fullDirPath, { recursive: true });
-            }
-
-            // Write file content
-            await fs.promises.writeFile(fullPath, content, 'utf8');
-
-            // Update working copy tracking
-            const stats = await fs.promises.stat(fullPath);
-            await workingCopy.trackFile(filePath, {
-              mtime: stats.mtime,
-              size: stats.size,
-              mode: stats.mode,
-            });
-          } catch (error) {
-            throw new JJError(
-              'FILE_RESTORE_FAILED',
-              `Failed to restore file ${filePath}: ${error.message}`,
-              { filePath, originalError: error.message }
-            );
-          }
-        }
+      // Fully sync the working directory to the target change's snapshot:
+      // write everything it has AND remove anything it doesn't (issue #30
+      // — this used to only overlay the target's files on top of whatever
+      // was already on disk, so a file present in the PREVIOUS change but
+      // absent from the target leaked into the next snapshot).
+      try {
+        await syncWorkingCopyFiles(change.fileSnapshot || {});
+      } catch (error) {
+        throw new JJError('FILE_RESTORE_FAILED', `Failed to restore files: ${error.message}`, {
+          originalError: error.message,
+        });
       }
 
       // Set this change as the working copy
@@ -1967,11 +2318,13 @@ export async function createJJ(options) {
         },
         description: `edit change ${args.changeId.slice(0, 8)}`,
         parents: [],
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
           heads: [args.changeId],
           workingCopy: args.changeId,
+          fileSnapshot: fileSnapshotBeforeSwitch,
         },
       });
 
@@ -2002,106 +2355,118 @@ export async function createJJ(options) {
     /**
      * Undo last operation
      *
+     * Reverts the most recent operation — including graph-rewriting ones
+     * (squash/rebase/abandon/new/edit), not just working-copy/file state
+     * (see issue #29). Matches real jj's progressive-undo semantics
+     * (`jj-undo(1)`): called again with nothing else in between, it steps
+     * one further operation into the past rather than undoing itself.
+     *
      * @returns {Promise<Object>} Information about the undo including the undone operation and restored state
      */
     async undo() {
-      // Get the operation we're about to undo to access its pre-state
       await oplog.load();
       const ops = await oplog.list();
       if (ops.length === 0) {
         throw new JJError('NOTHING_TO_UNDO', 'No operations to undo');
       }
 
-      // Get the current operation (the one being undone) to restore its pre-state
-      const currentOp = ops[ops.length - 1];
-
-      const previousView = /** @type {any} */ (await oplog.undo());
-
-      // Restore state from previous view
-      await workingCopy.setCurrentChange(previousView.workingCopy);
-
-      // Restore ChangeGraph content mutated in place by the operation being
-      // undone (e.g. describe() editing change.description) — see issue #12.
-      // currentOp.changeSnapshot holds the affected change record(s) as they
-      // were BEFORE currentOp ran, captured the same way fileSnapshot is.
-      await graph.load();
-      if (currentOp && currentOp.changeSnapshot) {
-        for (const snapshot of Object.values(
-          /** @type {Record<string, any>} */ (currentOp.changeSnapshot)
-        )) {
-          if (snapshot && (await graph.getChange(snapshot.changeId))) {
-            await graph.updateChange(snapshot);
-          }
-        }
-      }
-
-      // Restore filesystem from previous operation's snapshot (taken BEFORE that operation)
-      // This is how JJ snapshots the working copy before every command
-      if (previousView.fileSnapshot) {
-        for (const [filePath, content] of Object.entries(previousView.fileSnapshot)) {
-          try {
-            const fullPath = path.join(dir, filePath);
-
-            // Ensure directory exists
-            const pathParts = filePath.split('/');
-            if (pathParts.length > 1) {
-              const dirPath = pathParts.slice(0, -1).join('/');
-              const fullDirPath = path.join(dir, dirPath);
-              await fs.promises.mkdir(fullDirPath, { recursive: true });
-            }
-
-            // Write file content
-            await fs.promises.writeFile(fullPath, content, 'utf8');
-          } catch (error) {
-            throw new JJError(
-              'UNDO_FILE_RESTORE_FAILED',
-              `Failed to restore file ${filePath} during undo: ${error.message}`,
-              { filePath, originalError: error.message }
-            );
-          }
-        }
-      }
+      const targetOp = resolveUndoTarget(ops);
+      const landingOpId = targetOp.parents && targetOp.parents[0];
+      const landingOp = landingOpId ? ops.find((op) => op.id === landingOpId) : null;
 
-      // Restore conflicts state from before the undone operation
-      // The conflictsSnapshot in an operation represents the state BEFORE that operation ran
-      await conflicts.load();
-      if (currentOp && currentOp.conflictsSnapshot) {
-        // Restore conflicts from the operation we're undoing (its pre-state)
-        conflicts.conflicts = new Map(Object.entries(currentOp.conflictsSnapshot.conflicts || {}));
-        conflicts.fileConflicts = new Map(
-          Object.entries(currentOp.conflictsSnapshot.fileConflicts || {})
-        );
-        await conflicts.save();
+      /** @type {ReturnType<typeof computeGraphReversal>} */
+      let reversal;
+      /** @type {any} */
+      let landingView;
+      if (landingOp) {
+        reversal = computeGraphReversal(ops, landingOp);
+        landingView = landingOp.view || {};
       } else {
-        // No conflicts snapshot - clear conflicts
-        await conflicts.clear();
+        // Undoing the very first (root) operation: there's nothing before
+        // it to restore to, so land on its own recorded state rather than
+        // throwing (mirrors the previous no-parent fallback).
+        reversal = {
+          changeSnapshotToApply: {},
+          fileSnapshot: undefined,
+          conflictsSnapshot: undefined,
+        };
+        landingView = targetOp.view || {};
+      }
+
+      // Capture EXACTLY what's about to be overwritten, from ground truth,
+      // before applying the reversal — this is what redo() re-applies
+      // later. It can't just recompute "the state after targetOp" the way
+      // undo() itself computes "the state after landingOp" (by scanning
+      // for a LATER op that also touched the same changeId/files/
+      // conflicts): that scan only works going backward, where "nothing
+      // touched it since" means "it's already correct". Going forward,
+      // "nothing touched it since targetOp" means the opposite — its
+      // effect is still live and needs to be captured now, not rederived.
+      await graph.load();
+      /** @type {Record<string, any>} */
+      const redoChangeSnapshot = {};
+      for (const changeId of Object.keys(reversal.changeSnapshotToApply)) {
+        const current = await graph.getChange(changeId);
+        if (current) redoChangeSnapshot[changeId] = current;
+      }
+      const redoFileSnapshot =
+        reversal.fileSnapshot !== undefined ? await snapshotFilesystem() : undefined;
+      let redoConflictsSnapshot;
+      if (reversal.conflictsSnapshot !== undefined) {
+        await conflicts.load();
+        redoConflictsSnapshot = {
+          conflicts: Object.fromEntries(conflicts.conflicts),
+          fileConflicts: Object.fromEntries(conflicts.fileConflicts),
+        };
       }
 
-      // Record undo operation. Tag it with the view it undid so that redo()
-      // can re-apply it (jj's progressive undo/redo, added in jj v0.33).
+      if (landingView.workingCopy) {
+        await workingCopy.setCurrentChange(landingView.workingCopy);
+      }
+      await applyGraphReversal(reversal);
+
+      // Record undo as its own operation (matching real jj) — tagged with
+      // which operation it targeted so a following undo() can walk one
+      // step further back (resolveUndoTarget) instead of toggling, and
+      // carrying exactly what redo() needs to re-apply (captured above).
+      //
+      // Also record `changeSnapshot: redoChangeSnapshot` — the SAME
+      // ground-truth-before-this-op values, but under the field name
+      // computeGraphReversal() actually scans for. Without this, undo()
+      // itself was the one mutating operation in the whole API that never
+      // recorded its own changeSnapshot, so a LATER undo() targeting THIS
+      // undo (to step back past it) had nothing to restore: it would
+      // repoint the working copy and files, but leave whatever this
+      // undo() overwrote (e.g. a change's description) exactly as this
+      // undo() left it. See issue #37(a).
       await oplog.recordOperation({
         timestamp: new Date().toISOString(),
         user: await getUserOplogInfo(),
         description: 'undo operation',
         eventType: 'undo',
-        undoneOpId: currentOp.id,
-        undoneView: currentOp.view,
-        undoneConflictsSnapshot: currentOp.conflictsSnapshot || null,
+        targetOpId: targetOp.id,
+        undoneOpId: targetOp.id, // kept for API/type compatibility
+        changeSnapshot: redoChangeSnapshot,
+        redoChangeSnapshot,
+        redoFileSnapshot,
+        redoConflictsSnapshot,
         parents: [],
-        view: previousView,
+        view: landingView,
       });
 
-      // Return information about what was undone
+      const restoredFileCount =
+        reversal.fileSnapshot !== undefined ? Object.keys(reversal.fileSnapshot).length : 0;
+
       return {
         undoneOperation: {
-          description: currentOp.description,
-          timestamp: currentOp.timestamp,
-          user: currentOp.user,
+          description: targetOp.description,
+          timestamp: targetOp.timestamp,
+          user: targetOp.user,
         },
         restoredState: {
-          workingCopy: previousView.workingCopy,
-          heads: previousView.heads,
-          fileCount: previousView.fileSnapshot ? Object.keys(previousView.fileSnapshot).length : 0,
+          workingCopy: landingView.workingCopy,
+          heads: landingView.heads,
+          fileCount: restoredFileCount,
         },
       };
     },
@@ -2109,9 +2474,9 @@ export async function createJJ(options) {
     /**
      * Redo an operation previously undone with undo() (v1.5)
      *
-     * Mirrors `jj redo` (jj v0.33): progressively re-applies the operations that
-     * `undo()` reverted, most-recent-undo first. Each redo consumes exactly one
-     * pending undo.
+     * Mirrors `jj redo` (jj v0.33): re-applies the operation that the most
+     * recent not-yet-redone undo() reverted — including its graph rewrites,
+     * not just working-copy/file state (see issue #29).
      *
      * @returns {Promise<Object>} Information about the redone operation
      */
@@ -2142,42 +2507,52 @@ export async function createJJ(options) {
         });
       }
 
-      const redoneView = undoOp.undoneView || {};
+      const targetOpId = undoOp.targetOpId || undoOp.undoneOpId;
+      const targetOp = targetOpId && ops.find((op) => op.id === targetOpId);
+      const redoneView = (targetOp && targetOp.view) || {};
 
-      // Restore the working-copy pointer.
       if (redoneView.workingCopy) {
         await workingCopy.setCurrentChange(redoneView.workingCopy);
       }
 
-      // Restore the working-copy files captured in the undone view.
-      if (redoneView.fileSnapshot) {
-        for (const [filePath, content] of Object.entries(redoneView.fileSnapshot)) {
-          try {
-            const fullPath = path.join(dir, filePath);
-            const pathParts = filePath.split('/');
-            if (pathParts.length > 1) {
-              const fullDirPath = path.join(dir, pathParts.slice(0, -1).join('/'));
-              await fs.promises.mkdir(fullDirPath, { recursive: true });
-            }
-            await fs.promises.writeFile(fullPath, content, 'utf8');
-          } catch (error) {
-            throw new JJError(
-              'REDO_FILE_RESTORE_FAILED',
-              `Failed to restore file ${filePath} during redo: ${error.message}`,
-              { filePath, originalError: error.message }
-            );
-          }
-        }
+      // Re-apply exactly what this undo captured right before it reverted
+      // things — NOT computeGraphReversal(ops, targetOp): that scans for a
+      // LATER op touching the same changeId/files/conflicts, which is the
+      // right question for undo() ("has anything since made my target
+      // stale?") but the wrong one here — after an undo, NOTHING later
+      // re-established targetOp's own effect, so there's nothing to find
+      // by scanning forward. undo() captured it directly for exactly this
+      // reason (see its own comment).
+      await graph.load();
+
+      // Capture ground truth right before overwriting, same as undo()
+      // does for its own changeSnapshot (issue #37a) — lets a later
+      // undo() targeting THIS redo op restore what redo() is about to
+      // clobber, instead of finding no changeSnapshot at all.
+      /** @type {Record<string, any>} */
+      const undoChangeSnapshot = {};
+      for (const changeId of Object.keys(undoOp.redoChangeSnapshot || {})) {
+        const current = await graph.getChange(changeId);
+        if (current) undoChangeSnapshot[changeId] = current;
       }
 
-      // Restore conflicts to the state that existed after the redone operation.
+      for (const [changeId, snapshot] of Object.entries(undoOp.redoChangeSnapshot || {})) {
+        if (await graph.getChange(changeId)) {
+          // Bypass the git-sync middleware — see the matching comment in
+          // applyGraphReversal(). `snapshot` already carries the change's
+          // correct commitId from before the undo it's reversing ran
+          // (issue #37c applies to redo() too).
+          await baseGraph.updateChange(snapshot);
+        }
+      }
+      if (undoOp.redoFileSnapshot !== undefined) {
+        await syncWorkingCopyFiles(undoOp.redoFileSnapshot);
+      }
       await conflicts.load();
-      if (undoOp.undoneConflictsSnapshot) {
-        conflicts.conflicts = new Map(
-          Object.entries(undoOp.undoneConflictsSnapshot.conflicts || {})
-        );
+      if (undoOp.redoConflictsSnapshot !== undefined) {
+        conflicts.conflicts = new Map(Object.entries(undoOp.redoConflictsSnapshot.conflicts || {}));
         conflicts.fileConflicts = new Map(
-          Object.entries(undoOp.undoneConflictsSnapshot.fileConflicts || {})
+          Object.entries(undoOp.redoConflictsSnapshot.fileConflicts || {})
         );
         await conflicts.save();
       }
@@ -2188,19 +2563,23 @@ export async function createJJ(options) {
         description: 'redo operation',
         eventType: 'redo',
         redoOf: undoOp.id,
+        changeSnapshot: undoChangeSnapshot,
         parents: [],
         view: redoneView,
       });
 
+      const restoredFileCount =
+        undoOp.redoFileSnapshot !== undefined ? Object.keys(undoOp.redoFileSnapshot).length : 0;
+
       return {
         redoneOperation: {
           description: undoOp.description,
-          undoneOpId: undoOp.undoneOpId,
+          undoneOpId: targetOpId,
         },
         restoredState: {
           workingCopy: redoneView.workingCopy,
           heads: redoneView.heads,
-          fileCount: redoneView.fileSnapshot ? Object.keys(redoneView.fileSnapshot).length : 0,
+          fileCount: restoredFileCount,
         },
       };
     },
@@ -2427,6 +2806,12 @@ export async function createJJ(options) {
       /**
        * Restore repository to a specific operation (matches `jj operation restore`)
        *
+       * Fully reverts everything recorded after the target operation —
+       * including graph rewrites (squash/rebase/abandon/new/edit), working
+       * copy files, and conflict state, not just bookmarks/the working-copy
+       * pointer (see issue #29) — using the same reversal primitive as
+       * undo()/redo().
+       *
        * @param {Record<string, any>} args - Arguments
        * @returns {Promise<Object>} Restore result
        */
@@ -2466,12 +2851,35 @@ export async function createJJ(options) {
           await workingCopy.setCurrentChange(targetOp.view.workingCopy);
         }
 
+        // Revert the change graph, working-copy files, and conflict state
+        // to exactly what they were right after targetOp ran.
+        const reversal = computeGraphReversal(ops, targetOp);
+
+        // Capture ground truth for every changeId this restore is about to
+        // overwrite, BEFORE applying the reversal — exactly like undo()
+        // does for its own changeSnapshot. Without this, restore()'s own
+        // oplog entry carried no changeSnapshot at all, so undoing the
+        // restore itself had nothing to put back: a later undo() would
+        // repoint the working copy and files, but leave whatever the
+        // restore had just overwritten (e.g. a change's description)
+        // exactly as the restore left it. See issue #37(a).
+        await graph.load();
+        /** @type {Record<string, any>} */
+        const changeSnapshot = {};
+        for (const changeId of Object.keys(reversal.changeSnapshotToApply)) {
+          const current = await graph.getChange(changeId);
+          if (current) changeSnapshot[changeId] = current;
+        }
+
+        await applyGraphReversal(reversal);
+
         // Record this restoration as a new operation
         await oplog.recordOperation({
           timestamp: new Date().toISOString(),
           user: await getUserOplogInfo(),
           description: `restore to operation ${args.operation}`,
           parents: [],
+          changeSnapshot,
           view: targetOp.view,
         });
 
@@ -2757,10 +3165,53 @@ export async function createJJ(options) {
         timestamp: new Date().toISOString(),
       });
 
+      // Snapshot BEFORE mutating so undo()/redo()/operations.restore() can
+      // reverse the squash (un-abandon source, restore dest's description
+      // and content) — see issue #29.
+      /** @type {Record<string, any>} */
+      const changeSnapshot = {
+        [source]: structuredClone(sourceChange),
+        [destChangeId]: structuredClone(destChange),
+      };
+
       // Mark source as abandoned
       sourceChange.abandoned = true;
       await graph.updateChange(sourceChange);
 
+      // Merge source's file content into dest (issue #30: squash() used to
+      // only combine descriptions, leaving dest's tree untouched). Compute
+      // what source itself actually changed relative to ITS OWN parent
+      // (its "diff") and fold just that onto dest, rather than overwriting
+      // dest's whole snapshot with source's — a path source never touched
+      // (inherited unchanged from that parent) must not clobber a
+      // dest-specific version of the same path.
+      const sourceParentId = sourceChange.parents && sourceChange.parents[0];
+      const sourceParentChange = sourceParentId ? await graph.getChange(sourceParentId) : null;
+      const sourceBaseSnapshot = (sourceParentChange && sourceParentChange.fileSnapshot) || {};
+      const sourceSnapshot = sourceChange.fileSnapshot || {};
+      const mergedSnapshot = { ...(destChange.fileSnapshot || {}) };
+      const touchedPaths = new Set([
+        ...Object.keys(sourceBaseSnapshot),
+        ...Object.keys(sourceSnapshot),
+      ]);
+      for (const filePath of touchedPaths) {
+        const baseValue = sourceBaseSnapshot[filePath];
+        const sourceValue = sourceSnapshot[filePath];
+        if (sourceValue === baseValue) {
+          // source never touched this path (inherited as-is from its own
+          // parent) — leave whatever dest already had for it alone.
+          continue;
+        }
+        if (sourceValue === undefined) {
+          // source deleted a file it inherited from its parent.
+          delete mergedSnapshot[filePath];
+        } else {
+          // source added or modified this path.
+          mergedSnapshot[filePath] = sourceValue;
+        }
+      }
+      destChange.fileSnapshot = mergedSnapshot;
+
       // Update description of dest to indicate squash (middleware will sync to Git)
       destChange.description += `\n\n(squashed from ${source.slice(0, 8)})`;
       await graph.updateChange(destChange);
@@ -2788,10 +3239,22 @@ export async function createJJ(options) {
           },
           description: '(no description set)',
           timestamp: new Date().toISOString(),
-          fileSnapshot: {},
+          // Start from the DESTINATION's tree (which now includes source's
+          // folded-in changes, set above), not an empty object — matches
+          // real `jj squash`, where the new working-copy change looks
+          // identical to its new parent until you touch something. Issue
+          // #39: this used to hard-code `{}`, so status()/snapshot() saw
+          // every on-disk file as untracked/new until something re-wrote
+          // it and triggered a fresh auto-snapshot.
+          fileSnapshot: { ...destChange.fileSnapshot },
         };
 
         await graph.addChange(newChange); // Middleware will sync to Git
+        // Sync the working directory to match (issue #30's fix for
+        // new()/edit(); squash()'s own synthetic post-squash change never
+        // did this) — a no-op when source's parent was already dest (the
+        // common case), but necessary whenever source/dest aren't adjacent.
+        await syncWorkingCopyFiles(newChange.fileSnapshot);
         await workingCopy.setCurrentChange(newChangeId);
         newWorkingCopyId = newChangeId;
       }
@@ -2802,6 +3265,7 @@ export async function createJJ(options) {
         user: await getUserOplogInfo(),
         description: `squash ${source.slice(0, 8)} into ${destChangeId.slice(0, 8)}`,
         parents: [],
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -2872,6 +3336,12 @@ export async function createJJ(options) {
         throw new JJError('CHANGE_NOT_FOUND', `Change ${changeId} not found`);
       }
 
+      // Captured BEFORE anything mutates — see issue #38: abandoning the
+      // change @ currently points at must move @ off it (real jj checks
+      // out a fresh empty change on the abandoned change's own parent(s));
+      // abandoning any OTHER change must leave @ exactly where it was.
+      const wasWorkingCopy = changeId === workingCopy.getCurrentChangeId();
+
       // Dispatch change:abandoning event (preventable)
       await dispatchEventAsync(jj, 'change:abandoning', {
         operation: 'abandon',
@@ -2880,15 +3350,29 @@ export async function createJJ(options) {
         timestamp: new Date().toISOString(),
       });
 
+      // Snapshot BEFORE mutating so undo()/redo()/operations.restore() can
+      // reverse the abandon (un-abandon this change, un-reparent children)
+      // — see issue #29.
+      /** @type {Record<string, any>} */
+      const changeSnapshot = { [changeId]: structuredClone(change) };
+
       change.abandoned = true;
       await graph.updateChange(change);
 
+      // Re-parent children onto the abandoned change's own parent(s)
+      // (issue #30: this used to leave children pointing at the now-
+      // abandoned commit). Matches real `jj abandon`: the abandoned
+      // change is elided from the graph and its children attach directly
+      // to whatever it was attached to.
+      await reparentChildrenOnto(changeId, change.parents, changeSnapshot);
+
       // Record operation
       await oplog.recordOperation({
         timestamp: new Date().toISOString(),
         user: { name: user.name, email: user.email, hostname: 'localhost' },
         description: `abandon change ${changeId.slice(0, 8)}`,
         parents: [],
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -2910,9 +3394,220 @@ export async function createJJ(options) {
         { cancelable: false }
       );
 
+      // If @ was pointing at the change we just abandoned, it can't stay
+      // there — real jj moves @ to a new empty change on the abandoned
+      // change's own parent(s) (issue #38). Reuse new()'s own "create an
+      // empty change with given parents" logic rather than duplicating it
+      // — this is exactly the workaround callers had to reach for
+      // themselves (`new({ parents: [parentOfAt] })` before abandoning).
+      if (wasWorkingCopy) {
+        const newWorkingCopyChange = await jj.new({ parents: change.parents || [] });
+        return { ...change, newWorkingCopyChangeId: newWorkingCopyChange.changeId };
+      }
+
       return change;
     },
 
+    /**
+     * Converge divergent copies of a change (matches `jj converge`, jj
+     * v0.45.0+ — issue #32, extended for N-way per the isomorphic-jj v0.45
+     * catch-up follow-up) — resolves ANY number of divergent copies of one
+     * changeId in a single call. Real jj's own CLI currently only
+     * converges one change-id per invocation (an explicit TODO in its own
+     * source as of v0.45.1: "consider adding logic to deal with more than
+     * one divergent change-id in one invocation"), which is what fixed
+     * this package's own changeId-at-a-time API design — but its
+     * underlying engine (`TruncatedEvolutionGraph`/`find_divergent_changes`)
+     * already resolves every divergent revision of THAT one change-id
+     * together, not just a pair. This generalizes the same per-path rule
+     * accordingly: two-way "does the other side's value differ from base"
+     * becomes N-way "how many DISTINCT values, across every copy, differ
+     * from base" — 0 means nobody touched it, 1 means exactly one copy (or
+     * several copies agreeing on the same new value) changed it and that
+     * value wins, 2+ is a genuine conflict between that many copies.
+     *
+     * A change is divergent when more than one visible commit shares its
+     * change id (see the `divergent()` revset, and
+     * ChangeGraph.addDivergentCopy() for how a divergent copy gets added
+     * in the first place — nothing in this library creates one on its
+     * own yet; this resolves one once something has, e.g. a future git
+     * fetch/concurrent-operation integration).
+     *
+     * Non-interactive-mode convention, matching this package's other
+     * ambiguous-outcome APIs: like merge(), a genuine per-path conflict is
+     * returned as data (`{ resolved: false, conflicts }`), not thrown —
+     * you get a result back either way and decide what to do with
+     * unresolved conflicts. What DOES throw is anything that isn't even a
+     * well-formed convergence attempt (no divergence to resolve at all) —
+     * the same category as merge()'s own `MERGE_ERROR` throw for "no
+     * common ancestor found".
+     *
+     * @param {Record<string, any>|string} args - `{ changeId }`, or a bare changeId string
+     * @returns {Promise<Object>} `{ changeId, resolved, conflicts, commitId? }`
+     */
+    async converge(args) {
+      const changeId = typeof args === 'string' ? args : args && (args.changeId || args.change);
+      if (!changeId || typeof changeId !== 'string') {
+        throw new JJError('INVALID_ARGUMENT', 'Missing changeId argument', {
+          suggestion: 'Provide the divergent changeId to converge: { changeId: "..." }',
+        });
+      }
+
+      await graph.load();
+      await userConfig.load();
+      const siblings = graph.getDivergentSiblings(changeId);
+
+      if (siblings.length < 2) {
+        throw new JJError(
+          'NOT_DIVERGENT',
+          `Change ${changeId} has no divergent copies to converge`,
+          {
+            changeId,
+            suggestion:
+              'converge() is only meaningful for a changeId the divergent() revset reports',
+          }
+        );
+      }
+
+      // The primary copy is whichever one getChange() resolves (stored
+      // under the plain changeId key); every other one is a divergent copy
+      // added via addDivergentCopy(). No cap on how many — see the doc
+      // comment above.
+      const primary = /** @type {any} */ (await graph.getChange(changeId));
+      const others = siblings.filter((/** @type {any} */ s) => s.commitId !== primary.commitId);
+
+      // Base for the N-way merge: what this change looked like before it
+      // diverged. This package doesn't retain historical snapshots (only
+      // current content), so — same pragmatic choice rebase() makes for
+      // "old base" — use the shared parent's current content; divergent
+      // copies realistically share the same parent, since they're all
+      // rewrites of one prior position in history, not unrelated commits
+      // that happen to collide. Applied uniformly to every copy, not
+      // per-copy — the same simplification the original two-way version
+      // made, just not newly introduced by going N-way.
+      const baseParentId = primary.parents && primary.parents[0];
+      const baseParentChange = baseParentId ? await graph.getChange(baseParentId) : null;
+      const baseFiles = new Map(
+        Object.entries((baseParentChange && baseParentChange.fileSnapshot) || {})
+      );
+
+      // Every copy (primary + others), each as its own file map, paired
+      // with its commitId for conflict reporting.
+      const copies = [primary, ...others].map((/** @type {any} */ c) => ({
+        commitId: c.commitId,
+        files: new Map(Object.entries(c.fileSnapshot || {})),
+      }));
+
+      await conflicts.load();
+      const conflictsSnapshot = {
+        conflicts: Object.fromEntries(conflicts.conflicts),
+        fileConflicts: Object.fromEntries(conflicts.fileConflicts),
+      };
+
+      const allPaths = new Set([
+        ...baseFiles.keys(),
+        ...copies.flatMap((c) => [...c.files.keys()]),
+      ]);
+
+      /** @type {Record<string, string>} */
+      const mergedSnapshot = {};
+      /** @type {any[]} */
+      const detectedConflicts = [];
+
+      for (const filePath of allPaths) {
+        const baseValue = baseFiles.get(filePath);
+        // Every DISTINCT value across all copies that differs from base,
+        // each paired with (one of) the commitId(s) that has it — mirrors
+        // ConflictModel._detectPathConflict's two-way "no conflict" rules,
+        // generalized: 0 distinct changed values means nobody touched it
+        // (base wins, i.e. nothing to write), 1 means only one side (or
+        // several copies agreeing) changed it (that value wins), 2+ is a
+        // genuine conflict.
+        const changed = new Map();
+        for (const copy of copies) {
+          const value = copy.files.get(filePath);
+          if (value !== baseValue && !changed.has(value)) {
+            changed.set(value, copy.commitId);
+          }
+        }
+
+        if (changed.size === 0) {
+          if (baseValue !== undefined) mergedSnapshot[filePath] = baseValue;
+        } else if (changed.size === 1) {
+          const [[value]] = changed;
+          if (value !== undefined) mergedSnapshot[filePath] = value;
+        } else {
+          const versions = [...changed.entries()].map(([content, commitId]) => ({
+            commitId,
+            content,
+          }));
+          detectedConflicts.push(conflicts.createNWayConflict(filePath, baseValue, versions));
+        }
+      }
+
+      if (detectedConflicts.length > 0) {
+        // Matches real jj: non-interactive mode aborts automatic
+        // resolution rather than guessing — but per this package's own
+        // merge() convention, that's reported back as data, not thrown.
+        for (const conflict of detectedConflicts) {
+          await conflicts.addConflict(conflict);
+        }
+        await oplog.recordOperation({
+          timestamp: new Date().toISOString(),
+          user: await getUserOplogInfo(),
+          description: `converge ${changeId.slice(0, 8)} (unresolved)`,
+          parents: [],
+          conflictsSnapshot,
+          view: {
+            bookmarks: {},
+            remoteBookmarks: {},
+            heads: [],
+            workingCopy: workingCopy.getCurrentChangeId(),
+          },
+        });
+        return { changeId, resolved: false, conflicts: detectedConflicts };
+      }
+
+      const user = /** @type {any} */ (userConfig.getUser());
+      const changeSnapshot = { [changeId]: structuredClone(primary) };
+      const otherIds = others.map((/** @type {any} */ o) => o.commitId.slice(0, 8)).join(', ');
+
+      const convergedChange = {
+        ...primary,
+        commitId: randomHex(20),
+        fileSnapshot: mergedSnapshot,
+        description: primary.description + `\n\n(converged divergent copies: ${otherIds})`,
+        timestamp: new Date().toISOString(),
+        committer: {
+          name: user.name,
+          email: user.email,
+          timestamp: new Date().toISOString(),
+        },
+        divergent: false,
+      };
+      await graph.updateChange(convergedChange);
+      for (const other of others) {
+        await graph.deleteDivergentCopy(changeId, other.commitId);
+      }
+
+      await oplog.recordOperation({
+        timestamp: new Date().toISOString(),
+        user: await getUserOplogInfo(),
+        description: `converge ${changeId.slice(0, 8)}`,
+        parents: [],
+        changeSnapshot,
+        conflictsSnapshot,
+        view: {
+          bookmarks: {},
+          remoteBookmarks: {},
+          heads: [changeId],
+          workingCopy: workingCopy.getCurrentChangeId(),
+        },
+      });
+
+      return { changeId, resolved: true, conflicts: [], commitId: convergedChange.commitId };
+    },
+
     /**
      * Backout a change - create a new change that reverses the effect of the specified change
      *
@@ -4752,8 +5447,14 @@ export async function createJJ(options) {
        * @returns {Promise<Object>} Repository root information
        */
       async root() {
-        // Return the directory containing .git
-        const gitDir = path.join(dir, '.git');
+        // `dir` is a real host filesystem path (unlike the repo-relative
+        // git/jj paths `path` — posix-path.js — is for), so it needs the
+        // host's own separator here, not always '/': on Windows Node's real
+        // `fs` still resolves a forward-slash-joined path fine, but this
+        // method hands the string back to the caller as data, and jj's own
+        // `git root` returns a platform-native path there.
+        const isWin32 = typeof process !== 'undefined' && process.platform === 'win32';
+        const gitDir = isWin32 ? `${dir.replace(/[\\/]+$/, '')}\\.git` : path.join(dir, '.git');
 
         try {
           await fs.promises.access(gitDir);
@@ -4832,7 +5533,7 @@ export async function createJJ(options) {
       const wcFiles = await workingCopy.listFiles();
       for (const file of wcFiles) {
         try {
-          const content = await fs.promises.readFile(path.join(dir, file), 'utf-8');
+          const content = await fs.promises.readFile(path.join(dir, file), 'utf8');
           leftFiles.set(file, content);
         } catch (error) {
           // File might be deleted or binary - throw error for explicit handling
@@ -4975,7 +5676,7 @@ export async function createJJ(options) {
         }
 
         // Write resolved content to file
-        await fs.promises.writeFile(path.join(dir, conflict.path), resolvedContent, 'utf-8');
+        await fs.promises.writeFile(path.join(dir, conflict.path), resolvedContent, 'utf8');
 
         // Mark conflict as resolved
         await conflicts.resolveConflict(args.conflictId, 'manual');
@@ -5018,7 +5719,7 @@ export async function createJJ(options) {
             const resolvedContent = _resolveWithStrategy(conflict, args.strategy);
 
             // Write resolved content
-            await fs.promises.writeFile(path.join(dir, conflict.path), resolvedContent, 'utf-8');
+            await fs.promises.writeFile(path.join(dir, conflict.path), resolvedContent, 'utf8');
 
             // Mark as resolved
             await conflicts.resolveConflict(conflict.conflictId, args.strategy);
@@ -5458,7 +6159,7 @@ export async function createJJ(options) {
                 if (pathParts.length > 1) {
                   const dirPath = pathParts.slice(0, -1).join('/');
                   const fullDirPath = path.join(args.path, dirPath);
-                  await fs.promises.mkdir(fullDirPath, { recursive: true });
+                  await mkdirp(fs, fullDirPath);
                 }
 
                 // Write file content