isomorphic-jj 1.8.0 → 1.9.2

package/dist/index.mjs

@@ -1,8 +1,5 @@
-import path from 'path';
 import git from 'isomorphic-git';
-import protobuf from 'protobufjs';
-import { fileURLToPath } from 'url';
-import crypto$1 from 'crypto';
+import protobuf from 'protobufjs/light.js';
 
 /**
  * JJError - Custom error class for isomorphic-jj
@@ -90,6 +87,48 @@ class KeyedMutex {
   }
 }
 
+/**
+ * Recursive directory creation that works across filesystem backends.
+ *
+ * Why not `fs.promises.mkdir(path, { recursive: true })`: that's a Node
+ * `fs` feature. `@isomorphic-git/lightning-fs` (the filesystem this library
+ * documents for browser use — see issue #28) implements `mkdir()` but
+ * silently ignores the `recursive` option and throws `ENOENT` if any
+ * intermediate directory is missing, so code that assumed Node's recursive
+ * mkdir semantics would work identically against LightningFS actually
+ * broke the very first real repo init in a browser. This walks the path
+ * one segment at a time and creates each directory that doesn't exist yet,
+ * which is correct against both Node's `fs` and LightningFS (and is a
+ * harmless no-op-per-segment against Node's `fs` too).
+ *
+ * @param {any} fs - Filesystem implementation (isomorphic-git compatible;
+ *   needs `fs.promises.mkdir(path)`)
+ * @param {string} dirPath - Absolute, POSIX-style directory path to create
+ * @returns {Promise<void>}
+ */
+async function mkdirp(fs, dirPath) {
+  const isAbsolute = dirPath.charCodeAt(0) === 47; // '/'
+  const prefix = isAbsolute ? '/' : '';
+  const segments = dirPath.split('/').filter(Boolean);
+
+  // Compare against `current === ''` (not a truthiness check) below: the
+  // first accumulated segment of an absolute path is itself just `/x`,
+  // which parses fine, but a naive `current ? ... : ...` truthiness check
+  // would treat the *string* `''` the same as "unset" forever and never
+  // prepend the leading `/`.
+  let current = '';
+  for (const segment of segments) {
+    current = current === '' ? prefix + segment : `${current}/${segment}`;
+    try {
+      await fs.promises.mkdir(current);
+    } catch (err) {
+      // Already exists — fine, that's exactly what "recursive" means.
+      if (err && (err.code === 'EEXIST' || err.code === 'EISDIR')) continue;
+      throw err;
+    }
+  }
+}
+
 /**
  * Storage Manager for isomorphic-jj
  *
@@ -130,17 +169,17 @@ class Storage {
   async init() {
     try {
       // Create main directories
-      await this.fs.promises.mkdir(this.jjDir, { recursive: true });
-      await this.fs.promises.mkdir(this.repoDir, { recursive: true });
-      await this.fs.promises.mkdir(this.workingCopyDir, { recursive: true });
+      await mkdirp(this.fs, this.jjDir);
+      await mkdirp(this.fs, this.repoDir);
+      await mkdirp(this.fs, this.workingCopyDir);
 
       // Create repo subdirectories
-      await this.fs.promises.mkdir(`${this.repoDir}/store`, { recursive: true });
-      await this.fs.promises.mkdir(`${this.repoDir}/op_log`, { recursive: true });
-      await this.fs.promises.mkdir(`${this.repoDir}/conflicts`, { recursive: true });
+      await mkdirp(this.fs, `${this.repoDir}/store`);
+      await mkdirp(this.fs, `${this.repoDir}/op_log`);
+      await mkdirp(this.fs, `${this.repoDir}/conflicts`);
 
       // Create default workspace directory
-      await this.fs.promises.mkdir(`${this.workingCopyDir}/default`, { recursive: true });
+      await mkdirp(this.fs, `${this.workingCopyDir}/default`);
     } catch (error) {
       throw new JJError(
         'STORAGE_INIT_FAILED',
@@ -217,7 +256,7 @@ class Storage {
     try {
       // Ensure parent directory exists
       const dirPath = fullPath.substring(0, fullPath.lastIndexOf('/'));
-      await this.fs.promises.mkdir(dirPath, { recursive: true });
+      await mkdirp(this.fs, dirPath);
 
       // Write to temp file
       await this.fs.promises.writeFile(tmpPath, jsonData, 'utf8');
@@ -473,6 +512,75 @@ function validateBookmarkName(name) {
   }
 }
 
+/**
+ * ID Generation utilities for isomorphic-jj
+ *
+ * Generates stable change IDs and operation IDs using cryptographically secure random values.
+ */
+
+/**
+ * Generate `byteLength` cryptographically random bytes as a lowercase hex string.
+ *
+ * Uses the standard Web Crypto API (`crypto.getRandomValues`), available as
+ * a global in both Node.js (18.14+) and every browser — unlike Node's
+ * `crypto.randomBytes`, which requires `import 'crypto'` and does not exist
+ * in a browser bundle (see issue #28).
+ *
+ * @param {number} byteLength - Number of random bytes to generate
+ * @returns {string} `byteLength * 2`-character lowercase hex string
+ */
+function randomHex(byteLength) {
+  const bytes = crypto.getRandomValues(new Uint8Array(byteLength));
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate a stable change ID
+ *
+ * Uses 128-bit cryptographically random value encoded as 32-character hex string.
+ * Collision probability is negligible (2^128 space).
+ *
+ * @returns {string} 32-character lowercase hex string
+ */
+function generateChangeId() {
+  return randomHex(16);
+}
+
+/**
+ * Generate an operation ID from operation content
+ *
+ * Uses SHA-256 hash of operation content for integrity verification.
+ *
+ * @param {Object.<string, any>} operation - Operation data
+ * @returns {Promise<string>} 64-character lowercase hex string (SHA-256)
+ */
+async function generateOperationId(operation) {
+  const content = JSON.stringify({
+    timestamp: operation.timestamp,
+    user: operation.user,
+    description: operation.description,
+    parents: operation.parents,
+    view: operation.view,
+  });
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(content);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate a generic ID with optional prefix
+ *
+ * @param {string} prefix - Optional prefix (e.g., 'conflict', 'bookmark')
+ * @returns {string} ID string
+ */
+function generateId(prefix = '') {
+  const id = randomHex(16);
+  return prefix ? `${prefix}-${id}` : id;
+}
+
 /**
  * ChangeGraph - Manages the change graph with stable change IDs
  *
@@ -568,6 +676,68 @@ class ChangeGraph {
     await this.save();
   }
 
+  /**
+   * Add a DIVERGENT copy of an existing change: another commit that also
+   * claims `change.changeId` (see issue #32 / the `divergent()` revset —
+   * "multiple visible commits sharing one change id"). `addChange()`
+   * can't represent this: `nodes` is a `Map<changeId, change>`, one entry
+   * per key, by design — every other API (getChange, getParents,
+   * getChildren, ...) keys on plain changeId and would be ambiguous if
+   * that stopped being unique.
+   *
+   * Divergent copies are therefore stored under a synthetic internal key
+   * (`${changeId}\0${commitId}`) so the `nodes` Map stays a true map, but
+   * each copy's *own* `changeId` field is unchanged — so `getAll()` (and
+   * therefore the existing `divergent()` revset filter, which counts
+   * occurrences of `c.changeId` across `getAll()`) sees both/all of them
+   * and correctly reports the change as divergent. `getChange(changeId)`
+   * deliberately keeps resolving to just the primary copy (the one
+   * actually stored under the plain `changeId` key) — for anything that
+   * needs every copy, see getDivergentSiblings().
+   *
+   * @param {Record<string, any>} change - The divergent copy (must have
+   *   the same `changeId` as an existing change, and its own `commitId`)
+   */
+  async addDivergentCopy(change) {
+    validateChangeId(change.changeId);
+
+    if (!this.nodes.has(change.changeId)) {
+      throw new JJError(
+        'CHANGE_NOT_FOUND',
+        `Cannot add a divergent copy of ${change.changeId}: no existing change with that id`,
+        { changeId: change.changeId, suggestion: 'Use addChange() to create the first copy' }
+      );
+    }
+
+    const key = `${change.changeId}\0${change.commitId}`;
+    if (this.nodes.has(key)) {
+      throw new JJError(
+        'CHANGE_EXISTS',
+        `Change ${change.changeId} already has a divergent copy with commit ${change.commitId}`,
+        { changeId: change.changeId, commitId: change.commitId }
+      );
+    }
+
+    change.divergent = true;
+    this.nodes.set(key, change);
+    this.commitIndex.set(change.commitId, change.changeId);
+
+    await this.save();
+  }
+
+  /**
+   * Get every visible copy of a (possibly divergent) change id — just the
+   * one copy in the common case, or the primary plus every divergent copy
+   * added via addDivergentCopy().
+   *
+   * @param {string} changeId - Change ID
+   * @returns {Array<any>} All copies sharing this changeId, primary first
+   */
+  getDivergentSiblings(changeId) {
+    validateChangeId(changeId);
+    return this.getAll().filter((change) => change.changeId === changeId);
+  }
+
   /**
    * Get a change by ID
    *
@@ -679,6 +849,65 @@ class ChangeGraph {
     await this.save();
   }
 
+  /**
+   * Remove one divergent copy added via addDivergentCopy() — e.g. after
+   * converge() (issue #32) resolves a divergence and only needs to drop
+   * the now-superseded copy. The *primary* copy (stored under the plain
+   * `changeId` key) is never touched by this — use deleteChange() (or
+   * updateChange() to overwrite it with a resolved result) for that.
+   *
+   * @param {string} changeId
+   * @param {string} commitId - The divergent copy's own commit id
+   * @returns {Promise<boolean>} Whether a copy was actually removed
+   */
+  async deleteDivergentCopy(changeId, commitId) {
+    validateChangeId(changeId);
+
+    const key = `${changeId}\0${commitId}`;
+    const change = this.nodes.get(key);
+    if (!change) {
+      return false;
+    }
+
+    this.nodes.delete(key);
+    if (this.commitIndex.get(commitId) === changeId) {
+      this.commitIndex.delete(commitId);
+    }
+
+    await this.save();
+    return true;
+  }
+
+  /**
+   * Remove a change from the graph outright.
+   *
+   * Used to reverse an addChange() — e.g. undoing an operation that created
+   * a change (new(), or squash()'s synthetic empty working-copy change) —
+   * where restoring a "before" snapshot doesn't apply because there was no
+   * "before": the change simply didn't exist yet. A soft-delete (setting
+   * `abandoned: true` via updateChange()) is NOT the same thing and is used
+   * separately for abandon() itself.
+   *
+   * @param {string} changeId - Change ID to remove
+   * @returns {Promise<boolean>} Whether a change was actually removed
+   */
+  async deleteChange(changeId) {
+    validateChangeId(changeId);
+
+    const change = this.nodes.get(changeId);
+    if (!change) {
+      return false;
+    }
+
+    this.nodes.delete(changeId);
+    if (this.commitIndex.get(change.commitId) === changeId) {
+      this.commitIndex.delete(change.commitId);
+    }
+
+    await this.save();
+    return true;
+  }
+
   /**
    * Get all ancestors of a change (recursive parent traversal)
    *
@@ -716,10 +945,9 @@ class ChangeGraph {
    * @returns {Promise<Record<string, any>>} Created change object
    */
   async createChange(params = {}) {
-    const crypto = await import('crypto');
-    const changeId = params.changeId || crypto.randomBytes(16).toString('hex');
-    const commitId = params.commitId || crypto.randomBytes(20).toString('hex');
-    const tree = params.tree || crypto.randomBytes(20).toString('hex');
+    const changeId = params.changeId || randomHex(16);
+    const commitId = params.commitId || randomHex(20);
+    const tree = params.tree || randomHex(20);
     const timestamp = params.timestamp || new Date().toISOString();
 
     /** @type {Record<string, any>} */
@@ -761,6 +989,44 @@ class ChangeGraph {
  */
 
 
+/**
+ * Normalize an mtime value to a millisecond epoch number so two stat()
+ * results (or a stat() result and a stored value) can be compared by VALUE
+ * instead of by object identity (see issue #41).
+ *
+ * `fs.promises.stat()` returns a fresh `Date` instance on every call, so two
+ * separate stats of the same unchanged file are never `===`/`!==`-equal even
+ * when the underlying timestamp is identical. Additionally, once a tracked
+ * mtime has been through a `JSON.stringify`/`JSON.parse` round-trip (Storage
+ * persists working-copy state as JSON), a `Date` becomes an ISO string, not a
+ * `Date` — so the stored side of the comparison may be a `Date`, a plain
+ * epoch-ms number (this module now stores numbers going forward), or an ISO
+ * string (older/reloaded-from-disk state). This normalizes all three to a
+ * comparable number.
+ *
+ * Deliberately duck-types the Date case (`typeof value.getTime ===
+ * 'function'`) instead of `value instanceof Date`: Node's built-in `fs`
+ * module constructs `Stats.mtime` using its own realm's `Date`, which is not
+ * always the same `Date` constructor as this module's under test runners
+ * that sandbox each test file in its own VM context (observed under Jest
+ * with `--experimental-vm-modules`) — there, a real `Date` instance from
+ * `fs.promises.stat()` fails `instanceof Date` here even though it's a
+ * genuine Date. Duck-typing survives that realm mismatch.
+ *
+ * @param {Date|number|string|undefined} value
+ * @returns {number}
+ */
+function mtimeMs(value) {
+  if (value === null || value === undefined) return NaN;
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return new Date(value).getTime();
+  // Per the type contract above, anything left is Date-like -- duck-typed
+  // (see the comment above) rather than `instanceof Date`, so no runtime
+  // check is needed here either; a value outside this contract is a caller
+  // bug, not something to silently coerce.
+  return /** @type {any} */ (value).getTime();
+}
+
 class WorkingCopy {
   /**
    * @param {Storage} storage - Storage manager instance
@@ -932,8 +1198,10 @@ class WorkingCopy {
       try {
         const stats = await this.fs.promises.stat(fullPath);
 
-        // Fast path: check mtime and size
-        if (stats.mtime !== tracked.mtime || stats.size !== tracked.size) {
+        // Fast path: check mtime and size. Compare by VALUE (see mtimeMs
+        // above) — comparing the raw stat()/stored values with !== is
+        // always "different" even when nothing changed (issue #41).
+        if (mtimeMs(stats.mtime) !== mtimeMs(tracked.mtime) || stats.size !== tracked.size) {
           modified.push(path);
         }
       } catch (error) {
@@ -1044,12 +1312,19 @@ class WorkingCopy {
       }
 
       const prev = this.state.fileStates[rel];
-      const next = { mtime: stats.mtime, size: stats.size, mode: stats.mode };
+      // Store mtime as a plain epoch-ms number (not the raw stat() value):
+      // numbers round-trip through JSON exactly, so state reloaded from disk
+      // later compares identically to state still cached in-memory. Goes
+      // through mtimeMs() rather than assuming `.getTime()` exists directly —
+      // some fs implementations (e.g. the in-memory mock used in tests)
+      // return mtime as a plain epoch-ms number already, not a Date (see
+      // mtimeMs above and issue #41).
+      const next = { mtime: mtimeMs(stats.mtime), size: stats.size, mode: stats.mode };
 
       if (!prev) {
         this.state.fileStates[rel] = next;
         added.push(rel);
-      } else if (prev.mtime !== stats.mtime || prev.size !== stats.size) {
+      } else if (mtimeMs(stats.mtime) !== mtimeMs(prev.mtime) || prev.size !== stats.size) {
         this.state.fileStates[rel] = next;
         modified.push(rel);
       }
@@ -1183,61 +1458,6 @@ class WorkingCopy {
   }
 }
 
-/**
- * ID Generation utilities for isomorphic-jj
- *
- * Generates stable change IDs and operation IDs using cryptographically secure random values.
- */
-
-/**
- * Generate a stable change ID
- *
- * Uses 128-bit cryptographically random value encoded as 32-character hex string.
- * Collision probability is negligible (2^128 space).
- *
- * @returns {string} 32-character lowercase hex string
- */
-function generateChangeId() {
-  const bytes = crypto.getRandomValues(new Uint8Array(16));
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
-}
-
-/**
- * Generate an operation ID from operation content
- *
- * Uses SHA-256 hash of operation content for integrity verification.
- *
- * @param {Object.<string, any>} operation - Operation data
- * @returns {Promise<string>} 64-character lowercase hex string (SHA-256)
- */
-async function generateOperationId(operation) {
-  const content = JSON.stringify({
-    timestamp: operation.timestamp,
-    user: operation.user,
-    description: operation.description,
-    parents: operation.parents,
-    view: operation.view,
-  });
-
-  const encoder = new TextEncoder();
-  const data = encoder.encode(content);
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-}
-
-/**
- * Generate a generic ID with optional prefix
- *
- * @param {string} prefix - Optional prefix (e.g., 'conflict', 'bookmark')
- * @returns {string} ID string
- */
-function generateId(prefix = '') {
-  const bytes = crypto.getRandomValues(new Uint8Array(16));
-  const id = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
-  return prefix ? `${prefix}-${id}` : id;
-}
-
 /**
  * OperationLog - Manages the append-only operation log
  *
@@ -1854,11 +2074,7 @@ class TagStore {
   async save(tags) {
     // Ensure the store directory exists
     const storeDir = `${this.jjDir}/store`;
-    try {
-      await this.fs.promises.mkdir(storeDir, { recursive: true });
-    } catch (err) {
-      // Directory might already exist, ignore
-    }
+    await mkdirp(this.fs, storeDir);
     await this.fs.promises.writeFile(
       this.tagsFile,
       JSON.stringify({ tags, tracked: this.tracking || {} }, null, 2)
@@ -2497,9 +2713,12 @@ class RevsetEngine {
     const unquote = (/** @type {string} */ s) => s.trim().replace(/^['"]|['"]$/g, '');
 
     switch (name) {
-      case 'all':
+      case 'all': {
         await this.graph.load();
-        return this.graph.getAll().map((c) => c.changeId);
+        const allChanges = this.graph.getAll();
+        const hidden = await this._computeHiddenOrphans(allChanges);
+        return allChanges.filter((c) => !hidden.has(c.changeId)).map((c) => c.changeId);
+      }
 
       // `builtin_log()` (jj v0.44) is the revset the built-in `jj log` uses
       // when no user override is configured. isomorphic-jj's `log()` already
@@ -2507,9 +2726,12 @@ class RevsetEngine {
       // `builtin_log()` is a pure alias for that same default — this lets
       // callers compose it (e.g. `builtin_log() & mine()`) instead of
       // duplicating `all()`.
-      case 'builtin_log':
+      case 'builtin_log': {
         await this.graph.load();
-        return this.graph.getAll().map((c) => c.changeId);
+        const allChanges = this.graph.getAll();
+        const hidden = await this._computeHiddenOrphans(allChanges);
+        return allChanges.filter((c) => !hidden.has(c.changeId)).map((c) => c.changeId);
+      }
 
       case 'none':
         return [];
@@ -2624,15 +2846,27 @@ class RevsetEngine {
       }
 
       case 'divergent': {
+        // See issue #32 / converge(): a divergent change has more than one
+        // visible commit sharing its changeId (added via
+        // ChangeGraph.addDivergentCopy(), which is why counting `changeId`
+        // occurrences across getAll() actually finds something now —
+        // every other change has exactly one entry here). `c.divergent ===
+        // true` also matches directly, since addDivergentCopy() sets that
+        // flag on the copy it adds; the count check catches the *primary*
+        // copy too (it's never itself flagged, since nothing about IT
+        // changed) so both/all copies of a divergent changeId are
+        // reported, not just the one(s) added after the first.
         await this.graph.load();
         const all = this.graph.getAll();
         const counts = new Map();
         for (const c of all) {
           counts.set(c.changeId, (counts.get(c.changeId) || 0) + 1);
         }
-        return all
-          .filter((c) => c.divergent === true || counts.get(c.changeId) > 1)
-          .map((c) => c.changeId);
+        const matched = all.filter((c) => c.divergent === true || counts.get(c.changeId) > 1);
+        // De-duplicate: multiple copies of the same divergent changeId
+        // would otherwise each contribute their own (identical) changeId
+        // to the result.
+        return Array.from(new Set(matched.map((c) => c.changeId)));
       }
 
       case 'merges':
@@ -2958,6 +3192,108 @@ class RevsetEngine {
     return ancestors;
   }
 
+  /**
+   * Change IDs that `all()`/`builtin_log()` (and therefore the default
+   * `jj.log()`) should exclude — issue #37(b).
+   *
+   * undo()/redo()/operations.restore() deliberately don't delete a change
+   * record for a `new()`/`squash()` that gets reverted — they only un-ref
+   * it (restore the working-copy pointer/heads that made it reachable),
+   * matching real jj where an unreachable change stays resolvable by its
+   * change id (hidden, not gone) until explicitly gc'd — see
+   * computeGraphReversal's doc comment in repository.js. But that means
+   * the orphaned change record lingers in the graph, and before this fix
+   * `all()` (a flat `graph.getAll()`) surfaced it in `log()` right
+   * alongside everything still actually reachable.
+   *
+   * Real jj hides a commit from the default log when it is BOTH:
+   *   - unreachable from any visible head (not itself a head, and not an
+   *     ancestor of one), AND
+   *   - "discardable": empty (no file diff versus its own parent) and
+   *     undescribed.
+   * Merge commits (2+ parents) are conservatively never treated as
+   * "empty" here — real jj's diff-emptiness rule for merges is more
+   * involved and isn't needed by anything this package creates today.
+   *
+   * "Visible head" here deliberately does NOT mean "any change with no
+   * children" (that's what the `visible_heads()` revset function computes,
+   * structurally, from the raw graph) — an orphan `new()`/`squash()`
+   * change that undo() un-referenced has no children EITHER, so it would
+   * trivially count as its own head under that definition and never be
+   * excludable. Real jj instead tracks an explicit, maintained set of
+   * heads in its View (updated as operations run — abandoning/squashing a
+   * change removes it, rebasing children onto a new parent removes the
+   * old parent, etc.). This package doesn't thread the operation log's
+   * `view.heads` through to the revset engine, but the working-copy
+   * pointer plus every bookmark/tag target is the closest available
+   * proxy for "what's actually still in play" — anything only reachable
+   * from those, not from every dangling graph leaf.
+   *
+   * @param {any[]} allChanges - `graph.getAll()`
+   * @returns {Promise<Set<string>>} change IDs to exclude
+   */
+  async _computeHiddenOrphans(allChanges) {
+    const trackedHeads = new Set();
+    try {
+      const wcId = this.workingCopy && this.workingCopy.getCurrentChangeId();
+      if (wcId) trackedHeads.add(wcId);
+    } catch {
+      // working copy not loaded/available — fine, just no wc-based root.
+    }
+    if (this.bookmarkStore) {
+      await this.bookmarkStore.load();
+      for (const bookmark of await this.bookmarkStore.list()) {
+        if (bookmark && bookmark.changeId) trackedHeads.add(bookmark.changeId);
+      }
+    }
+    if (this.tagStore) {
+      for (const tag of await this.tagStore.list()) {
+        if (tag && tag.changeId) trackedHeads.add(tag.changeId);
+      }
+    }
+
+    const reachable = new Set();
+    for (const headId of trackedHeads) {
+      for (const id of await this.getAncestors(headId)) {
+        reachable.add(id);
+      }
+    }
+
+    // Sentinel "no message given" descriptions this package itself writes
+    // (new()'s '(no description)', squash()'s post-squash working-copy
+    // change '(no description set)') are, for visibility purposes, just
+    // as undescribed as a genuinely empty/missing description field.
+    const UNDESCRIBED = new Set([undefined, null, '', '(no description)', '(no description set)']);
+
+    const byId = new Map(allChanges.map((c) => [c.changeId, c]));
+    const isEmpty = (/** @type {any} */ change) => {
+      const parents = change.parents || [];
+      if (parents.length === 0) {
+        return !change.fileSnapshot || Object.keys(change.fileSnapshot).length === 0;
+      }
+      if (parents.length > 1) return false; // merges: not handled by this rule
+      const parent = byId.get(parents[0]);
+      const parentSnapshot = (parent && parent.fileSnapshot) || {};
+      const ownSnapshot = change.fileSnapshot || {};
+      const parentKeys = Object.keys(parentSnapshot);
+      const ownKeys = Object.keys(ownSnapshot);
+      if (parentKeys.length !== ownKeys.length) return false;
+      return parentKeys.every((k) => parentSnapshot[k] === ownSnapshot[k]);
+    };
+
+    const hidden = new Set();
+    for (const change of allChanges) {
+      if (
+        !reachable.has(change.changeId) &&
+        isEmpty(change) &&
+        UNDESCRIBED.has(change.description)
+      ) {
+        hidden.add(change.changeId);
+      }
+    }
+    return hidden;
+  }
+
   /**
    * Resolve a revset argument to a set of change IDs (v1.5).
    *
@@ -3686,43 +4022,221 @@ class RevsetEngine {
 }
 
 /**
- * ConflictModel - First-class conflict handling
+ * Minimal POSIX-only path utilities (join / dirname / resolve).
  *
- * In JJ, conflicts are not errors but structured data that can be:
- * - Stored in commits
- * - Rebased along with changes
- * - Resolved incrementally
- * - Committed and shared
+ * Why not Node's `path` module: this library is isomorphic — it also needs
+ * to run in browser bundles (see issue #28), where bare `import path from
+ * 'path'` fails unless a bundler-specific polyfill is configured. Git/jj
+ * repository paths are always POSIX-style (forward slashes), regardless of
+ * host OS, so depending on Node's `path` module was also subtly wrong on
+ * Windows: `path.join()` there uses `path.win32` semantics and would
+ * produce backslash-joined paths for repository-relative paths, which is
+ * not what git/jj object storage or working-copy paths want.
  *
- * This matches JJ's philosophy: conflicts never block you.
+ * These implement the same normalization rules as Node's `path.posix` for
+ * the operations this codebase actually uses.
+ */
+
+/**
+ * @param {string} path
+ * @returns {string} `path` with any run of `/` collapsed to a single `/`,
+ *   and `.`/`..` segments resolved. Preserves a leading `/` (absolute) and
+ *   a trailing `/` when present in the input.
  */
+function normalize(path) {
+  if (path === '') return '.';
+
+  const isAbsolute = path.charCodeAt(0) === 47; // '/'
+  const trailingSlash = path.charCodeAt(path.length - 1) === 47;
+
+  const segments = path.split('/');
+  /** @type {string[]} */
+  const out = [];
+  for (const segment of segments) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length && out[out.length - 1] !== '..') {
+        out.pop();
+      } else if (!isAbsolute) {
+        out.push('..');
+      }
+      continue;
+    }
+    out.push(segment);
+  }
 
+  let result = out.join('/');
+  if (!result && !isAbsolute) result = '.';
+  if (isAbsolute) result = '/' + result;
+  if (trailingSlash && result.charCodeAt(result.length - 1) !== 47) result += '/';
+  return result;
+}
 
 /**
- * Conflict types supported by JJ
+ * @param {...string} parts
+ * @returns {string} All `parts` joined with `/` and normalized.
  */
-const ConflictType = {
-  CONTENT: 'content', // File content conflicts (3-way merge)
-  DELETE_MODIFY: 'delete-modify', // File deleted in one side, modified in other
-  MODIFY_DELETE: 'modify-delete', // File modified in one side, deleted in other
-  ADD_ADD: 'add-add', // Same path added in both sides
-};
+function join(...parts) {
+  if (parts.length === 0) return '.';
+  const joined = parts.filter((p) => p !== '').join('/');
+  return joined === '' ? '.' : normalize(joined);
+}
 
 /**
- * ConflictModel manages conflict detection, storage, and resolution
+ * @param {string} path
+ * @returns {string} The directory portion of `path` (Node `path.dirname` semantics).
  */
-class ConflictModel {
-  /**
-   * @param {any} storage
-   * @param {any} fs
-   * @param {any} [mergeDriverRegistry]
-   */
-  constructor(storage, fs, mergeDriverRegistry = null) {
-    this.storage = storage;
-    this.fs = fs;
-    /** @type {any} */
-    this.mergeDriverRegistry = mergeDriverRegistry; // v0.5: merge drivers
-    this.conflicts = new Map(); // conflictId -> Conflict
+function dirname(path) {
+  if (path.length === 0) return '.';
+  const isAbsolute = path.charCodeAt(0) === 47;
+  let end = -1;
+  let matchedSlash = true;
+  for (let i = path.length - 1; i >= 1; i--) {
+    if (path.charCodeAt(i) === 47) {
+      if (!matchedSlash) {
+        end = i;
+        break;
+      }
+    } else {
+      matchedSlash = false;
+    }
+  }
+
+  if (end === -1) return isAbsolute ? '/' : '.';
+  if (isAbsolute && end === 0) return '/';
+  return path.slice(0, end);
+}
+
+/**
+ * Resolves a sequence of path segments into an absolute path.
+ *
+ * Unlike Node's `path.resolve`, this never consults the real process cwd —
+ * segments are resolved right-to-left, and if no absolute segment is found
+ * the result is left relative to a virtual `/` root (this library always
+ * deals in absolute repository-relative paths, so callers are expected to
+ * supply an absolute base).
+ *
+ * @param {...string} parts
+ * @returns {string}
+ */
+function resolve(...parts) {
+  let resolved = '';
+  let isAbsolute = false;
+
+  for (let i = parts.length - 1; i >= -1 && !isAbsolute; i--) {
+    const path = i >= 0 ? parts[i] : '/';
+    if (path.length === 0) continue;
+    resolved = path + '/' + resolved;
+    isAbsolute = path.charCodeAt(0) === 47;
+  }
+
+  resolved = normalize(resolved);
+  // normalize() preserves a trailing slash; path.resolve() never returns one
+  // (except for the root itself).
+  if (resolved.length > 1 && resolved.endsWith('/')) {
+    resolved = resolved.slice(0, -1);
+  }
+  return isAbsolute ? resolved : '/' + resolved;
+}
+
+/**
+ * Cross-environment byte/string conversion helpers.
+ *
+ * Why not just Node's `Buffer`: it's a Node global that most browser
+ * bundlers (Vite, esbuild, webpack 5+) do not polyfill by default, so code
+ * that calls `Buffer.from(...)` compiles fine but throws `ReferenceError:
+ * Buffer is not defined` at runtime in a browser bundle (see issue #28).
+ *
+ * `utf8Encode`/`utf8Decode` still prefer the real `Buffer` when it's present
+ * (i.e. under Node) so existing behavior — including `.toString()` producing
+ * the original text back, which a plain `Uint8Array` cannot do — is
+ * unchanged there; `typeof Buffer` is safe to evaluate even where `Buffer`
+ * was never declared (unlike referencing it directly), so this doesn't
+ * reintroduce the crash outside Node. `hexToBytes`/`bytesToHex`/`isBytes`
+ * only ever need `Uint8Array`, so they don't need the same branch.
+ */
+const hasBuffer = typeof Buffer !== 'undefined';
+
+/**
+ * @param {string} hex - Even-length hex string
+ * @returns {Uint8Array}
+ */
+function hexToBytes(hex) {
+  const length = hex.length / 2;
+  const bytes = new Uint8Array(length);
+  for (let i = 0; i < length; i++) {
+    bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * @param {string} str
+ * @returns {Uint8Array} UTF-8 encoded bytes (a real `Buffer` under Node)
+ */
+function utf8Encode(str) {
+  return hasBuffer ? Buffer.from(str, 'utf-8') : new TextEncoder().encode(str);
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} UTF-8 decoded string
+ */
+function utf8Decode(bytes) {
+  return hasBuffer ? Buffer.from(bytes).toString('utf-8') : new TextDecoder('utf-8').decode(bytes);
+}
+
+/**
+ * True for anything that walks/quacks like binary content — a real Node
+ * `Buffer` (which is itself a `Uint8Array` subclass) or a plain
+ * `Uint8Array`/typed array, as produced by protobufjs in environments
+ * without `Buffer` (e.g. a browser bundle).
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isBytes(value) {
+  return value instanceof Uint8Array;
+}
+
+/**
+ * ConflictModel - First-class conflict handling
+ *
+ * In JJ, conflicts are not errors but structured data that can be:
+ * - Stored in commits
+ * - Rebased along with changes
+ * - Resolved incrementally
+ * - Committed and shared
+ *
+ * This matches JJ's philosophy: conflicts never block you.
+ */
+
+
+/**
+ * Conflict types supported by JJ
+ */
+const ConflictType = {
+  CONTENT: 'content', // File content conflicts (3-way merge)
+  DELETE_MODIFY: 'delete-modify', // File deleted in one side, modified in other
+  MODIFY_DELETE: 'modify-delete', // File modified in one side, deleted in other
+  ADD_ADD: 'add-add', // Same path added in both sides
+};
+
+/**
+ * ConflictModel manages conflict detection, storage, and resolution
+ */
+class ConflictModel {
+  /**
+   * @param {any} storage
+   * @param {any} fs
+   * @param {any} [mergeDriverRegistry]
+   */
+  constructor(storage, fs, mergeDriverRegistry = null) {
+    this.storage = storage;
+    this.fs = fs;
+    /** @type {any} */
+    this.mergeDriverRegistry = mergeDriverRegistry; // v0.5: merge drivers
+    this.conflicts = new Map(); // conflictId -> Conflict
     this.fileConflicts = new Map(); // path -> conflictId
   }
 
@@ -3857,6 +4371,15 @@ class ConflictModel {
       const conflict = this._detectPathConflict(path, baseContent, leftContent, rightContent);
       if (conflict) {
         conflicts.push(conflict);
+      } else if (workingCopyDir) {
+        // No conflict, but "no conflict" doesn't mean "nothing to do": of
+        // _detectPathConflict's null-returning cases, every one *except*
+        // "right side changed, left didn't" already matches what's on disk,
+        // because `leftContent` **is** what's on disk (read straight from
+        // the working copy above) -- so only that one case needs a write.
+        if (baseContent === leftContent && baseContent !== rightContent) {
+          await this._applyCleanResolution(workingCopyDir, path, rightContent);
+        }
       }
     }
 
@@ -3944,6 +4467,30 @@ class ConflictModel {
     return null;
   }
 
+  /**
+   * Create a content conflict with more than two disagreeing versions —
+   * every other conflict in this module has exactly two sides (`left`/
+   * `right`, or `left`/`right` on an add-add), because every OTHER caller
+   * (merge, rebase) only ever three-way-merges two changes at a time.
+   * converge() (issue #32) can face more than two divergent copies of one
+   * change in a single call, so `sides` here is `{ base, versions }`
+   * instead: `versions` is every distinct value found across all copies
+   * that differs from `base`, each paired with (one of) the commitId(s)
+   * that has it.
+   *
+   * @param {string} path
+   * @param {any} base
+   * @param {Array<{commitId: string, content: any}>} versions
+   */
+  createNWayConflict(path, base, versions) {
+    return this._createConflict({
+      type: ConflictType.CONTENT,
+      path,
+      sides: { base, versions },
+      message: `${versions.length} divergent copies disagree on this file's content`,
+    });
+  }
+
   /**
    * Create a conflict object
    *
@@ -4187,6 +4734,36 @@ class ConflictModel {
     return result;
   }
 
+  /**
+   * Apply a clean (non-conflicting) three-way resolution to the working
+   * copy, for the default (no merge driver) path in detectConflicts(): the
+   * "right side wins" case, where the resolved content differs from what's
+   * currently on disk (see the call site for why this is the only clean
+   * case that needs one).
+   *
+   * @param {string} workingCopyDir - Working copy directory
+   * @param {string} filePath - File path
+   * @param {any} content - The winning (right) side's content, or
+   *   `undefined` to mean the file was deleted on that side
+   */
+  async _applyCleanResolution(workingCopyDir, filePath, content) {
+    const fullPath = join(workingCopyDir, filePath);
+
+    if (content === undefined) {
+      await this.fs.promises.unlink(fullPath).catch(() => {});
+      return;
+    }
+
+    const dir = dirname(fullPath);
+    await mkdirp(this.fs, dir);
+
+    if (isBytes(content)) {
+      await this.fs.promises.writeFile(fullPath, content);
+    } else {
+      await this.fs.promises.writeFile(fullPath, content, 'utf8');
+    }
+  }
+
   /**
    * Write merge driver result to working copy (v0.5)
    *
@@ -4195,32 +4772,32 @@ class ConflictModel {
    * @param {Record<string, any>} result - Merge result
    */
   async _writeDriverResult(workingCopyDir, filePath, result) {
-    const fullPath = path.join(workingCopyDir, filePath);
+    const fullPath = join(workingCopyDir, filePath);
 
     // Ensure directory exists
-    const dir = path.dirname(fullPath);
-    await this.fs.promises.mkdir(dir, { recursive: true });
+    const dir = dirname(fullPath);
+    await mkdirp(this.fs, dir);
 
     // Write main file
     if (result.content !== null && result.content !== undefined) {
-      if (Buffer.isBuffer(result.content)) {
+      if (isBytes(result.content)) {
         await this.fs.promises.writeFile(fullPath, result.content);
       } else {
-        await this.fs.promises.writeFile(fullPath, result.content, 'utf-8');
+        await this.fs.promises.writeFile(fullPath, result.content, 'utf8');
       }
     }
 
     // Write additional files if driver provided them
     if (result.additionalFiles) {
       for (const [additionalPath, additionalContent] of Object.entries(result.additionalFiles)) {
-        const additionalFullPath = path.join(workingCopyDir, additionalPath);
-        const additionalDir = path.dirname(additionalFullPath);
-        await this.fs.promises.mkdir(additionalDir, { recursive: true });
+        const additionalFullPath = join(workingCopyDir, additionalPath);
+        const additionalDir = dirname(additionalFullPath);
+        await mkdirp(this.fs, additionalDir);
 
-        if (Buffer.isBuffer(additionalContent)) {
+        if (isBytes(additionalContent)) {
           await this.fs.promises.writeFile(additionalFullPath, additionalContent);
         } else {
-          await this.fs.promises.writeFile(additionalFullPath, additionalContent, 'utf-8');
+          await this.fs.promises.writeFile(additionalFullPath, additionalContent, 'utf8');
         }
       }
     }
@@ -4266,11 +4843,11 @@ function matchesPattern(path, pattern) {
 /**
  * Check if a file is likely binary based on content
  *
- * @param {string|Buffer} content - File content
+ * @param {string|Uint8Array} content - File content
  * @returns {boolean} Whether content appears binary
  */
 function isBinaryContent(content) {
-  if (Buffer.isBuffer(content)) return true;
+  if (isBytes(content)) return true;
   if (typeof content !== 'string') return false;
 
   // Check for null bytes (common in binary files)
@@ -4585,9 +5162,9 @@ class MergeDriverRegistry {
   /**
    * Prepare content for driver based on binary/text
    *
-   * @param {string|Buffer|null} content - Raw content
-   * @param {boolean} isBinary - Whether to return as Buffer
-   * @returns {string|Buffer|null} Prepared content
+   * @param {string|Uint8Array|null} content - Raw content
+   * @param {boolean} isBinary - Whether to return as bytes
+   * @returns {string|Uint8Array|null} Prepared content
    */
   prepareContent(content, isBinary) {
     if (content === null || content === undefined) {
@@ -4595,14 +5172,14 @@ class MergeDriverRegistry {
     }
 
     if (isBinary) {
-      // Convert to Buffer if needed
-      if (Buffer.isBuffer(content)) return content;
-      if (typeof content === 'string') return Buffer.from(content, 'utf-8');
-      return Buffer.from(String(content));
+      // Convert to bytes if needed
+      if (isBytes(content)) return content;
+      if (typeof content === 'string') return utf8Encode(content);
+      return utf8Encode(String(content));
     } else {
       // Convert to string if needed
       if (typeof content === 'string') return content;
-      if (Buffer.isBuffer(content)) return content.toString('utf-8');
+      if (isBytes(content)) return utf8Decode(content);
       return String(content);
     }
   }
@@ -4763,25 +5340,25 @@ class WorkspaceManager {
     };
 
     // Create workspace directory
-    await this.fs.promises.mkdir(args.path, { recursive: true });
+    await mkdirp(this.fs, args.path);
 
     // Create workspace-specific working_copy directory in .jj
-    const workspaceCopyDir = path.join(this.repoDir, '.jj', 'working_copy', workspaceId);
-    await this.fs.promises.mkdir(workspaceCopyDir, { recursive: true });
+    const workspaceCopyDir = join(this.repoDir, '.jj', 'working_copy', workspaceId);
+    await mkdirp(this.fs, workspaceCopyDir);
 
     // Create .git file pointing to main repo's .git directory
     // This allows Git tools to work in the workspace
     // IMPORTANT: Must use absolute paths for Git compatibility
-    const gitFilePath = path.join(args.path, '.git');
-    const mainGitDir = path.resolve(this.repoDir, '.git');
+    const gitFilePath = join(args.path, '.git');
+    const mainGitDir = resolve(this.repoDir, '.git');
     const gitFileContent = `gitdir: ${mainGitDir}\n`;
     await this.fs.promises.writeFile(gitFilePath, gitFileContent, 'utf8');
 
     // Create .jj file pointing to main repo's .jj directory
     // This allows JJ tools to work in the workspace
     // IMPORTANT: Must use absolute paths for JJ CLI compatibility
-    const jjFilePath = path.join(args.path, '.jj');
-    const mainJJDir = path.resolve(this.repoDir, '.jj');
+    const jjFilePath = join(args.path, '.jj');
+    const mainJJDir = resolve(this.repoDir, '.jj');
     const jjFileContent = `jjdir: ${mainJJDir}\n`;
     await this.fs.promises.writeFile(jjFilePath, jjFileContent, 'utf8');
 
@@ -5416,6 +5993,575 @@ class UserConfig {
   }
 }
 
+/**
+ * Precompiled protobuf reflection JSON for local_working_copy.proto
+ *
+ * Generated from src/protos/local_working_copy.proto by scripts/build-protos.mjs. This
+ * is bundled directly (instead of loaded from a filesystem path at runtime)
+ * so that protobuf schema loading works identically in Node and in browser
+ * bundles — protobuf.load() requires filesystem/network access that does
+ * not exist in a browser bundle (see issue #28). Regenerate with:
+ *   node scripts/build-protos.mjs
+ */
+
+var localWorkingCopyJson = {
+  nested: {
+    local_working_copy: {
+      nested: {
+        FileType: {
+          valuesOptions: {
+            Conflict: {
+              deprecated: true,
+            },
+          },
+          values: {
+            Normal: 0,
+            Symlink: 1,
+            Executable: 2,
+            Conflict: 3,
+            GitSubmodule: 4,
+          },
+        },
+        MaterializedConflictData: {
+          fields: {
+            conflictMarkerLen: {
+              type: 'uint32',
+              id: 1,
+            },
+          },
+        },
+        FileState: {
+          fields: {
+            mtimeMillisSinceEpoch: {
+              type: 'int64',
+              id: 1,
+            },
+            size: {
+              type: 'uint64',
+              id: 2,
+            },
+            fileType: {
+              type: 'FileType',
+              id: 3,
+            },
+            materializedConflictData: {
+              type: 'MaterializedConflictData',
+              id: 5,
+            },
+          },
+          reserved: [[4, 4]],
+        },
+        FileStateEntry: {
+          fields: {
+            path: {
+              type: 'string',
+              id: 1,
+            },
+            state: {
+              type: 'FileState',
+              id: 2,
+            },
+          },
+        },
+        SparsePatterns: {
+          fields: {
+            prefixes: {
+              rule: 'repeated',
+              type: 'string',
+              id: 1,
+            },
+          },
+        },
+        TreeState: {
+          fields: {
+            legacyTreeId: {
+              type: 'bytes',
+              id: 1,
+              options: {
+                deprecated: true,
+              },
+            },
+            treeIds: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 5,
+            },
+            fileStates: {
+              rule: 'repeated',
+              type: 'FileStateEntry',
+              id: 2,
+            },
+            isFileStatesSorted: {
+              type: 'bool',
+              id: 6,
+            },
+            sparsePatterns: {
+              type: 'SparsePatterns',
+              id: 3,
+            },
+            watchmanClock: {
+              type: 'WatchmanClock',
+              id: 4,
+            },
+          },
+        },
+        WatchmanClock: {
+          oneofs: {
+            watchmanClock: {
+              oneof: ['stringClock', 'unixTimestamp'],
+            },
+          },
+          fields: {
+            stringClock: {
+              type: 'string',
+              id: 1,
+            },
+            unixTimestamp: {
+              type: 'int64',
+              id: 2,
+            },
+          },
+        },
+        Checkout: {
+          fields: {
+            operationId: {
+              type: 'bytes',
+              id: 2,
+            },
+            workspaceName: {
+              type: 'string',
+              id: 3,
+            },
+          },
+          reserved: [[1, 1]],
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Precompiled protobuf reflection JSON for simple_op_store.proto
+ *
+ * Generated from src/protos/simple_op_store.proto by scripts/build-protos.mjs. This
+ * is bundled directly (instead of loaded from a filesystem path at runtime)
+ * so that protobuf schema loading works identically in Node and in browser
+ * bundles — protobuf.load() requires filesystem/network access that does
+ * not exist in a browser bundle (see issue #28). Regenerate with:
+ *   node scripts/build-protos.mjs
+ */
+
+var simpleOpStoreJson = {
+  nested: {
+    simple_op_store: {
+      nested: {
+        RefConflictLegacy: {
+          fields: {
+            removes: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 1,
+              options: {
+                deprecated: true,
+              },
+            },
+            adds: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 2,
+              options: {
+                deprecated: true,
+              },
+            },
+          },
+        },
+        RefConflict: {
+          fields: {
+            removes: {
+              rule: 'repeated',
+              type: 'Term',
+              id: 1,
+            },
+            adds: {
+              rule: 'repeated',
+              type: 'Term',
+              id: 2,
+            },
+          },
+          nested: {
+            Term: {
+              oneofs: {
+                _value: {
+                  oneof: ['value'],
+                },
+              },
+              fields: {
+                value: {
+                  type: 'bytes',
+                  id: 1,
+                  options: {
+                    proto3_optional: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+        RefTarget: {
+          oneofs: {
+            value: {
+              oneof: ['commitId', 'conflictLegacy', 'conflict'],
+            },
+          },
+          fields: {
+            commitId: {
+              type: 'bytes',
+              id: 1,
+              options: {
+                deprecated: true,
+              },
+            },
+            conflictLegacy: {
+              type: 'RefConflictLegacy',
+              id: 2,
+              options: {
+                deprecated: true,
+              },
+            },
+            conflict: {
+              type: 'RefConflict',
+              id: 3,
+            },
+          },
+        },
+        RefTargetTerm: {
+          oneofs: {
+            _value: {
+              oneof: ['value'],
+            },
+          },
+          fields: {
+            value: {
+              type: 'bytes',
+              id: 1,
+              options: {
+                proto3_optional: true,
+              },
+            },
+          },
+        },
+        RemoteRefState: {
+          values: {
+            New: 0,
+            Tracked: 1,
+          },
+        },
+        RemoteBookmark: {
+          oneofs: {
+            _state: {
+              oneof: ['state'],
+            },
+          },
+          fields: {
+            remoteName: {
+              type: 'string',
+              id: 1,
+            },
+            target: {
+              type: 'RefTarget',
+              id: 2,
+            },
+            state: {
+              type: 'RemoteRefState',
+              id: 3,
+              options: {
+                proto3_optional: true,
+              },
+            },
+          },
+        },
+        Bookmark: {
+          fields: {
+            name: {
+              type: 'string',
+              id: 1,
+            },
+            localTarget: {
+              type: 'RefTarget',
+              id: 2,
+            },
+            remoteBookmarks: {
+              rule: 'repeated',
+              type: 'RemoteBookmark',
+              id: 3,
+              options: {
+                deprecated: true,
+              },
+            },
+          },
+        },
+        GitRef: {
+          fields: {
+            name: {
+              type: 'string',
+              id: 1,
+            },
+            commitId: {
+              type: 'bytes',
+              id: 2,
+              options: {
+                deprecated: true,
+              },
+            },
+            target: {
+              type: 'RefTarget',
+              id: 3,
+            },
+          },
+        },
+        RemoteRef: {
+          fields: {
+            name: {
+              type: 'string',
+              id: 1,
+            },
+            targetTerms: {
+              rule: 'repeated',
+              type: 'RefTargetTerm',
+              id: 2,
+            },
+            state: {
+              type: 'RemoteRefState',
+              id: 3,
+            },
+          },
+        },
+        Tag: {
+          fields: {
+            name: {
+              type: 'string',
+              id: 1,
+            },
+            target: {
+              type: 'RefTarget',
+              id: 2,
+            },
+          },
+        },
+        View: {
+          fields: {
+            headIds: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 1,
+            },
+            wcCommitId: {
+              type: 'bytes',
+              id: 2,
+              options: {
+                deprecated: true,
+              },
+            },
+            wcCommitIds: {
+              keyType: 'string',
+              type: 'bytes',
+              id: 8,
+            },
+            bookmarks: {
+              rule: 'repeated',
+              type: 'Bookmark',
+              id: 5,
+            },
+            localTags: {
+              rule: 'repeated',
+              type: 'Tag',
+              id: 6,
+            },
+            remoteViews: {
+              rule: 'repeated',
+              type: 'RemoteView',
+              id: 11,
+            },
+            gitRefs: {
+              rule: 'repeated',
+              type: 'GitRef',
+              id: 3,
+            },
+            gitHeadLegacy: {
+              type: 'bytes',
+              id: 7,
+              options: {
+                deprecated: true,
+              },
+            },
+            gitHead: {
+              type: 'RefTarget',
+              id: 9,
+            },
+            hasGitRefsMigratedToRemoteTags: {
+              type: 'bool',
+              id: 12,
+            },
+          },
+          reserved: [
+            [4, 4],
+            [10, 10],
+          ],
+        },
+        RemoteView: {
+          fields: {
+            name: {
+              type: 'string',
+              id: 1,
+            },
+            bookmarks: {
+              rule: 'repeated',
+              type: 'RemoteRef',
+              id: 2,
+            },
+            tags: {
+              rule: 'repeated',
+              type: 'RemoteRef',
+              id: 3,
+            },
+          },
+        },
+        Operation: {
+          fields: {
+            viewId: {
+              type: 'bytes',
+              id: 1,
+            },
+            parents: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 2,
+            },
+            metadata: {
+              type: 'OperationMetadata',
+              id: 3,
+            },
+            commitPredecessors: {
+              rule: 'repeated',
+              type: 'CommitPredecessors',
+              id: 4,
+            },
+            storesCommitPredecessors: {
+              type: 'bool',
+              id: 5,
+            },
+          },
+        },
+        Timestamp: {
+          fields: {
+            millisSinceEpoch: {
+              type: 'int64',
+              id: 1,
+            },
+            tzOffset: {
+              type: 'int32',
+              id: 2,
+            },
+          },
+        },
+        OperationMetadata: {
+          fields: {
+            startTime: {
+              type: 'Timestamp',
+              id: 1,
+            },
+            endTime: {
+              type: 'Timestamp',
+              id: 2,
+            },
+            description: {
+              type: 'string',
+              id: 3,
+            },
+            hostname: {
+              type: 'string',
+              id: 4,
+            },
+            username: {
+              type: 'string',
+              id: 5,
+            },
+            isSnapshot: {
+              type: 'bool',
+              id: 7,
+            },
+            tags: {
+              keyType: 'string',
+              type: 'string',
+              id: 6,
+            },
+          },
+        },
+        CommitPredecessors: {
+          fields: {
+            commitId: {
+              type: 'bytes',
+              id: 1,
+            },
+            predecessorIds: {
+              rule: 'repeated',
+              type: 'bytes',
+              id: 2,
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Protobuf schema loader
+ *
+ * Builds protobuf.js `Root` instances from precompiled reflection JSON
+ * (see local_working_copy.json.js / simple_op_store.json.js, generated from
+ * the .proto files in this directory) instead of calling `protobuf.load()`
+ * against a filesystem path.
+ *
+ * Why: `protobuf.load()` resolves its argument as a file path (Node `fs`) or
+ * URL (XHR/fetch), which requires either a real filesystem or a network
+ * request. In a bundled browser build there is no filesystem path to read
+ * (see issue #28), and shipping the raw .proto text and fetching it at
+ * runtime would require bundler-specific asset handling. Reflection JSON is
+ * plain data, so it can be imported like any other JS module and works
+ * identically under Node, Jest, and any browser bundler (Vite, esbuild,
+ * webpack, Rollup, ...).
+ *
+ * Regenerate the JSON files after editing a .proto with:
+ *   npm run build:protos
+ */
+
+
+/** @type {protobuf.Root|undefined} */
+let localWorkingCopyRoot;
+/** @type {protobuf.Root|undefined} */
+let simpleOpStoreRoot;
+
+/**
+ * @returns {protobuf.Root} Root for local_working_copy.proto (Checkout, TreeState, ...)
+ */
+function getLocalWorkingCopyRoot() {
+  if (!localWorkingCopyRoot) {
+    localWorkingCopyRoot = protobuf.Root.fromJSON(localWorkingCopyJson);
+  }
+  return localWorkingCopyRoot;
+}
+
+/**
+ * @returns {protobuf.Root} Root for simple_op_store.proto (Operation, View, ...)
+ */
+function getSimpleOpStoreRoot() {
+  if (!simpleOpStoreRoot) {
+    simpleOpStoreRoot = protobuf.Root.fromJSON(simpleOpStoreJson);
+  }
+  return simpleOpStoreRoot;
+}
+
 /**
  * JJ Checkout File Manager
  *
@@ -5424,15 +6570,6 @@ class UserConfig {
  */
 
 
-const __filename$4 = fileURLToPath(import.meta.url);
-const __dirname$4 = path.dirname(__filename$4);
-
-// Determine proto path based on whether we're running from dist or src
-const inDist$3 = __dirname$4.includes('/dist') || __dirname$4.includes('\\dist');
-const protoDir$3 = inDist$3
-  ? path.join(__dirname$4, '..', 'src', 'protos')
-  : path.join(__dirname$4, '..', 'protos');
-
 class JJCheckout {
   /**
    * @param {any} fs - File system module (isomorphic-git compatible)
@@ -5441,7 +6578,6 @@ class JJCheckout {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$3, 'local_working_copy.proto');
   }
 
   /**
@@ -5452,11 +6588,11 @@ class JJCheckout {
    */
   async writeCheckout(operationId, workspaceName = 'default') {
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getLocalWorkingCopyRoot();
     const Checkout = root.lookupType('local_working_copy.Checkout');
 
     // Convert hex operation ID to bytes
-    const opIdBuffer = Buffer.from(operationId, 'hex');
+    const opIdBuffer = hexToBytes(operationId);
 
     // Create message (use camelCase for protobufjs)
     const message = Checkout.create({
@@ -5488,7 +6624,7 @@ class JJCheckout {
     const buffer = await this.fs.promises.readFile(checkoutPath);
 
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getLocalWorkingCopyRoot();
     const Checkout = root.lookupType('local_working_copy.Checkout');
 
     // Decode
@@ -5516,6 +6652,7 @@ class JJCheckout {
  * calling `writeFile()` directly on the canonical path — see issue #16.
  */
 
+
 /**
  * @param {any} fs - Filesystem implementation (Node fs, LightningFS, etc.)
  * @param {string} targetPath - Canonical path to write to
@@ -5531,7 +6668,7 @@ async function atomicWriteFile(fs, targetPath, content) {
   try {
     const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
     if (dirPath) {
-      await fs.promises.mkdir(dirPath, { recursive: true });
+      await mkdirp(fs, dirPath);
     }
 
     await fs.promises.writeFile(tmpPath, content);
@@ -5555,15 +6692,6 @@ async function atomicWriteFile(fs, targetPath, content) {
  */
 
 
-const __filename$3 = fileURLToPath(import.meta.url);
-const __dirname$3 = path.dirname(__filename$3);
-
-// Determine proto path based on whether we're running from dist or src
-const inDist$2 = __dirname$3.includes('/dist') || __dirname$3.includes('\\dist');
-const protoDir$2 = inDist$2
-  ? path.join(__dirname$3, '..', 'src', 'protos')
-  : path.join(__dirname$3, '..', 'protos');
-
 class JJTreeState {
   /**
    * @param {any} fs - File system module (isomorphic-git compatible)
@@ -5572,7 +6700,6 @@ class JJTreeState {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$2, 'local_working_copy.proto');
   }
 
   /**
@@ -5583,11 +6710,11 @@ class JJTreeState {
    */
   async writeTreeState(treeId, fileStates = []) {
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getLocalWorkingCopyRoot();
     const TreeState = root.lookupType('local_working_copy.TreeState');
 
     // Convert hex tree ID to bytes
-    const treeIdBuffer = Buffer.from(treeId, 'hex');
+    const treeIdBuffer = hexToBytes(treeId);
 
     // Convert file states to protobuf format
     const fileStateEntries = fileStates.map((fs) => ({
@@ -5633,7 +6760,7 @@ class JJTreeState {
     const buffer = await this.fs.promises.readFile(treeStatePath);
 
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getLocalWorkingCopyRoot();
     const TreeState = root.lookupType('local_working_copy.TreeState');
 
     // Decode
@@ -5657,15 +6784,6 @@ class JJTreeState {
  */
 
 
-const __filename$2 = fileURLToPath(import.meta.url);
-const __dirname$2 = path.dirname(__filename$2);
-
-// Determine proto path based on whether we're running from dist or src
-const inDist$1 = __dirname$2.includes('/dist') || __dirname$2.includes('\\dist');
-const protoDir$1 = inDist$1
-  ? path.join(__dirname$2, '..', 'src', 'protos')
-  : path.join(__dirname$2, '..', 'protos');
-
 class JJOperationStore {
   /**
    * @param {any} fs - File system module (isomorphic-git compatible)
@@ -5674,7 +6792,6 @@ class JJOperationStore {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$1, 'simple_op_store.proto');
   }
 
   /**
@@ -5687,12 +6804,12 @@ class JJOperationStore {
    */
   async writeOperation(operationId, viewId, parentIds, metadata) {
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getSimpleOpStoreRoot();
     const Operation = root.lookupType('simple_op_store.Operation');
 
     // Convert hex IDs to bytes
-    const viewIdBuffer = Buffer.from(viewId, 'hex');
-    const parentBuffers = parentIds.map((id) => Buffer.from(id, 'hex'));
+    const viewIdBuffer = hexToBytes(viewId);
+    const parentBuffers = parentIds.map((id) => hexToBytes(id));
 
     // Create metadata message (use camelCase for protobufjs)
     const metadataMsg = {
@@ -5748,7 +6865,7 @@ class JJOperationStore {
     const buffer = await this.fs.promises.readFile(opPath);
 
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getSimpleOpStoreRoot();
     const Operation = root.lookupType('simple_op_store.Operation');
 
     // Decode
@@ -5787,15 +6904,6 @@ class JJOperationStore {
  */
 
 
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-
-// Determine proto path based on whether we're running from dist or src
-const inDist = __dirname$1.includes('/dist') || __dirname$1.includes('\\dist');
-const protoDir = inDist
-  ? path.join(__dirname$1, '..', 'src', 'protos')
-  : path.join(__dirname$1, '..', 'protos');
-
 class JJViewStore {
   /**
    * @param {any} fs - File system module (isomorphic-git compatible)
@@ -5804,7 +6912,6 @@ class JJViewStore {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir, 'simple_op_store.proto');
   }
 
   /**
@@ -5816,17 +6923,17 @@ class JJViewStore {
    */
   async writeView(viewId, headIds, wcCommitIds = {}) {
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getSimpleOpStoreRoot();
     const View = root.lookupType('simple_op_store.View');
 
     // Convert hex IDs to bytes
-    const headBuffers = headIds.map((id) => Buffer.from(id, 'hex'));
+    const headBuffers = headIds.map((id) => hexToBytes(id));
 
     // Convert wcCommitIds object to map
     /** @type {Record<string, any>} */
     const wcCommitIdsMap = {};
     for (const [workspace, commitId] of Object.entries(wcCommitIds)) {
-      wcCommitIdsMap[workspace] = Buffer.from(commitId, 'hex');
+      wcCommitIdsMap[workspace] = hexToBytes(commitId);
     }
 
     // Create view message (use camelCase for protobufjs)
@@ -5867,7 +6974,7 @@ class JJViewStore {
     const buffer = await this.fs.promises.readFile(viewPath);
 
     // Load protobuf schema
-    const root = await protobuf.load(this.protoPath);
+    const root = getSimpleOpStoreRoot();
     const View = root.lookupType('simple_op_store.View');
 
     // Decode
@@ -6563,14 +7670,14 @@ class IsomorphicGitBackend {
     const jjRepo = `${jjDir}/repo`;
 
     // Create directory structure
-    await this.fs.promises.mkdir(`${jjRepo}/store`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/store/extra/heads`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/op_store/operations`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/op_store/views`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/op_heads/heads`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/index`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjRepo}/submodule_store`, { recursive: true });
-    await this.fs.promises.mkdir(`${jjDir}/working_copy`, { recursive: true });
+    await mkdirp(this.fs, `${jjRepo}/store`);
+    await mkdirp(this.fs, `${jjRepo}/store/extra/heads`);
+    await mkdirp(this.fs, `${jjRepo}/op_store/operations`);
+    await mkdirp(this.fs, `${jjRepo}/op_store/views`);
+    await mkdirp(this.fs, `${jjRepo}/op_heads/heads`);
+    await mkdirp(this.fs, `${jjRepo}/index`);
+    await mkdirp(this.fs, `${jjRepo}/submodule_store`);
+    await mkdirp(this.fs, `${jjDir}/working_copy`);
 
     // Write type files
     await this.fs.promises.writeFile(`${jjRepo}/store/type`, 'git');
@@ -6597,8 +7704,8 @@ class IsomorphicGitBackend {
    */
   async _createInitialJJState() {
     // Generate unique IDs for initial state
-    const operationId = crypto$1.randomBytes(64).toString('hex'); // 512-bit = 128 hex chars
-    const viewId = crypto$1.randomBytes(64).toString('hex');
+    const operationId = randomHex(64); // 512-bit = 128 hex chars
+    const viewId = randomHex(64);
     const emptyTreeId = '4b825dc642cb6eb9a060e54bf8d69288fbee4904'; // Git's empty tree hash
 
     // Get the initial commit from Git
@@ -6610,7 +7717,7 @@ class IsomorphicGitBackend {
         ref: 'HEAD',
       });
       if (headOid) {
-        initialCommitId = crypto$1.randomBytes(64).toString('hex');
+        initialCommitId = randomHex(64);
       }
     } catch (error) {
       // No initial commit yet
@@ -6738,60 +7845,320 @@ async function createJJ(options) {
   const workspaces = new WorkspaceManager(storage, fs, dir);
   const userConfig = new UserConfig(storage);
 
-  /**
-   * Helper to get user info for oplog operations
-   * @returns {Promise<import('../types').OperationUser>}
-   */
-  const getUserOplogInfo = async () => {
-    await userConfig.load();
-    const user = /** @type {any} */ (userConfig.getUser());
-    return { name: user.name, email: user.email, hostname: 'localhost' };
+  /**
+   * Helper to get user info for oplog operations
+   * @returns {Promise<import('../types').OperationUser>}
+   */
+  const getUserOplogInfo = async () => {
+    await userConfig.load();
+    const user = /** @type {any} */ (userConfig.getUser());
+    return { name: user.name, email: user.email, hostname: 'localhost' };
+  };
+
+  /**
+   * Helper to snapshot current filesystem state
+   * This is called BEFORE every operation to enable undo
+   * @returns {Promise<Record<string, string>>}
+   */
+  const snapshotFilesystem = async () => {
+    /** @type {Record<string, string>} */
+    const fileSnapshot = {};
+
+    try {
+      const trackedFiles = await workingCopy.listFiles();
+
+      // Safeguards to prevent excessive memory usage
+      const MAX_FILE_SIZE = 1 * 1024 * 1024; // 1MB per file
+      const MAX_TOTAL_SIZE = 10 * 1024 * 1024; // 10MB total snapshot size
+      let totalSnapshotSize = 0;
+
+      for (const filePath of trackedFiles) {
+        try {
+          const fullPath = join(dir, filePath);
+          const stats = await fs.promises.stat(fullPath);
+
+          // Skip files that are too large
+          if (stats.size > MAX_FILE_SIZE) {
+            continue;
+          }
+
+          // Stop if total snapshot size would exceed limit
+          if (totalSnapshotSize + stats.size > MAX_TOTAL_SIZE) {
+            break;
+          }
+
+          const content = await fs.promises.readFile(fullPath, 'utf8');
+          fileSnapshot[filePath] = content;
+          totalSnapshotSize += stats.size;
+        } catch (error) {
+          // Skip files that can't be read (binary, deleted, etc.)
+        }
+      }
+    } catch (error) {
+      // If we can't list files, return empty snapshot
+    }
+
+    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 = 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 = join(dir, filePath);
+      const pathParts = filePath.split('/');
+      if (pathParts.length > 1) {
+        const fullDirPath = 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 };
   };
 
   /**
-   * Helper to snapshot current filesystem state
-   * This is called BEFORE every operation to enable undo
-   * @returns {Promise<Record<string, string>>}
+   * 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 snapshotFilesystem = async () => {
-    /** @type {Record<string, string>} */
-    const fileSnapshot = {};
-
-    try {
-      const trackedFiles = await workingCopy.listFiles();
+  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);
+      }
+    }
 
-      // Safeguards to prevent excessive memory usage
-      const MAX_FILE_SIZE = 1 * 1024 * 1024; // 1MB per file
-      const MAX_TOTAL_SIZE = 10 * 1024 * 1024; // 10MB total snapshot size
-      let totalSnapshotSize = 0;
+    if (reversal.fileSnapshot !== undefined) {
+      await syncWorkingCopyFiles(reversal.fileSnapshot);
+    }
 
-      for (const filePath of trackedFiles) {
-        try {
-          const fullPath = path.join(dir, filePath);
-          const stats = await fs.promises.stat(fullPath);
+    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.)
+  };
 
-          // Skip files that are too large
-          if (stats.size > MAX_FILE_SIZE) {
-            continue;
-          }
+  /**
+   * 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);
+    }
+  };
 
-          // Stop if total snapshot size would exceed limit
-          if (totalSnapshotSize + stats.size > MAX_TOTAL_SIZE) {
-            break;
-          }
+  /**
+   * 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;
+    }
 
-          const content = await fs.promises.readFile(fullPath, 'utf-8');
-          fileSnapshot[filePath] = content;
-          totalSnapshotSize += stats.size;
-        } catch (error) {
-          // Skip files that can't be read (binary, deleted, etc.)
-        }
-      }
-    } catch (error) {
-      // If we can't list files, return empty snapshot
+    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 fileSnapshot;
+    return head;
   };
 
   /**
@@ -6978,6 +8345,25 @@ 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(),
     };
@@ -7135,6 +8521,20 @@ 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
      */
@@ -7158,7 +8558,7 @@ 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
@@ -7213,10 +8613,10 @@ async function createJJ(options) {
           });
         }
 
-        const fullPath = path.join(dir, args.path);
+        const fullPath = 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);
           }
@@ -7381,7 +8781,7 @@ async function createJJ(options) {
 
       // Reading from working copy
       if (!args.changeId) {
-        const fullPath = path.join(dir, args.path);
+        const fullPath = join(dir, args.path);
         try {
           const stream = fs.createReadStream(
             fullPath,
@@ -7431,14 +8831,14 @@ async function createJJ(options) {
         });
       }
 
-      const fullPath = path.join(dir, args.path);
+      const fullPath = join(dir, args.path);
 
       // Ensure directory exists
       const pathParts = args.path.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 });
+        const fullDirPath = join(dir, dirPath);
+        await mkdirp(fs, fullDirPath);
       }
 
       // Create writable stream
@@ -7551,7 +8951,7 @@ 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',
@@ -7669,6 +9069,51 @@ 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);
@@ -7679,6 +9124,8 @@ 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: {},
@@ -7687,7 +9134,7 @@ async function createJJ(options) {
         },
       });
 
-      return change;
+      return { ...change, conflicts: detectedConflicts };
     },
 
     /**
@@ -7859,7 +9306,7 @@ async function createJJ(options) {
 
         for (const filePath of trackedFiles) {
           try {
-            const fullPath = path.join(dir, filePath);
+            const fullPath = join(dir, filePath);
             const stats = await fs.promises.stat(fullPath);
 
             // Skip files that are too large (silently - this is an optimization)
@@ -7872,7 +9319,7 @@ 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) {
@@ -8070,6 +9517,8 @@ 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();
 
@@ -8078,6 +9527,10 @@ 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);
         }
@@ -8105,6 +9558,7 @@ 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]);
@@ -8148,10 +9602,19 @@ 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
@@ -8164,6 +9627,13 @@ 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: {},
@@ -8544,6 +10014,13 @@ 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) {
@@ -8557,7 +10034,7 @@ async function createJJ(options) {
           for (const filePath of workingDirFiles) {
             if (!previousSnapshot[filePath]) {
               try {
-                const fullPath = path.join(dir, filePath);
+                const fullPath = join(dir, filePath);
                 await fs.promises.unlink(fullPath);
                 await workingCopy.untrackFile(filePath);
               } catch (error) {
@@ -8565,13 +10042,14 @@ 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);
+          }
         }
       }
 
@@ -8584,38 +10062,17 @@ 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
@@ -8631,11 +10088,13 @@ 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,
         },
       });
 
@@ -8666,106 +10125,118 @@ 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,
         },
       };
     },
@@ -8773,9 +10244,9 @@ 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
      */
@@ -8806,42 +10277,52 @@ 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();
       }
@@ -8852,19 +10333,23 @@ 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,
         },
       };
     },
@@ -9091,6 +10576,12 @@ 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
        */
@@ -9130,12 +10621,35 @@ 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,
         });
 
@@ -9421,10 +10935,53 @@ 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);
@@ -9452,10 +11009,22 @@ 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;
       }
@@ -9466,6 +11035,7 @@ async function createJJ(options) {
         user: await getUserOplogInfo(),
         description: `squash ${source.slice(0, 8)} into ${destChangeId.slice(0, 8)}`,
         parents: [],
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -9536,6 +11106,12 @@ 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',
@@ -9544,15 +11120,29 @@ 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: {},
@@ -9574,9 +11164,220 @@ 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
      *
@@ -11038,7 +12839,7 @@ async function createJJ(options) {
             .split('/')
             .pop()
             .replace(/\.git$/, '');
-        const fullCloneDir = path.join(dir, cloneDir);
+        const fullCloneDir = join(dir, cloneDir);
 
         // Clone using isomorphic-git
         await git.clone({
@@ -11416,8 +13217,14 @@ 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` : join(dir, '.git');
 
         try {
           await fs.promises.access(gitDir);
@@ -11496,7 +13303,7 @@ 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(join(dir, file), 'utf8');
           leftFiles.set(file, content);
         } catch (error) {
           // File might be deleted or binary - throw error for explicit handling
@@ -11639,7 +13446,7 @@ 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(join(dir, conflict.path), resolvedContent, 'utf8');
 
         // Mark conflict as resolved
         await conflicts.resolveConflict(args.conflictId, 'manual');
@@ -11682,7 +13489,7 @@ 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(join(dir, conflict.path), resolvedContent, 'utf8');
 
             // Mark as resolved
             await conflicts.resolveConflict(conflict.conflictId, args.strategy);
@@ -12004,7 +13811,7 @@ async function createJJ(options) {
           );
         }
 
-        const fullPath = path.join(dir, args.path);
+        const fullPath = join(dir, args.path);
 
         // Convert string mode to number if needed
         const mode = typeof args.mode === 'string' ? parseInt(args.mode, 8) : args.mode;
@@ -12115,14 +13922,14 @@ async function createJJ(options) {
           if (change.fileSnapshot) {
             for (const [filePath, content] of Object.entries(change.fileSnapshot)) {
               try {
-                const fullPath = path.join(args.path, filePath);
+                const fullPath = join(args.path, filePath);
 
                 // Ensure directory exists
                 const pathParts = filePath.split('/');
                 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 });
+                  const fullDirPath = join(args.path, dirPath);
+                  await mkdirp(fs, fullDirPath);
                 }
 
                 // Write file content