trusty-mpm 1.8.2

//! Git-native worktree enumeration and registry-root resolution (#4207 slice 1).
//!
//! Why: every worktree question this crate asks used to be answered by
//! GUESSING at the filesystem. `prune::find_orphaned_worktrees` walked five
//! hard-coded location shapes (`.worktrees/`, `.base/.worktrees/`,
//! `.claude/worktrees/`, `.base/.claude/worktrees/`, and
//! `.base/.worktrees/<id>/.claude/worktrees/`), and both
//! `worktree_safety::git_worktree_list_agrees` and
//! `decommission::remove_session_worktree` derived "which checkout owns this
//! worktree?" from the candidate's GRANDPARENT directory. Neither is a fact;
//! both are inferences that git can answer exactly, and both were wrong on
//! this machine on 2026-07-27: fourteen worktrees physically located inside
//! `<repo>/.base/.worktrees/` are registered to the PARENT repo `<repo>`, so
//! the grandparent rule asked `.base` about them, `.base` correctly said "not
//! mine", and the sweep skipped them conservatively — forever. They were not
//! merely un-reclaimed, they were STRUCTURALLY unreclaimable, and no amount of
//! adding a sixth location shape would have fixed it.
//!
//! Git already maintains the answer. `git worktree list --porcelain` is the
//! registry, and `git rev-parse --git-common-dir` names the checkout that owns
//! it. Deriving from those two commands makes location irrelevant: a worktree
//! is found because git registered it, not because it happened to be parked
//! under a directory name someone remembered to enumerate.
//!
//! What: [`RegisteredWorktree`] (one porcelain record),
//! [`parse_worktree_list`] (the pure parser), [`registry_root_for`] (replaces
//! grandparent-as-repo-root inference), [`list_registered_worktrees`] (what
//! git says about the repository owning a path),
//! [`scan_registered_worktrees`] (#4288 — EVERY registered worktree under the
//! repos root, each carrying the [`Admission`] verdict that says whether it is
//! a reclaim candidate and, when it is not, WHY), and
//! [`enumerate_registered_worktrees_in`] (the admitted subset — every registered
//! worktree living INSIDE a managed project under the repos root; see that
//! function's "positive assertion" section for the structural boundary that
//! bounds the sweep).
//!
//! # An unanswerable probe is never a verdict
//!
//! Every function here returns `Option`/`None` — never a `bool` — for the
//! "could not determine" case, so no caller can silently read a missing `git`
//! binary, a permissions error, or a stalled network mount as a fact about the
//! worktree. This is the same invariant PR #4202's round-1 fix broke by
//! collapsing every `canonicalize()` error kind into "destroyed"; on
//! 2026-07-21 a rule that loose would have told an operator to recreate ~70
//! fully intact worktrees. Callers decide what a `None` means in their own
//! direction of safety — [`enumerate_registered_worktrees_in`] treats it as "no
//! candidates from this anchor" (nothing is proposed for deletion), while
//! `git_worktree_list_agrees` keeps its long-standing best-effort `true`.
//!
//! Test: `worktree_registry_tests`.

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};

use super::git_ceiling::bounded_git_output;
use super::worktree_safety::git_command;
use super::worktree_scope::WorktreeScope;

/// The bare-clone checkout trusty-mpm provisions alongside a managed project.
///
/// Why: a managed project has at most TWO git checkouts that can own a worktree
/// registry — the project checkout itself and the `.base` clone
/// `inproject::create_session_worktree` creates. Naming the segment
/// once keeps [`enumerate_registered_worktrees_in`] from repeating the literal.
/// This is NOT a worktree-location guess: it names a CHECKOUT to interrogate,
/// and git then reports where that checkout's worktrees actually live.
/// What: `".base"`.
/// Test: `enumerate_finds_worktree_registered_to_base_clone`.
pub(crate) const BASE_CLONE_DIRNAME: &str = ".base";

/// One worktree exactly as `git worktree list --porcelain` reports it (#4207).
///
/// Why: the porcelain format carries the four facts the reclaim path needs —
/// where the worktree is, whether it is the main checkout (never a reclaim
/// candidate), whether it is bare (no working tree to reclaim), and whether
/// git already considers it prunable (its directory is gone, so there is
/// nothing to delete). Modelling them as fields rather than re-grepping the
/// raw text at each call site keeps the parse in one place.
/// What: `path` is git's own absolute path for the worktree; `branch` is the
/// short branch name when the worktree is not detached; `is_main` marks the
/// FIRST record, which git always emits for the main worktree.
/// Test: `parse_worktree_list_reads_porcelain_records`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct RegisteredWorktree {
    /// Absolute path git reports for this worktree.
    pub path: PathBuf,
    /// Short branch name (`refs/heads/` stripped), or `None` when detached.
    pub branch: Option<String>,
    /// `true` for a bare repository record (no working tree).
    pub bare: bool,
    /// `true` when git reports the worktree's directory is missing.
    pub prunable: bool,
    /// `true` when git reports the worktree is LOCKED — an explicit operator
    /// "do not remove this", which `git worktree remove` refuses to override
    /// without `--force`.
    pub locked: bool,
    /// The lock's REASON when git reported one, else `None` (#6561).
    ///
    /// Why: a lock is not one thing. The operator's `git worktree lock` is a
    /// standing veto; the Claude Code harness's own agent-worktree isolation
    /// also locks, for the life of the dispatched agent, with a reason naming
    /// that agent. Discarding the reason made both indistinguishable, so a tree
    /// a live agent was working in was dropped at [`Admission::Locked`] and
    /// never reached the gate that would have SAID SO — which is half of the
    /// silent `0 of 0` #6561 reports.
    /// Test: `parse_worktree_list_reads_locked_with_and_without_reason`,
    /// `parse_worktree_list_keeps_the_harness_agent_lock_reason`.
    pub lock_reason: Option<String>,
    /// `true` for the first record — git always lists the main worktree first.
    pub is_main: bool,
}

/// Does `reason` name the Claude Code harness's own agent-worktree lock (#6561)?
///
/// Why: this is the ONE fact that separates the harness's agent-lifetime lock
/// from an operator's standing veto, and it has to be read from the reason
/// string because git records nothing else about who locked a worktree. Measured
/// on this machine (git 2.54.0, Claude Code agent isolation): every live agent's
/// tree carries `claude agent agent-<id> (pid <n> start <time>)`, and every
/// finished agent's tree carries no lock at all — the harness releases it when
/// the agent ends.
/// What: a case-insensitive `claude agent` prefix test on the trimmed reason.
/// Deliberately a PREFIX and not a parse: nothing downstream reads the agent id
/// or the pid out of this string, so recognising the shape is the whole job, and
/// a reason that merely mentions "claude agent" further along is not matched.
/// Test: `harness_agent_lock_reason_matches_the_harness_shape`,
/// `harness_agent_lock_reason_rejects_an_operator_lock`.
pub(crate) fn is_harness_agent_lock_reason(reason: &str) -> bool {
    reason
        .trim_start()
        .get(..12)
        .is_some_and(|head| head.eq_ignore_ascii_case("claude agent"))
}

/// What git can say, right now, about whether the harness holds `path` (#6561).
///
/// Why: the delegation registry is a `DashMap` rebuilt empty at every daemon
/// boot, so after a restart it answers "nothing claims it" for an agent that is
/// still working — [`super::worktree_ownership::AgentDelegationState::Unknown`],
/// which ADR-0045 forbids reading as "free". Git's lock does not have that
/// defect: it is a file under `.git/worktrees/<id>/locked`, written by the
/// harness when it dispatches an agent into the tree and removed when that agent
/// ends, and it survives a daemon restart because no daemon writes it. So it is
/// the durable second source that can answer the question the registry cannot.
/// What: three answers, and the third is the point. [`Held`](Self::Held) — git
/// reports a harness agent lock. [`Released`](Self::Released) — git lists the
/// worktree and reports no lock on it, which is POSITIVE evidence the harness
/// let go. [`Undeterminable`](Self::Undeterminable) — git could not be asked, or
/// no longer lists the path; never read as released.
/// Test: `harness_lock_state_reports_a_harness_locked_tree_held`,
/// `harness_lock_state_reports_an_unlocked_tree_released`,
/// `harness_lock_state_of_a_non_worktree_is_undeterminable`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum HarnessLockState {
    /// Git reports a lock whose reason names a harness agent.
    Held,
    /// Git lists this worktree and reports no lock on it at all.
    Released,
    /// Git could not be asked, or does not list this path.
    Undeterminable,
}

/// Ask git whether the harness still holds `path` (#6561).
///
/// Why: see [`HarnessLockState`]. Resolved from the candidate itself so the
/// answer comes from the repository that actually registered the worktree.
/// What: one `git -C <path> worktree list --porcelain`, matched on the
/// canonicalized path. An operator lock — a lock whose reason is not the
/// harness's — is reported [`Undeterminable`](HarnessLockState::Undeterminable)
/// rather than `Released`, because it is not evidence about the harness either
/// way and must never advance a destructive path.
/// Test: `harness_lock_state_reports_a_harness_locked_tree_held`,
/// `harness_lock_state_reports_an_unlocked_tree_released`,
/// `harness_lock_state_of_an_operator_locked_tree_is_undeterminable`,
/// `harness_lock_state_of_a_non_worktree_is_undeterminable`.
pub(crate) fn harness_lock_state(path: &Path) -> HarnessLockState {
    let Some(registered) = list_registered_worktrees(path) else {
        return HarnessLockState::Undeterminable;
    };
    let canonical = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    let found = registered
        .into_iter()
        .find(|w| std::fs::canonicalize(&w.path).unwrap_or_else(|_| w.path.clone()) == canonical);
    let Some(record) = found else {
        return HarnessLockState::Undeterminable;
    };
    if !record.locked {
        return HarnessLockState::Released;
    }
    match record.lock_reason.as_deref() {
        Some(reason) if is_harness_agent_lock_reason(reason) => HarnessLockState::Held,
        _ => HarnessLockState::Undeterminable,
    }
}

/// The pid a harness agent lock reason names, if it names one (#7974).
///
/// Why: [`is_harness_agent_lock_reason`] deliberately recognises the SHAPE and
/// reads nothing out of it, because nothing needed the pid until adoption did.
/// Adoption needs it: after a daemon restart the delegation registry answers
/// `Unknown` for every agent (ADR-0045), and this lock — written by the harness,
/// never by a daemon — is the only durable record of WHICH process was
/// dispatched into the tree. A pid the kernel does not know is positive
/// evidence that process ended.
/// What: the digits after `(pid ` in a reason already confirmed to be a harness
/// agent lock. Measured shape (git 2.54.0, Claude Code agent isolation):
/// `claude agent agent-<id> (pid 17167 start Mon Sep 14 15:30:46 2026)`.
/// Returns `None` for a non-harness reason, a missing marker, or digits that do
/// not fit a `u32` — never a guess.
/// Test: `harness_lock_pid_reads_the_measured_reason_shape`,
/// `harness_lock_pid_rejects_an_operator_lock`,
/// `harness_lock_pid_is_none_when_the_reason_names_no_pid`.
pub(crate) fn harness_lock_pid_in_reason(reason: &str) -> Option<u32> {
    if !is_harness_agent_lock_reason(reason) {
        return None;
    }
    let rest = reason.split_once("(pid ")?.1;
    let digits: String = rest.chars().take_while(char::is_ascii_digit).collect();
    digits.parse().ok()
}

/// The pid of the harness agent lock git reports on `path`, if any (#7974).
///
/// Why: the one line that touches git, so the parse above stays pure.
/// What: resolves `path` in the registry that actually owns it and reads the
/// pid out of its lock reason. `None` when git could not be asked, when the
/// path is not a registered worktree, when it is unlocked or locked by an
/// operator, or when the reason carries no pid.
/// Test: `harness_lock_pid_of_a_non_worktree_is_none`.
pub(crate) fn harness_agent_lock_pid(path: &Path) -> Option<u32> {
    let registered = list_registered_worktrees(path)?;
    let canonical = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    let record = registered
        .into_iter()
        .find(|w| std::fs::canonicalize(&w.path).unwrap_or_else(|_| w.path.clone()) == canonical)?;
    if !record.locked {
        return None;
    }
    harness_lock_pid_in_reason(record.lock_reason.as_deref()?)
}

/// Is `pid` running, as far as this process can tell (#7974)?
///
/// Why a tri-state rather than [`crate::core::process::is_process_alive`]'s
/// bool: that wrapper folds every errno it did not expect into "dead", which is
/// the coercion ADR-0045 forbids on a probe feeding a mutation. Adoption takes
/// a tree away from whoever holds it, so an UNANSWERED probe must refuse, not
/// proceed.
/// What: `kill(pid, 0)` — a null signal that performs the existence and
/// permission check and delivers nothing. `Some(true)` when the process exists
/// (`EPERM` included: it exists, under another user); `Some(false)` only on
/// `ESRCH`; `None` for a pid outside the positive `pid_t` range (`0` and
/// negatives are process groups, never one process) and for any other errno.
/// Test: `pid_liveness_separates_running_gone_and_undeterminable` covers the
/// `Ok`, `ESRCH` and out-of-range arms against the live kernel;
/// `classify_kill_probe_*` cover every errno arm.
pub(crate) fn pid_liveness(pid: u32) -> Option<bool> {
    use nix::sys::signal::kill;
    use nix::unistd::Pid;

    let raw = i32::try_from(pid).ok()?;
    if raw <= 0 {
        return None;
    }
    // #7974: the classification is a separate pure function so the errno arms
    // are reachable from a test — no live process can be made to answer EPERM
    // or an unrecognised errno on demand.
    classify_kill_probe(kill(Pid::from_raw(raw), None))
}

/// What one `kill(pid, 0)` outcome says about the process (#7974).
///
/// Why separate from [`pid_liveness`]: the `EPERM` and unrecognised-errno arms
/// decide whether adoption refuses, and neither can be provoked hermetically
/// through the real syscall — `EPERM` needs a process owned by another uid that
/// is guaranteed to outlive the test, and no pid produces an arbitrary errno on
/// demand. Splitting the classification out makes both arms testable without a
/// trait seam or an injectable syscall.
/// What: `Some(true)` when the process exists — `EPERM` included, since the
/// kernel checked permission on a process it found; `Some(false)` only on
/// `ESRCH`; `None` for every other errno, which is the fail-closed direction
/// ADR-0045 requires of a probe feeding a mutation.
/// Test: `classify_kill_probe_reads_eperm_as_running`,
/// `classify_kill_probe_reads_an_unrecognised_errno_as_undeterminable`,
/// `classify_kill_probe_agrees_with_the_live_probe_on_ok_and_esrch`.
fn classify_kill_probe(probe: Result<(), nix::errno::Errno>) -> Option<bool> {
    use nix::errno::Errno;

    match probe {
        Ok(()) | Err(Errno::EPERM) => Some(true),
        Err(Errno::ESRCH) => Some(false),
        // intentional fail-closed (ADR-0045): an errno this probe does not
        // recognise has not proven the process gone.
        Err(_) => None,
    }
}

/// Parse `git worktree list --porcelain` output into records (#4207).
///
/// Why: the parse is the one piece of this module that can be tested without
/// spawning git, and the porcelain format has enough shape (blank-line-
/// separated stanzas, valueless `bare`/`detached`/`prunable` attribute lines)
/// that an ad-hoc `strip_prefix("worktree ")` over all lines — what
/// `git_worktree_list_agrees` did before this change — silently ignores every
/// other fact in the record.
/// What: splits on blank lines; each stanza starts with `worktree <path>` and
/// may carry `HEAD <sha>`, `branch <ref>`, `bare`, `detached`, `locked`, or
/// `prunable` (the last two optionally with a reason). The first stanza is
/// flagged [`RegisteredWorktree::is_main`]. Unknown attribute lines are
/// ignored so a future git version cannot break the parse.
/// Test: `parse_worktree_list_reads_porcelain_records`,
/// `parse_worktree_list_marks_only_the_first_record_main`,
/// `parse_worktree_list_reads_locked_with_and_without_reason`.
pub(crate) fn parse_worktree_list(stdout: &str) -> Vec<RegisteredWorktree> {
    let mut out: Vec<RegisteredWorktree> = Vec::new();
    for line in stdout.lines() {
        let line = line.trim_end();
        if let Some(path) = line.strip_prefix("worktree ") {
            out.push(RegisteredWorktree {
                path: PathBuf::from(path),
                branch: None,
                bare: false,
                prunable: false,
                locked: false,
                lock_reason: None,
                is_main: out.is_empty(),
            });
            continue;
        }
        let Some(current) = out.last_mut() else {
            continue;
        };
        if let Some(branch) = line.strip_prefix("branch ") {
            current.branch = Some(
                branch
                    .strip_prefix("refs/heads/")
                    .unwrap_or(branch)
                    .to_string(),
            );
        } else if line == "bare" {
            current.bare = true;
        } else if line == "prunable" || line.starts_with("prunable ") {
            current.prunable = true;
        } else if line == "locked" {
            current.locked = true;
        } else if let Some(reason) = line.strip_prefix("locked ") {
            // #6561: the reason is kept, not discarded — it is the only thing
            // that tells the harness's agent-lifetime lock from an operator veto.
            current.locked = true;
            current.lock_reason = Some(reason.to_string());
        }
    }
    out
}

/// The checkout that owns the worktree registry `anchor` belongs to (#4207).
///
/// Why: this REPLACES grandparent-as-repo-root inference
/// (`path.parent().and_then(|p| p.parent())`), which was correct only for the
/// two shapes it was written against and wrong for every other one —
/// `<repo>/.claude/worktrees/<name>` resolved to `<repo>/.claude`, which is
/// not a repository at all, and the fourteen `.base`-resident worktrees
/// registered to the parent repo resolved to `.base`, which disowns them.
/// `git rev-parse --git-common-dir` answers the same question as a fact: it
/// names the SHARED git directory every worktree of a repository points at,
/// which is exactly the registry `git worktree list` reads.
/// What: runs `git -C <anchor> rev-parse --path-format=absolute
/// --git-common-dir`. A normal checkout answers `<root>/.git`, so the root is
/// its parent; a bare clone answers with the bare directory itself, which IS
/// the root. Returns `None` when git cannot be run, exits non-zero (including
/// the ordinary "not a git repository" case), or prints nothing usable — never
/// a guessed path.
/// Test: `registry_root_for_linked_worktree_is_the_owning_checkout`,
/// `registry_root_for_non_repo_is_none`.
pub(crate) fn registry_root_for(anchor: &Path) -> Option<PathBuf> {
    // #8306: bounded; a timeout is `None`, the same "never a guessed path".
    let out = bounded_git_output(git_command(
        anchor,
        &["rev-parse", "--path-format=absolute", "--git-common-dir"],
    ))
    .ok()?;
    if !out.status.success() {
        return None;
    }
    let raw = String::from_utf8_lossy(&out.stdout);
    let common_dir = PathBuf::from(raw.trim());
    if common_dir.as_os_str().is_empty() {
        return None;
    }
    // A non-bare repository's common dir is `<root>/.git`; a bare one IS the root.
    if common_dir.file_name().is_some_and(|n| n == ".git") {
        common_dir.parent().map(Path::to_path_buf)
    } else {
        Some(common_dir)
    }
}

/// Every worktree git registers for the repository that owns `anchor` (#4207).
///
/// Why: `git worktree list` is the registry. Asking it directly is what makes
/// worktree discovery independent of where a worktree is parked, and it is the
/// only source that can report a worktree registered to one checkout while
/// living inside another's directory tree — the exact state that made fourteen
/// worktrees on this machine unreclaimable.
/// What: runs `git -C <anchor> worktree list --porcelain` and parses the
/// result via [`parse_worktree_list`]. Git resolves the repository from
/// `anchor` itself, so `anchor` may be the checkout root, a linked worktree, or
/// any directory inside one. Returns `None` on a spawn failure or non-zero
/// exit — an unanswerable probe, never an empty list.
/// Test: `list_registered_worktrees_reports_a_real_worktree`,
/// `list_registered_worktrees_none_outside_a_repo`.
pub(crate) fn list_registered_worktrees(anchor: &Path) -> Option<Vec<RegisteredWorktree>> {
    probe_registered_worktrees(anchor).ok()
}

/// [`list_registered_worktrees`], keeping WHY the probe failed (#8306).
///
/// Why: a caller that must fail closed on a wedged git has to tell a timeout
/// from "not a repository"; the `Option` form erases that.
/// What: `Err` with [`std::io::ErrorKind::TimedOut`] when git was killed at the
/// ceiling; any other `Err` for a spawn failure or a non-zero exit.
/// Test: `a_timed_out_worktree_list_disagrees`.
pub(crate) fn probe_registered_worktrees(
    anchor: &Path,
) -> std::io::Result<Vec<RegisteredWorktree>> {
    let out = bounded_git_output(git_command(anchor, &["worktree", "list", "--porcelain"]))?;
    if !out.status.success() {
        return Err(std::io::Error::other(format!(
            "`git worktree list` exited {}",
            out.status
        )));
    }
    Ok(parse_worktree_list(&String::from_utf8_lossy(&out.stdout)))
}

/// Every git-registered worktree living under `repos_root` (#4207 slice 1).
///
/// Why: this is the derive-not-walk replacement for
/// `prune::find_orphaned_worktrees`' five hard-coded location shapes. Those
/// shapes could only ever find worktrees someone had already thought to
/// enumerate, and each new agent runtime added a shape (#3649, #3971, and the
/// #3971 follow-up were all "we missed a location" fixes). Asking git removes
/// the category: a worktree is discovered because it is REGISTERED, wherever
/// it sits.
/// What: for each `<repos_root>/<owner>/<repo>/`, interrogates the two
/// checkouts trusty-mpm actually provisions — `<repo>` and
/// `<repo>/.base` — but only after confirming (via [`registry_root_for`]) that
/// the anchor IS that repository's root. That confirmation is load-bearing:
/// without it, `git -C <non-repo>` walks UP the filesystem and would report an
/// unrelated enclosing repository's worktrees. Records that are bare, main,
/// already prunable, or git-`locked` are dropped, as is any worktree failing
/// the [`scan_from_anchor`] containment rule. Results are canonicalized (so
/// they compare cleanly against the canonicalized active-session set) and
/// returned sorted and de-duplicated, since both anchors may report the same
/// worktree.
///
/// # Containment is a POSITIVE assertion, not a denylist (#4224 review, HIGH)
///
/// Enumerating from git's registry rather than from five path shapes widens
/// what can be SEEN, and the first cut of this module let anything git
/// registered anywhere under `repos_root` through — leaving the #3649 ownership
/// sentinel as the single structural boundary in front of an unattended
/// `remove_dir_all`. Replayed against the dogfood machine that admitted seven
/// paths the old walk never produced, FIVE of them the operator's own
/// long-lived checkouts (`<owner>/ft-follow-links`,
/// `<owner>/trusty-tools-main-build`, `<owner>/trusty-tools-worktrees/wt-*`,
/// `<owner>/gb-connect-card`). None was deletable — each lacks a sentinel — but
/// "one gate happens to hold" is not a boundary, and this repository has
/// already lost a bare clone to an over-broad removal (2026-07-21).
///
/// So a candidate must additionally be a STRICT DESCENDANT of the managed
/// project directory whose registry named it. That is an assertion the path IS
/// inside a tree trusty-mpm provisions and manages, which is an invariant of
/// the WRITE side: `provisioner::workspace` only ever creates worktrees beneath
/// `<repos_root>/<owner>/<repo>/` (in the checkout, in its `.base` clone, or in
/// an agent runtime's directory inside either). It is deliberately NOT a list
/// of blessed path shapes — any depth and any directory name inside the project
/// qualifies, so the "we forgot a location" bug class this PR deletes (#3649,
/// #3971) stays deleted. And it is not a denylist of known operator paths: an
/// operator checkout is excluded by its POSITION relative to the repository
/// that owns it, so a newly created one is excluded on the day it is created,
/// under any name.
///
/// Both operands come from git — the path from `git worktree list --porcelain`,
/// the project root from `git rev-parse --git-common-dir` — so this adds no
/// state that could drift out of sync with git's own registry. That matters:
/// worktrees present in one registry and absent from another is a failure this
/// repository has already had twice.
///
/// ## Why provenance is not available, and branch role does not substitute
///
/// The discriminator one WANTS is "was this provisioned for a writing agent, on
/// a workstream branch?". Git cannot answer the first half at all: nothing in
/// the porcelain record, and nothing in the `worktrees/<id>/` admin directory,
/// records WHO ran `git worktree add`. The only provenance fact that exists is
/// trusty-mpm's own #3649 sentinel, which is why the sentinel gate stays where
/// it is — this boundary is layered IN FRONT of it, not a second copy of it.
///
/// Branch role does not substitute, measured rather than assumed. Across the
/// 201 candidates on this machine the branch namespaces are
/// `fix/` (88), `feat/` (44), `docs/` (12), detached (10), `session/` (9),
/// `chore/` (9) — and the operator's own checkouts, the Claude-native
/// `agent-*` worktrees, and the genuinely tm-owned ones are ALL drawn from
/// `fix/` and `feat/`. Gating reclamation on a `session|ws|workstream`
/// namespace would admit 9 of 201 candidates and ZERO of the 3 sentinel-bearing
/// ones — reclamation would silently drop to nothing while still looking
/// healthy. A branch namespace is also just a name pattern, and an operator may
/// check out any branch in their own checkout.
///
/// Containment is therefore the strongest git-observable boundary available,
/// and it is count- and name-independent: the 1.3.0 direction (one worktree per
/// writing agent, more of them, shorter-lived) makes it MORE useful, not less,
/// because every agent worktree is provisioned inside the project tree no
/// matter how many there are or what they are called.
///
/// Measured on the same machine, the rule drops all five operator checkouts,
/// retains all 54 `.base`-resident worktrees (the class that was structurally
/// unreclaimable before this PR), and leaves the count of sentinel-bearing —
/// i.e. actually reclaimable — candidates unchanged at 3. The narrowing costs
/// no reclaim capability; it only removes reach the sweep never needed.
/// Test: `enumerate_finds_worktree_at_an_unwalked_location`,
/// `enumerate_finds_worktree_registered_to_base_clone`,
/// `enumerate_ignores_plain_directory_that_is_not_a_worktree`,
/// `enumerate_excludes_the_main_checkout`,
/// `enumerate_excludes_worktrees_outside_the_repos_root`,
/// `enumerate_excludes_a_sibling_checkout_of_the_same_repo`,
/// `enumerate_excludes_a_worktree_parked_beside_the_project`,
/// `enumerate_excludes_a_locked_worktree`,
/// `enumerate_admits_a_worktree_under_an_adopted_checkout` (#7357).
///
/// `adopted` (#7357) names the checkouts of projects registered from somewhere
/// other than `<repos_root>/<owner>/<repo>`; see
/// [`scan_registered_worktrees`] for the containment rule they get. Pass `&[]`
/// for the walk alone.
///
/// # Scope and rows (#8782)
///
/// `scope` bounds the scan ([`WorktreeScope::all`] for every project). Each
/// admitted path comes back as its [`ScannedWorktree`] row, one row per path,
/// so a caller keeps the registry that named it without asking git again.
/// Test: `an_orphan_sweep_scoped_to_one_project_spares_another`.
pub(crate) fn enumerate_registered_worktrees_in(
    repos_root: &Path,
    adopted: &[PathBuf],
    scope: &WorktreeScope,
) -> Vec<ScannedWorktree> {
    let mut seen: BTreeSet<PathBuf> = BTreeSet::new();
    let mut out: Vec<ScannedWorktree> = scan_registered_worktrees_in(repos_root, adopted, scope)
        .into_iter()
        .filter(|s| s.admission == Admission::Admitted && seen.insert(s.path.clone()))
        .collect();
    sort_deepest_first(&mut out);
    out
}

/// Order `paths` so a NESTED worktree always precedes the worktree that
/// contains it (#4288, in-scope item 4).
///
/// Why: the pre-#4288 order came straight out of a `BTreeSet<PathBuf>`, which
/// sorts lexicographically — so `…/parent` sorts BEFORE `…/parent/child`.
/// Nine registered worktrees on the dogfood machine are nested inside another
/// registered worktree, and removing a parent first takes its children's
/// directories with it: the child's own removal then finds nothing to remove
/// and git is left holding a dangling registry entry for a path that no longer
/// exists. Reversing the order makes each nested worktree removed by
/// `git worktree remove` (which de-registers it) before its parent is touched.
///
/// This changes ORDER only. It cannot admit a path the containment rules
/// already rejected, and it cannot cause a removal that would not otherwise
/// have happened — every element was already in the returned list.
/// What: sorts by path DEPTH descending (component count), breaking ties
/// lexicographically so the result stays deterministic. Depth-descending is
/// sufficient for the containment property: a descendant always has strictly
/// more components than its ancestor.
/// Test: `enumerate_orders_nested_worktree_before_its_parent`.
fn sort_deepest_first(rows: &mut [ScannedWorktree]) {
    rows.sort_by(|a, b| {
        b.path
            .components()
            .count()
            .cmp(&a.path.components().count())
            .then_with(|| a.path.cmp(&b.path))
    });
}

/// Why a registered worktree is, or is not, an orphan-reclaim CANDIDATE (#4288).
///
/// Why: `enumerate_registered_worktrees` returns only the admitted paths, so
/// everything it drops is invisible — and on the dogfood machine that is 33 of
/// 118 registered worktrees, 6 of which hold uncommitted work, including the
/// two landmines #4288 documents (a `workspace_path` that is an ordinary
/// subdirectory of a live checkout, and worktrees nested inside a live one).
/// Reconciliation cannot report what enumeration silently discards, so the
/// verdict is now a VALUE the scan carries rather than a `continue` statement.
/// What: [`Admitted`](Self::Admitted) is the reclaim-candidate set — identical
/// to what `enumerate_registered_worktrees` returned before #4288. Every other
/// variant names one exclusion, in the order the scan applies them.
/// Test: `scan_reports_the_excluded_set_with_reasons`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum Admission {
    /// Inside a managed project, not bare/main/prunable/locked — a candidate.
    Admitted,
    /// A bare repository record: no working tree to reclaim.
    Bare,
    /// The repository's main checkout: never a candidate.
    MainCheckout,
    /// Git already considers the directory gone.
    Prunable,
    /// The operator ran `git worktree lock` — an explicit removal veto.
    Locked,
    /// The Claude Code harness holds its own agent-lifetime lock (#6561).
    ///
    /// Why a variant of its own rather than [`Locked`](Self::Locked): both are
    /// refusals, but only one of them is a fact the operator has to be told.
    /// An operator lock is the operator's own standing decision; a harness lock
    /// means a DISPATCHED AGENT is working in that tree right now, and folding
    /// it into `Locked` dropped the candidate at gate 1 of
    /// `worktree_reclaim::classify` — before the gate that reports a spared
    /// agent tree ever ran. So `--merged-prs` printed `0 of 0` over a store
    /// full of agent worktrees and named none of them.
    /// Test: `scan_separates_a_harness_agent_lock_from_an_operator_lock`,
    /// `classify_discloses_a_harness_locked_agent_tree_as_agent_owned`.
    HarnessAgentLock,
    /// The path could not be canonicalized, so nothing about it is comparable.
    Unresolvable,
    /// Registered, but not a strict descendant of the managed project.
    OutsideProject,
    /// Registered, but outside the managed repos root.
    OutsideReposRoot,
}

impl Admission {
    /// A short, operator-facing phrase naming this verdict (#4288).
    ///
    /// Why: the reconcile report prints one reason per entry, and building
    /// that string at each call site would let the wordings drift.
    /// What: a `&'static str` per variant.
    /// Test: `scan_reports_the_excluded_set_with_reasons`.
    pub(crate) fn reason(self) -> &'static str {
        match self {
            Self::Admitted => "admitted: registered inside a managed project",
            Self::Bare => "excluded: bare repository record (no working tree)",
            Self::MainCheckout => "excluded: the repository's main checkout",
            Self::Prunable => "excluded: git reports the directory is already gone",
            Self::Locked => "excluded: git-locked by the operator",
            Self::HarnessAgentLock => {
                "excluded: the harness holds its agent-lifetime lock on this worktree — a \
                 dispatched agent is still working in it (#6561)"
            }
            Self::Unresolvable => "excluded: path could not be canonicalized",
            Self::OutsideProject => "excluded: not inside the managed project that registered it",
            Self::OutsideReposRoot => "excluded: outside the managed repos root",
        }
    }
}

/// One registered worktree plus everything the scan learned about it (#4288).
///
/// Why: reconciliation needs the registry that named a worktree (that is half
/// the git-derived key), the project bounding it, and the admission verdict —
/// none of which survive `enumerate_registered_worktrees`' `Vec<PathBuf>`.
/// What: `path` is canonical when it resolved (raw otherwise, so an
/// [`Admission::Unresolvable`] entry can still be REPORTED); `project` is the
/// managed project directory; `registry_root` is the checkout whose
/// `git worktree list` named it; `branch` and `admission` complete the record.
/// Test: `scan_reports_the_excluded_set_with_reasons`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ScannedWorktree {
    /// Canonical worktree path (raw when canonicalization failed).
    pub path: PathBuf,
    /// The managed project directory `<repos_root>/<owner>/<repo>`.
    pub project: PathBuf,
    /// The checkout whose registry listed this worktree.
    pub registry_root: PathBuf,
    /// Short branch name, or `None` when detached.
    pub branch: Option<String>,
    /// Whether this is an orphan-reclaim candidate, and if not, why not.
    pub admission: Admission,
}

/// Every worktree BOTH managed anchors register under `repos_root`, admitted
/// or not (#4288).
///
/// Why: this is [`enumerate_registered_worktrees_in`] with the `continue`
/// statements turned into values, so reconciliation reports the excluded set
/// instead of inheriting enumeration's blind spot. Sharing one traversal is
/// the point — a second, parallel enumerator is exactly the drift that let the
/// pre-#4207 five-shape walk disagree with itself.
/// What: for each `<repos_root>/<owner>/<repo>/`, interrogates `<repo>` and
/// `<repo>/.base` (each only after [`registry_root_for`] confirms the anchor
/// IS that repository's root), and returns one [`ScannedWorktree`] per
/// porcelain record, deduplicated on (path, registry root) and sorted.
/// Test: `scan_reports_the_excluded_set_with_reasons`,
/// `scan_reports_both_registries_for_the_same_path_prefix`.
///
/// # `adopted` — the checkouts of projects registered elsewhere (#7357)
///
/// Why: the repos-root walk finds a project only at `<repos_root>/<owner>/<repo>`.
/// A project registered from a checkout anywhere else — the case #7357 reports —
/// is never interrogated at all, so reconcile reported zero rows for it, the
/// `--merged-prs` sweep reclaimed nothing under it, and `tm doctor` agreed
/// because all three read this one function. `adopted` is the set of checkouts
/// [`crate::project::worktree_adoption`] recorded when those projects were
/// registered.
/// What: the walk exactly as before, then one pass per adopted checkout. Two
/// rules keep the widening from re-attributing anything:
///
/// 1. An adopted checkout INSIDE `repos_root` is skipped — the walk already
///    owns it, and letting both produce a row would put one path under two
///    projects.
/// 2. An adopted checkout bounds its own candidates: containment is asserted
///    against the checkout itself (the same strict-descendant rule
///    [`enumerate_registered_worktrees_in`]' "positive assertion" section
///    describes), and a path some earlier anchor already produced is left with
///    the attribution it already has.
///
/// Test (#7357): `scan_admits_a_worktree_under_an_adopted_checkout`,
/// `scan_ignores_an_adopted_checkout_inside_the_repos_root`,
/// `scan_does_not_duplicate_a_repeated_adopted_checkout`. Pass `&[]` for the
/// walk alone.
pub(crate) fn scan_registered_worktrees(
    repos_root: &Path,
    adopted: &[PathBuf],
) -> Vec<ScannedWorktree> {
    let canonical_root = std::fs::canonicalize(repos_root).unwrap_or_else(|_| repos_root.into());
    let mut found: BTreeSet<(PathBuf, PathBuf, ScannedKey)> = BTreeSet::new();
    let Ok(owner_entries) = std::fs::read_dir(repos_root) else {
        return Vec::new();
    };
    for owner_entry in owner_entries.flatten() {
        let owner_path = owner_entry.path();
        if !owner_path.is_dir() {
            continue;
        }
        let Ok(repo_entries) = std::fs::read_dir(&owner_path) else {
            continue;
        };
        for repo_entry in repo_entries.flatten() {
            let repo_path = repo_entry.path();
            // The containment boundary below is expressed against the project's
            // RESOLVED path. A project directory that will not canonicalize
            // cannot bound anything, so the whole project is skipped rather
            // than falling back to the far wider `repos_root` — a failed
            // observation may only ever shrink what this function proposes.
            let Ok(canonical_project) = std::fs::canonicalize(&repo_path) else {
                continue;
            };
            for anchor in [repo_path.clone(), repo_path.join(BASE_CLONE_DIRNAME)] {
                scan_from_anchor(&anchor, &canonical_root, &canonical_project, &mut found);
            }
        }
    }
    scan_adopted_checkouts(adopted, &canonical_root, &mut found);
    found
        .into_iter()
        .map(|(path, registry_root, key)| ScannedWorktree {
            path,
            project: key.project,
            registry_root,
            branch: key.branch,
            admission: key.admission,
        })
        .collect()
}

/// [`scan_registered_worktrees`], keeping only the rows `scope` admits (#8782).
///
/// Why: the one chokepoint both prune passes enumerate through, so a scoped
/// run cannot survey — or reclaim — another project's worktrees.
/// Test: `a_project_scope_admits_only_that_projects_worktrees`.
pub(crate) fn scan_registered_worktrees_in(
    repos_root: &Path,
    adopted: &[PathBuf],
    scope: &WorktreeScope,
) -> Vec<ScannedWorktree> {
    scan_registered_worktrees(repos_root, adopted)
        .into_iter()
        .filter(|s| scope.admits(s))
        .collect()
}

/// Record every worktree registered at an ADOPTED project checkout (#7357).
///
/// Why: the repos-root walk cannot reach these checkouts, and the fix must not
/// widen anything else while reaching them. Both guards below exist so an
/// adopted anchor can only ADD rows for paths nothing else produced.
/// What: skips an anchor that lies inside `canonical_root` (the walk already
/// covers it) and any path already present in `found`; otherwise interrogates
/// the checkout and its `.base` clone exactly as the walk does, with the
/// checkout itself as BOTH the containment root and the bounding project.
/// Test: `scan_admits_a_worktree_under_an_adopted_checkout`,
/// `scan_ignores_an_adopted_checkout_inside_the_repos_root`,
/// `scan_does_not_duplicate_a_repeated_adopted_checkout`.
fn scan_adopted_checkouts(
    adopted: &[PathBuf],
    canonical_root: &Path,
    found: &mut BTreeSet<(PathBuf, PathBuf, ScannedKey)>,
) {
    for checkout in adopted {
        let Ok(canonical_checkout) = std::fs::canonicalize(checkout) else {
            continue;
        };
        // Guard 1: the walk owns everything under the managed repos root.
        if canonical_checkout.starts_with(canonical_root) {
            continue;
        }
        let already: BTreeSet<PathBuf> = found.iter().map(|(p, _, _)| p.clone()).collect();
        let mut fresh: BTreeSet<(PathBuf, PathBuf, ScannedKey)> = BTreeSet::new();
        for anchor in [
            canonical_checkout.clone(),
            canonical_checkout.join(BASE_CLONE_DIRNAME),
        ] {
            scan_from_anchor(
                &anchor,
                &canonical_checkout,
                &canonical_checkout,
                &mut fresh,
            );
        }
        // Guard 2: never restate a path some earlier anchor already attributed.
        for row in fresh {
            if !already.contains(&row.0) {
                found.insert(row);
            }
        }
    }
}

/// The non-key remainder of a [`ScannedWorktree`], carried through the dedup
/// `BTreeSet` (#4288).
///
/// Why: deduplication is on (path, registry root) — the identity of the entry —
/// but `BTreeSet` needs the WHOLE tuple to be `Ord`, and the payload has to
/// ride along. Keeping it in a named struct rather than a bare tuple keeps
/// `scan_registered_worktrees`' final `map` readable.
/// What: the fields of [`ScannedWorktree`] that are not part of its identity.
/// Test: covered by every `scan_*` test.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct ScannedKey {
    project: PathBuf,
    branch: Option<String>,
    admission: Admission,
}

/// Record every worktree registered at `anchor`, with its admission verdict.
///
/// Why: extracted so [`scan_registered_worktrees`]' two anchors share one rule
/// rather than duplicating the root-confirmation, filtering, and containment
/// logic — the duplication that let the old walk's five shapes drift apart
/// from each other.
/// What: no-ops unless `anchor` is a directory that is ITSELF the root of the
/// repository owning its registry (see [`registry_root_for`]); then records
/// every worktree, marking [`Admission::Admitted`] only for the non-bare,
/// non-main, non-prunable, non-`locked` ones whose canonicalized path is a
/// STRICT DESCENDANT of `canonical_project` (the managed project directory —
/// see [`enumerate_registered_worktrees_in`]' "positive assertion" section) and
/// also lies under `canonical_root`.
///
/// Both containment checks are applied even though the first normally implies
/// the second: `canonical_project` is derived by canonicalizing a `read_dir`
/// entry, so a symlinked project directory could resolve OUTSIDE the managed
/// root, and the pair keeps the sweep bounded in that case too.
/// Test: covered by every `enumerate_*` and `scan_*` test.
fn scan_from_anchor(
    anchor: &Path,
    canonical_root: &Path,
    canonical_project: &Path,
    found: &mut BTreeSet<(PathBuf, PathBuf, ScannedKey)>,
) {
    if !anchor.is_dir() {
        return;
    }
    // Confirm the anchor is a repository ROOT, not merely a directory inside
    // one — otherwise git walks up and reports a foreign repository's registry.
    let Some(root) = registry_root_for(anchor) else {
        return;
    };
    let canonical_anchor = std::fs::canonicalize(anchor).unwrap_or_else(|_| anchor.into());
    let canonical_repo_root = std::fs::canonicalize(&root).unwrap_or(root);
    if canonical_anchor != canonical_repo_root {
        return;
    }
    let Some(worktrees) = list_registered_worktrees(anchor) else {
        return;
    };
    for wt in worktrees {
        let admission = admission_for(&wt, canonical_root, canonical_project);
        let path = std::fs::canonicalize(&wt.path).unwrap_or_else(|_| wt.path.clone());
        found.insert((
            path,
            canonical_repo_root.clone(),
            ScannedKey {
                project: canonical_project.to_path_buf(),
                branch: wt.branch.clone(),
                admission,
            },
        ));
    }
}

/// The [`Admission`] verdict for one porcelain record (#4288).
///
/// Why: the exclusion rules were `continue` statements inside the scan loop, so
/// nothing could name WHICH rule fired. Splitting them out makes each verdict
/// reportable without changing any of them — the order and the conditions are
/// exactly those `collect_from_anchor` applied before #4288.
/// What: applies, in order, the git-reported vetoes, then canonicalization,
/// then the two containment checks.
/// Test: `scan_reports_the_excluded_set_with_reasons`,
/// `enumerate_excludes_a_locked_worktree`.
fn admission_for(
    wt: &RegisteredWorktree,
    canonical_root: &Path,
    canonical_project: &Path,
) -> Admission {
    {
        // `locked` is git's own removal veto — the operator ran
        // `git worktree lock` to say "do not remove this".
        //
        // Be precise about WHY skipping here is load-bearing, because the
        // obvious reading is wrong and would get this filter deleted as
        // redundant. `git worktree remove --force` does NOT override a lock:
        // verified on git 2.54.0, a single `--force` exits 128 with "cannot
        // remove a locked working tree; use 'remove -f -f' to override or
        // unlock first", leaving the directory intact. Git respects the lock.
        //
        // The danger was what `decommission::remove_session_worktree` did with
        // that refusal: until #4732 it treated ANY non-zero git exit as "git
        // failed" and fell back to `std::fs::remove_dir_all`, deleting the
        // directory regardless — defeating the lock via the error path rather
        // than the force flag, AND leaving git's now-dangling registry entry
        // behind. The remover refuses now, so this filter is no longer the ONLY
        // place the veto survives; it is the first, and it is what keeps a
        // locked worktree out of every candidate list an operator is shown.
        if wt.bare {
            return Admission::Bare;
        }
        if wt.is_main {
            return Admission::MainCheckout;
        }
        if wt.prunable {
            return Admission::Prunable;
        }
        if wt.locked {
            // #6561: which KIND of lock, because only one of them names a
            // dispatched agent the operator must be told about.
            let harness = wt
                .lock_reason
                .as_deref()
                .is_some_and(is_harness_agent_lock_reason)
                && super::worktree_ownership::is_harness_agent_worktree(&wt.path);
            return if harness {
                Admission::HarnessAgentLock
            } else {
                Admission::Locked
            };
        }
        // #1845 item 8, preserved: a path that cannot be canonicalized is
        // SKIPPED, never proposed. A dangling symlink, a deletion race, an
        // unreadable parent, or a stalled mount all make the path unresolvable,
        // and an unresolvable path cannot be compared against the active-session
        // set — so proposing it would risk offering a LIVE worktree for
        // deletion. The asymmetry is deliberate: a failed observation reduces
        // what this function proposes, and can never enlarge it.
        let Ok(canonical) = std::fs::canonicalize(&wt.path) else {
            return Admission::Unresolvable;
        };
        // The structural boundary (#4224 HIGH). `starts_with` is component-wise,
        // so `<owner>/trusty-tools-worktrees/x` cannot match the project
        // `<owner>/trusty-tools`. The `!=` makes it STRICT: the project checkout
        // itself — the operator's working copy — is never a candidate, whether
        // or not some other registry lists it as a linked worktree.
        if canonical == canonical_project || !canonical.starts_with(canonical_project) {
            return Admission::OutsideProject;
        }
        if !canonical.starts_with(canonical_root) {
            return Admission::OutsideReposRoot;
        }
        Admission::Admitted
    }
}

#[cfg(test)]
#[path = "worktree_registry_tests.rs"]
mod worktree_registry_tests;