diff --git a/crates/agent_ui/src/thread_metadata_store.rs b/crates/agent_ui/src/thread_metadata_store.rs
index b0e85e71f4c009811b372a89c998cea2c13cbebc..cbc5c2ae51799955bca96efb75403eb7c4ee77ca 100644
--- a/crates/agent_ui/src/thread_metadata_store.rs
+++ b/crates/agent_ui/src/thread_metadata_store.rs
@@ -149,19 +149,37 @@ impl From<&ThreadMetadata> for acp_thread::AgentSessionInfo {
 
 /// Record of a git worktree that was archived (deleted from disk) when its last thread was archived.
 pub struct ArchivedGitWorktree {
-    /// Auto-incrementing primary key, used for the git ref name and join table.
+    /// Auto-incrementing primary key
     pub id: i64,
-    /// Absolute path where the worktree directory lived on disk before deletion.
+    /// Absolute path to the directory of the worktree before it was deleted.
+    /// Used when restoring, to put the recreated worktree back where it was.
+    /// (If that dir is already taken when restoring, we auto-generate a new dir.)
     pub worktree_path: PathBuf,
-    /// Absolute path of the main (non-linked) repository that owns this worktree.
+    /// Absolute path of the main repository ("main worktree") that owned this worktree.
+    /// Used when restoring, to reattach the recreated worktree to the correct main worktree.
+    /// (If that dir is missing, use worktree_path as the new main worktree.)
     pub main_repo_path: PathBuf,
     /// Branch that was checked out in the worktree at archive time. `None` if
-    /// the worktree was in detached HEAD state, which shouldn't normally happen
-    /// for user-created linked worktrees but is possible via the terminal.
+    /// the worktree was in detached HEAD state, which isn't supported in Zed, but
+    /// could happen if the user made a detached one outside of Zed.
+    /// If that branch is missing, we auto-generate an new branch name. If the branch already
+    /// exists, we see if it points to our commit_hash~2 (~2 because commit_hash points to
+    /// WIP commits we created to preserve uncommitted and staged files, respectively),
+    /// and the branch does already point to that commit, then we use the branch as-is. If it
+    /// already exists but it's pointing to a different commit, we auto-gen a new branch.
     pub branch_name: Option<String>,
-    /// SHA of the WIP commit that preserves the worktree's file state.
+    /// SHA of the WIP commit that we made in order to save the files that were uncommitted
+    /// and unstaged at the time of archiving. This commit can be empty. Its parent commit
+    /// will also be a WIP that we created during archiving, which contains the files that
+    /// were staged at the time of archiving. (It can also be empty.) After doing `git reset`
+    /// past both of these commits, we're back in the state we had before archiving, including
+    /// what was staged, what was unstaged, and what was committed.
     pub commit_hash: String,
-    /// Whether this worktree has been restored by a prior unarchive.
+    /// Whether this worktree has been restored by a prior unarchive. This is used when
+    /// unarchiving multiple threads, and tells us whether to treat worktree_path's presence
+    /// in the filesystem as a collision to be worked around (the directory was "taken" by
+    /// something else while we were archived), or as a source of truth we can reuse for an
+    /// unarchived thread instead of needing to create another directory.
     pub restored: bool,
 }