isomorphic-jj 1.7.0 → 1.9.0

package/dist/index.cjs

@@ -1,12 +1,8 @@
 'use strict';
 
-var path = require('path');
 var git = require('isomorphic-git');
-var protobuf = require('protobufjs');
-var url = require('url');
-var crypto$1 = require('crypto');
+var protobuf = require('protobufjs/light.js');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /**
  * JJError - Custom error class for isomorphic-jj
  *
@@ -29,6 +25,112 @@ class JJError extends Error {
   }
 }
 
+/**
+ * Small in-process locking utilities.
+ *
+ * These provide same-process concurrency safety only — they do not protect
+ * against races between separate OS processes sharing the same on-disk
+ * repository. Cross-process locking is a separate concern (e.g. a lockfile
+ * with retry/backoff) and is intentionally out of scope here.
+ */
+
+/**
+ * A simple FIFO async mutex: `run(fn)` queues `fn` to execute only once all
+ * previously-queued work on this mutex has settled, serializing access to
+ * whatever critical section `fn` represents.
+ */
+class Mutex {
+  constructor() {
+    /** @type {Promise<any>} */
+    this._queue = Promise.resolve();
+  }
+
+  /**
+   * @template T
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  run(fn) {
+    const result = this._queue.then(() => fn());
+    // Keep the queue moving even if `fn` rejects — a failed critical section
+    // must not permanently wedge the lock for subsequent callers.
+    this._queue = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+/**
+ * A registry of mutexes keyed by an arbitrary string (typically a file path),
+ * so unrelated paths don't contend with each other while operations on the
+ * *same* path are fully serialized.
+ */
+class KeyedMutex {
+  constructor() {
+    /** @type {Map<string, Mutex>} */
+    this._mutexes = new Map();
+  }
+
+  /**
+   * @template T
+   * @param {string} key
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  run(key, fn) {
+    let mutex = this._mutexes.get(key);
+    if (!mutex) {
+      mutex = new Mutex();
+      this._mutexes.set(key, mutex);
+    }
+    return mutex.run(fn);
+  }
+}
+
+/**
+ * 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
  *
@@ -48,6 +150,13 @@ class Storage {
     this.repoDir = `${dir}/.jj/repo`; // Core repo data
     this.workingCopyDir = `${dir}/.jj/working_copy`; // Default workspace working copy
     this.cache = new Map();
+
+    // Serializes write()/appendLine() critical sections per path so that
+    // concurrent same-process callers (e.g. a user command racing
+    // BackgroundOps's autosnapshot) can't interleave a read-modify-write
+    // cycle and silently lose an update. This only protects callers that
+    // share this Storage instance — cross-process locking is out of scope.
+    this._locks = new KeyedMutex();
   }
 
   /**
@@ -62,17 +171,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',
@@ -122,14 +231,34 @@ class Storage {
    * @param {Object|string} data - Data to write (object will be stringified)
    */
   async write(path, data) {
+    return this._locks.run(path, () => this._writeLocked(path, data));
+  }
+
+  /**
+   * Unlocked implementation of write(). Only call this from within a
+   * `this._locks.run(path, ...)` critical section (directly from write()
+   * itself, or from appendLine() which holds the same path's lock already).
+   *
+   * @param {string} path - Relative path from .jj directory
+   * @param {Object|string} data - Data to write (object will be stringified)
+   */
+  async _writeLocked(path, data) {
     const fullPath = `${this.jjDir}/${path}`;
-    const tmpPath = `${fullPath}.tmp.${Date.now()}`;
+    // Random suffix (not just a millisecond timestamp) so two concurrent
+    // writes to the same path never collide on the temp filename — a
+    // collision would let one write's error-cleanup unlink() delete the
+    // other's still in-flight temp file.
+    const tmpSuffix =
+      typeof crypto !== 'undefined' && crypto.randomUUID
+        ? crypto.randomUUID()
+        : `${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+    const tmpPath = `${fullPath}.tmp.${Date.now()}.${tmpSuffix}`;
     const jsonData = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
 
     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');
@@ -193,16 +322,25 @@ class Storage {
     const fullPath = `${this.jjDir}/${path}`;
 
     try {
-      // Read existing content
-      let existing = '';
-      try {
-        existing = await this.fs.promises.readFile(fullPath, 'utf8');
-      } catch (error) {
-        if (error.code !== 'ENOENT') throw error;
-      }
+      // Hold the same per-path lock write() uses for the *entire*
+      // read-modify-write cycle (not just the write half). Without this,
+      // two concurrent appendLine() calls on the same path can both read
+      // the pre-append content, and the loser's write silently drops its
+      // line even though both calls report success.
+      await this._locks.run(path, async () => {
+        // Read existing content
+        let existing = '';
+        try {
+          existing = await this.fs.promises.readFile(fullPath, 'utf8');
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
 
-      // Write atomically
-      await this.write(path, existing + line + '\n');
+        // Write atomically (already inside this path's lock, so use the
+        // unlocked implementation to avoid deadlocking on a non-reentrant
+        // per-key mutex).
+        await this._writeLocked(path, existing + line + '\n');
+      });
     } catch (error) {
       throw new JJError('STORAGE_WRITE_FAILED', `Failed to append to ${path}: ${error.message}`, {
         path: fullPath,
@@ -376,6 +514,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
  *
@@ -471,6 +678,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
    *
@@ -582,6 +851,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)
    *
@@ -619,10 +947,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>} */
@@ -1086,61 +1413,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
  *
@@ -1713,18 +1985,36 @@ class TagStore {
     this.fs = fs;
     this.jjDir = jjDir;
     this.tagsFile = `${jjDir}/store/tags.json`;
+    /**
+     * Tracking info for local tags mirrored from a remote (jj v0.44 `jj tag
+     * track`/`untrack`). Keyed by local tag name: { remote, remoteName }.
+     * @type {Record<string, any>}
+     */
+    this.tracking = {};
   }
 
   /**
-   * Loads tags from storage
+   * Loads tags (and their remote-tracking info, jj v0.44) from storage
    * @returns {Promise<Record<string, any>>} Map of tag name to changeId
    */
   async load() {
     try {
       const data = await this.fs.promises.readFile(this.tagsFile, 'utf8');
-      return JSON.parse(data);
+      const parsed = JSON.parse(data);
+
+      // v0.44: tags.json may be either the legacy flat `{ name: changeId }`
+      // map, or the newer `{ tags: {...}, tracked: {...} }` shape that also
+      // carries remote-tracking state. Support both for backward compat.
+      if (parsed && typeof parsed === 'object' && 'tags' in parsed) {
+        this.tracking = parsed.tracked || {};
+        return parsed.tags || {};
+      }
+
+      this.tracking = {};
+      return parsed || {};
     } catch (error) {
       if (error.code === 'ENOENT') {
+        this.tracking = {};
         return {};
       }
       throw error;
@@ -1732,19 +2022,18 @@ class TagStore {
   }
 
   /**
-   * Saves tags to storage
+   * Saves tags (and their remote-tracking info, jj v0.44) to storage
    * @param {Object} tags - Map of tag name to changeId
    * @returns {Promise<void>}
    */
   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 this.fs.promises.writeFile(this.tagsFile, JSON.stringify(tags, null, 2));
+    await mkdirp(this.fs, storeDir);
+    await this.fs.promises.writeFile(
+      this.tagsFile,
+      JSON.stringify({ tags, tracked: this.tracking || {} }, null, 2)
+    );
   }
 
   /**
@@ -1773,9 +2062,11 @@ class TagStore {
   }
 
   /**
-   * Lists all tags, optionally filtered by pattern
+   * Lists all tags, optionally filtered by pattern. Each entry also carries
+   * a `tracking: { remote, ref }` field when the tag is tracking a remote
+   * (jj v0.44 `jj tag track`).
    * @param {string} [pattern] - Optional glob pattern
-   * @returns {Promise<Array<{name: string, changeId: string}>>}
+   * @returns {Promise<Array<Record<string, any>>>}
    */
   async list(pattern) {
     const tags = await this.load();
@@ -1786,10 +2077,17 @@ class TagStore {
       tagNames = tagNames.filter((name) => matchesPattern$1(name, pattern));
     }
 
-    return tagNames.map((name) => ({
-      name,
-      changeId: tags[name],
-    }));
+    return tagNames.map((name) => {
+      /** @type {Record<string, any>} */
+      const tag = { name, changeId: tags[name] };
+      if (this.tracking && this.tracking[name]) {
+        tag.tracking = {
+          remote: this.tracking[name].remote,
+          ref: this.tracking[name].remoteName || name,
+        };
+      }
+      return tag;
+    });
   }
 
   /**
@@ -2143,11 +2441,30 @@ class RevsetParser {
       this.next();
       const value = /** @type {string} */ (tok.value);
 
-      // A bare "base..tip" range, e.g. `abcd1234..ef567890`.
+      // `::` (bare, no operands) means "all visible changes", matching jj's
+      // `::` alias for all().
+      if (value === '::') {
+        return { type: 'rangeAll' };
+      }
+
+      // A bare "base..tip" range, e.g. `abcd1234..ef567890` — and the
+      // open-ended forms `..tip` (ancestors(tip)) and `base..` (everything
+      // not an ancestor of base, approximated here as descendants(base)).
       if (value.includes('..')) {
         const parts = value.split('..');
         if (parts.length === 2) {
-          return { type: 'range', base: parts[0].trim(), tip: parts[1].trim() };
+          const base = parts[0].trim();
+          const tip = parts[1].trim();
+          if (base === '' && tip === '') {
+            return { type: 'rangeAll' };
+          }
+          if (base === '') {
+            return { type: 'rangeAncestors', tip };
+          }
+          if (tip === '') {
+            return { type: 'rangeDescendants', base };
+          }
+          return { type: 'range', base, tip };
         }
       }
 
@@ -2216,7 +2533,7 @@ class RevsetEngine {
    * @returns {string}
    */
   _suggestion() {
-    return 'Use @, @-, @+, bookmark(name), all(), none(), root(), visible_heads(), git_refs(), git_head(), ancestors(revset[, depth]), author(name), author_name(x), author_email(x), committer(x), committer_name(x), committer_email(x), subject(pattern), description(text), change_id(prefix), commit_id(prefix), empty(), mine(), merge(), merges(), forks(), signed(), divergent(), file(pattern), roots(revset), heads(revset), parents(revset), children(revset), first_parent(revset), first_ancestors(revset), fork_point(revset), merge_point(revset), exactly(revset, n), present(revset), coalesce(a, b, ...), latest(revset, [count]), tags([pattern]), remote_tags([pattern]), bookmarks([pattern]), last(N[dh]), since(date), between(start, end), descendants(rev[, depth]), common_ancestor(rev1, rev2), range(base..tip), diverge_point(rev1, rev2), connected(rev1, rev2), operators (x-, x+), set operations (& | ~), or a direct change ID';
+    return 'Use @, @-, @+, bookmark(name), all(), builtin_log(), none(), root(), visible_heads(), ancestors(revset[, depth]), author(name), author_name(x), author_email(x), committer(x), committer_name(x), committer_email(x), subject(pattern), description(text), change_id(prefix), commit_id(prefix), empty(), mine(), merge(), merges(), forks(), signed(), divergent(), file(pattern), roots(revset), heads(revset), parents(revset), children(revset), first_parent(revset), first_ancestors(revset), fork_point(revset), merge_point(revset), exactly(revset, n), present(revset), coalesce(a, b, ...), latest(revset, [count]), tags([pattern]), remote_tags([pattern]), bookmarks([pattern]), last(N[dh]), since(date), between(start, end), descendants(rev[, depth]), common_ancestor(rev1, rev2), range(base..tip), diverge_point(rev1, rev2), connected(rev1, rev2), operators (x-, x+), set operations (& | ~), or a direct change ID (git_refs()/git_head() still work but are deprecated — jj removed them in v0.43; use bookmarks()/tags()/@ instead)';
   }
 
   /**
@@ -2273,6 +2590,15 @@ class RevsetEngine {
       }
       case 'range':
         return await this.evalRange(node.base, node.tip);
+      // Open-ended ranges (issue #18): `..tip` / `base..` / `::` delegate to
+      // the equivalent ancestors()/descendants()/all() functions rather than
+      // failing with a misleading "invalid IDs" error.
+      case 'rangeAll':
+        return await this.evaluateFunctionCall('all', '');
+      case 'rangeAncestors':
+        return await this.evaluateFunctionCall('ancestors', node.tip);
+      case 'rangeDescendants':
+        return await this.evaluateFunctionCall('descendants', node.base);
       case 'call':
         return await this.evaluateFunctionCall(node.name, node.argsRaw);
       default:
@@ -2346,6 +2672,16 @@ class RevsetEngine {
         await this.graph.load();
         return this.graph.getAll().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
+      // defaults to `all()` when no revset is given (see `jj.log()`), so
+      // `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':
+        await this.graph.load();
+        return this.graph.getAll().map((c) => c.changeId);
+
       case 'none':
         return [];
 
@@ -2376,6 +2712,13 @@ class RevsetEngine {
         return allChanges.filter((c) => !hasChildren.has(c.changeId)).map((c) => c.changeId);
       }
 
+      // `git_refs()` and `git_head()` are deprecated compatibility shims.
+      // Upstream jj deprecated both in favor of `bookmarks()`/`tags()` and
+      // `@`, then removed them outright in jj v0.43 (revset/template calls
+      // to either now error in real jj). isomorphic-jj keeps them working
+      // rather than hard-breaking existing callers, but they are no longer
+      // advertised in `_suggestion()` — prefer `bookmarks([pattern])` /
+      // `tags([pattern])` / `@` instead.
       case 'git_refs': {
         if (!this.bookmarkStore) return [];
         await this.bookmarkStore.load();
@@ -2452,15 +2795,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':
@@ -3514,23 +3869,201 @@ 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.
  */
 
-
 /**
- * Conflict types supported by JJ
+ * @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.
  */
-const ConflictType = {
-  CONTENT: 'content', // File content conflicts (3-way merge)
+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;
+}
+
+/**
+ * @param {...string} parts
+ * @returns {string} All `parts` joined with `/` and normalized.
+ */
+function join(...parts) {
+  if (parts.length === 0) return '.';
+  const joined = parts.filter((p) => p !== '').join('/');
+  return joined === '' ? '.' : normalize(joined);
+}
+
+/**
+ * @param {string} path
+ * @returns {string} The directory portion of `path` (Node `path.dirname` semantics).
+ */
+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
@@ -3685,6 +4218,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);
+        }
       }
     }
 
@@ -3772,6 +4314,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
    *
@@ -4015,6 +4581,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)
    *
@@ -4023,32 +4619,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');
         }
       }
     }
@@ -4094,11 +4690,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)
@@ -4413,9 +5009,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) {
@@ -4423,14 +5019,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);
     }
   }
@@ -4591,25 +5187,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');
 
@@ -5244,6 +5840,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
  *
@@ -5252,15 +6417,6 @@ class UserConfig {
  */
 
 
-const __filename$4 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
-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)
@@ -5269,7 +6425,6 @@ class JJCheckout {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$3, 'local_working_copy.proto');
   }
 
   /**
@@ -5280,11 +6435,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({
@@ -5316,7 +6471,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
@@ -5330,6 +6485,52 @@ class JJCheckout {
   }
 }
 
+/**
+ * Shared atomic-write helper for filesystem writes.
+ *
+ * Writes content to a uniquely-named temp file, then renames it over the
+ * canonical path. A crash/error between those two steps leaves the
+ * canonical file untouched (never a truncated/partial write) — the temp
+ * file is best-effort cleaned up on failure.
+ *
+ * This mirrors the pattern `Storage.write()` (src/core/storage-manager.js)
+ * already uses for JSON stores, factored out so the protobuf-backed stores
+ * (JJOperationStore, JJViewStore, JJTreeState) can use it too instead of
+ * 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
+ * @param {string|Uint8Array} content - Content to write
+ */
+async function atomicWriteFile(fs, targetPath, content) {
+  const tmpSuffix =
+    typeof crypto !== 'undefined' && crypto.randomUUID
+      ? crypto.randomUUID()
+      : `${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+  const tmpPath = `${targetPath}.tmp.${Date.now()}.${tmpSuffix}`;
+
+  try {
+    const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+    if (dirPath) {
+      await mkdirp(fs, dirPath);
+    }
+
+    await fs.promises.writeFile(tmpPath, content);
+    await fs.promises.rename(tmpPath, targetPath);
+  } catch (error) {
+    try {
+      await fs.promises.unlink(tmpPath);
+    } catch {
+      // Best-effort cleanup; ignore if the temp file was never created (or
+      // is already gone).
+    }
+    throw error;
+  }
+}
+
 /**
  * JJ TreeState File Manager
  *
@@ -5338,15 +6539,6 @@ class JJCheckout {
  */
 
 
-const __filename$3 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
-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)
@@ -5355,7 +6547,6 @@ class JJTreeState {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$2, 'local_working_copy.proto');
   }
 
   /**
@@ -5366,11 +6557,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) => ({
@@ -5401,9 +6592,9 @@ class JJTreeState {
     // Encode to binary
     const buffer = TreeState.encode(message).finish();
 
-    // Write to .jj/working_copy/tree_state
+    // Write to .jj/working_copy/tree_state (atomically — see issue #16).
     const treeStatePath = `${this.dir}/.jj/working_copy/tree_state`;
-    await this.fs.promises.writeFile(treeStatePath, buffer);
+    await atomicWriteFile(this.fs, treeStatePath, buffer);
   }
 
   /**
@@ -5416,7 +6607,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
@@ -5440,15 +6631,6 @@ class JJTreeState {
  */
 
 
-const __filename$2 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
-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)
@@ -5457,7 +6639,6 @@ class JJOperationStore {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir$1, 'simple_op_store.proto');
   }
 
   /**
@@ -5470,12 +6651,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 = {
@@ -5512,9 +6693,11 @@ class JJOperationStore {
     // Encode to binary
     const buffer = Operation.encode(message).finish();
 
-    // Write to .jj/repo/op_store/operations/OPERATIONID
+    // Write to .jj/repo/op_store/operations/OPERATIONID (atomically — a
+    // crash mid-write must never leave a truncated/undecodable file, see
+    // issue #16).
     const opPath = `${this.dir}/.jj/repo/op_store/operations/${operationId}`;
-    await this.fs.promises.writeFile(opPath, buffer);
+    await atomicWriteFile(this.fs, opPath, buffer);
   }
 
   /**
@@ -5529,7 +6712,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
@@ -5568,15 +6751,6 @@ class JJOperationStore {
  */
 
 
-const __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
-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)
@@ -5585,7 +6759,6 @@ class JJViewStore {
   constructor(fs, dir) {
     this.fs = fs;
     this.dir = dir;
-    this.protoPath = path.join(protoDir, 'simple_op_store.proto');
   }
 
   /**
@@ -5597,17 +6770,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)
@@ -5631,9 +6804,9 @@ class JJViewStore {
     // Encode to binary
     const buffer = View.encode(message).finish();
 
-    // Write to .jj/repo/op_store/views/VIEWID
+    // Write to .jj/repo/op_store/views/VIEWID (atomically — see issue #16).
     const viewPath = `${this.dir}/.jj/repo/op_store/views/${viewId}`;
-    await this.fs.promises.writeFile(viewPath, buffer);
+    await atomicWriteFile(this.fs, viewPath, buffer);
   }
 
   /**
@@ -5648,7 +6821,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
@@ -6210,7 +7383,11 @@ class IsomorphicGitBackend {
    * @param {boolean} [opts.force] - Allow non-fast-forward
    * @param {any} [opts.onProgress] - Progress callback
    * @param {any} [opts.onAuth] - Authentication callback
-   * @returns {Promise<{pushedRefs: Array<any>, rejectedRefs: Array<any>}>} Push result
+   * @returns {Promise<{pushedRefs: Array<{name: string, oid: string}>, rejectedRefs: Array<{name: string, code: string, reason: string, message: string}>}>} Push result.
+   *   Each rejected ref carries a `code` (one of `AUTH_FAILED`,
+   *   `NETWORK_ERROR`, `NON_FAST_FORWARD`, `OTHER`) and a human-readable
+   *   `reason`, so callers can tell an auth failure apart from a
+   *   non-fast-forward rejection instead of guessing (see issue #14).
    */
   async push(opts) {
     if (!this.http) {
@@ -6246,8 +7423,13 @@ class IsomorphicGitBackend {
             pushedRefs.push({ name: ref, oid });
           }
         } catch (pushError) {
-          // Track rejected refs
-          rejectedRefs.push(ref);
+          // Track rejected refs with the categorized reason so callers can
+          // distinguish an auth failure from a non-fast-forward rejection
+          // (or a network blip) instead of guessing — see issue #14. A
+          // caller that blindly retries with force:true on every rejection
+          // risks doing so on what was actually an auth/network problem.
+          const { code, reason } = this._categorizePushError(pushError);
+          rejectedRefs.push({ name: ref, code, reason, message: pushError.message });
         }
       }
 
@@ -6279,6 +7461,53 @@ class IsomorphicGitBackend {
     }
   }
 
+  /**
+   * Categorize a per-ref push failure into a stable code/reason pair so
+   * callers can distinguish auth failures, network errors, and
+   * non-fast-forward rejections from each other and from other/unknown
+   * failures — see issue #14. isomorphic-git doesn't throw a single
+   * "AuthError" class; auth failures generally surface as an HttpError with
+   * a 401/403 status code (or a UserCanceledError if onAuth cancels).
+   *
+   * @private
+   * @param {any} error - Error thrown by git.push() for a single ref
+   * @returns {{code: string, reason: string}}
+   */
+  _categorizePushError(error) {
+    const errCode = error && error.code;
+
+    if (errCode === 'PushRejectedError') {
+      const reason = error.data && error.data.reason;
+      return {
+        code: 'NON_FAST_FORWARD',
+        reason: reason === 'tag-exists' ? 'tag already exists on remote' : 'non-fast-forward',
+      };
+    }
+
+    if (errCode === 'HttpError') {
+      const status = error.data && error.data.statusCode;
+      if (status === 401 || status === 403) {
+        return { code: 'AUTH_FAILED', reason: `HTTP ${status}` };
+      }
+      return { code: 'NETWORK_ERROR', reason: status ? `HTTP ${status}` : 'HTTP error' };
+    }
+
+    if (
+      errCode === 'AuthError' ||
+      errCode === 'UserCanceledError' ||
+      errCode === 'MissingUsernameError' ||
+      errCode === 'MissingPasswordTokenError'
+    ) {
+      return { code: 'AUTH_FAILED', reason: errCode };
+    }
+
+    if (errCode === 'NetworkError' || errCode === 'UnknownTransportError') {
+      return { code: 'NETWORK_ERROR', reason: errCode };
+    }
+
+    return { code: 'OTHER', reason: (error && error.message) || String(error) };
+  }
+
   /**
    * Create minimal .jj/repo structure for jj CLI compatibility
    * @private
@@ -6288,14 +7517,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');
@@ -6322,8 +7551,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
@@ -6335,7 +7564,7 @@ class IsomorphicGitBackend {
         ref: 'HEAD',
       });
       if (headOid) {
-        initialCommitId = crypto$1.randomBytes(64).toString('hex');
+        initialCommitId = randomHex(64);
       }
     } catch (error) {
       // No initial commit yet
@@ -6492,7 +7721,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
@@ -6505,7 +7734,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) {
@@ -6516,7 +7745,258 @@ async function createJJ(options) {
       // If we can't list files, return empty snapshot
     }
 
-    return fileSnapshot;
+    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 };
+  };
+
+  /**
+   * Apply a reversal computed by computeGraphReversal() to the live graph,
+   * working-copy files, and conflict state. Does NOT touch the working-copy
+   * pointer or bookmarks — callers set those from the landing op's own
+   * `view` directly (pointers, unlike file/graph/conflict content, are
+   * already correct as recorded, see computeGraphReversal's doc comment).
+   *
+   * @param {ReturnType<typeof computeGraphReversal>} reversal
+   * @returns {Promise<void>}
+   */
+  const applyGraphReversal = async (reversal) => {
+    await graph.load();
+    for (const [changeId, snapshot] of Object.entries(reversal.changeSnapshotToApply)) {
+      if (await graph.getChange(changeId)) {
+        await graph.updateChange(snapshot);
+      }
+    }
+
+    if (reversal.fileSnapshot !== undefined) {
+      await syncWorkingCopyFiles(reversal.fileSnapshot);
+    }
+
+    await conflicts.load();
+    if (reversal.conflictsSnapshot !== undefined) {
+      conflicts.conflicts = new Map(Object.entries(reversal.conflictsSnapshot.conflicts || {}));
+      conflicts.fileConflicts = new Map(
+        Object.entries(reversal.conflictsSnapshot.fileConflicts || {})
+      );
+      await conflicts.save();
+    }
+    // Else: no operation in the reverted range touched conflicts — leave
+    // current conflict state alone. (Previously undo() unconditionally
+    // cleared ALL conflicts whenever the op being undone hadn't recorded
+    // its own conflictsSnapshot, which is nearly every non-merge() op —
+    // undoing an unrelated describe() would silently wipe conflicts from
+    // an earlier, unrelated merge(). Fixed as part of issue #29.)
+  };
+
+  /**
+   * Re-parent every child of `changeId` onto `newParents` instead — used
+   * when a change is being elided from the graph (abandon(), issue #30;
+   * converge(), issue #32) so its children don't end up pointing at
+   * something no longer meant to be there. Mutates `changeSnapshot` in
+   * place, adding each touched child's PRE-reparent record so the caller's
+   * own oplog entry lets undo()/redo()/operations.restore() reverse this
+   * too (the same mechanism the caller already uses for the elided
+   * change's own snapshot).
+   *
+   * @param {string} changeId - The change being elided
+   * @param {string[]} newParents - What its children should point at instead
+   * @param {Record<string, any>} changeSnapshot - Accumulator to add each touched child's pre-state to
+   * @returns {Promise<void>}
+   */
+  const reparentChildrenOnto = async (changeId, newParents, changeSnapshot) => {
+    const childIds = graph.getChildren(changeId);
+    for (const childId of childIds) {
+      const child = await graph.getChange(childId);
+      if (!child) continue;
+      changeSnapshot[childId] = structuredClone(child);
+      const reparented = child.parents.flatMap((/** @type {string} */ p) =>
+        p === changeId ? newParents : [p]
+      );
+      // De-dupe (e.g. the child could already have one of the new parents
+      // as another of its own parents) while preserving first-seen order.
+      child.parents = [...new Set(reparented)];
+      await graph.updateChange(child);
+    }
+  };
+
+  /**
+   * Determine which operation a fresh undo() call should revert, matching
+   * real jj's progressive-undo semantics (`jj-undo(1)`: "If used once after
+   * a normal operation, this will undo that last operation by restoring its
+   * parent. If jj undo is used repeatedly, it will restore increasingly
+   * older operations, going further back into the past.").
+   *
+   * The raw op-log parent chain can't answer this directly once undo/redo
+   * bookkeeping operations are mixed into the log: an 'undo' operation's
+   * own parent is the operation it just undid, so naively targeting
+   * `ops[ops.length - 1]` on a SECOND undo() would undo the undo (toggle
+   * back to the future) instead of stepping one further step into the past
+   * — this was issue #29's "undo() twice only undoes the undo" bug.
+   *
+   * @param {Array<any>} ops - Full chronological operation list
+   * @returns {any} The operation object undo() should revert
+   */
+  const resolveUndoTarget = (ops) => {
+    const head = ops[ops.length - 1];
+    const findOp = (/** @type {any} */ id) => ops.find((op) => op.id === id);
+
+    if (head.eventType === 'undo') {
+      // We're stepping further into the past: what should be undone now is
+      // the operation right BEFORE the one `head` already undid — not
+      // head's own parent, which IS the operation head undid (targeting it
+      // again would just toggle back to the present).
+      const previouslyUndone = head.targetOpId && findOp(head.targetOpId);
+      const stepBack = previouslyUndone && findOp(previouslyUndone.parents[0]);
+      return stepBack || previouslyUndone || head;
+    }
+
+    if (head.eventType === 'redo') {
+      // A redo re-established some earlier operation as current; a fresh
+      // undo right after it should behave exactly as if that operation
+      // were freshly current and had never been touched by undo/redo at
+      // all — i.e. undo it again (real jj: redo "moves in the direction of
+      // the future"; undoing right after simply resumes stepping back).
+      const redoneUndo = head.redoOf && findOp(head.redoOf);
+      const target = redoneUndo && redoneUndo.targetOpId && findOp(redoneUndo.targetOpId);
+      return target || head;
+    }
+
+    return head;
   };
 
   /**
@@ -6703,6 +8183,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(),
     };
@@ -6860,6 +8359,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
      */
@@ -6883,7 +8396,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
@@ -6938,10 +8451,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);
           }
@@ -7106,7 +8619,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,
@@ -7156,14 +8669,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
@@ -7276,7 +8789,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',
@@ -7394,6 +8907,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);
@@ -7404,6 +8962,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: {},
@@ -7412,7 +8972,7 @@ async function createJJ(options) {
         },
       });
 
-      return change;
+      return { ...change, conflicts: detectedConflicts };
     },
 
     /**
@@ -7544,6 +9104,11 @@ async function createJJ(options) {
       const isWorkingCopy = targetChangeId === workingCopy.getCurrentChangeId();
       const fileSnapshotBefore = isWorkingCopy ? await snapshotFilesystem() : null;
 
+      // Snapshot the change record itself from BEFORE this operation mutates
+      // it in place, so undo() can restore ChangeGraph content (not just
+      // on-disk files/working-copy pointer) — mirrors fileSnapshotBefore above.
+      const changeSnapshotBefore = structuredClone(change);
+
       // Dispatch change:updating event (preventable)
       await dispatchEventAsync(jj, 'change:updating', {
         operation: 'describe',
@@ -7579,7 +9144,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)
@@ -7592,7 +9157,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) {
@@ -7624,6 +9189,10 @@ async function createJJ(options) {
         },
         description: `describe change ${targetChangeId.slice(0, 8)}`,
         parents: [],
+        // Snapshot of the affected ChangeGraph node from BEFORE this
+        // operation ran, so undo() can restore in-place content mutations
+        // (e.g. the description change below) — not just files/pointers.
+        changeSnapshot: { [targetChangeId]: changeSnapshotBefore },
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -7786,6 +9355,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();
 
@@ -7794,6 +9365,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);
         }
@@ -7821,6 +9396,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]);
@@ -7864,10 +9440,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
@@ -7880,6 +9465,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: {},
@@ -8136,11 +9728,28 @@ async function createJJ(options) {
         // Try to resolve as revset
         try {
           const changes = await revset.evaluate(args.change);
+          if (changes.length > 1) {
+            // An id-prefix (or other) revset that matches more than one
+            // change must not silently pick a "winner" — see issue #13.
+            throw new JJError(
+              'AMBIGUOUS_ID',
+              `"${args.change}" is ambiguous: it resolves to ${changes.length} changes (${changes.join(', ')})`,
+              {
+                expression: args.change,
+                matches: changes,
+                suggestion: 'Use a longer prefix or an exact change ID to disambiguate',
+              }
+            );
+          }
           if (changes.length > 0) {
             changeId = changes[0];
           }
-        } catch {
-          // Use as-is
+        } catch (error) {
+          if (error instanceof JJError && error.code === 'AMBIGUOUS_ID') {
+            throw error;
+          }
+          // Not a valid revset expression - use args.change as-is (e.g. a
+          // literal change ID that revset parsing rejected).
         }
       }
 
@@ -8243,6 +9852,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) {
@@ -8256,7 +9872,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) {
@@ -8264,13 +9880,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);
+          }
         }
       }
 
@@ -8283,38 +9900,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
@@ -8330,11 +9926,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,
         },
       });
 
@@ -8365,91 +9963,107 @@ 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);
+      const targetOp = resolveUndoTarget(ops);
+      const landingOpId = targetOp.parents && targetOp.parents[0];
+      const landingOp = landingOpId ? ops.find((op) => op.id === landingOpId) : null;
 
-      // 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 }
-            );
-          }
-        }
+      /** @type {ReturnType<typeof computeGraphReversal>} */
+      let reversal;
+      /** @type {any} */
+      let landingView;
+      if (landingOp) {
+        reversal = computeGraphReversal(ops, landingOp);
+        landingView = landingOp.view || {};
+      } else {
+        // 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),
+        };
       }
 
-      // 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();
-      } else {
-        // No conflicts snapshot - clear conflicts
-        await conflicts.clear();
+      if (landingView.workingCopy) {
+        await workingCopy.setCurrentChange(landingView.workingCopy);
       }
+      await applyGraphReversal(reversal);
 
-      // 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).
+      // 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).
       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
+        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,
         },
       };
     },
@@ -8457,9 +10071,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
      */
@@ -8490,42 +10104,36 @@ 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();
+      for (const [changeId, snapshot] of Object.entries(undoOp.redoChangeSnapshot || {})) {
+        if (await graph.getChange(changeId)) {
+          await graph.updateChange(snapshot);
         }
       }
-
-      // Restore conflicts to the state that existed after the redone operation.
+      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();
       }
@@ -8540,15 +10148,18 @@ async function createJJ(options) {
         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,
         },
       };
     },
@@ -8775,6 +10386,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
        */
@@ -8814,6 +10431,11 @@ 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);
+        await applyGraphReversal(reversal);
+
         // Record this restoration as a new operation
         await oplog.recordOperation({
           timestamp: new Date().toISOString(),
@@ -8867,6 +10489,7 @@ async function createJJ(options) {
         // Compute the inverse changes
         const inversChanges = /** @type {Record<string, any>} */ ({
           bookmarks: {},
+          tags: {},
           heads: [],
         });
 
@@ -8906,6 +10529,46 @@ async function createJJ(options) {
 
         await bookmarks.save();
 
+        // Revert tag changes (mirrors the bookmark diff above — issue #12).
+        // Unlike bookmarks, TagStore has no "move" primitive (tags are meant
+        // to be immutable once created), so a moved tag is reverted via
+        // delete+recreate, matching how tag.set() itself updates a tag.
+        const prevTags = previousOp.view?.tags || {};
+        const targetTags = targetOp.view?.tags || {};
+
+        for (const name of Object.keys(targetTags)) {
+          if (!prevTags[name]) {
+            // Tag was added - delete it
+            if (await tags.exists(name)) {
+              await tags.delete(name);
+            }
+            inversChanges.tags[name] = { action: 'deleted' };
+          } else if (prevTags[name] !== targetTags[name]) {
+            // Tag was moved - restore old target
+            if (await tags.exists(name)) {
+              await tags.delete(name);
+            }
+            await tags.create(name, prevTags[name]);
+            inversChanges.tags[name] = {
+              action: 'moved',
+              from: targetTags[name],
+              to: prevTags[name],
+            };
+          }
+        }
+
+        // Check for deleted tags (existed before, don't exist after)
+        for (const name of Object.keys(prevTags)) {
+          if (!targetTags[name] && !(await tags.exists(name))) {
+            // Tag was deleted - restore it
+            await tags.create(name, prevTags[name]);
+            inversChanges.tags[name] = {
+              action: 'restored',
+              to: prevTags[name],
+            };
+          }
+        }
+
         // Revert working copy change if it changed
         if (previousOp.view?.workingCopy !== targetOp.view?.workingCopy) {
           await workingCopy.load();
@@ -8920,6 +10583,7 @@ async function createJJ(options) {
           parents: [],
           view: {
             bookmarks: prevBookmarks,
+            tags: prevTags,
             remoteBookmarks: previousOp.view?.remoteBookmarks || {},
             heads: previousOp.view?.heads || [],
             workingCopy: previousOp.view?.workingCopy,
@@ -9063,10 +10727,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);
@@ -9108,6 +10815,7 @@ async function createJJ(options) {
         user: await getUserOplogInfo(),
         description: `squash ${source.slice(0, 8)} into ${destChangeId.slice(0, 8)}`,
         parents: [],
+        changeSnapshot,
         view: {
           bookmarks: {},
           remoteBookmarks: {},
@@ -9186,15 +10894,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: {},
@@ -9219,6 +10941,206 @@ async function createJJ(options) {
       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
      *
@@ -10680,7 +12602,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({
@@ -11058,8 +12980,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);
@@ -11138,7 +13066,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
@@ -11281,7 +13209,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');
@@ -11324,7 +13252,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);
@@ -11357,11 +13285,18 @@ async function createJJ(options) {
           throw new JJError('CONFLICT_NOT_FOUND', `Conflict ${args.conflictId} not found`);
         }
 
-        // Generate standard conflict markers
+        // Generate standard conflict markers. Force a newline before each
+        // boundary marker whenever there's non-empty content that doesn't
+        // already end in one — otherwise the content fuses onto the
+        // `=======`/`>>>>>>> theirs` marker, producing a corrupted/unparseable
+        // line (see issue #15). Empty sides (e.g. a modify-delete conflict)
+        // intentionally get no extra blank line before the marker.
         const ours = conflict.sides.left || '';
         const theirs = conflict.sides.right || '';
+        const oursSep = ours && !ours.endsWith('\n') ? '\n' : '';
+        const theirsSep = theirs && !theirs.endsWith('\n') ? '\n' : '';
 
-        return `<<<<<<< ours\n${ours}=======\n${theirs}>>>>>>> theirs`;
+        return `<<<<<<< ours\n${ours}${oursSep}=======\n${theirs}${theirsSep}>>>>>>> theirs`;
       },
 
       /**
@@ -11448,10 +13383,17 @@ async function createJJ(options) {
        * Searches the tracked files of a change (defaults to the working copy)
        * for lines matching a pattern. Following jj v0.41, the pattern is treated
        * as a regular expression by default; pass `{ kind: 'substring' }` for a
-       * literal search.
+       * literal search. isomorphic-jj has always returned the matched line
+       * (and its 1-based `lineNumber`) alongside the path, which is what jj
+       * v0.44 made the CLI's new default (`jj file search` used to print only
+       * file paths). Pass `{ nameOnly: true }` for the pre-v0.44 CLI
+       * behavior — a deduplicated list of matching file paths, matching the
+       * new `--name-only` flag.
        *
-       * @param {Record<string, any>} args - Arguments
-       * @returns {Promise<Array<{path: string, lineNumber: number, line: string}>>}
+       * @param {Record<string, any>} args - Arguments. Pass `nameOnly: true`
+       *   to return only unique matching file paths instead of per-line
+       *   matches (jj v0.44 `--name-only`)
+       * @returns {Promise<Array<{path: string, lineNumber: number, line: string}>|Array<string>>}
        */
       async search(args) {
         if (!args || !args.pattern) {
@@ -11502,6 +13444,10 @@ async function createJJ(options) {
             }
           });
         }
+
+        if (args.nameOnly) {
+          return Array.from(new Set(results.map((r) => r.path)));
+        }
         return results;
       },
 
@@ -11628,7 +13574,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;
@@ -11739,14 +13685,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
@@ -12583,6 +14529,10 @@ async function createJJ(options) {
           view: {
             bookmarks: {},
             remoteBookmarks: {},
+            // Tag delta for this operation (mirrors how `bookmarks` records
+            // its delta above), so operations.revert() can diff it — see
+            // issue #12.
+            tags: { [args.name]: changeId },
             heads: [],
             workingCopy: workingCopy.getCurrentChangeId(),
           },
@@ -12628,6 +14578,7 @@ async function createJJ(options) {
           view: {
             bookmarks: {},
             remoteBookmarks: {},
+            tags: { [args.name]: changeId },
             heads: [],
             workingCopy: workingCopy.getCurrentChangeId(),
           },
@@ -12637,10 +14588,11 @@ async function createJJ(options) {
       },
 
       /**
-       * List all tags
+       * List all tags. Each entry also carries a `tracking: { remote, ref }`
+       * field when the tag is tracking a remote (jj v0.44 `jj tag track`).
        *
        * @param {Record<string, any>} [args] - Optional filter arguments
-       * @returns {Promise<Array<{name: string, changeId: string}>>} List of tags
+       * @returns {Promise<Array<Record<string, any>>>} List of tags
        */
       async list(args) {
         const pattern = args?.pattern;
@@ -12672,6 +14624,7 @@ async function createJJ(options) {
           view: {
             bookmarks: {},
             remoteBookmarks: {},
+            tags: {},
             heads: [],
             workingCopy: workingCopy.getCurrentChangeId(),
           },
@@ -12679,6 +14632,94 @@ async function createJJ(options) {
 
         return { deleted: args.name };
       },
+
+      /**
+       * Associate a local tag with a remote tag so it is updated on fetch
+       * (matches `jj tag track`, new in jj v0.44).
+       *
+       * jj v0.44 made tags remote-trackable just like bookmarks: fetched
+       * tags are tracked by default, and `jj tag track`/`untrack` let you
+       * opt individual tags in or out by hand. isomorphic-jj doesn't (yet)
+       * auto-import remote tags during `git.fetch()` — see CHANGELOG — so
+       * this records tracking intent/state the same way `bookmark.track()`
+       * does, without changing fetch's own behavior.
+       *
+       * @param {Record<string, any>} args - Tag arguments: `{ name, remote }`
+       *   (`name` is the local tag name to track; `remote` defaults to `'origin'`)
+       * @returns {Promise<{name: string, remote: string, tracking: boolean}>}
+       */
+      async track(args) {
+        if (!args || !args.name) {
+          throw new JJError('INVALID_ARGUMENT', 'Missing tag name', {
+            suggestion: 'Provide tag name: { name: "v1.0.0", remote: "origin" }',
+          });
+        }
+
+        const remote = args.remote || 'origin';
+        const remoteTagName = `${remote}/${args.name}`;
+
+        const tagMap = await tags.load();
+        /** @type {Record<string, any>} */
+        const tracking = tags.tracking || {};
+        tracking[args.name] = { remote, remoteName: args.name };
+        tags.tracking = tracking;
+        await tags.save(tagMap);
+
+        // Record operation
+        await oplog.recordOperation({
+          timestamp: new Date().toISOString(),
+          user: await getUserOplogInfo(),
+          description: `tag track ${args.name} from ${remote}`,
+          parents: [],
+          view: {
+            bookmarks: {},
+            remoteBookmarks: { [remoteTagName]: true },
+            heads: [],
+            workingCopy: workingCopy.getCurrentChangeId(),
+          },
+        });
+
+        return { name: args.name, remote, tracking: true };
+      },
+
+      /**
+       * Stop tracking a remote tag (matches `jj tag untrack`, new in jj v0.44).
+       *
+       * @param {Record<string, any>} args - Tag arguments: `{ name }`, the
+       *   local tag name to stop tracking
+       * @returns {Promise<{name: string, tracking: boolean, wasTracking: boolean}>}
+       */
+      async untrack(args) {
+        if (!args || !args.name) {
+          throw new JJError('INVALID_ARGUMENT', 'Missing tag name', {
+            suggestion: 'Provide tag name: { name: "v1.0.0" }',
+          });
+        }
+
+        const tagMap = await tags.load();
+        /** @type {Record<string, any>} */
+        const tracking = tags.tracking || {};
+        const wasTracking = tracking[args.name];
+        delete tracking[args.name];
+        tags.tracking = tracking;
+        await tags.save(tagMap);
+
+        // Record operation
+        await oplog.recordOperation({
+          timestamp: new Date().toISOString(),
+          user: await getUserOplogInfo(),
+          description: `tag untrack ${args.name}`,
+          parents: [],
+          view: {
+            bookmarks: {},
+            remoteBookmarks: {},
+            heads: [],
+            workingCopy: workingCopy.getCurrentChangeId(),
+          },
+        });
+
+        return { name: args.name, tracking: false, wasTracking: !!wasTracking };
+      },
     },
 
     /**