forge_agent/env/

worktree.rs

//! Git-worktree helpers for the worker spawn and despawn paths:
//! detecting a repo, reading a worktree's branch, deciding whether a
//! worktree is safe to remove, removing it, and reaping the branch
//! behind it.
//!
//! Synchronous throughout because each answer is one fast git
//! subprocess and the callers are already on a tokio task.

use std::collections::HashMap;
use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::OnceLock;

use super::git_command;

/// Check whether `path` is inside a git repository. Shells out to
/// `git rev-parse --git-dir`. Exit 0 -> true; anything else -> false.
///
/// Handles every git-recognised shape (normal repo, submodule,
/// worktree-in-worktree, detached HEAD, bare repo) by reading git's
/// own answer rather than re-implementing detection. Non-existent
/// paths return false because git itself errors on them.
pub fn is_git_repo(path: &Path) -> bool {
    git_command::command("git")
        .args(["rev-parse", "--git-dir"])
        .current_dir(path)
        .output()
        .is_ok_and(|out| out.status.success())
}

/// The tree a worker spawned at `cwd` runs in: the repo root when the
/// path is inside a repository, the path itself otherwise. Both are
/// canonical, because the `claude` CLI derives the session JSONL's
/// directory from the canonical path - measured: a worktree under
/// `/tmp` writes its transcript under `/private/tmp` - so a record
/// holding the alias would name a directory the CLI never wrote to.
///
/// `Err` when the path is not there to canonicalize or is not a
/// directory, so a typo is refused where it was typed rather than
/// surfacing as claude's own cwd failure at spawn.
pub fn worker_root(cwd: &Path) -> Result<std::path::PathBuf, String> {
    let resolved = std::fs::canonicalize(cwd)
        .map_err(|error| format!("{} is not a directory: {error}", cwd.display()))?;
    if !resolved.is_dir() {
        return Err(format!("{} is not a directory", cwd.display()));
    }
    let Some(toplevel) = git_in_repo(&resolved, &["rev-parse", "--show-toplevel"]) else {
        return Ok(resolved);
    };
    Ok(std::fs::canonicalize(toplevel.trim()).unwrap_or(resolved))
}

/// The checkout root the `claude` CLI forks a worker's `--worktree` under:
/// the repository's main working tree, resolved from the first entry of
/// `git worktree list --porcelain` - the main checkout when the project is
/// itself a linked worktree, the repo root for a subdirectory. Measured on
/// 2.1.280: the CLI resolves its cwd to that root before composing
/// `<root>/.claude/worktrees/<label>`, so a project rooted in a linked
/// worktree (or in a repo subdirectory) otherwise names a directory the
/// CLI never creates (#2460). A path that is not a repository is its own
/// base.
///
/// A repository kept in a separate git dir is NOT a supported worker
/// layout: git names its admin dir (not a checkout) as the first worktree
/// entry, and the CLI's own base for that shape is unverified, so forge
/// follows git's answer rather than guessing a checkout it cannot derive.
///
/// Memoised per root: callers include render paths that ask per row per
/// frame, and a checkout's canonical root does not move under a live
/// forge. A git that could not answer is NOT memoised - a transient
/// failure must not pin the path this exists to correct - and is reported
/// once per root.
pub fn worktree_base(root: &Path) -> PathBuf {
    static BASES: OnceLock<parking_lot::Mutex<HashMap<PathBuf, PathBuf>>> = OnceLock::new();
    let cache = BASES.get_or_init(|| parking_lot::Mutex::new(HashMap::new()));
    if let Some(base) = cache.lock().get(root).cloned() {
        return base;
    }
    // A path that is not there cannot be a repository: answer without a
    // git call, so a caller on a render path (a stale row's gone tree)
    // does not spawn one per frame.
    if !root.is_dir() {
        return root.to_path_buf();
    }
    let Some(base) = resolve_worktree_base(root) else {
        // Not a repository is an answer; a repository git would not read
        // is not. Only the second is worth reporting, and neither is
        // cached: the next call re-asks.
        if is_git_repo(root) && first_unresolved(root) {
            report_unresolved_root(root);
        }
        return root.to_path_buf();
    };
    cache.lock().insert(root.to_path_buf(), base.clone());
    base
}

/// True the first time this process reports `root` as unresolved, so the
/// warning is one line per root rather than one per render-path call.
fn first_unresolved(root: &Path) -> bool {
    static UNRESOLVED: OnceLock<parking_lot::Mutex<std::collections::HashSet<PathBuf>>> =
        OnceLock::new();
    UNRESOLVED.get_or_init(Default::default).lock().insert(root.to_path_buf())
}

/// The one-line report for a root git would not name, so a log grep for
/// `worktree_base_unresolved` finds the path that composed the wrong way.
fn report_unresolved_root(root: &Path) {
    tracing::warn!(
        target: "forge_agent::env::worktree",
        event_name = "worktree_base_unresolved",
        repo = %root.display(),
        "git would not name this checkout's root, so worker paths compose from the project path \
         until it can; a linked-worktree project records the wrong directory meanwhile",
    );
}

/// [`worktree_base`] without the memo; `None` when git could not answer.
///
/// The first entry of `git worktree list --porcelain` is the main working
/// tree: the main checkout for a linked worktree, the repo root from a
/// subdirectory. A repo kept in a separate git dir is not a supported
/// layout - git names its admin dir there, and the CLI's base for it is
/// unverified - so forge follows git rather than guessing.
fn resolve_worktree_base(root: &Path) -> Option<PathBuf> {
    let listing = git_in_repo(root, &["worktree", "list", "--porcelain"])?;
    let first = listing.lines().find_map(|line| line.strip_prefix("worktree "))?;
    std::fs::canonicalize(first).ok()
}

/// The branch checked out at `path`, via `git rev-parse --abbrev-ref
/// HEAD`. `None` on detached HEAD, a git error, or non-utf8 output.
/// Read before a worktree is removed so its per-branch review threads
/// clean up under the same `(project, branch)` key the overlay saved
/// them with.
pub fn worktree_branch(path: &Path) -> Option<String> {
    let branch = git_in_repo(path, &["rev-parse", "--abbrev-ref", "HEAD"])?.trim().to_owned();
    if branch.is_empty() || branch == "HEAD" { None } else { Some(branch) }
}

/// Errors from [`remove_worktree`].
#[derive(Debug, thiserror::Error)]
pub enum WorktreeError {
    /// The worktree path has no parent directory, so there is no
    /// in-repo location to run `git worktree remove` from.
    #[error("worktree path {0} has no parent directory to run git from")]
    NoParent(String),
    /// `git worktree remove` could not be spawned at all.
    #[error("failed to spawn git worktree remove: {0}")]
    GitSpawn(String),
    /// `git worktree remove` ran but exited non-zero (e.g. a dirty
    /// worktree without `--force`, or a transient git error). Carries
    /// git's stderr.
    #[error("git worktree remove failed: {0}")]
    RemoveFailed(String),
    /// `git worktree add` ran but exited non-zero. Carries git's stderr.
    #[error("git worktree add failed: {0}")]
    CreateFailed(String),
    /// [`remove_orphaned_worktree_dir`] was handed a path that is not a
    /// direct child of the repo's `.claude/worktrees` root.
    #[error("refusing to remove {path}: not a worktree under {root}")]
    OutsideWorktreesRoot { path: String, root: String },
    /// [`remove_orphaned_worktree_dir`] was handed something that is not
    /// a plain directory (a file, a symlink, a missing path), so there
    /// is nothing safe to delete.
    #[error("refusing to remove {0}: not a directory")]
    NotAPlainDirectory(String),
    /// git still lists the path as a worktree, live or by the stale path
    /// a repo move leaves, so it is not a leftover: git may be holding
    /// uncommitted work in it. Also returned when the registration cannot
    /// be read - refusing is the safe direction.
    #[error("refusing to remove {0}: git still lists it as a worktree")]
    StillRegistered(String),
    /// [`remove_orphaned_worktree_dir`] was handed a directory whose
    /// `.git` entry says it belongs to something else - a directory (a
    /// checkout of its own, never a worktree tail), a link naming a live
    /// foreign repo, or a stale link with no removal this repo recorded.
    /// Not this repo's leftover, so not this repo's to delete.
    #[error("refusing to remove {path}: {detail}")]
    ForeignLeftover { path: String, detail: String },
    /// The registration git lists at the worktree path cannot be reused:
    /// its gitdir link names a path the repo has left and `git worktree
    /// repair` could not rewrite it, or it carries a live foreign link
    /// that repair would adopt. Either way the worktree is not this
    /// spawn's to use.
    #[error("refusing to reuse {path}: {detail}")]
    RegistrationUnusable { path: String, detail: String },
    /// The leftover directory itself could not be deleted from disk.
    #[error("failed to delete the leftover worktree directory {path}: {error}")]
    LeftoverUndeletable { path: String, error: String },
}

/// Why a worktree is not safe to remove, or `None` when it is clean.
///
/// "Dirty" means either uncommitted/untracked changes
/// (`git status --porcelain` non-empty) OR commits reachable from HEAD
/// and from no remote-tracking ref (`git rev-list --count HEAD --not
/// --remotes` > 0) - reachability, not the branch's upstream, which a
/// squash merge leaves permanently ahead. A branch whose configured
/// upstream ref has been deleted was pushed and its remote branch is
/// gone, which is how a squash land reads once the branch is pruned. A
/// repo with no remote-tracking refs stays not-unpushed. The despawn
/// path calls this BEFORE any teardown so a dirty worker is blocked
/// without being killed.
pub fn worktree_dirty_reason(path: &Path) -> Option<String> {
    if let Some(reason) = worktree_uncommitted_reason(path) {
        return Some(reason);
    }

    if let Some(ahead) = unpushed_commit_count(path)
        && ahead > 0
    {
        let plural = if ahead == 1 { "" } else { "s" };
        return Some(format!("{ahead} unpushed commit{plural}"));
    }

    None
}

/// Uncommitted or untracked changes, or `None` when the tree is
/// porcelain-clean.
///
/// The subagent reap gates on this alone: committed work is safe there
/// because the branch outlives the tree and [`reap_worktree_branch`]
/// keeps one holding unique commits. Uncommitted work exists only in
/// the tree, so a status that cannot be read blocks.
fn worktree_uncommitted_reason(path: &Path) -> Option<String> {
    match git_command::command("git").args(["status", "--porcelain"]).current_dir(path).output() {
        Ok(out) if out.status.success() => {
            if !out.stdout.is_empty() {
                return Some("uncommitted or untracked changes".to_owned());
            }
            None
        }
        // Couldn't read the status - block rather than risk discarding
        // work we failed to inspect.
        _ => Some("could not determine the worktree's git status".to_owned()),
    }
}

/// Commits HEAD reaches that no remote-tracking ref does, with a branch
/// whose remote branch was deleted counted as pushed. `None` when the
/// repo holds no remote-tracking refs to compare against, or when the
/// query fails - both leave the verdict clean.
///
/// A failed query does not block, unlike a failed status: commits live
/// on the branch, which the despawn's own reap keeps when it holds
/// unique commits, while uncommitted work would go with the tree.
fn unpushed_commit_count(path: &Path) -> Option<u64> {
    let has_remote_refs = git_command::command("git")
        .args(["for-each-ref", "--count=1", "--format=%(refname)", "refs/remotes/"])
        .current_dir(path)
        .output()
        .is_ok_and(|out| out.status.success() && !out.stdout.is_empty());
    if !has_remote_refs {
        return None;
    }
    let out = git_command::command("git")
        .args(["rev-list", "--count", "HEAD", "--not", "--remotes"])
        .current_dir(path)
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let count = String::from_utf8_lossy(&out.stdout).trim().parse().ok()?;
    if count == 0 || upstream_ref_deleted(path) { Some(0) } else { Some(count) }
}

/// Whether the branch's configured upstream names a remote ref that no
/// longer exists.
///
/// `push -u` writes the upstream only after a successful push, so the
/// branch was on that remote and its remote branch has since been
/// deleted - the shape a squash-merged PR leaves once the branch is
/// pruned. Neither reachability nor the upstream can see a squash by
/// sha, and by then the remote branch is normally gone.
///
/// This trusts `-u`: an upstream configured by hand against a ref that
/// was never fetched reads as deleted. Proceeding still loses nothing,
/// because the despawn's branch reap keeps a local branch holding
/// commits no other ref reaches, and reports it.
fn upstream_ref_deleted(path: &Path) -> bool {
    let Some(branch) = worktree_branch(path) else {
        return false;
    };
    let Some(remote) = git_config_value(path, &format!("branch.{branch}.remote")) else {
        return false;
    };
    // A `.` remote tracks a local branch, which is not a push.
    if remote == "." {
        return false;
    }
    let Some(tracked) = git_config_value(path, &format!("branch.{branch}.merge"))
        .and_then(|merge| merge.strip_prefix("refs/heads/").map(str::to_owned))
    else {
        return false;
    };
    let refname = format!("refs/remotes/{remote}/{tracked}");
    // `--quiet` exits 1 for a ref that is missing and 128 for a repo it
    // cannot read, so only 1 counts as deleted.
    git_command::command("git")
        .args(["rev-parse", "--verify", "--quiet", &refname])
        .current_dir(path)
        .output()
        .is_ok_and(|out| out.status.code() == Some(1))
}

/// One `git config --get` value, `None` when unset or unreadable.
fn git_config_value(path: &Path, key: &str) -> Option<String> {
    let out = git_command::command("git")
        .args(["config", "--get", key])
        .current_dir(path)
        .output()
        .ok()?;
    if !out.status.success() {
        return None;
    }
    let value = String::from_utf8_lossy(&out.stdout).trim().to_owned();
    if value.is_empty() { None } else { Some(value) }
}

/// Remove the git worktree at `path` via `git worktree remove`. Run
/// from the worktree's PARENT (which lives inside the main worktree
/// for claude's `<repo>/.claude/worktrees/<label>` layout), since git
/// refuses to remove the worktree it is invoked from. `force` adds
/// `--force`, removing even a dirty worktree (the despawn path only
/// reaches this on a verified-clean worktree, or when the caller
/// explicitly passed `force`).
///
/// Without `--force`, git itself refuses a worktree with
/// uncommitted/untracked changes, and also one holding initialized
/// submodules however clean it is - git-worktree(1) puts both cases
/// under `--force`. The unpushed-commits guard lives in
/// [`worktree_dirty_reason`] (git's own check does not cover unpushed).
pub fn remove_worktree(path: &Path, force: bool) -> Result<(), WorktreeError> {
    let parent =
        path.parent().ok_or_else(|| WorktreeError::NoParent(path.display().to_string()))?;
    // The worktree carries the claude session's own lock, which git
    // won't remove even with --force; unlock first, ignoring the result
    // since a not-locked worktree errors harmlessly.
    let _ = git_command::command("git")
        .arg("worktree")
        .arg("unlock")
        .arg(path)
        .current_dir(parent)
        .output();
    let mut cmd = git_command::command("git");
    cmd.arg("worktree").arg("remove");
    if force {
        cmd.arg("--force");
    }
    cmd.arg(path).current_dir(parent);
    let output = cmd.output().map_err(|e| WorktreeError::GitSpawn(e.to_string()))?;
    if output.status.success() {
        Ok(())
    } else {
        Err(WorktreeError::RemoveFailed(String::from_utf8_lossy(&output.stderr).trim().to_owned()))
    }
}

/// Delete the directory a failed [`remove_worktree`] left behind, once
/// git no longer lists it as a worktree.
///
/// `git worktree remove` deregisters the path before it walks the tree,
/// so a delete that fails part-way - a build still writing
/// into `target/` while the removal runs, which surfaces as "Directory
/// not empty" - leaves the directory with no registration at all: the
/// tree can no longer be read by git, and every later removal refuses it
/// as "not a working tree". The branch, which is where the work actually
/// lives, is untouched by any of this.
///
/// Only the directory is left to delete, and only when the path is
/// exactly `<repo>/.claude/worktrees/<name>`, git no longer lists it, and
/// the `.git` entry (or, where that entry cannot prove ownership, this
/// repo's own removal record) agrees it is ours; anything else refuses
/// rather than guesses. A still-registered worktree is not a leftover -
/// git may be holding uncommitted work in it, and `git worktree remove`
/// is the only path allowed to delete one.
///
/// **What the delete trusts, stated plainly:** it is unconditional on the
/// directory's contents, so the evidence must prove both halves - that the
/// directory is this repo's, and that a removal this repo admitted left it
/// behind. A `.git` link naming this repo's common git dir proves the
/// first while that git dir still exists, and that shape clears as it
/// always has (a leftover from an older forge carries no record). Once the
/// git dir is gone (the repo was moved) or there is no `.git` at all, the
/// link is a path shape that a moved or deleted foreign worktree can match
/// just as well, so the second half is the record
/// [`remove_owned_worktree`] writes under the git common dir before a
/// removal starts: it travels with the repo, `worktree prune` does not
/// touch it, and a foreign worktree's label is not in it. Where the link
/// cannot prove ownership, a leftover with no such record is refused - a
/// pruned live worktree after a move is one, and is kept - while one whose
/// link still names this repo's common dir clears, as it always has. The
/// blast radius when the record is wrong is uncommitted/untracked files in
/// a directory that is no longer a worktree; committed work lives on the
/// branch, which this never touches.
pub fn remove_orphaned_worktree_dir(repo: &Path, path: &Path) -> Result<(), WorktreeError> {
    let root = repo.join(".claude/worktrees");
    // The gate is lexical, not a real-path guarantee: `parent` and
    // `file_name` are compared as path components and nothing here
    // resolves symlinks, so a symlinked `.claude/worktrees` root would
    // aim the delete at that link's target - forge's own single-user
    // namespace. `file_name` is None for a path ending in `..`, which
    // would otherwise pass the parent test and aim the delete at
    // `.claude`.
    if path.parent() != Some(root.as_path()) || path.file_name().is_none() {
        return Err(WorktreeError::OutsideWorktreesRoot {
            path: path.display().to_string(),
            root: root.display().to_string(),
        });
    }
    // `symlink_metadata`, so a symlink at the path is refused rather
    // than followed.
    match std::fs::symlink_metadata(path) {
        Ok(meta) if meta.is_dir() => {}
        _ => return Err(WorktreeError::NotAPlainDirectory(path.display().to_string())),
    }
    if worktree_registered(repo, path) {
        return Err(WorktreeError::StillRegistered(path.display().to_string()));
    }
    if let Some(detail) = foreign_leftover_detail(repo, path) {
        return Err(WorktreeError::ForeignLeftover { path: path.display().to_string(), detail });
    }
    std::fs::remove_dir_all(path).map_err(|error| WorktreeError::LeftoverUndeletable {
        path: path.display().to_string(),
        error: error.to_string(),
    })?;
    if let Some(label) = path.file_name().and_then(std::ffi::OsStr::to_str) {
        record_worktree_state(repo, label, path, WorktreeRecord::Cleared);
    }
    Ok(())
}

/// Why the directory at `path` is not this repo's leftover, when its
/// `.git` entry says so - `None` when it is ours to delete.
///
/// A link naming a git dir that still exists is the evidence the guard has
/// always accepted: when that git dir is this repo's git COMMON dir - the
/// one `git rev-parse --git-common-dir` answers, so a project checked out
/// as a linked worktree or a submodule matches its own too - the directory
/// is this repo's, record or no record. A leftover from an older forge
/// therefore still clears.
///
/// A link whose git dir is GONE cannot prove ownership: the repo may have
/// been moved, but a moved or deleted FOREIGN worktree parked under our
/// root produces the same shape, and so does a live worktree of ours whose
/// registration was pruned. The same is true of no `.git` at all (a write
/// recreated the path after the walk). There the evidence is a removal
/// this repo ADMITTED, recorded by [`remove_owned_worktree`] in the git
/// common dir before git ran: it travels with the repo (`worktree prune`
/// does not touch it) and exists only for a removal this repo started and
/// never finished.
///
/// A `.git` DIRECTORY is a checkout of its own - a worktree's link is
/// always a file - and a `.git` that cannot be read as a link is refused
/// as well, so refusing is the safe direction wherever the evidence is not
/// ours. The link is READ, never resolved: a deregistration has already
/// removed the worktree admin dir it names.
fn foreign_leftover_detail(repo: &Path, path: &Path) -> Option<String> {
    match std::fs::symlink_metadata(path.join(".git")) {
        Ok(meta) if meta.is_dir() => {
            return Some(
                "its .git is a directory, so it is a checkout of its own, not a worktree this \
                 repo forked"
                    .to_owned(),
            );
        }
        // No `.git` at all: the recreated-path shape, ours when a removal
        // of this worktree was admitted and never completed. An empty
        // directory holds nothing to lose and the fresh-spawn obstacle
        // treats it as free, so the clear must too.
        Err(_) => {
            let empty = std::fs::read_dir(path).is_ok_and(|mut entries| entries.next().is_none());
            return (!empty && !worktree_removal_admitted(repo, path)).then(|| {
                "it holds no .git and this repo recorded no removal of it; remove the directory \
                 by hand if it is yours, then spawn again"
                    .to_owned()
            });
        }
        Ok(_) => {}
    }
    let Ok(link) = std::fs::read_to_string(path.join(".git")) else {
        return Some("its .git file could not be read".to_owned());
    };
    let Some(named) = link.trim().strip_prefix("gitdir:").map(str::trim) else {
        return Some("its .git file does not name a gitdir".to_owned());
    };
    let named = Path::new(named);
    let named = if named.is_absolute() { named.to_path_buf() } else { path.join(named) };
    if named.parent().and_then(Path::parent).is_some_and(Path::exists) {
        // A live git dir: ours or not, and nothing else to weigh.
        return live_foreign_git_dir(repo, path);
    }
    (!worktree_removal_admitted(repo, path)).then(|| {
        format!(
            "its .git link points at '{}', outside this repo's worktree admin dir, and this repo \
             recorded no removal of this worktree; remove the directory by hand if it is yours, \
             then spawn again",
            named.display()
        )
    })
}

/// Why the `.git` link at `path` names a LIVE git dir that is not this
/// repo's, when it does; `None` when it names this repo's common dir or
/// the git dir is gone. A stale or absent target is not proof of foreign
/// ownership on its own, so callers weigh it separately.
fn live_foreign_git_dir(repo: &Path, path: &Path) -> Option<String> {
    let link = std::fs::read_to_string(path.join(".git")).ok()?;
    let named = link.trim().strip_prefix("gitdir:").map(str::trim)?;
    let named = Path::new(named);
    let named = if named.is_absolute() { named.to_path_buf() } else { path.join(named) };
    let git_dir = named.parent().and_then(Path::parent)?;
    if !git_dir.exists() {
        return None;
    }
    // Canonicalised on both sides, because the spellings can disagree on a
    // symlinked prefix.
    let ours = matches!(
        (git_common_dir(repo), std::fs::canonicalize(git_dir).ok()),
        (Some(ours), Some(named)) if ours == named
    );
    (!ours).then(|| {
        format!(
            "its .git link points at '{}', outside this repo's worktree admin dir",
            named.display()
        )
    })
}

/// Where the worktree at `path` stands with git's registrations.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WorktreeRegistration {
    /// git lists it, and the listed path resolves to this directory.
    Live,
    /// git lists it by a path that no longer resolves, and the listing's
    /// tail still names this worktree - the shape a repo move leaves.
    Stale,
    /// git lists no registration for this path.
    Absent,
}

/// The registration [`worktree_registration`] finds, or `None` when git
/// could not be asked. The clear treats that as listed (the refusing
/// direction); ensure reuses the path as it stands.
fn worktree_registration(repo: &Path, path: &Path) -> Option<WorktreeRegistration> {
    // Canonicalised on both sides: the listed path and the caller's can
    // disagree on a symlinked prefix (`/tmp` vs `/private/tmp` on macOS)
    // while naming the same directory.
    let ours = std::fs::canonicalize(path).ok()?;
    let out = scrubbed_git(repo, &["worktree", "list", "--porcelain"]).output().ok()?;
    if !out.status.success() {
        return None;
    }
    let mut found = WorktreeRegistration::Absent;
    for listed in String::from_utf8_lossy(&out.stdout)
        .lines()
        .filter_map(|line| line.strip_prefix("worktree "))
    {
        let resolved = std::fs::canonicalize(listed);
        if resolved.as_ref().is_ok_and(|resolved| *resolved == ours) {
            return Some(WorktreeRegistration::Live);
        }
        // A listed path that resolves and names somewhere else is a
        // different worktree: `cp -a` keeps a link that still resolves at
        // the original path, so the stale fallback must not run on a path
        // that resolves at all.
        if resolved.is_err() && moved_registration_names(listed, &ours) {
            found = WorktreeRegistration::Stale;
        }
    }
    Some(found)
}

/// Whether git still lists `path` as one of `repo`'s worktrees, live or
/// stale. A repo git cannot read answers `true`, the refusing direction.
fn worktree_registered(repo: &Path, path: &Path) -> bool {
    !matches!(worktree_registration(repo, path), Some(WorktreeRegistration::Absent))
}

/// Whether a listed worktree path that no longer resolves still names the
/// worktree at `ours`. A repo moved or renamed leaves its registrations
/// carrying the old absolute path, while the tail below the repo root -
/// `.claude/worktrees/<label>` - is intact. The listing is this repo's
/// own, so a matching tail is this repo's registration, not a foreign
/// one.
fn moved_registration_names(listed: &str, ours: &Path) -> bool {
    let Some(label) = ours.file_name() else {
        return false;
    };
    Path::new(listed).ends_with(Path::new(".claude").join("worktrees").join(label))
}

/// `git worktree repair <path>`: git's own remedy for a registration and
/// link that name the path the repo has left. Only a stale registration
/// needs it; reusing one unrepaired leaves every git command in the
/// worktree failing.
fn repair_worktree(repo: &Path, path: &Path) -> Result<(), WorktreeError> {
    let output =
        scrubbed_git(repo, &["worktree", "repair"]).arg(path).output().map_err(|error| {
            WorktreeError::RegistrationUnusable {
                path: path.display().to_string(),
                detail: format!("git worktree repair could not be spawned: {error}"),
            }
        })?;
    if output.status.success() {
        Ok(())
    } else {
        Err(WorktreeError::RegistrationUnusable {
            path: path.display().to_string(),
            detail: format!(
                "git worktree repair failed: {}",
                String::from_utf8_lossy(&output.stderr).trim()
            ),
        })
    }
}

/// What forge recorded about a worktree it owns, in the repo's git common
/// dir so the record moves with the repo.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WorktreeRecord {
    /// forge created the worktree and has not started removing it.
    Owned,
    /// A removal this repo admitted started and never reported completion.
    Removing,
    /// The removal completed; there is nothing left to clear.
    Cleared,
}

impl WorktreeRecord {
    fn as_str(self) -> &'static str {
        match self {
            Self::Owned => "owned",
            Self::Removing => "removing",
            Self::Cleared => "cleared",
        }
    }
}

const WORKTREE_RECORDS: &str = "forge-worktrees";

/// The repo's git common dir, resolved and canonicalised. A project
/// checked out as a linked worktree or a submodule answers with the dir
/// its gitdir lives under, not `<repo>/.git`.
fn git_common_dir(repo: &Path) -> Option<std::path::PathBuf> {
    let raw = git_in_repo(repo, &["rev-parse", "--git-common-dir"])?;
    let raw = raw.trim();
    if raw.is_empty() {
        return None;
    }
    let dir = Path::new(raw);
    let dir = if dir.is_absolute() { dir.to_path_buf() } else { repo.join(dir) };
    std::fs::canonicalize(dir).ok()
}

fn worktree_record_path(repo: &Path) -> Option<std::path::PathBuf> {
    git_common_dir(repo).map(|dir| dir.join(WORKTREE_RECORDS))
}

/// Append one state for `label` in this checkout. Append-only with last
/// line winning: a rewrite would race another spawn's record in the same
/// process, and the file is a handful of bytes per worker lifecycle. The
/// checkout root is stored with the path because the common dir can be
/// shared by several checkouts.
fn record_worktree_state(repo: &Path, label: &str, path: &Path, state: WorktreeRecord) {
    let Some(file) = worktree_record_path(repo) else {
        tracing::warn!(
            target: "forge_agent::env::worktree",
            event_name = "worktree_record_unavailable",
            repo = %repo.display(),
            label = %label,
            "the repo's git common dir could not be read, so this worktree's ownership is not \
             recorded and a leftover it leaves may be refused rather than cleared",
        );
        return;
    };
    let line = format!("{}\t{label}\t{}\t{}\n", state.as_str(), repo.display(), path.display());
    let written = std::fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(&file)
        .and_then(|mut file| file.write_all(line.as_bytes()));
    if let Err(err) = written {
        tracing::warn!(
            target: "forge_agent::env::worktree",
            event_name = "worktree_record_unwritable",
            repo = %repo.display(),
            label = %label,
            record = %file.display(),
            %err,
            "this worktree's ownership could not be recorded, so a leftover it leaves may be \
             refused rather than cleared",
        );
    }
}

/// One record, as [`recorded_worktree`] reads it.
struct RecordedWorktree {
    state: WorktreeRecord,
    /// The checkout root the record was written from.
    root: std::path::PathBuf,
    /// The worktree path as it stood when the state was written.
    path: std::path::PathBuf,
}

/// The record that speaks for the worktree at `path`, when one can be
/// read.
///
/// The file lives in the git common dir, which a project that is itself a
/// linked worktree SHARES with the main checkout, so neither a label nor a
/// path alone identifies a worktree across projects. A record whose path
/// still exists speaks for this worktree only when it resolves to it; a
/// record whose path is gone is the one a repo move left behind, and it
/// speaks only for a checkout root that is also gone - a live root that
/// differs is another checkout's. A matching live path is preferred over
/// a stale one, so another checkout's `cleared` cannot retract this
/// checkout's still-standing admission.
fn recorded_worktree(repo: &Path, path: &Path) -> Option<RecordedWorktree> {
    let label = path.file_name().and_then(std::ffi::OsStr::to_str)?;
    let text = std::fs::read_to_string(worktree_record_path(repo)?).ok()?;
    let mut live = None;
    let mut stale = None;
    for line in text.lines() {
        let mut fields = line.splitn(4, '\t');
        let Some(recorded_state) = fields.next().and_then(|field| match field {
            "owned" => Some(WorktreeRecord::Owned),
            "removing" => Some(WorktreeRecord::Removing),
            "cleared" => Some(WorktreeRecord::Cleared),
            _ => None,
        }) else {
            continue;
        };
        if fields.next() != Some(label) {
            continue;
        }
        let Some(recorded_root) = fields.next() else {
            continue;
        };
        let Some(recorded_path) = fields.next() else {
            continue;
        };
        let recorded = RecordedWorktree {
            state: recorded_state,
            root: std::path::PathBuf::from(recorded_root),
            path: std::path::PathBuf::from(recorded_path),
        };
        if recorded.path.exists() {
            if recorded_names(&recorded.path, path) {
                live = Some(recorded);
            }
        } else if recorded_root_is_ours(&recorded.root, repo) {
            stale = Some(recorded);
        }
    }
    live.or(stale)
}

/// Whether a record written by the checkout at `recorded` can speak for
/// `repo`: a root that no longer exists is the one a repo move left,
/// while a live root must be this checkout.
fn recorded_root_is_ours(recorded: &Path, repo: &Path) -> bool {
    if !recorded.exists() {
        return true;
    }
    matches!(
        (std::fs::canonicalize(recorded), std::fs::canonicalize(repo)),
        (Ok(recorded), Ok(repo)) if recorded == repo
    )
}

/// Whether a recorded path that still exists names the worktree at
/// `current`.
fn recorded_names(recorded: &Path, current: &Path) -> bool {
    matches!(
        (std::fs::canonicalize(recorded), std::fs::canonicalize(current)),
        (Ok(recorded), Ok(current)) if recorded == current
    )
}

/// Whether an admitted removal is on record for this worktree and never
/// reported complete. Where the link cannot prove ownership, this record
/// is what the orphan clear deletes on; a live link naming this repo's
/// common dir clears without it.
fn worktree_removal_admitted(repo: &Path, path: &Path) -> bool {
    recorded_worktree(repo, path).is_some_and(|record| record.state == WorktreeRecord::Removing)
}

/// Record that forge created the worktree at `path`.
fn record_worktree_owned(repo: &Path, label: &str, path: &Path) {
    record_worktree_state(repo, label, path, WorktreeRecord::Owned);
}

/// Record that the worktree at `path` is gone. Retracts any earlier
/// admission for the label, so a directory that later takes its place is
/// not cleared on it.
pub fn record_worktree_gone(repo: &Path, label: &str, path: &Path) {
    record_worktree_state(repo, label, path, WorktreeRecord::Cleared);
}

/// Remove a worktree whose removal this repo admitted - a despawn, or a
/// refused spawn's rollback - recording the admission before git runs.
/// A removal that dies part-way leaves the record behind, which is what
/// lets [`remove_orphaned_worktree_dir`] prove the leftover is ours after
/// a repo move; a completed removal clears it.
///
/// A path that is already gone admits nothing: a `removing` record for it
/// would outlive the directory it described and could later authorize
/// deleting a new worktree that reused the label, so `cleared` is written
/// instead.
pub fn remove_owned_worktree(
    repo: &Path,
    label: &str,
    path: &Path,
    force: bool,
) -> Result<(), WorktreeError> {
    let admission = if path.is_dir() { WorktreeRecord::Removing } else { WorktreeRecord::Cleared };
    record_worktree_state(repo, label, path, admission);
    let outcome = remove_worktree(path, force);
    if outcome.is_ok() {
        record_worktree_state(repo, label, path, WorktreeRecord::Cleared);
    }
    outcome
}

/// What [`ensure_worker_worktree`] had to do, so a caller rolling back
/// a refused spawn knows what it may delete: the worktree only when it
/// was absent, the branch only when this call minted it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorktreeEnsure {
    /// `path` already stood and was reused; a stale registration was
    /// repaired first when the repo had been moved.
    AlreadyPresent,
    /// `path` was created and an existing `worktree-<label>` branch was
    /// attached to it. The branch predates the call and may hold the
    /// worker's only copy of its commits.
    AttachedExistingBranch,
    /// `path` was created and `worktree-<label>` was minted at claude's
    /// fresh base: `origin/<default-branch>`, or the local HEAD when the
    /// repo names no usable origin base.
    CreatedWithNewBranch,
}

/// Recreate the worker worktree at `path` when a despawn removed it, so
/// a resumed worker can run with its worktree as cwd again - the
/// transcript lives under the worktree's storage key, so `claude
/// --resume` cannot find it from any other directory. Anchored on the
/// branch: attach the surviving `worktree-<label>` when despawn kept
/// it, otherwise recreate the branch from `origin/<default-branch>` - the
/// base claude's own `--worktree <label>` uses under its default
/// `worktree.baseRef` of `fresh`.
///
/// **`worktree.baseRef = "head"` is not honoured.** forge always cuts from
/// the origin base and falls back to the local HEAD only when the repo names
/// no `origin/HEAD`, or names one that no longer resolves.
///
/// A `path` that exists is judged by its REGISTRATION, not its presence:
/// a worktree git still lists is reused, while a leftover directory git
/// no longer tracks - a despawn's removal failed part-way, and git
/// deregisters a path before it walks the tree - is cleared deliberately
/// before the add below, because `worktree add` refuses a path that
/// exists and a resume that died on git's refusal surfaced as the
/// transport's message rather than git's (#1767). An out-of-band delete
/// still defeats this (git's stale registration makes `worktree add`
/// fail with git's message, surfaced here).
///
/// A registration git lists by the path the repo has left (a move) is
/// repaired with `git worktree repair` before it is reused: without that,
/// `AlreadyPresent` would hand the resume a directory where every git
/// command exits 128. A repair git refuses is a refusal here.
///
/// **What the clearing trusts, stated plainly:** that this state is the
/// tail of a removal the despawn admitted (its dirty verdict, or an
/// explicit force) - nothing in this call re-reads the tree. The record
/// [`remove_owned_worktree`] wrote before that removal is what proves it
/// where the link cannot, so a pruned live worktree after a move is
/// refused and kept. Committed work lives on the branch, which is never
/// touched here; what could be lost if the record were wrong is
/// uncommitted/untracked files in a directory that is no longer a
/// worktree.
pub fn ensure_worker_worktree(
    repo: &Path,
    label: &str,
    path: &Path,
) -> Result<WorktreeEnsure, WorktreeError> {
    if path.exists() {
        match worktree_registration(repo, path) {
            Some(WorktreeRegistration::Absent) => remove_orphaned_worktree_dir(repo, path)?,
            Some(WorktreeRegistration::Stale) => {
                // `git worktree repair` rewrites the directory's `.git`
                // link, so a live foreign link here is refused rather
                // than adopted.
                if let Some(detail) = live_foreign_git_dir(repo, path) {
                    return Err(WorktreeError::RegistrationUnusable {
                        path: path.display().to_string(),
                        detail: format!("{detail}; git worktree repair would adopt it"),
                    });
                }
                repair_worktree(repo, path)?;
                record_worktree_owned(repo, label, path);
                return Ok(WorktreeEnsure::AlreadyPresent);
            }
            // A live registration retracts any stale admission: a removal
            // that reported failure over a worktree still alive and
            // registered must not authorize deleting it later.
            Some(WorktreeRegistration::Live) => {
                record_worktree_owned(repo, label, path);
                return Ok(WorktreeEnsure::AlreadyPresent);
            }
            // git could not be asked: reuse as it stands.
            None => return Ok(WorktreeEnsure::AlreadyPresent),
        }
    }
    let branch = format!("worktree-{label}");
    let mut cmd = git_command::command("git");
    cmd.arg("worktree").arg("add").arg("-q");
    let outcome = if branch_ref_exists(repo, &branch) {
        cmd.arg(path).arg(&branch);
        WorktreeEnsure::AttachedExistingBranch
    } else {
        // **The base claude's own `--worktree` uses.** Its
        // `worktree.baseRef` defaults to `fresh`, which cuts from
        // `origin/<default-branch>`; a resume that recreates the branch at
        // the local HEAD starts the worker from a commit its launcher would
        // not have chosen whenever HEAD is ahead (#1594). A repo that names
        // no remote default has no origin base and keeps the local HEAD.
        cmd.arg("-b").arg(&branch).arg(path);
        if let Some(base) = origin_base(repo) {
            cmd.arg(base);
        }
        WorktreeEnsure::CreatedWithNewBranch
    };
    cmd.current_dir(repo);
    let output = cmd.output().map_err(|e| WorktreeError::GitSpawn(e.to_string()))?;
    if output.status.success() {
        record_worktree_owned(repo, label, path);
        Ok(outcome)
    } else {
        Err(WorktreeError::CreateFailed(git_error(&output)))
    }
}

/// Undo the work [`ensure_worker_worktree`] did for a spawn that was
/// then refused, so the refusal strands neither worktree nor branch.
/// The worktree goes only when ensure created it, the branch only when
/// ensure minted it - an `AttachedExistingBranch` keeps the branch,
/// which predates the call and may hold the worker's only copy of its
/// commits. Returns git's complaint when something had to stay behind;
/// the spawn is already refused, so a failure is a warning, not an
/// error.
pub fn discard_worker_worktree(
    repo: &Path,
    label: &str,
    path: &Path,
    ensured: WorktreeEnsure,
) -> Option<String> {
    if matches!(ensured, WorktreeEnsure::AlreadyPresent) {
        return None;
    }
    if let Err(err) = remove_owned_worktree(repo, label, path, true) {
        return Some(err.to_string());
    }
    if !matches!(ensured, WorktreeEnsure::CreatedWithNewBranch) {
        return None;
    }
    let branch = format!("worktree-{label}");
    match reap_worktree_branch(repo, &branch) {
        BranchReapOutcome::Reaped | BranchReapOutcome::NotPresent => None,
        other => Some(format!("branch '{branch}' left behind: {other:?}")),
    }
}

/// What git refuses to create a worker's worktree for at `path`, when there
/// is something: the `worktree-<label>` branch already checked out in
/// another worktree, a path taken by something that is not this worktree,
/// or a registration git will not reuse.
///
/// The worktree is claude's to create - it is handed `--worktree <label>` -
/// and a creation that does nothing still leaves the session started, so a
/// worker can read live with nowhere to work. Asking git the question that
/// creation asks lets the caller refuse that spawn instead, and leaves who
/// creates the worktree unchanged.
///
/// `None` when git cannot be asked: this exists to catch a silent failure,
/// not to block a spawn on a probe that never answered.
///
/// The label is taken raw, the way forge's worktree paths take it
/// everywhere else. claude sanitises the name before deriving the path and
/// the branch, so a label carrying `/` is a divergence that predates this
/// check rather than one it widens.
pub fn worktree_creation_obstacle(repo: &Path, label: &str, path: &Path) -> Option<String> {
    let branch = format!("worktree-{label}");
    let mut command = git_command::command("git");
    command.arg("-C").arg(repo).args(["worktree", "list", "--porcelain"]);
    // Both ways of failing to ask git leave nothing else to tell the two
    // apart from a repo with no obstacle, and that is the one branch where
    // this check silently does nothing.
    let output = match command.output() {
        Ok(output) => output,
        Err(err) => {
            tracing::warn!(
                target: "forge_agent::env::worktree",
                event_name = "worktree_obstacle_unavailable",
                repo = %repo.display(),
                label = %label,
                %err,
                "git could not be asked whether this worker's worktree can be created, so this \
                 spawn is not refused here and may start without a worktree",
            );
            return None;
        }
    };
    if !output.status.success() {
        tracing::warn!(
            target: "forge_agent::env::worktree",
            event_name = "worktree_obstacle_unreadable",
            repo = %repo.display(),
            label = %label,
            status = %output.status,
            stderr = %String::from_utf8_lossy(&output.stderr).trim(),
            "git would not list this repo's worktrees, so this spawn is not refused here and \
             may start without a worktree",
        );
        return None;
    }

    let listing = String::from_utf8_lossy(&output.stdout);
    obstacle_from_listing(&listed_worktrees(&listing), repo, &branch, path)
}

/// One `git worktree list --porcelain` entry.
struct ListedWorktree {
    /// The path git printed, already canonical while it exists.
    at: String,
    /// The ref this worktree holds, when it holds a branch.
    branch: Option<String>,
}

/// The entries of a porcelain listing: one block each, a `worktree <path>`
/// header followed by the `branch` line when the entry holds one.
fn listed_worktrees(listing: &str) -> Vec<ListedWorktree> {
    let mut entries: Vec<ListedWorktree> = Vec::new();
    for line in listing.lines() {
        if let Some(at) = line.strip_prefix("worktree ") {
            entries.push(ListedWorktree { at: at.to_owned(), branch: None });
        } else if let Some(found) = line.strip_prefix("branch ")
            && let Some(entry) = entries.last_mut()
        {
            entry.branch = Some(found.to_owned());
        }
    }
    entries
}

/// The obstacle the listing describes: the branch held at another path, or
/// what git has registered at `path` and will not reuse.
///
/// The second decision reads the worktree's own gitdir LINK, not git's
/// `prunable` line: a LOCKED entry carries no such line on any git version
/// (and claude locks every worktree it creates), while a git older than
/// 2.36 carries none for anything - so the line cannot tell a registration
/// whose gitdir is gone from one whose gitdir is there, which is the half
/// the link answers. [`worktree_gitdir_resolves`] then asks whether that
/// gitdir is one git can actually reuse, so a present-but-unusable
/// registration is refused here rather than left for the add.
fn obstacle_from_listing(
    entries: &[ListedWorktree],
    repo: &Path,
    branch: &str,
    path: &Path,
) -> Option<String> {
    let wanted = format!("refs/heads/{branch}");
    if let Some(at) = entries.iter().find(|e| e.branch.as_deref() == Some(&wanted)).map(|e| &e.at)
        && !same_path(at, path)
    {
        return Some(format!(
            "the branch '{branch}' is already checked out in the worktree at {at}, so this \
             worker's worktree cannot be created; remove that worktree, or spawn under a \
             different label"
        ));
    }
    match entries.iter().find(|e| same_path(&e.at, path)) {
        // There, and usable: the worktree is reused as it stands. A locked
        // one included - claude locks every worktree it creates.
        Some(_) if worktree_gitdir_resolves(path) => None,
        Some(_) => Some(format!(
            "the worktree registration at {} cannot be reused - its .git link is not the plain \
             file git writes, the gitdir it names is gone or belongs to another repository, or \
             its HEAD does not resolve - so this worker's worktree cannot be created there; \
             unlock it with `git worktree unlock {}` (which errors harmlessly when it is not \
             locked), delete that directory if it is still there, then `git worktree prune` in \
             {} and spawn again",
            path.display(),
            path.display(),
            repo.display(),
        )),
        None if path_is_taken(path) => Some(format!(
            "{} already exists and is not an empty directory, so this worker's worktree cannot \
             be created there; remove it, or spawn under a different label",
            path.display()
        )),
        None => None,
    }
}

/// Whether the worktree registered at `path` still points at a gitdir git
/// can reuse.
///
/// git reads several facts when it decides to reuse or refuse a worktree, so
/// the link alone is not the question: the `.git` entry must be the plain
/// link file git writes (not a symlink standing in for one), the gitdir it
/// names must be there, that gitdir's own `gitdir` back-link must name THIS
/// worktree's `.git` entry, and its HEAD must resolve. Each of those states
/// is one git's own reuse probe returns null for, and the add then refuses -
/// the silent failure this check exists to catch (#1593).
fn worktree_gitdir_resolves(path: &Path) -> bool {
    let Ok(link_meta) = std::fs::symlink_metadata(path.join(".git")) else {
        return false;
    };
    if !link_meta.is_file() {
        return false;
    }
    let Ok(link) = std::fs::read_to_string(path.join(".git")) else {
        return false;
    };
    let Some(gitdir) = link.trim().strip_prefix("gitdir:") else {
        return false;
    };
    let gitdir = Path::new(gitdir.trim());
    let gitdir = if gitdir.is_absolute() { gitdir.to_path_buf() } else { path.join(gitdir) };
    if !gitdir.is_dir() {
        return false;
    }
    let Ok(back) = std::fs::read_to_string(gitdir.join("gitdir")) else {
        return false;
    };
    let back = Path::new(back.trim());
    let back = if back.is_absolute() { back.to_path_buf() } else { gitdir.join(back) };
    // git writes the back link as the worktree's `.git` entry itself, so
    // that file is what must canonicalize to this worktree's.
    let (Ok(back), Ok(here)) =
        (std::fs::canonicalize(back), std::fs::canonicalize(path.join(".git")))
    else {
        return false;
    };
    if back != here {
        return false;
    }
    git_command::command("git")
        .arg("--git-dir")
        .arg(&gitdir)
        .args(["rev-parse", "--verify", "--quiet", "HEAD"])
        .output()
        .is_ok_and(|out| out.status.success())
}

/// Why the worktree a git worker's spawn put it in is not usable, or `None`
/// when it is there and git can read it.
///
/// The spawn-time check runs before creation; this is the read after it. A
/// tree that went away before the session connected otherwise leaves the
/// worker reading live with nowhere to work (#1593).
pub fn worktree_missing_reason(path: &Path) -> Option<String> {
    if !path.is_dir() {
        return Some(format!("its worktree {} is gone", path.display()));
    }
    if !worktree_gitdir_resolves(path) {
        return Some(format!(
            "its worktree {} is not a git worktree git can reuse",
            path.display()
        ));
    }
    None
}

/// Whether something at `path` is in the way of `git worktree add`, which
/// takes a path that is absent or an empty directory and refuses anything
/// else: a file, and any directory holding an entry, both exit 128
/// ("already exists"). A dotfile counts as an entry - measured.
fn path_is_taken(path: &Path) -> bool {
    match std::fs::read_dir(path) {
        Ok(mut entries) => entries.next().is_some(),
        // Not a directory at all, or one that cannot be read: git takes
        // neither. `exists` separates those from a free path EXCEPT for a
        // broken symlink, which it follows to nothing - the link itself is
        // what git refuses, so `symlink_metadata` is asked too.
        Err(_) => path.exists() || path.symlink_metadata().is_ok(),
    }
}

/// Whether a path git printed and a path forge composed name the same
/// directory. Each side canonicalizes through its parent with the name
/// re-attached, so a symlinked spelling of a repo root (a macOS tempdir
/// under `/private`, a linked checkout) cannot read as a different
/// worktree. That matters most for a path that is gone, which is exactly
/// where a stranded registration lives and nothing exists to canonicalize.
fn same_path(listed: &str, composed: &Path) -> bool {
    let listed = Path::new(listed);
    match (spelled_from_parent(listed), spelled_from_parent(composed)) {
        (Some(listed), Some(composed)) => listed == composed,
        _ => listed == composed,
    }
}

/// `path` with its parent canonicalized and its own name re-attached: the
/// spelling a path keeps once it exists, for one that does not.
fn spelled_from_parent(path: &Path) -> Option<std::path::PathBuf> {
    let parent = std::fs::canonicalize(path.parent()?).ok()?;
    Some(parent.join(path.file_name()?))
}

/// Outcome of [`reap_worktree_branch`]. `Kept`, `KeptOnError` and
/// `DeleteFailed` each leave a branch behind and the caller warns
/// differently for each; `NotPresent` warns about nothing.
#[derive(Debug, PartialEq, Eq)]
pub enum BranchReapOutcome {
    /// Deleted. No commit became unreachable.
    Reaped,
    /// No branch by that name, so nothing to do.
    NotPresent,
    /// `count` commits are reachable from this branch and nothing else, so
    /// deleting it would strand them. `tip` is the short sha.
    Kept { count: u64, tip: String },
    /// The check could not be completed, so whether the branch holds
    /// unique commits is unknown.
    KeptOnError { reason: String },
    /// The check passed and only the delete failed.
    DeleteFailed { reason: String },
}

/// Delete `branch` from the repo at `repo` if no commit would become
/// unreachable, i.e. every commit reachable from it is also reachable
/// from another ref or from a worktree's HEAD.
///
/// Asks about reachability, never merged-ness: nothing here consults
/// whether the branch landed, so a squash merge cannot mislead it. Any
/// failure keeps the branch.
pub fn reap_worktree_branch(repo: &Path, branch: &str) -> BranchReapOutcome {
    let refname = format!("refs/heads/{branch}");

    // Existence plus the tip in one call. `--quiet` exits 1 for a ref that
    // is missing or broken and 128 for a repo it cannot read, so "no such
    // branch" never absorbs "no such repo".
    let tip = match git_command::command("git")
        .args(["rev-parse", "--short", "--verify", "--quiet", &refname])
        .current_dir(repo)
        .output()
    {
        Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).trim().to_owned(),
        Ok(out) if out.status.code() == Some(1) => return BranchReapOutcome::NotPresent,
        Ok(out) => return BranchReapOutcome::KeptOnError { reason: git_error(&out) },
        Err(err) => return BranchReapOutcome::KeptOnError { reason: err.to_string() },
    };

    // `--exclude` filters what the NEXT `--all` considers, so it has to
    // precede it; placed after, git ignores it and every branch reads as
    // holding nothing.
    let exclude = format!("--exclude={refname}");
    let count = match git_command::command("git")
        .args(["rev-list", "--count", &refname, "--not", &exclude, "--all"])
        .current_dir(repo)
        .output()
    {
        Ok(out) if out.status.success() => {
            match String::from_utf8_lossy(&out.stdout).trim().parse::<u64>() {
                Ok(count) => count,
                Err(err) => {
                    return BranchReapOutcome::KeptOnError {
                        reason: format!("unreadable commit count: {err}"),
                    };
                }
            }
        }
        Ok(out) => return BranchReapOutcome::KeptOnError { reason: git_error(&out) },
        Err(err) => return BranchReapOutcome::KeptOnError { reason: err.to_string() },
    };
    if count > 0 {
        return BranchReapOutcome::Kept { count, tip };
    }

    // `-D`, not `-d`: the count above IS the safety decision. `-d` would
    // re-derive merged-ness from history shape and refuses a pristine
    // branch whenever HEAD predates the commit it was created from.
    match git_command::command("git").args(["branch", "-D", branch]).current_dir(repo).output() {
        Ok(out) if out.status.success() => BranchReapOutcome::Reaped,
        Ok(out) => BranchReapOutcome::DeleteFailed { reason: git_error(&out) },
        Err(err) => BranchReapOutcome::DeleteFailed { reason: err.to_string() },
    }
}

/// Whether `branch` resolves at `repo`, as a local head or as any
/// remote-tracking ref. A repo git cannot read answers `true`, so a
/// caller cleaning up on absence never discards state it failed to
/// inspect.
///
/// Membership in [`repo_branch_names`] rather than a targeted
/// `for-each-ref` pattern, so both callers share one parser. A pattern
/// cannot answer this safely on a delete path: `refs/remotes/*/<branch>`
/// has a `*` that does not cross `/`, so a remote named `gh/upstream`
/// puts its refs where the pattern cannot see them, and `a[b`, a leading
/// `-` or a space match nothing. Every one of those exits 0 with empty
/// stdout, and empty is what triggers the delete.
///
/// Remote-tracking refs count because [`reap_worktree_branch`] deletes a
/// local head whose commits are reachable from one, and a branch that
/// survives on a remote is still open for review.
pub fn branch_ref_exists(repo: &Path, branch: &str) -> bool {
    repo_branch_names(repo).is_none_or(|repo| repo.names.contains(branch))
}

/// The ref claude's `--worktree` cuts a fresh branch from:
/// `origin/<default-branch>` as the repo's `origin/HEAD` names it.
///
/// `None` when the repo names no remote default, or when the symref names a
/// ref the remote no longer carries: a start point git cannot resolve would
/// refuse the whole resume, so the caller falls back to the local HEAD.
fn origin_base(repo: &Path) -> Option<String> {
    let name = git_in_repo(repo, &["symbolic-ref", "--short", "refs/remotes/origin/HEAD"])?
        .trim()
        .to_owned();
    if name.is_empty() {
        return None;
    }
    git_in_repo(repo, &["rev-parse", "--verify", "--quiet", &name]).map(|_| name)
}

/// Run `git -C repo <args>` with the ambient repo-location env scrubbed,
/// returning stdout on exit 0.
///
/// `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` override `-C` outright,
/// so without the scrub a forge launched from a git hook, a `git rebase
/// --exec`, or any shell that exported them answers every question about
/// every repo from one foreign repo - at exit 0, with nothing in the
/// output to say so.
fn git_in_repo(repo: &Path, args: &[&str]) -> Option<String> {
    let out = scrubbed_git(repo, args).output().ok()?;
    out.status.success().then(|| String::from_utf8_lossy(&out.stdout).into_owned())
}

/// The command [`git_in_repo`] runs, built separately so a test can
/// assert the scrub is on it.
fn scrubbed_git(repo: &Path, args: &[&str]) -> Command {
    let mut command = git_command::command("git");
    command.arg("-C").arg(repo).args(args);
    command
}

/// What a repo knows about its branches, in two quantities that must not
/// be confused for each other.
///
/// [`Self::names`] deliberately over-includes and [`Self::ref_count`] is
/// exact. A caller sparing on membership wants the first; a caller
/// judging whether the repo can be trusted to answer wants the second.
/// They were one value once, and the over-inclusion silently inflated
/// the population: each slash in a branch name adds a phantom suffix, so
/// `release/2.0/rc1` reads as three names against two refs and a shallow
/// clone looks well-stocked. One slash does not show it - two names, two
/// refs.
pub struct RepoBranches {
    /// Every name a stored branch might legitimately match. Includes
    /// every `/`-suffix of a remote-tracking ref's tail, so it can only
    /// spare a branch, never condemn one - which is why nothing is
    /// dropped from it on a name test. NOT a population.
    pub names: std::collections::HashSet<String>,
    /// Branch refs the repo actually holds - local heads plus
    /// remote-tracking refs, excluding symrefs, which point at another
    /// ref in the same listing rather than being branches of their own.
    /// Independent of how any branch is named, which is the whole point:
    /// a count derived from names moves when a branch is renamed.
    pub ref_count: usize,
}

/// Every branch name the repo rooted exactly at `repo` knows, plus how
/// many branch refs it actually holds. `None` when `repo` is not itself
/// a work-tree root or git could not be asked.
///
/// One listing, then exact string membership. That is the difference
/// between this and asking [`branch_ref_exists`] per branch: a
/// `for-each-ref` *pattern* matches path prefixes, so a stored `fix`
/// matches `fix/anything`, an empty name matches every head, and a name
/// carrying `[`, a leading `-` or a space matches nothing and exits 0 -
/// indistinguishable from a branch that is genuinely gone. A caller that
/// deletes on absence cannot tell those apart; a set cannot produce them.
///
/// A remote-tracking ref is `refs/remotes/<remote>/<branch>`, and
/// `<remote>` may itself contain slashes - `git remote add gh/upstream`
/// is accepted - so where one segment ends and the other begins is not
/// recoverable from the refname. Every `/`-suffix of the tail joins
/// `names` rather than guessing: `gh/upstream/feat/pushed` contributes
/// `upstream/feat/pushed`, `feat/pushed` and `pushed`. That can only add
/// names, so its failure is to spare a branch whose name happens to be a
/// suffix of another ref's path - never to delete a live one, which
/// splitting once does. `ref_count` counts refs and is untouched by it.
///
/// The `--show-toplevel` equality check is what keeps discovery from
/// walking up: git answers happily from an ancestor repo when `repo` is
/// merely nested inside one. It is only meaningful because the helper
/// above scrubs the env first - with `GIT_DIR` set, `--show-toplevel`
/// reports the working directory and the check passes while the refs
/// come from elsewhere.
pub fn repo_branch_names(repo: &Path) -> Option<RepoBranches> {
    let toplevel = git_in_repo(repo, &["rev-parse", "--show-toplevel"])?;
    let toplevel = std::fs::canonicalize(toplevel.trim()).ok()?;
    if toplevel != std::fs::canonicalize(repo).ok()? {
        return None;
    }
    let listing = git_in_repo(
        repo,
        &["for-each-ref", "--format=%(refname) %(symref)", "refs/heads", "refs/remotes"],
    )?;
    let mut names = std::collections::HashSet::new();
    let mut ref_count = 0;
    for line in listing.lines() {
        // A ref name cannot contain a space, so the first one separates
        // it from `%(symref)`, which is empty for everything but a symref.
        let (refname, symref) = line.split_once(' ').unwrap_or((line, ""));
        // `origin/HEAD` points at another ref in this same listing, so
        // counting it would make every clone look one branch richer and
        // its target's name is already here. Tested by symref rather than
        // by the name: `release/HEAD` is a legal branch, and skipping it
        // on the name would drop a real branch out of `names` - which
        // deletes it.
        if !symref.trim().is_empty() {
            continue;
        }
        if let Some(head) = refname.strip_prefix("refs/heads/") {
            ref_count += 1;
            names.insert(head.to_owned());
        } else if let Some(tail) = refname.strip_prefix("refs/remotes/") {
            ref_count += 1;
            let mut rest = tail;
            while let Some((_, suffix)) = rest.split_once('/') {
                names.insert(suffix.to_owned());
                rest = suffix;
            }
        }
    }
    names.remove("");
    Some(RepoBranches { names, ref_count })
}

/// git's stderr, or its exit status when it said nothing.
fn git_error(out: &std::process::Output) -> String {
    let stderr = String::from_utf8_lossy(&out.stderr).trim().to_owned();
    if stderr.is_empty() { out.status.to_string() } else { stderr }
}

/// A completed `isolation: "worktree"` subagent's managed worktree, as
/// the Agent tool reports it on completion. Produced only by
/// [`completed_agent_worktree`], which vouches for every field.
#[derive(Debug)]
pub struct AgentWorktree {
    /// The worktree directory, `<repo>/.claude/worktrees/agent-<hex>`.
    pub path: std::path::PathBuf,
    /// The repo the worktree was cut from; where branch reaping runs.
    pub repo_root: std::path::PathBuf,
    /// The CLI's conventional branch (`worktree-<slug>`), from the tool
    /// response or derived from the directory name.
    pub branch: String,
}

/// Outcome of [`reap_agent_worktree`].
#[derive(Debug)]
pub enum AgentWorktreeReap {
    /// Removed. Carries the conventional branch's reap outcome.
    Reaped { branch: BranchReapOutcome },
    /// Uncommitted or untracked changes: the CLI hands a changed tree
    /// back to the caller deliberately, so the reap refuses too.
    KeptDirty { reason: String },
    /// Detached HEAD holding commits reachable from no ref: removal
    /// would strand them, because the post-removal branch reap sees refs
    /// only and never a linked worktree's HEAD. `tip` is the full sha.
    KeptUniqueCommit { tip: String },
    /// Already gone - the CLI's own auto-clean, or an earlier reap.
    Absent,
    /// Git does not vouch for the path being a worktree.
    NotAWorktree,
    /// `git worktree remove` failed; the directory survives.
    RemoveFailed { reason: String },
}

/// Whether this hook payload names an isolation:"worktree" Agent call -
/// the population whose completion either names a managed worktree or
/// proves the CLI's tool-response contract drifted.
pub fn is_isolated_agent_call(tool_name: &str, tool_input: &serde_json::Value) -> bool {
    (tool_name == "Agent" || tool_name == "Task")
        && tool_input.get("isolation").and_then(serde_json::Value::as_str) == Some("worktree")
}

/// The agent worktree a completed Agent-tool call left behind, from the
/// PostToolUse hook payload.
///
/// Gated four ways because the answer aims a deletion: only the Agent
/// tool (either spelling), only calls that ran with
/// `isolation: "worktree"`, only a structured `worktreePath` field, and
/// only paths with the CLI's managed layout
/// `<repo>/.claude/worktrees/agent-<...>`. `None` when any gate fails.
pub fn completed_agent_worktree(
    tool_name: &str,
    tool_input: &serde_json::Value,
    tool_response: &serde_json::Value,
) -> Option<AgentWorktree> {
    if !is_isolated_agent_call(tool_name, tool_input) {
        return None;
    }
    let path: std::path::PathBuf = find_string_field(tool_response, "worktreePath", 0)?.into();
    if !path.is_absolute() {
        return None;
    }
    let name = path.file_name()?.to_str()?;
    if !name.starts_with("agent-") {
        return None;
    }
    let worktrees = path.parent()?;
    if worktrees.file_name()? != std::ffi::OsStr::new("worktrees") {
        return None;
    }
    let dot_claude = worktrees.parent()?;
    if dot_claude.file_name()? != std::ffi::OsStr::new(".claude") {
        return None;
    }
    let branch = find_string_field(tool_response, "worktreeBranch", 0)
        .unwrap_or_else(|| format!("worktree-{name}"));
    let repo_root = dot_claude.parent()?.to_path_buf();
    Some(AgentWorktree { path, repo_root, branch })
}

/// First string value under `key` in a pre-order walk. The walk is
/// depth-capped at 6: the captured shape is flat and top-level, so a
/// deeper field is treated as absent (surfaced by the caller's
/// parse-miss log, never guessed at). String content is never searched,
/// so a result text quoting `worktreePath:` cannot aim the reap.
fn find_string_field(value: &serde_json::Value, key: &str, depth: u8) -> Option<String> {
    if depth > 6 {
        return None;
    }
    match value {
        serde_json::Value::Object(map) => {
            for (k, v) in map {
                if k == key
                    && let Some(s) = v.as_str()
                {
                    return Some(s.to_owned());
                }
            }
            map.values().find_map(|v| find_string_field(v, key, depth + 1))
        }
        serde_json::Value::Array(items) => {
            items.iter().find_map(|v| find_string_field(v, key, depth + 1))
        }
        _ => None,
    }
}

/// The full sha of a detached worktree HEAD holding commits that only
/// the worktree itself reaches, or `None` when removal cannot strand
/// anything. An attached branch is judged after removal by
/// [`reap_worktree_branch`]; a detached HEAD must be judged before.
///
/// The survivors are refs plus every OTHER worktree's HEAD. `--all`
/// cannot serve here: it includes this worktree's own HEAD, against
/// which nothing ever reads unique, so the guard would never fire. Any
/// failure to verify returns a tip, keeping the tree.
fn detached_unique_tip(repo_root: &Path, path: &Path) -> Option<String> {
    if worktree_branch(path).is_some() {
        return None;
    }
    let tip = match git_in_repo(path, &["rev-parse", "HEAD"]) {
        Some(sha) => sha.trim().to_owned(),
        None => return Some(String::from("(unreadable HEAD)")),
    };
    if tip.is_empty() {
        return Some(String::from("(unreadable HEAD)"));
    }
    let survivors = survivor_tips(repo_root, path)?;
    let exclusions: Vec<String> = survivors.iter().map(|sha| format!("^{sha}")).collect();
    let mut cmd = git_command::command("git");
    cmd.arg("-C")
        .arg(repo_root)
        .args(["rev-list", "--count", &tip, "--stdin"])
        .stdin(std::process::Stdio::piped())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::piped());
    let Ok(mut child) = cmd.spawn() else {
        return Some(tip);
    };
    if let Some(mut stdin) = child.stdin.take() {
        use std::io::Write;
        let _ = stdin.write_all(exclusions.join("\n").as_bytes());
        let _ = stdin.write_all(b"\n");
    }
    let unique = match child.wait_with_output() {
        Ok(out) if out.status.success() => {
            String::from_utf8_lossy(&out.stdout).trim().parse::<u64>().ok()
        }
        _ => None,
    };
    match unique {
        Some(0) => None,
        _ => Some(tip),
    }
}

/// Every tip that would survive `worktree_path`'s removal: all refs plus
/// the HEAD of each other worktree. `None` when git cannot be asked,
/// which the caller treats as keep.
fn survivor_tips(repo_root: &Path, worktree_path: &Path) -> Option<Vec<String>> {
    let mut tips: Vec<String> =
        git_in_repo(repo_root, &["for-each-ref", "--format=%(objectname)"])?
            .lines()
            .filter(|l| !l.trim().is_empty())
            .map(|l| l.trim().to_owned())
            .collect();
    let listing = git_in_repo(repo_root, &["worktree", "list", "--porcelain"])?;
    let here = std::fs::canonicalize(worktree_path).ok();
    let mut current: Option<(String, Option<String>)> = None;
    let flush = |current: &mut Option<(String, Option<String>)>, tips: &mut Vec<String>| {
        if let Some((path, Some(sha))) = current.take() {
            let same = std::fs::canonicalize(std::path::Path::new(&path))
                .ok()
                .zip(here.clone())
                .is_some_and(|(a, b)| a == b)
                || path == worktree_path.to_string_lossy();
            if !same {
                tips.push(sha);
            }
        }
    };
    for line in listing.lines() {
        if let Some(path) = line.strip_prefix("worktree ") {
            flush(&mut current, &mut tips);
            current = Some((path.to_owned(), None));
        } else if let Some(sha) = line.strip_prefix("HEAD ") {
            if let Some((_, head)) = current.as_mut() {
                *head = Some(sha.to_owned());
            }
        } else if line.is_empty() {
            flush(&mut current, &mut tips);
        }
    }
    flush(&mut current, &mut tips);
    Some(tips)
}

/// Managed agent worktrees under `<base>/.claude/worktrees/` untouched
/// for at least `age`, for the reconciliation sweep that runs at every
/// session spawn: it reaps what a one-shot failure or a missed
/// completion event left behind. A lock whose reason carries a live pid
/// (the CLI stamps one on a live isolation agent's tree) keeps the tree
/// out; a dead pid - a crashed CLI's leftover, which git never prunes on
/// its own - is reapable. Locks without a parsable pid are not ours to
/// judge and skip. `Ok(vec![])` when the worktrees dir is absent; other
/// read errors propagate, and a repo git cannot answer about sweeps as
/// empty - the fail-closed direction for a deleter. Feed the result to
/// [`reap_agent_worktree`].
pub fn stale_agent_worktrees(
    repo_root: &Path,
    age: std::time::Duration,
) -> std::io::Result<Vec<AgentWorktree>> {
    // The CLI's own root, which is the main checkout for a project that is
    // itself a linked worktree (#2460); the project path lists a directory
    // the CLI never fills.
    let worktrees_dir = worktree_base(repo_root).join(".claude").join("worktrees");
    let entries = match std::fs::read_dir(&worktrees_dir) {
        Ok(entries) => entries,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(err) => return Err(err),
    };
    let Some(locks) = locked_worktrees(repo_root) else {
        return Ok(Vec::new());
    };
    let mut stale = Vec::new();
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else { continue };
        if !name.starts_with("agent-") {
            continue;
        }
        let Ok(meta) = entry.metadata() else { continue };
        if !meta.is_dir() {
            continue;
        }
        let untouched = meta.modified().ok().and_then(|m| m.elapsed().ok());
        if untouched.is_none_or(|tree_age| tree_age < age) {
            continue;
        }
        let path = entry.path();
        let real = std::fs::canonicalize(&path);
        let lock = locks
            .iter()
            .find(|lock| lock.path == path || real.as_ref().is_ok_and(|real| lock.path == *real));
        match lock {
            // Live owner, or a lock we cannot judge: keep the tree.
            Some(lock) if lock_pid_is_live(lock.pid) => continue,
            _ => {}
        }
        stale.push(AgentWorktree {
            path,
            repo_root: repo_root.to_path_buf(),
            branch: format!("worktree-{name}"),
        });
    }
    Ok(stale)
}

/// Whether a lock blocks the sweep: a parsable pid whose process is
/// alive blocks, and so does one we cannot judge (no pid, or liveness
/// unanswerable); only a provably dead pid releases the tree.
fn lock_pid_is_live(pid: Option<u32>) -> bool {
    match pid {
        Some(pid) => process_is_live(pid),
        None => true,
    }
}

/// Whether `pid` names a live process. Unanswerable counts as live: a
/// liveness question we cannot ask never deletes a tree.
fn process_is_live(pid: u32) -> bool {
    let Ok(out) = Command::new("ps").args(["-p", &pid.to_string(), "-o", "pid="]).output() else {
        return true;
    };
    out.status.success() && !out.stdout.is_empty()
}

/// Whether `path`'s lock, re-read now, belongs to a live process. The
/// sweep re-runs this immediately before each removal so a lock taken
/// after the listing still stops that reap. Unlocked or dead-owner
/// trees answer false; unreadable answers true.
pub fn agent_worktree_lock_is_live(repo_root: &Path, path: &Path) -> bool {
    let Ok(real) = std::fs::canonicalize(path) else {
        return true;
    };
    let Some(locks) = locked_worktrees(repo_root) else {
        return true;
    };
    match locks.into_iter().find(|lock| lock.path == real) {
        Some(lock) => lock_pid_is_live(lock.pid),
        None => false,
    }
}

/// A worktree lock: the canonicalized path plus the pid the CLI stamps
/// into its reason, when it carries one.
struct WorktreeLock {
    path: std::path::PathBuf,
    pid: Option<u32>,
}

/// This repo's worktrees git reports as locked, canonicalized, with the
/// pid parsed from the reason when there is one. `None` when git cannot
/// be asked - the caller sweeps as empty rather than judge without the
/// lock facts.
fn locked_worktrees(repo_root: &Path) -> Option<Vec<WorktreeLock>> {
    let listing = git_in_repo(repo_root, &["worktree", "list", "--porcelain"])?;
    let mut locks = Vec::new();
    let mut current: Option<String> = None;
    let mut reason: Option<String> = None;
    let flush = |current: &mut Option<String>,
                 reason: &mut Option<String>,
                 locks: &mut Vec<WorktreeLock>| {
        if let (Some(path), Some(reason)) = (current.take(), reason.take())
            && let Ok(real) = std::fs::canonicalize(std::path::Path::new(&path))
        {
            locks.push(WorktreeLock { path: real, pid: parse_lock_pid(&reason) });
        }
    };
    for line in listing.lines() {
        if let Some(path) = line.strip_prefix("worktree ") {
            flush(&mut current, &mut reason, &mut locks);
            current = Some(path.to_owned());
        } else if let Some(reason_text) = line.strip_prefix("locked") {
            reason = Some(reason_text.trim().to_owned());
        } else if line.is_empty() {
            flush(&mut current, &mut reason, &mut locks);
        }
    }
    flush(&mut current, &mut reason, &mut locks);
    Some(locks)
}

/// The pid in a CLI lock reason, `claude agent agent-<hex> (pid 33497
/// start ...)`. `None` for a bare `locked` line or any foreign reason.
fn parse_lock_pid(reason: &str) -> Option<u32> {
    let digits = reason.split("pid ").nth(1)?;
    let digits: String = digits.chars().take_while(char::is_ascii_digit).collect();
    digits.parse().ok()
}

/// Remove a completed subagent's managed worktree, then reap the
/// conventional branch behind it. Refuses anything but a porcelain-clean
/// tree: the measured leak is clean trees whose gitignored target/ the
/// CLI's auto-clean does not count, while uncommitted edits are a tree
/// the CLI handed back deliberately. Only `branch` is ever aimed at -
/// a branch the subagent checked out itself is left to git's normal
/// lifecycle, the same rule the worker despawn applies.
pub fn reap_agent_worktree(agent_worktree: &AgentWorktree) -> AgentWorktreeReap {
    let path = &agent_worktree.path;
    if !path.exists() {
        return AgentWorktreeReap::Absent;
    }
    if !is_git_repo(path) {
        return AgentWorktreeReap::NotAWorktree;
    }
    if let Some(reason) = worktree_uncommitted_reason(path) {
        return AgentWorktreeReap::KeptDirty { reason };
    }
    if let Some(tip) = detached_unique_tip(&agent_worktree.repo_root, path) {
        return AgentWorktreeReap::KeptUniqueCommit { tip };
    }
    // `git worktree remove` refuses a worktree holding initialized
    // submodules however clean it is (git-worktree(1)), so the unforced
    // form cannot serve here. The porcelain gate above authorizes
    // `--force` and is then the only dirtiness gate on this path: the hook
    // runs once the subagent has returned, and the sweep lists only trees
    // whose top-level dir has gone untouched for an hour and whose lock
    // has no live pid - neither of which excludes a process the subagent
    // left running behind it.
    match remove_worktree(path, true) {
        Ok(()) => AgentWorktreeReap::Reaped {
            branch: reap_worktree_branch(&agent_worktree.repo_root, &agent_worktree.branch),
        },
        Err(err) => AgentWorktreeReap::RemoveFailed { reason: err.to_string() },
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::tempdir;

    #[test]
    fn returns_false_for_empty_dir() {
        let dir = tempdir().expect("tempdir");
        assert!(!is_git_repo(dir.path()));
    }

    #[test]
    fn returns_true_for_initialised_repo() {
        let dir = tempdir().expect("tempdir");
        std::process::Command::new("git")
            .args(["init", "-q"])
            .current_dir(dir.path())
            .status()
            .expect("git init");
        assert!(is_git_repo(dir.path()));
    }

    #[test]
    fn returns_false_for_nonexistent_path() {
        assert!(!is_git_repo(Path::new("/nonexistent/path/that/does/not/exist")));
    }

    #[test]
    fn returns_true_for_subdir_of_repo() {
        let dir = tempdir().expect("tempdir");
        std::process::Command::new("git")
            .args(["init", "-q"])
            .current_dir(dir.path())
            .status()
            .expect("git init");
        let sub = dir.path().join("sub");
        fs::create_dir(&sub).expect("mkdir");
        assert!(is_git_repo(&sub));
    }

    /// A spawn's tree is the repo root of wherever it points: a
    /// subdirectory must land the worker at the root, because that is
    /// where claude's `--worktree` forks from.
    #[test]
    fn worker_root_resolves_a_subdirectory_to_the_repo_root() {
        let repo = init_repo_with_commit();
        let nested = repo.path().join("crates/deep");
        fs::create_dir_all(&nested).expect("nested dir");

        let root = worker_root(&nested).expect("resolves");

        assert_eq!(
            root,
            fs::canonicalize(repo.path()).expect("canonical repo"),
            "a subdirectory must resolve to the repo root, not itself",
        );
    }

    /// A path outside any repo is its own tree, resolved: the worker runs
    /// there without a worktree.
    #[test]
    fn worker_root_keeps_a_path_outside_a_repo_as_itself() {
        let dir = tempdir().expect("tempdir");

        let root = worker_root(dir.path()).expect("resolves");

        assert_eq!(
            root,
            fs::canonicalize(dir.path()).expect("canonical dir"),
            "a non-repo directory is its own root",
        );
    }

    /// The record stores the canonical root on purpose: the claude CLI
    /// derives the session JSONL's directory from the canonical path
    /// (measured: `/tmp` resolves to `/private/tmp`), so an alias in the
    /// record would compose a directory the CLI never wrote to.
    #[test]
    fn worker_root_canonicalizes_the_path_it_returns() {
        let dir = tempdir().expect("tempdir");
        let alias = dir.path().join("alias");
        fs::create_dir_all(&alias).expect("alias dir");
        std::os::unix::fs::symlink(&alias, dir.path().join("link")).expect("symlink");

        let root = worker_root(&dir.path().join("link")).expect("resolves");

        assert_eq!(
            root,
            fs::canonicalize(&alias).expect("canonical"),
            "the resolved root must carry no symlink component",
        );
    }

    /// `--worktree <label>` composes `<canonical root>/.claude/worktrees/
    /// <label>`, and the canonical root of a linked worktree is the MAIN
    /// checkout, not the worktree path (#2460). A path inside a repo
    /// resolves to its toplevel the same way; a path that is not a
    /// repository is its own base, and a git that could not answer is
    /// re-asked rather than pinned.
    #[test]
    fn worktree_base_is_the_cli_canonical_root() {
        let repo = init_repo_with_commit();
        let main = fs::canonicalize(repo.path()).expect("canonical repo");
        let linked = main.join("linked");
        run_git(&main, &["worktree", "add", "-q", "-b", "linked", linked.to_str().expect("utf8")]);
        let linked_nested = linked.join("crates/deep");
        fs::create_dir_all(&linked_nested).expect("nested dir");
        let main_nested = main.join("crates/deep");
        fs::create_dir_all(&main_nested).expect("nested dir");

        assert_eq!(
            worktree_base(&linked),
            main,
            "a project that is a linked worktree forks its workers' worktrees under the main \
             checkout",
        );
        assert_eq!(
            worktree_base(&linked_nested),
            main,
            "a path inside a linked worktree resolves to the main checkout",
        );
        assert_eq!(
            worktree_base(&main_nested),
            main,
            "a subdirectory of a normal checkout resolves to its toplevel, as the CLI does",
        );
        assert_eq!(worktree_base(&main), main, "the main checkout is its own base");

        // A declared project path can reach the main checkout through a
        // symlink; the CLI composes from the canonical spelling, so the
        // answer must not depend on which spelling the config used.
        let holder = tempdir().expect("alias holder");
        let alias = holder.path().join("project");
        std::os::unix::fs::symlink(&main, &alias).expect("symlink");
        assert_eq!(worktree_base(&alias), main, "a symlinked spelling resolves to the same root");

        // A linked worktree of a repo kept in a separate git dir. This is
        // the unsupported layout: see the assertion below.
        let separate = tempdir().expect("separate holder");
        let checkout = separate.path().join("checkout");
        let store = separate.path().join("store.git");
        run_git(
            separate.path(),
            &[
                "init",
                "-q",
                "--separate-git-dir",
                store.to_str().expect("utf8"),
                checkout.to_str().expect("utf8"),
            ],
        );
        run_git(&checkout, &["config", "user.email", "t@example.com"]);
        run_git(&checkout, &["config", "user.name", "Test"]);
        run_git(&checkout, &["config", "commit.gpgsign", "false"]);
        fs::write(checkout.join("README.md"), "seed").expect("write seed");
        run_git(&checkout, &["add", "."]);
        run_git(&checkout, &["commit", "-q", "-m", "init"]);
        let separate_linked = checkout.join("linked");
        run_git(
            &checkout,
            &["worktree", "add", "-q", "-b", "sep-linked", separate_linked.to_str().expect("utf8")],
        );
        // A repo kept in a separate git dir is NOT a supported worker
        // layout: git names the ADMIN dir as its main worktree here, and
        // the CLI's own base for this shape is unverified. forge follows
        // git's answer rather than guessing a checkout it cannot derive.
        assert_eq!(
            worktree_base(&separate_linked),
            fs::canonicalize(&store).expect("canonical store"),
            "a separate git dir's base is the admin dir git names, and the layout is unsupported",
        );

        // A failed resolution is re-asked: with its link gone the worktree
        // is not a repository, and once the link is back the same root
        // answers with the main checkout rather than the pinned fallback.
        // The path sits outside the main checkout so the lifted link
        // leaves it in no repository at all.
        let flaky_holder = tempdir().expect("flaky holder");
        let flaky = flaky_holder.path().join("flaky");
        run_git(&main, &["worktree", "add", "-q", "-b", "flaky", flaky.to_str().expect("utf8")]);
        let link = flaky.join(".git");
        let held = flaky_holder.path().join("flaky-link");
        fs::rename(&link, &held).expect("lift the worktree link");
        assert_eq!(worktree_base(&flaky), flaky, "a path git cannot answer for is its own base");
        fs::rename(&held, &link).expect("restore the worktree link");
        assert_eq!(
            worktree_base(&flaky),
            main,
            "the failed resolution was not memoised, so the next call answers with the main \
             checkout",
        );

        let outside = tempdir().expect("outside");
        assert_eq!(
            worktree_base(outside.path()),
            outside.path(),
            "a path outside any repo is its own base",
        );
        let missing = outside.path().join("not-there");
        assert_eq!(
            worktree_base(&missing),
            missing,
            "a path that is not there answers without a git call and is its own base",
        );
    }

    /// The unresolved-root warning is once per root, not once per call:
    /// callers include render paths that ask for the same row every frame.
    #[test]
    fn an_unresolved_root_is_reported_once() {
        let holder = tempdir().expect("holder");
        let first = holder.path().join("one");
        let second = holder.path().join("two");

        assert!(first_unresolved(&first), "the first report of a root goes through");
        assert!(!first_unresolved(&first), "a repeat for the same root is suppressed");
        assert!(first_unresolved(&second), "a different root reports on its own");
    }

    /// The warning line carries the event name a log grep uses and the
    /// root it is about.
    #[test]
    fn the_unresolved_root_warning_names_the_event_and_the_root() {
        #[derive(Clone)]
        struct Capture(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
        impl std::io::Write for Capture {
            fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
                self.0.lock().expect("capture lock").extend_from_slice(buf);
                Ok(buf.len())
            }
            fn flush(&mut self) -> std::io::Result<()> {
                Ok(())
            }
        }
        impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Capture {
            type Writer = Capture;
            fn make_writer(&'a self) -> Self::Writer {
                self.clone()
            }
        }

        let buffer = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let subscriber = tracing_subscriber::fmt()
            .with_max_level(tracing::Level::WARN)
            .with_writer(Capture(std::sync::Arc::clone(&buffer)))
            .finish();
        let root = std::path::Path::new("/nowhere/at/all");
        tracing::subscriber::with_default(subscriber, || report_unresolved_root(root));

        let text =
            String::from_utf8(buffer.lock().expect("capture lock").clone()).expect("utf8 log");
        assert!(text.contains("worktree_base_unresolved"), "the event name is logged: {text}");
        assert!(text.contains("/nowhere/at/all"), "and the root it is about: {text}");
    }

    /// A directory that is not there is a refusal, not a silent pass: the
    /// spawn would otherwise fail later with claude's own cwd error, far
    /// from the caller that mistyped the path.
    #[test]
    fn worker_root_refuses_a_directory_that_is_not_there() {
        let dir = tempdir().expect("tempdir");
        let missing = dir.path().join("not-there");

        let error = worker_root(&missing).expect_err("a missing directory is refused");

        assert!(
            error.contains("not-there") && error.contains("not a directory"),
            "the refusal names the path and what is wrong with it: {error}",
        );
    }

    fn run_git(dir: &Path, args: &[&str]) {
        let status = std::process::Command::new("git")
            .args(args)
            .current_dir(dir)
            .status()
            .expect("spawn git");
        assert!(status.success(), "git {args:?} failed in {dir:?}");
    }

    /// A repo with one commit. Never names a default branch - CI's git
    /// 2.25.1 predates `init -b` and defaults to `master`.
    fn init_repo_with_commit() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        init_repo_at(dir.path());
        dir
    }

    fn init_repo_at(path: &Path) {
        run_git(path, &["init", "-q"]);
        run_git(path, &["config", "user.email", "t@example.com"]);
        run_git(path, &["config", "user.name", "Test"]);
        run_git(path, &["config", "commit.gpgsign", "false"]);
        fs::write(path.join("README.md"), "seed").expect("write seed");
        run_git(path, &["add", "."]);
        run_git(path, &["commit", "-q", "-m", "init"]);
    }

    /// Init a repo with one commit and add a worktree at `<repo>/wt`.
    /// Returns `(repo_tempdir, worktree_path)`.
    fn init_repo_with_worktree() -> (tempfile::TempDir, std::path::PathBuf) {
        let dir = init_repo_with_commit();
        let wt = dir.path().join("wt");
        run_git(dir.path(), &["worktree", "add", "-q", wt.to_str().expect("utf8 path")]);
        (dir, wt)
    }

    #[test]
    fn repo_branch_names_lists_local_heads_and_remote_tracking_refs() {
        let dir = init_repo_with_commit();
        run_git(dir.path(), &["branch", "feat/live"]);
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/feat/pushed", "HEAD"]);
        // A remote whose own name carries no slash, and one branch under a
        // nested path, so the two-segment split is exercised both ways.
        run_git(dir.path(), &["update-ref", "refs/remotes/upstream/main", "HEAD"]);

        let names = repo_branch_names(dir.path()).expect("a repo root answers").names;
        assert!(names.contains("feat/live"), "local heads are listed: {names:?}");
        assert!(names.contains("feat/pushed"), "remote-tracking refs count: {names:?}");
        assert!(names.contains("main") || names.contains("master"), "{names:?}");
        assert!(
            !names.iter().any(|n| n.starts_with("refs/")),
            "names are branch names, not refnames: {names:?}",
        );
    }

    /// The branch this returns is what the despawn delete is keyed on,
    /// so an unscrubbed read hands the wrong name to a correctly-scrubbed
    /// check: absent in the real repo, and its review state deleted. A
    /// scrubbed check beside an unscrubbed read is the asymmetry that
    /// produced the original defect.
    #[test]
    fn worktree_branch_is_scrubbed_like_every_other_repo_question() {
        let foreign = init_repo_with_commit();
        run_git(foreign.path(), &["checkout", "-q", "-b", "only-in-foreign"]);
        let host = init_repo_with_commit();
        run_git(host.path(), &["checkout", "-q", "-b", "the-real-branch"]);

        let command = scrubbed_git(host.path(), &["rev-parse", "--abbrev-ref", "HEAD"]);
        let removed: Vec<&str> = command
            .get_envs()
            .filter(|(_, value)| value.is_none())
            .filter_map(|(key, _)| key.to_str())
            .collect();
        assert!(removed.contains(&"GIT_DIR"), "the read goes through the scrub: {removed:?}");
        assert_eq!(worktree_branch(host.path()).as_deref(), Some("the-real-branch"));
        let _ = foreign;
    }

    /// `release/HEAD` is a legal branch name - `git branch release/HEAD`
    /// succeeds - so excluding `origin/HEAD` by its last segment drops a
    /// real branch out of the alive set, and absent is what deletes. The
    /// symref is what distinguishes them: a clone's `origin/HEAD` carries
    /// one, a branch never does.
    #[test]
    fn a_branch_legally_named_head_is_not_mistaken_for_the_symref() {
        let dir = init_repo_with_commit();
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/release/HEAD", "HEAD"]);
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/feat/a", "HEAD"]);
        // What a clone leaves: a real symref, not a plain ref.
        run_git(
            dir.path(),
            &["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/feat/a"],
        );

        let repo = repo_branch_names(dir.path()).expect("a repo root answers");
        assert!(
            repo.names.contains("release/HEAD"),
            "a branch that happens to end in HEAD is still a branch: {:?}",
            repo.names,
        );
        assert!(branch_ref_exists(dir.path(), "release/HEAD"), "and the delete gate agrees");
        // The symref itself is excluded from the population, its target
        // having been counted already.
        assert_eq!(repo.ref_count, 3, "local head + two remote branches: {:?}", repo.names);
    }

    /// A remote name may contain slashes - `git remote add gh/upstream`
    /// is accepted - so splitting the tail once leaves the remote's own
    /// tail on the front of the branch, and the live branch reads as
    /// absent. That is the only hazard in this area that points at
    /// DELETING state for a branch that still exists; every other one
    /// spares wrongly.
    #[test]
    fn a_slash_bearing_remote_still_yields_the_real_branch_name() {
        let dir = init_repo_with_commit();
        run_git(dir.path(), &["update-ref", "refs/remotes/gh/upstream/feat/pushed", "HEAD"]);
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/feat/plain", "HEAD"]);

        let names = repo_branch_names(dir.path()).expect("a repo root answers").names;
        assert!(
            names.contains("feat/pushed"),
            "the branch behind a slash-bearing remote must not read as gone: {names:?}",
        );
        assert!(names.contains("feat/plain"), "the ordinary case still works: {names:?}");
        // Over-sparing is the deliberate direction: intermediate suffixes
        // join the alive set, which can only spare, never delete.
        assert!(names.contains("upstream/feat/pushed"), "{names:?}");
        assert!(names.contains("pushed"), "{names:?}");
    }

    /// Discovery walks up. Asking about a directory that merely sits
    /// inside a repo gets the ancestor's refs at exit 0, which for a
    /// caller deleting on absence means judging one project's rows
    /// against another repo's branches.
    #[test]
    fn repo_branch_names_refuses_a_directory_nested_inside_a_repo() {
        let dir = init_repo_with_commit();
        let nested = dir.path().join("crates");
        fs::create_dir_all(&nested).expect("mkdir");
        assert!(
            repo_branch_names(&nested).is_none(),
            "only the work-tree root answers for its own refs",
        );
        assert!(repo_branch_names(dir.path()).is_some(), "the root itself still answers");
    }

    #[test]
    fn repo_branch_names_is_none_outside_a_repo() {
        let dir = tempdir().expect("tempdir");
        assert!(repo_branch_names(dir.path()).is_none());
    }

    /// Pins the DEFENCE rather than only the hazard. The inherited case
    /// cannot be exercised in-process - the crate forbids `unsafe_code`,
    /// so a test cannot set `GIT_DIR` on itself - but `env_remove` beating
    /// an explicit `env` on the same `Command` is the same precedence that
    /// defeats inheritance, and it is what `git_in_repo` relies on.
    #[test]
    fn env_remove_beats_a_git_dir_set_on_the_same_command() {
        let host = init_repo_with_commit();
        run_git(host.path(), &["branch", "only-in-host"]);
        let foreign = init_repo_with_commit();
        run_git(foreign.path(), &["branch", "only-in-foreign"]);

        let out = Command::new("git")
            .arg("-C")
            .arg(host.path())
            .args(["for-each-ref", "--format=%(refname)", "refs/heads"])
            .env("GIT_DIR", foreign.path().join(".git"))
            .env_remove("GIT_DIR")
            .output()
            .expect("git runs");
        let listing = String::from_utf8_lossy(&out.stdout);

        assert!(out.status.success());
        assert!(
            listing.contains("only-in-host"),
            "the scrubbed command reads its -C repo: {listing:?}"
        );
        assert!(
            !listing.contains("only-in-foreign"),
            "and not the one GIT_DIR pointed at: {listing:?}",
        );
    }

    /// Pins the scrub at its CALL SITE. The precedence test above covers
    /// `env_remove` winning; this covers `git_in_repo` actually applying
    /// it, which nothing else does - all three calls can be deleted with
    /// the rest of the suite green.
    #[test]
    fn the_git_helper_scrubs_every_repo_location_variable() {
        let dir = tempdir().expect("tempdir");
        let command = scrubbed_git(dir.path(), &["rev-parse", "--show-toplevel"]);
        let removed: Vec<&str> = command
            .get_envs()
            .filter(|(_, value)| value.is_none())
            .filter_map(|(key, _)| key.to_str())
            .collect();
        for key in ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR"] {
            assert!(removed.contains(&key), "{key} is not scrubbed: {removed:?}");
        }
    }

    /// The hazard the scrub exists for: `-C` does not win against an
    /// inherited `GIT_DIR`, so an unscrubbed call answers about whatever
    /// repo the environment names.
    #[test]
    fn an_inherited_git_dir_beats_dash_c() {
        let foreign = init_repo_with_commit();
        run_git(foreign.path(), &["branch", "only-in-foreign"]);
        let elsewhere = tempdir().expect("tempdir");

        let out = Command::new("git")
            .env("GIT_DIR", foreign.path().join(".git"))
            .arg("-C")
            .arg(elsewhere.path())
            .args(["for-each-ref", "--format=%(refname)", "refs/heads"])
            .output()
            .expect("git runs");
        let listing = String::from_utf8_lossy(&out.stdout);

        assert!(out.status.success(), "the wrong answer arrives as a success");
        assert!(
            listing.contains("only-in-foreign"),
            "GIT_DIR overrides -C, so this reports the foreign repo's refs: {listing:?}",
        );
    }

    #[test]
    fn clean_worktree_reports_not_dirty() {
        let (_dir, wt) = init_repo_with_worktree();
        assert_eq!(worktree_dirty_reason(&wt), None);
    }

    #[test]
    fn untracked_file_reports_dirty() {
        let (_dir, wt) = init_repo_with_worktree();
        fs::write(wt.join("scratch.txt"), "uncommitted").expect("write scratch");
        assert!(worktree_dirty_reason(&wt).is_some());
    }

    #[test]
    fn unpushed_commit_reports_dirty() {
        let (_dir, wt) = init_repo_with_worktree();
        // Establish an upstream via a bare remote, then commit locally
        // so HEAD is one ahead of @{upstream}. The working tree stays
        // clean (the change is committed), isolating the unpushed path.
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(&wt, &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")]);
        run_git(&wt, &["push", "-q", "-u", "origin", "HEAD"]);
        fs::write(wt.join("ahead.txt"), "local only").expect("write ahead");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "ahead of upstream"]);
        let reason = worktree_dirty_reason(&wt).expect("unpushed commit reports dirty");
        assert!(reason.contains("unpushed"), "reason names unpushed commits: {reason:?}");
    }

    /// The measured wind-down (#2486): a worker branch cut from main
    /// tracks `origin/main`, its head is pushed to a remote branch, and
    /// the content landed on main as a squash commit. The upstream
    /// comparison reads ahead forever because the squash has a different
    /// sha, and refused a clean despawn.
    ///
    /// The head goes to a second remote, `upstream`: reachability is
    /// from ANY remote ref, not from `origin` alone.
    #[test]
    fn a_squash_merged_branch_head_reports_clean() {
        let (dir, wt) = init_repo_with_worktree();
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")],
        );
        let fork = tempdir().expect("fork tempdir");
        run_git(fork.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "upstream", fork.path().to_str().expect("utf8 path")],
        );
        let main = git_stdout(dir.path(), &["rev-parse", "--abbrev-ref", "HEAD"]);
        run_git(dir.path(), &["push", "-q", "-u", "origin", "HEAD"]);

        // The worker branch: cut from main, tracking it, head pushed to
        // its own remote ref the way the PR's branch is.
        run_git(&wt, &["branch", "--set-upstream-to", &format!("origin/{main}")]);
        fs::write(wt.join("work.txt"), "the PR's content").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "the PR's commit"]);
        run_git(&wt, &["push", "-q", "upstream", "HEAD:refs/heads/wt"]);

        // The squash onto main: same content, a new sha.
        run_git(dir.path(), &["merge", "-q", "--squash", "wt"]);
        run_git(dir.path(), &["commit", "-q", "-m", "squash-merge wt"]);
        run_git(dir.path(), &["push", "-q", "origin", "HEAD"]);

        assert_eq!(
            git_stdout(&wt, &["rev-list", "--count", "@{upstream}..HEAD"]),
            "1",
            "the fixture reproduces the trap: the upstream comparison still reads ahead",
        );
        let reaching = git_stdout(&wt, &["branch", "-r", "--contains", "HEAD"]);
        assert!(
            reaching.contains("upstream/wt"),
            "the head is on a remote ref, and not origin's: {reaching:?}",
        );
        assert!(!reaching.contains("origin/wt"), "origin alone cannot see it: {reaching:?}");
        assert_eq!(worktree_dirty_reason(&wt), None);
    }

    /// The landing after the remote branch is gone: the worker pushed
    /// with `-u`, the PR squash-merged three commits (one of them
    /// empty), the head branch was deleted on the remote and a prune
    /// dropped its tracking ref. No remote ref reaches HEAD and no
    /// patch-id matches a multi-commit squash, so only the deleted
    /// upstream says the branch landed.
    #[test]
    fn a_squash_merged_branch_survives_its_remote_branch_being_pruned() {
        let (dir, wt) = init_repo_with_worktree();
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")],
        );
        run_git(dir.path(), &["push", "-q", "-u", "origin", "HEAD"]);

        // The worker pushes with `-u`, so its upstream is its own branch.
        fs::write(wt.join("one.txt"), "first").expect("write one");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "first"]);
        fs::write(wt.join("two.txt"), "second").expect("write two");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "second"]);
        run_git(&wt, &["commit", "-q", "--allow-empty", "-m", "empty"]);
        run_git(&wt, &["push", "-q", "-u", "origin", "HEAD:refs/heads/wt"]);

        run_git(dir.path(), &["merge", "-q", "--squash", "wt"]);
        run_git(dir.path(), &["commit", "-q", "-m", "squash-merge wt"]);
        run_git(dir.path(), &["push", "-q", "origin", "HEAD"]);

        run_git(dir.path(), &["push", "-q", "origin", "--delete", "wt"]);
        run_git(dir.path(), &["fetch", "-q", "--prune", "origin"]);

        assert_eq!(
            git_stdout(&wt, &["rev-list", "--count", "HEAD", "--not", "--remotes"]),
            "3",
            "no remote ref reaches the branch's commits any more",
        );
        assert_eq!(worktree_dirty_reason(&wt), None);
    }

    /// Reachability is from ANY remote ref. The head sits on a fork
    /// remote (`upstream`) and nothing has merged it yet, so only a
    /// query that asks about every remote sees it as pushed.
    #[test]
    fn a_head_pushed_to_any_remote_counts_as_pushed() {
        let (dir, wt) = init_repo_with_worktree();
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")],
        );
        let fork = tempdir().expect("fork tempdir");
        run_git(fork.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "upstream", fork.path().to_str().expect("utf8 path")],
        );
        run_git(dir.path(), &["push", "-q", "-u", "origin", "HEAD"]);

        fs::write(wt.join("work.txt"), "pushed to the fork").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "on the fork only"]);
        run_git(&wt, &["push", "-q", "upstream", "HEAD:refs/heads/wt"]);

        assert!(
            !git_stdout(&wt, &["branch", "-r", "--contains", "HEAD"]).contains("origin/"),
            "nothing on origin reaches the head",
        );
        assert_eq!(worktree_dirty_reason(&wt), None);
    }

    /// The other side: a commit no remote ref reaches is unpushed however
    /// the branch is configured. A branch with no upstream used to be
    /// skipped entirely, so the close went through without naming it.
    #[test]
    fn a_commit_no_remote_ref_reaches_reports_dirty() {
        let (dir, wt) = init_repo_with_worktree();
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(
            dir.path(),
            &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")],
        );
        run_git(dir.path(), &["push", "-q", "-u", "origin", "HEAD"]);

        // No upstream on the worker branch, and the commit is pushed
        // nowhere: reachability from a remote ref is the whole question.
        fs::write(wt.join("work.txt"), "local only").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "never pushed"]);

        assert_eq!(
            worktree_dirty_reason(&wt),
            Some("1 unpushed commit".to_owned()),
            "the named reason counts the commits no remote ref reaches",
        );
    }

    #[test]
    fn worktree_branch_reports_checked_out_branch() {
        let (dir, wt) = init_repo_with_worktree();
        // The main worktree is on its init branch; the added worktree
        // gets its own detached-or-named branch. Name one explicitly.
        run_git(&wt, &["checkout", "-q", "-b", "review-loop/feat"]);
        assert_eq!(worktree_branch(&wt).as_deref(), Some("review-loop/feat"));
        assert!(worktree_branch(dir.path()).is_some(), "main worktree also reports a branch");
    }

    #[test]
    fn worktree_branch_none_for_non_repo() {
        let dir = tempdir().expect("tempdir");
        assert!(worktree_branch(dir.path()).is_none());
    }

    #[test]
    fn remove_worktree_removes_clean() {
        let (_dir, wt) = init_repo_with_worktree();
        assert!(wt.exists());
        remove_worktree(&wt, false).expect("clean worktree removes");
        assert!(!wt.exists(), "worktree dir gone after remove");
    }

    #[test]
    fn remove_worktree_removes_locked_clean() {
        let (dir, wt) = init_repo_with_worktree();
        run_git(dir.path(), &["worktree", "lock", wt.to_str().expect("utf8 path")]);
        assert!(wt.exists());
        remove_worktree(&wt, false).expect("locked clean worktree removes");
        assert!(!wt.exists(), "locked worktree dir gone after remove");
    }

    #[test]
    fn remove_worktree_errors_on_dirty_without_force() {
        let (_dir, wt) = init_repo_with_worktree();
        fs::write(wt.join("scratch.txt"), "uncommitted").expect("write scratch");
        run_git(&wt, &["add", "."]);
        assert!(remove_worktree(&wt, false).is_err(), "dirty worktree blocks removal");
        assert!(wt.exists(), "worktree survives a blocked removal");
    }

    #[test]
    fn remove_worktree_force_removes_dirty() {
        let (_dir, wt) = init_repo_with_worktree();
        fs::write(wt.join("scratch.txt"), "uncommitted").expect("write scratch");
        run_git(&wt, &["add", "."]);
        remove_worktree(&wt, true).expect("force removes a dirty worktree");
        assert!(!wt.exists(), "worktree dir gone after force remove");
    }

    /// The leftover state a failed delete leaves: the path deregistered,
    /// the directory still on disk with the build tree in it. `git
    /// worktree remove` refuses that state for good, and the fallback
    /// finishes the job on the one path it was handed.
    #[test]
    fn orphan_removal_removes_a_deregistered_leftover_directory() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("leftover");
        fs::create_dir_all(wt.join("target").join("debug")).expect("target dir");
        fs::write(wt.join("target").join("debug").join("obj.o"), "x").expect("object file");
        // The despawn records the admitted removal before git runs.
        record_worktree_state(dir.path(), "leftover", &wt, WorktreeRecord::Removing);
        fs::remove_dir_all(dir.path().join(".git").join("worktrees").join("leftover"))
            .expect("deregister the worktree");
        // Fixture precondition, asserted rather than assumed so a git
        // that stops refusing fails here instead of passing without the
        // fallback.
        assert!(
            remove_worktree(&wt, true).is_err(),
            "fixture precondition: git refuses a deregistered worktree"
        );
        assert!(wt.exists(), "and the refusal leaves the directory on disk");

        remove_orphaned_worktree_dir(dir.path(), &wt).expect("the leftover directory removes");

        assert!(!wt.exists(), "the leftover directory is gone");
    }

    /// A registered worktree is not a leftover: git may be holding
    /// uncommitted work in it, and `git worktree remove` (with its own
    /// clean check) stays the only path allowed to delete one.
    #[test]
    fn orphan_removal_refuses_a_registered_worktree() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("registered");

        let err = remove_orphaned_worktree_dir(dir.path(), &wt).expect_err("refused");

        assert!(
            matches!(err, WorktreeError::StillRegistered(_)),
            "the refusal names the registration: {err:?}"
        );
        assert!(wt.exists(), "the registered worktree is untouched");
        assert!(worktree_registered(dir.path(), &wt), "and git still lists it");
    }

    /// Anything that is not a direct child of the worktrees root is
    /// refused rather than guessed at - the main checkout above all.
    #[test]
    fn orphan_removal_refuses_paths_outside_the_worktrees_root() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("elsewhere");
        fs::create_dir_all(dir.path().join("some-dir")).expect("unrelated dir");
        let root = wt.parent().expect("worktrees root").to_path_buf();
        let targets =
            [dir.path().to_path_buf(), root.clone(), root.join(".."), dir.path().join("some-dir")];
        for target in targets {
            let err = remove_orphaned_worktree_dir(dir.path(), &target).expect_err("refused");
            assert!(
                matches!(err, WorktreeError::OutsideWorktreesRoot { .. }),
                "the refusal is about the path, not the caller: {err:?} for {target:?}"
            );
        }
        assert!(dir.path().join("some-dir").is_dir(), "nothing outside the root was touched");
        assert!(root.is_dir(), "the worktrees root stands");
        assert!(wt.exists(), "the worktree it does hold stands");
    }

    /// A symlink or a plain file where the directory should be is
    /// refused, not followed or deleted.
    #[test]
    fn orphan_removal_refuses_a_non_directory() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("shape");
        std::fs::remove_dir_all(dir.path().join(".git").join("worktrees").join("shape"))
            .expect("deregister the worktree");
        std::fs::remove_dir_all(&wt).expect("clear the worktree dir");
        let elsewhere = dir.path().join("precious");
        fs::create_dir_all(&elsewhere).expect("precious dir");
        fs::write(elsewhere.join("keep.txt"), "keep").expect("keep file");
        std::os::unix::fs::symlink(&elsewhere, &wt).expect("symlink at the worktree path");

        let err = remove_orphaned_worktree_dir(dir.path(), &wt).expect_err("refused");

        assert!(
            matches!(err, WorktreeError::NotAPlainDirectory(_)),
            "a symlink is not a directory to delete: {err:?}"
        );
        assert!(
            elsewhere.join("keep.txt").exists(),
            "the symlink's target was not deleted through the link"
        );

        fs::remove_file(&wt).expect("clear the symlink");
        fs::write(&wt, "not a directory").expect("file at the path");
        let err = remove_orphaned_worktree_dir(dir.path(), &wt).expect_err("refused");
        assert!(
            matches!(err, WorktreeError::NotAPlainDirectory(_)),
            "a file is not a directory to delete: {err:?}"
        );
        assert!(wt.is_file(), "the file was not deleted");
    }

    /// A `.git` DIRECTORY at the path is a checkout of its own, never the
    /// tail of a worktree removal - a worktree's link is a file - so the
    /// clear must refuse it rather than delete someone's repository.
    #[test]
    fn orphan_removal_refuses_a_checkout_of_its_own() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(wt.join(".git")).expect("a .git directory");
        fs::write(wt.join("real-work.txt"), "someone's repository").expect("write");

        let err =
            remove_orphaned_worktree_dir(dir.path(), &wt).expect_err("a foreign checkout refuses");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.join("real-work.txt").exists(), "nothing was deleted");
    }

    /// A `.git` link naming ANOTHER repo's admin dir is someone else's
    /// worktree parked at our path: not this repo's leftover, so not this
    /// repo's to delete. The comparison must resolve both spellings (a
    /// tempdir root is a symlink on macOS), which the same-repo case in
    /// `orphan_removal_removes_a_deregistered_leftover_directory` pins
    /// from the other side.
    #[test]
    fn orphan_removal_refuses_another_repos_worktree_link() {
        let dir = init_repo_with_commit();
        let other = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("mkdir");
        fs::write(
            wt.join(".git"),
            format!(
                "gitdir: {}\n",
                other.path().join(".git").join("worktrees").join("lbl").display()
            ),
        )
        .expect("write the foreign link");

        let err =
            remove_orphaned_worktree_dir(dir.path(), &wt).expect_err("a foreign link refuses");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.exists(), "the directory was left alone");
    }

    /// A repo moved or renamed after a failed despawn keeps its leftover's
    /// `.git` link pointing at the path the repo left. The removal record
    /// travels with the repo's `.git`, so it is what proves the leftover
    /// is ours - otherwise the resumed worker dies on git's already-exists,
    /// the #1767 symptom, for the moved-repo edge (#2344).
    #[test]
    fn orphan_removal_clears_its_leftover_after_the_repo_moved() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let wt = before.join(".claude").join("worktrees").join("lbl");
        record_worktree_owned(&before, "lbl", &wt);
        // The despawn records the admitted removal before git runs.
        record_worktree_state(&before, "lbl", &wt, WorktreeRecord::Removing);
        deregister_worktree(&before, "lbl");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");
        let link = fs::read_to_string(wt.join(".git")).expect("leftover link");
        let named = link.trim().strip_prefix("gitdir:").expect("a gitdir link").trim();
        assert!(
            !Path::new(named).exists(),
            "fixture precondition: the link names the path the repo left behind: {named}",
        );
        assert_eq!(
            recorded_worktree(&after, &wt).map(|record| record.state),
            Some(WorktreeRecord::Removing),
            "the removal record moved with the repo",
        );

        remove_orphaned_worktree_dir(&after, &wt).expect("its own leftover clears after a move");

        assert!(!wt.exists(), "the leftover directory is gone");
        assert_eq!(
            recorded_worktree(&after, &wt).map(|record| record.state),
            Some(WorktreeRecord::Cleared),
            "the clear leaves no authorization behind for the next directory at this label",
        );
    }

    /// Our own worktree after a repo move whose registration was pruned -
    /// `git worktree prune` is normal cleanup - leaves the same stale link
    /// a failed despawn does, with uncommitted files still inside. No
    /// removal was admitted, so the clear must refuse and keep the
    /// directory rather than delete it before the add (#2344).
    #[test]
    fn orphan_removal_refuses_a_moved_worktree_without_a_removal_record() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");
        // The pruned registration: git no longer lists the worktree, and
        // the directory keeps the file nobody committed.
        deregister_worktree(&after, "lbl");
        fs::write(wt.join("uncommitted.txt"), "work in progress").expect("write work");

        let err = remove_orphaned_worktree_dir(&after, &wt)
            .expect_err("a live worktree with no admitted removal refuses");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.join("uncommitted.txt").exists(), "the uncommitted work was not deleted");
    }

    /// A foreign repo's worktree parked under our root whose repo was
    /// moved or deleted produces the same stale link shape as our own
    /// moved leftover. Its label is not in this repo's removal record, so
    /// it is refused no matter what the link says (#2344).
    #[test]
    fn orphan_removal_refuses_a_moved_foreign_worktree_link() {
        let dir = init_repo_with_commit();
        let foreign_parent = tempdir().expect("foreign parent");
        let foreign = foreign_parent.path().join("foreign");
        fs::create_dir_all(&foreign).expect("mkdir");
        init_repo_at(&foreign);
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("mkdir");
        fs::write(
            wt.join(".git"),
            format!("gitdir: {}\n", foreign.join(".git").join("worktrees").join("lbl").display()),
        )
        .expect("write the foreign link");
        fs::rename(&foreign, foreign_parent.path().join("gone")).expect("move the foreign repo");

        let err = remove_orphaned_worktree_dir(dir.path(), &wt)
            .expect_err("a moved foreign link refuses");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.exists(), "the directory was left alone");
    }

    /// A stale link naming a DIFFERENT worktree than the directory it sits
    /// in is not this directory's removal tail. With no record for this
    /// label, it refuses rather than trusting the path shape (#2344).
    #[test]
    fn orphan_removal_refuses_a_stale_link_naming_another_worktree() {
        let dir = init_repo_with_commit();
        let foreign_parent = tempdir().expect("foreign parent");
        let foreign = foreign_parent.path().join("foreign");
        fs::create_dir_all(&foreign).expect("mkdir");
        init_repo_at(&foreign);
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("mkdir");
        fs::write(
            wt.join(".git"),
            format!("gitdir: {}\n", foreign.join(".git").join("worktrees").join("other").display()),
        )
        .expect("write the foreign link");
        fs::rename(&foreign, foreign_parent.path().join("gone")).expect("move the foreign repo");

        let err = remove_orphaned_worktree_dir(dir.path(), &wt)
            .expect_err("a stale link to another worktree refuses");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.exists(), "the directory was left alone");
    }

    /// Only an admitted removal authorizes the clear. A live `owned`
    /// record and a spent `cleared` one are both the latest state for the
    /// label and both must leave the directory in place; a `.is_some()`
    /// predicate would delete a live worktree (#2344).
    #[test]
    fn orphan_removal_refuses_a_moved_worktree_recorded_owned_or_cleared() {
        for state in [WorktreeRecord::Owned, WorktreeRecord::Cleared] {
            let parent = tempdir().expect("parent");
            let before = parent.path().join("before");
            fs::create_dir_all(&before).expect("mkdir");
            init_repo_at(&before);
            add_worker_worktree(&before, "lbl");
            let wt = before.join(".claude").join("worktrees").join("lbl");
            record_worktree_state(&before, "lbl", &wt, state);
            deregister_worktree(&before, "lbl");
            let after = parent.path().join("after");
            fs::rename(&before, &after).expect("move the repo");
            let wt = after.join(".claude").join("worktrees").join("lbl");
            fs::write(wt.join("uncommitted.txt"), "work in progress").expect("write work");

            let err = remove_orphaned_worktree_dir(&after, &wt)
                .expect_err("only an admitted removal authorizes the clear");

            assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{state:?}: {err:?}");
            assert!(wt.exists(), "{state:?}: the directory was left alone");
        }
    }

    /// The record parser scopes by label: an admission for `a` must not
    /// authorize deleting a leftover named `b` (#2344).
    #[test]
    fn orphan_removal_refuses_a_leftover_whose_label_has_no_admission() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "b");
        record_worktree_state(
            &before,
            "a",
            &before.join(".claude").join("worktrees").join("a"),
            WorktreeRecord::Removing,
        );
        deregister_worktree(&before, "b");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("b");

        let err = remove_orphaned_worktree_dir(&after, &wt)
            .expect_err("another label's admission does not authorize the clear");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.exists(), "the directory was left alone");
    }

    /// Two checkouts can share a git common dir (a project that is itself
    /// a linked worktree keeps its git dir in the main repo), so the same
    /// record file holds both projects' labels. A record whose path still
    /// exists speaks only for the checkout it names; another checkout's
    /// admission must not authorize this one's clear, and its later
    /// `cleared` must not retract this one's live admission (#2344).
    #[test]
    fn another_checkouts_record_does_not_speak_for_this_one() {
        let dir = init_repo_with_commit();
        let left = dir.path().join("left");
        let right = dir.path().join("right");
        run_git(
            dir.path(),
            &["worktree", "add", "-q", "-b", "left", left.to_str().expect("utf8 path")],
        );
        run_git(
            dir.path(),
            &["worktree", "add", "-q", "-b", "right", right.to_str().expect("utf8 path")],
        );
        let left_wt = left.join(".claude").join("worktrees").join("w");
        run_git(
            &left,
            &["worktree", "add", "-q", "-b", "worktree-w", left_wt.to_str().expect("utf8 path")],
        );
        record_worktree_state(&left, "w", &left_wt, WorktreeRecord::Removing);
        // The right checkout's leftover carries the same label and no
        // record of its own; the left checkout's admission names a path
        // that still exists and is not this one.
        let right_wt = right.join(".claude").join("worktrees").join("w");
        fs::create_dir_all(&right_wt).expect("mkdir");
        fs::write(right_wt.join("uncommitted.txt"), "right's work").expect("write");

        let err = remove_orphaned_worktree_dir(&right, &right_wt)
            .expect_err("the left checkout's admission does not speak for the right");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(right_wt.join("uncommitted.txt").exists(), "right's work was not deleted");

        // A spent record from the right checkout, its path now gone, does
        // not retract the left's still-standing admission: a matching
        // live path is preferred over a stale one.
        record_worktree_state(&right, "w", &right_wt.join("gone"), WorktreeRecord::Cleared);
        assert_eq!(
            recorded_worktree(&left, &left_wt).map(|record| record.state),
            Some(WorktreeRecord::Removing),
            "the left checkout's live admission still speaks for its own worktree",
        );

        // A stale-path record from the left checkout - its path gone
        // while its checkout root is alive - is still not the right
        // checkout's.
        record_worktree_state(&left, "w", &left.join("gone-wt"), WorktreeRecord::Removing);
        let err = remove_orphaned_worktree_dir(&right, &right_wt)
            .expect_err("a stale record from a live other checkout does not speak for the right");
        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(right_wt.join("uncommitted.txt").exists(), "right's work was not deleted");
    }

    /// The whole mechanism end to end: `remove_owned_worktree` records the
    /// admission before git runs, a removal that dies part-way leaves the
    /// directory and the record, and after a repo move `ensure` clears the
    /// leftover on that record and recreates the worktree.
    #[test]
    fn remove_owned_worktree_leaves_the_record_a_failed_removal_needs() {
        use std::os::unix::fs::PermissionsExt;

        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        let branch = add_worker_worktree(&before, "lbl");
        let wt = before.join(".claude").join("worktrees").join("lbl");
        let blocked = wt.join("blocked");
        fs::create_dir_all(&blocked).expect("blocked dir");
        fs::write(blocked.join("file"), "x").expect("file");
        fs::set_permissions(&blocked, fs::Permissions::from_mode(0o555)).expect("chmod");
        let err = remove_owned_worktree(&before, "lbl", &wt, true)
            .expect_err("the removal dies on the unwritable directory");
        assert!(wt.exists(), "the directory survives the failed removal: {err:?}");
        assert_eq!(
            recorded_worktree(&before, &wt).map(|record| record.state),
            Some(WorktreeRecord::Removing),
            "the admission stands after the removal died",
        );

        fs::set_permissions(&blocked, fs::Permissions::from_mode(0o755)).expect("chmod back");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");

        let outcome = ensure_worker_worktree(&after, "lbl", &wt)
            .expect("the moved leftover clears on the record");

        assert_eq!(outcome, WorktreeEnsure::AttachedExistingBranch, "the branch is reattached");
        assert_eq!(worktree_branch(&wt).as_deref(), Some(branch.as_str()));
        assert!(!wt.join("blocked").exists(), "the leftover's dead tree is gone");
    }

    /// A completed removal clears its record, so nothing is left behind to
    /// authorize a later clear.
    #[test]
    fn a_completed_removal_clears_the_record() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");

        remove_owned_worktree(dir.path(), "lbl", &wt, true).expect("the worktree removes");

        assert_eq!(
            recorded_worktree(dir.path(), &wt).map(|record| record.state),
            Some(WorktreeRecord::Cleared),
            "a completed removal leaves nothing to clear",
        );
    }

    /// A forced removal of a path that is already gone admits nothing. If
    /// it did, the admission would outlive its directory and later
    /// authorize deleting a new worktree that reused the label after a
    /// repo move (#2344).
    #[test]
    fn a_forced_removal_of_a_gone_worktree_admits_nothing() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        let branch = add_worker_worktree(&before, "lbl");
        let wt = before.join(".claude").join("worktrees").join("lbl");
        // The live worker's directory is gone before the forced despawn,
        // and the removal itself fails - git cannot even be spawned from
        // the missing parent - so only the admission record can outlive
        // the call.
        fs::remove_dir_all(wt.parent().expect("worktrees root")).expect("the worktree is gone");
        remove_owned_worktree(&before, "lbl", &wt, true)
            .expect_err("git cannot run from a missing parent");
        assert_eq!(
            recorded_worktree(&before, &wt).map(|record| record.state),
            Some(WorktreeRecord::Cleared),
            "a gone path admits nothing",
        );
        // The label is reused: any stale registration is pruned, a new
        // worktree takes the path, and it holds a file nobody committed.
        if before.join(".git").join("worktrees").join("lbl").exists() {
            deregister_worktree(&before, "lbl");
        }
        run_git(&before, &["worktree", "add", "-q", wt.to_str().expect("utf8 path"), &branch]);
        fs::write(wt.join("uncommitted.txt"), "new worker's work").expect("write work");
        deregister_worktree(&before, "lbl");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");

        let err = ensure_worker_worktree(&after, "lbl", &wt)
            .expect_err("the spent admission does not authorize deleting the new worktree");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.join("uncommitted.txt").exists(), "the new worker's work is intact");
    }

    /// A directory with no `.git` is decided by the removal record: no
    /// admission refuses (with the directory intact), an admitted removal
    /// clears. An empty directory is the one exception - it holds nothing
    /// to lose and the fresh-spawn obstacle treats it as free.
    #[test]
    fn orphan_removal_decides_a_no_git_directory_by_its_record() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("mkdir");
        fs::write(wt.join("uncommitted.txt"), "work").expect("write");

        let err = remove_orphaned_worktree_dir(dir.path(), &wt)
            .expect_err("no .git and no admission refuses");
        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.join("uncommitted.txt").exists(), "the directory was left alone");

        record_worktree_state(dir.path(), "lbl", &wt, WorktreeRecord::Removing);
        remove_orphaned_worktree_dir(dir.path(), &wt).expect("an admitted removal clears it");
        assert!(!wt.exists(), "the leftover directory is gone");
    }

    #[test]
    fn orphan_removal_clears_an_empty_directory_without_a_record() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("mkdir");

        remove_orphaned_worktree_dir(dir.path(), &wt)
            .expect("an empty directory holds nothing to lose");

        assert!(!wt.exists(), "the empty directory is gone");
    }

    /// A stale registration whose directory carries a LIVE foreign link is
    /// not repaired: `git worktree repair` would rewrite the link and adopt
    /// the directory into this repo.
    #[test]
    fn ensure_does_not_repair_a_registration_over_a_foreign_link() {
        let other = init_repo_with_commit();
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let wt = before.join(".claude").join("worktrees").join("lbl");
        let foreign = format!(
            "gitdir: {}\n",
            other.path().join(".git").join("worktrees").join("lbl").display()
        );
        fs::write(wt.join(".git"), &foreign).expect("write the foreign link");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");

        let err = ensure_worker_worktree(&after, "lbl", &wt)
            .expect_err("a repair over a live foreign link refuses");

        assert!(matches!(err, WorktreeError::RegistrationUnusable { .. }), "{err:?}");
        assert_eq!(
            fs::read_to_string(wt.join(".git")).expect("the link"),
            foreign,
            "the foreign link was not rewritten",
        );
    }

    /// A repair git refuses is a refusal, not `AlreadyPresent` over a
    /// git-dead directory.
    #[test]
    fn ensure_refuses_a_moved_registration_git_cannot_repair() {
        use std::os::unix::fs::PermissionsExt;

        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");
        // The admin dir's `gitdir` file is what repair rewrites, so making
        // it read-only makes the repair itself fail.
        let gitdir = after.join(".git").join("worktrees").join("lbl").join("gitdir");
        fs::set_permissions(&gitdir, fs::Permissions::from_mode(0o444)).expect("chmod the gitdir");

        let err = ensure_worker_worktree(&after, "lbl", &wt)
            .expect_err("a repair git refuses is a refusal");

        assert!(matches!(err, WorktreeError::RegistrationUnusable { .. }), "{err:?}");
        fs::set_permissions(&gitdir, fs::Permissions::from_mode(0o644)).expect("chmod back");
    }

    /// A removal that reported failure over a worktree which is still
    /// alive and registered must not authorize deleting it later. `ensure`
    /// seeing the live registration retracts the admission, so after a
    /// move and a prune the directory is refused rather than cleared on
    /// the old admission (#2344).
    #[test]
    fn ensure_retracts_a_stale_admission_when_the_worktree_is_alive() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let wt = before.join(".claude").join("worktrees").join("lbl");
        // A despawn's removal was admitted, then reported failure over a
        // worktree git still lists.
        record_worktree_state(&before, "lbl", &wt, WorktreeRecord::Removing);
        ensure_worker_worktree(&before, "lbl", &wt).expect("the live worktree is reused");
        assert_eq!(
            recorded_worktree(&before, &wt).map(|record| record.state),
            Some(WorktreeRecord::Owned),
            "the live observation retracts the admission",
        );
        // Later: the repo moves, the registration is pruned, and the file
        // nobody committed is still there.
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");
        deregister_worktree(&after, "lbl");
        fs::write(wt.join("uncommitted.txt"), "work in progress").expect("write work");

        let err = ensure_worker_worktree(&after, "lbl", &wt)
            .expect_err("the retracted admission does not authorize the clear");

        assert!(matches!(err, WorktreeError::ForeignLeftover { .. }), "{err:?}");
        assert!(wt.exists(), "the directory was left alone");
    }

    /// A leftover from an older forge carries no record at all. Its link
    /// names this repo's live git dir, which proves ownership, so it still
    /// clears as the guard always did (#2344 heals forward).
    #[test]
    fn orphan_removal_clears_a_leftover_with_a_live_link_and_no_record() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        deregister_worktree(dir.path(), "lbl");

        remove_orphaned_worktree_dir(dir.path(), &wt).expect("a live link still proves ownership");

        assert!(!wt.exists(), "the leftover directory is gone");
    }

    /// A repo moved while a worktree registration survives: git lists the
    /// worktree by the old absolute path, so the registration is stale and
    /// every git command inside the worktree fails. `ensure` must repair
    /// the link before reusing it, not answer `AlreadyPresent` over a
    /// git-dead directory (#2344).
    #[test]
    fn ensure_reuses_a_moved_registered_worktree_after_repairing_it() {
        let parent = tempdir().expect("parent");
        let before = parent.path().join("before");
        fs::create_dir_all(&before).expect("mkdir");
        init_repo_at(&before);
        add_worker_worktree(&before, "lbl");
        let after = parent.path().join("after");
        fs::rename(&before, &after).expect("move the repo");
        let wt = after.join(".claude").join("worktrees").join("lbl");
        assert!(
            !worktree_runs_git(&wt),
            "fixture precondition: the moved worktree cannot run git before the repair",
        );

        let outcome =
            ensure_worker_worktree(&after, "lbl", &wt).expect("the moved registration repairs");

        assert_eq!(
            outcome,
            WorktreeEnsure::AlreadyPresent,
            "the worktree is reused, not recreated"
        );
        assert!(worktree_runs_git(&wt), "git commands work in the worktree after the repair");
        assert_eq!(
            worktree_registration(&after, &wt),
            Some(WorktreeRegistration::Live),
            "the listing now resolves at the new path",
        );
        assert_eq!(
            recorded_worktree(&after, &wt).map(|record| record.state),
            Some(WorktreeRecord::Owned),
            "the repaired worktree is recorded as this checkout's and not being removed",
        );
        assert!(wt.exists(), "the worktree stands");
    }

    fn worktree_runs_git(wt: &Path) -> bool {
        std::process::Command::new("git")
            .args(["rev-parse", "--show-toplevel"])
            .current_dir(wt)
            .output()
            .is_ok_and(|out| out.status.success())
    }

    fn copy_tree(from: &Path, to: &Path) {
        let status = std::process::Command::new("cp")
            .arg("-a")
            .arg(from)
            .arg(to)
            .status()
            .expect("spawn cp");
        assert!(status.success(), "cp -a {from:?} {to:?}");
    }

    /// `cp -a` of a repo copies the worktree admin dirs too, and their
    /// `gitdir` files still resolve at the ORIGINAL repo's worktree. The
    /// copy must not read that as its own stale registration: the stale
    /// fallback runs only when the listed path no longer resolves.
    #[test]
    fn a_copied_repo_does_not_claim_the_original_worktree_registration() {
        let dir = init_repo_with_commit();
        add_worker_worktree(dir.path(), "lbl");
        let holder = tempdir().expect("holder");
        let clone = holder.path().join("clone");
        copy_tree(dir.path(), &clone);
        let clone_wt = clone.join(".claude").join("worktrees").join("lbl");

        assert!(
            matches!(worktree_registration(&clone, &clone_wt), Some(WorktreeRegistration::Absent)),
            "the copied registration names the original worktree, which still resolves",
        );
        assert!(!worktree_registered(&clone, &clone_wt), "and is not this copy's registration");
    }

    /// A project that is itself a linked worktree keeps its git dir in the
    /// main repo's common dir, and a worker worktree created inside it is
    /// registered there too. Ownership must be compared against
    /// `git rev-parse --git-common-dir`, not `<repo>/.git`, or such a
    /// project never matches its own worktree's link.
    #[test]
    fn orphan_removal_clears_a_leftover_in_a_project_that_is_a_linked_worktree() {
        let dir = init_repo_with_commit();
        let linked = dir.path().join("linked");
        run_git(
            dir.path(),
            &["worktree", "add", "-q", "-b", "linked", linked.to_str().expect("utf8 path")],
        );
        let wt = linked.join(".claude").join("worktrees").join("lbl");
        run_git(
            &linked,
            &["worktree", "add", "-q", "-b", "worktree-lbl", wt.to_str().expect("utf8 path")],
        );
        record_worktree_state(&linked, "lbl", &wt, WorktreeRecord::Removing);
        fs::remove_dir_all(dir.path().join(".git").join("worktrees").join("lbl"))
            .expect("deregister the worktree under the common dir");

        remove_orphaned_worktree_dir(&linked, &wt)
            .expect("its own leftover clears under a linked worktree");

        assert!(!wt.exists(), "the leftover directory is gone");
    }

    fn branch_exists(repo: &Path, branch: &str) -> bool {
        let out = std::process::Command::new("git")
            .args(["rev-parse", "--verify", "--quiet", &format!("refs/heads/{branch}")])
            .current_dir(repo)
            .output()
            .expect("spawn git");
        match out.status.code() {
            Some(0) => true,
            Some(1) => false,
            other => panic!("git rev-parse in {repo:?} exited {other:?}, so absence is unproven"),
        }
    }

    /// Init a repo with one commit plus a claude-shaped worker worktree:
    /// `worktree add -b worktree-<label>` at `.claude/worktrees/<label>`.
    /// The worktree is left in place; tests that reap remove it first,
    /// matching the despawn order.
    fn init_repo_with_worker_worktree(
        label: &str,
    ) -> (tempfile::TempDir, std::path::PathBuf, String) {
        let dir = init_repo_with_commit();
        let branch = add_worker_worktree(dir.path(), label);
        let wt = dir.path().join(".claude").join("worktrees").join(label);
        (dir, wt, branch)
    }

    /// `worktree add -b worktree-<label>` off the current HEAD: the branch
    /// claude's `--worktree <label>` names, though not the base it would
    /// use. Returns the branch name.
    fn add_worker_worktree(repo: &Path, label: &str) -> String {
        let branch = format!("worktree-{label}");
        let wt = repo.join(".claude").join("worktrees").join(label);
        run_git(repo, &["worktree", "add", "-q", "-b", &branch, wt.to_str().expect("utf8 path")]);
        branch
    }

    /// The gitdir a worktree's `.git` link names.
    fn worktree_gitdir(wt: &Path) -> PathBuf {
        let link = fs::read_to_string(wt.join(".git")).expect("the worktree's link");
        let gitdir = link.trim().strip_prefix("gitdir:").expect("a gitdir link").trim();
        PathBuf::from(gitdir)
    }

    fn git_stdout(repo: &Path, args: &[&str]) -> String {
        let out = std::process::Command::new("git")
            .args(args)
            .current_dir(repo)
            .output()
            .expect("spawn git");
        assert!(out.status.success(), "git {args:?} failed in {repo:?}");
        String::from_utf8_lossy(&out.stdout).trim().to_owned()
    }

    fn drop_worktree(repo: &Path, wt: &Path) {
        run_git(repo, &["worktree", "remove", "--force", wt.to_str().expect("utf8 path")]);
    }

    /// The shape a despawn's failed removal leaves: the directory survives
    /// with no registration at all, because git deregisters a worktree
    /// before it walks the tree. `git worktree remove` cannot reach this
    /// state itself (it deletes the directory too), so the registration's
    /// admin dir is what the fixture drops.
    fn deregister_worktree(repo: &Path, name: &str) {
        fs::remove_dir_all(repo.join(".git").join("worktrees").join(name))
            .expect("drop the registration");
    }

    #[test]
    fn reaps_a_pristine_worker_branch() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        drop_worktree(dir.path(), &wt);
        assert_eq!(reap_worktree_branch(dir.path(), &branch), BranchReapOutcome::Reaped);
        assert!(!branch_exists(dir.path(), &branch), "the ref is actually gone");
    }

    /// The reachability premise itself: a branch whose commits survive only
    /// on a remote-tracking ref is still reapable, because deleting the
    /// local ref strands nothing.
    #[test]
    fn reaps_a_branch_whose_commits_live_on_a_remote_ref() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(&wt, &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")]);
        fs::write(wt.join("work.txt"), "pushed work").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        run_git(&wt, &["push", "-q", "-u", "origin", &branch]);
        drop_worktree(dir.path(), &wt);

        assert_eq!(reap_worktree_branch(dir.path(), &branch), BranchReapOutcome::Reaped);
        assert!(!branch_exists(dir.path(), &branch), "the local ref goes, the commits do not");
    }

    #[test]
    fn keeps_a_branch_holding_unique_commits() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        fs::write(wt.join("work.txt"), "a worker committed here").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        drop_worktree(dir.path(), &wt);

        let outcome = reap_worktree_branch(dir.path(), &branch);
        let BranchReapOutcome::Kept { count, tip } = outcome else {
            panic!("a branch with its own commit is kept, got {outcome:?}");
        };
        assert_eq!(count, 1, "the one commit reachable from no other ref");
        assert_eq!(
            tip,
            git_stdout(dir.path(), &["rev-parse", "--short", &branch]),
            "the warning names the BRANCH tip, so 'git log <tip>' lands in the right history",
        );
        assert!(branch_exists(dir.path(), &branch), "the branch survives");
    }

    /// The squash trap: the content landed on the default branch but the
    /// shape did not, so `git cherry` reports nothing unique here and a
    /// patch-id gate would delete it.
    #[test]
    fn keeps_a_squash_merged_branch() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        fs::write(wt.join("work.txt"), "a worker committed here").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        run_git(dir.path(), &["merge", "-q", "--squash", &branch]);
        run_git(dir.path(), &["commit", "-q", "-m", "squashed the worker's work"]);
        drop_worktree(dir.path(), &wt);

        assert!(
            git_stdout(dir.path(), &["cherry", "HEAD", &branch]).starts_with("- "),
            "fixture precondition: the squash is patch-identical, so a patch-id gate reaps it",
        );
        assert!(
            matches!(reap_worktree_branch(dir.path(), &branch), BranchReapOutcome::Kept { .. }),
            "a squash-merged branch still holds its own commit object",
        );
        assert!(branch_exists(dir.path(), &branch));
    }

    /// `git branch -d` refuses this exact shape - pristine branch, tip not
    /// an ancestor of HEAD - so the reap must not delegate to git's
    /// merged-ness inference. The precondition is asserted so the fixture
    /// cannot stop exercising the shape silently.
    #[test]
    fn reaps_a_pristine_branch_whose_tip_is_not_an_ancestor_of_head() {
        let dir = init_repo_with_commit();
        // The operator's own branch, parked at the first commit, then the
        // worker's worktree branches off a newer one.
        run_git(dir.path(), &["branch", "operator-work"]);
        fs::write(dir.path().join("README.md"), "advanced").expect("write advance");
        run_git(dir.path(), &["commit", "-qam", "advance"]);
        let branch = add_worker_worktree(dir.path(), "lbl");
        drop_worktree(dir.path(), &dir.path().join(".claude").join("worktrees").join("lbl"));
        run_git(dir.path(), &["checkout", "-q", "operator-work"]);

        let not_ancestor = std::process::Command::new("git")
            .args(["merge-base", "--is-ancestor", &branch, "HEAD"])
            .current_dir(dir.path())
            .status()
            .expect("spawn git");
        assert!(!not_ancestor.success(), "fixture precondition: the tip is ahead of HEAD");

        assert_eq!(reap_worktree_branch(dir.path(), &branch), BranchReapOutcome::Reaped);
        assert!(!branch_exists(dir.path(), &branch));
    }

    #[test]
    fn missing_branch_is_a_noop() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        drop_worktree(dir.path(), &wt);
        assert_eq!(
            reap_worktree_branch(dir.path(), "worktree-never-existed"),
            BranchReapOutcome::NotPresent
        );
    }

    #[test]
    fn ensure_worker_worktree_leaves_an_existing_worktree_alone() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("no-op");
        assert_eq!(outcome, WorktreeEnsure::AlreadyPresent, "nothing was touched");
        assert!(wt.exists());
        assert_eq!(worktree_branch(&wt).as_deref(), Some(branch.as_str()));
    }

    /// A dirty existing worktree is still a no-op: the uncommitted file
    /// and the branch must survive ensure, so a force-recreate mutation
    /// that wipes the checkout cannot pass.
    #[test]
    fn ensure_worker_worktree_never_touches_a_dirty_existing_worktree() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        fs::write(wt.join("uncommitted.txt"), "in flight").expect("write uncommitted");
        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("no-op");
        assert_eq!(outcome, WorktreeEnsure::AlreadyPresent);
        assert!(wt.join("uncommitted.txt").exists(), "the uncommitted work survives ensure");
    }

    /// The despawn-kept-branch shape: the worktree was removed but the
    /// branch survives (it held unreachable commits). Reattaching it must
    /// bring the branch's content back with it, or the resumed worker
    /// returns to an empty checkout.
    #[test]
    fn ensure_worker_worktree_reattaches_a_surviving_branch() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        fs::write(wt.join("work.txt"), "a worker committed here").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        drop_worktree(dir.path(), &wt);
        assert!(!wt.exists(), "fixture precondition: the worktree is gone");
        assert!(branch_ref_exists(dir.path(), &branch), "fixture precondition: branch kept");

        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("reattach succeeds");
        assert_eq!(
            outcome,
            WorktreeEnsure::AttachedExistingBranch,
            "the branch predates the call, so a rollback must spare it"
        );
        assert!(wt.exists(), "the worktree exists again");
        assert_eq!(worktree_branch(&wt).as_deref(), Some(branch.as_str()));
        assert!(wt.join("work.txt").exists(), "reattaching the branch restores its content");
    }

    /// The incident (#1767): a despawn's removal failed part-way, leaving
    /// the directory with NO registration - a late write into the dir
    /// makes `git worktree remove` fail after git has already deregistered
    /// the path - and `ensure` then answered `AlreadyPresent` over it, so
    /// the resumed child ran `--worktree` and git refused the occupied
    /// path before the initialize handshake. The leftover must be cleared
    /// deliberately and the worktree recreated.
    #[test]
    fn ensure_worker_worktree_clears_a_leftover_dir_git_no_longer_tracks() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        // The despawn records the admitted removal before git runs.
        record_worktree_state(dir.path(), "lbl", &wt, WorktreeRecord::Removing);
        deregister_worktree(dir.path(), "lbl");
        fs::write(wt.join("late-write.txt"), "wrote while dying").expect("late write");
        assert!(wt.exists(), "fixture precondition: the directory is still there");
        assert!(
            !worktree_registered(dir.path(), &wt),
            "fixture precondition: git no longer lists the path",
        );

        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("the leftover clears");

        assert_eq!(
            outcome,
            WorktreeEnsure::AttachedExistingBranch,
            "the branch predates the call and may hold real work, so it is reused",
        );
        assert!(wt.exists(), "the worktree stands again");
        assert_eq!(worktree_branch(&wt).as_deref(), Some(branch.as_str()));
        assert!(!wt.join("late-write.txt").exists(), "the leftover's death-throes write is gone");
        assert_eq!(
            recorded_worktree(dir.path(), &wt).map(|record| record.state),
            Some(WorktreeRecord::Owned),
            "a created worktree is recorded as this checkout's",
        );
    }

    /// A path that is not a plain directory cannot be cleared as a
    /// leftover, and answering `AlreadyPresent` over it is what let the
    /// resumed child die behind the transport's message. The refusal names
    /// the path instead of pretending the worktree is there.
    #[test]
    fn ensure_worker_worktree_refuses_a_leftover_that_is_not_a_directory() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(wt.parent().expect("worktrees dir")).expect("mkdir worktrees");
        fs::write(&wt, "a file where the worktree goes").expect("write a file at the path");

        let err = ensure_worker_worktree(dir.path(), "lbl", &wt).expect_err("a file is refused");

        assert!(
            matches!(err, WorktreeError::NotAPlainDirectory(ref at) if at.ends_with("lbl")),
            "the refusal names the occupied path: {err:?}",
        );
    }

    /// The despawn-reaped-branch shape: nothing on the branch was
    /// unreachable, so despawn deleted it. A repo with no remote default
    /// has no origin base to cut from, so the branch is recreated at the
    /// local HEAD - the fallback [`ensure_worker_worktree`] documents.
    #[test]
    fn ensure_worker_worktree_recreates_the_branch_when_reaped() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        drop_worktree(dir.path(), &wt);
        assert_eq!(
            reap_worktree_branch(dir.path(), "worktree-lbl"),
            BranchReapOutcome::Reaped,
            "fixture precondition: despawn reaped the branch"
        );
        assert!(!wt.exists());

        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("recreate succeeds");
        assert_eq!(outcome, WorktreeEnsure::CreatedWithNewBranch);
        assert!(wt.exists());
        assert_eq!(worktree_branch(&wt).as_deref(), Some("worktree-lbl"));
        assert_eq!(
            git_stdout(dir.path(), &["rev-parse", "worktree-lbl"]),
            git_stdout(dir.path(), &["rev-parse", "HEAD"]),
            "the recreated branch starts at the repo's current HEAD"
        );
    }

    /// claude's own `--worktree` cuts a fresh branch from
    /// `origin/<default-branch>` (`worktree.baseRef` defaults to `fresh`),
    /// so a resume that recreates the branch must start there too. Cutting
    /// at the local HEAD starts a resumed worker from a commit its
    /// launcher would not have chosen whenever HEAD is ahead (#1594).
    #[test]
    fn ensure_worker_worktree_cuts_a_recreated_branch_from_the_origin_base() {
        let dir = init_repo_with_commit();
        let origin = git_stdout(dir.path(), &["rev-parse", "HEAD"]);
        // The remote's default branch sits where the clone found it...
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/main", &origin]);
        run_git(
            dir.path(),
            &["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/main"],
        );
        // ...and local HEAD moves on ahead of it.
        fs::write(dir.path().join("README.md"), "local work").expect("write advance");
        run_git(dir.path(), &["commit", "-qam", "local ahead"]);
        let local = git_stdout(dir.path(), &["rev-parse", "HEAD"]);
        assert_ne!(origin, local, "fixture precondition: local HEAD is ahead of the origin base");

        let wt = dir.path().join(".claude").join("worktrees").join("lbl");
        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("recreate succeeds");

        assert_eq!(outcome, WorktreeEnsure::CreatedWithNewBranch);
        assert_eq!(
            git_stdout(dir.path(), &["rev-parse", "worktree-lbl"]),
            origin,
            "the new branch starts at origin/HEAD's commit, the base claude's own path uses",
        );
    }

    /// An `origin/HEAD` naming a ref the remote no longer carries is not a
    /// base git can resolve: the recreate falls back to the local HEAD
    /// rather than refusing the whole resume.
    #[test]
    fn ensure_worker_worktree_falls_back_when_origin_head_dangles() {
        let dir = init_repo_with_commit();
        let local = git_stdout(dir.path(), &["rev-parse", "HEAD"]);
        run_git(
            dir.path(),
            &["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/gone"],
        );
        let wt = dir.path().join(".claude").join("worktrees").join("lbl");

        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("recreate succeeds");

        assert_eq!(outcome, WorktreeEnsure::CreatedWithNewBranch);
        assert_eq!(
            git_stdout(dir.path(), &["rev-parse", "worktree-lbl"]),
            local,
            "the local HEAD is the fallback when the origin base does not resolve",
        );
    }

    /// The branch is checked out in a second worktree, so `git worktree
    /// add` at the label path cannot attach it. ensure reports the
    /// failure with git's stderr instead of pretending to succeed.
    #[test]
    fn ensure_worker_worktree_fails_when_the_branch_is_checked_out_elsewhere() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        drop_worktree(dir.path(), &wt);
        let second = dir.path().join("elsewhere");
        run_git(
            dir.path(),
            &["worktree", "add", "-q", second.to_str().expect("utf8"), "worktree-lbl"],
        );

        let err = ensure_worker_worktree(dir.path(), "lbl", &wt).expect_err("attach is refused");
        assert!(
            matches!(err, WorktreeError::CreateFailed(ref reason) if reason.contains("worktree-lbl")),
            "the error carries git's stderr naming the branch: {err:?}"
        );
        assert!(!wt.exists(), "the failed add leaves no worktree behind");
    }

    /// The measured silent case: claude is handed `--worktree lbl`, the
    /// branch is checked out elsewhere, the creation does nothing - and the
    /// session starts anyway. The obstacle is what lets the spawn refuse it.
    #[test]
    fn obstacle_names_a_branch_checked_out_elsewhere() {
        let repo = init_repo_with_commit();
        let elsewhere = repo.path().join("elsewhere");
        run_git(
            repo.path(),
            &["worktree", "add", "-q", "-b", "worktree-lbl", elsewhere.to_str().expect("utf8")],
        );
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");

        let obstacle = worktree_creation_obstacle(repo.path(), "lbl", &wt)
            .expect("the branch held elsewhere is an obstacle");

        assert!(
            obstacle.contains("worktree-lbl") && obstacle.contains("already checked out"),
            "the obstacle names the branch and what holds it: {obstacle}"
        );
    }

    /// The worker's own worktree is where a fresh re-spawn lands, and the
    /// worktree there is reused as it stands.
    #[test]
    fn obstacle_is_none_for_the_workers_own_worktree() {
        let repo = init_repo_with_commit();
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(wt.parent().expect("worktrees dir")).expect("mkdir worktrees");
        run_git(
            repo.path(),
            &["worktree", "add", "-q", "-b", "worktree-lbl", wt.to_str().expect("utf8")],
        );

        assert_eq!(
            worktree_creation_obstacle(repo.path(), "lbl", &wt),
            None,
            "a worktree registered at the worker's own path is not an obstacle",
        );
    }

    #[test]
    fn obstacle_is_none_where_the_worktree_can_be_created() {
        let repo = init_repo_with_commit();
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");

        assert_eq!(worktree_creation_obstacle(repo.path(), "lbl", &wt), None);
    }

    /// git takes a path that is absent or an EMPTY directory, so an empty
    /// one is not in its way. Refusing it would strand the label: a `mkdir`
    /// or a cleanup that empties the directory would block every spawn of
    /// it until someone removed the directory by hand.
    #[test]
    fn obstacle_is_none_for_an_empty_directory() {
        let repo = init_repo_with_commit();
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("empty worktrees dir");

        assert_eq!(
            worktree_creation_obstacle(repo.path(), "lbl", &wt),
            None,
            "an empty directory is a path git will take",
        );
    }

    /// claude locks every worktree it creates and git will not prune a
    /// locked registration, so the remedy has to clear the lock first:
    /// measured, `worktree prune` alone exits 0 having done nothing and
    /// the same refusal comes back byte-identical.
    #[test]
    fn obstacle_remedy_unlocks_before_pruning() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        run_git(dir.path(), &["worktree", "lock", wt.to_str().expect("utf8 path")]);
        fs::remove_dir_all(&wt).expect("delete the worktree directory");

        let obstacle = worktree_creation_obstacle(dir.path(), "lbl", &wt)
            .expect("a locked registration with no directory is an obstacle");

        let unlock = obstacle.find("worktree unlock").expect("the remedy clears the lock");
        let prune = obstacle.find("worktree prune").expect("and then clears the registration");
        assert!(
            unlock < prune,
            "the order is the remedy, not the pair of names: unlock comes first in {obstacle}"
        );
    }

    #[test]
    fn obstacle_names_a_path_taken_by_something_else() {
        let repo = init_repo_with_commit();
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(&wt).expect("stray dir");
        fs::write(wt.join("notes.txt"), "hand-made").expect("stray file");

        let obstacle = worktree_creation_obstacle(repo.path(), "lbl", &wt)
            .expect("a stray directory at the path is an obstacle");

        assert!(
            obstacle.contains("is not an empty directory"),
            "the obstacle names what is in the way: {obstacle}"
        );
    }

    /// A listing with nothing but paths and branches: no `prunable` line, as
    /// a git older than 2.36 prints for every stranded entry, and no `locked`
    /// marker either. Written against the listing rather than against git,
    /// since no git on this machine prints that older shape: an entry at the
    /// worker's path it cannot reuse would otherwise go unrefused, which is
    /// #1303 returning. The predicate reads no marker lines, so what the
    /// fixture pins is that they are not needed.
    #[test]
    fn obstacle_refuses_an_entry_whose_listing_says_nothing_about_it() {
        let repo = Path::new("/repo");
        let path = Path::new("/repo/.claude/worktrees/lbl");
        let listing = "worktree /repo\nbranch refs/heads/main\n\n\
                       worktree /repo/.claude/worktrees/lbl\nbranch refs/heads/worktree-lbl\n";
        assert!(
            !listing.contains("prunable") && !listing.contains("locked"),
            "fixture precondition: the listing carries neither marker, the older git shape",
        );
        let entries = listed_worktrees(listing);

        let obstacle = obstacle_from_listing(&entries, repo, "worktree-lbl", path)
            .expect("a registration whose gitdir cannot resolve is an obstacle");

        assert!(
            obstacle.contains("registration at"),
            "the obstacle names the registration that cannot be reused: {obstacle}"
        );
    }

    /// **A gitdir that exists is not a usable worktree gitdir.** The
    /// spawn-time check read only whether the linked directory was there,
    /// so four states git's own reuse probe refuses - a link that is a
    /// symlink, a gitdir with no HEAD, a HEAD naming a deleted branch, and
    /// a link into another repository - all read as reusable and the spawn
    /// started with nowhere to work (#1593).
    #[test]
    fn obstacle_refuses_a_registration_whose_gitdir_git_cannot_reuse() {
        // A symlink standing in for the link file is not what git writes.
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let real = wt.join("real-link");
        fs::rename(wt.join(".git"), &real).expect("move the link aside");
        std::os::unix::fs::symlink(&real, wt.join(".git")).expect("symlink the link");
        assert!(
            worktree_creation_obstacle(dir.path(), "lbl", &wt).is_some(),
            "a symlinked .git link is not a registration git reuses",
        );

        // A gitdir whose HEAD is gone.
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let gitdir = worktree_gitdir(&wt);
        fs::remove_file(gitdir.join("HEAD")).expect("remove HEAD");
        assert!(
            worktree_creation_obstacle(dir.path(), "lbl", &wt).is_some(),
            "a gitdir with no HEAD cannot be reused",
        );

        // A HEAD naming a branch the repo deleted.
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let gitdir = worktree_gitdir(&wt);
        fs::write(gitdir.join("HEAD"), "ref: refs/heads/gone\n").expect("point HEAD at nothing");
        assert!(
            worktree_creation_obstacle(dir.path(), "lbl", &wt).is_some(),
            "a HEAD naming a deleted branch cannot be reused",
        );

        // A link pointing into another repository: its gitdir's own back
        // link names that repository's worktree, not this one.
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let (_other, other_wt, _other_branch) = init_repo_with_worker_worktree("lbl");
        let other_gitdir = worktree_gitdir(&other_wt);
        fs::write(wt.join(".git"), format!("gitdir: {}\n", other_gitdir.display()))
            .expect("point at another repository");
        assert!(
            worktree_creation_obstacle(dir.path(), "lbl", &wt).is_some(),
            "another repository's worktree gitdir is not this worktree's",
        );
    }

    /// A worktree whose `.git` link file is gone while its directory stands,
    /// LOCKED - which is claude's own shape, since it locks every worktree it
    /// creates. git refuses to add a worktree there (exit 128), and a locked
    /// entry carries no `prunable` line to say so, which is why the state is
    /// read from the link itself rather than from that flag.
    #[test]
    fn obstacle_refuses_a_locked_worktree_whose_gitdir_link_is_broken() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        run_git(dir.path(), &["worktree", "lock", wt.to_str().expect("utf8 path")]);
        fs::remove_file(wt.join(".git")).expect("delete the worktree's gitdir link");
        assert!(wt.is_dir(), "fixture precondition: the directory itself stands");

        let obstacle = worktree_creation_obstacle(dir.path(), "lbl", &wt)
            .expect("a worktree git will not reuse is an obstacle");

        assert!(
            obstacle.contains("cannot be reused"),
            "the obstacle names the registration git will not reuse: {obstacle}"
        );
    }

    /// A dangling symlink at the path is a path git refuses (`already
    /// exists`, exit 128 - measured), and one `exists()` cannot see: it
    /// follows the link and answers false. Admitting it starts the worker
    /// with no worktree, which is the bug this check exists for.
    #[test]
    fn obstacle_refuses_a_dangling_symlink_at_the_path() {
        let repo = init_repo_with_commit();
        let wt = repo.path().join(".claude").join("worktrees").join("lbl");
        fs::create_dir_all(wt.parent().expect("worktrees dir")).expect("mkdir worktrees");
        std::os::unix::fs::symlink(repo.path().join("nowhere"), &wt).expect("dangling symlink");

        let obstacle = worktree_creation_obstacle(repo.path(), "lbl", &wt)
            .expect("a symlink git refuses is an obstacle");

        assert!(
            obstacle.contains("is not an empty directory"),
            "the obstacle names what is in the way: {obstacle}"
        );
    }

    #[test]
    fn discard_worker_worktree_removes_a_minted_worktree_and_branch() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        drop_worktree(dir.path(), &wt);
        assert_eq!(
            reap_worktree_branch(dir.path(), &branch),
            BranchReapOutcome::Reaped,
            "fixture precondition: the branch is gone, so ensure must mint it"
        );
        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("recreate succeeds");
        assert_eq!(outcome, WorktreeEnsure::CreatedWithNewBranch);

        let warning = discard_worker_worktree(dir.path(), "lbl", &wt, outcome);
        assert!(warning.is_none(), "a clean discard warns about nothing: {warning:?}");
        assert!(!wt.exists(), "the minted worktree is gone");
        assert!(!branch_exists(dir.path(), &branch), "the minted branch is reaped");
    }

    /// The attach case is the data-loss guard: the branch predates the
    /// ensure and may hold the worker's only copy of its commits, so a
    /// rollback removes the worktree and spares the branch.
    #[test]
    fn discard_worker_worktree_keeps_a_pre_existing_branch() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        fs::write(wt.join("work.txt"), "a worker committed here").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        drop_worktree(dir.path(), &wt);
        let outcome = ensure_worker_worktree(dir.path(), "lbl", &wt).expect("reattach succeeds");
        assert_eq!(outcome, WorktreeEnsure::AttachedExistingBranch);

        let warning = discard_worker_worktree(dir.path(), "lbl", &wt, outcome);
        assert!(warning.is_none(), "a clean discard warns about nothing: {warning:?}");
        assert!(!wt.exists(), "the worktree ensure created is gone");
        assert!(branch_exists(dir.path(), &branch), "the pre-existing branch survives");
        assert_eq!(
            git_stdout(dir.path(), &["rev-list", "--count", &branch]),
            "2",
            "the branch's two commits (seed + the worker's) are all still reachable"
        );
    }

    #[test]
    fn discard_worker_worktree_is_a_noop_when_ensure_touched_nothing() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let warning =
            discard_worker_worktree(dir.path(), "lbl", &wt, WorktreeEnsure::AlreadyPresent);
        assert!(warning.is_none());
        assert!(wt.exists(), "an already-present worktree is left alone");
    }

    #[test]
    fn a_refused_delete_is_not_reported_as_a_verification_failure() {
        let (dir, _wt, branch) = init_repo_with_worker_worktree("lbl");
        let outcome = reap_worktree_branch(dir.path(), &branch);
        let BranchReapOutcome::DeleteFailed { reason } = outcome else {
            panic!("a refused delete reports DeleteFailed, got {outcome:?}");
        };
        assert!(!reason.is_empty(), "the warning can name git's complaint");
        assert!(branch_exists(dir.path(), &branch), "the branch survives a refused delete");
    }

    #[test]
    fn keeps_on_error_when_the_path_is_not_a_repo() {
        let dir = tempdir().expect("tempdir");
        assert!(
            matches!(
                reap_worktree_branch(dir.path(), "worktree-lbl"),
                BranchReapOutcome::KeptOnError { .. }
            ),
            "a repo we cannot read is never treated as a branch that does not exist",
        );
    }

    #[test]
    fn branch_ref_exists_separates_present_from_absent() {
        let (dir, _wt, branch) = init_repo_with_worker_worktree("lbl");
        assert!(branch_ref_exists(dir.path(), &branch));
        assert!(!branch_ref_exists(dir.path(), "never-created"));
    }

    /// The reap counts a remote-tracking ref as reachability and so deletes
    /// a pushed local head. Existence has to count the same ref or the two
    /// disagree about a branch that is still open for review.
    #[test]
    fn branch_ref_exists_counts_a_branch_that_only_survives_on_a_remote() {
        let (dir, wt, branch) = init_repo_with_worker_worktree("lbl");
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(&wt, &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")]);
        fs::write(wt.join("work.txt"), "pushed work").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        run_git(&wt, &["push", "-q", "-u", "origin", &branch]);
        drop_worktree(dir.path(), &wt);
        assert_eq!(reap_worktree_branch(dir.path(), &branch), BranchReapOutcome::Reaped);

        assert!(!branch_exists(dir.path(), &branch), "the local head really is gone");
        assert!(
            branch_ref_exists(dir.path(), &branch),
            "a branch alive only on a remote still exists for review purposes",
        );
    }

    /// A slashed name must not let the remote-ref glob over-match.
    #[test]
    fn branch_ref_exists_handles_a_slashed_branch_name() {
        let (dir, wt, _branch) = init_repo_with_worker_worktree("lbl");
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(&wt, &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")]);
        run_git(&wt, &["checkout", "-q", "-b", "fix/deep/name"]);
        run_git(&wt, &["push", "-q", "-u", "origin", "fix/deep/name"]);
        run_git(&wt, &["checkout", "-q", "-"]);
        run_git(dir.path(), &["branch", "-D", "fix/deep/name"]);

        assert!(branch_ref_exists(dir.path(), "fix/deep/name"));
        assert!(!branch_ref_exists(dir.path(), "fix/deep"));
    }

    /// The existing coverage slashes the BRANCH name; this slashes the
    /// REMOTE, which is what the old `refs/remotes/*/<branch>` pattern
    /// could not see - `*` does not cross `/`. Empty stdout, exit 0, and
    /// on the despawn path empty is what deletes.
    #[test]
    fn branch_ref_exists_sees_a_branch_behind_a_slash_bearing_remote() {
        let dir = init_repo_with_commit();
        run_git(dir.path(), &["update-ref", "refs/remotes/gh/upstream/feat/pushed", "HEAD"]);
        assert!(
            branch_ref_exists(dir.path(), "feat/pushed"),
            "a branch surviving only on a slash-named remote is still present",
        );
        assert!(!branch_ref_exists(dir.path(), "feat/never-existed"));
    }

    /// A project path nested inside a repo cannot be judged, so it reads
    /// as present. Sharing the parser brings the work-tree-root check
    /// with it: previously this answered from the ancestor's refs and
    /// could delete on them.
    #[test]
    fn branch_ref_exists_reads_a_nested_path_as_present() {
        let dir = init_repo_with_commit();
        let nested = dir.path().join("crates");
        fs::create_dir_all(&nested).expect("mkdir");
        assert!(branch_ref_exists(&nested, "anything-at-all"));
    }

    #[test]
    fn branch_ref_exists_reads_an_unreadable_repo_as_present() {
        let dir = tempdir().expect("tempdir");
        assert!(
            branch_ref_exists(dir.path(), "worktree-lbl"),
            "a repo we cannot read must not read as a branch that is gone",
        );
    }

    /// The PostToolUse tool_response of a real isolation:"worktree" Agent
    /// call that left an uncommitted file, captured on CLI 2.1.220
    /// (absolute path redacted). The worktree fields are flat and
    /// top-level; a completed call that changed nothing carries none of
    /// them, and an async launch carries none either.
    fn kept_worktree_response(path: &str, branch: &str) -> serde_json::Value {
        serde_json::json!({
            "status": "completed",
            "prompt": "Create a file named kept.txt in the repo root containing the word hello. Do not commit it. When finished, reply with just the word done.",
            "agentId": "ac437073a41a2149d",
            "agentType": "general-purpose",
            "content": [{ "type": "text", "text": "done" }],
            "resolvedModel": "glm-5.3-flash",
            "totalDurationMs": 111_649,
            "totalTokens": 35201,
            "totalToolUseCount": 8,
            "usage": {
                "input_tokens": 190,
                "cache_creation_input_tokens": 0,
                "cache_read_input_tokens": 35008,
                "output_tokens": 3,
                "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 0 },
                "service_tier": "standard",
            },
            "toolStats": { "editFileCount": 1, "linesAdded": 2, "linesRemoved": 0 },
            "worktreePath": path,
            "worktreeBranch": branch,
        })
    }

    /// The tool_response of a real async isolation:"worktree" launch,
    /// captured on CLI 2.1.220. It names no worktree: the subagent is
    /// about to run in it, so a parse that found a path here would reap a
    /// live agent's tree.
    fn async_launch_response(output_file: &str) -> serde_json::Value {
        serde_json::json!({
            "isAsync": true,
            "status": "async_launched",
            "agentId": "a01ffe965157f5add",
            "description": "capture async",
            "resolvedModel": "glm-5.3-flash",
            "prompt": "sleep then done",
            "outputFile": output_file,
            "canReadOutputFile": true,
        })
    }

    fn agent_input() -> serde_json::Value {
        serde_json::json!({ "isolation": "worktree", "prompt": "review it" })
    }

    /// The CLI auto-cleans a no-changes worktree and names no path in the
    /// response; that population must parse as None, never as a miss that
    /// guesses.
    #[test]
    fn completed_agent_worktree_ignores_a_completed_response_without_a_worktree() {
        let mut response = kept_worktree_response("/repo/.claude/worktrees/agent-abc123", "w");
        response.as_object_mut().expect("object").remove("worktreePath");
        response.as_object_mut().expect("object").remove("worktreeBranch");
        assert!(completed_agent_worktree("Agent", &agent_input(), &response).is_none());
    }

    /// An async launch's worktree is about to be a live agent's cwd; the
    /// response naming no path is what keeps the reap off it.
    #[test]
    fn completed_agent_worktree_never_reaps_an_async_launch() {
        assert!(
            completed_agent_worktree(
                "Agent",
                &agent_input(),
                &async_launch_response("/tmp/tasks/a01ffe965157f5add.output")
            )
            .is_none()
        );
    }

    #[test]
    fn is_isolated_agent_call_tracks_the_gate_population() {
        assert!(is_isolated_agent_call("Agent", &agent_input()));
        assert!(is_isolated_agent_call("Task", &agent_input()));
        assert!(!is_isolated_agent_call("EnterWorktree", &agent_input()));
        assert!(!is_isolated_agent_call("Agent", &serde_json::json!({ "prompt": "plain" })));
    }

    #[test]
    fn completed_agent_worktree_parses_the_managed_path_and_branch() {
        let wt = completed_agent_worktree(
            "Agent",
            &agent_input(),
            &kept_worktree_response(
                "/repo/.claude/worktrees/agent-a83052083ca02b1ce",
                "worktree-agent-a83052083ca02b1ce",
            ),
        )
        .expect("an isolated Agent completion yields its worktree");
        assert_eq!(wt.path, Path::new("/repo/.claude/worktrees/agent-a83052083ca02b1ce"));
        assert_eq!(wt.repo_root, Path::new("/repo"));
        assert_eq!(wt.branch, "worktree-agent-a83052083ca02b1ce");
    }

    #[test]
    fn completed_agent_worktree_derives_the_branch_when_the_response_omits_it() {
        let response = serde_json::json!({
            "worktreePath": "/repo/.claude/worktrees/agent-abc123",
        });
        let wt = completed_agent_worktree("Agent", &agent_input(), &response)
            .expect("a path-only response still yields the worktree");
        assert_eq!(wt.branch, "worktree-agent-abc123", "the CLI's worktree-<slug> convention");
    }

    /// Older CLIs name the tool `Task`; both spellings gate the reap.
    #[test]
    fn completed_agent_worktree_accepts_the_task_spelling() {
        let wt = completed_agent_worktree(
            "Task",
            &agent_input(),
            &kept_worktree_response(
                "/repo/.claude/worktrees/agent-abc123",
                "worktree-agent-abc123",
            ),
        );
        assert!(wt.is_some(), "Task is the pre-rename Agent tool name");
    }

    /// A completed Agent tool result text quotes the worktreePath template;
    /// only a structured field may aim the reap.
    #[test]
    fn completed_agent_worktree_ignores_the_path_when_it_only_appears_in_text() {
        let response = serde_json::json!({
            "content": [{ "type": "text", "text": "worktreePath: /repo/.claude/worktrees/agent-abc123" }],
        });
        assert!(completed_agent_worktree("Agent", &agent_input(), &response).is_none());
    }

    #[test]
    fn completed_agent_worktree_requires_the_isolation_input() {
        let plain = serde_json::json!({ "prompt": "review it" });
        assert!(
            completed_agent_worktree(
                "Agent",
                &plain,
                &kept_worktree_response(
                    "/repo/.claude/worktrees/agent-abc123",
                    "worktree-agent-abc123"
                ),
            )
            .is_none(),
            "a non-isolated Agent call never names a managed worktree",
        );
    }

    /// EnterWorktree's own response also carries worktree fields; the
    /// tool-name gate is what keeps it out of the reap.
    #[test]
    fn completed_agent_worktree_rejects_other_tool_names() {
        assert!(
            completed_agent_worktree(
                "EnterWorktree",
                &agent_input(),
                &kept_worktree_response(
                    "/repo/.claude/worktrees/agent-abc123",
                    "worktree-agent-abc123"
                ),
            )
            .is_none()
        );
    }

    #[test]
    fn completed_agent_worktree_rejects_paths_outside_the_managed_layout() {
        for path in [
            "/repo/other/agent-abc123",
            "/repo/worktrees/agent-abc123",
            "/repo/.claude/worktrees/worker-abc123",
            ".claude/worktrees/agent-abc123",
        ] {
            assert!(
                completed_agent_worktree(
                    "Agent",
                    &agent_input(),
                    &kept_worktree_response(path, "worktree-agent-abc123"),
                )
                .is_none(),
                "{path} is not a managed agent worktree",
            );
        }
    }

    /// The reap counts on the parser's layout guard for its repo root,
    /// so the response walk must find the field at a shallow nesting
    /// (depth cap 6); a deeper shape degrades to the parse-miss log.
    #[test]
    fn completed_agent_worktree_walks_nested_response_objects() {
        let response = serde_json::json!({
            "result": { "worktreePath": "/repo/.claude/worktrees/agent-abc123" },
        });
        let wt = completed_agent_worktree("Agent", &agent_input(), &response)
            .expect("a nested worktreePath is still a structured field");
        assert_eq!(wt.repo_root, Path::new("/repo"));
    }

    fn init_repo_with_agent_worktree(hex: &str) -> (tempfile::TempDir, std::path::PathBuf, String) {
        let dir = init_repo_with_commit();
        let branch = add_worker_worktree(dir.path(), &format!("agent-{hex}"));
        let wt = dir.path().join(".claude").join("worktrees").join(format!("agent-{hex}"));
        (dir, wt, branch)
    }

    fn agent_worktree_for(dir: &Path, hex: &str, branch: &str) -> AgentWorktree {
        AgentWorktree {
            path: dir.join(".claude").join("worktrees").join(format!("agent-{hex}")),
            repo_root: dir.to_path_buf(),
            branch: branch.to_owned(),
        }
    }

    /// The agent fixture whose tree holds an initialized submodule: the
    /// repo gains the submodule and the tree's branch follows it, then
    /// `git submodule update --init` runs in the tree - what a subagent
    /// does - which is what leaves
    /// `<repo>/.git/worktrees/agent-<hex>/modules` behind.
    fn init_repo_with_submodule_agent_worktree(
        hex: &str,
    ) -> (tempfile::TempDir, std::path::PathBuf, String) {
        let (dir, wt, branch) = init_repo_with_agent_worktree(hex);
        let source = tempdir().expect("submodule source tempdir");
        run_git(source.path(), &["init", "-q"]);
        run_git(source.path(), &["config", "commit.gpgsign", "false"]);
        fs::write(source.path().join("sub.txt"), "submodule seed").expect("write seed");
        run_git(source.path(), &["add", "."]);
        run_git(
            source.path(),
            &[
                "-c",
                "user.email=t@example.com",
                "-c",
                "user.name=Test",
                "commit",
                "-q",
                "-m",
                "sub",
            ],
        );
        run_git(
            dir.path(),
            &[
                "-c",
                "protocol.file.allow=always",
                "submodule",
                "add",
                source.path().to_str().expect("utf8 path"),
                "contracts/sub",
            ],
        );
        run_git(dir.path(), &["commit", "-q", "-m", "add submodule"]);
        // The tree is cut from the pre-submodule commit, so its branch has
        // to take the repo's HEAD before the submodule exists to init.
        run_git(&wt, &["reset", "--hard", &git_stdout(dir.path(), &["rev-parse", "HEAD"])]);
        run_git(&wt, &["-c", "protocol.file.allow=always", "submodule", "update", "--init"]);
        (dir, wt, branch)
    }

    /// The shape `git worktree remove` refuses however clean the tree is:
    /// a subagent that ran `git submodule update --init` in its own
    /// worktree, which the reap must still remove. Left unfixed the tree
    /// survives the completion hook AND every spawn-time sweep, so it
    /// leaks instead of being retried away.
    #[test]
    fn reaps_a_clean_agent_worktree_holding_initialized_submodules() {
        let (dir, wt, branch) = init_repo_with_submodule_agent_worktree("abc123");
        // Fixture precondition, and the reason the test exists: git will
        // not remove this tree unforced. Asserted rather than assumed so a
        // git that stops refusing fails here instead of passing without
        // exercising the fix.
        assert!(
            dir.path().join(".git").join("worktrees").join("agent-abc123").join("modules").is_dir(),
            "fixture precondition: the tree's gitdir holds the submodule's modules dir",
        );
        let refused = std::process::Command::new("git")
            .args(["worktree", "remove", wt.to_str().expect("utf8 path")])
            .current_dir(wt.parent().expect("wt parent"))
            .output()
            .expect("spawn git");
        assert!(!refused.status.success(), "fixture precondition: git refuses this tree unforced");
        assert!(wt.exists(), "and the refusal leaves it on disk");

        let outcome = reap_agent_worktree(&agent_worktree_for(dir.path(), "abc123", &branch));

        assert!(
            matches!(outcome, AgentWorktreeReap::Reaped { .. }),
            "a clean tree git refuses by shape is reaped, not leaked: {outcome:?}"
        );
        assert!(!wt.exists(), "the directory is gone");
        assert!(!branch_exists(dir.path(), &branch), "the conventional branch goes with it");
    }

    #[test]
    fn reaps_a_clean_agent_worktree_and_its_conventional_branch() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");
        let agent_wt = agent_worktree_for(dir.path(), "abc123", &branch);

        let outcome = reap_agent_worktree(&agent_wt);

        assert!(
            matches!(outcome, AgentWorktreeReap::Reaped { .. }),
            "a clean completed agent worktree is reaped, got {outcome:?}"
        );
        assert!(!wt.exists(), "the directory is gone");
        assert!(!branch_exists(dir.path(), &branch), "the conventional branch is gone");
    }

    /// target/ and friends are ignored, so the measured leak is
    /// porcelain-clean; a non-empty porcelain means the subagent left real
    /// edits and the CLI handed the tree back deliberately.
    #[test]
    fn keeps_an_agent_worktree_holding_uncommitted_changes() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");
        fs::write(wt.join("notes.md"), "uncommitted").expect("write scratch");
        let agent_wt = agent_worktree_for(dir.path(), "abc123", &branch);

        let outcome = reap_agent_worktree(&agent_wt);

        let AgentWorktreeReap::KeptDirty { reason } = outcome else {
            panic!("a dirty agent worktree is kept, got {outcome:?}");
        };
        assert!(!reason.is_empty());
        assert!(wt.exists(), "the directory survives");
    }

    /// The same committed-branch shape in a repo that HAS remote refs.
    /// The subagent never pushes, so the despawn's unpushed check would
    /// call this dirty; the reap gates on the uncommitted tree alone,
    /// because the branch reap below is what protects committed work.
    /// A tree kept here is re-listed by every sweep.
    #[test]
    fn removes_a_committed_agent_worktree_in_a_repo_with_remote_refs() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");
        run_git(dir.path(), &["update-ref", "refs/remotes/origin/main", "HEAD"]);
        fs::write(wt.join("work.txt"), "committed by the subagent").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        let agent_wt = agent_worktree_for(dir.path(), "abc123", &branch);

        let outcome = reap_agent_worktree(&agent_wt);

        let AgentWorktreeReap::Reaped { branch: branch_outcome } = outcome else {
            panic!("a committed, unpushed branch does not keep the tree, got {outcome:?}");
        };
        assert!(!wt.exists(), "the directory is gone");
        assert!(
            matches!(branch_outcome, BranchReapOutcome::Kept { .. }),
            "the branch keeps the commit no ref reaches, got {branch_outcome:?}"
        );
    }

    /// A subagent that committed its work to the conventional branch leaves
    /// a clean tree; the reachability check keeps the branch.
    #[test]
    fn removes_a_clean_worktree_but_keeps_a_branch_holding_unique_commits() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");
        fs::write(wt.join("work.txt"), "committed by the subagent").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        let agent_wt = agent_worktree_for(dir.path(), "abc123", &branch);

        let outcome = reap_agent_worktree(&agent_wt);

        let AgentWorktreeReap::Reaped { branch: branch_outcome } = outcome else {
            panic!("a clean tree is removed, got {outcome:?}");
        };
        assert!(!wt.exists(), "the directory is gone");
        assert!(
            matches!(branch_outcome, BranchReapOutcome::Kept { .. }),
            "the branch holds a unique commit, got {branch_outcome:?}"
        );
        assert!(branch_exists(dir.path(), &branch));
    }

    /// A subagent may check out its own branch inside the worktree (the
    /// leaked review-971 shape). The reap aims at the conventional branch
    /// only, never at whatever was checked out.
    #[test]
    fn never_aims_at_a_branch_the_subagent_checked_out_itself() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");
        run_git(&wt, &["checkout", "-q", "-b", "review-971"]);
        let agent_wt = agent_worktree_for(dir.path(), "abc123", &branch);

        let outcome = reap_agent_worktree(&agent_wt);

        assert!(
            matches!(outcome, AgentWorktreeReap::Reaped { .. }),
            "the tree is clean, got {outcome:?}"
        );
        assert!(!wt.exists());
        assert!(!branch_exists(dir.path(), &branch), "the conventional branch goes");
        assert!(
            branch_exists(dir.path(), "review-971"),
            "the subagent's own branch is not the reap's target",
        );
    }

    /// A detached worktree HEAD is invisible to the post-removal branch
    /// reap (`--all` reads refs, not linked worktree HEADs), so commits
    /// there would strand on removal. No upstream exists to trip the
    /// unpushed check, and the tree reads porcelain-clean - exactly the
    /// shape the reap otherwise removes.
    #[test]
    fn keeps_a_detached_agent_worktree_whose_commits_no_ref_reaches() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("agent-abc123");
        std::fs::create_dir_all(wt.parent().expect("parent")).expect("mkdir");
        run_git(
            dir.path(),
            &["worktree", "add", "-q", "--detach", wt.to_str().expect("utf8 path")],
        );
        fs::write(wt.join("work.txt"), "committed while detached").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "detached work"]);
        let agent_wt = agent_worktree_for(dir.path(), "abc123", "worktree-agent-abc123");

        let outcome = reap_agent_worktree(&agent_wt);

        let AgentWorktreeReap::KeptUniqueCommit { tip } = outcome else {
            panic!("a detached HEAD holding unique commits keeps the tree, got {outcome:?}");
        };
        assert_eq!(
            tip,
            git_stdout(&wt, &["rev-parse", "HEAD"]),
            "the warning names the full tip, so the commit stays findable"
        );
        assert!(wt.exists(), "the tree survives, and the commit with it");
    }

    /// The second leaked worktree sat on a detached HEAD: no branch to
    /// reap, removal must still work.
    #[test]
    fn removes_a_detached_head_agent_worktree() {
        let dir = init_repo_with_commit();
        let wt = dir.path().join(".claude").join("worktrees").join("agent-abc123");
        std::fs::create_dir_all(wt.parent().expect("parent")).expect("mkdir");
        run_git(
            dir.path(),
            &["worktree", "add", "-q", "--detach", wt.to_str().expect("utf8 path")],
        );
        let agent_wt = agent_worktree_for(dir.path(), "abc123", "worktree-agent-abc123");

        let outcome = reap_agent_worktree(&agent_wt);

        assert!(
            matches!(outcome, AgentWorktreeReap::Reaped { .. }),
            "a detached clean worktree is reaped, got {outcome:?}"
        );
        assert!(!wt.exists());
        assert!(
            !branch_exists(dir.path(), "worktree-agent-abc123"),
            "the conventional branch never existed here"
        );
    }

    #[test]
    fn reports_absent_when_the_worktree_is_already_gone() {
        let dir = init_repo_with_commit();
        let agent_wt = agent_worktree_for(dir.path(), "abc123", "worktree-agent-abc123");

        assert!(
            matches!(reap_agent_worktree(&agent_wt), AgentWorktreeReap::Absent),
            "the CLI's own auto-clean may have removed it first"
        );
    }

    #[test]
    fn reports_not_a_worktree_for_a_plain_directory() {
        let dir = tempdir().expect("tempdir");
        let fake = dir.path().join(".claude").join("worktrees").join("agent-abc123");
        std::fs::create_dir_all(&fake).expect("mkdir");
        let agent_wt = AgentWorktree {
            path: fake,
            repo_root: dir.path().to_path_buf(),
            branch: "worktree-agent-abc123".to_owned(),
        };

        assert!(
            matches!(reap_agent_worktree(&agent_wt), AgentWorktreeReap::NotAWorktree),
            "a directory git does not vouch for is never removed",
        );
    }

    #[test]
    fn stale_agent_worktrees_lists_a_tree_once_its_age_elapses() {
        let (dir, wt, branch) = init_repo_with_agent_worktree("abc123");

        let listed =
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO).expect("listing works");
        assert_eq!(listed.len(), 1, "a fresh tree is stale at age zero: {listed:?}");
        // The listing composes from the canonical base, as the CLI does.
        assert_eq!(
            fs::canonicalize(&listed[0].path).expect("canonical listed tree"),
            fs::canonicalize(&wt).expect("canonical worktree"),
        );
        assert_eq!(listed[0].branch, branch);
        assert_eq!(listed[0].repo_root, dir.path());

        assert!(
            stale_agent_worktrees(dir.path(), std::time::Duration::from_secs(3600))
                .expect("listing works")
                .is_empty(),
            "a tree younger than the age is not listed"
        );
    }

    /// A project that is itself a linked worktree: the CLI's agent
    /// worktrees live under the MAIN checkout, and the sweep must list
    /// there or every tree it never sees leaks (#2460).
    #[test]
    fn stale_agent_worktrees_reads_the_main_checkout_for_a_linked_project() {
        let repo = init_repo_with_commit();
        let main = fs::canonicalize(repo.path()).expect("canonical main");
        let linked = main.join("linked");
        run_git(&main, &["worktree", "add", "-q", "-b", "linked", linked.to_str().expect("utf8")]);
        let branch = add_worker_worktree(&main, "agent-abc123");

        let listed = stale_agent_worktrees(&linked, std::time::Duration::ZERO).expect("listing");
        assert_eq!(
            listed.len(),
            1,
            "the tree under the main checkout is seen from the linked project: {listed:?}",
        );
        assert_eq!(
            fs::canonicalize(&listed[0].path).expect("canonical listed tree"),
            main.join(".claude").join("worktrees").join("agent-abc123"),
        );
        assert_eq!(listed[0].branch, branch);
    }

    /// A pid whose process has already exited, for dead-owner fixtures.
    fn dead_child_pid() -> u32 {
        let mut child = std::process::Command::new("true").spawn().expect("spawn true");
        let pid = child.id();
        child.wait().expect("wait true");
        pid
    }

    /// A lock means a live CLI process owns the tree; the sweep must not
    /// list it, because the reap's removal unlocks first.
    #[test]
    fn stale_agent_worktrees_never_lists_a_locked_tree() {
        let (dir, wt, _branch) = init_repo_with_agent_worktree("abc123");
        run_git(dir.path(), &["worktree", "lock", wt.to_str().expect("utf8 path")]);

        assert!(
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO)
                .expect("listing works")
                .is_empty(),
            "a locked tree stays out of the sweep"
        );
    }

    /// The lock the CLI stamps on a live isolation agent's tree: a pid
    /// this process can prove alive. Measured live on CLI 2.1.220.
    #[test]
    fn stale_agent_worktrees_skips_a_live_pid_lock() {
        let (dir, wt, _branch) = init_repo_with_agent_worktree("abc123");
        let reason = format!("claude agent agent-abc123 (pid {} start now)", std::process::id());
        run_git(
            dir.path(),
            &["worktree", "lock", "--reason", &reason, wt.to_str().expect("utf8 path")],
        );

        assert!(
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO)
                .expect("listing works")
                .is_empty(),
            "a live owner keeps its tree out of the sweep"
        );
    }

    /// A crashed CLI leaves its pid behind; a dead pid makes the tree
    /// reapable again instead of leaking forever (git never prunes
    /// locked worktrees on its own).
    #[test]
    fn stale_agent_worktrees_lists_a_dead_pid_lock() {
        let (dir, wt, _branch) = init_repo_with_agent_worktree("abc123");
        let exited = std::process::Command::new("true")
            .spawn()
            .expect("spawn true")
            .wait()
            .expect("wait true");
        assert!(exited.success());
        let dead = dead_child_pid();
        let reason = format!("claude agent agent-abc123 (pid {dead} start now)");
        run_git(
            dir.path(),
            &["worktree", "lock", "--reason", &reason, wt.to_str().expect("utf8 path")],
        );

        let listed =
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO).expect("listing works");
        assert_eq!(listed.len(), 1, "a dead owner's leftover is reapable: {listed:?}");
    }

    /// A lock reason without a pid is one we did not write; its
    /// lifecycle is not ours to judge, so it skips.
    #[test]
    fn stale_agent_worktrees_skips_a_lock_without_a_parsable_pid() {
        let (dir, wt, _branch) = init_repo_with_agent_worktree("abc123");
        run_git(
            dir.path(),
            &["worktree", "lock", "--reason", "held by hand", wt.to_str().expect("utf8 path")],
        );

        assert!(
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO)
                .expect("listing works")
                .is_empty()
        );
    }

    /// The gate the sweep re-runs immediately before each removal, so a
    /// lock taken after the listing still stops that reap.
    #[test]
    fn agent_worktree_lock_is_live_distinguishes_the_three_states() {
        let (dir, wt_locked, _b) = init_repo_with_agent_worktree("locked1");
        let reason = format!("claude agent agent-locked1 (pid {} start now)", std::process::id());
        run_git(
            dir.path(),
            &["worktree", "lock", "--reason", &reason, wt_locked.to_str().expect("utf8 path")],
        );
        let (_d2, wt_dead, _b2) = {
            let (dir2, wt2, b2) = init_repo_with_agent_worktree("dead1");
            let dead = dead_child_pid();
            let reason = format!("claude agent agent-dead1 (pid {dead} start now)");
            run_git(
                dir2.path(),
                &["worktree", "lock", "--reason", &reason, wt2.to_str().expect("utf8 path")],
            );
            (dir2, wt2, b2)
        };
        let (_d3, wt_unlocked, _b3) = init_repo_with_agent_worktree("free1");

        assert!(agent_worktree_lock_is_live(dir.path(), &wt_locked), "a live owner's lock is live");
        assert!(!agent_worktree_lock_is_live(dir.path(), &wt_dead), "a dead owner's lock is not");
        assert!(
            !agent_worktree_lock_is_live(dir.path(), &wt_unlocked),
            "an unlocked tree has nothing live",
        );
    }

    #[test]
    fn stale_agent_worktrees_ignores_non_agent_names_and_plain_files() {
        let (dir, _wt, _branch) = init_repo_with_agent_worktree("abc123");
        add_worker_worktree(dir.path(), "worker-z");
        let scratch = dir.path().join(".claude").join("worktrees").join("agent-plain-file");
        fs::write(&scratch, "a file, not a tree").expect("write scratch");

        let listed =
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO).expect("listing works");
        assert_eq!(listed.len(), 1, "only the agent-prefixed dir is listed: {listed:?}");
        assert!(listed[0].path.ends_with("agent-abc123"), "{:?}", listed[0].path);
    }

    /// A worktrees dir that cannot be read propagates the error - the
    /// sweep must not read an unreadable listing as an empty one.
    #[cfg(unix)]
    #[test]
    fn stale_agent_worktrees_propagates_an_unreadable_worktrees_dir() {
        use std::os::unix::fs::PermissionsExt;

        let dir = init_repo_with_commit();
        let worktrees = dir.path().join(".claude").join("worktrees");
        std::fs::create_dir_all(&worktrees).expect("mkdir");
        std::fs::set_permissions(&worktrees, std::fs::Permissions::from_mode(0o000))
            .expect("chmod");

        let outcome = stale_agent_worktrees(dir.path(), std::time::Duration::ZERO);
        std::fs::set_permissions(&worktrees, std::fs::Permissions::from_mode(0o755))
            .expect("restore chmod");
        assert!(
            outcome.is_err(),
            "an unreadable dir is an error, never an empty sweep: {outcome:?}"
        );
    }

    #[test]
    fn stale_agent_worktrees_is_empty_outside_a_repo() {
        let dir = tempdir().expect("tempdir");
        assert!(
            stale_agent_worktrees(dir.path(), std::time::Duration::ZERO)
                .expect("listing works")
                .is_empty()
        );
    }
}