Fix "Specified HEAD didn't match actual HEAD^{tree}" error on branch apply

Telemetry showed users hitting this error when applying a branch. It's
caused by a race condition: `apply()` reads `prev_head_id` from the
workspace graph and passes it to `safe_checkout`, but between those two
calls the file watcher can run `update_workspace_commit`, which moves
the `gitbutler/workspace` ref to a new commit with a different tree.

Inside `merge_worktree_changes_into_destination_or_keep_snapshot`, the
caller's stale `source_tree_id` was compared against
`repo.head_tree_id_or_empty()` and the mismatch triggered a `bail!()`.

The fix removes that assertion and always reads the tree from
`repo.head_tree_id_or_empty()`. This is correct because worktree diffs
(via the git index) are always relative to the actual HEAD tree, not
whatever the caller cached — so the snapshot base must match.

Includes regression test:
`checkout_succeeds_when_source_tree_diverges_from_head`

Remove unused source_tree_id parameter

Remove the now-unused source_tree_id parameter from
merge_worktree_changes_into_destination_or_keep_snapshot and its
callers. The parameter was unused in the function body and
documentation, so eliminating it cleans up the function signature,
related docs, and the call site in function.rs to avoid passing an
unnecessary value. This simplifies the API and reduces confusion about
the expected inputs.

Author: mtsgrd

crates/but-core/src/worktree/checkout/function.rs

@@ -74,7 +74,6 @@ pub fn safe_checkout(
     let snapshot_tree = merge_worktree_changes_into_destination_or_keep_snapshot(
         &changed_files,
         repo,
-        source_tree.id,
         destination_tree.id,
         &mut opts,
         conflicting_worktree_changes_opts,

crates/but-core/src/worktree/checkout/utils.rs

@@ -36,9 +36,6 @@ use crate::{
 /// * `repo` - Repository used to inspect the current worktree, read the current `HEAD` tree, create
 ///   snapshot trees, and persist any in-memory objects needed by the adjusted destination tree if one is written.
 ///   No changes will be observable if there is no intersecting worktree changes.
-/// * `source_tree_id` - The tree expected to match the repository's current `HEAD`. It is used as the
-///   base for the snapshot of local worktree changes, and is verified against the actual `HEAD` before
-///   preserving changes.
 /// * `destination_tree_id` - The tree the checkout originally intends to write into the worktree. If
 ///   preserved worktree changes can be cleanly reapplied, they are resolved onto this tree and may
 ///   produce a replacement destination tree in the return value.
@@ -64,7 +61,6 @@ use crate::{
 pub fn merge_worktree_changes_into_destination_or_keep_snapshot(
     files_to_checkout: &[(ChangeKind, BString)],
     repo: &gix::Repository,
-    source_tree_id: gix::ObjectId,
     destination_tree_id: gix::ObjectId,
     checkout_opts: &mut git2::build::CheckoutBuilder,
     uncommitted_changes: UncommitedWorktreeChanges,
@@ -76,11 +72,11 @@ pub fn merge_worktree_changes_into_destination_or_keep_snapshot(
     let worktree_changes = crate::diff::worktree_changes_no_renames(repo)?;
     if !worktree_changes.changes.is_empty() || !worktree_changes.ignored_changes.is_empty() {
         let actual_head_tree_id = repo.head_tree_id_or_empty()?;
-        if actual_head_tree_id != source_tree_id {
-            bail!(
-                "Specified HEAD {source_tree_id} didn't match actual HEAD^{{tree}} {actual_head_tree_id}"
-            )
-        }
+        // Worktree changes are always relative to the actual HEAD tree (via the index),
+        // so the snapshot must use it as its base. If the caller's source tree diverges
+        // (e.g. due to a concurrent workspace commit update), we use the actual HEAD tree
+        // to keep the snapshot consistent with the worktree diff.
+        let source_tree_id = actual_head_tree_id.detach();
         let mut checkout_deletions_lut = super::tree::Lut::default();
         let mut checkout_writes_lut = super::tree::Lut::default();
         for (kind, path) in files_to_checkout {

crates/but-core/tests/core/worktree/checkout.rs

@@ -1086,6 +1086,89 @@ fn partial_commit_with_deletion_plus_insertion_conflicts_on_checkout() -> anyhow
     Ok(())
 }
 
+#[test]
+fn checkout_succeeds_when_source_tree_diverges_from_head() -> anyhow::Result<()> {
+    let (repo, _tmp) = writable_scenario("mixed-hunk-modifications");
+    // This scenario has uncommitted worktree changes — the condition that
+    // triggers the HEAD tree consistency check.
+    insta::assert_snapshot!(git_status(&repo)?, @r"
+     M file
+    M  file-in-index
+    RM file-to-be-renamed-in-index -> file-renamed-in-index
+     D file-to-be-renamed
+    ?? file-renamed
+    ");
+
+    // Build a target commit that adds a new independent file, so the checkout
+    // doesn't conflict with the existing worktree changes.
+    let (head_commit, new_commit) = build_commit(
+        &repo,
+        |tree| {
+            let blob_id = repo.write_blob(b"new-content\n")?;
+            tree.upsert("new-file", EntryKind::Blob, blob_id)?;
+            Ok(())
+        },
+        "add 'new-file'",
+    )?;
+
+    // Create a "stale" commit with a different tree to simulate stale workspace
+    // metadata causing `entrypoint_commit()` to return a commit whose tree
+    // differs from actual HEAD^{tree}. This reproduces the "Specified HEAD
+    // didn't match actual HEAD^{tree}" error from production telemetry.
+    let stale_tree = {
+        let mut editor = head_commit.tree()?.edit()?;
+        let blob_id = repo.write_blob(b"stale marker\n")?;
+        editor.upsert("stale-marker", EntryKind::Blob, blob_id)?;
+        editor.write()?.detach()
+    };
+    let stale_commit_id = repo
+        .write_object(gix::objs::Commit {
+            tree: stale_tree,
+            parents: [head_commit.id].into(),
+            message: "stale workspace commit".into(),
+            ..head_commit.decode()?.to_owned()?
+        })?
+        .detach();
+
+    // Pass the stale commit as current_head_id. Its tree differs from what
+    // HEAD^{tree} actually is, but the checkout should still succeed — the
+    // worktree changes are relative to the real HEAD, not the stale commit.
+    let out = safe_checkout(
+        stale_commit_id,
+        new_commit.id,
+        &repo,
+        checkout::Options {
+            skip_head_update: true,
+            ..Default::default()
+        },
+    )?;
+    insta::assert_debug_snapshot!(out, @r#"
+    Outcome {
+        snapshot_tree: None,
+        num_deleted_files: 1,
+        num_added_or_updated_files: 1,
+        head_update: "None",
+    }
+    "#);
+
+    // The new file was checked out.
+    let new_file = repo.workdir_path("new-file").unwrap();
+    assert!(new_file.exists(), "new-file should have been checked out");
+    assert_eq!(std::fs::read_to_string(new_file)?, "new-content\n");
+
+    // The existing worktree changes are preserved.
+    insta::assert_snapshot!(git_status(&repo)?, @r"
+     M file
+    M  file-in-index
+    RM file-to-be-renamed-in-index -> file-renamed-in-index
+     D file-to-be-renamed
+    A  new-file
+    ?? file-renamed
+    ");
+
+    Ok(())
+}
+
 fn overwrite_options() -> checkout::Options {
     checkout::Options {
         uncommitted_changes: UncommitedWorktreeChanges::KeepConflictingInSnapshotAndOverwrite,