omni_dev/daemon/services/

worktrees.rs

//! The worktrees daemon service.
//!
//! A thin adapter that hosts the cross-window [`WorktreesRegistry`] under the
//! daemon's lifecycle and exposes register/heartbeat/unregister/list/tree/open
//! over the control socket, plus a tray submenu with a per-window "focus" action.
//! The `open` op (#1266) focuses/opens an arbitrary worktree folder in VS Code
//! through the **same** launcher path the tray uses, so a socket client (the
//! companion's double-click) shares the tested guard and launcher resolution
//! rather than duplicating them.
//!
//! All registry state and liveness logic (the `Mutex<HashMap>`, TTL reaping, the
//! entry cap/eviction) lives in [`crate::worktrees`]; this adapter only routes
//! ops, renders the menu/status, and drives the VS Code launcher. Like the
//! Snowflake service it is a cheap, in-memory adapter — no async setup, no
//! secret persisted.
//!
//! The adapter also computes the **per-worktree git enrichment** (current
//! branch, ahead/behind counts, and the parent repository a linked worktree
//! belongs to) on read via `git2` (#1186), keeping the companion a thin reporter
//! of raw folder paths (ADR-0040). The engine stores only what the companion
//! sends; disk I/O for the enrichment lives here, alongside the launcher, never
//! under the registry lock.
//!
//! The `tree` op (#1265) inverts the data model for the companion's tree view:
//! from the open windows the adapter derives the **distinct repositories**, then
//! enumerates **all** of each repo's worktrees (main working tree +
//! [`Repository::worktrees`]), enriches each (reusing [`git_status`]), tags the
//! GitHub identity of `origin`, and joins the open windows back on by
//! canonicalized path. The open-window registry stays the liveness source;
//! "is a window open on it?" becomes a per-worktree attribute. All of this is
//! git disk I/O, so it runs on a blocking thread, never under the registry lock.

mod divergence;
mod geometry;

use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::{Duration, Instant};

use anyhow::{anyhow, bail, Context, Result};
use chrono::{DateTime, Utc};

use crate::git::remote::RemoteInfo;
use crate::git::worktree_batch::Selection;
use crate::git::worktree_push;
use crate::git::worktree_rebase;
use crate::github_rate_limit::{
    resolve_rate_limit_with, RateLimitCache, RateLimitResource, RateLimitSnapshot,
};
use crate::pr_status::{
    EnqueueOutcome, PrBadge, PrCheckState, PrResolution, PrStatusCache, PrTarget,
};
use async_trait::async_trait;
use divergence::{AheadBehindCoordinator, Divergence};
use git2::{Repository, RepositoryState, Status, StatusOptions, WorktreeLockStatus};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use tokio::sync::watch;
use tokio::sync::Mutex as AsyncMutex;
use tokio::task::JoinHandle;
use tokio_util::sync::CancellationToken;

use crate::daemon::service::{
    DaemonService, MenuAction, MenuItem, MenuSnapshot, ServiceStatus, ServiceStream,
};
use crate::worktrees::{RegisterRequest, WindowEntry, WorktreesRegistry};

/// The worktrees service name (the control-socket routing key).
pub const SERVICE_NAME: &str = "worktrees";

/// The tray submenu title.
const SUBMENU_TITLE: &str = "Worktrees";

/// Environment override for the VS Code launcher used by the "focus" tray
/// action, for when the daemon runs under launchd with a minimal `PATH`.
const VSCODE_BIN_ENV: &str = "OMNI_DEV_VSCODE_BIN";

/// Environment override for [`menu_refresh_interval`] (whole seconds; a blank,
/// non-numeric, or `0` value falls back to [`DEFAULT_MENU_REFRESH_INTERVAL`]).
const ENV_MENU_REFRESH_INTERVAL: &str = "OMNI_DEV_DAEMON_MENU_REFRESH";

/// Default cadence at which the background task recomputes the tray menu snapshot
/// off the main thread when `OMNI_DEV_DAEMON_MENU_REFRESH` is unset. The macOS
/// tray polls `menu()` ~1 Hz and always serves this cache, never doing git I/O on
/// the GUI thread (which would peg a core and stall shutdown — the #1186
/// regression); the interval only governs how stale that cached branch/sync state
/// may be when the menu is opened.
///
/// Raised from 2 s to 10 s (#1305): this refresh is an independent per-window git
/// walk that the subscription-stream coalescing (#1303) never touched — it was
/// the dominant idle-CPU cost — so relaxing it cuts that cost ~5× while leaving
/// menu open-latency unchanged (the cache still serves instantly).
const DEFAULT_MENU_REFRESH_INTERVAL: Duration = Duration::from_secs(10);

/// The resolved tray menu-refresh cadence: `OMNI_DEV_DAEMON_MENU_REFRESH` (whole
/// seconds) when valid, else [`DEFAULT_MENU_REFRESH_INTERVAL`].
fn menu_refresh_interval() -> Duration {
    crate::daemon::server::duration_secs_from_env(
        ENV_MENU_REFRESH_INTERVAL,
        DEFAULT_MENU_REFRESH_INTERVAL,
    )
}

/// Environment override for [`pr_poll_interval`] — the cadence at which the PR
/// badge poller re-asks GitHub **while a badge is still pending** (whole seconds;
/// a blank, non-numeric, or `0` value falls back to [`DEFAULT_PR_POLL_INTERVAL`]).
const ENV_PR_POLL_INTERVAL: &str = "OMNI_DEV_DAEMON_PR_POLL";

/// Default cadence for the PR badge poller while CI is in flight (#1337).
///
/// Matches `gh pr checks --watch`, which uses 10 s when a human is actively
/// watching a run — which is exactly this situation. It is affordable because the
/// poll costs **1 point** regardless of how many repos, worktrees, or windows are
/// open: 10 s sustained is ~360 points/hour against a 5,000/hour budget, and only
/// while something is actually pending.
const DEFAULT_PR_POLL_INTERVAL: Duration = Duration::from_secs(10);

/// The ceiling the poller backs off to once every badge is terminal.
///
/// Nothing is expected to change, so this is a liveness heartbeat, not a watch.
/// The 30-minute figure is the cross-tool consensus for background PR polling
/// (vscode-pull-request-github's backoff ceiling, gh-dash's and GitLens's
/// defaults). The backoff exists for battery and wakeups rather than budget — at
/// 1 point per poll the budget never binds.
const MAX_PR_POLL_INTERVAL: Duration = Duration::from_secs(30 * 60);

/// How long after fresh work (a push, or an added target) the poller holds its
/// fast [`DEFAULT_PR_POLL_INTERVAL`] cadence before escalating *within* pending
/// (#1389, fix 5). Two minutes covers the window where a just-pushed run is most
/// likely to report; past it, a still-pending badge (a long build, a zombie suite)
/// is watched more cheaply. See [`next_pr_poll_delay`].
const PENDING_FAST_WINDOW: Duration = Duration::from_secs(2 * 60);

/// The ceiling the poller escalates to *while still pending* once
/// [`PENDING_FAST_WINDOW`] has passed (#1389, fix 5). Below the terminal
/// [`MAX_PR_POLL_INTERVAL`] because a pending badge is expected to change soon,
/// just not soon enough to justify pinning `base` — 60 s caps a 20-minute CI run
/// at ~50 calls instead of ~120.
const PENDING_MAX_INTERVAL: Duration = Duration::from_secs(60);

/// The cadence floor the poller is held to while the shared GitHub budget is
/// at/over [`WARN_PERCENT`](crate::github_rate_limit::WARN_PERCENT) (#1389, fix 6).
/// Five minutes makes the daemon's contribution to an already-strained budget
/// negligible while still recovering promptly once the window resets — a pause in
/// all but name. See [`budget_throttled_delay`].
const BUDGET_THROTTLE_INTERVAL: Duration = Duration::from_secs(5 * 60);

/// Environment override for [`pr_debounce_interval`] — the settle window the PR
/// poller waits after the change-notify fires before snapshotting (whole seconds;
/// a blank, non-numeric, or `0` value falls back to [`DEFAULT_PR_DEBOUNCE`]).
const ENV_PR_DEBOUNCE: &str = "OMNI_DEV_DAEMON_PR_DEBOUNCE";

/// Default settle window for the PR-poll change-notify debounce (#1389, fix 2).
///
/// A VS Code restart unregisters then re-registers its windows one-by-one over
/// several seconds, each bump waking the poller; a daemon restart re-registers the
/// same way. Waiting for ~2 s of quiet before snapshotting collapses the whole
/// storm into **one** fetch on the final watch set instead of one per window.
const DEFAULT_PR_DEBOUNCE: Duration = Duration::from_secs(2);

/// The resolved PR-poll cadence: `OMNI_DEV_DAEMON_PR_POLL` (whole seconds) when
/// valid, else [`DEFAULT_PR_POLL_INTERVAL`].
fn pr_poll_interval() -> Duration {
    crate::daemon::server::duration_secs_from_env(ENV_PR_POLL_INTERVAL, DEFAULT_PR_POLL_INTERVAL)
}

/// The resolved PR-poll debounce settle window: `OMNI_DEV_DAEMON_PR_DEBOUNCE`
/// (whole seconds) when valid, else [`DEFAULT_PR_DEBOUNCE`].
fn pr_debounce_interval() -> Duration {
    crate::daemon::server::duration_secs_from_env(ENV_PR_DEBOUNCE, DEFAULT_PR_DEBOUNCE)
}

/// Environment override for [`open_pr_ttl`] — how long the daemon reuses a repo's
/// `gh pr list` result before re-fetching (whole seconds; a blank, non-numeric, or
/// `0` value falls back to [`DEFAULT_OPEN_PR_TTL`]).
const ENV_OPEN_PR_TTL: &str = "OMNI_DEV_DAEMON_OPEN_PR_TTL";

/// Default TTL for the shared open-PR cache (#1389, fix 7). Matches the extension's
/// former per-window `gh pr list` cache (#1296): serving "Open Pull Request…" — and
/// the extension's transient badge fallback — from the daemon means N windows now
/// dedupe to **one** counted `gh` per repo per TTL, rather than one per window.
const DEFAULT_OPEN_PR_TTL: Duration = Duration::from_secs(60);

/// The `--json` fields the daemon requests from `gh pr list`, mirroring the
/// extension's `PR_JSON_FIELDS` so the forwarded array parses into its
/// `PullRequest` shape unchanged.
const OPEN_PR_JSON_FIELDS: &str = "number,title,url,headRefName,baseRefName,isDraft,state,author";

/// The `gh pr list --limit` cap — high enough to list a repo's open PRs in one call
/// (parity with the extension's `PR_LIST_LIMIT`).
const OPEN_PR_LIST_LIMIT: &str = "100";

/// The resolved open-PR cache TTL: `OMNI_DEV_DAEMON_OPEN_PR_TTL` (whole seconds)
/// when valid, else [`DEFAULT_OPEN_PR_TTL`].
fn open_pr_ttl() -> Duration {
    crate::daemon::server::duration_secs_from_env(ENV_OPEN_PR_TTL, DEFAULT_OPEN_PR_TTL)
}

/// Environment override for [`rate_limit_poll_interval`] — the cadence at which
/// the GitHub rate-limit monitor re-reads `/rate_limit` (whole seconds; a blank,
/// non-numeric, or `0` value falls back to [`DEFAULT_RATE_LIMIT_POLL_INTERVAL`]).
const ENV_RATE_LIMIT_POLL_INTERVAL: &str = "OMNI_DEV_DAEMON_RATE_LIMIT_POLL";

/// Default cadence for the GitHub rate-limit monitor (#1375).
///
/// A fixed 60 s is fine and simple: querying `/rate_limit` is **exempt** — it
/// spends nothing against any budget — so unlike the PR poller this cadence has no
/// budget concern and needs no adaptive backoff. One free `gh` subprocess a minute
/// keeps `daemon status` current enough to catch a slow drain.
const DEFAULT_RATE_LIMIT_POLL_INTERVAL: Duration = Duration::from_secs(60);

/// The resolved rate-limit-poll cadence: `OMNI_DEV_DAEMON_RATE_LIMIT_POLL` (whole
/// seconds) when valid, else [`DEFAULT_RATE_LIMIT_POLL_INTERVAL`].
fn rate_limit_poll_interval() -> Duration {
    crate::daemon::server::duration_secs_from_env(
        ENV_RATE_LIMIT_POLL_INTERVAL,
        DEFAULT_RATE_LIMIT_POLL_INTERVAL,
    )
}

/// A running background menu-refresh task and the token that stops it.
struct RefreshTask {
    /// Cancelled by `shutdown` to end the refresh loop.
    token: CancellationToken,
    /// The spawned loop, awaited on shutdown so it fully unwinds.
    handle: JoinHandle<()>,
}

/// Whether this tick should spend a `gh` call.
///
/// The poller wakes far more often than it fetches — waking is a cached snapshot
/// read, fetching is a subprocess and a network round trip. Two things justify the
/// call: the watch set **grew** (a target was added, or a branch's upstream moved —
/// a push, invisible to the change-notify, so only looking finds it), or the
/// **backoff elapsed** and it is simply time to look again.
///
/// A pure *removal* is deliberately not a reason (#1389): a window closing, a
/// worktree going away, a lease lapsing, or a TTL reap can never change any
/// **surviving** badge, so `grew` is false and the poll skips — see
/// [`pr_watch_grew`]. That kills the close-side of every burn scenario.
///
/// Pure so the policy is testable directly: from outside, the only evidence of it
/// is *when* a subprocess runs, which a test cannot pin down without either flaking
/// or passing for the wrong reason.
fn pr_should_fetch(grew: bool, since_last_fetch: Option<Duration>, backoff: Duration) -> bool {
    grew || since_last_fetch.is_none_or(|elapsed| elapsed >= backoff)
}

/// Whether `next` holds a watch the poller has not already resolved for its
/// current upstream — an **addition** (a new (repo, branch) target) or an
/// **upstream that moved** (a push — the #1344 case that starts the CI run a badge
/// reports). Either warrants asking GitHub *now*.
///
/// A pure removal is never "grew": [`PrWatch`] equality is `(target, upstream_sha)`
/// only, so a shrunk `next` that is otherwise a subset of `prev` returns `false`
/// and the poll coalesces (#1389). Head-only moves are excluded by construction —
/// [`PrWatch`] carries no head — because a local commit GitHub has not seen returns
/// exactly the cached verdict, and the badge stays correctly stale through
/// [`PrBadge::is_stale_for`](crate::pr_status::PrBadge::is_stale_for) with no
/// network call (#1389, fix 3).
///
/// Pure so the fetch trigger is testable without driving a live subprocess.
fn pr_watch_grew(prev: &[PrWatch], next: &[PrWatch]) -> bool {
    next.iter().any(|w| !prev.contains(w))
}

/// The next PR-poll delay.
///
/// - **Terminal** (`pending` false): double `current` up to [`MAX_PR_POLL_INTERVAL`]
///   — nothing is expected to change, so this is a slow liveness heartbeat. A failed
///   poll passes `pending: false`, so a persistent failure backs off here rather
///   than being retried hard.
/// - **Pending** (`pending` true): hold `base` (~10 s) for the first
///   [`PENDING_FAST_WINDOW`] after the watch last moved, then escalate — double
///   `current` up to [`PENDING_MAX_INTERVAL`] (#1389, fix 5). A single 20-minute CI
///   run used to pin `base` for its whole duration (360 calls/hour); escalating
///   *within* pending caps that while a verdict arriving a cadence-tick late stays
///   invisible in the tray. `since_moved` is time since fresh work was last seen (a
///   push or an added target), or `None` when nothing has moved yet — treated as
///   past the fast window so a stale-from-boot pending state does not pin `base`.
///
/// A pure function rather than copies inline, because the cadence is only
/// observable from outside as timing, which a test cannot assert without flaking.
fn next_pr_poll_delay(
    current: Duration,
    base: Duration,
    pending: bool,
    since_moved: Option<Duration>,
) -> Duration {
    if !pending {
        return current.saturating_mul(2).min(MAX_PR_POLL_INTERVAL);
    }
    match since_moved {
        // Fresh work: watch it closely at `base` while it is likely to resolve.
        Some(elapsed) if elapsed < PENDING_FAST_WINDOW => base,
        // Still pending well after the move (a long CI run, or a zombie suite):
        // escalate so the cadence stops burning, bounded below the terminal ceiling.
        _ => current.saturating_mul(2).min(PENDING_MAX_INTERVAL),
    }
}

/// Stretches a computed poll delay when the shared GitHub budget is under pressure.
///
/// The daemon is the **single** `gh` choke point for every open window, so this is
/// the one place a machine-wide cap can actually be enforced (#1389, fix 6). When
/// any tracked resource is at/over
/// [`WARN_PERCENT`](crate::github_rate_limit::WARN_PERCENT), the cadence is held at
/// no less than [`BUDGET_THROTTLE_INTERVAL`] so a runaway in this class cannot drain
/// the budget the whole machine shares — structurally, not just by convention. Below
/// the threshold (or with no reading yet) the delay is returned unchanged.
///
/// Pure so the throttle is testable without a live rate-limit poll.
fn budget_throttled_delay(delay: Duration, rate_limit: Option<&RateLimitSnapshot>) -> Duration {
    if rate_limit.is_some_and(RateLimitSnapshot::over_warn) {
        delay.max(BUDGET_THROTTLE_INTERVAL)
    } else {
        delay
    }
}

/// Whether the rate-limit poller should emit a WARN this poll: `true` only when a
/// resource **crosses** the [`WARN_PERCENT`](crate::github_rate_limit::WARN_PERCENT)
/// threshold upward since the previous reading (or is already over on the first
/// poll, when `prev` is `None`). Keying on the rising edge means the log fires once
/// per crossing rather than every poll while usage stays high.
///
/// Pure so the policy is testable without driving a live poll.
fn rate_limit_crossed_warn(prev: Option<&RateLimitSnapshot>, next: &RateLimitSnapshot) -> bool {
    let over = |res: Option<RateLimitResource>| res.is_some_and(|r| r.over_warn());
    // Per-resource so a *different* resource crossing (while another recovers) is
    // still caught — `graphql` dropping below while `core` climbs over would look
    // unchanged to a whole-snapshot `over_warn` comparison.
    [
        (prev.and_then(|p| p.graphql), next.graphql),
        (prev.and_then(|p| p.core), next.core),
        (prev.and_then(|p| p.search), next.search),
    ]
    .into_iter()
    .any(|(before, after)| over(after) && !over(before))
}

/// A running background PR-badge poll task and the token that stops it.
struct PollerTask {
    /// Cancelled by `shutdown` to end the poll loop.
    token: CancellationToken,
    /// The spawned loop, awaited on shutdown so it fully unwinds.
    handle: JoinHandle<()>,
}

/// One thing the PR poller watches: a badge target and the commit its upstream
/// points at.
///
/// The upstream OID is what makes a **push** observable to the poller. A window
/// opening bumps the registry's change-notify, but nothing notifies the daemon
/// when you push — so the poller compares this against the previous tick's and
/// treats an added target or a moved upstream as "go and ask now" (see
/// [`pr_watch_grew`]). A push moves **only** the upstream (#1344), and it is the
/// very thing that starts the CI run a badge reports, so the upstream must be here.
///
/// The local HEAD is deliberately **not** watched (#1389, fix 3): a local commit
/// GitHub has not seen would return exactly the cached verdict, so asking wastes a
/// call, and the badge stays correctly stale through
/// [`PrBadge::is_stale_for`](crate::pr_status::PrBadge::is_stale_for) — a local
/// comparison, no network — until the branch is actually pushed. Equality is thus
/// `(target, upstream_sha)`, which is exactly the key [`pr_watch_grew`] compares.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct PrWatch {
    /// The (repo, branch) to resolve a badge for.
    target: PrTarget,
    /// That branch's upstream tip, or `None` when it tracks no upstream.
    upstream_sha: Option<String>,
}

/// Extracts what the poller watches — the badge targets and their local heads and
/// upstream tips — from a `tree` snapshot.
///
/// Reading them back off the snapshot — rather than walking git again — means the
/// poller reuses the coalescing [`TreeSnapshotCache`] build instead of adding a
/// second independent per-worktree git walk, which is the idle-CPU cost #1305 went
/// out of its way to remove. Only GitHub repos with a branch contribute; the result
/// is sorted and deduped so N worktrees of one repo on one branch ask once.
fn pr_watch_from_snapshot(snapshot: &Value) -> Vec<PrWatch> {
    let mut out = Vec::new();
    for repo in snapshot
        .get("repos")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        // The zero-`gh` guarantee (#1376): a repo the user has not enabled
        // contributes no watch, so the poll's `gh api graphql` never mentions it.
        // The snapshot this reads is already `stamp_polling`-stamped, so this one
        // check is the single filter point — default-off means an absent flag skips.
        if repo.get("polling_enabled").and_then(Value::as_bool) != Some(true) {
            continue;
        }
        let Some(github) = repo.get("github") else {
            continue;
        };
        let (Some(owner), Some(name)) = (
            github.get("owner").and_then(Value::as_str),
            github.get("name").and_then(Value::as_str),
        ) else {
            continue;
        };
        for wt in repo
            .get("worktrees")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if let Some(branch) = wt.get("branch").and_then(Value::as_str) {
                out.push(PrWatch {
                    upstream_sha: wt
                        .get("upstream_sha")
                        .and_then(Value::as_str)
                        .map(str::to_string),
                    target: PrTarget {
                        owner: owner.to_string(),
                        name: name.to_string(),
                        branch: branch.to_string(),
                    },
                });
            }
        }
    }
    out.sort();
    out.dedup();
    out
}

/// The (repo, branch) pairs to resolve badges for — [`pr_watch_from_snapshot`]
/// without the heads.
#[cfg(test)]
fn pr_targets_from_snapshot(snapshot: &Value) -> Vec<PrTarget> {
    pr_watch_from_snapshot(snapshot)
        .into_iter()
        .map(|w| w.target)
        .collect()
}

/// Hosts the cross-window [`WorktreesRegistry`] as a [`DaemonService`].
pub struct WorktreesService {
    /// The cross-window registry this adapter routes ops to. Behind an `Arc` so
    /// the background menu-refresh task can read it off the main thread.
    registry: Arc<WorktreesRegistry>,
    /// The most recent tray menu snapshot, recomputed off the main thread by
    /// [`start_menu_refresh`](Self::start_menu_refresh). `menu()` serves a clone
    /// of this so it never blocks on git enrichment. `None` until the first
    /// refresh lands — or when no runtime started a task (e.g. unit tests) — in
    /// which case `menu()` falls back to a one-off inline compute.
    menu_cache: Arc<Mutex<Option<Vec<MenuItem>>>>,
    /// The background refresh task, once started (`None` in tests / no runtime).
    refresh: Mutex<Option<RefreshTask>>,
    /// PR badges resolved by the background poller and read by the tree snapshot
    /// build (#1337). Behind an `Arc` so the poll task and the snapshot builder
    /// share the one cache. Empty until the first poll lands — and always empty
    /// when no poller runs (unit tests), in which case the tree simply carries no
    /// `pr` field, exactly as a pre-#1337 daemon did.
    pr_cache: Arc<PrStatusCache>,
    /// The background PR-badge poll task, once started (`None` in tests / no
    /// runtime).
    poller: Mutex<Option<PollerTask>>,
    /// The GitHub API rate-limit snapshot the [`rate-limit poller`] writes and the
    /// tray menu build / built-in `status` op read (#1375). Behind an `Arc` so the
    /// poll task, the tray refresh, and the daemon's registry share the one cache.
    /// Empty until the first poll lands; the daemon hands a clone to the registry
    /// so `status` can report machine-wide GitHub budget usage.
    ///
    /// [`rate-limit poller`]: Self::start_rate_limit_poller
    rate_limit_cache: Arc<RateLimitCache>,
    /// The background rate-limit poll task, once started (`None` in tests / no
    /// runtime).
    rate_limit_poller: Mutex<Option<PollerTask>>,
    /// The shared, coalescing tree-snapshot cache every `subscribe` stream reads
    /// through, so N open windows perform **one** `build_tree` per tick instead
    /// of N (#1303). Behind an `Arc` so each stream holds a cheap handle to the
    /// one cache. The one-shot `tree` op deliberately bypasses it and computes
    /// fresh (it is a rare manual refresh, not part of the per-tick fan-out).
    tree_cache: Arc<TreeSnapshotCache>,
    /// Serializes [`remove_worktree`] across concurrent `close` executes (#1359).
    ///
    /// The extension fans a multi-select delete out into one `close` op per
    /// target, so two executes can reach the prune at once. Their heartbeat waits
    /// overlap freely — that is the point — but the prunes themselves should not:
    /// each op enumerates the repo's worktrees ([`worktree_name_for_path`]) and
    /// then prunes an entry out of that same `.git/worktrees`, so concurrent ops
    /// read a directory a sibling is midway through removing from, and `git2`
    /// promises nothing about that. Precautionary rather than a fix for an
    /// observed corruption — the window is narrow enough that it has not been
    /// reproduced — but serializing costs nothing measurable (the prune is a
    /// directory delete; the wait it follows is seconds) and keeps the fan-out
    /// safe at the source rather than relying on every caller to stay sequential.
    ///
    /// A `tokio` mutex rather than a `std` one: it is held across the
    /// `spawn_blocking` join, which is an `.await`.
    prune_lock: tokio::sync::Mutex<()>,
    /// Shares and bounds the `ahead-behind` op's git work across concurrent
    /// requests (#2111): N windows asking about the same worktree cost one
    /// computation, and only a few run at once. See [`divergence`].
    ahead_behind: AheadBehindCoordinator,
    /// Where the per-repo PR-poll enable set is persisted (#1376), so a user's
    /// choice survives a daemon restart. `None` disables persistence entirely —
    /// the default from [`new`](Self::new), which keeps the bare service cheap
    /// and I/O-free for unit tests; the daemon wires it via
    /// [`load_polling_prefs`](Self::load_polling_prefs) at startup. Behind a
    /// `std::Mutex` only so `load_polling_prefs` can set it on `&self`; read
    /// briefly and never held across an `.await`.
    polling_prefs_path: Mutex<Option<PathBuf>>,
    /// Where the resolved PR-badge cache is persisted (#1389, fix 4), so badges
    /// survive a daemon restart and the poller can skip its immediate re-poll when
    /// they are still fresh. `None` disables persistence — the default from
    /// [`new`](Self::new), keeping the bare service I/O-free for unit tests; the
    /// daemon wires it via [`load_pr_cache`](Self::load_pr_cache) at startup. Same
    /// `std::Mutex`-only-to-set-on-`&self` role as [`Self::polling_prefs_path`].
    pr_cache_path: Mutex<Option<PathBuf>>,
    /// The warm-start state restored from the persisted cache (#1389, fix 4),
    /// taken by [`start_pr_poller_with`](Self::start_pr_poller_with) when the loop
    /// spawns. `None` on a cold start (no file, or persistence disabled), in which
    /// case the poller does its normal first fetch.
    pr_warm_start: Mutex<Option<PrWarmStart>>,
    /// Shared TTL cache of `gh pr list` results per repo, backing the daemon-served
    /// `open-prs` op (#1389, fix 7) so N windows' "Open Pull Request…" lookups
    /// dedupe to one counted `gh` per repo instead of one per window. Behind an
    /// `Arc` for parity with the other caches.
    open_pr_cache: Arc<OpenPrCache>,
    /// Where the windows the **last** `reposition` moved were sitting beforehand,
    /// so `reposition-undo` can put them back (#1407).
    ///
    /// Exactly one level of undo, deliberately: the affordance exists because
    /// repositioning is otherwise irreversible (the previous layout is simply
    /// gone), and "undo the thing I just did" is the whole of what that needs. A
    /// deeper stack would raise questions — what does undoing an older batch mean
    /// once a newer one has moved the same window? — that a one-level store cannot
    /// pose. Each successful `reposition` replaces it; each `reposition-undo`
    /// consumes it, so an undo cannot be replayed.
    ///
    /// In-memory only, like every other piece of registry state: a daemon restart
    /// drops it, and the user is simply left with the layout they have. Behind its
    /// **own** `std::Mutex`, taken independently of the registry's (neither nests)
    /// and never held across an `.await`.
    reposition_undo: Mutex<Vec<(String, geometry::Frame)>>,
    /// Serializes the `rebase` op's phase-2 execute across concurrent requests
    /// (#1415) — the [`prune_lock`](Self::prune_lock) precedent, one op over.
    ///
    /// Within a batch the engine already rebases sequentially, on purpose: linked
    /// worktrees share one object database, and `git rebase` writes refs and
    /// packs into it. Two *concurrent requests* would defeat that, so the lock
    /// restores it globally. It also means a second click cannot start a rebase of
    /// a worktree the first is still mid-way through — the `operation`-in-progress
    /// classifier only sees state that is already on disk.
    ///
    /// A `tokio` mutex, since it is held across the `spawn_blocking` join.
    rebase_lock: tokio::sync::Mutex<()>,
    /// Serializes the `push` op's phase-2 execute across concurrent requests
    /// (#1443) — the [`rebase_lock`](Self::rebase_lock) twin.
    ///
    /// A successful push writes `refs/remotes/<remote>/<branch>` into the object
    /// database and ref store that every linked worktree of the repository shares,
    /// so concurrent batches would race on it. Taking the lock **before** the
    /// re-plan (not merely around the execute) is what keeps the classification the
    /// engine acts on from being invalidated by another batch's push mid-flight —
    /// which for a lease is not benign: a plan taken outside the lock could still
    /// say `would-force` against a tracking ref the other run has since advanced.
    ///
    /// Deliberately **separate** from `rebase_lock` rather than shared: a rebase and
    /// a push touch different refs (`refs/heads/*` vs `refs/remotes/*`) and there is
    /// no reason a push should wait behind an unrelated repository's rebase.
    ///
    /// A `tokio` mutex, since it is held across the `spawn_blocking` join.
    push_lock: tokio::sync::Mutex<()>,
}

impl WorktreesService {
    /// Creates the service with an empty registry. Cheap — no I/O and no task;
    /// the daemon calls [`start_menu_refresh`](Self::start_menu_refresh) to begin
    /// off-thread menu caching, while tests use the bare service (menu computed
    /// inline on demand).
    #[must_use]
    pub fn new() -> Self {
        let registry = Arc::new(WorktreesRegistry::new());
        let pr_cache = Arc::new(PrStatusCache::new());
        Self {
            registry: registry.clone(),
            menu_cache: Arc::new(Mutex::new(None)),
            refresh: Mutex::new(None),
            pr_cache: pr_cache.clone(),
            poller: Mutex::new(None),
            rate_limit_cache: Arc::new(RateLimitCache::new()),
            rate_limit_poller: Mutex::new(None),
            tree_cache: Arc::new(TreeSnapshotCache::new(registry, pr_cache)),
            prune_lock: tokio::sync::Mutex::new(()),
            ahead_behind: AheadBehindCoordinator::new(),
            polling_prefs_path: Mutex::new(None),
            pr_cache_path: Mutex::new(None),
            pr_warm_start: Mutex::new(None),
            open_pr_cache: Arc::new(OpenPrCache::new(open_pr_ttl())),
            reposition_undo: Mutex::new(Vec::new()),
            rebase_lock: tokio::sync::Mutex::new(()),
            push_lock: tokio::sync::Mutex::new(()),
        }
    }

    /// Seeds the per-repo PR-poll enable set from the persisted `0600` prefs file
    /// and remembers `path` so later [`set-polling`](Self::handle) changes persist
    /// back to it (#1376). Called once by the daemon at startup, before any window
    /// subscribes — so [`seed_polling`](WorktreesRegistry::seed_polling) needs no
    /// bump. Best-effort throughout: a missing file is the first-run default (no
    /// repos enabled), and a corrupt/unreadable one is logged and treated as
    /// empty rather than wedging the service — the user simply re-enables. The
    /// path is stored regardless, so the next change rewrites a clean file.
    pub fn load_polling_prefs(&self, path: PathBuf) {
        match std::fs::read(&path) {
            Ok(bytes) => match serde_json::from_slice::<PollingPrefs>(&bytes) {
                Ok(prefs) => self
                    .registry
                    .seed_polling(prefs.enabled.into_iter().map(|l| (l.repo, l.expires_at))),
                Err(err) => tracing::warn!(
                    "ignoring unreadable worktrees polling prefs at {}: {err:#}",
                    path.display()
                ),
            },
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
            Err(err) => tracing::warn!(
                "could not read worktrees polling prefs at {}: {err:#}",
                path.display()
            ),
        }
        *self
            .polling_prefs_path
            .lock()
            .unwrap_or_else(PoisonError::into_inner) = Some(path);
    }

    /// Writes the current enable set to the `0600` prefs file, if persistence is
    /// configured ([`load_polling_prefs`](Self::load_polling_prefs) set a path).
    /// Best-effort: a write failure is logged at WARN and swallowed, since the
    /// in-memory set is authoritative for the running daemon — the user's toggle
    /// still took effect, it just would not survive a restart. A no-op (returns
    /// early) in unit tests, which never configure a path.
    fn persist_polling_prefs(&self) {
        let Some(path) = self
            .polling_prefs_path
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .clone()
        else {
            return;
        };
        let prefs = PollingPrefs {
            enabled: self
                .registry
                .polling_snapshot()
                .into_iter()
                .map(|(repo, expires_at)| PollingLease { repo, expires_at })
                .collect(),
        };
        if let Err(err) = write_polling_prefs(&path, &prefs) {
            tracing::warn!(
                "could not persist worktrees polling prefs to {}: {err:#}",
                path.display()
            );
        }
    }

    /// Seeds the resolved PR-badge cache from the persisted `0600` file and
    /// remembers `path` so each poll persists back to it (#1389, fix 4). Called
    /// once by the daemon at startup, before any window subscribes and before the
    /// poller spawns, so restored badges render on the first tree snapshot and the
    /// poller can skip its immediate re-poll for verdicts still fresh.
    ///
    /// Best-effort throughout (the [`load_polling_prefs`](Self::load_polling_prefs)
    /// contract): a missing file is the cold-start default, and a corrupt/unreadable
    /// one is logged and treated as empty — the poller simply re-resolves. The path
    /// is stored regardless, so the next poll rewrites a clean file. Restores both
    /// the badges (into [`pr_cache`](Self::pr_cache)) and the
    /// [`PrWarmStart`](PrWarmStart) the poller reads at spawn.
    pub fn load_pr_cache(&self, path: PathBuf) {
        match std::fs::read(&path) {
            Ok(bytes) => match serde_json::from_slice::<PrCachePrefs>(&bytes) {
                Ok(prefs) => {
                    self.pr_cache.seed(
                        prefs
                            .entries
                            .into_iter()
                            .map(|e| (e.target, e.resolution.into_resolution())),
                    );
                    // A warm start needs both a watch set to compare against and a
                    // poll time to age it; without `polled_at` the file is too old a
                    // shape to trust, so treat it as a cold start (badges still
                    // render, the poller just re-polls immediately).
                    if let Some(polled_at) = prefs.polled_at {
                        let watched = prefs
                            .watched
                            .into_iter()
                            .map(|w| PrWatch {
                                target: w.target,
                                upstream_sha: w.upstream_sha,
                            })
                            .collect();
                        *self
                            .pr_warm_start
                            .lock()
                            .unwrap_or_else(PoisonError::into_inner) =
                            Some(PrWarmStart { watched, polled_at });
                    }
                }
                // Bind the path so it is formatted whenever the branch runs — not
                // only when a WARN subscriber is installed — so coverage sees it
                // (the `let summary = …` pattern the rate-limit warn uses).
                Err(err) => {
                    let at = path.display();
                    tracing::warn!("ignoring unreadable worktrees PR cache at {at}: {err:#}");
                }
            },
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
            Err(err) => {
                let at = path.display();
                tracing::warn!("could not read worktrees PR cache at {at}: {err:#}");
            }
        }
        *self
            .pr_cache_path
            .lock()
            .unwrap_or_else(PoisonError::into_inner) = Some(path);
    }

    /// Resolves a repo's open pull requests for the `open-prs` op (#1389, fix 7),
    /// served from the shared TTL cache when fresh, else **one** counted `gh pr
    /// list`. The `gh` runs on a blocking thread (never an async worker), routed
    /// through the #1387-counted [`run_gh`](crate::github_metrics::run_gh) choke
    /// point so the call is still counted exactly once — the constraint the whole
    /// of #1389 preserves. The result is forwarded to the extension verbatim.
    async fn open_prs(&self, owner: &str, name: &str) -> Result<Vec<Value>> {
        // The `gh` binary is resolved once here (the env read is process-stable),
        // then handed to the seam below — the poller's "bin as a param" pattern, so
        // a test injects a stub without mutating the process environment (#1030).
        self.open_prs_with(owner, name, crate::pr_status::resolve_gh_binary())
            .await
    }

    /// [`open_prs`](Self::open_prs) with an explicit `gh` binary, so a test drives
    /// the cache against a stub without touching the environment.
    async fn open_prs_with(&self, owner: &str, name: &str, bin: PathBuf) -> Result<Vec<Value>> {
        let key = format!("{owner}/{name}");
        if let Some(prs) = self.open_pr_cache.fresh(&key) {
            return Ok(prs);
        }
        let slug = key.clone();
        let prs = tokio::task::spawn_blocking(move || open_pr_list(&bin, &slug))
            .await
            .unwrap_or_else(|err| Err(anyhow!("blocking open-prs task failed: {err}")))?;
        self.open_pr_cache.store(key, prs.clone());
        Ok(prs)
    }

    /// A handle to the GitHub rate-limit snapshot cache (#1375), so the daemon can
    /// share it with the [`ServiceRegistry`](crate::daemon::registry::ServiceRegistry)
    /// for the built-in `status` op to read.
    #[must_use]
    pub fn rate_limit_cache(&self) -> Arc<RateLimitCache> {
        self.rate_limit_cache.clone()
    }

    /// Starts the background task that recomputes the tray menu snapshot every
    /// [`menu_refresh_interval`] **off the main thread** — git enrichment is
    /// blocking disk I/O — and stores it in [`menu_cache`](Self::menu_cache), so
    /// the macOS tray's `menu()` serves a cache instead of running git on the GUI
    /// event loop. Idempotent, and a no-op outside a tokio runtime (mirroring the
    /// Snowflake keep-alive heartbeat), so unit tests that build a bare service
    /// keep computing the menu inline.
    pub fn start_menu_refresh(&self) {
        if tokio::runtime::Handle::try_current().is_err() {
            tracing::debug!("no tokio runtime; worktrees menu refresh not started");
            return;
        }
        let mut guard = self.refresh.lock().unwrap_or_else(PoisonError::into_inner);
        if guard.is_some() {
            return;
        }
        let token = CancellationToken::new();
        let loop_token = token.clone();
        let registry = self.registry.clone();
        let cache = self.menu_cache.clone();
        let rate_limit_cache = self.rate_limit_cache.clone();
        // Resolved once at spawn: the interval is process-stable env config, and
        // re-reading it every loop would be wasted work.
        let interval = menu_refresh_interval();
        let handle = tokio::spawn(async move {
            loop {
                // Snapshot the registry (a cheap lock), then build the menu —
                // which opens repos and parses git config — on a blocking thread,
                // never on this async worker or the tray's main thread.
                let entries = registry.list();
                // The rate-limit reading (a cheap lock, `Copy`) prepends a status
                // line; read it here and hand it to the blocking build (#1375).
                let rate_limit = rate_limit_cache.get();
                if let Ok(items) = tokio::task::spawn_blocking(move || {
                    menu_items_for(&entries, rate_limit.as_ref())
                })
                .await
                {
                    *cache.lock().unwrap_or_else(PoisonError::into_inner) = Some(items);
                }
                tokio::select! {
                    () = loop_token.cancelled() => break,
                    () = tokio::time::sleep(interval) => {}
                }
            }
        });
        *guard = Some(RefreshTask { token, handle });
    }

    /// Starts the background task that keeps PR check badges fresh (#1337).
    ///
    /// This is the half of the badge nothing else can do. Badges used to be
    /// resolved extension-side on repo-expand, so they were recomputed only when a
    /// repo node's children were rebuilt — and the streamed snapshot carries
    /// worktree topology, not CI. While CI ran and no window opened or closed,
    /// nothing re-asked GitHub and a badge stayed wrong indefinitely.
    ///
    /// The loop resolves **every** (repo, branch) pair in one `gh api graphql` call
    /// (cost 1, independent of repo/worktree/window count), writes the cache the
    /// tree snapshot reads, and bumps the registry's change-notify **only when a
    /// verdict actually moved** — so the server's diff pushes to every open window
    /// exactly when CI state changes, and never otherwise.
    ///
    /// Cadence adapts: [`pr_poll_interval`] (~10 s) while a badge is pending and
    /// fresh, escalating to [`PENDING_MAX_INTERVAL`] once a pending phase runs long
    /// (#1389, fix 5) and doubling to [`MAX_PR_POLL_INTERVAL`] once everything is
    /// terminal; it polls nothing at all while no window is registered.
    ///
    /// It spends a `gh` call only when the watch set **grows** — a target added or
    /// an upstream pushed (#1389, fixes 1/3) — or the backoff elapses; a pure
    /// removal (window close, VS Code/daemon shutdown, TTL reap, lease lapse) never
    /// fetches. A change-notify storm is debounced ([`pr_debounce_interval`],
    /// #1389 fix 2) into one fetch, restored badges survive a restart (#1389 fix
    /// 4), and the cadence is capped when the shared GitHub budget is strained
    /// (#1389 fix 6).
    ///
    /// Idempotent, and a no-op outside a tokio runtime (mirroring
    /// [`start_menu_refresh`](Self::start_menu_refresh) and the Snowflake keep-alive
    /// heartbeat), so unit tests build a bare service that never spawns `gh`.
    pub fn start_pr_poller(&self) {
        // Resolved once at spawn: process-stable env config (the menu-refresh
        // precedent), never re-read per poll.
        self.start_pr_poller_with(
            pr_poll_interval(),
            pr_debounce_interval(),
            crate::pr_status::resolve_gh_binary(),
        );
    }

    /// [`start_pr_poller`](Self::start_pr_poller) with an explicit cadence,
    /// debounce settle window, and `gh` binary, so tests drive the loop at
    /// millisecond speed against a stub **without mutating the process
    /// environment** — one global env var cannot serve two parallel tests pointing
    /// at different fakes. Mirrors the [`TreeSnapshotCache::with_ttl`] seam and the
    /// Snowflake heartbeat's "interval via config, not env" rule.
    ///
    /// Reads the rate-limit cache, the persistence path, and the warm-start state
    /// off `self` at spawn (all `#1389` inputs), so its signature stays close to
    /// the original two-cadence seam.
    fn start_pr_poller_with(&self, base: Duration, debounce: Duration, gh_bin: PathBuf) {
        if tokio::runtime::Handle::try_current().is_err() {
            tracing::debug!("no tokio runtime; worktrees PR poller not started");
            return;
        }
        let mut guard = self.poller.lock().unwrap_or_else(PoisonError::into_inner);
        if guard.is_some() {
            return;
        }
        let token = CancellationToken::new();
        let loop_token = token.clone();
        let registry = self.registry.clone();
        let tree_cache = self.tree_cache.clone();
        let pr_cache = self.pr_cache.clone();
        // The shared budget reading (#1389, fix 6) and the `0600` persistence path +
        // restored warm start (#1389, fix 4). The warm start is *taken* — it seeds
        // the loop once and must not be reused by a later restart of the poller.
        let rate_limit_cache = self.rate_limit_cache.clone();
        let pr_cache_path = self
            .pr_cache_path
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .clone();
        let warm_start = self
            .pr_warm_start
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .take();
        // Captured here, before the task's first sleep, so a window that registers
        // while the loop is starting still wakes it rather than being missed.
        let mut changes = self.registry.subscribe_changes();
        let handle = tokio::spawn(async move {
            // Two independent cadences. The loop *wakes* every `base` — cheap: a read
            // of the coalescing snapshot cache, no subprocess, no network. It only
            // *asks GitHub* when there is reason to: the watch set grew (a target
            // added, or an upstream pushed), or the backoff has elapsed.
            //
            // They have to be separate because the two things that should trigger a
            // fetch arrive by different routes. A window opening bumps the registry's
            // change-notify, but **a push does not** — nothing in the daemon is
            // notified when you `git push`. The only way to notice is to look, so the
            // loop looks often and cheaply, and pays only when something grew.
            let mut backoff = base;
            // Warm start (#1389, fix 4): resume what the previous daemon last
            // resolved and when, so a restart within the backoff window skips the
            // immediate re-poll for verdicts already restored into `pr_cache`.
            // `last_poll` is reconstructed as an `Instant` that many seconds ago; a
            // reboot (monotonic epoch reset) or a future timestamp collapses to
            // "never polled", which just re-polls — the safe direction.
            let (mut watched, mut last_poll): (Option<Vec<PrWatch>>, Option<Instant>) =
                match warm_start {
                    Some(ws) => {
                        let elapsed = (Utc::now() - ws.polled_at)
                            .to_std()
                            .unwrap_or(Duration::ZERO);
                        (Some(ws.watched), Instant::now().checked_sub(elapsed))
                    }
                    None => (None, None),
                };
            // When fresh work (a push or an added target) was last seen, so the
            // pending cadence can escalate once it goes quiet (#1389, fix 5).
            let mut moved_at: Option<Instant> = None;
            'poll: loop {
                // Wait first: at startup no window has registered yet, and the
                // first snapshot would be empty anyway.
                tokio::select! {
                    () = loop_token.cancelled() => break,
                    () = tokio::time::sleep(base) => {}
                    // A window opened or closed — look now rather than at the next
                    // tick, but debounce first.
                    result = changes.changed() => {
                        // Unreachable today: this task owns an `Arc` of the registry
                        // that holds the sender, so it cannot be dropped while we are
                        // here. Kept anyway because the alternative is worse — a
                        // closed channel makes `changed()` return `Ready` forever, so
                        // ignoring the error would spin this loop at full speed,
                        // re-snapshotting and re-running `gh` every iteration.
                        if result.is_err() {
                            break;
                        }
                        // Debounce (#1389, fix 2): a VS Code restart unregisters then
                        // re-registers its windows one-by-one over several seconds,
                        // each bump waking us; a daemon restart re-registers the same
                        // way. Wait for `debounce` of quiet before snapshotting so the
                        // whole storm collapses to **one** fetch on the final watch
                        // set. Bounded by an overall deadline so a steady drip of
                        // changes cannot postpone the poll forever.
                        let overall_deadline = Instant::now() + debounce.saturating_mul(4);
                        loop {
                            tokio::select! {
                                () = loop_token.cancelled() => break 'poll,
                                () = tokio::time::sleep(debounce) => break,
                                r = changes.changed() => {
                                    if r.is_err() {
                                        break 'poll;
                                    }
                                    if Instant::now() >= overall_deadline {
                                        break;
                                    }
                                }
                            }
                        }
                    }
                }
                // Off the coalescing snapshot cache, so this reuses the tick's
                // `build_tree` rather than walking git a second time.
                let snapshot = tree_cache.snapshot().await;
                let watch = pr_watch_from_snapshot(&snapshot);
                if watch.is_empty() {
                    // No windows, or nothing on GitHub: ask nothing, and forget any
                    // backoff so the next tree starts fresh. But **keep** `watched`
                    // (#1389, fix 4): a VS Code restart momentarily empties the watch
                    // mid-storm, and nulling it here would make the re-registered set
                    // look brand-new and re-fetch. A genuinely gone tree simply has
                    // nothing to compare against on the next non-empty tick.
                    backoff = base;
                    last_poll = None;
                    moved_at = None;
                    continue;
                }
                // Did the watched set **grow** (an addition, or an upstream pushed)?
                // A pure removal is not a reason to fetch (#1389, fix 1); a local
                // commit is not either (#1389, fix 3, `PrWatch` carries no head).
                let grew = pr_watch_grew(watched.as_deref().unwrap_or(&[]), &watch);
                // Prune verdicts for targets that vanished, so a closed worktree's
                // badge does not linger in the cache (#1389, fix 1) — local, no
                // network, and correct whether or not this tick goes on to fetch.
                let keep: HashSet<PrTarget> = watch.iter().map(|w| w.target.clone()).collect();
                pr_cache.retain_targets(&keep);
                // Budget-aware cap (#1389, fix 6): the daemon is the single `gh`
                // choke point, so throttling here is the one place a machine-wide cap
                // works. Over WARN_PERCENT, hold the stretched cadence *and* ignore an
                // immediate `grew`, so no runaway in this class can drain the shared
                // budget — structurally, not by convention.
                let rate_limit = rate_limit_cache.get();
                let over_budget = rate_limit.is_some_and(|s| s.over_warn());
                let effective_backoff = budget_throttled_delay(backoff, rate_limit.as_ref());
                let trigger = grew && !over_budget;
                if !pr_should_fetch(trigger, last_poll.map(|at| at.elapsed()), effective_backoff) {
                    // Not fetching this tick. Advance `watched` only for a pure shrink
                    // or a quiet identical tick — an addition/push (`grew`) must stay
                    // unresolved so it is still fetched once the cadence or budget
                    // allows, rather than being silently consumed here.
                    if !grew {
                        watched = Some(watch);
                    }
                    continue;
                }
                if grew {
                    // Fresh work: watch it closely and restart the escalation clock
                    // rather than serving out a backoff earned while it was quiet.
                    backoff = base;
                    moved_at = Some(Instant::now());
                }
                let targets: Vec<PrTarget> = watch.iter().map(|w| w.target.clone()).collect();
                // `gh` is a blocking subprocess: never on an async worker. A join
                // failure (the task panicked, or the runtime is going down) folds
                // into the same error channel as a `gh` failure — both mean "no
                // badges this round", and neither deserves its own handling.
                let bin = gh_bin.clone();
                let resolved = tokio::task::spawn_blocking(move || {
                    crate::pr_status::resolve_with_budget(&bin, &targets)
                })
                .await
                .unwrap_or_else(|err| Err(anyhow!("blocking poll task failed: {err}")));
                // Best-effort decoration: a missing/unauthenticated `gh`, a network
                // blip, or a rate limit must never sink the tree. A failed poll
                // leaves the last good resolutions in place — badges *and* explicit
                // negatives, and it mints no new negatives (#1370) — rather than
                // blanking every row, and is not "pending", so it backs off rather
                // than hammers.
                let (pending, resolved_ok) = match resolved {
                    Ok((resolutions, budget)) => {
                        // Fold the free budget reading this poll carried into the
                        // shared cache (#1389, fix 8): the graphql figure stays fresh
                        // whenever polling is active, which lets the standalone
                        // `/rate_limit` poller idle (fix 8b), and the poll's `cost`
                        // reveals the real per-call point price.
                        if let Some(b) = budget {
                            tracing::debug!(
                                "PR poll cost {} point(s); graphql {}/{} used, {} remaining",
                                b.cost,
                                b.used,
                                b.limit,
                                b.remaining
                            );
                            rate_limit_cache.observe_graphql(RateLimitResource::new(
                                b.used,
                                b.limit,
                                b.remaining,
                                b.reset,
                            ));
                        }
                        // Bump only on a real change, or the server's diff-and-drop
                        // is defeated and every window re-renders on every poll.
                        if pr_cache.replace(resolutions) {
                            registry.bump();
                        }
                        (pr_cache.any_pending(), true)
                    }
                    Err(err) => {
                        tracing::debug!("PR badge poll failed: {err:#}");
                        (false, false)
                    }
                };
                last_poll = Some(Instant::now());
                // Record what this verdict was about, so the *next* tick can tell a
                // genuine change from a quiet tree.
                watched = Some(watch);
                let since_moved = moved_at.map(|at| at.elapsed());
                backoff = next_pr_poll_delay(backoff, base, pending, since_moved);
                // Persist the fresh verdicts (#1389, fix 4) so the next restart
                // serves them and can skip its immediate re-poll. Only on a real
                // resolution — a failed poll must not advance the persisted poll time
                // past the last *good* one. Best-effort; a write failure costs at
                // most one extra poll after the next restart.
                if resolved_ok {
                    if let Some(path) = &pr_cache_path {
                        persist_pr_cache(
                            path,
                            &pr_cache,
                            watched.as_deref().unwrap_or(&[]),
                            Utc::now(),
                        );
                    }
                }
            }
        });
        *guard = Some(PollerTask { token, handle });
    }

    /// Starts the background task that keeps the GitHub API rate-limit reading
    /// fresh (#1375).
    ///
    /// The daemon's PR-badge poller shells out to `gh`, spending the same GitHub
    /// budget as every other tool sharing the user's token; when that drains, `gh`
    /// rate-limits machine-wide with no warning until commands start failing. This
    /// loop polls `gh api rate_limit` — an endpoint GitHub documents (and this
    /// project verified) as **exempt**, spending nothing against any budget — so
    /// `daemon status`, the JSON payload, and the tray can show the used-percentage
    /// *trend* and warn before exhaustion, at zero cost to the budget watched.
    ///
    /// A plain fixed cadence ([`rate_limit_poll_interval`], ~60 s): no adaptive
    /// backoff and no window-gating, because the endpoint is free and a current
    /// reading is wanted whenever an operator checks `status`. Idempotent, and a
    /// no-op outside a tokio runtime (mirroring [`start_pr_poller`](Self::start_pr_poller)
    /// and [`start_menu_refresh`](Self::start_menu_refresh)), so unit tests build a
    /// bare service that never spawns `gh`.
    pub fn start_rate_limit_poller(&self) {
        // Both resolved once at spawn: process-stable env config, never re-read per
        // poll (the PR-poller precedent).
        self.start_rate_limit_poller_with(
            rate_limit_poll_interval(),
            crate::pr_status::resolve_gh_binary(),
        );
    }

    /// [`start_rate_limit_poller`](Self::start_rate_limit_poller) with an explicit
    /// cadence and `gh` binary, so tests drive the loop at millisecond speed
    /// against a stub **without mutating the process environment** (the
    /// [`start_pr_poller_with`](Self::start_pr_poller_with) seam).
    fn start_rate_limit_poller_with(&self, interval: Duration, gh_bin: PathBuf) {
        if tokio::runtime::Handle::try_current().is_err() {
            tracing::debug!("no tokio runtime; worktrees rate-limit poller not started");
            return;
        }
        let mut guard = self
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner);
        if guard.is_some() {
            return;
        }
        let token = CancellationToken::new();
        let loop_token = token.clone();
        let cache = self.rate_limit_cache.clone();
        let registry = self.registry.clone();
        let handle = tokio::spawn(async move {
            // Remembers the previous reading so a WARN fires only on the *rising*
            // edge across the threshold, not every poll while usage stays high.
            let mut prev: Option<RateLimitSnapshot> = None;
            loop {
                // Gate the poll on activity (#1389, fix 8b): a fully-idle daemon —
                // no window registered and no polling lease active — has nothing to
                // watch, so it spends no `/rate_limit` subprocess and lets the last
                // reading stand. The read is free against the budget, but the
                // wakeups are not; and while polling *is* active the graphql figure
                // stays fresh from every PR poll's folded-in budget (fix 8a), so the
                // standalone poll is only topping up `core`/`search`.
                if !registry.list().is_empty() || !registry.polling_snapshot().is_empty() {
                    // Poll first, so `status` has a reading soon after a window
                    // appears rather than one interval later. `gh` is a blocking
                    // subprocess: never on an async worker. A join failure folds into
                    // the same channel as a `gh` failure — both mean "no fresh
                    // reading this round".
                    let bin = gh_bin.clone();
                    let resolved =
                        tokio::task::spawn_blocking(move || resolve_rate_limit_with(&bin))
                            .await
                            .unwrap_or_else(|err| {
                                Err(anyhow!("blocking rate-limit poll task failed: {err}"))
                            });
                    match resolved {
                        Ok(snap) => {
                            if rate_limit_crossed_warn(prev.as_ref(), &snap) {
                                // Bound to a local (rather than inlined into the
                                // macro) so it is computed whenever the branch is
                                // taken, not only when a WARN-level subscriber is
                                // installed — `tracing` skips evaluating macro args
                                // otherwise.
                                let summary = snap.summary_line();
                                tracing::warn!(
                                    "GitHub API rate limit high: {summary} (querying \
                                     /rate_limit is free; the daemon's gh usage is not)"
                                );
                            }
                            // Update the cache only; deliberately no `registry.bump()`
                            // — the rate limit is not tree topology, and bumping would
                            // re-push an unchanged tree to every window. The tray
                            // re-polls `menu()` at ~1 Hz and `status` reads on demand.
                            cache.replace(snap);
                            prev = Some(snap);
                        }
                        // Best-effort decoration: a missing/unauthenticated `gh` or a
                        // network blip leaves the last good reading in place rather
                        // than blanking the line, and never affects the budget (the
                        // read is free).
                        Err(err) => tracing::debug!("GitHub rate-limit poll failed: {err:#}"),
                    }
                }
                tokio::select! {
                    () = loop_token.cancelled() => break,
                    () = tokio::time::sleep(interval) => {}
                }
            }
        });
        *guard = Some(PollerTask { token, handle });
    }

    /// Handles the `close` op: close a worktree's window and, for a **linked**
    /// worktree, delete it. The flow has two phases keyed off `confirmed`:
    ///
    /// - **Phase 1** (`remove:true`, `confirmed:false`) — a pure, side-effect-free
    ///   [`git_safety`] check returning the risks of deleting, so the extension can
    ///   show a modal confirm only when something would actually be lost.
    /// - **Phase 2** (`confirmed:true`, or any `remove:false`) — execute: signal
    ///   the owning window(s) to close, then (for `remove:true`) `git2`-prune the
    ///   worktree. The main working tree is refused defensively.
    ///
    /// Cross-window signalling (another window has the target open) is a
    /// fast-follow: this core handles the **no-window** and **self-close**
    /// (`requester_key == target_key`) cases, and errors clearly when another
    /// window owns the target so the destructive path is never taken blind.
    async fn close(&self, req: CloseRequest) -> Result<Value> {
        // Which live windows currently have the target open. The canonical-path
        // compare is disk I/O, so run it (with the safety check below) on a
        // blocking thread, never under the registry lock or on the async worker.
        let entries = self.registry.list();
        let scan_path = req.path.clone();
        let open_windows =
            tokio::task::spawn_blocking(move || windows_with_path(&entries, &scan_path))
                .await
                .unwrap_or_default();
        let open = !open_windows.is_empty();
        let window_key = open_windows.first().map(|(k, _)| k.clone());
        let window_folder_count = open_windows.first().map_or(0, |(_, c)| *c);

        // Phase 1: the safety check runs only for a delete request awaiting
        // confirmation. A "Close Window" (remove:false) never inspects git and
        // has nothing to confirm, so it skips straight to execute.
        if req.remove && !req.confirmed {
            let path = req.path.clone();
            let git = tokio::task::spawn_blocking(move || git_safety(&path))
                .await
                .map_err(|e| anyhow!("safety check task panicked: {e}"))
                .and_then(|inner| inner)
                .map_err(|err| log_close_error(&req.path, "safety check", err))?;
            // Make the phase-1 verdict auditable in `omni-dev daemon logs`
            // (#1364): the target, the owning window key (if any), whether a
            // window has it open, and the deletability verdict — with the
            // blocking risk kinds that force a confirm dialog, so a later "why did
            // the close prompt/refuse?" is answerable from the log alone.
            log_safety_check(&req.path, window_key.as_deref(), &git, open);
            return Ok(serde_json::to_value(SafetyReport {
                removable: git.removable,
                is_main: git.is_main,
                open,
                window_key,
                window_folder_count,
                risks: git.risks,
                info: git.info,
            })
            .unwrap_or_else(|_| json!({})));
        }

        // Phase 2: execute. Signal every owning window *other than the
        // requester* (which closes itself on our `ok:true` reply, avoiding the
        // ext-host-dies-mid-op race) and wait for each to unregister before
        // touching the worktree. The directive reaches a cross-window target via
        // its heartbeat reply — the only channel the daemon has to a window it
        // can reply to but never call.
        let others: Vec<String> = open_windows
            .iter()
            .map(|(k, _)| k.clone())
            .filter(|k| req.requester_key.as_deref() != Some(k))
            .collect();
        // A self-close is the requester closing a window it owns: it never rides
        // the cross-window signal (it acts on our `ok:true` reply instead). Logged
        // (#1364) so the execute's routing decision is auditable before the wait,
        // even if that wait then hangs or times out.
        let self_close = is_self_close(req.requester_key.as_deref(), &open_windows);
        log_executing(
            &req.path,
            req.requester_key.as_deref(),
            req.remove,
            self_close,
            others.len(),
        );
        for key in &others {
            self.registry.mark_close_pending(key);
        }
        if !others.is_empty() {
            if let Err(err) = await_windows_closed(
                &self.registry,
                &req.path,
                req.requester_key.as_deref(),
                CLOSE_WAIT_TIMEOUT,
                CLOSE_WAIT_POLL,
            )
            .await
            {
                log_close_abort(&req.path, &err);
                return Err(err);
            }
        }

        if req.remove {
            let path = req.path.clone();
            // The live window set, so a working-tree-gone-but-admin-present orphan
            // can find its owning main repo to prune (#1403); unused on the common
            // path where the checkout still exists.
            let entries = self.registry.list();
            // Taken *after* the wait above, so concurrent executes still overlap
            // their heartbeat waits (#1359) and only the prune itself serializes.
            // Load-bearing placement, not incidental: hoisting this above
            // `await_windows_closed` would restack the waits and undo the whole
            // point. Pinned by `concurrent_closes_overlap_their_heartbeat_waits`.
            let _guard = self.prune_lock.lock().await;
            let removed = tokio::task::spawn_blocking(move || remove_worktree(&path, &entries))
                .await
                .map_err(|e| anyhow!("worktree removal task panicked: {e}"))
                .map_err(|err| log_close_error(&req.path, "removal task", err))?;
            // The audit line + Result→reply mapping lives in a sync helper so the
            // destructive outcome is unit-testable off the runtime (#1364).
            log_and_map_removal(&req.path, removed)
        } else {
            // "Close Window" with no owning window is a no-op success; a
            // self-close replies and the extension closes its own window.
            log_window_closed(&req.path);
            Ok(json!({ "closed": true }))
        }
    }

    /// Handles the `reload` op (#1417): signal each target window to reload
    /// itself, returning `{ requested, signalled, unknown }`.
    ///
    /// Synchronous, and deliberately so — the whole op is a set insert per key.
    /// It marks a directive on each *currently registered* target and returns;
    /// the window acts on it on its next `heartbeat`, up to the ~10s cadence
    /// later. Unlike [`close`](Self::close) it never waits, because a reload has
    /// no completion the daemon can observe (the window re-registers under the
    /// same key), which is why the reply says `signalled`, never `reloaded`.
    ///
    /// A key with no live window is reported in `unknown` rather than erroring:
    /// the batch is a sweep, and a window closing between the client rendering
    /// its list and sending the op is routine, not a failure. `list()` reaps
    /// stale entries on read, so a window that died without unregistering is
    /// correctly unknown here.
    fn reload(&self, req: ReloadRequest) -> Value {
        let live: HashSet<String> = self
            .registry
            .list()
            .into_iter()
            .map(|entry| entry.key)
            .collect();

        let mut seen = HashSet::new();
        let mut signalled = 0usize;
        let mut unknown = Vec::new();
        for key in &req.target_keys {
            // A client repeating a key asks for one reload, not two.
            if !seen.insert(key.as_str()) {
                continue;
            }
            if live.contains(key) {
                self.registry.mark_reload_pending(key);
                signalled += 1;
            } else {
                unknown.push(key.clone());
            }
        }

        log_reload(seen.len(), signalled, &unknown);
        json!({
            "requested": seen.len(),
            "signalled": signalled,
            "unknown": unknown,
        })
    }

    /// Handles the `merge-queue` op (#1401): batch-enqueue the eligible worktrees'
    /// PRs into the GitHub merge queue. Two-phase, keyed off `confirmed`:
    ///
    /// - **Phase 1** (`check:true`, or any un-`confirmed` request) — run the
    ///   side-effect-free eligibility evaluation ([`evaluate_batch`]) and return an
    ///   [`EligibilityReport`]: the enqueue-eligible worktrees and the skipped ones
    ///   (each with a machine `kind` + human `detail`).
    /// - **Phase 2** (`confirmed:true`) — **re-run** the same evaluation (never
    ///   trust a phase-1 result the client sent, exactly as `close` re-validates on
    ///   execute), then enqueue each still-eligible PR. A per-PR rejection lands in
    ///   `failed[]`; the batch never fails as a whole.
    ///
    /// All git and `gh` I/O runs on a blocking thread — never the async worker and
    /// never under the registry lock. No lock is taken: each enqueue mutates a
    /// distinct remote PR, not a shared local resource.
    async fn merge_queue(&self, req: MergeQueueRequest) -> Result<Value> {
        // Resolved once here (the env read is process-stable), then handed to the
        // seam below — the `open_prs`/`open_prs_with` "bin as a param" pattern, so a
        // test drives the eligibility + enqueue paths against a fake `gh` without
        // touching the environment (#1030).
        self.merge_queue_with(req, crate::pr_status::resolve_gh_binary())
            .await
    }

    /// [`merge_queue`](Self::merge_queue) with an explicit `gh` binary, so a test
    /// exercises the phase-1 network resolve and the phase-2 enqueue against a stub.
    async fn merge_queue_with(&self, req: MergeQueueRequest, bin: PathBuf) -> Result<Value> {
        // Report-only unless explicitly confirmed; an explicit `check` request
        // always reports and never enqueues.
        let report_only = req.check || !req.confirmed;

        let eval_bin = bin.clone();
        let eval_paths = req.paths.clone();
        let (eligible, skipped) =
            tokio::task::spawn_blocking(move || evaluate_batch(&eval_bin, &eval_paths))
                .await
                .map_err(|e| anyhow!("merge-queue eligibility task panicked: {e}"))
                .and_then(|inner| inner)?;

        if report_only {
            // Auditable in `omni-dev daemon logs` (ADR-0049 §6 precedent).
            log_merge_check(&req, eligible.len(), skipped.len());
            let eligible: Vec<PrRef> = eligible.iter().map(PrRef::from).collect();
            return Ok(
                serde_json::to_value(EligibilityReport { eligible, skipped })
                    .unwrap_or_else(|_| json!({})),
            );
        }

        // Phase 2: enqueue the freshly re-validated eligible set, sequentially.
        let enqueue_bin = bin.clone();
        let (queued, failed) =
            tokio::task::spawn_blocking(move || enqueue_eligible(&enqueue_bin, eligible))
                .await
                .map_err(|e| anyhow!("merge-queue enqueue task panicked: {e}"))?;
        log_merge_enqueue(&req, queued.len(), failed.len(), skipped.len());
        Ok(serde_json::to_value(EnqueueResult {
            queued,
            skipped,
            failed,
        })
        .unwrap_or_else(|_| json!({})))
    }

    /// Handles the `rebase` op (#1415): batch-rebase the selected worktrees onto
    /// their repository's remote default branch, fetching it **once per
    /// repository**. Two-phase, keyed off `confirmed`, exactly like `merge-queue`:
    ///
    /// - **Phase 1** (`check:true`, or any un-`confirmed` request) — run
    ///   [`worktree_rebase::plan`], which fetches once per repo and classifies
    ///   every selected worktree. This *is* the "only rebase if it makes sense
    ///   from the current git state" gate: the classifier skips a detached HEAD, a
    ///   dirty tree, an operation already in progress, a non-worktree path, an
    ///   unresolvable onto ref, and anything already up to date — the main working
    ///   tree is a valid target like any other (ADR-0060). Side-effect-free apart
    ///   from the fetch, which only advances a remote-tracking ref.
    /// - **Phase 2** (`confirmed:true`) — **re-plan from scratch** (never trust a
    ///   phase-1 result the client sent back, as `close` and `merge-queue` do),
    ///   then execute. A worktree that went dirty between the phases is skipped
    ///   rather than rebased.
    ///
    /// **Why the daemon may do this at all** (ADR-0059): ADR-0055 confined the
    /// rebase to the CLI on the premise that the daemon could not authenticate a
    /// fetch. It can — launchd exports `SSH_AUTH_SOCK` into the per-user session,
    /// so the daemon inherits the user's `ssh-agent`. The real gap was the minimal
    /// `PATH`, closed by [`crate::git::resolve_git_binary`].
    ///
    /// All git I/O runs on a blocking thread, never the async worker and never
    /// under the registry lock.
    async fn rebase(&self, req: RebaseRequest) -> Result<Value> {
        // Resolved once here (the probe is process-stable), then handed to the
        // seam below — the `merge_queue_with` "bin as a param" pattern, so a test
        // drives both phases against a stub without touching the environment.
        self.rebase_with(req, crate::git::resolve_git_binary())
            .await
    }

    /// [`rebase`](Self::rebase) with an explicit `git` binary, so a test exercises
    /// the plan and execute paths against a stub.
    async fn rebase_with(&self, req: RebaseRequest, git_bin: PathBuf) -> Result<Value> {
        if req.paths.is_empty() {
            bail!("`rebase` requires at least one path");
        }
        // Report-only unless explicitly confirmed; an explicit `check` request
        // always reports and never rebases.
        let report_only = req.check || !req.confirmed;
        let opts = req.options(git_bin);
        let selection = Selection::Paths(req.paths.clone());

        if report_only {
            // Phase 1: fetch once per repo and classify, rebase nothing. No lock —
            // it mutates no worktree, and a plan is allowed to race an execute.
            let plan = plan_rebase(&selection, &opts).await?;
            // Auditable in `omni-dev daemon logs` (ADR-0049 §6 precedent).
            log_rebase_check(&req, &plan);
            return Ok(rebase_reply(&plan.fetches, &plan.worktrees));
        }

        // Phase 2: re-plan and execute, serialized against other executes —
        // linked worktrees share one object database (see `rebase_lock`).
        //
        // The lock is taken **before** the re-plan, not merely around the execute,
        // and that ordering is load-bearing. A plan taken outside it can be
        // invalidated by a concurrent execute before this one gets its turn — and
        // acting on a stale plan is not benign: if the other run left a worktree
        // mid-rebase, a stale `WouldRebase` here would run `git rebase` against a
        // repository that is already mid-rebase and (without `keep_conflicts`)
        // `--abort` it, destroying exactly the conflict resolution the other run
        // was preserving. Planning under the lock means the classifier sees that
        // worktree's real state and skips it as `operation-in-progress`.
        let _guard = self.rebase_lock.lock().await;
        let plan = plan_rebase(&selection, &opts).await?;
        // The worktrees actually about to be rewritten, canonicalized here (disk
        // I/O belongs in the adapter, not the registry) so they match the tree
        // snapshot's own keys.
        let pending: Vec<PathBuf> = plan
            .worktrees
            .iter()
            .filter(|w| matches!(w.result, worktree_rebase::RebaseResult::WouldRebase { .. }))
            .map(|w| canonical(&w.path))
            .collect();
        self.registry.mark_rebasing(&pending);
        let fetches = plan.fetches.clone();
        let exec_opts = opts.clone();
        let outcomes =
            tokio::task::spawn_blocking(move || worktree_rebase::execute(plan, &exec_opts)).await;
        // Cleared on **every** exit, including a panicked task, so a failed rebase
        // can never leave a permanent spinner on a tree row.
        self.registry.clear_rebasing(&pending);
        let outcomes = outcomes.map_err(|e| anyhow!("rebase task panicked: {e}"))?;

        log_rebase_execute(&req, &outcomes);
        Ok(rebase_reply(&fetches, &outcomes))
    }

    /// Handles the `push` op (#1443): publish the selected worktrees' branches to
    /// their upstreams, force-pushing **with a lease** where a rebase rewrote
    /// history. The complement of [`rebase`](Self::rebase), and two-phase in
    /// exactly the same way:
    ///
    /// - **Phase 1** (`check:true`, or any un-`confirmed` request) — run
    ///   [`worktree_push::plan`], which classifies every selected worktree against
    ///   its upstream. This *is* the "does this make sense?" gate: it skips a
    ///   detached HEAD (which also covers a worktree mid-rebase), a non-worktree
    ///   path, a branch with nowhere to publish, and a force-push of the
    ///   repository's remote default branch — while a dirty tree is deliberately
    ///   **not** a skip, since a push publishes commits rather than the working
    ///   tree. Unlike `rebase`'s phase 1 this is not merely side-effect-*light*: it
    ///   contacts no remote at all (ADR-0061).
    /// - **Phase 2** (`confirmed:true`) — **re-plan from scratch**, then execute. A
    ///   phase-1 result the client sends back is never trusted, as `close`,
    ///   `merge-queue` and `rebase` all re-validate. A branch that moved between
    ///   the phases is re-classified, not pushed on stale information.
    ///
    /// **Why the daemon may do this at all** (ADR-0061): this is the first op to
    /// write to a remote using the user's ambient *git* credentials — `merge-queue`
    /// mutates the remote through `gh` (ADR-0056) and `rebase` only fetches
    /// (ADR-0059). It stays same-user-bounded behind the `0600` socket, publishes
    /// only branches the client names, and can never overwrite work it has not
    /// seen, because the lease is enforced by `git` itself.
    ///
    /// All git I/O runs on a blocking thread, never the async worker and never
    /// under the registry lock.
    async fn push(&self, req: PushRequest) -> Result<Value> {
        // Resolved once here (the probe is process-stable), then handed to the
        // seam below — the `rebase_with` "bin as a param" pattern.
        self.push_with(req, crate::git::resolve_git_binary()).await
    }

    /// [`push`](Self::push) with an explicit `git` binary, so a test exercises the
    /// plan and execute paths against a stub.
    async fn push_with(&self, req: PushRequest, git_bin: PathBuf) -> Result<Value> {
        if req.paths.is_empty() {
            bail!("`push` requires at least one path");
        }
        // Report-only unless explicitly confirmed; an explicit `check` request
        // always reports and never pushes.
        let report_only = req.check || !req.confirmed;
        let selection = Selection::Paths(req.paths.clone());

        if report_only {
            // Phase 1: classify only. No lock and no network — planning reads the
            // local remote-tracking refs, which is exactly what the lease is
            // checked against.
            let plan = plan_push(&selection).await?;
            // Auditable in `omni-dev daemon logs` (ADR-0049 §6 precedent).
            log_push_check(&req, &plan);
            return Ok(push_reply(&plan.worktrees));
        }

        // Phase 2: re-plan and execute, serialized against other executes — a push
        // writes into the ref store linked worktrees share (see `push_lock`). The
        // lock is taken **before** the re-plan for the same reason `rebase` takes
        // its own that way: a plan plus a lease are only meaningful together, and a
        // plan taken outside the lock can be invalidated before its turn comes.
        let _guard = self.push_lock.lock().await;
        let plan = plan_push(&selection).await?;
        // The worktrees actually about to be published, canonicalized here (disk
        // I/O belongs in the adapter, not the registry) so they match the tree
        // snapshot's own keys.
        let pending: Vec<PathBuf> = plan
            .worktrees
            .iter()
            .filter(|w| w.result.is_pending())
            .map(|w| canonical(&w.path))
            .collect();
        self.registry.mark_pushing(&pending);
        let opts = worktree_push::PushOptions {
            git_bin: Some(git_bin),
        };
        let outcomes =
            tokio::task::spawn_blocking(move || worktree_push::execute(plan, &opts)).await;
        // Cleared on **every** exit, including a panicked task. A push writes no
        // on-disk state, so this set is the *whole* cue — a mark left behind would
        // be a permanent spinner nothing else could correct.
        self.registry.clear_pushing(&pending);
        let outcomes = outcomes.map_err(|e| anyhow!("push task panicked: {e}"))?;

        log_push_execute(&req, &outcomes);
        Ok(push_reply(&outcomes))
    }

    /// Handles the `reposition` op (#1407): move and resize each target worktree's
    /// **already-open** VS Code window to match the invoking window's geometry.
    ///
    /// The invoking window is the reference: it supplies the frame and is never
    /// itself moved. A target with no open window, no resolvable OS window, or an
    /// ambiguous name is reported rather than guessed at. Z-order is untouched —
    /// see [`geometry::ax`] for why the Accessibility API gives that for free, and
    /// why this must **not** reuse [`focus_window`], which deliberately raises.
    ///
    /// `check: true` is a dry run: everything resolves exactly as it would for a
    /// real run, but nothing is written. That is the whole diagnostic surface for
    /// title matching (`worktrees reposition --dry-run`).
    ///
    /// Not two-phase like `close`/`merge-queue`: nothing durable is created,
    /// modified, or destroyed, so a confirmation on a routine layout command would
    /// cost more than it protects. Reversibility is provided instead, by
    /// [`reposition_undo`](Self::reposition_undo).
    async fn reposition(&self, req: RepositionRequest) -> Result<Value> {
        self.reposition_with(req, geometry::ax::AxBackend::new)
            .await
    }

    /// [`reposition`](Self::reposition) with the platform backend injected as a
    /// **factory**, so a test drives the whole op — key resolution, the undo
    /// store, the reply shape — against a fake with no `unsafe` and no windows.
    ///
    /// A factory rather than the backend itself because the real backend holds
    /// CoreFoundation references and so is neither `Send` nor `Sync`: it has to be
    /// built *inside* the blocking closure. The `merge_queue_with` "seam as a
    /// parameter" pattern, one level of indirection over.
    async fn reposition_with<B, F>(&self, req: RepositionRequest, make_backend: F) -> Result<Value>
    where
        B: geometry::WindowBackend,
        F: FnOnce() -> B + Send + 'static,
    {
        if req.reference_key.trim().is_empty() {
            bail!("`reposition` requires a non-empty `reference_key`");
        }
        // Resolve keys against the registry *here*, so all AX work below deals in
        // plain data and the registry lock is never held across the blocking join.
        let entries = self.registry.list();
        let reference = registered_window(&entries, &req.reference_key);
        if !reference.live {
            // Unlike a target, an unresolvable *reference* is a hard error: there
            // is no geometry to copy, so the request cannot mean anything.
            bail!(
                "no open window with key {} (it may have closed)",
                req.reference_key
            );
        }
        // A target key with no live window is a reportable per-target outcome, not
        // a failure of the batch — the tree row may simply be a tick stale.
        let targets: Vec<geometry::RegisteredWindow> = req
            .target_keys
            .iter()
            .map(|key| registered_window(&entries, key))
            .collect();

        let check = req.check;
        let mut report = tokio::task::spawn_blocking(move || {
            // The backend lives for exactly one op, so its enumeration cache can
            // never serve a window that has since moved or closed.
            let backend = make_backend();
            geometry::reposition(&backend, &reference, &targets, check)
        })
        .await
        .map_err(|e| anyhow!("reposition task panicked: {e}"))?;

        // Taken out of the report rather than cloned: nothing downstream reads it,
        // and the store is its only owner. A dry run leaves the previous batch's
        // record intact — it changed nothing, so there is neither something new to
        // undo nor something stale to discard.
        let undo = std::mem::take(&mut report.undo);
        let undoable = !check && !undo.is_empty();
        if undoable {
            *self
                .reposition_undo
                .lock()
                .unwrap_or_else(PoisonError::into_inner) = undo;
        }
        log_reposition(&req, &report);
        Ok(reposition_reply(&report, undoable))
    }

    /// Handles the `reposition-undo` op (#1407): put the windows the last
    /// `reposition` moved back where they were.
    ///
    /// Consumes the stored batch, so an undo cannot be replayed onto windows the
    /// user has since arranged by hand. Every window is re-resolved from scratch —
    /// one that has closed, been renamed, or gone fullscreen in the meantime is
    /// reported, not forced.
    async fn reposition_undo(&self) -> Result<Value> {
        self.reposition_undo_with(geometry::ax::AxBackend::new)
            .await
    }

    /// [`reposition_undo`](Self::reposition_undo) with the backend factory
    /// injected, for the same reasons as
    /// [`reposition_with`](Self::reposition_with).
    async fn reposition_undo_with<B, F>(&self, make_backend: F) -> Result<Value>
    where
        B: geometry::WindowBackend,
        F: FnOnce() -> B + Send + 'static,
    {
        let stored = std::mem::take(
            &mut *self
                .reposition_undo
                .lock()
                .unwrap_or_else(PoisonError::into_inner),
        );
        if stored.is_empty() {
            return Ok(json!({ "trusted": true, "results": [], "moved": 0, "skipped": 0 }));
        }
        let entries = self.registry.list();
        let restore: Vec<(geometry::RegisteredWindow, geometry::Frame)> = stored
            .into_iter()
            .map(|(key, frame)| (registered_window(&entries, &key), frame))
            .collect();

        let report = tokio::task::spawn_blocking(move || {
            let backend = make_backend();
            geometry::restore(&backend, &restore)
        })
        .await
        .map_err(|e| anyhow!("reposition-undo task panicked: {e}"))?;
        log_reposition_undo(&report);
        Ok(reposition_reply(&report, false))
    }
}

impl Default for WorktreesService {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl DaemonService for WorktreesService {
    fn name(&self) -> &'static str {
        SERVICE_NAME
    }

    async fn handle(&self, op: &str, payload: Value) -> Result<Value> {
        match op {
            "register" => {
                let req: RegisterRequest =
                    serde_json::from_value(payload).context("invalid `register` payload")?;
                if req.key.trim().is_empty() {
                    bail!("`register` requires a non-empty `key`");
                }
                self.registry.register(req);
                Ok(json!({ "ok": true }))
            }
            "heartbeat" => {
                let key = require_str(&payload, "key", "heartbeat")?;
                let known = self.registry.heartbeat(key);
                // A pending close directive (#1277) rides the reply as an
                // additive `close` field, taken-and-cleared here so it fires
                // exactly once. Omitted when false to keep older windows — which
                // read only `known` — byte-identical on the wire.
                let mut reply = json!({ "known": known });
                if self.registry.take_close_pending(key) {
                    reply["close"] = Value::Bool(true);
                }
                // A pending reload directive (#1417) rides the same reply, on
                // the same terms. Deliberately an independent `if`, not an
                // `else`: each field then means exactly "this directive was
                // pending", and each is taken exactly once regardless of the
                // other. The companion resolves a both-set collision by
                // checking `close` first, since closing subsumes reloading.
                if self.registry.take_reload_pending(key) {
                    reply["reload"] = Value::Bool(true);
                }
                Ok(reply)
            }
            "unregister" => {
                let key = require_str(&payload, "key", "unregister")?;
                Ok(json!({ "removed": self.registry.unregister(key) }))
            }
            "list" => Ok(json!({ "windows": enriched_windows(self.registry.list()).await })),
            "tree" => {
                // The same `{ repos, show_closed }` snapshot the `subscribe`
                // stream pushes, so a one-shot `tree` fetch and the live stream
                // agree byte-for-byte (the git enumeration runs off-lock on a
                // blocking thread inside the helper). Computed fresh here — the
                // `tree` op is a rare manual refresh, deliberately bypassing the
                // stream's coalescing cache so it never returns a stale view
                // (#1303).
                Ok(tree_snapshot(&self.registry, self.pr_cache.clone()).await)
            }
            "ahead-behind" => {
                // Lazy per-worktree divergence (#1306). The `tree`/`subscribe`
                // snapshot no longer carries ahead/behind — the dominant
                // per-worktree cost when computed eagerly every tick — so a client
                // (the extension on expand, `worktrees tree`) asks for it here only
                // for the worktrees it is about to show. Batched by path, one op per
                // repo expand; the git walks run on a blocking thread.
                let paths = payload
                    .get("paths")
                    .and_then(Value::as_array)
                    .map(|arr| {
                        arr.iter()
                            .filter_map(Value::as_str)
                            .map(PathBuf::from)
                            .collect::<Vec<_>>()
                    })
                    .unwrap_or_default();
                Ok(json!({ "results": ahead_behind_results(&self.ahead_behind, paths).await }))
            }
            "set-show-closed" => {
                // The daemon-backed show/hide-closed toggle (#1301). Setting it
                // bumps the change-notify, so every subscribed window re-pushes a
                // snapshot carrying the new `show_closed` — reliable cross-window
                // sync `context.globalState` could not do.
                let show_closed = payload
                    .get("show_closed")
                    .and_then(Value::as_bool)
                    .ok_or_else(|| anyhow!("`set-show-closed` requires a boolean `show_closed`"))?;
                self.registry.set_show_closed(show_closed);
                Ok(json!({ "ok": true }))
            }
            "set-polling" => {
                // Per-repo PR-poll toggle (#1376). Enabling a repo starts the
                // poller resolving its badges (default is off — zero `gh`);
                // disabling stops it and drops its badges. `set_polling` bumps the
                // change-notify on a real change, so every subscribed window
                // re-pushes a `tree` snapshot carrying the new per-repo
                // `polling_enabled` — the reliable cross-window sync the
                // `set-show-closed` precedent relies on. A changed value is
                // persisted so it survives a daemon restart.
                let owner = require_str(&payload, "owner", "set-polling")?;
                let name = require_str(&payload, "name", "set-polling")?;
                let enabled = payload
                    .get("enabled")
                    .and_then(Value::as_bool)
                    .ok_or_else(|| anyhow!("`set-polling` requires a boolean `enabled`"))?;
                if owner.trim().is_empty() || name.trim().is_empty() {
                    bail!("`set-polling` requires a non-empty `owner` and `name`");
                }
                if self.registry.set_polling(owner, name, enabled) {
                    self.persist_polling_prefs();
                }
                Ok(json!({ "ok": true }))
            }
            "open-prs" => {
                // Serve "Open Pull Request…" (and the extension's transient badge
                // fallback) from the daemon (#1389, fix 7): one shared, TTL-cached,
                // #1387-counted `gh pr list` per repo, so N windows dedupe to one
                // call instead of each shelling its own (the per-window burn
                // #1370/#1389 target). Repo-wide; the client filters by branch for a
                // worktree-scoped lookup, and answers a badged branch straight from
                // the snapshot (zero `gh`) without ever reaching here.
                let owner = require_str(&payload, "owner", "open-prs")?;
                let name = require_str(&payload, "name", "open-prs")?;
                if owner.trim().is_empty() || name.trim().is_empty() {
                    bail!("`open-prs` requires a non-empty `owner` and `name`");
                }
                Ok(json!({ "pull_requests": self.open_prs(owner, name).await? }))
            }
            "open" => {
                // Focus (or open — VS Code reuses an already-open window) an
                // arbitrary worktree folder supplied by a socket client, reusing
                // the tray's launcher path: `focus_window` resolves the launcher
                // (`OMNI_DEV_VSCODE_BIN` → well-known paths → `code`) and applies
                // the absolute-existing-directory guard (which also blocks a
                // `-`-leading path being parsed by `code` as a flag). This is the
                // one op a socket *writer* can use to spawn `code`; see the
                // ADR-0040 threat model (#1266).
                let path = require_str(&payload, "path", "open")?;
                focus_window(Path::new(path))?;
                Ok(json!({ "ok": true }))
            }
            "close" => {
                // Close a worktree's window and (for a linked worktree)
                // **delete** it. Destructive, so all git logic stays in the
                // daemon (git2, never a shell) and the main working tree is
                // refused defensively — the UI gating is not the only guard.
                // See ADR-0049 and docs/worktrees-service.md.
                let req: CloseRequest =
                    serde_json::from_value(payload).context("invalid `close` payload")?;
                self.close(req).await
            }
            "reload" => {
                // Signal each target window to reload itself (#1417). Addressed
                // by window key like `reposition`, not by path like `close`: a
                // reload acts on a *window*, and one tree row is one window,
                // whereas a path can be open in several. Nothing here is
                // destructive and nothing waits — the directive is marked and
                // the reply says only what was *signalled*. See
                // docs/worktrees-service.md.
                let req: ReloadRequest =
                    serde_json::from_value(payload).context("invalid `reload` payload")?;
                Ok(self.reload(req))
            }
            "merge-queue" => {
                // Batch-enqueue eligible worktrees' PRs into the GitHub merge
                // queue (#1401). Two-phase like `close` (side-effect-free
                // eligibility check → confirmed enqueue) and daemon-re-validated,
                // but a single batched op over `paths`. All git/`gh` work runs on
                // a blocking thread; enqueue authenticates through the user's own
                // `gh`. See ADR-0056 and docs/worktrees-service.md.
                let req: MergeQueueRequest =
                    serde_json::from_value(payload).context("invalid `merge-queue` payload")?;
                self.merge_queue(req).await
            }
            "rebase" => {
                // Batch-rebase the selected worktrees onto their repo's remote
                // default branch, fetching once per repo (#1415). Two-phase like
                // `close`/`merge-queue` (side-effect-free plan → confirmed
                // execute) and daemon-re-validated. The fetch authenticates
                // through the user's own `ssh-agent`, which launchd exports into
                // the daemon's environment — the premise ADR-0055 got wrong. All
                // git work runs on a blocking thread. See ADR-0059, ADR-0055 and
                // docs/worktrees-service.md.
                let req: RebaseRequest =
                    serde_json::from_value(payload).context("invalid `rebase` payload")?;
                self.rebase(req).await
            }
            "push" => {
                // Publish the selected worktrees' branches to their upstreams,
                // force-pushing **with a lease** where a rebase rewrote history
                // (#1443). Two-phase like `rebase` (side-effect-free plan →
                // confirmed execute) and daemon-re-validated, but its plan phase
                // contacts no remote at all. The push authenticates through the
                // user's own ambient git credentials — the first op to *write* to
                // a remote that way. There is no force escape hatch and no remote
                // override: a refused lease is the feature working. See ADR-0061
                // and docs/worktrees-service.md.
                let req: PushRequest =
                    serde_json::from_value(payload).context("invalid `push` payload")?;
                self.push(req).await
            }
            "reposition" => {
                // Move each target's already-open VS Code window onto the invoking
                // window's geometry (#1407). The one op that reaches outside the
                // process to control another application's windows, so all of its
                // OS interaction is confined to the `geometry::ax` module behind
                // the macOS Accessibility permission — geometry only, never a
                // raise, so Z-order is untouched. All AX I/O runs on a blocking
                // thread. See ADR-0058 and docs/worktrees-service.md.
                let req: RepositionRequest =
                    serde_json::from_value(payload).context("invalid `reposition` payload")?;
                self.reposition(req).await
            }
            "reposition-undo" => {
                // Put the windows the last `reposition` moved back where they were
                // (#1407). Payload-free: the daemon holds the one-level undo
                // record, so the client cannot ask to restore arbitrary geometry.
                self.reposition_undo().await
            }
            other => bail!("unknown worktrees op: {other}"),
        }
    }

    fn subscribe(&self, op: &str, _payload: &Value) -> Option<Box<dyn ServiceStream>> {
        // The single streaming op: a live push of the repo/worktree `tree`
        // snapshot. Every other op falls through to the request→reply `handle`.
        if op != "subscribe" {
            return None;
        }
        Some(Box::new(WorktreesStream {
            // Every stream reads through the one shared cache, so N windows
            // sampling the same tick build the tree once, not N times (#1303).
            cache: self.tree_cache.clone(),
            // Capture the change source *now* — before the server takes its
            // initial snapshot — so a change racing that snapshot still wakes us.
            changes: self.registry.subscribe_changes(),
        }))
    }

    fn menu(&self) -> MenuSnapshot {
        // Serve the snapshot the background task maintains off the main thread;
        // fall back to a one-off inline compute only before the first refresh
        // lands (or with no runtime — the unit tests). Never blocks on git here
        // in the daemon, honouring the trait's "cheap, must not block" contract.
        let cached = self
            .menu_cache
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .clone();
        let items = cached.unwrap_or_else(|| {
            menu_items_for(&self.registry.list(), self.rate_limit_cache.get().as_ref())
        });
        MenuSnapshot {
            title: SUBMENU_TITLE.to_string(),
            items,
        }
    }

    async fn menu_action(&self, action_id: &str) -> Result<()> {
        if let Some(key) = action_id.strip_prefix("focus:") {
            // The registry resolves the folder under its own lock and clones it
            // out, so the mutex is never held across the process launch.
            let folder = self
                .registry
                .first_folder(key)
                .ok_or_else(|| anyhow!("no open window with key {key} (it may have closed)"))?;
            focus_window(&folder)?;
            return Ok(());
        }
        bail!("unknown worktrees menu action: {action_id}")
    }

    async fn status(&self) -> ServiceStatus {
        let entries = self.registry.list();
        let repos: BTreeSet<&str> = entries.iter().filter_map(|e| e.repo.as_deref()).collect();
        let summary = format!("{} window(s) across {} repo(s)", entries.len(), repos.len());
        let windows = enriched_windows(entries).await;
        ServiceStatus {
            name: SERVICE_NAME.to_string(),
            healthy: true,
            summary,
            detail: json!({ "windows": windows }),
        }
    }

    fn credit_accept_outage(&self, outage: Duration) {
        self.registry.credit_outage(outage);
    }

    async fn shutdown(&self) {
        // Stop the background menu-refresh task; the registry itself is in-memory
        // with nothing to drain or persist. Take the task out from under the lock
        // first so the `std::Mutex` is never held across the `.await`.
        let task = self
            .refresh
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .take();
        if let Some(task) = task {
            task.token.cancel();
            let _ = task.handle.await;
        }
        // Same discipline for the PR badge poller (#1337): take it out from under
        // its lock before awaiting, so no `std::Mutex` is held across the `.await`.
        let poller = self
            .poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .take();
        if let Some(poller) = poller {
            poller.token.cancel();
            let _ = poller.handle.await;
        }
        // And the GitHub rate-limit poller (#1375), same discipline.
        let rate_limit_poller = self
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .take();
        if let Some(poller) = rate_limit_poller {
            poller.token.cancel();
            let _ = poller.handle.await;
        }
    }
}

/// Extracts a required string `field` from an op payload, erroring with the op
/// name when it is absent or not a string. Shared by `heartbeat`/`unregister`
/// (`key`) and `open` (`path`).
fn require_str<'a>(payload: &'a Value, field: &str, op: &str) -> Result<&'a str> {
    payload
        .get(field)
        .and_then(Value::as_str)
        .ok_or_else(|| anyhow!("`{op}` requires `{field}`"))
}

/// The live git state of a worktree folder: the checked-out branch and how far
/// it has diverged from its upstream. Computed on read from the on-disk repo
/// (#1186), so `list`/`status`/`menu` reflect the current branch rather than a
/// snapshot taken at registration.
///
/// Every field is optional and degrades independently: a folder that is not a
/// git repo, is on a detached HEAD, or whose branch tracks no upstream is still
/// listed — just without the fields it cannot supply. The `skip_serializing_if`
/// attributes let it flatten cleanly onto an entry (see [`EnrichedEntry`]),
/// omitting each absent field on the wire.
#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize)]
struct GitStatus {
    /// The checked-out branch, or `None` when detached or not in a repo.
    #[serde(skip_serializing_if = "Option::is_none")]
    branch: Option<String>,
    /// The commit HEAD points at, or `None` when unborn or not in a repo. Present
    /// even on a detached HEAD, which has a commit but no branch. Rides the
    /// streamed snapshot so a new commit is a real delta the server's diff cannot
    /// drop — without it, a push serialises byte-identically and no client
    /// re-renders (#1337).
    #[serde(skip_serializing_if = "Option::is_none")]
    head_sha: Option<String>,
    /// The commit the branch's configured upstream ref points at, or `None`
    /// without an upstream (or when detached, unborn, or not in a repo). Rides
    /// the streamed snapshot for the same reason as `head_sha`, one ref over: a
    /// **push** moves only `refs/remotes/<remote>/<branch>`, leaving every other
    /// field — `head_sha` included — byte-identical, so without this the frame
    /// serialised the same, the server's diff dropped it, and the lazily-fetched
    /// ahead/behind was never re-asked (#1344).
    #[serde(skip_serializing_if = "Option::is_none")]
    upstream_sha: Option<String>,
    /// Commits the branch is ahead of its upstream (`None` without an upstream).
    #[serde(skip_serializing_if = "Option::is_none")]
    ahead: Option<usize>,
    /// Commits the branch is behind its upstream (`None` without an upstream).
    #[serde(skip_serializing_if = "Option::is_none")]
    behind: Option<usize>,
    /// The main repository's directory name — the parent repo for a linked
    /// worktree, the checkout's own directory otherwise. Derived from git's
    /// common dir so a worktree names the repo it belongs to rather than its
    /// worktree-folder basename. `None` when not in a repo.
    #[serde(skip_serializing_if = "Option::is_none")]
    main_repo: Option<String>,
    /// Whether the enriched folder is a **linked** git worktree rather than the
    /// repository's main working tree. Omitted (false) for a normal checkout.
    #[serde(skip_serializing_if = "is_false")]
    is_worktree: bool,
    /// The multi-step git operation the worktree is in the middle of (#1415):
    /// `rebase`, `rebase-interactive`, `merge`, `cherry-pick`, `revert`, `bisect`
    /// or `apply-mailbox`. `None` for a clean worktree (the overwhelming case), so
    /// the field is omitted on the wire and an older client is byte-identical.
    ///
    /// This is the **durable** half of the tree's rebase cue: read fresh off disk
    /// on every snapshot, it survives a daemon restart and keeps showing a
    /// conflict the `rebase` op left in place until the user resolves it. The
    /// transient half — "the daemon is rebasing this right now" — comes from the
    /// registry's in-memory set instead (see [`TreeWorktree::rebasing`]).
    ///
    /// Cheap enough for the every-worktree-every-tick snapshot (#1306's bar):
    /// `Repository::state()` stats a handful of paths under `.git`, which is
    /// nothing beside the `Repository::discover` this function already does — and
    /// unlike `graph_ahead_behind` it is neither a revwalk nor an object lookup.
    #[serde(skip_serializing_if = "Option::is_none")]
    operation: Option<String>,
}

/// `skip_serializing_if` predicate for a `bool` defaulting to `false`, so the
/// field is dropped on the wire unless set — keeping older clients byte-identical
/// (the protocol's forward-compatibility convention).
#[allow(clippy::trivially_copy_pass_by_ref)]
fn is_false(b: &bool) -> bool {
    !*b
}

/// One persisted PR-poll lease: the GitHub repo (`"owner/name"`) and when its
/// lease expires (#1376). Storing the expiry — not just the repo — is what lets a
/// daemon restart within the lease window keep the *remaining* time rather than
/// resetting the 15-minute clock; an already-expired entry is dropped on load.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PollingLease {
    repo: String,
    expires_at: DateTime<Utc>,
}

/// The on-disk shape of the per-repo PR-poll prefs (#1376): the live leases whose
/// PR badges the daemon polls. Only **enabled** (leased) repos are stored —
/// absence means not-polled (the default-off model) — so the file stays small (a
/// handful of active repos out of many open). `#[serde(default)]` so an
/// empty/older file decodes to "nothing enabled".
#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PollingPrefs {
    #[serde(default)]
    enabled: Vec<PollingLease>,
}

/// Writes `prefs` to `path` as pretty JSON with `0600` perms, creating the
/// parent runtime dir (`0700`) if needed — the bridge-token persistence pattern
/// (`BridgeService`), reusing the same [`crate::daemon::paths`] helpers.
fn write_polling_prefs(path: &Path, prefs: &PollingPrefs) -> Result<()> {
    if let Some(parent) = path.parent() {
        crate::daemon::paths::ensure_dir_0700(parent)?;
    }
    let json = serde_json::to_vec_pretty(prefs).context("failed to serialize polling prefs")?;
    crate::daemon::paths::write_file_0600(path, &json)
}

// --- PR-badge cache persistence (#1389, fix 4) -----------------------------

/// A persisted badge — the disk twin of [`PrBadge`](crate::pr_status::PrBadge).
///
/// A distinct DTO rather than reusing `PrBadge`'s derive because the two shapes
/// disagree: `PrBadge` renders onto the **tree wire**, where `head_oid` is
/// `#[serde(skip)]` (it is a local staleness key, never sent) and `is_draft` is
/// `isDraft`. The cache file must round-trip `head_oid` — a restored verdict is
/// compared against the worktree's current HEAD via
/// [`PrBadge::is_stale_for`](crate::pr_status::PrBadge::is_stale_for), and a lost
/// `head_oid` would render every restored badge stale — so it carries the field
/// explicitly under a stable snake_case name.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PersistedBadge {
    number: u64,
    is_draft: bool,
    checks: PrCheckState,
    url: String,
    head_oid: String,
}

/// A persisted resolution — the disk twin of
/// [`PrResolution`](crate::pr_status::PrResolution). Externally tagged so the
/// no-PR negative (#1370) round-trips as a plain `"NoPr"` and a badge as
/// `{ "Pr": { … } }`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
enum PersistedResolution {
    Pr(PersistedBadge),
    NoPr,
}

/// One persisted cache entry: which target, and the verdict last resolved for it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PersistedEntry {
    target: PrTarget,
    resolution: PersistedResolution,
}

/// A persisted watch — the `(target, upstream_sha)` the poller compared at the
/// last fetch. Lets a warm start tell "same set, verdicts still fresh → skip the
/// immediate re-poll" from "a target was added or a branch pushed while we were
/// down → fetch" (the [`pr_watch_grew`] comparison, restored across a restart).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PersistedWatch {
    target: PrTarget,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    upstream_sha: Option<String>,
}

/// The on-disk shape of the resolved PR-badge cache (#1389, fix 4): the badges,
/// the watch set they were resolved for, and when. `#[serde(default)]` throughout
/// so an empty/older/partial file decodes to "nothing restored" rather than
/// failing the load — best-effort, exactly like [`PollingPrefs`].
#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct PrCachePrefs {
    #[serde(default)]
    entries: Vec<PersistedEntry>,
    #[serde(default)]
    watched: Vec<PersistedWatch>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    polled_at: Option<DateTime<Utc>>,
}

impl PersistedResolution {
    /// The disk form of a live resolution.
    fn from_resolution(r: &PrResolution) -> Self {
        match r {
            PrResolution::Pr(b) => Self::Pr(PersistedBadge {
                number: b.number,
                is_draft: b.is_draft,
                checks: b.checks,
                url: b.url.clone(),
                head_oid: b.head_oid.clone(),
            }),
            PrResolution::NoPr => Self::NoPr,
        }
    }

    /// The live form of a restored resolution.
    fn into_resolution(self) -> PrResolution {
        match self {
            Self::Pr(b) => PrResolution::Pr(PrBadge {
                number: b.number,
                is_draft: b.is_draft,
                checks: b.checks,
                url: b.url,
                head_oid: b.head_oid,
            }),
            Self::NoPr => PrResolution::NoPr,
        }
    }
}

/// Assembles the on-disk cache from the live cache entries, the watch they were
/// resolved for, and the poll time.
fn pr_cache_prefs_from(
    entries: Vec<(PrTarget, PrResolution)>,
    watched: &[PrWatch],
    polled_at: DateTime<Utc>,
) -> PrCachePrefs {
    let mut entries: Vec<PersistedEntry> = entries
        .into_iter()
        .map(|(target, resolution)| PersistedEntry {
            target,
            resolution: PersistedResolution::from_resolution(&resolution),
        })
        .collect();
    // Stable on-disk order so the file does not churn on rewrite from `HashMap`
    // iteration order alone (the same reason `PollingPrefs` sorts).
    entries.sort_by(|a, b| a.target.cmp(&b.target));
    let mut watched: Vec<PersistedWatch> = watched
        .iter()
        .map(|w| PersistedWatch {
            target: w.target.clone(),
            upstream_sha: w.upstream_sha.clone(),
        })
        .collect();
    watched.sort_by(|a, b| a.target.cmp(&b.target));
    PrCachePrefs {
        entries,
        watched,
        polled_at: Some(polled_at),
    }
}

/// Writes `prefs` to `path` as pretty JSON with `0600` perms, creating the parent
/// runtime dir (`0700`) if needed — the [`write_polling_prefs`] pattern.
fn write_pr_cache(path: &Path, prefs: &PrCachePrefs) -> Result<()> {
    if let Some(parent) = path.parent() {
        crate::daemon::paths::ensure_dir_0700(parent)?;
    }
    let json = serde_json::to_vec_pretty(prefs).context("failed to serialize PR cache")?;
    crate::daemon::paths::write_file_0600(path, &json)
}

/// Persists the current PR-badge cache to `path` (best-effort). Reads the live
/// entries off `pr_cache`, pairs them with the `watched` set and `polled_at`, and
/// writes the `0600` file; a failure is logged at WARN and swallowed, since the
/// in-memory cache is authoritative for the running daemon and losing the warm
/// start only costs one extra poll after the next restart.
fn persist_pr_cache(
    path: &Path,
    pr_cache: &PrStatusCache,
    watched: &[PrWatch],
    polled_at: DateTime<Utc>,
) {
    let prefs = pr_cache_prefs_from(pr_cache.entries(), watched, polled_at);
    if let Err(err) = write_pr_cache(path, &prefs) {
        let at = path.display();
        tracing::warn!("could not persist worktrees PR cache to {at}: {err:#}");
    }
}

/// Warm-start state restored from the persisted PR-badge cache (#1389, fix 4):
/// the watch set the previous daemon last resolved and when it last polled. The
/// poller seeds its loop from this so a restart within the backoff window skips
/// the immediate re-poll for verdicts it already holds, instead of spending a `gh`
/// call to re-derive what the `0600` file already carries.
#[derive(Debug, Clone)]
struct PrWarmStart {
    /// The `(target, upstream_sha)` set the persisted verdicts describe.
    watched: Vec<PrWatch>,
    /// When those verdicts were resolved, used to age the warm start against the
    /// backoff (a stale-enough file just re-polls).
    polled_at: DateTime<Utc>,
}

// --- Shared open-PR cache for the daemon-served "Open PR" op (#1389, fix 7) -----

/// One cached `gh pr list` result: the forwarded JSON PR array and when it was
/// fetched, for TTL expiry.
#[derive(Debug, Clone)]
struct OpenPrEntry {
    at: Instant,
    prs: Vec<Value>,
}

/// A shared, TTL'd cache of `gh pr list` results per repo (#1389, fix 7).
///
/// Serving "Open Pull Request…" — and the extension's transient badge fallback —
/// from the daemon means N windows asking about one repo dedupe to a single counted
/// `gh pr list` within the TTL, instead of each window shelling its own (the
/// per-window burn #1370/#1389 target). A plain temporal cache, **no single-flight**:
/// the access pattern is a manual action (or a brief post-enable transient), so two
/// exactly-concurrent misses for the same repo — costing one extra `gh` — are rare
/// and harmless, while the common repeat-within-TTL is served for free. The lock is
/// never held across an `.await`.
#[derive(Debug)]
struct OpenPrCache {
    entries: Mutex<HashMap<String, OpenPrEntry>>,
    ttl: Duration,
}

impl OpenPrCache {
    fn new(ttl: Duration) -> Self {
        Self {
            entries: Mutex::new(HashMap::new()),
            ttl,
        }
    }

    /// The cached PRs for `key` (`owner/name`) while still within the TTL, else
    /// `None` (a miss that the caller resolves with a fresh `gh`).
    fn fresh(&self, key: &str) -> Option<Vec<Value>> {
        self.entries
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .get(key)
            .filter(|e| e.at.elapsed() < self.ttl)
            .map(|e| e.prs.clone())
    }

    /// Records a freshly-fetched PR list for `key`.
    fn store(&self, key: String, prs: Vec<Value>) {
        self.entries
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .insert(
                key,
                OpenPrEntry {
                    at: Instant::now(),
                    prs,
                },
            );
    }
}

/// Runs `gh pr list` for `slug` (`owner/name`) through the #1387-counted `run_gh`
/// choke point and parses the JSON array of open PRs. **Blocking** (a subprocess) —
/// call on a blocking thread, never an async worker. The array is forwarded to the
/// extension verbatim, which parses it into its `PullRequest` shape.
fn open_pr_list(bin: &Path, slug: &str) -> Result<Vec<Value>> {
    let output = crate::github_metrics::run_gh(
        bin,
        [
            "pr",
            "list",
            "--repo",
            slug,
            "--state",
            "open",
            "--json",
            OPEN_PR_JSON_FIELDS,
            "--limit",
            OPEN_PR_LIST_LIMIT,
        ],
        "pr list",
        None,
    )
    .with_context(|| {
        format!(
            "failed to run {} (is the GitHub CLI installed?)",
            bin.display()
        )
    })?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("gh pr list failed: {}", stderr.trim());
    }
    match serde_json::from_slice(&output.stdout).context("gh pr list returned invalid JSON")? {
        Value::Array(arr) => Ok(arr),
        _ => bail!("gh pr list did not return a JSON array"),
    }
}

/// Computes the **full** [`GitStatus`] of `folder` — branch, repo identity, and
/// the ahead/behind divergence from upstream. Used by the one-shot `list`/`status`
/// op and the tray menu, both bounded to the (few) open windows, where the extra
/// `graph_ahead_behind` walk is negligible. The streamed `tree` snapshot uses the
/// cheaper [`git_status_cheap`] instead and fetches divergence on demand (#1306).
fn git_status(folder: &Path) -> GitStatus {
    git_status_impl(folder, true)
}

/// Computes the **cheap** [`GitStatus`] of `folder` — branch and repo identity
/// only, skipping the (expensive) `graph_ahead_behind` upstream revwalk. Used by
/// the `tree`/`subscribe` snapshot, which is rebuilt for **every** worktree on
/// **every** tick: divergence there is computed lazily via the `ahead-behind` op
/// only for the worktrees a client actually looks at (#1306). The `ahead`/`behind`
/// fields stay `None`, so they are omitted on the wire exactly as for a branch
/// with no upstream.
fn git_status_cheap(folder: &Path) -> GitStatus {
    git_status_impl(folder, false)
}

/// The shared body of [`git_status`] / [`git_status_cheap`]: discovers the
/// repository that contains `folder` — so a subdirectory or a linked worktree both
/// resolve — reads HEAD, and (only when `with_ahead_behind`) walks the upstream
/// divergence. Every failure mode degrades to an empty status rather than
/// erroring: the enrichment is best-effort and must never sink a `list` or a tree.
fn git_status_impl(folder: &Path, with_ahead_behind: bool) -> GitStatus {
    let Ok(repo) = Repository::discover(folder) else {
        return GitStatus::default();
    };
    // Repo identity applies even when HEAD is unborn or detached, so a worktree
    // still names its parent repo (and is flagged as a worktree) in those states.
    // The in-progress operation is read here too, for the same reason: a worktree
    // mid-rebase has a *detached* HEAD, so reading it any later would miss the one
    // state the cue exists to show.
    let base = GitStatus {
        main_repo: main_repo_name(repo.commondir()),
        is_worktree: repo.is_worktree(),
        operation: operation_slug(repo.state()),
        ..GitStatus::default()
    };
    let Ok(head) = repo.head() else {
        // An unborn branch (fresh repo, no commits) or an unreadable HEAD.
        return base;
    };
    // Resolved here — before the branch filter below, so a detached HEAD still
    // reports its commit, and before `Branch::wrap` consumes `head`. `target()` is
    // a refs read: no revwalk and no object lookup, so unlike the divergence walk
    // it is cheap enough for the streamed snapshot's every-worktree-every-tick
    // rebuild (#1306's bar).
    let base = GitStatus {
        head_sha: head.target().map(|oid| oid.to_string()),
        ..base
    };
    // A branch HEAD has a UTF-8 shorthand; anything else — a detached HEAD
    // (mid-rebase or a checked-out tag/commit), or the rare non-UTF-8 branch
    // name — degrades to no branch through this one path.
    let Some(name) = head
        .shorthand()
        .ok()
        .filter(|_| head.is_branch())
        .map(str::to_string)
    else {
        return base;
    };
    // Consumes `head`, so it has to follow the `shorthand()` read above. A pure
    // type wrapper — no I/O — so hoisting it out of the `with_ahead_behind` arm
    // below costs the cheap path nothing, and is what gives it a handle to
    // resolve the upstream from.
    let branch = git2::Branch::wrap(head);
    // Unlike the divergence walk, this rides both paths: it is what makes a push
    // a visible delta (#1344).
    let upstream_sha = upstream_target(&branch);
    // The divergence walk is the dominant per-worktree cost, so the cheap path
    // skips it and leaves ahead/behind absent.
    let (ahead, behind) = if with_ahead_behind {
        match upstream_ahead_behind(&repo, &branch) {
            Some((ahead, behind)) => (Some(ahead), Some(behind)),
            None => (None, None),
        }
    } else {
        (None, None)
    };
    GitStatus {
        branch: Some(name),
        upstream_sha,
        ahead,
        behind,
        ..base
    }
}

/// The stable kebab-case slug for a repository's in-progress operation, or `None`
/// when it is [`RepositoryState::Clean`] (#1415).
///
/// The three rebase flavours libgit2 distinguishes (`Rebase`, `RebaseInteractive`,
/// `RebaseMerge`) all collapse to `rebase-interactive` or `rebase`, because the
/// distinction is an implementation detail of how git is driving the rebase and
/// says nothing a user acting on the row would do differently. The `*Sequence`
/// variants likewise fold into their singular form. Everything a client does not
/// recognise still renders as "some operation in progress", which is the useful
/// floor.
fn operation_slug(state: RepositoryState) -> Option<String> {
    let slug = match state {
        RepositoryState::Clean => return None,
        RepositoryState::Merge => "merge",
        RepositoryState::Revert | RepositoryState::RevertSequence => "revert",
        RepositoryState::CherryPick | RepositoryState::CherryPickSequence => "cherry-pick",
        RepositoryState::Bisect => "bisect",
        RepositoryState::Rebase | RepositoryState::RebaseMerge => "rebase",
        RepositoryState::RebaseInteractive => "rebase-interactive",
        RepositoryState::ApplyMailbox | RepositoryState::ApplyMailboxOrRebase => "apply-mailbox",
    };
    Some(slug.to_string())
}

/// The commit `branch`'s configured upstream ref points at, or `None` when it
/// tracks no upstream (or the ref is unresolvable).
///
/// Costs a config lookup (`branch.<name>.remote` + `.merge`) and a
/// remote-tracking refs read — more than [`git_status_impl`]'s single `head`
/// refs read, but still **no revwalk and no object lookup**, which is the bar
/// #1306 set for the snapshot's every-worktree-every-tick rebuild and the one
/// `graph_ahead_behind` fails. [`upstream_ahead_behind`] already resolves the
/// same OID, so it is proven reachable.
fn upstream_target(branch: &git2::Branch<'_>) -> Option<String> {
    Some(branch.upstream().ok()?.get().target()?.to_string())
}

/// The ahead/behind divergence of `repo`'s checked-out branch versus its
/// upstream, computed on demand for the lazy `ahead-behind` op (#1306). Mirrors the
/// branch resolution in [`git_status_impl`] but does **only** the upstream walk
/// [`git_status_cheap`] omits. `None` when HEAD is detached or unborn, or the
/// branch tracks no upstream — every case the tree renders without a sync
/// indicator.
///
/// Takes an open repository so [`folder_divergence`] can answer this and
/// [`repo_main_behind`] from one `Repository::discover` (#2111).
fn repo_ahead_behind(repo: &Repository) -> Option<(usize, usize)> {
    let head = repo.head().ok()?;
    if !head.is_branch() {
        return None;
    }
    let branch = git2::Branch::wrap(head);
    upstream_ahead_behind(repo, &branch)
}

/// Commits `repo`'s checked-out branch is behind the repository's remote
/// default branch (`origin/<main>`), computed on demand for the lazy
/// `ahead-behind` op (#1457). Resolves the default branch the same
/// **local-only, no-fetch** way `worktree_rebase::resolve_onto` resolves its
/// `--onto` default — via [`RemoteInfo::detect_main_branch_local`] — but,
/// unlike that resolver, never falls back to a hardcoded `"main"`: this is a
/// passive signal, so an unresolvable default branch means silence (`None`)
/// rather than a guess.
///
/// `None` when: HEAD is detached/unborn, no default branch is locally
/// resolvable, or the branch's own upstream **is** already that default branch —
/// in which case [`repo_ahead_behind`]'s `behind` already reports this exact
/// divergence, so repeating it here would just duplicate the existing sync count.
fn repo_main_behind(repo: &Repository) -> Option<usize> {
    let head = repo.head().ok()?;
    if !head.is_branch() {
        return None;
    }
    let branch = git2::Branch::wrap(head);

    let remote = "origin";
    let default_branch = RemoteInfo::detect_main_branch_local(repo, remote)?;
    let onto_ref = format!("refs/remotes/{remote}/{default_branch}");

    // Skip when the branch's own upstream already IS the resolved default
    // branch (the common checked-out-main/master case) — compared by ref name
    // so a fork's upstream on a *different* remote (e.g. `upstream/main`) is
    // never mistaken for it.
    if let Ok(upstream) = branch.upstream() {
        if upstream.get().name() == Ok(onto_ref.as_str()) {
            return None;
        }
    }

    let head_oid = branch.get().target()?;
    let onto_oid = repo
        .revparse_single(&onto_ref)
        .ok()?
        .peel_to_commit()
        .ok()?
        .id();
    let (_ahead, behind) = divergence::graph_ahead_behind(repo, head_oid, onto_oid)?;
    Some(behind)
}

/// Both lazily-fetched divergences of `folder`, from a single repository open.
/// What the `ahead-behind` op computes per worktree (#2111).
fn folder_divergence(folder: &Path) -> Divergence {
    let Ok(repo) = Repository::discover(folder) else {
        return Divergence::default();
    };
    Divergence {
        ahead_behind: repo_ahead_behind(&repo),
        main_behind: repo_main_behind(&repo),
    }
}

/// The main repository's directory name from git's common dir. For the usual
/// `<repo>/.git` layout — shared by a checkout and all its linked worktrees —
/// that is the working-tree directory's name; for a bare repo (`<name>.git`) it
/// is that directory with a trailing `.git` stripped. Best-effort: `None` when
/// no name can be derived.
fn main_repo_name(commondir: &Path) -> Option<String> {
    let file_name = commondir.file_name()?.to_string_lossy().into_owned();
    if file_name == ".git" {
        // Normal layout: the repo is the directory that contains `.git`.
        commondir
            .parent()
            .and_then(Path::file_name)
            .map(|n| n.to_string_lossy().into_owned())
    } else {
        // A bare repo: use its own directory name, without any `.git` suffix.
        Some(
            file_name
                .strip_suffix(".git")
                .unwrap_or(&file_name)
                .to_string(),
        )
    }
}

/// Ahead/behind commit counts of `branch` versus its configured upstream, or
/// `None` when the branch tracks no upstream (or either tip is unresolvable).
fn upstream_ahead_behind(repo: &Repository, branch: &git2::Branch<'_>) -> Option<(usize, usize)> {
    let upstream = branch.upstream().ok()?;
    let local_oid = branch.get().target()?;
    let upstream_oid = upstream.get().target()?;
    divergence::graph_ahead_behind(repo, local_oid, upstream_oid)
}

/// The wire shape of an enriched window: the stored entry fields plus the
/// daemon-computed git state, flattened into one JSON object. Serializing
/// through a single struct (rather than mutating a `Value`) keeps every present
/// field on one code path and lets `skip_serializing_if` on [`GitStatus`] drop
/// the absent git fields — no manual per-field insertion.
#[derive(Serialize)]
struct EnrichedEntry<'a> {
    #[serde(flatten)]
    entry: &'a WindowEntry,
    #[serde(flatten)]
    git: GitStatus,
}

/// Serializes a registry entry and folds in the live [`git_status`] of its
/// primary (first) folder, producing the JSON object served on the wire
/// (`list`/`status`) and read by the extension UI. Only the primary folder is
/// enriched — it is the one the table shows and the "focus" action opens.
fn enriched_entry(entry: &WindowEntry) -> Value {
    let git = entry
        .folders
        .first()
        .map(|folder| git_status(folder))
        .unwrap_or_default();
    serde_json::to_value(EnrichedEntry { entry, git }).unwrap_or_else(|_| json!({}))
}

/// Enriches a batch of entries with their git state on a blocking thread, since
/// `git2` does synchronous disk I/O and this runs inside the async control-socket
/// handler. A join failure degrades to an empty list rather than erroring.
async fn enriched_windows(entries: Vec<WindowEntry>) -> Vec<Value> {
    tokio::task::spawn_blocking(move || entries.iter().map(enriched_entry).collect())
        .await
        .unwrap_or_default()
}

// --- Repo/worktree tree (#1265) ----------------------------------------------

/// A GitHub `owner/name` identity parsed from a repository's `origin` remote.
/// Present on a repo in the `tree` payload only for `github.com` remotes; a
/// non-GitHub (or remote-less) repo omits it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct GithubIdentity {
    /// The repository owner (user or org) — the first path segment.
    owner: String,
    /// The repository name, with any `.git` suffix stripped.
    name: String,
}

/// One worktree of a repository in the `tree` payload: its path, live git state,
/// whether it is the main working tree, and whether a VS Code window currently
/// has it open (with that window's key, for the focus action). Optional git
/// fields degrade independently, exactly like [`GitStatus`].
///
/// Ahead/behind **divergence** is deliberately absent from this snapshot: it was
/// the dominant per-worktree cost when computed eagerly for every worktree on
/// every tick, so it is now fetched lazily via the `ahead-behind` op only for the
/// worktrees a client actually shows (#1306).
///
/// The two **OIDs** the divergence is computed from — `head_sha` and
/// `upstream_sha` — do ride the snapshot, which is not a contradiction: each is a
/// refs read rather than a commit-graph walk, and between them they are what makes
/// a commit (#1337) or a push (#1344) a *visible delta*, so a client knows to
/// re-ask for the counts it left behind.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct TreeWorktree {
    /// Absolute path to the worktree's working directory.
    path: String,
    /// The checked-out branch, or `None` when detached or unborn.
    #[serde(skip_serializing_if = "Option::is_none")]
    branch: Option<String>,
    /// The commit HEAD points at, or `None` when unborn. Unlike ahead/behind this
    /// **does** ride the snapshot: it costs a refs read, and it is what makes a new
    /// commit a visible delta, so a push re-renders instead of being dropped by the
    /// server's snapshot diff (#1337).
    #[serde(skip_serializing_if = "Option::is_none")]
    head_sha: Option<String>,
    /// The commit the branch's upstream ref points at, or `None` without an
    /// upstream. The push counterpart of `head_sha`: a push moves only
    /// `refs/remotes/<remote>/<branch>`, so this is the *one* field that moves —
    /// making the snapshot a real delta the server's diff cannot drop, which is
    /// what re-fetches the lazy ahead/behind (#1344).
    #[serde(skip_serializing_if = "Option::is_none")]
    upstream_sha: Option<String>,
    /// Whether this is the repository's main working tree (vs a linked worktree).
    is_main: bool,
    /// Whether a live VS Code window currently has this worktree open.
    open: bool,
    /// The open window's registry key, when `open` — the handle a focus action
    /// resolves. Absent for a worktree with no open window.
    #[serde(skip_serializing_if = "Option::is_none")]
    window_key: Option<String>,
    /// The open PR whose head is this worktree's branch, with its CI verdict
    /// (#1337). Resolved by the daemon's background poller and folded on as the
    /// snapshot is built, so every open window sees the same live state without
    /// each running its own `gh`. Absent for a detached/non-GitHub worktree, one
    /// with no open PR (see `pr_none`), or until the first poll lands.
    #[serde(skip_serializing_if = "Option::is_none")]
    pr: Option<PrBadge>,
    /// Set when the daemon **checked GitHub and found no open PR** for this
    /// worktree's branch — the explicit negative (#1370), mutually exclusive
    /// with `pr`. Omitted (false) whenever `pr` is present, for a branchless or
    /// non-GitHub worktree, and — crucially — while the branch is simply **not
    /// yet resolved** (before the first poll lands, or ever, on a failed one):
    /// `pr` absent *and* `pr_none` absent still means "not resolved", so an
    /// older client stays byte-identical (ADR-0053). Clients use it to keep
    /// their degraded per-window `gh pr list` fallback quiet for branches the
    /// daemon has already answered for.
    #[serde(skip_serializing_if = "is_false")]
    pr_none: bool,
    /// The multi-step git operation this worktree is mid-way through, when any
    /// (#1415) — see [`GitStatus::operation`]. The **durable** half of the rebase
    /// cue: a conflict the `rebase` op left in place shows here until it is
    /// resolved, across daemon restarts. Omitted for a clean worktree.
    #[serde(skip_serializing_if = "Option::is_none")]
    operation: Option<String>,
    /// Whether the daemon is rebasing this worktree **right now** (#1415) — the
    /// **transient** half of the cue, from the registry's in-memory set.
    ///
    /// Not redundant with `operation`: a rebase that applies cleanly never leaves
    /// an on-disk state for `operation` to report, and even one that conflicts
    /// only writes it at the moment of collision — so without this a multi-second
    /// rebase would render as nothing happening at all. Omitted (false) for the
    /// common case, keeping an older client byte-identical.
    #[serde(skip_serializing_if = "is_false")]
    rebasing: bool,
    /// Whether the daemon is pushing this worktree **right now** (#1443) — the
    /// `rebasing` twin, from the registry's other in-flight set.
    ///
    /// Unlike a rebase this cue has **no durable half**: a push writes no on-disk
    /// state, so there is nothing for a later snapshot to rediscover and this flag
    /// is the whole of it. A *completed* push instead shows up as `upstream_sha`
    /// moving, which is why that field rides the snapshot (#1344). Omitted (false)
    /// for the common case, keeping an older client byte-identical.
    #[serde(skip_serializing_if = "is_false")]
    pushing: bool,
}

/// The registry's two transient in-flight sets, read together into one tree
/// snapshot (#1443).
///
/// Grouped rather than threaded as two parameters through
/// [`worktree_entry`]/[`repo_tree`]/[`build_tree`]/[`tree_repos`]: they are always
/// read at the same moment, from the same registry, for the same snapshot, and a
/// third would otherwise mean a fifth positional `HashSet` at every level.
#[derive(Debug, Clone, Default)]
struct InFlight {
    /// Worktree paths the `rebase` op is executing on (#1415).
    rebasing: HashSet<PathBuf>,
    /// Worktree paths the `push` op is executing on (#1443).
    pushing: HashSet<PathBuf>,
}

impl InFlight {
    /// Reads both sets off the registry. Two short lock acquisitions, neither held
    /// across an `.await`; the pair need not be atomic, since each cue is
    /// independently true or false of a given row.
    fn read(registry: &WorktreesRegistry) -> Self {
        Self {
            rebasing: registry.rebasing_paths(),
            pushing: registry.pushing_paths(),
        }
    }
}

/// One repository (with **all** its worktrees) in the `tree` payload. Repos are
/// derived from the distinct open windows; a repo leaves the tree when its last
/// window closes (the open-window-derived model, ADR-0040 / #1264).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct TreeRepo {
    /// The main repository's directory name (see [`main_repo_name`]).
    main_repo: String,
    /// The GitHub identity of `origin`, when it is a `github.com` remote.
    #[serde(skip_serializing_if = "Option::is_none")]
    github: Option<GithubIdentity>,
    /// Absolute path to the main working tree — the repo's root.
    root: String,
    /// Whether the daemon polls this repo's PR badges (#1376). Stamped from the
    /// registry's per-repo enable set, which defaults **off**, so it is omitted
    /// (false) for the common not-polled repo — keeping older clients
    /// byte-identical — and present (`true`) only for a repo the user has
    /// explicitly enabled. The extension colours the repo icon green when set and
    /// gates the "Disable PR Polling" menu on it; the daemon's own poller filters
    /// on it so a not-polled repo issues zero `gh`.
    #[serde(skip_serializing_if = "is_false")]
    polling_enabled: bool,
    /// Every worktree of the repo: the main working tree first, then linked
    /// worktrees sorted by path.
    worktrees: Vec<TreeWorktree>,
}

/// Parses a git remote URL into its GitHub `owner/name`, or `None` for any
/// non-GitHub host. Handles the common forms: `https://github.com/o/r(.git)`,
/// `http://…`, `ssh://git@github.com/o/r(.git)`, `git://github.com/o/r(.git)`,
/// and the SCP-like `git@github.com:o/r(.git)`. A trailing `.git` and trailing
/// slashes are stripped; anything with an empty or extra path segment is
/// rejected (best-effort, never panics).
fn github_identity(url: &str) -> Option<GithubIdentity> {
    let url = url.trim();
    // Reduce every supported form to the `owner/name…` tail after the host.
    let rest = [
        "https://github.com/",
        "http://github.com/",
        "ssh://git@github.com/",
        "git://github.com/",
        "git@github.com:",
    ]
    .iter()
    .find_map(|prefix| url.strip_prefix(prefix))?;
    let rest = rest.strip_suffix(".git").unwrap_or(rest);
    let rest = rest.trim_end_matches('/');
    let mut parts = rest.splitn(2, '/');
    let owner = parts.next()?.trim();
    let name = parts.next()?.trim();
    // A well-formed identity has exactly two non-empty segments.
    if owner.is_empty() || name.is_empty() || name.contains('/') {
        return None;
    }
    Some(GithubIdentity {
        owner: owner.to_string(),
        name: name.to_string(),
    })
}

/// The GitHub identity of `repo`: `origin`'s URL first, else the first
/// `github.com` remote found. `None` when no remote is a GitHub remote.
fn remote_github_identity(repo: &Repository) -> Option<GithubIdentity> {
    if let Ok(origin) = repo.find_remote("origin") {
        if let Some(id) = origin.url().ok().and_then(github_identity) {
            return Some(id);
        }
    }
    // `remotes()` yields `Result<Option<&str>, _>` per name; the first flatten
    // drops the (per-name) errors, the second the non-UTF-8 `None`s. `names` is
    // bound so `iter()` can borrow it (only `&StringArray` is `IntoIterator`).
    let names = repo.remotes().ok();
    names
        .iter()
        .flat_map(|arr| arr.iter())
        .flatten()
        .flatten()
        .filter_map(|name| repo.find_remote(name).ok())
        .find_map(|remote| remote.url().ok().and_then(github_identity))
}

/// Canonicalizes a path for stable comparison (resolving symlinks and `..`),
/// falling back to the path as-given when it cannot be canonicalized (e.g. it
/// no longer exists) so the join still degrades gracefully.
fn canonical(path: &Path) -> PathBuf {
    std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
}

/// Indexes the open windows by canonicalized workspace-folder path → window key,
/// so a worktree path can be joined back to the window (if any) that has it open.
/// The first window wins a shared folder; `entries` arrive in a deterministic
/// (repo, key) order, so the choice is stable.
fn open_window_index(entries: &[WindowEntry]) -> HashMap<PathBuf, String> {
    let mut index = HashMap::new();
    for entry in entries {
        for folder in &entry.folders {
            index
                .entry(canonical(folder))
                .or_insert_with(|| entry.key.clone());
        }
    }
    index
}

/// Builds a [`TreeWorktree`] for `path`: reuses [`git_status_cheap`] for the live
/// git state (branch + repo identity, **no** ahead/behind walk — that is lazy per
/// #1306) and joins the open-window index for `open`/`window_key`. `is_main` is set
/// by the caller from the enumeration (main working tree vs linked).
fn worktree_entry(
    path: &Path,
    is_main: bool,
    open_index: &HashMap<PathBuf, String>,
    in_flight: &InFlight,
) -> TreeWorktree {
    let status = git_status_cheap(path);
    let canonical = canonical(path);
    let window_key = open_index.get(&canonical).cloned();
    TreeWorktree {
        path: path.display().to_string(),
        branch: status.branch,
        head_sha: status.head_sha,
        upstream_sha: status.upstream_sha,
        is_main,
        open: window_key.is_some(),
        window_key,
        // Folded on afterwards by `fold_pr_badges`, which needs the repo's GitHub
        // identity — known one level up, in `repo_tree`.
        pr: None,
        pr_none: false,
        operation: status.operation,
        // Every in-flight cue is joined on the *canonical* path: the registry sets
        // are canonicalized by the adapter when an op marks them.
        rebasing: in_flight.rebasing.contains(&canonical),
        pushing: in_flight.pushing.contains(&canonical),
    }
}

/// Folds the poller's cached PR resolutions onto each worktree of each repo
/// (#1337).
///
/// Runs after [`build_tree`] because a resolution is keyed by (repo GitHub
/// identity, branch) and the identity is only known once the repo is assembled.
/// Purely a cache read — no I/O, no network — so it is safe on the snapshot's hot
/// path. A non-GitHub repo, a branchless worktree, or an unresolved branch simply
/// keeps `pr: None`/`pr_none: false` and renders nothing.
///
/// A verdict computed for a **different commit** than the worktree has checked out
/// is downgraded to pending here rather than shown as-is. That is what makes a push
/// invalidate the badge the moment it happens: the cache still holds the previous
/// commit's verdict, and this fold — which runs on every snapshot — notices without
/// waiting for a poll. Without it the previous head's `✓` stands until the poller
/// next runs, which is up to the full backoff.
///
/// A **negative** ([`PrResolution::NoPr`], #1370) is deliberately *not* dropped
/// when `head_sha` moves: it has no commit to be stale against, and dropping it
/// would re-arm every client's `gh` fallback on every local commit. The poller's
/// `moved` trigger re-checks the branch within one fast poll anyway.
/// Stamps each repo's `polling_enabled` flag from the registry's per-repo PR-poll
/// enable set (#1376).
///
/// Runs after [`build_tree`] (which knows the GitHub identity) and **before**
/// [`fold_pr_badges`] (which skips a not-polled repo), so a repo the user has not
/// enabled carries neither the flag nor any badge. Purely a set membership check —
/// no I/O — so it is safe on the snapshot's hot path. A non-GitHub repo has no key
/// and stays `false`; it never polls anyway.
fn stamp_polling(repos: &mut [TreeRepo], enabled: &HashSet<String>) {
    for repo in repos {
        if let Some(github) = &repo.github {
            repo.polling_enabled = enabled.contains(&format!("{}/{}", github.owner, github.name));
        }
    }
}

fn fold_pr_badges(repos: &mut [TreeRepo], pr_cache: &PrStatusCache) {
    for repo in repos {
        // A not-polled repo (#1376) never carries a badge: skip it so a repo the
        // user disabled drops its `pr`/`pr_none` the moment `stamp_polling` clears
        // the flag, and so the icon greys cross-window on the next pushed snapshot.
        if !repo.polling_enabled {
            continue;
        }
        let Some(github) = repo.github.clone() else {
            continue;
        };
        for worktree in &mut repo.worktrees {
            let Some(branch) = &worktree.branch else {
                continue;
            };
            match pr_cache.get(&github.owner, &github.name, branch) {
                Some(PrResolution::Pr(mut badge)) => {
                    if badge.is_stale_for(worktree.head_sha.as_deref()) {
                        badge.checks = PrCheckState::Pending;
                    }
                    worktree.pr = Some(badge);
                }
                Some(PrResolution::NoPr) => worktree.pr_none = true,
                None => {}
            }
        }
    }
}

/// Enumerates a repository and all its worktrees into a [`TreeRepo`], given a
/// handle discovered from one of its folders. Opens the **main** repo from the
/// shared common dir's parent so the main working tree and every linked worktree
/// are enumerated regardless of which one seeded the discovery. `None` for a
/// bare or otherwise root-less repo (no working tree to show).
fn repo_tree(
    discovered: &Repository,
    open_index: &HashMap<PathBuf, String>,
    in_flight: &InFlight,
) -> Option<TreeRepo> {
    // The common dir (`…/<root>/.git`) is shared by the main checkout and all
    // linked worktrees; its parent is the main working tree.
    let commondir = canonical(discovered.commondir());
    let main_root = commondir.parent()?.to_path_buf();
    let main_repo = Repository::open(&main_root).ok()?;

    // Main working tree first.
    let mut worktrees = vec![worktree_entry(&main_root, true, open_index, in_flight)];
    // Then every linked worktree, sorted by path for deterministic output. The
    // `StringArray` of names is bound so `iter()` can borrow it (only
    // `&StringArray` is `IntoIterator`); a name that no longer resolves to a
    // worktree is skipped.
    let names = main_repo.worktrees().ok();
    let mut linked: Vec<PathBuf> = names
        .iter()
        .flat_map(|arr| arr.iter())
        .flatten() // Result<Option<&str>, _> → Option<&str> (drop per-name errors)
        .flatten() // Option<&str> → &str (drop non-UTF-8 names)
        .filter_map(|name| main_repo.find_worktree(name).ok())
        .map(|wt| wt.path().to_path_buf())
        .collect();
    linked.sort();
    worktrees.extend(
        linked
            .iter()
            .map(|path| worktree_entry(path, false, open_index, in_flight)),
    );

    Some(TreeRepo {
        main_repo: main_repo_name(&commondir)?,
        github: remote_github_identity(&main_repo),
        root: main_root.display().to_string(),
        // Defaults off; `stamp_polling` sets it from the registry's enable set
        // once the repo (and thus its GitHub identity) is assembled.
        polling_enabled: false,
        worktrees,
    })
}

/// Resolves the seed `folders` to their distinct repositories and enumerates
/// each repo's worktrees. Dedupes repos by their common dir (shared across a
/// repo's worktrees) via a `BTreeMap` for deterministic ordering; a folder that
/// is not in a git repo is skipped. Pure blocking git I/O — call it via
/// [`tree_repos`], never under the registry lock.
fn build_tree(
    folders: Vec<PathBuf>,
    windows: Vec<WindowEntry>,
    in_flight: InFlight,
) -> Vec<TreeRepo> {
    let open_index = open_window_index(&windows);
    let mut repos: BTreeMap<PathBuf, TreeRepo> = BTreeMap::new();
    for folder in &folders {
        let Ok(repo) = Repository::discover(folder) else {
            continue;
        };
        let key = canonical(repo.commondir());
        if repos.contains_key(&key) {
            continue;
        }
        if let Some(tree) = repo_tree(&repo, &open_index, &in_flight) {
            repos.insert(key, tree);
        }
    }
    repos.into_values().collect()
}

/// Enumerates and enriches the repo/worktree tree on a blocking thread (`git2`
/// does synchronous disk I/O and this runs inside the async control-socket
/// handler), returning the serialized `repos` array. A join failure degrades to
/// an empty list rather than erroring, matching [`enriched_windows`].
async fn tree_repos(
    folders: Vec<PathBuf>,
    windows: Vec<WindowEntry>,
    pr_cache: Arc<PrStatusCache>,
    enabled_polling: HashSet<String>,
    in_flight: InFlight,
) -> Vec<Value> {
    tokio::task::spawn_blocking(move || {
        let mut repos = build_tree(folders, windows, in_flight);
        // Stamp per-repo poll state first so `fold_pr_badges` can skip a
        // not-polled repo — a disabled repo carries neither the flag nor a badge.
        stamp_polling(&mut repos, &enabled_polling);
        fold_pr_badges(&mut repos, &pr_cache);
        repos
            .iter()
            .map(|repo| serde_json::to_value(repo).unwrap_or_else(|_| json!({})))
            .collect()
    })
    .await
    .unwrap_or_default()
}

// --- Lazy ahead/behind (#1306) -----------------------------------------------

/// The wire shape of one worktree's lazily-fetched divergence: `ahead`/`behind`
/// (from its own upstream, folded in together or not at all — they come from one
/// `graph_ahead_behind` call) and `main_behind` (from the repo's remote default
/// branch, #1457), each independently optional. `main_behind` can be present
/// when `ahead`/`behind` are absent (no upstream at all) or absent when they are
/// present (the branch's own upstream already *is* the default branch).
#[derive(Serialize)]
struct AheadBehindEntry {
    #[serde(skip_serializing_if = "Option::is_none")]
    ahead: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    behind: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    main_behind: Option<usize>,
}

/// Computes the ahead/behind divergence for a batch of worktree `paths` on demand,
/// returning a JSON object keyed by the **requested** path string:
/// `{ "<path>": { "ahead"?, "behind"?, "main_behind"? }, … }`. A row is **omitted**
/// when neither the upstream divergence nor the main-branch divergence resolves
/// (not a repo, detached/unborn HEAD) — the client renders it without a sync
/// indicator, exactly as before #1457. A row can otherwise carry any subset of the
/// three fields: `main_behind` alone (no upstream, but behind the default branch),
/// `ahead`/`behind` alone (upstream *is* the default branch, so `main_behind` is
/// skipped), or all three together.
///
/// Backs the `ahead-behind` op, which exists precisely so the streamed `tree`
/// snapshot can stay cheap: a client fetches divergence only for the worktrees it
/// shows (the extension on expand), not for every worktree on every tick.
///
/// Every window re-asks for the same worktrees on each pushed delta, so the work
/// goes through `coordinator` (#2111): concurrent requests for one worktree share a
/// single computation, at most a few run at once, and each runs on a blocking
/// thread (the walks are disk I/O). A computation that fails degrades to "no
/// divergence" for that one worktree, which omits its row, rather than erroring.
async fn ahead_behind_results(coordinator: &AheadBehindCoordinator, paths: Vec<PathBuf>) -> Value {
    let divergences = futures::future::join_all(
        paths
            .iter()
            .map(|path| coordinator.get_or_compute(path.clone(), |p| folder_divergence(&p))),
    )
    .await;
    let mut results = serde_json::Map::new();
    for (path, divergence) in paths.iter().zip(divergences) {
        let (ahead, behind) = divergence
            .ahead_behind
            .map_or((None, None), |(a, b)| (Some(a), Some(b)));
        let main_behind = divergence.main_behind;
        if ahead.is_none() && main_behind.is_none() {
            continue;
        }
        results.insert(
            path.display().to_string(),
            json!(AheadBehindEntry {
                ahead,
                behind,
                main_behind,
            }),
        );
    }
    Value::Object(results)
}

// --- Push subscription (#1267) -----------------------------------------------

/// The [`ServiceStream`] backing the worktrees `subscribe` op: a live push of
/// the same `{ repos: [...] }` snapshot the `tree` op returns (#1265). The
/// server drives it — awaiting [`changed`](ServiceStream::changed) plus its own
/// periodic tick, then diffing [`snapshot`](ServiceStream::snapshot) — so this
/// type only has to (a) relay the registry's change-notify and (b) read the
/// tree snapshot on demand.
///
/// Every window's stream shares one [`TreeSnapshotCache`] (#1303): the snapshot
/// is built at most once per tick and fanned out, rather than each stream
/// rebuilding the identical tree. This type holds only cheap handles — a clone
/// of the shared cache and its own change-notify receiver.
struct WorktreesStream {
    /// The shared coalescing cache the snapshot is read through, so every
    /// stream's tick/change re-sample hits one shared `build_tree` (#1303).
    cache: Arc<TreeSnapshotCache>,
    /// Wakes on each visible-set change (a `register`, a removing `unregister`,
    /// or a mutation-driven reap). A burst coalesces into one wakeup; the
    /// server's diff drops any snapshot that ends up identical.
    changes: watch::Receiver<u64>,
}

#[async_trait]
impl ServiceStream for WorktreesStream {
    async fn changed(&mut self) {
        // `watch::Receiver::changed` marks the newest version seen, so a burst of
        // bumps collapses into a single wakeup. If every sender is gone (the
        // registry — and thus the daemon — is tearing down) it returns `Err`;
        // park instead of returning, so this arm can never spin the server's
        // `select!` (the tick and shutdown arms still drive teardown).
        if self.changes.changed().await.is_err() {
            std::future::pending::<()>().await;
        }
    }

    async fn snapshot(&self) -> Value {
        // Read through the shared coalescing cache. The value is built by the
        // same `tree_snapshot` the `tree` op runs, so a one-shot fetch and this
        // live push agree byte-for-byte — but here it is built once per tick and
        // shared across every subscriber rather than rebuilt per stream (#1303).
        self.cache.snapshot().await
    }
}

/// A coalescing cache for the global tree snapshot (#1303).
///
/// Every open VS Code window holds one persistent [`WorktreesStream`], and the
/// server re-samples each on its own `STREAM_TICK` and on every registry change
/// — so with N windows the *identical* global tree was being built N times per
/// tick. This cache collapses that to **one** build: all streams share it, and
/// it rebuilds at most once per `ttl` (the stream tick) per registry
/// change-generation.
///
/// Two conditions gate reuse, and **both** must hold, so freshness is preserved
/// exactly as before:
/// - the registry's [`change_generation`](WorktreesRegistry::change_generation)
///   still matches — a `register`/`unregister`/toggle bumps it and forces a
///   fresh build, so subscribers never see a stale visible set; and
/// - the cached value is younger than `ttl` — so a pure on-disk git change (a
///   branch switch, new commits), which fires no registry event, still surfaces
///   within one tick.
///
/// Concurrency is single-flight: the `.await`-held [`AsyncMutex`] serializes
/// callers, so a burst of N streams waking on the same tick/change performs one
/// build while the rest wait and read the shared result. The one-shot `tree` op
/// bypasses this and computes fresh — it is a rare manual refresh, not part of
/// the per-tick fan-out.
struct TreeSnapshotCache {
    /// The registry every snapshot is built from, and whose change-generation
    /// gates cache reuse.
    registry: Arc<WorktreesRegistry>,
    /// PR badges folded onto each worktree as the snapshot is built (#1337).
    /// Written by the background poller; read here. A miss simply omits `pr`.
    pr_cache: Arc<PrStatusCache>,
    /// How long a built snapshot stays fresh before a tick-driven read rebuilds
    /// it. Defaults to the server's `STREAM_TICK` (via [`new`](Self::new)) so the
    /// coalesced build runs at most once per tick; tests inject a shorter value.
    ttl: Duration,
    /// The single-flight guard and cached result. A `tokio` mutex (not `std`)
    /// because it is deliberately held across the `.await` of the git
    /// enumeration, so concurrent callers serialize onto one build rather than
    /// each computing their own.
    state: AsyncMutex<Option<CachedTree>>,
    /// How many times the tree was actually (re)built — so tests can assert the
    /// coalescing collapses an N-stream burst into one build. Cheap and always
    /// maintained; only read under `#[cfg(test)]`.
    computes: AtomicU64,
}

/// One cached tree snapshot: the shared value plus the two freshness stamps
/// [`TreeSnapshotCache`] checks before reusing it.
struct CachedTree {
    /// The registry change-generation captured *before* the build, so a change
    /// racing the build advances the generation and the next read rebuilds
    /// (conservative: it may rebuild once needlessly, but never serves stale).
    generation: u64,
    /// When the value was built, for the `ttl` staleness check.
    computed_at: Instant,
    /// The already-built `{ repos, show_closed }` snapshot, fanned out to every
    /// subscriber by cloning the `Arc`'s inner value.
    value: Arc<Value>,
}

impl TreeSnapshotCache {
    /// Creates a cache over `registry` with the default TTL — the server's
    /// [`stream_tick`](crate::daemon::server::stream_tick), so the coalesced
    /// build runs at most once per tick.
    fn new(registry: Arc<WorktreesRegistry>, pr_cache: Arc<PrStatusCache>) -> Self {
        Self::with_ttl(registry, pr_cache, crate::daemon::server::stream_tick())
    }

    /// Creates a cache with an explicit `ttl`, for tests that need a short (or
    /// long) freshness window without waiting a real tick.
    fn with_ttl(
        registry: Arc<WorktreesRegistry>,
        pr_cache: Arc<PrStatusCache>,
        ttl: Duration,
    ) -> Self {
        Self {
            registry,
            pr_cache,
            ttl,
            state: AsyncMutex::new(None),
            computes: AtomicU64::new(0),
        }
    }

    /// The current tree snapshot, built at most once per `ttl` per registry
    /// change-generation and shared across all callers. See the type docs for
    /// the freshness and single-flight semantics.
    async fn snapshot(&self) -> Value {
        // Hold the lock across the whole check-and-build so concurrent callers
        // serialize onto one build (single-flight); reading the generation here
        // (before the build) means a change racing the build forces the *next*
        // read to rebuild rather than serving this now-stale value.
        let mut state = self.state.lock().await;
        let generation = self.registry.change_generation();
        // Reuse the cached value only while it matches the current generation
        // *and* is within the TTL; either failing forces a rebuild.
        let fresh = state.as_ref().and_then(|cached| {
            (cached.generation == generation && cached.computed_at.elapsed() < self.ttl)
                .then(|| Arc::clone(&cached.value))
        });
        let value = if let Some(value) = fresh {
            value
        } else {
            let value = Arc::new(tree_snapshot(&self.registry, self.pr_cache.clone()).await);
            self.computes.fetch_add(1, Ordering::Relaxed);
            *state = Some(CachedTree {
                generation,
                computed_at: Instant::now(),
                value: Arc::clone(&value),
            });
            value
        };
        // Release the lock before the (deeper) clone of the shared value out.
        drop(state);
        (*value).clone()
    }

    /// How many times the tree was actually built — the coalescing assertion in
    /// tests (N reads within one tick/generation should build once).
    #[cfg(test)]
    fn compute_count(&self) -> u64 {
        self.computes.load(Ordering::Relaxed)
    }
}

/// Builds the `{ repos, show_closed }` snapshot shared by the `tree` op and the
/// `subscribe` stream, so the two never drift (#1301). Two cheap registry locks
/// (the seed folders to derive repos from, and the live windows to join on) and
/// a lock-free read of the toggle, then the git enumeration/enrichment off the
/// lock on a blocking thread inside [`tree_repos`].
async fn tree_snapshot(registry: &WorktreesRegistry, pr_cache: Arc<PrStatusCache>) -> Value {
    let folders = registry.open_folders();
    let windows = registry.list();
    let show_closed = registry.show_closed();
    let enabled_polling = registry.enabled_polling_repos();
    // The transient rebase (#1415) and push (#1443) cues, read here with the other
    // cheap registry locks so the git work below deals only in plain data.
    let in_flight = InFlight::read(registry);
    json!({
        "repos": tree_repos(folders, windows, pr_cache, enabled_polling, in_flight).await,
        "show_closed": show_closed,
    })
}

/// A short human name for a window: its repo, else its first folder's basename,
/// else a placeholder.
fn display_name(entry: &WindowEntry) -> String {
    if let Some(repo) = &entry.repo {
        return repo.clone();
    }
    if let Some(folder) = entry.folders.first() {
        return folder.file_name().map_or_else(
            || folder.display().to_string(),
            |n| n.to_string_lossy().into_owned(),
        );
    }
    "(no folder)".to_string()
}

/// Separator between the repo name and branch for a normal working tree.
const REPO_SEP: char = '·';
/// Separator marking a **linked worktree** (a git "fork" glyph), so a worktree
/// line is distinguishable at a glance from its parent repo's main checkout.
const WORKTREE_SEP: char = '⑂';

/// The full tray item list for a window set: the "No open windows" placeholder
/// when empty, else one line per window via [`window_menu_items`]. Does the git
/// enrichment (blocking disk I/O), so it runs on a blocking thread from the
/// background refresh task — and inline only as a cold-start fallback in `menu`.
fn menu_items_for(
    entries: &[WindowEntry],
    rate_limit: Option<&RateLimitSnapshot>,
) -> Vec<MenuItem> {
    let mut items = Vec::new();
    // Prepend the GitHub rate-limit reading (#1375) as a non-clickable status line
    // above the windows, so an approaching exhaustion is visible in the tray before
    // it bites. Absent (unpolled `gh`, or no resources) → no line and no separator.
    if let Some(label) = rate_limit.map(RateLimitSnapshot::tray_label) {
        if !label.is_empty() {
            items.push(MenuItem::Label(label));
            items.push(MenuItem::Separator);
        }
    }
    if entries.is_empty() {
        items.push(MenuItem::Label("No open windows".to_string()));
    } else {
        items.extend(window_menu_items(entries));
    }
    items
}

/// Builds the tray items for a non-empty window list: **one clickable line per
/// window** whose label carries the live git state and whose click focuses that
/// window. A window with no workspace folder has nothing for `code` to open, so
/// it stays a non-clickable status line. The labels read each worktree from disk
/// (via [`window_label`]) — cheap for a realistic window count and consistent
/// with reap-on-read.
fn window_menu_items(entries: &[WindowEntry]) -> Vec<MenuItem> {
    entries
        .iter()
        .map(|entry| {
            let label = window_label(entry);
            if entry.folders.is_empty() {
                MenuItem::Label(label)
            } else {
                MenuItem::Action(MenuAction {
                    id: format!("focus:{}", entry.key),
                    label,
                    enabled: true,
                })
            }
        })
        .collect()
}

/// The tray label for one window: the **main repository** name, then live branch
/// state (`omni-dev · branch (+2 -1)`) when the primary folder is a git repo. A
/// linked worktree is set off with the [`WORKTREE_SEP`] fork glyph
/// (`omni-dev ⑂ branch`) so it reads distinctly from the main checkout; a folder
/// that is not a repo falls back to its reported title.
fn window_label(entry: &WindowEntry) -> String {
    let status = entry
        .folders
        .first()
        .map(|folder| git_status(folder))
        .unwrap_or_default();
    // Prefer the git-derived main repo so a linked worktree names its parent
    // repository rather than its worktree-folder basename.
    let name = status
        .main_repo
        .clone()
        .unwrap_or_else(|| display_name(entry));
    if let Some(branch) = &status.branch {
        let sep = if status.is_worktree {
            WORKTREE_SEP
        } else {
            REPO_SEP
        };
        return match sync_indicator(status.ahead, status.behind) {
            Some(sync) => format!("{name} {sep} {branch} {sync}"),
            None => format!("{name} {sep} {branch}"),
        };
    }
    // No git branch (not a repo / detached): fall back to the reported title.
    match &entry.title {
        Some(title) if title != &name => format!("{name} {REPO_SEP} {title}"),
        _ => name,
    }
}

/// A compact `(+ahead -behind)` divergence indicator, or `None` when the branch
/// has no upstream to compare against.
fn sync_indicator(ahead: Option<usize>, behind: Option<usize>) -> Option<String> {
    match (ahead, behind) {
        (Some(ahead), Some(behind)) => Some(format!("(+{ahead} -{behind})")),
        _ => None,
    }
}

/// Well-known absolute locations for the VS Code launcher, tried in order so a
/// daemon running under launchd (with a minimal `PATH`) still finds it.
const CODE_BINARY_CANDIDATES: &[&str] = &[
    "/usr/local/bin/code",
    "/opt/homebrew/bin/code",
    "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
    "/usr/bin/code",
];

/// Focuses (or opens, since VS Code reuses an already-open window) `folder` in
/// VS Code by spawning its CLI, resolved via [`resolve_code_binary`]. Shared
/// with the sessions service's tray "focus" action, which resolves a session to
/// its VS Code window folder and opens it through this same guarded launcher.
pub(crate) fn focus_window(folder: &Path) -> Result<()> {
    focus_window_with(&resolve_code_binary(), folder)
}

/// Spawns `program` on `folder` after validating the folder. Split out from
/// [`focus_window`] so the validation and spawn paths are testable with an
/// explicit launcher (no environment or installed-editor dependency).
///
/// Best-effort and non-blocking: the spawned child is reaped on a detached
/// thread so a long-lived daemon does not accumulate zombies one per focus.
fn focus_window_with(program: &Path, folder: &Path) -> Result<()> {
    // The tray path passes an absolute workspace folder, but the socket `open`
    // op (#1266) passes an arbitrary client-supplied path, so this guard is a
    // real check there, not just an assertion: requiring an absolute path also
    // rules out a `-`-leading path being parsed by `code` as a flag.
    if !folder.is_absolute() {
        bail!(
            "refusing to focus a non-absolute folder path: {}",
            folder.display()
        );
    }
    if !folder.is_dir() {
        bail!("worktree folder no longer exists: {}", folder.display());
    }
    // Detach the launcher's stdio so its output never interleaves into the
    // long-lived daemon's own stdout/stderr (or the test harness's).
    let child = Command::new(program)
        .arg(folder)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .spawn()
        .with_context(|| {
            format!(
                "failed to launch `{}` to focus {}",
                program.display(),
                folder.display()
            )
        })?;
    // Reap the child without blocking so it never lingers as a zombie.
    std::thread::spawn(move || {
        let mut child = child;
        let _ = child.wait();
    });
    Ok(())
}

/// Resolves the VS Code launcher from the real environment: the
/// `OMNI_DEV_VSCODE_BIN` override, then [`CODE_BINARY_CANDIDATES`], then bare
/// `code` on `PATH`. The pure resolution logic lives in
/// [`resolve_code_binary_from`] for testing.
fn resolve_code_binary() -> PathBuf {
    resolve_code_binary_from(std::env::var_os(VSCODE_BIN_ENV), CODE_BINARY_CANDIDATES)
}

/// Pure launcher resolution: `env_override` wins; otherwise the first existing
/// `candidate`; otherwise bare `code`.
fn resolve_code_binary_from(
    env_override: Option<std::ffi::OsString>,
    candidates: &[&str],
) -> PathBuf {
    if let Some(path) = env_override {
        return PathBuf::from(path);
    }
    for candidate in candidates {
        let path = Path::new(candidate);
        if path.exists() {
            return path.to_path_buf();
        }
    }
    PathBuf::from("code")
}

// --- Reposition op (#1407) ---------------------------------------------------

/// The `reposition` op payload: move every target window onto the invoking
/// window's geometry.
///
/// Keyed by **window key**, not worktree path, because the subject is a *window*:
/// the geometry belongs to the OS window, and a path resolves to one only via the
/// registry. The CLI (which naturally speaks paths) maps them to keys itself
/// before sending.
#[derive(Debug, Clone, Deserialize)]
struct RepositionRequest {
    /// The invoking window's key. Supplies the frame; never moved itself.
    reference_key: String,
    /// The windows to move. May include `reference_key` — a multi-selection
    /// naturally contains the invoking window — which is reported and skipped.
    #[serde(default)]
    target_keys: Vec<String>,
    /// Resolve and report only, writing nothing (`worktrees reposition
    /// --dry-run`). The diagnostic surface for title matching.
    #[serde(default)]
    check: bool,
}

/// Distils the live registration for `key` into what [`geometry`] matches on.
///
/// A key with no live window still yields a value, flagged `live: false`, so it
/// reports as a per-target `no-window` skip rather than vanishing from the batch —
/// a tree row can be a tick stale, and the user needs to see which of their
/// selection was ignored.
fn registered_window(entries: &[WindowEntry], key: &str) -> geometry::RegisteredWindow {
    entries.iter().find(|entry| entry.key == key).map_or_else(
        || geometry::RegisteredWindow {
            key: key.to_string(),
            live: false,
            title: None,
            pid: None,
        },
        |entry| geometry::RegisteredWindow {
            key: entry.key.clone(),
            live: true,
            title: entry.title.clone(),
            pid: entry.pid,
        },
    )
}

/// Renders a [`geometry::RepositionReport`] as the op's reply.
///
/// `trusted` is a reply **field**, not an error, so the client can branch on the
/// missing-permission case as data — offering the user a link to the Accessibility
/// settings pane — rather than pattern-matching an error string.
fn reposition_reply(report: &geometry::RepositionReport, undoable: bool) -> Value {
    let mut reply = json!({
        "trusted": report.trusted,
        "results": report.results,
        "moved": report.moved(),
        "skipped": report.skipped(),
    });
    if let Some(reference) = &report.reference {
        reply["reference"] = serde_json::to_value(reference).unwrap_or_else(|_| json!({}));
    }
    if let Some(blocked) = &report.blocked {
        reply["blocked"] = serde_json::to_value(blocked).unwrap_or_else(|_| json!({}));
    }
    // Omitted unless true, so a client that only reads `results` sees a reply
    // byte-identical to one from a daemon without the undo store.
    if undoable {
        reply["undoable"] = Value::Bool(true);
    }
    reply
}

/// Emits the audit line for a `reposition`, so `omni-dev daemon logs` can answer
/// "why did that window not move?" from the log alone (the ADR-0049 §6 precedent).
/// Sync, like [`log_merge_check`].
fn log_reposition(req: &RepositionRequest, report: &geometry::RepositionReport) {
    // `phase` is a structured field rather than three message literals, so a log
    // filter can select checks from applies without matching on prose.
    let phase = if !report.trusted {
        "untrusted"
    } else if report.blocked.is_some() {
        "blocked"
    } else if req.check {
        "check"
    } else {
        "apply"
    };
    tracing::info!(
        phase,
        reference = req.reference_key.as_str(),
        requested = req.target_keys.len(),
        blocked = report.blocked.as_ref().map_or("-", |b| b.reason),
        moved = report.moved(),
        skipped = report.skipped(),
        outcomes = outcome_kinds(report).as_str(),
        "reposition"
    );
}

/// Emits the audit line for a `reposition-undo`.
fn log_reposition_undo(report: &geometry::RepositionReport) {
    tracing::info!(
        trusted = report.trusted,
        restored = report.moved(),
        skipped = report.skipped(),
        outcomes = outcome_kinds(report).as_str(),
        "reposition undo"
    );
}

/// Joins a report's per-target outcome slugs into one compact `a,b,b` field, so a
/// batch's verdict rides a single structured log value rather than a `Debug` dump —
/// the [`note_kinds`] precedent.
fn outcome_kinds(report: &geometry::RepositionReport) -> String {
    if report.results.is_empty() {
        return "-".to_string();
    }
    report
        .results
        .iter()
        .map(|r| r.outcome)
        .collect::<Vec<_>>()
        .join(",")
}

// --- Reload op (#1417) -------------------------------------------------------

/// The `reload` op payload: reload the listed windows.
///
/// Keyed by **window**, like [`RepositionRequest`] and unlike [`CloseRequest`] —
/// a reload acts on a window, and one tree row is one window, whereas a path can
/// be open in several. There is no `requester_key`: a client that wants to
/// reload itself does so directly rather than waiting a heartbeat for its own
/// directive, so the daemon never needs to know who asked.
#[derive(Debug, Clone, Deserialize)]
struct ReloadRequest {
    /// Registry keys of the windows to signal. An empty list is a no-op, not an
    /// error: the callers all filter their targets first, and reporting zeros is
    /// more useful to a batch client than a failure.
    #[serde(default)]
    target_keys: Vec<String>,
}

/// Emits the audit line for a `reload` op. Sync, like the `close` loggers, so it
/// is unit-testable off the runtime. Logs counts and the unknown keys only —
/// never a path, which this op never sees.
fn log_reload(requested: usize, signalled: usize, unknown: &[String]) {
    // Formatted before the macro, not inside it: a `tracing` field expression is
    // only evaluated when a subscriber is interested, so inlining this would
    // leave it unexecuted (and unmeasurable) in any test that installs none.
    let unknown = if unknown.is_empty() {
        "-".to_string()
    } else {
        unknown.join(",")
    };
    tracing::info!(
        requested,
        signalled,
        unknown = %unknown,
        "worktrees reload: signalled windows"
    );
}

// --- Close op (#1277) --------------------------------------------------------

/// The `close` op payload: close a worktree's window and (for a linked worktree)
/// delete it. Symmetric to `open`, but destructive, so it carries the
/// two-phase-confirm and self-close routing fields.
#[derive(Debug, Clone, Deserialize)]
struct CloseRequest {
    /// Absolute path of the target worktree's working directory.
    path: PathBuf,
    /// The requesting window's key, so a self-close (`requester_key` owns the
    /// target) removes-then-replies and lets the extension close its own window,
    /// rather than waiting on a window that is blocked awaiting this reply.
    #[serde(default)]
    requester_key: Option<String>,
    /// Whether to **delete** the worktree (linked "Close Worktree") rather than
    /// only close its window (main "Close Window"). A delete is refused on the
    /// main working tree regardless of this flag.
    #[serde(default)]
    remove: bool,
    /// Set on the phase-2 execute call. Absent/false with `remove:true` is the
    /// phase-1, side-effect-free safety check; ignored for `remove:false`.
    #[serde(default)]
    confirmed: bool,
}

/// One risk or informational note in a [`SafetyReport`]: a machine-readable
/// `kind` and a human-readable `detail`. Shared by both the blocking `risks`
/// (data would be lost) and the non-blocking `info` (context, e.g. unpushed
/// commits that survive because the branch is kept).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct Note {
    /// A stable machine slug for the condition (e.g. `dirty`, `untracked`).
    kind: String,
    /// A human-readable one-line explanation for the confirm dialog.
    detail: String,
}

impl Note {
    fn new(kind: &str, detail: impl Into<String>) -> Self {
        Self {
            kind: kind.to_string(),
            detail: detail.into(),
        }
    }
}

/// Joins a set of [`Note`]s' machine slugs into a compact `a,b` string (empty →
/// `-`) for a single structured log field. Used by the `close` op's audit lines
/// (#1364) so a verdict's risk kinds ride one field rather than a `Debug` dump.
fn note_kinds(notes: &[Note]) -> String {
    if notes.is_empty() {
        return "-".to_string();
    }
    notes
        .iter()
        .map(|n| n.kind.as_str())
        .collect::<Vec<_>>()
        .join(",")
}

/// Whether a `close` execute is a **self-close**: the requesting window owns the
/// target, so it acts on our `ok:true` reply and never rides the cross-window
/// signal. Split out as a pure predicate so the routing decision the audit line
/// (#1364) reports is unit-testable.
fn is_self_close(requester_key: Option<&str>, open_windows: &[(String, usize)]) -> bool {
    requester_key.is_some_and(|rk| open_windows.iter().any(|(k, _)| k == rk))
}

/// Logs a `close`-op failure at ERROR before propagating it. The phase-1/phase-2
/// audit lines sit *past* the fallible `git_safety` / removal calls, so without
/// this a failed safety check (a non-git-worktree target) or a panicked blocking
/// task would early-return invisibly — the exact blind spot #1364 closes. Returns
/// the error unchanged so callers keep using `?`.
fn log_close_error(path: &Path, phase: &str, err: anyhow::Error) -> anyhow::Error {
    tracing::error!(
        path = %path.display(),
        "worktrees close: {phase} failed: {err:#}"
    );
    err
}

/// Logs the outcome of a linked-worktree removal and maps it to the `close`
/// reply. Split out of [`WorktreesService::close`] so the destructive op's audit
/// line (#1364) is unit-testable without a tokio runtime or the `spawn_blocking`
/// the real prune runs behind.
///
/// The three outcomes are logged distinctly (#1403) so a future "the daemon says
/// pruned but the row is still there" is diagnosable from the log alone: an
/// actual prune and an already-gone no-op are both INFO (and both reply
/// `removed: true` — the row should go either way), but carry different
/// `outcome`/message text; a failure is WARN and propagates the error.
fn log_and_map_removal(path: &Path, removed: Result<Removal>) -> Result<Value> {
    match removed {
        Ok(Removal::Pruned) => {
            tracing::info!(
                path = %path.display(),
                outcome = "pruned",
                "worktrees close: linked worktree pruned"
            );
            Ok(json!({ "removed": true }))
        }
        Ok(Removal::AlreadyGone) => {
            tracing::info!(
                path = %path.display(),
                outcome = "already-gone",
                "worktrees close: nothing to prune, worktree already removed"
            );
            Ok(json!({ "removed": true }))
        }
        Err(err) => {
            tracing::warn!(
                path = %path.display(),
                outcome = "failed",
                "worktrees close: worktree prune failed: {err:#}"
            );
            Err(err)
        }
    }
}

/// Emits the phase-1 audit line for a `close` safety check (#1364): the target,
/// the owning window key (if any), the open flag, and the deletability verdict
/// with the blocking risk kinds. Split out so the audit line is unit-testable off
/// the runtime — a `tracing` event fired right after the `git_safety`
/// `spawn_blocking` is not reliably captured under the parallel suite.
fn log_safety_check(path: &Path, window_key: Option<&str>, git: &GitSafety, open: bool) {
    tracing::info!(
        path = %path.display(),
        window_key = window_key.unwrap_or("-"),
        removable = git.removable,
        is_main = git.is_main,
        open,
        risks = %note_kinds(&git.risks),
        "worktrees close: safety check"
    );
}

/// Emits the phase-2 audit line for a `close` execute (#1364): the requesting
/// window key and the routing decision (self-close vs. how many cross-window
/// targets are being signalled), logged before the wait so it is auditable even
/// if that wait then hangs. Sync so it is unit-testable off the runtime.
fn log_executing(
    path: &Path,
    requester: Option<&str>,
    remove: bool,
    self_close: bool,
    cross_window: usize,
) {
    tracing::info!(
        path = %path.display(),
        requester = requester.unwrap_or("-"),
        remove,
        self_close,
        cross_window,
        "worktrees close: executing"
    );
}

/// Emits the phase-2 audit WARN when a `close` execute aborts because a signalled
/// window never closed (#1364): the op leaves the worktree intact. Sync so it is
/// unit-testable off the runtime.
fn log_close_abort(path: &Path, err: &anyhow::Error) {
    tracing::warn!(
        path = %path.display(),
        "worktrees close: aborted — signalled window(s) did not close: {err:#}"
    );
}

/// Emits the phase-2 audit line for a non-destructive `close` — "Close Window":
/// the window is closed and nothing is deleted (#1364). Sync so it is
/// unit-testable off the runtime.
fn log_window_closed(path: &Path) {
    tracing::info!(
        path = %path.display(),
        "worktrees close: window closed, no removal"
    );
}

/// The phase-1 safety report the extension reads to decide whether to prompt.
/// `removable && risks.is_empty()` → proceed with **no** dialog; any `risks`
/// entry → show a modal confirm listing them.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct SafetyReport {
    /// Whether the target is a deletable (linked) worktree at all — `false` for
    /// the main working tree, which the daemon never removes.
    removable: bool,
    /// Whether the target is the repository's main working tree.
    is_main: bool,
    /// Whether a live VS Code window currently has the target open.
    open: bool,
    /// The owning window's key, when `open` (the first, for the wait/close).
    #[serde(skip_serializing_if = "Option::is_none")]
    window_key: Option<String>,
    /// How many workspace folders the owning window has — so the extension can
    /// warn "this window has N folders open; all will close" (failure mode #10).
    window_folder_count: usize,
    /// Conditions that would lose data on removal; a non-empty list forces a
    /// confirm dialog.
    risks: Vec<Note>,
    /// Non-blocking context shown for awareness (e.g. unpushed commits that
    /// survive because the branch is kept).
    info: Vec<Note>,
}

/// The git-only half of the safety check, before the registry's open-window
/// facts are folded in. Pure disk I/O; computed on a blocking thread.
#[derive(Debug, Clone, PartialEq, Eq)]
struct GitSafety {
    is_main: bool,
    removable: bool,
    risks: Vec<Note>,
    info: Vec<Note>,
}

// --- Rebase op (#1415) -------------------------------------------------------

/// The `rebase` op payload: batch-rebase worktrees onto their repository's remote
/// default branch. Two-phase like [`MergeQueueRequest`], keyed off `confirmed`,
/// and likewise a **single batched** op over `paths` — which is what buys the
/// fetch-once-per-repository contract (ADR-0055 §2), since the engine can only
/// group by repository if it sees the whole selection at once.
#[derive(Debug, Clone, Deserialize)]
struct RebaseRequest {
    /// Absolute paths of the selected worktree folders.
    paths: Vec<PathBuf>,
    /// The requesting window's key — carried for the audit line, as `close` and
    /// `merge-queue` carry theirs.
    #[serde(default)]
    requester_key: Option<String>,
    /// Phase 1: plan and report only, never rebase.
    #[serde(default)]
    check: bool,
    /// Phase 2: rebase the (re-validated) pending worktrees.
    #[serde(default)]
    confirmed: bool,
    /// Leave a conflicting worktree mid-rebase instead of aborting it. The tree
    /// view sends `true` — resolving a conflict in place is the point of #1415 —
    /// but it stays a client choice, and defaults to the engine's conservative
    /// abort so an older or scripted client gets the pre-#1415 behaviour.
    #[serde(default)]
    keep_conflicts: bool,
    /// Stash uncommitted changes around each rebase rather than skipping a dirty
    /// worktree. Not surfaced by the tree view; here so a socket client can ask.
    #[serde(default)]
    autostash: bool,
    /// Rebase onto this ref instead of the remote default branch.
    #[serde(default)]
    onto: Option<String>,
}

impl RebaseRequest {
    /// The engine options this request selects, with `git` already resolved.
    fn options(&self, git_bin: PathBuf) -> worktree_rebase::RebaseOptions {
        worktree_rebase::RebaseOptions {
            onto: self.onto.clone(),
            autostash: self.autostash,
            // The daemon never uses the engine's own dry-run flag: phase 1 *is*
            // the dry run, and it is `plan` (never `execute`) that runs for it.
            dry_run: false,
            keep_conflicts: self.keep_conflicts,
            git_bin: Some(git_bin),
        }
    }
}

/// Runs [`worktree_rebase::plan`] on a blocking thread: it shells out to
/// `git fetch` once per repository and walks each worktree's object database, so
/// it must never run on an async worker.
async fn plan_rebase(
    selection: &Selection,
    opts: &worktree_rebase::RebaseOptions,
) -> Result<worktree_rebase::Plan> {
    let selection = selection.clone();
    let opts = opts.clone();
    tokio::task::spawn_blocking(move || worktree_rebase::plan(&selection, &opts))
        .await
        .map_err(|e| anyhow!("rebase planning task panicked: {e}"))
        .and_then(|inner| inner)
}

/// Builds a `rebase` reply. Both phases share one shape — the per-repo fetch
/// outcomes and the per-worktree results — because phase 1's report and phase 2's
/// result differ only in which [`RebaseResult`](worktree_rebase::RebaseResult)
/// variants appear, and a client that can render one can render the other.
fn rebase_reply(
    fetches: &[worktree_rebase::FetchOutcome],
    worktrees: &[worktree_rebase::WorktreeOutcome],
) -> Value {
    json!({ "fetches": fetches, "worktrees": worktrees })
}

/// Emits the phase-1 audit line for a `rebase` plan (ADR-0049 §6's precedent, as
/// applied by [`log_merge_check`]): who asked, how many worktrees were named, and
/// how many the classifier found actually pending.
fn log_rebase_check(req: &RebaseRequest, plan: &worktree_rebase::Plan) {
    let pending = plan
        .worktrees
        .iter()
        .filter(|w| matches!(w.result, worktree_rebase::RebaseResult::WouldRebase { .. }))
        .count();
    let failed_fetches = plan.fetches.iter().filter(|f| !f.ok).count();
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        requested = req.paths.len(),
        pending,
        fetches = plan.fetches.len(),
        failed_fetches,
        "rebase check"
    );
}

/// Emits the phase-2 audit line for a `rebase` execute: the history-rewriting
/// outcome, counted by kind. A left-in-place conflict is counted separately from
/// an aborted one — it is the case that leaves a worktree needing the user.
fn log_rebase_execute(req: &RebaseRequest, outcomes: &[worktree_rebase::WorktreeOutcome]) {
    use worktree_rebase::RebaseResult;
    let mut rebased = 0;
    let mut conflicts = 0;
    let mut left_in_place = 0;
    let mut skipped = 0;
    for outcome in outcomes {
        match &outcome.result {
            RebaseResult::Rebased { .. } => rebased += 1,
            RebaseResult::Conflict {
                left_in_place: k, ..
            } => {
                conflicts += 1;
                if *k {
                    left_in_place += 1;
                }
            }
            RebaseResult::Skipped { .. } | RebaseResult::FetchFailed { .. } => skipped += 1,
            RebaseResult::UpToDate | RebaseResult::WouldRebase { .. } => {}
        }
    }
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        requested = req.paths.len(),
        rebased,
        conflicts,
        left_in_place,
        skipped,
        "rebase execute"
    );
}

// --- Push op (#1443) ---------------------------------------------------------

/// The `push` op payload: publish worktrees' branches to their upstreams,
/// force-pushing with a lease where history was rewritten. Two-phase like
/// [`RebaseRequest`], keyed off `confirmed`, and likewise a **single batched** op
/// over `paths` so the reply is one per-worktree summary rather than N independent
/// results.
///
/// Deliberately has **no** force knob. There is no field a client can set to escape
/// the lease, and none to reach a remote other than the branch's own upstream —
/// both by design (ADR-0061 §2).
#[derive(Debug, Clone, Deserialize)]
struct PushRequest {
    /// Absolute paths of the selected worktree folders.
    paths: Vec<PathBuf>,
    /// The requesting window's key — carried for the audit line, as `close`,
    /// `merge-queue` and `rebase` carry theirs.
    #[serde(default)]
    requester_key: Option<String>,
    /// Phase 1: classify and report only, never push.
    #[serde(default)]
    check: bool,
    /// Phase 2: publish the (re-validated) pending worktrees.
    #[serde(default)]
    confirmed: bool,
}

/// Runs [`worktree_push::plan`] on a blocking thread: it walks each worktree's
/// object database, so it must never run on an async worker. Unlike
/// [`plan_rebase`] it needs no `git` binary — planning a push contacts no remote.
async fn plan_push(selection: &Selection) -> Result<worktree_push::Plan> {
    let selection = selection.clone();
    tokio::task::spawn_blocking(move || worktree_push::plan(&selection))
        .await
        .map_err(|e| anyhow!("push planning task panicked: {e}"))
        .and_then(|inner| inner)
}

/// Builds a `push` reply. Both phases share one shape — the per-worktree results —
/// because phase 1's report and phase 2's result differ only in which
/// [`PushResult`](worktree_push::PushResult) variants appear, and a client that can
/// render one can render the other.
///
/// There is no `fetches` field (the one shape difference from `rebase`): a push
/// plan contacts no remote, so there is nothing per-repository to report.
fn push_reply(worktrees: &[worktree_push::WorktreeOutcome]) -> Value {
    json!({ "worktrees": worktrees })
}

/// Emits the phase-1 audit line for a `push` plan: who asked, how many worktrees
/// were named, how many are pending, and — separately — how many would need the
/// lease, since that is the interesting half.
fn log_push_check(req: &PushRequest, plan: &worktree_push::Plan) {
    use worktree_push::PushResult;
    let pending = plan
        .worktrees
        .iter()
        .filter(|w| w.result.is_pending())
        .count();
    let forced = plan
        .worktrees
        .iter()
        .filter(|w| matches!(w.result, PushResult::WouldForce { .. }))
        .count();
    let skipped = plan
        .worktrees
        .iter()
        .filter(|w| matches!(w.result, PushResult::Skipped { .. }))
        .count();
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        requested = req.paths.len(),
        pending,
        forced,
        skipped,
        "push check"
    );
}

/// Emits the phase-2 audit line for a `push` execute. `forced` and `stale_rejected`
/// are broken out deliberately: the first is the count of histories this daemon
/// published a rewrite of, and the second the count of times the lease stopped it
/// from overwriting work it had not seen.
fn log_push_execute(req: &PushRequest, outcomes: &[worktree_push::WorktreeOutcome]) {
    use worktree_push::PushResult;
    let mut pushed = 0;
    let mut forced = 0;
    let mut created = 0;
    let mut rejected = 0;
    let mut stale_rejected = 0;
    for outcome in outcomes {
        match &outcome.result {
            PushResult::Pushed { forced: f } => {
                pushed += 1;
                if *f {
                    forced += 1;
                }
            }
            PushResult::Created => created += 1,
            PushResult::Rejected { stale, .. } => {
                rejected += 1;
                if *stale {
                    stale_rejected += 1;
                }
            }
            PushResult::UpToDate
            | PushResult::WouldFastForward { .. }
            | PushResult::WouldForce { .. }
            | PushResult::WouldCreate
            | PushResult::Skipped { .. } => {}
        }
    }
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        requested = req.paths.len(),
        pushed,
        forced,
        created,
        rejected,
        stale_rejected,
        "push execute"
    );
}

// --- Merge-queue op (#1401) --------------------------------------------------

/// The `merge-queue` op payload: batch-enqueue eligible worktrees' PRs into the
/// GitHub merge queue. Two-phase like [`CloseRequest`], keyed off `confirmed`, but
/// a **single batched** op over `paths` rather than one op per target.
#[derive(Debug, Clone, Deserialize)]
struct MergeQueueRequest {
    /// Absolute paths of the selected worktree folders.
    paths: Vec<PathBuf>,
    /// The requesting window's key — carried for parity with `close` and future
    /// per-window routing; unused today.
    #[serde(default)]
    requester_key: Option<String>,
    /// Phase 1: report eligibility only, never enqueue.
    #[serde(default)]
    check: bool,
    /// Phase 2: enqueue the (re-validated) eligible PRs.
    #[serde(default)]
    confirmed: bool,
}

/// One enqueue-eligible worktree in an [`EligibilityReport`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct PrRef {
    /// The worktree folder.
    path: String,
    /// The open PR number.
    number: u64,
    /// The PR's web URL.
    url: String,
    /// The branch the PR heads.
    branch: String,
}

impl From<&Eligible> for PrRef {
    fn from(e: &Eligible) -> Self {
        Self {
            path: e.path.to_string_lossy().to_string(),
            number: e.number,
            url: e.url.clone(),
            branch: e.branch.clone(),
        }
    }
}

/// One skipped worktree: which, and why — a machine `kind` slug plus a
/// human-readable `detail`, mirroring [`Note`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct Skip {
    path: String,
    kind: String,
    detail: String,
}

impl Skip {
    fn new(path: &Path, kind: &str, detail: impl Into<String>) -> Self {
        Self {
            path: path.to_string_lossy().to_string(),
            kind: kind.to_string(),
            detail: detail.into(),
        }
    }
}

/// The phase-1 reply: which selected worktrees are enqueue-eligible and which are
/// skipped-with-reason. The extension confirms once over the whole set, then sends
/// the phase-2 execute.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct EligibilityReport {
    eligible: Vec<PrRef>,
    skipped: Vec<Skip>,
}

/// One PR successfully in the queue after phase 2.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct QueuedPr {
    path: String,
    number: u64,
    /// True when the PR was already in the queue — an idempotent no-op, reported as
    /// success. Omitted (false) on the wire for the common freshly-queued case.
    #[serde(skip_serializing_if = "is_false")]
    already_queued: bool,
}

/// One PR the enqueue mutation rejected (merge queue disabled, not mergeable,
/// insufficient permissions, …).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct EnqueueFailure {
    path: String,
    number: u64,
    error: String,
}

/// The phase-2 reply: the enqueue outcome for the selected worktrees. `skipped` is
/// the re-validated skip set (a worktree that became ineligible between phases).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
struct EnqueueResult {
    queued: Vec<QueuedPr>,
    skipped: Vec<Skip>,
    failed: Vec<EnqueueFailure>,
}

/// A worktree that cleared the local (git-only) gates 1–3, carrying what the
/// network step needs to resolve its PR.
#[derive(Debug)]
struct LocalOk {
    path: PathBuf,
    target: PrTarget,
    head_sha: String,
}

/// A worktree that cleared **every** gate and is ready to enqueue.
#[derive(Debug)]
struct Eligible {
    path: PathBuf,
    number: u64,
    url: String,
    branch: String,
    /// The PR's GraphQL node id — the `enqueuePullRequest` input.
    pr_id: String,
    /// Already in the queue ⇒ phase 2 skips the mutation and reports success.
    already_queued: bool,
}

/// Evaluates the **local** (git-only) merge-queue gates for one worktree — clean
/// tree (1), a real commit (2), fully pushed (3) — and resolves the branch's
/// [`PrTarget`] for the network step. Pure disk I/O; runs on a blocking thread.
/// Returns the first failing gate as a [`Skip`] so an ineligible worktree never
/// costs a GitHub call.
fn evaluate_local(path: &Path) -> std::result::Result<LocalOk, Skip> {
    let Ok(repo) = Repository::discover(path) else {
        return Err(Skip::new(path, "not-a-repo", "not a git repository"));
    };
    // Gate 1: a clean working tree (reusing the `close` safety check's counter).
    let (dirty, untracked) = count_dirty_untracked(&repo);
    if dirty > 0 {
        return Err(Skip::new(
            path,
            "dirty",
            format!("{dirty} modified tracked file(s) — commit or stash first"),
        ));
    }
    if untracked > 0 {
        return Err(Skip::new(
            path,
            "untracked",
            format!("{untracked} untracked file(s) — commit, remove, or ignore first"),
        ));
    }
    // Gate 2: a real commit exists (a non-unborn HEAD). The deeper "commits beyond
    // base" is proven by the open PR (gate 4) + GitHub's own enqueue validation.
    let Ok(head) = repo.head() else {
        return Err(Skip::new(
            path,
            "no-commits",
            "the branch has no commits yet",
        ));
    };
    let Some(head_sha) = head.target().map(|oid| oid.to_string()) else {
        return Err(Skip::new(
            path,
            "no-commits",
            "HEAD does not resolve to a commit",
        ));
    };
    // A branch HEAD has a UTF-8 shorthand; a detached HEAD has no branch — and so
    // no branch PR to enqueue. Read before `Branch::wrap` consumes `head`.
    let Some(branch_name) = head
        .shorthand()
        .ok()
        .filter(|_| head.is_branch())
        .map(str::to_string)
    else {
        return Err(Skip::new(
            path,
            "detached",
            "HEAD is detached — no branch to enqueue",
        ));
    };
    let branch = git2::Branch::wrap(head);
    // Gate 3: fully pushed — an upstream exists and matches the local head.
    let Some(upstream_sha) = upstream_target(&branch) else {
        return Err(Skip::new(
            path,
            "no-upstream",
            "the branch tracks no upstream — push it first",
        ));
    };
    if upstream_sha != head_sha {
        return Err(Skip::new(
            path,
            "unpushed",
            "local commits are not on the remote yet — push first",
        ));
    }
    // Belt-and-suspenders: even with matching heads, a positive ahead count is
    // unpushed work.
    if let Some((ahead, _behind)) = upstream_ahead_behind(&repo, &branch) {
        if ahead > 0 {
            return Err(Skip::new(
                path,
                "unpushed",
                format!("{ahead} unpushed commit(s) — push first"),
            ));
        }
    }
    // Gate 4 setup: the branch's GitHub identity, so the network step can resolve
    // its PR. A non-github repo can never have a merge-queue PR.
    let Some(id) = remote_github_identity(&repo) else {
        return Err(Skip::new(
            path,
            "no-github",
            "the repository has no github.com remote",
        ));
    };
    Ok(LocalOk {
        path: path.to_path_buf(),
        target: PrTarget {
            owner: id.owner,
            name: id.name,
            branch: branch_name,
        },
        head_sha,
    })
}

/// Whether GitHub's `mergeStateStatus` says the PR cannot merge cleanly. `DIRTY`
/// (merge conflicts) and the explicit `CONFLICTING` both block enqueue; other
/// states (`BLOCKED` on a required review, `UNKNOWN` still computing, `CLEAN`) do
/// not, since the merge queue itself resolves them.
fn is_conflicting(state: Option<&str>) -> bool {
    matches!(state, Some("CONFLICTING" | "DIRTY"))
}

/// A human-readable label for a rolled-up CI verdict, for a `checks-failing` skip.
fn check_label(state: PrCheckState) -> &'static str {
    match state {
        PrCheckState::Success => "passing",
        PrCheckState::Failure => "failing",
        PrCheckState::Pending => "still running",
        PrCheckState::None => "not reported",
    }
}

/// Emits the phase-1 audit line for a `merge-queue` check (ADR-0056; the ADR-0049
/// §6 precedent): the requesting window key, how many worktrees were requested,
/// and the eligible/skipped split. Sync so it is unit-testable off the runtime —
/// and so its `tracing` field expressions are exercised under an INFO subscriber.
fn log_merge_check(req: &MergeQueueRequest, eligible: usize, skipped: usize) {
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        requested = req.paths.len(),
        eligible,
        skipped,
        "merge-queue check"
    );
}

/// Emits the phase-2 audit line for a `merge-queue` enqueue: the requesting window
/// key and the queued/failed/skipped counts. Sync, for the same reasons as
/// [`log_merge_check`].
fn log_merge_enqueue(req: &MergeQueueRequest, queued: usize, failed: usize, skipped: usize) {
    tracing::info!(
        requester = req.requester_key.as_deref().unwrap_or("-"),
        queued,
        failed,
        skipped,
        "merge-queue enqueue"
    );
}

/// Evaluates every merge-queue gate for a batch of worktree paths and partitions
/// them into the enqueue-eligible and the skipped-with-reason. **Blocking** — run
/// on a blocking thread.
///
/// Local gates 1–3 run first (per path); only survivors reach GitHub, so a dirty
/// or unpushed worktree is skipped with **zero** API calls. The survivors' PRs are
/// resolved in **one** batched `gh api graphql` call, then the network gates —
/// an open PR (4), not a draft (5), not conflicting (6), CI green (7), and the
/// remote head matching the local head — are applied. Shared by both phases: phase
/// 2 re-runs it (never trusting a phase-1 result the client sent).
fn evaluate_batch(bin: &Path, paths: &[PathBuf]) -> Result<(Vec<Eligible>, Vec<Skip>)> {
    let mut skipped = Vec::new();
    let mut locals = Vec::new();
    for path in paths {
        match evaluate_local(path) {
            Ok(ok) => locals.push(ok),
            Err(skip) => skipped.push(skip),
        }
    }
    if locals.is_empty() {
        return Ok((Vec::new(), skipped));
    }
    let targets: Vec<PrTarget> = locals.iter().map(|l| l.target.clone()).collect();
    let resolved = crate::pr_status::resolve_merge_targets(bin, &targets)?;
    let mut eligible = Vec::new();
    for local in locals {
        let Some(info) = resolved.get(&local.target) else {
            skipped.push(Skip::new(
                &local.path,
                "no-pr",
                "no open PR heads this branch",
            ));
            continue;
        };
        if info.head_oid != local.head_sha {
            skipped.push(Skip::new(
                &local.path,
                "stale",
                "the open PR's head differs from the local head — re-check",
            ));
        } else if info.is_draft {
            skipped.push(Skip::new(
                &local.path,
                "draft",
                format!("PR #{} is a draft", info.number),
            ));
        } else if is_conflicting(info.merge_state.as_deref()) {
            skipped.push(Skip::new(
                &local.path,
                "conflicting",
                format!("PR #{} has merge conflicts", info.number),
            ));
        } else if info.checks != PrCheckState::Success {
            skipped.push(Skip::new(
                &local.path,
                "checks-failing",
                format!(
                    "PR #{} checks are {}",
                    info.number,
                    check_label(info.checks)
                ),
            ));
        } else {
            eligible.push(Eligible {
                path: local.path,
                number: info.number,
                url: info.url.clone(),
                branch: local.target.branch.clone(),
                pr_id: info.pr_id.clone(),
                already_queued: info.already_queued,
            });
        }
    }
    Ok((eligible, skipped))
}

/// Enqueues each eligible PR into its repo's merge queue, sequentially.
/// **Blocking** — run on a blocking thread. An already-queued PR is reported as
/// success without a mutation; a GitHub rejection or a failed `gh` invocation
/// lands in `failed[]`, so one un-enqueuable PR never sinks the batch.
fn enqueue_eligible(bin: &Path, eligible: Vec<Eligible>) -> (Vec<QueuedPr>, Vec<EnqueueFailure>) {
    let mut queued = Vec::new();
    let mut failed = Vec::new();
    for e in eligible {
        let path = e.path.to_string_lossy().to_string();
        if e.already_queued {
            queued.push(QueuedPr {
                path,
                number: e.number,
                already_queued: true,
            });
            continue;
        }
        match crate::pr_status::enqueue_pull_request(bin, &e.pr_id) {
            Ok(EnqueueOutcome::Queued(_)) => queued.push(QueuedPr {
                path,
                number: e.number,
                already_queued: false,
            }),
            Ok(EnqueueOutcome::Rejected(msg)) => failed.push(EnqueueFailure {
                path,
                number: e.number,
                error: msg,
            }),
            Err(err) => failed.push(EnqueueFailure {
                path,
                number: e.number,
                error: format!("{err:#}"),
            }),
        }
    }
    (queued, failed)
}

/// Live windows (key, workspace-folder count) that currently have `path` open,
/// matched by canonicalized path so a symlinked or `..`-laden report still
/// joins. Disk I/O (canonicalization), so it runs on a blocking thread.
fn windows_with_path(entries: &[WindowEntry], path: &Path) -> Vec<(String, usize)> {
    let target = canonical(path);
    entries
        .iter()
        .filter(|e| e.folders.iter().any(|f| canonical(f) == target))
        .map(|e| (e.key.clone(), e.folders.len()))
        .collect()
}

/// How long the execute phase waits for a signalled window to close
/// (`unregister`) before giving up. Deliberately generous against the ~10s
/// heartbeat interval the close directive rides — a window may have just
/// heartbeated, so the directive is only picked up on the *next* one — plus the
/// window's own close/save latency. The keyed-push responsiveness upgrade
/// (#1277 fast-follow) removes this wait entirely.
const CLOSE_WAIT_TIMEOUT: Duration = Duration::from_secs(20);

/// How often the execute phase re-checks whether the signalled windows have
/// unregistered.
const CLOSE_WAIT_POLL: Duration = Duration::from_millis(250);

/// Waits up to `timeout` for every window *other than* `requester` that has
/// `path` open to unregister (close), polling the live registry every `poll`.
/// A window whose `last_seen` has already gone stale is reaped by `list()` and
/// so counts as closed. Returns an error naming the still-open windows on
/// timeout, so the caller can surface "window did not close" and leave the
/// worktree untouched (failure modes #4/#5).
async fn await_windows_closed(
    registry: &WorktreesRegistry,
    path: &Path,
    requester: Option<&str>,
    timeout: Duration,
    poll: Duration,
) -> Result<()> {
    let deadline = std::time::Instant::now() + timeout;
    loop {
        // The registry read is cheap CPU, but the path canonicalization in
        // `windows_with_path` is disk I/O — do the whole check on a blocking
        // thread, never on the async worker.
        let entries = registry.list();
        let path = path.to_path_buf();
        let requester = requester.map(str::to_string);
        let remaining: Vec<String> = tokio::task::spawn_blocking(move || {
            windows_with_path(&entries, &path)
                .into_iter()
                .map(|(k, _)| k)
                .filter(|k| requester.as_deref() != Some(k))
                .collect()
        })
        .await
        .unwrap_or_default();

        if remaining.is_empty() {
            return Ok(());
        }
        if std::time::Instant::now() >= deadline {
            bail!("window(s) did not close in time: {}", remaining.join(", "));
        }
        tokio::time::sleep(poll).await;
    }
}

/// Computes the [`GitSafety`] of a worktree at `path`: whether it is the main
/// working tree (never removable) and, for a linked worktree, what a removal
/// would lose. Best-effort per-check but the overall open must succeed — a path
/// that is not a git worktree is a hard error (we refuse to delete an unknown
/// directory). A path that no longer exists is treated as an already-removed
/// linked worktree so the idempotent execute path can proceed with no dialog.
fn git_safety(path: &Path) -> Result<GitSafety> {
    if !path.exists() {
        return Ok(GitSafety {
            is_main: false,
            removable: true,
            risks: vec![],
            info: vec![Note::new("already-removed", "worktree no longer exists")],
        });
    }
    let repo = Repository::open(path)
        .with_context(|| format!("not a git worktree: {}", path.display()))?;
    // The one structural fact deletability keys off — never the branch name.
    if !repo.is_worktree() {
        return Ok(GitSafety {
            is_main: true,
            removable: false,
            risks: vec![],
            info: vec![Note::new(
                "main-working-tree",
                "the repository's main working tree is never deleted",
            )],
        });
    }

    let mut risks = Vec::new();
    let mut info = Vec::new();

    let (dirty, untracked) = count_dirty_untracked(&repo);
    if dirty > 0 {
        risks.push(Note::new(
            "dirty",
            format!("{dirty} modified tracked file(s) would be lost"),
        ));
    }
    if untracked > 0 {
        risks.push(Note::new(
            "untracked",
            format!("{untracked} untracked file(s) would be lost"),
        ));
    }

    // An in-progress rebase/merge/cherry-pick etc. is lost on removal.
    let state = repo.state();
    if state != RepositoryState::Clean {
        risks.push(Note::new(
            "in-progress",
            format!("an in-progress {state:?} operation would be lost"),
        ));
    }

    // Commits reachable only from a detached HEAD are GC'd once the worktree —
    // and its HEAD ref — are gone. A HEAD still reachable from any ref (a branch
    // or tag) loses nothing, so it is not flagged.
    if repo.head_detached().unwrap_or(false) {
        let lost = unreachable_commit_count(&repo).unwrap_or(0);
        if lost > 0 {
            risks.push(Note::new(
                "unreachable-commits",
                format!("{lost} commit(s) on a detached HEAD will be permanently lost"),
            ));
        }
    }

    // Unpushed commits on a *named* branch survive: removal never deletes the
    // branch. Informational only — it must not block or prompt.
    if let Some(ahead) = current_branch_ahead(&repo) {
        if ahead > 0 {
            info.push(Note::new(
                "unpushed",
                format!("{ahead} unpushed commit(s) on the branch (kept — the branch survives)"),
            ));
        }
    }

    Ok(GitSafety {
        is_main: false,
        removable: true,
        risks,
        info,
    })
}

/// Counts a worktree's `(dirty tracked, untracked)` files. Tracked covers any
/// staged or unstaged modification (including conflicts and deletions);
/// untracked is `WT_NEW`. `.gitignore`d files are excluded — they are
/// regenerable and must not force a prompt — via `include_ignored(false)`, so no
/// status entry ever carries the `IGNORED` bit. A failed status read degrades to
/// `(0, 0)` rather than sinking the whole safety check.
fn count_dirty_untracked(repo: &Repository) -> (usize, usize) {
    let mut opts = StatusOptions::new();
    opts.include_untracked(true)
        .recurse_untracked_dirs(true)
        .include_ignored(false)
        .exclude_submodules(true);
    let Ok(statuses) = repo.statuses(Some(&mut opts)) else {
        return (0, 0);
    };
    // Any staged or unstaged change to a tracked path (WT_NEW is untracked, so
    // it is deliberately excluded from this mask).
    let tracked = Status::INDEX_NEW
        | Status::INDEX_MODIFIED
        | Status::INDEX_DELETED
        | Status::INDEX_RENAMED
        | Status::INDEX_TYPECHANGE
        | Status::WT_MODIFIED
        | Status::WT_DELETED
        | Status::WT_TYPECHANGE
        | Status::WT_RENAMED
        | Status::CONFLICTED;
    let mut dirty = 0;
    let mut untracked = 0;
    for entry in statuses.iter() {
        let s = entry.status();
        if s.contains(Status::WT_NEW) {
            untracked += 1;
        }
        if s.intersects(tracked) {
            dirty += 1;
        }
    }
    (dirty, untracked)
}

/// Counts commits reachable from the (detached) HEAD but from no other ref —
/// the commits git would garbage-collect once the worktree's HEAD is gone.
/// `None` if HEAD or the revwalk cannot be resolved. The literal `HEAD` ref is
/// skipped (hiding it would hide the very commits we are counting); every real
/// branch/tag/remote ref is hidden, so a tip that any branch also points at
/// yields `0` (nothing is actually lost).
fn unreachable_commit_count(repo: &Repository) -> Option<usize> {
    let head_oid = repo.head().ok()?.target()?;
    let mut walk = repo.revwalk().ok()?;
    walk.push(head_oid).ok()?;
    for reference in repo.references().ok()? {
        let Ok(reference) = reference else { continue };
        // Skip the literal HEAD ref — hiding it would hide the very commits we
        // are counting; every real branch/tag/remote ref is hidden below.
        if matches!(reference.name(), Ok("HEAD")) {
            continue;
        }
        if let Some(oid) = reference.target() {
            let _ = walk.hide(oid);
        }
    }
    Some(walk.flatten().count())
}

/// Commits the worktree's current branch is ahead of its upstream, or `None`
/// when HEAD is detached or the branch tracks no upstream. Reuses
/// [`upstream_ahead_behind`]; only the ahead count matters here (unpushed work).
fn current_branch_ahead(repo: &Repository) -> Option<usize> {
    let head = repo.head().ok()?;
    if !head.is_branch() {
        return None;
    }
    let branch = git2::Branch::wrap(head);
    upstream_ahead_behind(repo, &branch).map(|(ahead, _behind)| ahead)
}

/// Resolves the linked worktree whose working directory canonicalizes to
/// `target` to its registered name in `main_repo`. Errors when `target` is not
/// one of the repo's worktrees — the defensive guard against removing a path
/// that opened as a worktree but is not enumerated. Split out so that guard is
/// unit-testable without corrupting git's worktree admin state.
fn worktree_name_for_path(main_repo: &Repository, target: &Path) -> Result<String> {
    let names = main_repo.worktrees()?;
    names
        .iter()
        .flatten() // Result<Option<&str>, _> → Option<&str> (drop per-name errors)
        .flatten() // Option<&str> → &str (drop non-UTF-8 names)
        .find(|name| {
            main_repo
                .find_worktree(name)
                .is_ok_and(|wt| canonical(wt.path()) == target)
        })
        .map(str::to_string)
        .ok_or_else(|| {
            anyhow!(
                "worktree {} is not registered in {}",
                target.display(),
                main_repo.path().display()
            )
        })
}

/// Backoff delays between recursive-removal retries (#1315). A concurrent
/// writer — a just-closed window's language server (Metals/Bloop) or
/// `rust-analyzer`/`cargo` still flushing build artifacts into `target/` — can
/// create a file between our directory scan and its `rmdir`, making the removal
/// fail with `ENOTEMPTY` ("Directory not empty"). Each retry re-sweeps and
/// waits longer, giving the winding-down process time to quiesce. Total wait
/// ~2.75s across four retries; the window teardown the caller already waited on
/// dominates it.
const WORKTREE_RMDIR_BACKOFF: &[Duration] = &[
    Duration::from_millis(250),
    Duration::from_millis(500),
    Duration::from_secs(1),
    Duration::from_secs(1),
];

/// Whether `e` is the transient "directory re-populated under us" race we retry
/// (see [`WORKTREE_RMDIR_BACKOFF`]) rather than a hard failure (permission
/// denied, read-only filesystem) we must surface immediately. Matches the raw
/// errno — `std::io::ErrorKind::DirectoryNotEmpty` is only stable from Rust 1.83,
/// past our MSRV — including the `EEXIST`/`EBUSY` siblings libgit2 lumps in.
fn is_transient_rmdir_error(e: &std::io::Error) -> bool {
    matches!(
        e.raw_os_error(),
        Some(nix::libc::ENOTEMPTY | nix::libc::EEXIST | nix::libc::EBUSY)
    )
}

/// Recursively removes `dir`, retrying on the transient concurrent-writer race
/// (see [`is_transient_rmdir_error`]) and treating an already-absent directory
/// as success. Non-transient errors surface immediately with the original
/// message. Runs on a blocking thread (called only from [`remove_worktree`], via
/// `spawn_blocking`), so the between-retry `sleep` is fine.
fn remove_dir_all_retrying(dir: &Path) -> Result<()> {
    remove_dir_all_retrying_with(dir, WORKTREE_RMDIR_BACKOFF, || std::fs::remove_dir_all(dir))
}

/// [`remove_dir_all_retrying`] with the schedule and the removal itself injected.
/// Provoking the real race requires a concurrent writer to lose a timing window,
/// so only an injected sequence of errors can drive every branch of the loop —
/// exhausting the backoff especially — deterministically and without sleeping out
/// the production schedule.
fn remove_dir_all_retrying_with(
    dir: &Path,
    backoff: &[Duration],
    mut remove: impl FnMut() -> std::io::Result<()>,
) -> Result<()> {
    let mut backoff = backoff.iter();
    loop {
        match remove() {
            Ok(()) => return Ok(()),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),
            Err(e) => {
                if is_transient_rmdir_error(&e) {
                    if let Some(delay) = backoff.next() {
                        std::thread::sleep(*delay);
                        continue;
                    }
                }
                return Err(e).with_context(|| {
                    format!("failed to remove worktree directory {}", dir.display())
                });
            }
        }
    }
}

/// Whether `path` is a **half-removed** linked worktree: its `.git` gitlink
/// still points at an admin directory a prior failed removal already deleted.
/// libgit2's combined prune deletes the admin metadata *before* it rmdirs the
/// working tree, so a working-tree rmdir failure (#1315) leaves exactly this
/// orphan — the directory on disk with a dangling gitlink, no longer tracked by
/// git. Safe to delete outright: a live worktree's gitlink resolves (its repo
/// opens) and a normal checkout has a `.git` *directory*, so this matches
/// neither.
fn is_orphaned_worktree(path: &Path) -> bool {
    // `read_to_string` fails on a `.git` directory (a normal checkout), so only
    // a linked worktree's gitlink file gets past here.
    let Ok(contents) = std::fs::read_to_string(path.join(".git")) else {
        return false;
    };
    let Some(admin) = contents.strip_prefix("gitdir:").map(str::trim) else {
        return false;
    };
    let admin = Path::new(admin);
    // A linked-worktree admin path (`…/worktrees/<name>`) whose target is gone.
    admin.components().any(|c| c.as_os_str() == "worktrees") && !admin.exists()
}

/// The outcome of a linked-worktree removal, so the audit log can tell "actually
/// removed something" from "nothing was there" (#1403). Before this the
/// working-tree-gone-but-admin-present case returned `Ok(())` and logged a
/// `pruned` lie, leaving the row stuck in the tree view.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Removal {
    /// The admin metadata (and possibly the working tree) was actually removed.
    Pruned,
    /// Nothing was there to remove — a truly already-removed worktree.
    AlreadyGone,
}

/// Removes a **linked** worktree at `path` via `git2` (no shell — avoiding the
/// daemon-`PATH` problem the launcher fights): deletes both the checked-out
/// directory and the admin metadata. Refuses the main working tree (the
/// defensive backstop behind the UI gating) and a locked worktree (surfacing
/// "unlock first" rather than forcing past the lock). Idempotent: an
/// already-removed path is a success.
///
/// The working tree is removed **first** (retrying to absorb the
/// concurrent-writer race, #1315), and only then is the admin metadata pruned.
/// This is deliberately the reverse of libgit2's combined
/// `prune(working_tree: true)`, which deletes the admin dir first and, when the
/// working-tree rmdir then fails, leaves a **half-removed orphan** git no longer
/// tracks (and which a naive prune-retry cannot recover, since its admin gitdir
/// is already gone). Doing the directory first means a transient failure leaves
/// the worktree fully tracked and cleanly retryable; a pre-existing orphan from
/// the old ordering is detected and its leftover directory cleaned up directly.
///
/// A working directory that is *already gone* is **not** blindly treated as a
/// no-op: a half-removal from outside the daemon (a manual `rm -rf`, an OS
/// cleanup) can leave the main repo's `.git/worktrees/<name>/` admin entry behind
/// (git marks it `prunable` and the tree view keeps showing the row). That path
/// hands off to [`prune_orphaned_admin`], which locates the owning main repo from
/// `windows` (or the path's ancestors) and prunes just that entry; only when no
/// repo still tracks the path is it reported [`Removal::AlreadyGone`] (#1403).
fn remove_worktree(path: &Path, windows: &[WindowEntry]) -> Result<Removal> {
    if !path.exists() {
        return prune_orphaned_admin(path, &candidate_main_repos(path, windows));
    }
    let repo = match Repository::open(path) {
        Ok(repo) => repo,
        // Admin metadata already gone (a prior failed removal); git no longer
        // tracks this path, so no prune applies — just delete the leftover.
        Err(_) if is_orphaned_worktree(path) => {
            remove_dir_all_retrying(path)?;
            return Ok(Removal::Pruned);
        }
        Err(e) => return Err(e).context(format!("not a git worktree: {}", path.display())),
    };
    if !repo.is_worktree() {
        bail!(
            "refusing to delete the main working tree: {}",
            path.display()
        );
    }
    // The Worktree handle lives on the *main* repo (the common dir's parent),
    // keyed by name; find it by matching the target path.
    let commondir = canonical(repo.commondir());
    let main_root = commondir
        .parent()
        .ok_or_else(|| anyhow!("no repository root for {}", path.display()))?
        .to_path_buf();
    // Drop the worktree-scoped handle before we delete its directory.
    drop(repo);
    let main_repo = Repository::open(&main_root)
        .with_context(|| format!("failed to open repository at {}", main_root.display()))?;
    let name = worktree_name_for_path(&main_repo, &canonical(path))?;
    let worktree = main_repo.find_worktree(&name)?;

    // Never silently force past a lock (failure mode #6).
    if let WorktreeLockStatus::Locked(reason) = worktree.is_locked()? {
        let because = reason.map(|r| format!(" ({r})")).unwrap_or_default();
        bail!("worktree is locked{because}; unlock it first (git worktree unlock)");
    }

    // Delete the checked-out directory ourselves, retrying past the
    // concurrent-writer race (#1315).
    remove_dir_all_retrying(path)?;

    // The directory is gone; prune only the admin metadata. working_tree(false)
    // keeps git2 from re-attempting (and failing on) the now-absent directory;
    // valid(true) prunes even though the worktree was valid; locked stays false,
    // so a lock (re-checked above) is never forced.
    let mut opts = git2::WorktreePruneOptions::new();
    opts.valid(true).working_tree(false);
    worktree
        .prune(Some(&mut opts))
        .with_context(|| format!("failed to prune worktree metadata for {}", path.display()))?;
    Ok(Removal::Pruned)
}

/// The main-repo roots to search when pruning an orphaned worktree whose working
/// directory is already gone (#1403). There is no on-disk breadcrumb from the
/// vanished working tree back to its repo — the `.git` gitlink lived *inside* the
/// deleted directory — so the owner has to be found by enumerating candidates:
///
/// - **the path's own ancestors**, covering a worktree nested under its repo
///   (e.g. `<repo>/.claude/worktrees/<name>`): an existing ancestor that opens as
///   the *main* checkout is the owner. `Repository::open` (not `discover`) so only
///   a real repo-root ancestor matches, never an intermediate directory.
/// - **every main repo the live `windows` resolve to**, covering an external
///   worktree that shares no ancestor with its repo. These are the same repos
///   whose `worktrees()` enumeration produced the orphaned row, so this is
///   guaranteed to include the owner whenever the UI could show a row to close.
///
/// Deduped, order-preserving (ancestors first).
fn candidate_main_repos(path: &Path, windows: &[WindowEntry]) -> Vec<PathBuf> {
    let mut roots: Vec<PathBuf> = Vec::new();
    let mut push = |root: PathBuf| {
        if !roots.contains(&root) {
            roots.push(root);
        }
    };
    // Skip `path` itself (gone) via `skip(1)`.
    for ancestor in path.ancestors().skip(1) {
        if let Ok(repo) = Repository::open(ancestor) {
            if !repo.is_worktree() {
                if let Some(root) = canonical(repo.commondir()).parent() {
                    push(root.to_path_buf());
                }
            }
        }
    }
    for folder in windows.iter().flat_map(|w| &w.folders) {
        if let Ok(repo) = Repository::discover(folder) {
            if let Some(root) = canonical(repo.commondir()).parent() {
                push(root.to_path_buf());
            }
        }
    }
    roots
}

/// Prunes the leftover `.git/worktrees/<name>/` admin metadata of a worktree
/// whose working directory is already gone (#1403). Searches
/// `candidate_main_repos` for the main repo that still tracks a worktree
/// registered at `path`, prunes just that entry's metadata (`working_tree(false)`
/// — the checkout is already gone), and returns [`Removal::Pruned`]. When no
/// candidate still tracks the path it is truly already-removed:
/// [`Removal::AlreadyGone`]. A locked entry is refused, mirroring
/// [`remove_worktree`]'s live path, rather than forced past.
fn prune_orphaned_admin(path: &Path, candidate_main_repos: &[PathBuf]) -> Result<Removal> {
    let target = canonical(path);
    for root in candidate_main_repos {
        let Ok(main_repo) = Repository::open(root) else {
            continue;
        };
        // Only the main checkout carries the `.git/worktrees/<name>/` admin dir.
        if main_repo.is_worktree() {
            continue;
        }
        // Not the owner (or the entry is already pruned) — keep looking.
        let Ok(name) = worktree_name_for_path(&main_repo, &target) else {
            continue;
        };
        let worktree = main_repo.find_worktree(&name)?;
        if let WorktreeLockStatus::Locked(reason) = worktree.is_locked()? {
            let because = reason.map(|r| format!(" ({r})")).unwrap_or_default();
            bail!("worktree is locked{because}; unlock it first (git worktree unlock)");
        }
        let mut opts = git2::WorktreePruneOptions::new();
        opts.valid(true).working_tree(false);
        worktree.prune(Some(&mut opts)).with_context(|| {
            format!(
                "failed to prune orphaned worktree metadata for {}",
                path.display()
            )
        })?;
        return Ok(Removal::Pruned);
    }
    Ok(Removal::AlreadyGone)
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;
    use crate::test_support::shim::{
        retry_on_etxtbsy, retry_on_etxtbsy_async, shim_lock, write_exec_script,
    };
    use std::sync::MutexGuard;

    fn register_payload(key: &str, repo: Option<&str>, folder: &str) -> Value {
        json!({
            "key": key,
            "folders": [folder],
            "repo": repo,
            "title": format!("{key}-title"),
            "pid": 1234,
        })
    }

    /// Pulls the `windows` array out of a `list`/`status` payload.
    fn windows_of(payload: &Value) -> &Vec<Value> {
        payload
            .get("windows")
            .and_then(Value::as_array)
            .expect("windows array")
    }

    #[tokio::test]
    async fn name_and_unknown_op() {
        let svc = WorktreesService::new();
        assert_eq!(svc.name(), "worktrees");
        assert!(svc.handle("frobnicate", Value::Null).await.is_err());
    }

    #[tokio::test]
    async fn handle_routes_ops_and_shapes_payloads() {
        let svc = WorktreesService::new();
        // Empty to start.
        let payload = svc.handle("list", Value::Null).await.unwrap();
        assert_eq!(payload, json!({ "windows": [] }));

        // register → { ok: true }, then it shows up in list.
        let reply = svc
            .handle("register", register_payload("w1", Some("repo-a"), "/tmp/a"))
            .await
            .unwrap();
        assert_eq!(reply, json!({ "ok": true }));
        let windows = windows_of(&svc.handle("list", Value::Null).await.unwrap()).clone();
        assert_eq!(windows.len(), 1);
        assert_eq!(windows[0].get("key").and_then(Value::as_str), Some("w1"));
        assert!(windows[0].get("last_seen").is_some());

        // heartbeat known/unknown.
        let known = svc
            .handle("heartbeat", json!({ "key": "w1" }))
            .await
            .unwrap();
        assert_eq!(known, json!({ "known": true }));
        let unknown = svc
            .handle("heartbeat", json!({ "key": "nope" }))
            .await
            .unwrap();
        assert_eq!(unknown, json!({ "known": false }));

        // reload signals a live window and reports one it does not know.
        let reloaded = svc
            .handle("reload", json!({ "target_keys": ["w1", "nope"] }))
            .await
            .unwrap();
        assert_eq!(
            reloaded,
            json!({ "requested": 2, "signalled": 1, "unknown": ["nope"] })
        );
        assert!(svc.registry.take_reload_pending("w1"));

        // unregister removes, then repeats as a no-op success.
        let gone = svc
            .handle("unregister", json!({ "key": "w1" }))
            .await
            .unwrap();
        assert_eq!(gone, json!({ "removed": true }));
        let again = svc
            .handle("unregister", json!({ "key": "w1" }))
            .await
            .unwrap();
        assert_eq!(again, json!({ "removed": false }));
    }

    // --- Reposition op (#1407) ------------------------------------------------

    /// A window backend over an in-memory window table that **actually applies**
    /// writes, so the adapter's own responsibilities — key resolution, the undo
    /// store, the reply shape — are testable with no `unsafe`, no real windows, and
    /// no Accessibility grant. The planner/matcher itself is covered by
    /// `geometry`'s own tests.
    ///
    /// Applying the writes is what makes a reposition-then-undo round trip mean
    /// anything: against a fixed table the restore would find every window already
    /// in its wanted position and correctly report `unchanged`.
    #[derive(Clone)]
    struct StubBackend {
        trusted: bool,
        /// One application's windows. `Arc` so every clone the factory hands out —
        /// and every op in a test — shares the same mutating table.
        windows: Arc<Mutex<Vec<geometry::OsWindow>>>,
        /// Every frame written, in order.
        writes: Arc<Mutex<Vec<geometry::Frame>>>,
    }

    impl StubBackend {
        /// One application (pid 900) with two default-format VS Code windows, and
        /// two ext-host pids (11, 12) mapping onto it.
        fn new(trusted: bool) -> Self {
            let window = |title: &str, x: f64, width: f64| geometry::OsWindow {
                title: title.to_string(),
                frame: geometry::Frame {
                    x,
                    y: 0.0,
                    width,
                    height: 600.0,
                },
                minimized: false,
                fullscreen: false,
                standard: true,
                focused: false,
            };
            Self {
                trusted,
                windows: Arc::new(Mutex::new(vec![
                    window("plan.md — ref-tree", 0.0, 800.0),
                    window("main.rs — other-tree", 900.0, 500.0),
                ])),
                writes: Arc::new(Mutex::new(Vec::new())),
            }
        }

        fn writes(&self) -> Vec<geometry::Frame> {
            self.writes
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .clone()
        }

        /// The frame a window currently occupies, after any applied writes.
        fn frame_of(&self, index: usize) -> geometry::Frame {
            self.windows.lock().unwrap_or_else(PoisonError::into_inner)[index].frame
        }

        /// A factory for the `*_with` seams, sharing this stub's table and recorder.
        fn factory(&self) -> impl FnOnce() -> Self + Send + 'static {
            let clone = self.clone();
            move || clone
        }
    }

    impl geometry::WindowBackend for StubBackend {
        fn trusted(&self) -> bool {
            self.trusted
        }

        fn app_pids(&self, pids: &[u32]) -> HashMap<u32, u32> {
            pids.iter()
                .filter(|p| **p == 11 || **p == 12)
                .map(|p| (*p, 900))
                .collect()
        }

        fn windows(&self, app_pid: u32) -> Result<Vec<geometry::OsWindow>, String> {
            if app_pid != 900 {
                return Ok(Vec::new());
            }
            Ok(self
                .windows
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .clone())
        }

        fn set_frame(
            &self,
            id: geometry::WindowId,
            frame: geometry::Frame,
        ) -> Result<geometry::Frame, String> {
            self.writes
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .push(frame);
            let mut windows = self.windows.lock().unwrap_or_else(PoisonError::into_inner);
            let window = windows
                .get_mut(id.index)
                .ok_or_else(|| format!("no window at index {}", id.index))?;
            window.frame = frame;
            Ok(frame)
        }
    }

    /// Registers a window whose reported title is `title` and pid is `pid`, i.e.
    /// one the stub backend can resolve to an OS window.
    fn register_window(svc: &WorktreesService, key: &str, title: &str, pid: u32) {
        svc.registry.register(
            serde_json::from_value(json!({
                "key": key,
                "folders": [format!("/tmp/{key}")],
                "title": title,
                "pid": pid,
            }))
            .expect("valid register payload"),
        );
    }

    #[tokio::test]
    async fn reposition_requires_a_resolvable_reference() {
        let svc = WorktreesService::new();
        // A missing, blank, or unknown reference key is a hard error: with no
        // reference there is no geometry to copy, so the request is meaningless.
        assert!(svc.handle("reposition", json!({})).await.is_err());
        assert!(svc
            .handle("reposition", json!({ "reference_key": "  " }))
            .await
            .is_err());
        assert!(svc
            .handle("reposition", json!({ "reference_key": "ghost" }))
            .await
            .is_err());
    }

    #[tokio::test]
    async fn reposition_moves_targets_and_records_an_undo() {
        let svc = WorktreesService::new();
        register_window(&svc, "ref", "ref-tree", 11);
        register_window(&svc, "other", "other-tree", 12);
        let backend = StubBackend::new(true);

        let reply = svc
            .reposition_with(
                serde_json::from_value(json!({
                    "reference_key": "ref",
                    "target_keys": ["other"],
                }))
                .unwrap(),
                backend.factory(),
            )
            .await
            .unwrap();

        assert_eq!(reply["trusted"], json!(true));
        assert_eq!(reply["moved"], json!(1));
        assert_eq!(reply["skipped"], json!(0));
        assert_eq!(reply["undoable"], json!(true));
        assert_eq!(reply["reference"]["title"], json!("ref-tree"));
        assert_eq!(reply["results"][0]["key"], json!("other"));
        assert_eq!(reply["results"][0]["outcome"], json!("moved"));
        // Written the reference's own frame, read from the stub's window table.
        assert_eq!(backend.writes().len(), 1);
        assert_eq!(
            backend.writes()[0],
            backend.frame_of(0),
            "wrote the reference window's own frame"
        );
        assert_eq!(
            backend.frame_of(1),
            backend.frame_of(0),
            "the target now occupies the reference's frame"
        );

        // Undo puts it back where it was — the same backend, so it sees the window
        // where the move left it — and consumes the record, so a second undo has
        // nothing left to replay onto a layout the user may have since redone.
        let undone = svc.reposition_undo_with(backend.factory()).await.unwrap();
        assert_eq!(undone["moved"], json!(1));
        assert_eq!(undone["results"][0]["outcome"], json!("moved"));
        assert!(undone.get("reference").is_none(), "undo has no reference");
        assert_eq!(
            backend.frame_of(1),
            geometry::Frame {
                x: 900.0,
                y: 0.0,
                width: 500.0,
                height: 600.0,
            },
            "restored to exactly the pre-move frame"
        );

        let again = svc.reposition_undo_with(backend.factory()).await.unwrap();
        assert_eq!(
            again,
            json!({ "trusted": true, "results": [], "moved": 0, "skipped": 0 })
        );
    }

    #[tokio::test]
    async fn a_reposition_dry_run_writes_nothing_and_leaves_no_undo() {
        let svc = WorktreesService::new();
        register_window(&svc, "ref", "ref-tree", 11);
        register_window(&svc, "other", "other-tree", 12);
        let backend = StubBackend::new(true);

        let reply = svc
            .reposition_with(
                serde_json::from_value(json!({
                    "reference_key": "ref",
                    "target_keys": ["other"],
                    "check": true,
                }))
                .unwrap(),
                backend.factory(),
            )
            .await
            .unwrap();

        assert_eq!(reply["results"][0]["outcome"], json!("would-move"));
        assert!(
            reply.get("undoable").is_none(),
            "a dry run leaves nothing to undo"
        );
        assert!(
            backend.writes().is_empty(),
            "a dry run must not touch a window"
        );
    }

    #[tokio::test]
    async fn reposition_reports_a_missing_permission_as_data() {
        let svc = WorktreesService::new();
        register_window(&svc, "ref", "ref-tree", 11);
        register_window(&svc, "other", "other-tree", 12);
        let backend = StubBackend::new(false);

        let reply = svc
            .reposition_with(
                serde_json::from_value(json!({
                    "reference_key": "ref",
                    "target_keys": ["other"],
                }))
                .unwrap(),
                backend.factory(),
            )
            .await
            .unwrap();

        // Not an error: the client branches on `trusted` to offer the user a link
        // to the Accessibility settings pane.
        assert_eq!(reply["trusted"], json!(false));
        assert_eq!(reply["moved"], json!(0));
        assert!(backend.writes().is_empty());
    }

    #[tokio::test]
    async fn a_stale_target_key_is_skipped_not_fatal() {
        let svc = WorktreesService::new();
        register_window(&svc, "ref", "ref-tree", 11);
        register_window(&svc, "other", "other-tree", 12);
        let backend = StubBackend::new(true);

        let reply = svc
            .reposition_with(
                serde_json::from_value(json!({
                    "reference_key": "ref",
                    // A window that closed since the tree row was rendered, the
                    // reference itself, and a real target.
                    "target_keys": ["closed-since", "ref", "other"],
                }))
                .unwrap(),
                backend.factory(),
            )
            .await
            .unwrap();

        let outcomes: Vec<&str> = reply["results"]
            .as_array()
            .unwrap()
            .iter()
            .map(|r| r["outcome"].as_str().unwrap())
            .collect();
        assert_eq!(outcomes, vec!["no-window", "reference", "moved"]);
        assert_eq!(reply["moved"], json!(1));
        assert_eq!(reply["skipped"], json!(2));
    }

    #[tokio::test]
    async fn a_blocked_reposition_carries_the_reason_and_records_no_undo() {
        let svc = WorktreesService::new();
        // Two windows share a root name, so the *reference* cannot be resolved and
        // the whole batch is refused before any target is attempted.
        register_window(&svc, "ref", "twin", 11);
        register_window(&svc, "other", "other-tree", 12);
        // The window table is behind an `Arc<Mutex<…>>`, so retitling it needs no
        // `mut` binding — and the same shared table backs the factory's clone.
        let backend = StubBackend::new(true);
        {
            let mut windows = backend
                .windows
                .lock()
                .unwrap_or_else(PoisonError::into_inner);
            windows[0].title = "a.rs — twin".to_string();
            windows[1].title = "b.rs — twin".to_string();
        }

        let reply = svc
            .reposition_with(
                serde_json::from_value(json!({
                    "reference_key": "ref",
                    "target_keys": ["other"],
                }))
                .unwrap(),
                backend.factory(),
            )
            .await
            .unwrap();

        assert_eq!(reply["trusted"], json!(true));
        assert_eq!(reply["blocked"]["reason"], json!("reference-ambiguous"));
        assert!(
            reply["blocked"]["detail"]
                .as_str()
                .is_some_and(|d| d.contains("twin")),
            "the reason should name the ambiguous title: {reply}"
        );
        assert_eq!(reply["results"], json!([]), "no target is attempted");
        assert!(reply.get("undoable").is_none());
        assert!(backend.writes().is_empty());

        // And nothing was recorded, so a following undo has nothing to replay.
        let undone = svc
            .reposition_undo_with(StubBackend::new(true).factory())
            .await
            .unwrap();
        assert_eq!(undone["moved"], json!(0));
    }

    #[tokio::test]
    async fn reposition_undo_is_a_no_op_with_nothing_recorded() {
        let svc = WorktreesService::new();
        let reply = svc.handle("reposition-undo", Value::Null).await.unwrap();
        assert_eq!(reply["moved"], json!(0));
        assert_eq!(reply["results"], json!([]));
    }

    #[test]
    fn outcome_kinds_joins_slugs_and_dashes_an_empty_batch() {
        let empty = geometry::RepositionReport {
            trusted: true,
            blocked: None,
            reference: None,
            results: Vec::new(),
            undo: Vec::new(),
        };
        assert_eq!(outcome_kinds(&empty), "-");
    }

    #[tokio::test]
    async fn handle_rejects_missing_or_empty_key() {
        let svc = WorktreesService::new();
        // register validates a present, non-blank key.
        assert!(svc.handle("register", json!({})).await.is_err());
        assert!(svc
            .handle("register", json!({ "key": "  " }))
            .await
            .is_err());
        // heartbeat/unregister require the key via `require_str`.
        assert!(svc.handle("heartbeat", json!({})).await.is_err());
        assert!(svc.handle("unregister", json!({})).await.is_err());
    }

    #[test]
    fn display_name_prefers_repo_then_folder_basename() {
        let base = WindowEntry {
            key: "k".to_string(),
            folders: vec![PathBuf::from("/home/me/project")],
            repo: Some("my-repo".to_string()),
            title: None,
            pid: None,
            last_seen: Utc::now(),
        };
        assert_eq!(display_name(&base), "my-repo");

        let no_repo = WindowEntry {
            repo: None,
            ..base.clone()
        };
        assert_eq!(display_name(&no_repo), "project");

        let nothing = WindowEntry {
            repo: None,
            folders: vec![],
            ..base.clone()
        };
        assert_eq!(display_name(&nothing), "(no folder)");

        // A folder with no basename (the filesystem root) falls back to its
        // displayed path rather than panicking or yielding an empty name.
        let rootish = WindowEntry {
            repo: None,
            folders: vec![PathBuf::from("/")],
            ..base
        };
        assert_eq!(display_name(&rootish), "/");
    }

    #[test]
    fn window_menu_items_merge_stats_and_focus_into_one_clickable_line() {
        let now = Utc::now();
        let entries = vec![
            // A folderless window has nothing to focus, so it stays a plain
            // Label; a title equal to the name collapses to just the name. It
            // leads the list so the focus-action lookup below is exercised
            // against a leading non-Action item it has to skip.
            WindowEntry {
                key: "k2".to_string(),
                folders: vec![],
                repo: Some("solo".to_string()),
                title: Some("solo".to_string()),
                pid: None,
                last_seen: now,
            },
            // A folder-bearing, non-repo window: one clickable Action whose label
            // is the stats line ("name · title", since /tmp is not a git repo).
            WindowEntry {
                key: "k1".to_string(),
                folders: vec![PathBuf::from("/tmp/a")],
                repo: Some("repo".to_string()),
                title: Some("a branch".to_string()),
                pid: None,
                last_seen: now,
            },
        ];
        let items = window_menu_items(&entries);
        // Exactly one item per window — no duplicate label, no separator.
        assert_eq!(items.len(), 2);
        assert!(!items.iter().any(|i| matches!(i, MenuItem::Separator)));

        // The folder-bearing window is a single clickable action carrying the
        // stats label (the old label + Focus action, merged).
        let action = items
            .iter()
            .find_map(|i| match i {
                MenuItem::Action(a) => Some(a),
                _ => None,
            })
            .expect("a focus action");
        assert_eq!(action.id, "focus:k1");
        assert_eq!(action.label, "repo · a branch");

        // The folderless window is a non-clickable label (not "solo · solo").
        let labels: Vec<&str> = items
            .iter()
            .filter_map(|i| match i {
                MenuItem::Label(t) => Some(t.as_str()),
                _ => None,
            })
            .collect();
        assert_eq!(labels, vec!["solo"]);
    }

    #[tokio::test]
    async fn menu_and_status_shapes() {
        let svc = WorktreesService::new();
        // Empty.
        let menu = svc.menu();
        assert_eq!(menu.title, "Worktrees");
        assert!(matches!(
            menu.items.first(),
            Some(MenuItem::Label(text)) if text == "No open windows"
        ));
        let status = svc.status().await;
        assert_eq!(status.name, "worktrees");
        assert!(status.healthy);
        assert_eq!(status.summary, "0 window(s) across 0 repo(s)");

        // Two folder-bearing windows in the same repo, plus one folderless
        // window that shares the repo but has nothing for `code` to open.
        svc.handle("register", register_payload("w1", Some("repo-a"), "/tmp/a"))
            .await
            .unwrap();
        svc.handle("register", register_payload("w2", Some("repo-a"), "/tmp/b"))
            .await
            .unwrap();
        svc.handle(
            "register",
            json!({ "key": "w3", "repo": "repo-a", "folders": [] }),
        )
        .await
        .unwrap();
        let status = svc.status().await;
        assert_eq!(status.summary, "3 window(s) across 1 repo(s)");

        let menu = svc.menu();
        // One line per window — no separator, no duplicate label.
        assert_eq!(menu.items.len(), 3);
        assert!(!menu.items.iter().any(|i| matches!(i, MenuItem::Separator)));
        let action_ids: Vec<&str> = menu
            .items
            .iter()
            .filter_map(|i| match i {
                MenuItem::Action(a) => Some(a.id.as_str()),
                _ => None,
            })
            .collect();
        // The two folder-bearing windows are clickable; the folderless one is a
        // plain Label, so it never yields a focus action.
        assert!(action_ids.contains(&"focus:w1"));
        assert!(action_ids.contains(&"focus:w2"));
        assert!(!action_ids.contains(&"focus:w3"));
    }

    #[test]
    fn start_menu_refresh_is_a_noop_outside_a_runtime() {
        // With no tokio runtime, the background task is never spawned, so the
        // bare service keeps computing `menu()` inline (what the tests rely on).
        let svc = WorktreesService::new();
        svc.start_menu_refresh();
        assert!(svc.refresh.lock().unwrap().is_none());
    }

    #[tokio::test]
    async fn start_menu_refresh_populates_cache_and_shutdown_stops_it() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("repo-a"), "/tmp/a"))
            .await
            .unwrap();
        // Before the task runs, `menu()` computes inline from an empty cache.
        assert!(svc.menu_cache.lock().unwrap().is_none());

        svc.start_menu_refresh();
        // Idempotent: a second call does not start a second task.
        svc.start_menu_refresh();

        // The task fills the cache off the main thread; poll briefly for it.
        let mut filled = false;
        for _ in 0..100 {
            if svc.menu_cache.lock().unwrap().is_some() {
                filled = true;
                break;
            }
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
        assert!(filled, "background refresh should populate the menu cache");

        // `menu()` now serves the cache: one clickable line for the window.
        let menu = svc.menu();
        assert_eq!(menu.title, "Worktrees");
        assert!(menu
            .items
            .iter()
            .any(|i| matches!(i, MenuItem::Action(a) if a.id == "focus:w1")));

        // Shutdown cancels and joins the task, clearing the handle.
        svc.shutdown().await;
        assert!(svc.refresh.lock().unwrap().is_none());
    }

    #[tokio::test]
    async fn default_constructs_an_empty_service() {
        let svc = WorktreesService::default();
        let payload = svc.handle("list", Value::Null).await.unwrap();
        assert_eq!(payload, json!({ "windows": [] }));
    }

    // --- Push subscription (#1267) -----------------------------------------

    #[tokio::test]
    async fn subscribe_streams_only_for_the_subscribe_op() {
        let svc = WorktreesService::new();
        // The one streaming op yields a stream; every other op (including the
        // request/reply worktrees ops) declines, so the server dispatches them
        // normally.
        assert!(svc.subscribe("subscribe", &Value::Null).is_some());
        assert!(svc.subscribe("list", &Value::Null).is_none());
        assert!(svc.subscribe("register", &Value::Null).is_none());
        assert!(svc.subscribe("bogus", &Value::Null).is_none());
    }

    #[tokio::test]
    async fn subscribe_snapshot_matches_the_tree_op() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();

        let svc = WorktreesService::new();
        let stream = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        // No windows yet → no repos derived; the toggle rides along at its
        // default (show all).
        assert_eq!(
            stream.snapshot().await,
            json!({ "repos": [], "show_closed": true })
        );

        // A window opens on the repo → the snapshot carries it, byte-identical to
        // what the `tree` op returns for the same registry state.
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [dir.path()], "repo": "r" }),
        )
        .await
        .unwrap();
        let snap = stream.snapshot().await;
        let tree = svc.handle("tree", Value::Null).await.unwrap();
        assert_eq!(snap, tree);
        let repos = snap["repos"].as_array().expect("repos array");
        assert_eq!(repos.len(), 1);
        assert_eq!(repos[0]["worktrees"][0]["branch"], json!("main"));
    }

    #[tokio::test]
    async fn subscribe_changed_wakes_on_register() {
        let svc = WorktreesService::new();
        let mut stream = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        // Idle: `changed()` must not resolve without a registry change.
        tokio::select! {
            () = stream.changed() => panic!("changed resolved with no registry change"),
            () = tokio::time::sleep(Duration::from_millis(50)) => {}
        }
        // A register bumps the change-notify → `changed()` resolves promptly.
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        tokio::time::timeout(Duration::from_secs(1), stream.changed())
            .await
            .expect("changed should resolve after a register");
    }

    // --- Coalesced tree-snapshot cache (#1303) -----------------------------

    #[tokio::test]
    async fn tree_cache_coalesces_reads_within_ttl_and_generation() {
        let reg = Arc::new(WorktreesRegistry::new());
        // A long TTL so only the generation gate is exercised here.
        let cache = TreeSnapshotCache::with_ttl(
            reg,
            Arc::new(PrStatusCache::new()),
            Duration::from_secs(60),
        );
        // The first read builds once.
        let first = cache.snapshot().await;
        assert_eq!(cache.compute_count(), 1);
        // Further reads with no registry change and within the TTL reuse the
        // cached value — no extra build, byte-identical result.
        let second = cache.snapshot().await;
        assert_eq!(
            cache.compute_count(),
            1,
            "an unchanged read must not rebuild"
        );
        assert_eq!(first, second);
    }

    #[tokio::test]
    async fn tree_cache_single_flights_a_read_burst() {
        let reg = Arc::new(WorktreesRegistry::new());
        let cache = Arc::new(TreeSnapshotCache::with_ttl(
            reg,
            Arc::new(PrStatusCache::new()),
            Duration::from_secs(60),
        ));
        // A burst of concurrent readers — as N subscriber streams would wake
        // together on a change/tick — collapses to exactly one build; the rest
        // read the shared result (the acceptance criterion).
        let mut handles = Vec::new();
        for _ in 0..16 {
            let cache = cache.clone();
            handles.push(tokio::spawn(async move { cache.snapshot().await }));
        }
        let mut results = Vec::new();
        for handle in handles {
            results.push(handle.await.unwrap());
        }
        assert_eq!(
            cache.compute_count(),
            1,
            "a concurrent read burst must build the tree once"
        );
        assert!(
            results.windows(2).all(|w| w[0] == w[1]),
            "every reader must observe the identical snapshot"
        );
    }

    #[tokio::test]
    async fn tree_cache_rebuilds_on_registry_change() {
        let reg = Arc::new(WorktreesRegistry::new());
        let cache = TreeSnapshotCache::with_ttl(
            reg.clone(),
            Arc::new(PrStatusCache::new()),
            Duration::from_secs(60),
        );
        cache.snapshot().await;
        assert_eq!(cache.compute_count(), 1);
        // A registry change bumps the generation, so the next read rebuilds even
        // though the (long) TTL has not expired — subscribers never see a stale
        // visible set.
        assert!(reg.set_show_closed(false));
        cache.snapshot().await;
        assert_eq!(
            cache.compute_count(),
            2,
            "a generation bump must force a rebuild"
        );
    }

    #[tokio::test]
    async fn tree_cache_rebuilds_after_ttl_expiry() {
        let reg = Arc::new(WorktreesRegistry::new());
        // A zero TTL: every read is already past it, so a pure on-disk git change
        // still surfaces on the next tick with no registry bump needed.
        let cache =
            TreeSnapshotCache::with_ttl(reg, Arc::new(PrStatusCache::new()), Duration::ZERO);
        cache.snapshot().await;
        cache.snapshot().await;
        assert_eq!(
            cache.compute_count(),
            2,
            "an expired TTL must force a rebuild each read"
        );
    }

    #[tokio::test]
    async fn subscribe_streams_share_one_build_per_generation() {
        let svc = WorktreesService::new();
        let s1 = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        let s2 = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        // Two windows' streams sampling the same registry state build the tree
        // once, not once per stream (#1303) — they share the service's cache.
        let a = s1.snapshot().await;
        let b = s2.snapshot().await;
        assert_eq!(a, b);
        assert_eq!(
            svc.tree_cache.compute_count(),
            1,
            "N streams on one generation must share a single build"
        );
    }

    // --- Show/hide-closed toggle (#1301) -----------------------------------

    #[tokio::test]
    async fn set_show_closed_toggles_the_snapshot_field() {
        let svc = WorktreesService::new();
        // The snapshot carries the toggle; it defaults to show-all.
        assert_eq!(
            svc.handle("tree", Value::Null).await.unwrap()["show_closed"],
            json!(true)
        );
        // Setting it flips the field the next snapshot reports.
        let reply = svc
            .handle("set-show-closed", json!({ "show_closed": false }))
            .await
            .unwrap();
        assert_eq!(reply, json!({ "ok": true }));
        assert_eq!(
            svc.handle("tree", Value::Null).await.unwrap()["show_closed"],
            json!(false)
        );
    }

    #[tokio::test]
    async fn set_show_closed_rejects_a_non_boolean_payload() {
        let svc = WorktreesService::new();
        assert!(svc.handle("set-show-closed", json!({})).await.is_err());
        assert!(svc
            .handle("set-show-closed", json!({ "show_closed": "yes" }))
            .await
            .is_err());
    }

    #[tokio::test]
    async fn set_show_closed_wakes_the_subscription() {
        let svc = WorktreesService::new();
        let mut stream = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        // A real flip bumps the change-notify → `changed()` resolves promptly.
        svc.handle("set-show-closed", json!({ "show_closed": false }))
            .await
            .unwrap();
        tokio::time::timeout(Duration::from_secs(1), stream.changed())
            .await
            .expect("changed should resolve after a toggle flip");
        // The pushed snapshot now reflects the new toggle.
        assert_eq!(stream.snapshot().await["show_closed"], json!(false));
    }

    #[tokio::test]
    async fn set_polling_toggles_the_snapshot_field_for_a_repo() {
        // #1376: enabling stamps `polling_enabled: true` on the repo; disabling
        // drops it (skip-if-false), so the extension colours the icon off the flag.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();

        let repo = repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0].clone();
        assert!(
            repo.get("polling_enabled").is_none(),
            "default off omits the flag: {repo:?}"
        );

        let reply = svc
            .handle(
                "set-polling",
                json!({ "owner": "rust-works", "name": "omni-dev", "enabled": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "ok": true }));
        let repo = repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0].clone();
        assert_eq!(repo["polling_enabled"], json!(true));

        svc.handle(
            "set-polling",
            json!({ "owner": "rust-works", "name": "omni-dev", "enabled": false }),
        )
        .await
        .unwrap();
        let repo = repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0].clone();
        assert!(repo.get("polling_enabled").is_none());
    }

    #[tokio::test]
    async fn set_polling_rejects_missing_or_empty_fields() {
        let svc = WorktreesService::new();
        // Missing `enabled`.
        assert!(svc
            .handle("set-polling", json!({ "owner": "o", "name": "n" }))
            .await
            .is_err());
        // Missing `owner`/`name`.
        assert!(svc
            .handle("set-polling", json!({ "enabled": true }))
            .await
            .is_err());
        // Blank `owner`/`name`.
        assert!(svc
            .handle(
                "set-polling",
                json!({ "owner": " ", "name": "n", "enabled": true })
            )
            .await
            .is_err());
    }

    #[tokio::test]
    async fn set_polling_wakes_the_subscription() {
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        let mut stream = svc
            .subscribe("subscribe", &Value::Null)
            .expect("subscribe stream");
        svc.handle(
            "set-polling",
            json!({ "owner": "rust-works", "name": "omni-dev", "enabled": true }),
        )
        .await
        .unwrap();
        tokio::time::timeout(Duration::from_secs(1), stream.changed())
            .await
            .expect("changed should resolve after enabling a repo");
        let repo = repos_of(&stream.snapshot().await)[0].clone();
        assert_eq!(repo["polling_enabled"], json!(true));
    }

    #[tokio::test]
    async fn disabling_a_repo_drops_its_pr_badges_immediately() {
        // The "drop existing badges immediately" requirement (#1376), done
        // daemon-side: the fold skips a not-polled repo, so a disable strips the
        // badge on the very next snapshot rather than waiting for a poll.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap().to_string();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.registry.set_polling("rust-works", "omni-dev", true);

        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(pending_badge(7, &head)),
        );
        svc.pr_cache.replace(badges);

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr"]["number"], json!(7));

        svc.handle(
            "set-polling",
            json!({ "owner": "rust-works", "name": "omni-dev", "enabled": false }),
        )
        .await
        .unwrap();
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(
            wt.get("pr").is_none(),
            "a disabled repo must carry no badge: {wt:?}"
        );
    }

    #[tokio::test]
    async fn an_expired_lease_drops_the_flag_and_badges() {
        // The 15-minute auto-expire (#1376) seen end-to-end: once a repo's lease
        // elapses, the snapshot drops `polling_enabled` *and* the badge, and the
        // poller would no longer watch it — all reaped on read, no timer.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap().to_string();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.registry.set_polling("rust-works", "omni-dev", true);
        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(pending_badge(7, &head)),
        );
        svc.pr_cache.replace(badges);

        // Leased: flag stamped, badge folded, and the poller would watch it.
        let snap = svc.handle("tree", Value::Null).await.unwrap();
        assert_eq!(repos_of(&snap)[0]["polling_enabled"], json!(true));
        assert_eq!(repos_of(&snap)[0]["worktrees"][0]["pr"]["number"], json!(7));
        assert_eq!(pr_targets_from_snapshot(&snap).len(), 1);

        // Force the lease into the past — as 15 minutes elapsing would.
        svc.registry.set_polling_expiry(
            "rust-works",
            "omni-dev",
            Utc::now() - chrono::Duration::minutes(1),
        );

        let snap = svc.handle("tree", Value::Null).await.unwrap();
        let repo0 = &repos_of(&snap)[0];
        assert!(
            repo0.get("polling_enabled").is_none(),
            "expired lease drops the flag: {repo0:?}"
        );
        assert!(
            repo0["worktrees"][0].get("pr").is_none(),
            "expired lease drops the badge"
        );
        assert!(
            pr_targets_from_snapshot(&snap).is_empty(),
            "the poller no longer watches an expired repo"
        );
    }

    #[tokio::test]
    async fn polling_prefs_persist_across_reloads_with_0600() {
        // The enable set survives a daemon restart (#1376): a change writes the
        // `0600` file, and a fresh service seeded from it comes up enabled.
        let dir = tempfile::tempdir().unwrap();
        let prefs = dir.path().join("worktrees-polling.json");

        let svc = WorktreesService::new();
        svc.load_polling_prefs(prefs.clone());
        assert!(!svc.registry.is_polling_enabled("rust-works", "omni-dev"));
        svc.handle(
            "set-polling",
            json!({ "owner": "rust-works", "name": "omni-dev", "enabled": true }),
        )
        .await
        .unwrap();
        assert!(prefs.exists());
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            assert_eq!(
                std::fs::metadata(&prefs).unwrap().permissions().mode() & 0o777,
                0o600
            );
        }

        // A new service reloads the enabled set from that file.
        let svc2 = WorktreesService::new();
        svc2.load_polling_prefs(prefs.clone());
        assert!(svc2.registry.is_polling_enabled("rust-works", "omni-dev"));

        // Disabling rewrites the file, so the next reload has nothing enabled.
        svc2.handle(
            "set-polling",
            json!({ "owner": "rust-works", "name": "omni-dev", "enabled": false }),
        )
        .await
        .unwrap();
        let svc3 = WorktreesService::new();
        svc3.load_polling_prefs(prefs);
        assert!(!svc3.registry.is_polling_enabled("rust-works", "omni-dev"));
    }

    #[test]
    fn load_polling_prefs_tolerates_a_corrupt_or_unreadable_file() {
        // Best-effort load (#1376): a hand-edited/corrupt file or an unreadable
        // path is logged and treated as "nothing enabled" rather than wedging the
        // service. A missing file is already the first-run default (covered by the
        // persistence round-trip above); this exercises the two error branches.
        let dir = tempfile::tempdir().unwrap();

        // Corrupt JSON — the parse error is swallowed, nothing is enabled.
        let corrupt = dir.path().join("worktrees-polling.json");
        std::fs::write(&corrupt, b"{ not valid json ]").unwrap();
        let svc = WorktreesService::new();
        svc.load_polling_prefs(corrupt);
        assert!(svc.registry.enabled_polling_repos().is_empty());

        // A directory at the path — the (non-NotFound) read error is swallowed too.
        let as_dir = dir.path().join("is-a-directory");
        std::fs::create_dir(&as_dir).unwrap();
        let svc2 = WorktreesService::new();
        svc2.load_polling_prefs(as_dir);
        assert!(svc2.registry.enabled_polling_repos().is_empty());
    }

    #[tokio::test]
    async fn pr_poller_asks_nothing_for_a_registered_but_not_enabled_repo() {
        // The zero-`gh` guarantee (#1376): a window is open on a GitHub repo, but
        // the user has not enabled polling for it — so the poller spawns no `gh`.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let marker = bin_dir.path().join("spawned");
        let fake = bin_dir.path().join("fake-gh");
        std::fs::write(
            &fake,
            format!("#!/bin/sh\ntouch '{}'\necho '{{}}'\n", marker.display()),
        )
        .unwrap();
        let mut perms = std::fs::metadata(&fake).unwrap().permissions();
        std::os::unix::fs::PermissionsExt::set_mode(&mut perms, 0o755);
        std::fs::set_permissions(&fake, perms).unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Deliberately NOT enabling polling for the repo.
        svc.start_pr_poller_with(Duration::from_millis(20), Duration::from_millis(10), fake);
        tokio::time::sleep(Duration::from_millis(200)).await;
        svc.shutdown().await;
        assert!(
            !marker.exists(),
            "a registered-but-not-enabled repo must drive zero gh"
        );
    }

    #[tokio::test]
    async fn menu_action_rejects_unknown_and_missing_window() {
        let svc = WorktreesService::new();
        assert!(svc.menu_action("bogus").await.is_err());
        // A focus for a key with no registration errors rather than spawning.
        assert!(svc.menu_action("focus:nope").await.is_err());
        svc.shutdown().await;
    }

    /// Restores `OMNI_DEV_VSCODE_BIN` on drop. The two spawn tests that read the
    /// variable (via `resolve_code_binary` → `focus_window`) —
    /// `menu_action_focus_resolves_folder_and_spawns` and
    /// `open_focuses_an_existing_absolute_dir` — both point the launcher at the
    /// same harmless `/bin/sh`, and no test asserts the variable is *unset*, so a
    /// transient overlap under the harness's test parallelism is benign.
    struct VscodeBinGuard(Option<std::ffi::OsString>);
    impl Drop for VscodeBinGuard {
        fn drop(&mut self) {
            match self.0.take() {
                Some(v) => std::env::set_var(VSCODE_BIN_ENV, v),
                None => std::env::remove_var(VSCODE_BIN_ENV),
            }
        }
    }

    #[tokio::test]
    async fn menu_action_focus_resolves_folder_and_spawns() {
        let dir = tempfile::tempdir().unwrap();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [dir.path()], "repo": "r" }),
        )
        .await
        .unwrap();

        // Point the launcher at a harmless binary so the spawn deterministically
        // succeeds and the focus path returns Ok.
        let _g = VscodeBinGuard(std::env::var_os(VSCODE_BIN_ENV));
        std::env::set_var(VSCODE_BIN_ENV, "/bin/sh");
        svc.menu_action("focus:w1").await.unwrap();
    }

    #[tokio::test]
    async fn open_rejects_missing_relative_or_nonexistent_path() {
        let svc = WorktreesService::new();
        // A missing `path` is a payload error.
        assert!(svc.handle("open", json!({})).await.is_err());
        assert!(svc.handle("open", json!({ "path": 42 })).await.is_err());
        // A relative path is rejected before any spawn — this is also what
        // blocks a `-`-leading argument from reaching `code` as a flag.
        assert!(svc
            .handle("open", json!({ "path": "relative/dir" }))
            .await
            .is_err());
        assert!(svc
            .handle("open", json!({ "path": "-flag" }))
            .await
            .is_err());
        // An absolute path that does not exist is rejected before any spawn, so
        // no launcher is needed for these guard cases.
        assert!(svc
            .handle("open", json!({ "path": "/no/such/abs/dir/xyzzy" }))
            .await
            .is_err());
        svc.shutdown().await;
    }

    #[tokio::test]
    async fn open_focuses_an_existing_absolute_dir() {
        let dir = tempfile::tempdir().unwrap();
        let svc = WorktreesService::new();
        // Pin the launcher to a harmless binary so the spawn deterministically
        // succeeds whether or not `code` is installed. Unlike the tray `focus`
        // path, `open` takes the folder straight from the payload — no prior
        // `register` is required.
        let _g = VscodeBinGuard(std::env::var_os(VSCODE_BIN_ENV));
        std::env::set_var(VSCODE_BIN_ENV, "/bin/sh");
        let reply = svc
            .handle("open", json!({ "path": dir.path() }))
            .await
            .unwrap();
        assert_eq!(reply, json!({ "ok": true }));
        svc.shutdown().await;
    }

    #[test]
    fn focus_window_with_validates_folder_then_spawns() {
        let dir = tempfile::tempdir().unwrap();
        // Non-absolute and missing-directory folders are rejected before spawn.
        assert!(focus_window_with(Path::new("/bin/sh"), Path::new("relative/dir")).is_err());
        assert!(
            focus_window_with(Path::new("/bin/sh"), Path::new("/no/such/abs/dir/xyzzy")).is_err()
        );
        // A valid absolute directory spawns the launcher successfully.
        focus_window_with(Path::new("/bin/sh"), dir.path()).unwrap();
        // A missing launcher surfaces the spawn error (with context), not Ok.
        assert!(focus_window_with(Path::new("/no/such/launcher/xyzzy"), dir.path()).is_err());
    }

    #[test]
    fn resolve_code_binary_from_prefers_env_then_candidate_then_fallback() {
        // Env override wins outright.
        assert_eq!(
            resolve_code_binary_from(Some("/custom/code".into()), &["/usr/bin/code"]),
            PathBuf::from("/custom/code")
        );
        // No override: the first existing candidate is chosen.
        let existing = tempfile::NamedTempFile::new().unwrap();
        let existing_path = existing.path().to_str().unwrap();
        assert_eq!(
            resolve_code_binary_from(None, &["/no/such/candidate/xyzzy", existing_path]),
            PathBuf::from(existing_path)
        );
        // Nothing exists: fall back to bare `code` on PATH.
        assert_eq!(
            resolve_code_binary_from(None, &["/no/such/candidate/xyzzy"]),
            PathBuf::from("code")
        );
        // The real-env wrapper resolves without panicking.
        let _ = resolve_code_binary();
    }

    // --- Git enrichment (#1186) --------------------------------------------

    /// Initializes a fresh repo with a deterministic identity so `commit()`
    /// works without depending on a global git config.
    fn init_repo(dir: &Path) -> Repository {
        let repo = Repository::init(dir).unwrap();
        let mut cfg = repo.config().unwrap();
        cfg.set_str("user.name", "Test").unwrap();
        cfg.set_str("user.email", "test@example.com").unwrap();
        repo
    }

    /// Writes an empty-tree commit (file content is irrelevant to ahead/behind),
    /// optionally moving `refname` to it, and returns its oid.
    fn empty_commit(
        repo: &Repository,
        refname: Option<&str>,
        parents: &[&git2::Commit<'_>],
        msg: &str,
    ) -> git2::Oid {
        let sig = git2::Signature::now("Test", "test@example.com").unwrap();
        let tree = repo
            .find_tree(repo.treebuilder(None).unwrap().write().unwrap())
            .unwrap();
        repo.commit(refname, &sig, &sig, msg, &tree, parents)
            .unwrap()
    }

    /// Commits `content` as file `name` onto `refname`, chaining off its current
    /// tip (if any). Unlike [`empty_commit`], the tree carries a real blob, so
    /// the file is checked out into a worktree and can then be modified to
    /// produce a dirty (tracked) status.
    fn commit_file(
        repo: &Repository,
        refname: &str,
        name: &str,
        content: &[u8],
        msg: &str,
    ) -> git2::Oid {
        let sig = git2::Signature::now("Test", "test@example.com").unwrap();
        let blob = repo.blob(content).unwrap();
        let mut builder = repo.treebuilder(None).unwrap();
        builder.insert(name, blob, 0o100_644).unwrap();
        let tree = repo.find_tree(builder.write().unwrap()).unwrap();
        let parent = repo
            .refname_to_id(refname)
            .ok()
            .and_then(|oid| repo.find_commit(oid).ok());
        let parents: Vec<&git2::Commit<'_>> = parent.iter().collect();
        repo.commit(Some(refname), &sig, &sig, msg, &tree, &parents)
            .unwrap()
    }

    /// Builds a repo whose `main` is 1 commit ahead of and 1 behind a configured
    /// `origin/main` upstream, so enrichment reports `ahead: 1, behind: 1`.
    fn diverging_repo(dir: &Path) -> Repository {
        let repo = init_repo(dir);
        // A: the shared base on `main`.
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        let a_commit = repo.find_commit(a).unwrap();
        // origin/main diverges to C, a sibling of the local tip.
        let c = empty_commit(&repo, None, &[&a_commit], "C");
        repo.reference("refs/remotes/origin/main", c, true, "origin main")
            .unwrap();
        // Local `main` advances to B → 1 ahead of / 1 behind origin/main.
        empty_commit(&repo, Some("refs/heads/main"), &[&a_commit], "B");
        // Release the commit's borrow of `repo` so it can be returned.
        drop(a_commit);
        repo.set_head("refs/heads/main").unwrap();
        // Configure the tracking relationship so `upstream()` resolves.
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", "https://example.invalid/x.git")
            .unwrap();
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str("branch.main.remote", "origin").unwrap();
        cfg.set_str("branch.main.merge", "refs/heads/main").unwrap();
        repo
    }

    /// Builds a repo whose `main` has **no upstream configured** but is 1 commit
    /// behind a resolvable `origin/main` — the "no own upstream, but behind the
    /// default branch" case [`repo_main_behind`] exists for (#1457). No
    /// `origin/HEAD` symref is set, so resolution goes through
    /// [`RemoteInfo::detect_main_branch_local`]'s common-names fallback.
    fn behind_main_no_upstream_repo(dir: &Path) -> Repository {
        let repo = init_repo(dir);
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        let a_commit = repo.find_commit(a).unwrap();
        let c = empty_commit(&repo, None, &[&a_commit], "C");
        repo.reference("refs/remotes/origin/main", c, true, "origin main")
            .unwrap();
        drop(a_commit);
        repo.set_head("refs/heads/main").unwrap();
        repo
    }

    #[test]
    fn git_status_reads_branch_and_ahead_behind() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        let status = git_status(dir.path());
        assert_eq!(status.branch.as_deref(), Some("main"));
        assert_eq!(status.ahead, Some(1));
        assert_eq!(status.behind, Some(1));
        // A normal checkout names itself and is not flagged a worktree.
        assert_eq!(
            status.main_repo.as_deref(),
            dir.path().file_name().and_then(|n| n.to_str())
        );
        assert!(!status.is_worktree);
    }

    #[test]
    fn git_status_empty_repo_is_unborn() {
        // A repo with no commits has an unborn HEAD, so `head()` errors and the
        // branch/sync fields stay empty rather than panicking — but the repo
        // identity is still resolved from the common dir.
        let dir = tempfile::tempdir().unwrap();
        init_repo(dir.path());
        let status = git_status(dir.path());
        assert_eq!(status.branch, None);
        // An unborn HEAD has no commit to name, so the SHA is absent too (#1337).
        assert_eq!(status.head_sha, None);
        assert_eq!(status.ahead, None);
        assert_eq!(status.behind, None);
        assert_eq!(
            status.main_repo.as_deref(),
            dir.path().file_name().and_then(|n| n.to_str())
        );
        assert!(!status.is_worktree);
    }

    #[test]
    fn git_status_no_upstream_reports_branch_only() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let status = git_status(dir.path());
        assert_eq!(status.branch.as_deref(), Some("main"));
        // No upstream → ahead/behind stay absent rather than zero.
        assert_eq!(status.ahead, None);
        assert_eq!(status.behind, None);
        // …and so does the upstream SHA, so such a branch still renders with no
        // sync indicator at all (#1344).
        assert_eq!(status.upstream_sha, None);
    }

    #[test]
    fn git_status_non_repo_is_empty_detached_reports_repo_without_branch() {
        // A plain directory that is not a git repo yields nothing at all.
        let plain = tempfile::tempdir().unwrap();
        assert_eq!(git_status(plain.path()), GitStatus::default());

        // A detached HEAD reports no branch (and thus no sync), but the repo
        // identity is still resolved from the common dir.
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head_detached(a).unwrap();
        let status = git_status(dir.path());
        assert_eq!(status.branch, None);
        // A detached HEAD has no branch but *does* have a commit — the SHA is
        // resolved before the branch filter, so it survives here (#1337).
        assert_eq!(status.head_sha.as_deref(), Some(a.to_string().as_str()));
        assert_eq!(status.ahead, None);
        assert_eq!(status.behind, None);
        // A detached HEAD has no branch, so there is no upstream to resolve
        // either — the branch filter returns before the wrap (#1344).
        assert_eq!(status.upstream_sha, None);
        assert_eq!(
            status.main_repo.as_deref(),
            dir.path().file_name().and_then(|n| n.to_str())
        );
        assert!(!status.is_worktree);
    }

    // --- Lazy ahead/behind (#1306) -----------------------------------------

    #[test]
    fn git_status_cheap_reads_branch_but_skips_the_divergence_walk() {
        // The same repo `git_status` reports 1/1 for. The cheap variant used by
        // the streamed tree snapshot still reads the branch and repo identity, but
        // leaves ahead/behind absent — divergence is now lazy (#1306).
        let dir = tempfile::tempdir().unwrap();
        let repo = diverging_repo(dir.path());
        let status = git_status_cheap(dir.path());
        assert_eq!(status.branch.as_deref(), Some("main"));
        assert_eq!(status.ahead, None);
        assert_eq!(status.behind, None);
        assert_eq!(
            status.main_repo.as_deref(),
            dir.path().file_name().and_then(|n| n.to_str())
        );
        // The SHA rides the *cheap* path deliberately: it is a refs read, not a
        // revwalk, and it is what makes a new commit a snapshot delta (#1337).
        let head = repo.head().unwrap().target().unwrap();
        assert_eq!(status.head_sha.as_deref(), Some(head.to_string().as_str()));
    }

    // --- HEAD SHA on the snapshot (#1337) ----------------------------------

    #[test]
    fn git_status_head_sha_tracks_new_commits() {
        // The regression #1337 turns on: a commit must change the status the
        // snapshot is built from. Before the SHA rode the payload, committing
        // changed nothing on the wire, the server's diff dropped the identical
        // snapshot, and no client re-rendered — so a badge computed for the old
        // head survived the push that invalidated it.
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let before = git_status_cheap(dir.path());
        assert_eq!(before.head_sha.as_deref(), Some(a.to_string().as_str()));

        let head = repo.find_commit(a).unwrap();
        let b = empty_commit(&repo, Some("refs/heads/main"), &[&head], "B");
        let after = git_status_cheap(dir.path());
        assert_eq!(after.head_sha.as_deref(), Some(b.to_string().as_str()));
        assert_ne!(before.head_sha, after.head_sha);
        // The branch is unchanged — the SHA is the *only* thing that moved, which
        // is exactly why its absence made the push invisible.
        assert_eq!(before.branch, after.branch);
    }

    // --- Upstream SHA on the snapshot (#1344) ------------------------------

    /// Repoints `refs/remotes/origin/main` at `oid` — exactly what a `git push`
    /// does, and all of what it does: the local branch and HEAD do not move. Lets
    /// these tests exercise a push with no network and no second repo.
    fn simulate_push(repo: &Repository, oid: git2::Oid) {
        repo.reference("refs/remotes/origin/main", oid, true, "push")
            .unwrap();
    }

    #[test]
    fn git_status_upstream_sha_tracks_a_push() {
        // The regression #1344 turns on. `diverging_repo` leaves local `main` at B
        // and origin/main at C — 1 ahead, 1 behind. Pushing B moves *only* the
        // remote-tracking ref, so before this field rode the payload every wire
        // field was byte-identical across the push, the server's diff dropped the
        // snapshot, no client re-rendered, and the lazily-fetched ahead/behind was
        // never re-asked — the row showed `↑1 ↓0` forever.
        let dir = tempfile::tempdir().unwrap();
        let repo = diverging_repo(dir.path());
        let before = git_status(dir.path());
        assert_eq!(before.ahead, Some(1));
        assert_eq!(before.behind, Some(1));

        let head = repo.head().unwrap().target().unwrap();
        simulate_push(&repo, head);
        let after = git_status(dir.path());

        // The upstream now names the pushed commit, and the counts agree.
        assert_eq!(
            after.upstream_sha.as_deref(),
            Some(head.to_string().as_str())
        );
        assert_ne!(before.upstream_sha, after.upstream_sha);
        assert_eq!(after.ahead, Some(0));
        assert_eq!(after.behind, Some(0));
        // Nothing else moved — which is the whole point. A push leaves the branch
        // and the local head exactly where they were, so `upstream_sha` is the
        // only signal a client could possibly notice.
        assert_eq!(before.branch, after.branch);
        assert_eq!(before.head_sha, after.head_sha);
    }

    #[test]
    fn git_status_cheap_reports_upstream_sha() {
        // The crux: the field has to ride the *cheap* path, since that is the one
        // the streamed snapshot is built from. Costing a config lookup and a refs
        // read — no revwalk — it clears the bar #1306 set, unlike the divergence
        // walk still absent here.
        let dir = tempfile::tempdir().unwrap();
        let repo = diverging_repo(dir.path());
        let status = git_status_cheap(dir.path());
        let upstream = repo
            .find_branch("origin/main", git2::BranchType::Remote)
            .unwrap()
            .get()
            .target()
            .unwrap();
        assert_eq!(
            status.upstream_sha.as_deref(),
            Some(upstream.to_string().as_str())
        );
        assert_eq!(status.ahead, None);
        assert_eq!(status.behind, None);
    }

    #[test]
    fn folder_divergence_computes_ahead_behind_and_degrades() {
        // A diverging tracking branch → the on-demand walk reports (ahead, behind).
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        assert_eq!(folder_divergence(dir.path()).ahead_behind, Some((1, 1)));

        // A branch with no upstream → None (the tree renders no sync indicator).
        let no_up = tempfile::tempdir().unwrap();
        let repo = init_repo(no_up.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        assert_eq!(folder_divergence(no_up.path()).ahead_behind, None);

        // A detached HEAD and a plain (non-repo) directory → None.
        let detached = tempfile::tempdir().unwrap();
        let drepo = init_repo(detached.path());
        let a = empty_commit(&drepo, Some("refs/heads/main"), &[], "A");
        drepo.set_head_detached(a).unwrap();
        assert_eq!(folder_divergence(detached.path()).ahead_behind, None);
        let plain = tempfile::tempdir().unwrap();
        assert_eq!(folder_divergence(plain.path()).ahead_behind, None);
    }

    // --- Lazy main-branch behind (#1457) ------------------------------------

    #[test]
    fn folder_divergence_computes_main_behind_and_degrades() {
        // No own upstream, but a resolvable `origin/main` (via the common-names
        // fallback — no `origin/HEAD` symref is set) that the branch is
        // genuinely behind.
        let dir = tempfile::tempdir().unwrap();
        let _repo = behind_main_no_upstream_repo(dir.path());
        assert_eq!(folder_divergence(dir.path()).main_behind, Some(1));

        // A detached HEAD and a plain (non-repo) directory → None.
        let detached = tempfile::tempdir().unwrap();
        let drepo = init_repo(detached.path());
        let a = empty_commit(&drepo, Some("refs/heads/main"), &[], "A");
        drepo.set_head_detached(a).unwrap();
        assert_eq!(folder_divergence(detached.path()).main_behind, None);
        let plain = tempfile::tempdir().unwrap();
        assert_eq!(folder_divergence(plain.path()).main_behind, None);
    }

    #[test]
    fn folder_divergence_skips_main_behind_when_own_upstream_is_the_default_branch() {
        // `diverging_repo` checks out `main` tracking `origin/main` itself — the
        // common case — so even though it's genuinely 1 behind, `main_behind`
        // stays silent: `ahead_behind`'s `behind` already reports this
        // exact divergence.
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        assert_eq!(folder_divergence(dir.path()).main_behind, None);
    }

    #[test]
    fn folder_divergence_has_no_main_behind_without_a_resolvable_default_branch() {
        // No `origin` remote-tracking refs at all (no symref, no common names).
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        assert_eq!(folder_divergence(dir.path()).main_behind, None);
    }

    #[test]
    fn folder_divergence_reports_independent_main_behind_and_ahead_behind_counts() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let base = empty_commit(&repo, Some("refs/heads/main"), &[], "base");
        let base_commit = repo.find_commit(base).unwrap();

        // origin/main advances 3 commits past the shared base.
        let m1 = empty_commit(&repo, None, &[&base_commit], "m1");
        let m1_commit = repo.find_commit(m1).unwrap();
        let m2 = empty_commit(&repo, None, &[&m1_commit], "m2");
        let m2_commit = repo.find_commit(m2).unwrap();
        let m3 = empty_commit(&repo, None, &[&m2_commit], "m3");
        repo.reference("refs/remotes/origin/main", m3, true, "origin main")
            .unwrap();

        // `feature` branches off the shared base and diverges 1 ahead / 1
        // behind its own upstream `origin/feature`.
        let of = empty_commit(&repo, None, &[&base_commit], "origin-feature");
        repo.reference("refs/remotes/origin/feature", of, true, "origin feature")
            .unwrap();
        empty_commit(
            &repo,
            Some("refs/heads/feature"),
            &[&base_commit],
            "local-feature",
        );
        drop(base_commit);
        drop(m1_commit);
        drop(m2_commit);

        repo.set_head("refs/heads/feature").unwrap();
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", "https://example.invalid/x.git")
            .unwrap();
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str("branch.feature.remote", "origin").unwrap();
        cfg.set_str("branch.feature.merge", "refs/heads/feature")
            .unwrap();

        assert_eq!(folder_divergence(dir.path()).ahead_behind, Some((1, 1)));
        assert_eq!(folder_divergence(dir.path()).main_behind, Some(3));
    }

    #[tokio::test]
    async fn ahead_behind_op_returns_divergence_keyed_by_path_and_omits_no_upstream() {
        let diverging = tempfile::tempdir().unwrap();
        let _d = diverging_repo(diverging.path());
        let no_up = tempfile::tempdir().unwrap();
        let repo = init_repo(no_up.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();

        let svc = WorktreesService::new();
        let diverging_path = diverging.path().display().to_string();
        let no_up_path = no_up.path().display().to_string();
        let reply = svc
            .handle(
                "ahead-behind",
                json!({ "paths": [&diverging_path, &no_up_path] }),
            )
            .await
            .unwrap();
        let results = reply.get("results").unwrap();
        // The diverging worktree carries its counts, keyed by the requested path.
        // `diverging_repo` checks out `main` tracking `origin/main` itself, so
        // `main_behind` is skipped — `behind` already reports this divergence.
        let d = results.get(diverging_path.as_str()).unwrap();
        assert_eq!(d.get("ahead").and_then(Value::as_u64), Some(1));
        assert_eq!(d.get("behind").and_then(Value::as_u64), Some(1));
        assert!(d.get("main_behind").is_none(), "{d:?}");
        // The no-upstream worktree has no `origin` remote-tracking refs at all,
        // so neither `ahead`/`behind` nor `main_behind` resolves — the row is
        // omitted entirely, not reported as zero.
        assert!(results.get(no_up_path.as_str()).is_none(), "{results:?}");

        // A missing/empty `paths` list yields an empty results object, not an error.
        let empty = svc.handle("ahead-behind", json!({})).await.unwrap();
        assert_eq!(empty.get("results"), Some(&json!({})));
    }

    /// The adapter forwards a daemon-level accept outage to its registry (#2111),
    /// which is covered in depth in `crate::worktrees`; here it just has to reach it
    /// and leave a live window live.
    #[tokio::test]
    async fn credit_accept_outage_reaches_the_registry_without_dropping_a_live_window() {
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [], "repo": "x" }),
        )
        .await
        .unwrap();

        svc.credit_accept_outage(Duration::from_secs(5));

        assert_eq!(svc.registry.list().len(), 1);
    }

    /// Every window asks about the same worktrees at once (#2111): all of those
    /// requests must get the right answer, whether they shared a computation or not,
    /// including a request that names one worktree twice.
    #[tokio::test]
    async fn concurrent_ahead_behind_requests_all_get_the_same_correct_answer() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        let svc = WorktreesService::new();
        let path = dir.path().display().to_string();

        let replies = futures::future::join_all(
            (0..16).map(|_| svc.handle("ahead-behind", json!({ "paths": [&path, &path] }))),
        )
        .await;

        for reply in replies {
            let reply = reply.unwrap();
            let entry = reply.get("results").unwrap().get(path.as_str()).unwrap();
            assert_eq!(entry.get("ahead").and_then(Value::as_u64), Some(1));
            assert_eq!(entry.get("behind").and_then(Value::as_u64), Some(1));
        }
    }

    #[tokio::test]
    async fn ahead_behind_op_includes_a_path_with_only_main_behind_and_no_upstream() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = behind_main_no_upstream_repo(dir.path());
        let svc = WorktreesService::new();
        let path = dir.path().display().to_string();
        let reply = svc
            .handle("ahead-behind", json!({ "paths": [&path] }))
            .await
            .unwrap();
        let entry = reply.get("results").unwrap().get(path.as_str()).unwrap();
        assert_eq!(entry.get("main_behind").and_then(Value::as_u64), Some(1));
        // No own upstream at all → no `ahead`/`behind` keys, just `main_behind`.
        assert!(entry.get("ahead").is_none(), "{entry:?}");
        assert!(entry.get("behind").is_none(), "{entry:?}");
    }

    #[tokio::test]
    async fn ahead_behind_op_reports_main_behind_alongside_an_in_sync_own_upstream() {
        // `release` stays perfectly in sync with its own upstream
        // `origin/release`, while `origin/main` has independently advanced 2
        // commits past their shared base — `main_behind` must still fold in
        // even though `ahead`/`behind` are both zero.
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let base = empty_commit(&repo, Some("refs/heads/main"), &[], "base");
        let base_commit = repo.find_commit(base).unwrap();

        let m1 = empty_commit(&repo, None, &[&base_commit], "m1");
        let m1_commit = repo.find_commit(m1).unwrap();
        let m2 = empty_commit(&repo, None, &[&m1_commit], "m2");
        repo.reference("refs/remotes/origin/main", m2, true, "origin main")
            .unwrap();

        let r = empty_commit(
            &repo,
            Some("refs/heads/release"),
            &[&base_commit],
            "release",
        );
        repo.reference("refs/remotes/origin/release", r, true, "origin release")
            .unwrap();
        drop(base_commit);
        drop(m1_commit);

        repo.set_head("refs/heads/release").unwrap();
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", "https://example.invalid/x.git")
            .unwrap();
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str("branch.release.remote", "origin").unwrap();
        cfg.set_str("branch.release.merge", "refs/heads/release")
            .unwrap();

        let svc = WorktreesService::new();
        let path = dir.path().display().to_string();
        let reply = svc
            .handle("ahead-behind", json!({ "paths": [&path] }))
            .await
            .unwrap();
        let entry = reply.get("results").unwrap().get(path.as_str()).unwrap();
        assert_eq!(entry.get("ahead").and_then(Value::as_u64), Some(0));
        assert_eq!(entry.get("behind").and_then(Value::as_u64), Some(0));
        assert_eq!(entry.get("main_behind").and_then(Value::as_u64), Some(2));
    }

    #[tokio::test]
    async fn tree_snapshot_omits_ahead_behind_for_a_diverging_worktree() {
        // A window on a repo whose branch is 1 ahead of / 1 behind its upstream.
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "x" }),
        )
        .await
        .unwrap();

        let repos = repos_of(&svc.handle("tree", Value::Null).await.unwrap());
        let worktrees = repos[0].get("worktrees").and_then(Value::as_array).unwrap();
        let main_wt = &worktrees[0];
        // The cheap parts are present, but divergence is not — it is fetched
        // lazily via the `ahead-behind` op (#1306).
        assert_eq!(main_wt.get("branch").and_then(Value::as_str), Some("main"));
        assert!(main_wt.get("ahead").is_none(), "{main_wt:?}");
        assert!(main_wt.get("behind").is_none(), "{main_wt:?}");
    }

    #[tokio::test]
    async fn tree_snapshot_carries_head_sha_so_a_commit_is_a_real_delta() {
        // The end-to-end shape of the #1337 freshness fix. The server pushes a
        // snapshot only when it differs from the last one
        // (`server.rs`: `if snap != last`), so anything invisible on the wire
        // cannot trigger a re-render. Committing must therefore move the payload.
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "x" }),
        )
        .await
        .unwrap();

        let before = svc.handle("tree", Value::Null).await.unwrap();
        let wt = &repos_of(&before)[0]["worktrees"][0];
        assert_eq!(
            wt.get("head_sha").and_then(Value::as_str),
            Some(a.to_string().as_str())
        );

        // Commit again: same branch, same paths, same open windows — pre-#1337 the
        // snapshot was byte-identical here and the push was dropped.
        let head = repo.find_commit(a).unwrap();
        let b = empty_commit(&repo, Some("refs/heads/main"), &[&head], "B");
        let after = svc.handle("tree", Value::Null).await.unwrap();
        assert_eq!(
            repos_of(&after)[0]["worktrees"][0]
                .get("head_sha")
                .and_then(Value::as_str),
            Some(b.to_string().as_str())
        );
        assert_ne!(before, after, "a commit must be a visible snapshot delta");
    }

    #[tokio::test]
    async fn tree_snapshot_omits_head_sha_for_an_unborn_repo() {
        // Wire-compat: an absent SHA is dropped entirely rather than sent as null,
        // matching the payload's `skip_serializing_if` convention.
        let dir = tempfile::tempdir().unwrap();
        init_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "x" }),
        )
        .await
        .unwrap();
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(wt.get("head_sha").is_none(), "{wt:?}");
    }

    // --- Upstream SHA on the snapshot (#1344) ------------------------------

    #[tokio::test]
    async fn tree_snapshot_carries_upstream_sha_so_a_push_is_a_real_delta() {
        // The end-to-end shape of the #1344 fix, one ref over from #1337. A push
        // moves neither the branch nor the local head, so `upstream_sha` is the
        // only field that can carry the news. Without it the snapshot serialised
        // byte-identically, `server.rs`'s `if snap != last` dropped the frame, no
        // window re-rendered, and the lazy ahead/behind was never re-fetched.
        let dir = tempfile::tempdir().unwrap();
        let repo = diverging_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "x" }),
        )
        .await
        .unwrap();

        let before = svc.handle("tree", Value::Null).await.unwrap();
        let head = repo.head().unwrap().target().unwrap();
        assert_ne!(
            repos_of(&before)[0]["worktrees"][0]
                .get("upstream_sha")
                .and_then(Value::as_str),
            Some(head.to_string().as_str()),
            "the fixture must start un-pushed for this to prove anything"
        );

        // Push: only `refs/remotes/origin/main` moves.
        simulate_push(&repo, head);
        let after = svc.handle("tree", Value::Null).await.unwrap();
        let wt = &repos_of(&after)[0]["worktrees"][0];
        assert_eq!(
            wt.get("upstream_sha").and_then(Value::as_str),
            Some(head.to_string().as_str())
        );
        // The head and branch are untouched across the push — so this delta rests
        // entirely on `upstream_sha`.
        assert_eq!(
            wt.get("head_sha").and_then(Value::as_str),
            repos_of(&before)[0]["worktrees"][0]
                .get("head_sha")
                .and_then(Value::as_str)
        );
        assert_ne!(before, after, "a push must be a visible snapshot delta");
    }

    #[tokio::test]
    async fn tree_snapshot_omits_upstream_sha_without_an_upstream() {
        // Wire-compat, and the no-regression case: a branch tracking nothing sends
        // no key at all rather than a null, so an older client sees exactly the
        // payload it saw before and still renders no sync indicator.
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "x" }),
        )
        .await
        .unwrap();
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(wt.get("upstream_sha").is_none(), "{wt:?}");
        // The head still rides, so this is specifically the upstream degrading.
        assert!(wt.get("head_sha").is_some(), "{wt:?}");
    }

    // --- PR badge poller (#1337) -------------------------------------------

    /// Writes an executable stub that ignores its arguments and prints `stdout`,
    /// standing in for `gh api graphql` so the poll loop is exercised offline.
    /// Returns the shim lock alongside the path: the caller **must** hold the
    /// guard until the poller has finished exec'ing the stub. Writing an
    /// executable and then `execve`ing it races every other thread that forks —
    /// the child inherits the still-open writable FD and the exec fails
    /// `ETXTBSY`. See [`crate::pr_status`]'s twin helper (#642, #1344).
    fn fake_gh(dir: &Path, stdout: &str) -> (PathBuf, MutexGuard<'static, ()>) {
        let guard = shim_lock();
        let path = dir.join("fake-gh");
        write_exec_script(&path, &format!("#!/bin/sh\ncat <<'JSON'\n{stdout}\nJSON\n"));
        (path, guard)
    }

    /// A [`fake_gh`] that also records **ground truth**: each invocation appends a
    /// byte to a counter file before printing `stdout`. The returned counter path
    /// lets a test assert how many `gh` subprocesses actually ran, independent of
    /// the #1387 request-log counter — so the two can be compared (#1389).
    fn counting_fake_gh(dir: &Path, stdout: &str) -> (PathBuf, MutexGuard<'static, ()>, PathBuf) {
        let guard = shim_lock();
        let path = dir.join("fake-gh");
        let counter = dir.join("gh-calls");
        write_exec_script(
            &path,
            &format!(
                "#!/bin/sh\nprintf x >> {counter:?}\ncat <<'JSON'\n{stdout}\nJSON\n",
                counter = counter.display()
            ),
        );
        (path, guard, counter)
    }

    /// The number of `gh` subprocesses the counting stub recorded (0 if it never
    /// ran) — the length of the counter file.
    fn gh_spawn_count(counter: &Path) -> usize {
        std::fs::read(counter).map_or(0, |b| b.len())
    }

    /// The number of **successful** `kind: "gh"` records the #1387 choke point
    /// wrote to `log` — one NDJSON line per `gh` that ran to a `0` exit. Filtering
    /// on the exit code matches the ground-truth counter (which is written when the
    /// stub *runs*), so a rare failed spawn cannot desync the two.
    fn counted_gh_records(log: &Path) -> usize {
        std::fs::read_to_string(log)
            .unwrap_or_default()
            .lines()
            .filter(|l| l.contains(r#""kind":"gh""#) && l.contains(r#""exit_code":0"#))
            .count()
    }

    /// A repo with a GitHub origin and one commit on `main`.
    fn github_repo(dir: &Path) -> Repository {
        github_repo_with_remote(dir, "git@github.com:rust-works/omni-dev.git")
    }

    /// A repo with a specific GitHub `origin` URL and one commit on `main`, so a
    /// test can register **distinct** targets (owner/name) across windows.
    fn github_repo_with_remote(dir: &Path, url: &str) -> Repository {
        let repo = init_repo(dir);
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        repo.remote("origin", url).unwrap();
        repo
    }

    /// A pending badge whose verdict is about `head_oid`. The commit is explicit
    /// because the fold downgrades a badge naming a different commit than the
    /// worktree's HEAD (#1337) — a fixture that got it wrong would pass for the
    /// wrong reason.
    fn pending_badge(number: u64, head_oid: &str) -> PrBadge {
        PrBadge {
            number,
            is_draft: false,
            checks: PrCheckState::Pending,
            url: "u".into(),
            head_oid: head_oid.to_string(),
        }
    }

    /// Wraps a badge as the cache's resolution value (#1370).
    fn pr(badge: PrBadge) -> PrResolution {
        PrResolution::Pr(badge)
    }

    #[test]
    fn pr_targets_from_snapshot_reads_github_branches_and_dedupes() {
        let snapshot = json!({"repos":[
            {
                "main_repo":"omni-dev",
                "github":{"owner":"rust-works","name":"omni-dev"},
                "root":"/r",
                // Enabled (#1376) — a not-polled repo contributes no targets (see
                // `pr_watch_from_snapshot_skips_a_not_polled_repo`).
                "polling_enabled":true,
                // Two worktrees on the same branch must ask once, not twice.
                "worktrees":[
                    {"path":"/r","branch":"main","is_main":true,"open":true},
                    {"path":"/w1","branch":"main","is_main":false,"open":true},
                    {"path":"/w2","branch":"feature","is_main":false,"open":true},
                    // Detached: no branch, so nothing to resolve.
                    {"path":"/w3","is_main":false,"open":true}
                ]
            },
            {
                // Not on GitHub: contributes no targets at all.
                "main_repo":"local","root":"/l",
                "worktrees":[{"path":"/l","branch":"main","is_main":true,"open":true}]
            }
        ]});
        let targets = pr_targets_from_snapshot(&snapshot);
        assert_eq!(
            targets,
            vec![
                PrTarget {
                    owner: "rust-works".into(),
                    name: "omni-dev".into(),
                    branch: "feature".into()
                },
                PrTarget {
                    owner: "rust-works".into(),
                    name: "omni-dev".into(),
                    branch: "main".into()
                },
            ]
        );
    }

    #[test]
    fn pr_targets_from_snapshot_is_empty_without_repos() {
        assert!(pr_targets_from_snapshot(&json!({"repos":[]})).is_empty());
        assert!(pr_targets_from_snapshot(&json!({})).is_empty());
    }

    #[test]
    fn pr_targets_from_snapshot_skips_a_malformed_github_identity() {
        // Defensive: a `github` object without usable owner/name strings yields no
        // target rather than a half-built query.
        for github in [
            json!({}),
            json!({"owner": "o"}),
            json!({"owner": 1, "name": 2}),
        ] {
            let snapshot = json!({"repos":[{
                "main_repo":"r","github":github,"root":"/r","polling_enabled":true,
                "worktrees":[{"path":"/r","branch":"main","is_main":true,"open":true}]
            }]});
            assert!(
                pr_targets_from_snapshot(&snapshot).is_empty(),
                "{snapshot:?}"
            );
        }
    }

    #[test]
    fn pr_watch_from_snapshot_skips_a_not_polled_repo() {
        // The zero-`gh` guarantee (#1376): a GitHub repo with `polling_enabled`
        // absent (the default-off case) or explicitly false contributes no watch,
        // so the poll never mentions it. Only an enabled repo is polled.
        for repo in [
            json!({
                "main_repo":"omni-dev","github":{"owner":"o","name":"n"},"root":"/r",
                "worktrees":[{"path":"/r","branch":"main","is_main":true,"open":true}]
            }),
            json!({
                "main_repo":"omni-dev","github":{"owner":"o","name":"n"},"root":"/r",
                "polling_enabled":false,
                "worktrees":[{"path":"/r","branch":"main","is_main":true,"open":true}]
            }),
        ] {
            let snapshot = json!({ "repos": [repo] });
            assert!(
                pr_targets_from_snapshot(&snapshot).is_empty(),
                "not-polled repo must yield no targets: {snapshot:?}"
            );
        }
        // Flipping the same repo to enabled makes it contribute.
        let enabled = json!({"repos":[{
            "main_repo":"omni-dev","github":{"owner":"o","name":"n"},"root":"/r",
            "polling_enabled":true,
            "worktrees":[{"path":"/r","branch":"main","is_main":true,"open":true}]
        }]});
        assert_eq!(pr_targets_from_snapshot(&enabled).len(), 1);
    }

    #[test]
    fn pr_should_fetch_when_the_watch_grew_or_the_backoff_elapsed() {
        let backoff = Duration::from_secs(600);
        // Never fetched: go.
        assert!(pr_should_fetch(false, None, backoff));
        // Quiet tree, backoff not elapsed: this is the common tick — wake, look,
        // spend nothing.
        assert!(!pr_should_fetch(
            false,
            Some(Duration::from_secs(1)),
            backoff
        ));
        // Quiet tree, backoff elapsed: time to look again.
        assert!(pr_should_fetch(false, Some(backoff), backoff));
        assert!(pr_should_fetch(false, Some(backoff * 2), backoff));
        // The load-bearing case: the watch grew (a target added, or an upstream
        // pushed), so fetch **now** regardless of how deep the backoff had grown.
        // Without this a push waits out the full ceiling on a stale badge.
        assert!(pr_should_fetch(true, Some(Duration::ZERO), backoff));
        assert!(pr_should_fetch(
            true,
            Some(Duration::from_millis(1)),
            backoff
        ));
    }

    #[test]
    fn next_pr_poll_delay_escalates_within_pending_and_backs_off_when_terminal() {
        let base = Duration::from_secs(10);
        let fresh = Some(Duration::ZERO);
        let stale = Some(PENDING_FAST_WINDOW);
        // Pending and fresh (within the fast window): hold `base`, however long we
        // had backed off for.
        assert_eq!(next_pr_poll_delay(base, base, true, fresh), base);
        assert_eq!(
            next_pr_poll_delay(PENDING_MAX_INTERVAL, base, true, fresh),
            base
        );
        // Pending but past the fast window (a long CI run): escalate — double up to
        // the pending ceiling, never to the terminal one.
        assert_eq!(next_pr_poll_delay(base, base, true, stale), base * 2);
        assert_eq!(
            next_pr_poll_delay(PENDING_MAX_INTERVAL, base, true, stale),
            PENDING_MAX_INTERVAL
        );
        // Pending with nothing having moved yet (`None`) is treated as past the fast
        // window, so a stale-from-boot pending state does not pin `base`.
        assert_eq!(next_pr_poll_delay(base, base, true, None), base * 2);
        // Everything terminal: double…
        assert_eq!(next_pr_poll_delay(base, base, false, fresh), base * 2);
        assert_eq!(next_pr_poll_delay(base * 2, base, false, fresh), base * 4);
        // …up to the terminal ceiling (above the pending one), and never overflow.
        assert_eq!(
            next_pr_poll_delay(MAX_PR_POLL_INTERVAL, base, false, fresh),
            MAX_PR_POLL_INTERVAL
        );
        assert_eq!(
            next_pr_poll_delay(Duration::MAX, base, false, None),
            MAX_PR_POLL_INTERVAL
        );
    }

    /// A watch on one branch with the given upstream tip.
    fn watch(branch: &str, upstream: Option<&str>) -> PrWatch {
        PrWatch {
            target: PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: branch.into(),
            },
            upstream_sha: upstream.map(str::to_string),
        }
    }

    #[test]
    fn pr_watch_grew_fires_on_additions_and_pushes_but_never_on_removals() {
        let a = watch("a", Some("111"));
        let b = watch("b", Some("222"));
        let ab = [a.clone(), b.clone()];
        let just_a = std::slice::from_ref(&a);
        let just_b = std::slice::from_ref(&b);
        // Nothing new: quiet tick.
        assert!(!pr_watch_grew(&ab, &ab));
        // Addition: a new target appeared.
        assert!(pr_watch_grew(just_a, &ab));
        // Pure removal: a window/worktree went away — must NOT fetch (#1389, fix 1).
        assert!(!pr_watch_grew(&ab, just_a));
        // First sight (empty prev, from `None`): everything is new.
        assert!(pr_watch_grew(&[], just_a));
        // A push moves only the upstream — still "grew".
        let a_pushed = [watch("a", Some("999"))];
        assert!(pr_watch_grew(just_a, &a_pushed));
        // Gaining a target while losing another still fetches (the gain wins).
        assert!(pr_watch_grew(just_a, just_b));
    }

    #[test]
    fn budget_throttled_delay_holds_the_floor_only_when_over_warn() {
        let base = Duration::from_secs(10);
        let over = RateLimitSnapshot {
            graphql: Some(rl_resource(90)),
            core: Some(rl_resource(3)),
            search: None,
        };
        let under = RateLimitSnapshot {
            graphql: Some(rl_resource(50)),
            core: Some(rl_resource(3)),
            search: None,
        };
        // No reading yet: unchanged.
        assert_eq!(budget_throttled_delay(base, None), base);
        // Under the warn threshold: unchanged.
        assert_eq!(budget_throttled_delay(base, Some(&under)), base);
        // Over: raised to at least the throttle floor…
        assert_eq!(
            budget_throttled_delay(base, Some(&over)),
            BUDGET_THROTTLE_INTERVAL
        );
        // …but a delay already above the floor is left alone (never shortened).
        let long = BUDGET_THROTTLE_INTERVAL * 2;
        assert_eq!(budget_throttled_delay(long, Some(&over)), long);
    }

    #[test]
    fn pr_cache_prefs_round_trips_through_json_including_head_oid() {
        // The persisted cache must survive a JSON round trip with `head_oid` intact
        // — it is the staleness key the tree wire drops, and losing it would render
        // every restored badge stale (#1389, fix 4).
        let target = PrTarget {
            owner: "rust-works".into(),
            name: "omni-dev".into(),
            branch: "main".into(),
        };
        let badge = PrResolution::Pr(PrBadge {
            number: 1337,
            is_draft: true,
            checks: PrCheckState::Pending,
            url: "http://x/1337".into(),
            head_oid: "deadbeef".into(),
        });
        let watched = vec![watch("main", Some("abc"))];
        let polled_at = DateTime::parse_from_rfc3339("2026-07-21T00:00:00Z")
            .unwrap()
            .with_timezone(&Utc);
        let prefs = pr_cache_prefs_from(vec![(target, badge.clone())], &watched, polled_at);

        let json = serde_json::to_vec(&prefs).unwrap();
        let back: PrCachePrefs = serde_json::from_slice(&json).unwrap();
        assert_eq!(back, prefs);
        assert_eq!(back.polled_at, Some(polled_at));
        assert_eq!(back.watched[0].upstream_sha.as_deref(), Some("abc"));
        // The restored resolution equals the original — head_oid and all.
        assert_eq!(back.entries[0].resolution.clone().into_resolution(), badge);
    }

    #[test]
    fn pr_cache_prefs_round_trip_an_explicit_no_pr_verdict() {
        // The explicit negative must survive persistence too: restoring `NoPr`
        // as "absent" would lose the #1370 distinction across a restart and
        // re-ask GitHub for branches already known to have no PR.
        let target = PrTarget {
            owner: "rust-works".into(),
            name: "omni-dev".into(),
            branch: "feature".into(),
        };
        let prefs = pr_cache_prefs_from(vec![(target, PrResolution::NoPr)], &[], Utc::now());
        let json = serde_json::to_vec(&prefs).unwrap();
        let back: PrCachePrefs = serde_json::from_slice(&json).unwrap();
        assert_eq!(back.entries[0].resolution, PersistedResolution::NoPr);
        assert_eq!(
            back.entries[0].resolution.clone().into_resolution(),
            PrResolution::NoPr
        );
    }

    #[test]
    fn load_pr_cache_without_polled_at_restores_badges_but_no_warm_start() {
        // A file with verdicts but no `polled_at` (an older shape, or a
        // hand-edited one) still renders badges, but must not arm the warm
        // start: without a poll time there is nothing to age the verdicts
        // against, so the poller re-polls immediately (#1389, fix 4).
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("pr-cache.json");
        let target = PrTarget {
            owner: "rust-works".into(),
            name: "omni-dev".into(),
            branch: "main".into(),
        };
        let mut prefs = pr_cache_prefs_from(
            vec![(target, PrResolution::Pr(pending_badge(7, "abc")))],
            &[watch("main", None)],
            Utc::now(),
        );
        prefs.polled_at = None;
        write_pr_cache(&path, &prefs).unwrap();

        let svc = WorktreesService::new();
        svc.load_pr_cache(path);
        assert!(
            svc.pr_cache.get("rust-works", "omni-dev", "main").is_some(),
            "the badge itself must still restore"
        );
        assert!(
            svc.pr_warm_start
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .is_none(),
            "no poll time means a cold start, not a trusted warm one"
        );
    }

    /// Installs a thread-local WARN-level subscriber for the duration of a
    /// test, so degraded-path `tracing::warn!` sites actually format their
    /// fields instead of short-circuiting on "nobody is listening".
    fn warn_subscriber() -> tracing::subscriber::DefaultGuard {
        tracing::subscriber::set_default(
            tracing_subscriber::fmt()
                .with_max_level(tracing::Level::WARN)
                .with_writer(std::io::sink)
                .finish(),
        )
    }

    #[test]
    fn load_pr_cache_tolerates_a_corrupt_or_unreadable_file() {
        // The best-effort contract: a mangled cache is logged and treated as
        // empty — never a panic — and the path is stored regardless, so the
        // next successful poll rewrites a clean file (#1389, fix 4).
        let _trace = warn_subscriber();
        let dir = tempfile::tempdir().unwrap();
        let corrupt = dir.path().join("pr-cache.json");
        std::fs::write(&corrupt, b"not json").unwrap();
        let svc = WorktreesService::new();
        svc.load_pr_cache(corrupt.clone());
        assert!(svc.pr_cache.entries().is_empty());
        assert_eq!(
            svc.pr_cache_path
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .as_deref(),
            Some(corrupt.as_path()),
            "the path must be stored even when the load fails, so persistence recovers"
        );

        // A directory: `read` fails with a non-NotFound error (the distinct
        // "could not read" arm), with the same treated-as-empty outcome.
        let svc = WorktreesService::new();
        svc.load_pr_cache(dir.path().to_path_buf());
        assert!(svc.pr_cache.entries().is_empty());
    }

    #[test]
    fn persist_pr_cache_swallows_a_write_failure() {
        // Best-effort: an unwritable path is logged at WARN and swallowed — the
        // in-memory cache stays authoritative, and losing the warm start only
        // costs one extra poll after the next restart.
        let _trace = warn_subscriber();
        let dir = tempfile::tempdir().unwrap();
        let blocker = dir.path().join("blocker");
        std::fs::write(&blocker, b"").unwrap();
        // The parent is a regular file, so creating the runtime dir must fail.
        let path = blocker.join("pr-cache.json");
        persist_pr_cache(&path, &PrStatusCache::new(), &[], Utc::now());
        assert!(!path.exists());
        // The root has no parent at all — nothing to create, and the write
        // itself fails (it is a directory); still swallowed.
        persist_pr_cache(Path::new("/"), &PrStatusCache::new(), &[], Utc::now());
    }

    #[tokio::test]
    async fn tree_snapshot_folds_cached_pr_badges_onto_matching_branches() {
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap().to_string();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);

        // No poll has landed: the badge is absent, exactly as a pre-#1337 daemon —
        // and so is the negative, so "not resolved" stays distinguishable (#1370).
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(wt.get("pr").is_none(), "{wt:?}");
        assert!(wt.get("pr_none").is_none(), "{wt:?}");

        // Seed the cache the poller writes, then re-read the tree.
        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(pending_badge(1337, &head)),
        );
        assert!(svc.pr_cache.replace(badges));

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr"]["number"], json!(1337));
        assert_eq!(wt["pr"]["checks"], json!("pending"));
        // camelCase on the wire, or the extension silently loses the draft marker.
        assert_eq!(wt["pr"]["isDraft"], json!(false));
        // A badge and the negative are mutually exclusive.
        assert!(wt.get("pr_none").is_none(), "{wt:?}");
    }

    #[tokio::test]
    async fn tree_snapshot_omits_a_badge_for_a_detached_worktree() {
        // A detached HEAD has a commit but no branch, and a badge is keyed by
        // branch — so there is nothing to match. It must fall through silently
        // rather than borrow a badge from whatever branch happens to be cached, and
        // rather than sink the tree.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap();
        repo.set_head_detached(head).unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        // A badge *is* cached for `main` — the branch this worktree was on before
        // detaching. It must not leak onto the now-branchless row.
        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(pending_badge(1, &head.to_string())),
        );
        svc.pr_cache.replace(badges);

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(wt.get("branch").is_none(), "{wt:?}");
        // The SHA still shows — detached means no branch, not no commit.
        assert_eq!(
            wt.get("head_sha").and_then(Value::as_str),
            Some(head.to_string().as_str())
        );
        assert!(wt.get("pr").is_none(), "{wt:?}");
        // No branch means nothing was checked either: no negative on the row.
        assert!(wt.get("pr_none").is_none(), "{wt:?}");
    }

    #[tokio::test]
    async fn tree_snapshot_omits_a_badge_for_an_unmatched_branch() {
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        // A badge for a different branch must not leak onto `main`.
        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "other".into(),
            },
            pr(pending_badge(1, "irrelevant")),
        );
        svc.pr_cache.replace(badges);
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert!(wt.get("pr").is_none(), "{wt:?}");
        // An unmatched branch is unresolved, not negative.
        assert!(wt.get("pr_none").is_none(), "{wt:?}");
    }

    #[tokio::test]
    async fn tree_snapshot_reports_an_explicit_negative_for_a_branch_with_no_pr() {
        // The #1370 fix on the wire: a branch the poller checked and found PR-less
        // carries `pr_none: true` — never a sentinel `pr` object — so a client can
        // tell "checked, none" from "not resolved" and keep its fallback quiet.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);

        let mut resolutions = HashMap::new();
        resolutions.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            PrResolution::NoPr,
        );
        assert!(svc.pr_cache.replace(resolutions));

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr_none"], json!(true));
        // Mutually exclusive with a badge.
        assert!(wt.get("pr").is_none(), "{wt:?}");
    }

    #[tokio::test]
    async fn a_commit_does_not_drop_a_negative_resolution() {
        // A negative has no commit to be stale against. Dropping it when HEAD
        // moves would flip the row back to "unresolved" on every local commit —
        // re-arming every client's `gh` fallback, the very cost #1370 removes. The
        // poller's `moved` trigger re-checks the branch promptly instead.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let first = repo.head().unwrap().target().unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);

        let mut resolutions = HashMap::new();
        resolutions.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            PrResolution::NoPr,
        );
        svc.pr_cache.replace(resolutions);

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr_none"], json!(true));

        // Commit — as a push would leave things, with the cache untouched.
        let head = repo.find_commit(first).unwrap();
        empty_commit(&repo, Some("refs/heads/main"), &[&head], "B");

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(
            wt["pr_none"],
            json!(true),
            "a local commit must not drop the negative"
        );
    }

    #[tokio::test]
    async fn pr_poller_asks_nothing_while_no_window_is_registered() {
        // The idle case — the daemon runs all day with no editor open. Point it at a
        // stub that fails loudly if ever spawned: a poll here would both waste
        // GitHub budget and, on a real `gh`, wake the radio for nothing.
        let bin_dir = tempfile::tempdir().unwrap();
        let marker = bin_dir.path().join("spawned");
        let fake = bin_dir.path().join("fake-gh");
        std::fs::write(
            &fake,
            format!("#!/bin/sh\ntouch '{}'\necho '{{}}'\n", marker.display()),
        )
        .unwrap();
        let mut perms = std::fs::metadata(&fake).unwrap().permissions();
        std::os::unix::fs::PermissionsExt::set_mode(&mut perms, 0o755);
        std::fs::set_permissions(&fake, perms).unwrap();

        let svc = WorktreesService::new();
        svc.start_pr_poller_with(Duration::from_millis(20), Duration::from_millis(10), fake);
        tokio::time::sleep(Duration::from_millis(200)).await;
        svc.shutdown().await;
        assert!(
            !marker.exists(),
            "the poller must not spawn gh with no windows registered"
        );
    }

    #[tokio::test]
    async fn pr_poller_survives_a_failing_gh_and_keeps_the_last_good_badges() {
        // Badges are decoration: an unauthenticated or broken `gh` must never sink
        // the tree, and one bad poll must not blank rows that were fine a second ago.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap().to_string();
        let bin_dir = tempfile::tempdir().unwrap();
        let fake = bin_dir.path().join("fake-gh");
        // Exits non-zero, exactly as `gh` does without `gh auth login`.
        std::fs::write(
            &fake,
            "#!/bin/sh\necho 'gh: not authenticated' >&2\nexit 1\n",
        )
        .unwrap();
        let mut perms = std::fs::metadata(&fake).unwrap().permissions();
        std::os::unix::fs::PermissionsExt::set_mode(&mut perms, 0o755);
        std::fs::set_permissions(&fake, perms).unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        // Seed a badge as though an earlier poll had succeeded.
        let mut seeded = HashMap::new();
        seeded.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(pending_badge(7, &head)),
        );
        svc.pr_cache.replace(seeded);

        svc.start_pr_poller_with(Duration::from_millis(20), Duration::from_millis(10), fake);
        tokio::time::sleep(Duration::from_millis(200)).await;

        // The tree still serves, and the seeded badge survived the failing polls —
        // which also minted no false "no PR" negatives (#1370).
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr"]["number"], json!(7));
        assert!(wt.get("pr_none").is_none(), "{wt:?}");
        svc.shutdown().await;
    }

    #[tokio::test]
    // The shim guard is deliberately held across the awaits below: it must span
    // both the stub's write *and* the poller's exec of it, since the ETXTBSY race
    // is against another test writing while this one forks. Safe here — only test
    // threads take it, never a task inside the runtime, so it cannot deadlock.
    // Scoped per-test rather than on the module, which would also silence the
    // registry lock's "never held across .await" invariant.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_wakes_when_the_first_window_opens_after_an_idle_start() {
        // The normal startup order: the daemon starts at login, *before* any
        // editor. It therefore sees an empty tree and backs off to the 30-minute
        // ceiling — so unless a register wakes it, the first badge of the session
        // arrives up to half an hour after the window does, which reads as the
        // feature being broken rather than slow.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"a","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"IN_PROGRESS","conclusion":null}
                ]}}},
                "associatedPullRequests":{"nodes":[{"number":99,"isDraft":false,"url":"u"}]}
            }}}}"#,
        );

        let svc = WorktreesService::new();
        // Poller first, with nothing registered — it backs off on the empty tree.
        svc.start_pr_poller_with(Duration::from_millis(50), Duration::from_millis(10), fake);
        tokio::time::sleep(Duration::from_millis(150)).await;

        // Now an editor opens.
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);

        // The badge must follow promptly — the register wakes the loop out of its
        // backoff. The deadline is orders of magnitude below the ceiling, so this
        // fails on the bug rather than merely being slow.
        let badge = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if let Some(PrResolution::Pr(badge)) =
                    svc.pr_cache.get("rust-works", "omni-dev", "main")
                {
                    return badge;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("a window opening must wake the poller out of its idle backoff");
        assert_eq!(badge.number, 99);
        svc.shutdown().await;
    }

    #[tokio::test]
    async fn a_commit_invalidates_the_previous_verdict_without_a_poll() {
        // The acceptance criterion: "pushing a new commit invalidates the badge
        // rather than leaving the previous head's verdict standing."
        //
        // The cache still holds the verdict for the *old* commit, and the poller may
        // have backed off for up to half an hour. So the fold — which runs on every
        // snapshot — has to notice on its own, with no network call.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let first = repo.head().unwrap().target().unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);

        // A green verdict, correctly describing the commit currently checked out.
        let mut badges = HashMap::new();
        badges.insert(
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "main".into(),
            },
            pr(PrBadge {
                number: 1337,
                is_draft: false,
                checks: PrCheckState::Success,
                url: "u".into(),
                head_oid: first.to_string(),
            }),
        );
        svc.pr_cache.replace(badges);

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(
            wt["pr"]["checks"],
            json!("success"),
            "green for its own commit"
        );

        // Now commit — as a push would leave things, with the cache untouched.
        let head = repo.find_commit(first).unwrap();
        empty_commit(&repo, Some("refs/heads/main"), &[&head], "B");

        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(
            wt["pr"]["checks"],
            json!("pending"),
            "the previous commit's ✓ must not stand after a new commit"
        );
        // The PR itself is still shown — it is the *verdict* that is unknown, not
        // the PR.
        assert_eq!(wt["pr"]["number"], json!(1337));
    }

    #[test]
    fn is_stale_for_compares_the_commit_the_verdict_describes() {
        let badge = pending_badge(1, "aaa");
        assert!(!badge.is_stale_for(Some("aaa")));
        assert!(badge.is_stale_for(Some("bbb")));
        // No local HEAD (unborn): nothing to compare against, so not stale.
        assert!(!badge.is_stale_for(None));
    }

    #[test]
    fn pr_watch_ignores_the_head_so_a_local_commit_asks_nothing() {
        // #1389, fix 3. A local commit moves only the head — GitHub has not seen
        // it — so asking would return exactly the cached verdict, and the badge
        // stays correctly stale via `is_stale_for` with no network. So a snapshot
        // that differs *only* in `head_sha` must compare **equal** as a watch.
        let snap = |sha: &str| {
            json!({"repos":[{
                "main_repo":"omni-dev",
                "github":{"owner":"rust-works","name":"omni-dev"},
                "root":"/r",
                "polling_enabled":true,
                "worktrees":[{"path":"/r","branch":"main","head_sha":sha,"is_main":true,"open":true}]
            }]})
        };
        let before = pr_watch_from_snapshot(&snap("aaa"));
        let after = pr_watch_from_snapshot(&snap("bbb"));
        assert_eq!(before.len(), 1);
        assert_eq!(before[0].target, after[0].target);
        // The head moved, but the watch did not — no fetch trigger, no `gh` call.
        assert_eq!(before, after);
        assert!(!pr_watch_grew(&before, &after));
    }

    #[test]
    fn pr_watch_tracks_the_upstream_so_a_push_is_visible_to_the_poller() {
        // #1344's bonus. A push is what *starts* the CI run a badge reports, yet
        // it moves no local head — so an upstream move alone must register as "go
        // and ask now", or the badge sits at `●` until the backoff elapses.
        let snap = |upstream: &str| {
            json!({"repos":[{
                "main_repo":"omni-dev",
                "github":{"owner":"rust-works","name":"omni-dev"},
                "root":"/r",
                "polling_enabled":true,
                "worktrees":[{"path":"/r","branch":"main","head_sha":"aaa",
                              "upstream_sha":upstream,"is_main":true,"open":true}]
            }]})
        };
        let before = pr_watch_from_snapshot(&snap("aaa"));
        let after = pr_watch_from_snapshot(&snap("bbb"));
        // Same target, only the upstream moved — a genuine "grew" signal.
        assert_eq!(before.len(), 1);
        assert_eq!(before[0].target, after[0].target);
        assert_ne!(before, after);
        assert!(pr_watch_grew(&before, &after));
        // A quiet tick still asks nothing.
        assert_eq!(before, pr_watch_from_snapshot(&snap("aaa")));
        assert!(!pr_watch_grew(
            &before,
            &pr_watch_from_snapshot(&snap("aaa"))
        ));
    }

    #[test]
    fn pr_watch_omits_an_absent_upstream_rather_than_erroring() {
        // An older daemon — or any branch tracking nothing — simply sends no
        // `upstream_sha`, which reads as `None` rather than failing the poll.
        let snap = json!({"repos":[{
            "main_repo":"omni-dev",
            "github":{"owner":"rust-works","name":"omni-dev"},
            "root":"/r",
            "polling_enabled":true,
            "worktrees":[{"path":"/r","branch":"main","head_sha":"aaa","is_main":true,"open":true}]
        }]});
        let watch = pr_watch_from_snapshot(&snap);
        assert_eq!(watch.len(), 1);
        assert_eq!(watch[0].upstream_sha, None);
    }

    #[test]
    fn start_pr_poller_is_a_noop_outside_a_runtime() {
        let svc = WorktreesService::new();
        svc.start_pr_poller();
        assert!(svc
            .poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .is_none());
    }

    #[tokio::test]
    async fn start_pr_poller_is_idempotent_and_shutdown_stops_it() {
        let svc = WorktreesService::new();
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            PathBuf::from("/bin/true"),
        );
        let token = svc
            .poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .as_ref()
            .map(|t| t.token.clone())
            .expect("poller started");

        // Cancel the live task, then start again: if `start` spawned a replacement
        // it would orphan this one, so the token staying cancelled proves it did not.
        token.cancel();
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            PathBuf::from("/bin/true"),
        );
        assert!(svc
            .poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .as_ref()
            .is_some_and(|t| t.token.is_cancelled()));

        svc.shutdown().await;
        assert!(svc
            .poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .is_none());
    }

    // --- Rate-limit monitor (#1375) ---

    /// A resource at `used`% of a 100-request budget.
    fn rl_resource(used: u64) -> RateLimitResource {
        RateLimitResource {
            used,
            limit: 100,
            remaining: 100 - used,
            percent: used as f64,
            reset: 0,
        }
    }

    #[test]
    fn rate_limit_crossed_warn_fires_only_on_the_rising_edge() {
        let snap = |graphql: u64, core: u64| RateLimitSnapshot {
            graphql: Some(rl_resource(graphql)),
            core: Some(rl_resource(core)),
            search: None,
        };
        // First poll already over threshold → warn.
        assert!(rate_limit_crossed_warn(None, &snap(85, 3)));
        // First poll below → no warn.
        assert!(!rate_limit_crossed_warn(None, &snap(50, 3)));
        // Crossing upward → warn.
        assert!(rate_limit_crossed_warn(Some(&snap(70, 3)), &snap(85, 3)));
        // Staying over → no repeat warn.
        assert!(!rate_limit_crossed_warn(Some(&snap(85, 3)), &snap(90, 3)));
        // Recovering below → no warn.
        assert!(!rate_limit_crossed_warn(Some(&snap(85, 3)), &snap(50, 3)));
        // A *different* resource crossing while the first recovers is still caught.
        assert!(rate_limit_crossed_warn(Some(&snap(85, 3)), &snap(50, 90)));
    }

    #[test]
    fn start_rate_limit_poller_is_a_noop_outside_a_runtime() {
        let svc = WorktreesService::new();
        svc.start_rate_limit_poller();
        assert!(svc
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .is_none());
    }

    #[tokio::test]
    async fn start_rate_limit_poller_is_idempotent_and_shutdown_stops_it() {
        let svc = WorktreesService::new();
        svc.start_rate_limit_poller_with(Duration::from_millis(50), PathBuf::from("/bin/true"));
        let token = svc
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .as_ref()
            .map(|t| t.token.clone())
            .expect("poller started");

        // Cancel the live task, then start again: a second start must not spawn a
        // replacement (which would orphan this one), so the token stays cancelled.
        token.cancel();
        svc.start_rate_limit_poller_with(Duration::from_millis(50), PathBuf::from("/bin/true"));
        assert!(svc
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .as_ref()
            .is_some_and(|t| t.token.is_cancelled()));

        svc.shutdown().await;
        assert!(svc
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .is_none());
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn rate_limit_poller_resolves_via_gh_populates_the_cache_and_stops_on_shutdown() {
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"resources":{
                "graphql":{"limit":5000,"used":4100,"remaining":900,"reset":1700000000},
                "core":{"limit":5000,"used":27,"remaining":4973,"reset":1700000000}
            }}"#,
        );
        let svc = WorktreesService::new();
        // #1389, fix 8b: the poller only spends a `/rate_limit` call while something
        // is being watched — a lease makes it active without needing a window/folder.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_rate_limit_poller_with(Duration::from_millis(50), fake.clone());

        // Each poll spawns a real subprocess; wait on a generous deadline so a
        // loaded machine fails honestly rather than flaking.
        let snap = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if let Some(snap) = svc.rate_limit_cache.get() {
                    return snap;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("poller should populate the cache through the fake gh");
        assert_eq!(snap.graphql.unwrap().used, 4100);
        assert_eq!(snap.core.unwrap().used, 27);

        // The reading reaches the built-in status field via the shared cache.
        assert!(svc.rate_limit_cache().get().is_some());

        svc.shutdown().await;
        assert!(svc
            .rate_limit_poller
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .is_none());
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn rate_limit_poller_stays_idle_with_nothing_registered() {
        // #1389, fix 8b: a fully-idle daemon (no window, no lease) spends no
        // `/rate_limit` subprocess — the counting stub records zero spawns.
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim, counter) = counting_fake_gh(
            bin_dir.path(),
            r#"{"resources":{"graphql":{"limit":5000,"used":1,"remaining":4999,"reset":1}}}"#,
        );
        let svc = WorktreesService::new();
        svc.start_rate_limit_poller_with(Duration::from_millis(20), fake);

        // Give the loop several ticks; with nothing registered it must never poll.
        tokio::time::sleep(Duration::from_millis(300)).await;
        assert_eq!(
            gh_spawn_count(&counter),
            0,
            "idle daemon must not poll (#1389, fix 8b)"
        );
        assert!(svc.rate_limit_cache.get().is_none());

        // Once a lease is active, the next tick populates the cache.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if svc.rate_limit_cache.get().is_some() {
                    return;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("an active lease should resume polling");
        assert!(gh_spawn_count(&counter) >= 1);
        svc.shutdown().await;
    }

    #[tokio::test]
    async fn rate_limit_poller_survives_a_failing_gh() {
        // A missing/failing `gh` leaves the cache empty and never wedges the loop —
        // the degraded branch keeps the last (here, absent) reading rather than
        // crashing. Active via a lease so the gate (#1389, fix 8b) lets it try.
        let svc = WorktreesService::new();
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_rate_limit_poller_with(
            Duration::from_millis(20),
            PathBuf::from("/no/such/gh/xyzzy"),
        );
        // Let it fail a few times: the cache stays empty and the task stays alive.
        tokio::time::sleep(Duration::from_millis(150)).await;
        assert!(svc.rate_limit_cache.get().is_none());
        assert!(
            svc.rate_limit_poller
                .lock()
                .unwrap_or_else(PoisonError::into_inner)
                .is_some(),
            "the loop must survive a failing gh, not panic out"
        );
        svc.shutdown().await;
    }

    #[test]
    fn menu_prepends_the_rate_limit_line_only_when_the_cache_is_populated() {
        let svc = WorktreesService::new();
        // Empty cache → no rate-limit line (the pre-#1375 shape).
        let items = svc.menu().items;
        assert!(
            !items
                .iter()
                .any(|i| matches!(i, MenuItem::Label(l) if l.contains("github:"))),
            "no github line before the first poll"
        );

        // Populate the cache → the first item is the rate-limit status line.
        svc.rate_limit_cache.replace(RateLimitSnapshot {
            graphql: Some(rl_resource(82)),
            core: Some(rl_resource(3)),
            search: None,
        });
        let items = svc.menu().items;
        assert!(
            matches!(items.first(), Some(MenuItem::Label(l)) if l.starts_with("github: graphql 82%")),
            "expected the github line first, got {items:?}"
        );
        assert!(
            matches!(items.get(1), Some(MenuItem::Separator)),
            "expected a separator after the github line"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_resolves_via_gh_populates_the_cache_and_stops_on_shutdown() {
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        // One repo, one branch → aliases r0/b0. A still-running check so the badge
        // stays pending and the loop keeps its fast cadence.
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"abc","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"IN_PROGRESS","conclusion":null}
                ]}}},
                "associatedPullRequests":{"nodes":[{"number":1337,"isDraft":false,"url":"http://x/1337"}]}
            }}}}"#,
        );
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            fake.clone(),
        );

        // Wait on a generous wall-clock deadline: each poll spawns a real
        // subprocess, and under a loaded machine (a full `build.sh` runs a build
        // and clippy alongside) a tight budget flakes rather than fails honestly.
        let badge = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if let Some(PrResolution::Pr(badge)) =
                    svc.pr_cache.get("rust-works", "omni-dev", "main")
                {
                    return badge;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("poller should resolve a badge through the fake gh");
        assert_eq!(badge.number, 1337);
        assert_eq!(badge.checks, crate::pr_status::PrCheckState::Pending);

        // The badge reaches the wire the windows actually read.
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr"]["number"], json!(1337));

        // And the loop is quiescent after shutdown: the generation must stop moving.
        svc.shutdown().await;
        let generation = svc.registry.change_generation();
        tokio::time::sleep(Duration::from_millis(120)).await;
        assert_eq!(
            svc.registry.change_generation(),
            generation,
            "no bumps after shutdown"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poll_folds_its_graphql_budget_into_the_rate_limit_cache() {
        // #1389, fix 8a: every PR poll carries a free graphql budget reading, which
        // the poller folds into the shared cache — so the graphql figure stays fresh
        // without a standalone `/rate_limit` call.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{
                "rateLimit":{"limit":5000,"cost":1,"remaining":4877,"used":123,
                             "resetAt":"2026-07-21T16:00:00Z"},
                "r0":{"b0":{
                  "target":{"oid":"abc","statusCheckRollup":{"contexts":{"nodes":[
                    {"__typename":"CheckRun","status":"IN_PROGRESS","conclusion":null}
                  ]}}},
                  "associatedPullRequests":{"nodes":[{"number":1337,"isDraft":false,"url":"http://x/1337"}]}
                }}
            }}"#,
        );
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.registry.set_polling("rust-works", "omni-dev", true);
        // No rate-limit poller started: the only writer of the cache is the PR poll's
        // folded-in budget, so a populated graphql reading proves fix 8a.
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            fake.clone(),
        );

        let graphql = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if let Some(g) = svc.rate_limit_cache.get().and_then(|s| s.graphql) {
                    return g;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("the PR poll should fold its budget into the cache");
        assert_eq!(graphql.used, 123);
        assert_eq!(graphql.limit, 5000);
        assert_eq!(graphql.remaining, 4877);
        svc.shutdown().await;
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poll_counts_every_gh_call_exactly_once() {
        // #1389's non-negotiable constraint (#1387): fewer calls, but every call
        // still counted. Compares the ground-truth number of `gh` subprocesses the
        // poll actually spawned against the number of successful `kind:"gh"` records
        // the counted `run_gh` choke point wrote — they must be equal, so a future
        // refactor cannot add an uncounted `gh` path (counted < spawns) without
        // failing here.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim, counter) = counting_fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"abc","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"IN_PROGRESS","conclusion":null}
                ]}}},
                "associatedPullRequests":{"nodes":[{"number":1337,"isDraft":false,"url":"http://x/1337"}]}
            }}}}"#,
        );
        let log = bin_dir.path().join("log.jsonl");
        std::env::set_var("OMNI_DEV_LOG_FILE", &log);

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_pr_poller_with(Duration::from_millis(30), Duration::from_millis(10), fake);

        // Wait for at least one fetch to land.
        tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if svc.pr_cache.get("rust-works", "omni-dev", "main").is_some() {
                    return;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("poller should fetch through the fake gh");

        // Stop the loop so both counts are final (no in-flight gh), then compare.
        svc.shutdown().await;
        let spawns = gh_spawn_count(&counter);
        let counted = counted_gh_records(&log);
        std::env::remove_var("OMNI_DEV_LOG_FILE");
        assert!(
            spawns >= 1,
            "the poll should have spent at least one gh call"
        );
        assert_eq!(
            counted, spawns,
            "#1387: every gh call ({spawns}) must be counted exactly once, got {counted}"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poll_debounces_a_registration_storm_into_one_fetch() {
        // #1389, fix 2: a burst of registrations (a VS Code restart re-registering
        // its windows) that each *grow* the watch must collapse into ONE fetch on
        // the final set, not one per window. Two distinct repos appear back-to-back
        // inside the debounce window; a debounce-free loop would fetch twice.
        let dir_a = tempfile::tempdir().unwrap();
        let dir_b = tempfile::tempdir().unwrap();
        github_repo(dir_a.path()); // rust-works/omni-dev → alias r0
        github_repo_with_remote(dir_b.path(), "git@github.com:rust-works/other-repo.git"); // r1
        let bin_dir = tempfile::tempdir().unwrap();
        // Both terminal, so no fast pending cadence can add a second fetch.
        let (fake, _shim, counter) = counting_fake_gh(
            bin_dir.path(),
            r#"{"data":{
                "r0":{"b0":{"target":{"oid":"a","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"COMPLETED","conclusion":"SUCCESS"}]}}},
                  "associatedPullRequests":{"nodes":[{"number":1,"isDraft":false,"url":"http://x/1"}]}}},
                "r1":{"b0":{"target":{"oid":"b","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"COMPLETED","conclusion":"SUCCESS"}]}}},
                  "associatedPullRequests":{"nodes":[{"number":2,"isDraft":false,"url":"http://x/2"}]}}}
            }}"#,
        );
        let svc = WorktreesService::new();
        // Enable polling for both before they register, so the first snapshot after
        // the storm already counts them.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.registry.set_polling("rust-works", "other-repo", true);
        // `base` far larger than the test so only the storm — never the cadence —
        // can trigger a fetch; a generous debounce so the two registers land inside
        // one settle window even on a loaded machine.
        svc.start_pr_poller_with(Duration::from_secs(30), Duration::from_millis(200), fake);
        // The burst: both windows register back-to-back.
        svc.handle(
            "register",
            json!({ "key": "a", "folders": [dir_a.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // A beat between the two, so the first bump has (all but certainly)
        // woken the poller into its settle window before the second arrives —
        // exercising the debounce *restart*, not just a single coalesced wake.
        tokio::time::sleep(Duration::from_millis(50)).await;
        svc.handle(
            "register",
            json!({ "key": "b", "folders": [dir_b.path()], "repo": "other-repo" }),
        )
        .await
        .unwrap();

        // Wait until both badges resolve — proving the single fetch covered the full
        // final set, not just the first window.
        tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                let a = svc.pr_cache.get("rust-works", "omni-dev", "main").is_some();
                let b = svc
                    .pr_cache
                    .get("rust-works", "other-repo", "main")
                    .is_some();
                if a && b {
                    return;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("the debounced fetch should resolve both repos");

        svc.shutdown().await;
        assert_eq!(
            gh_spawn_count(&counter),
            1,
            "the registration storm must collapse into exactly one fetch (#1389, fix 2)"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poll_debounce_deadline_bounds_a_steady_drip_of_changes() {
        // The settle loop is bounded: a drip of registry bumps, each landing
        // inside the debounce window, must not postpone the poll forever — the
        // overall deadline (4× the debounce) forces the snapshot mid-storm
        // (#1389, fix 2).
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim, counter) = counting_fake_gh(bin_dir.path(), "{}");
        let svc = WorktreesService::new();
        svc.registry.set_polling("rust-works", "omni-dev", true);
        // `base` far past the timeout below, so only the grew-trigger — released by
        // the deadline — can fetch; a base the drip could outlive would let the
        // periodic cadence satisfy the assertion on a very slow run (#1426).
        svc.start_pr_poller_with(Duration::from_secs(300), Duration::from_millis(50), fake);
        let register = json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" });
        svc.handle("register", register.clone()).await.unwrap();
        // Re-register (an upsert, but still a bump) every 25ms — inside the 50ms
        // debounce — until the deadline-forced fetch actually lands. The observation
        // point is the condition itself, never a clock: sampling the counter at a
        // fixed instant would additionally assert that a `fork` + `exec` + `/bin/sh`
        // startup + file append all beat that instant, which is what made this flaky
        // under full-suite load (#1426). Under load the drip just runs longer. Every
        // iteration bumps, so the fetch is still observed *while bumps are arriving*
        // — a deadline-free settle loop never fetches here at all, and the timeout
        // *is* the assertion.
        let forced_mid_drip = tokio::time::timeout(Duration::from_secs(10), async {
            loop {
                tokio::time::sleep(Duration::from_millis(25)).await;
                svc.handle("register", register.clone()).await.unwrap();
                if gh_spawn_count(&counter) >= 1 {
                    return;
                }
            }
        })
        .await;
        svc.shutdown().await;
        forced_mid_drip.expect(
            "the deadline must force a fetch while the drip is still running (#1389, fix 2)",
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_skips_the_immediate_fetch_when_the_warm_cache_is_fresh() {
        // #1389, fix 4: a daemon restart within the backoff window serves badges
        // from the persisted cache and spends **no** gh call, because every current
        // target already has a fresh verdict.
        let dir = tempfile::tempdir().unwrap();
        let repo = github_repo(dir.path());
        let head = repo.head().unwrap().target().unwrap().to_string();
        let bin_dir = tempfile::tempdir().unwrap();
        // If the poller wrongly fetched, this empty reply would still spawn the stub
        // and bump the counter — which is exactly what the assertion catches.
        let (fake, _shim, counter) = counting_fake_gh(bin_dir.path(), "{}");

        // Persist a fresh cache the way the previous daemon would have: a badge for
        // `main` whose verdict is about the current head (so it is not stale),
        // watched at `(main, no upstream)`, resolved just now.
        let cache_path = bin_dir.path().join("pr-cache.json");
        let target = PrTarget {
            owner: "rust-works".into(),
            name: "omni-dev".into(),
            branch: "main".into(),
        };
        let prefs = pr_cache_prefs_from(
            vec![(target, PrResolution::Pr(pending_badge(1337, &head)))],
            &[watch("main", None)],
            Utc::now(),
        );
        write_pr_cache(&cache_path, &prefs).unwrap();

        let svc = WorktreesService::new();
        svc.load_pr_cache(cache_path);
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // `base` far larger than the test: the only fetch that could happen is the
        // immediate one we expect the warm cache to skip.
        svc.start_pr_poller_with(Duration::from_secs(30), Duration::from_millis(10), fake);

        // The restored badge renders on the wire without a gh call.
        let number = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                let tree = svc.handle("tree", Value::Null).await.unwrap();
                if let Some(n) = repos_of(&tree)
                    .first()
                    .and_then(|r| r["worktrees"][0]["pr"]["number"].as_u64())
                {
                    return n;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("the restored badge should render from the warm cache");
        assert_eq!(number, 1337);

        // Let the poller run a while, then confirm it stayed quiet.
        tokio::time::sleep(Duration::from_millis(300)).await;
        svc.shutdown().await;
        assert_eq!(
            gh_spawn_count(&counter),
            0,
            "a fresh warm cache must skip the immediate re-poll (#1389, fix 4)"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_persists_fresh_verdicts_for_the_next_warm_start() {
        // #1389, fix 4, write side (the twin of the skip test above, which reads
        // a hand-written file): a successful resolve persists the cache —
        // creating the runtime dir if needed — so the *next* daemon restart
        // warm-starts from it.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"abc","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"COMPLETED","conclusion":"SUCCESS"}]}}},
                "associatedPullRequests":{"nodes":[{"number":41,"isDraft":false,"url":"u"}]}
            }}}}"#,
        );
        let svc = WorktreesService::new();
        // No file yet, and no parent dir either: the load takes the benign
        // NotFound arm, and the write must create the `0700` runtime dir.
        let cache_path = bin_dir.path().join("runtime").join("pr-cache.json");
        svc.load_pr_cache(cache_path.clone());
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.start_pr_poller_with(Duration::from_millis(50), Duration::from_millis(10), fake);

        // A partially-written or not-yet-written file simply retries: only a
        // fully parseable cache ends the wait.
        let prefs = tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if let Ok(bytes) = std::fs::read(&cache_path) {
                    if let Ok(prefs) = serde_json::from_slice::<PrCachePrefs>(&bytes) {
                        if !prefs.entries.is_empty() {
                            return prefs;
                        }
                    }
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("a successful resolve should persist the cache file");
        svc.shutdown().await;

        assert_eq!(prefs.entries[0].target.branch, "main");
        assert!(
            matches!(&prefs.entries[0].resolution, PersistedResolution::Pr(b) if b.number == 41),
            "{:?}",
            prefs.entries[0].resolution
        );
        assert_eq!(
            prefs.watched,
            vec![PersistedWatch {
                target: prefs.entries[0].target.clone(),
                upstream_sha: None
            }]
        );
        assert!(
            prefs.polled_at.is_some(),
            "the poll time is what ages the next warm start"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn open_prs_op_serves_from_gh_then_dedupes_within_the_ttl() {
        // #1389, fix 7: the daemon serves "Open Pull Request…" so N windows dedupe
        // to one counted `gh pr list` per repo. A generous TTL, so the second call
        // is served from the cache and spawns **no** second `gh` — the whole point.
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim, counter) = counting_fake_gh(
            bin_dir.path(),
            r#"[{"number":42,"title":"T","url":"http://x/42","headRefName":"feat",
                "baseRefName":"main","isDraft":false,"state":"OPEN","author":{"login":"me"}}]"#,
        );
        let svc = WorktreesService::new();

        let prs = svc
            .open_prs_with("rust-works", "omni-dev", fake.clone())
            .await
            .expect("gh pr list should resolve");
        assert_eq!(prs.len(), 1);
        assert_eq!(prs[0]["number"], json!(42));
        assert_eq!(prs[0]["url"], json!("http://x/42"));
        assert_eq!(gh_spawn_count(&counter), 1, "first call spends one gh");

        // A second window asking the same repo is served from the shared cache.
        let again = svc
            .open_prs_with("rust-works", "omni-dev", fake.clone())
            .await
            .expect("cache hit should resolve");
        assert_eq!(again, prs);
        assert_eq!(
            gh_spawn_count(&counter),
            1,
            "the second lookup must dedupe to the cached result, not a new gh (#1389, fix 7)"
        );

        // The op wrapper shapes the reply and validates the payload.
        let reply = svc
            .handle(
                "open-prs",
                json!({ "owner": "rust-works", "name": "omni-dev" }),
            )
            .await
            .expect("open-prs op should route");
        assert_eq!(reply["pull_requests"][0]["number"], json!(42));
        assert!(svc
            .handle("open-prs", json!({ "owner": "  ", "name": "x" }))
            .await
            .is_err());
    }

    #[test]
    fn open_pr_list_surfaces_a_missing_binary_a_failed_run_and_bad_json() {
        // The three degraded shapes a real `gh` presents — not installed, a
        // nonzero exit (auth/network), and output that is not the JSON array
        // the menu indexes into — must each be a distinct, actionable error
        // rather than a panic or a silently empty list (#1389, fix 7).
        let err = open_pr_list(Path::new("/nonexistent/gh"), "rust-works/omni-dev").unwrap_err();
        assert!(
            err.to_string().contains("is the GitHub CLI installed"),
            "{err:#}"
        );

        let bin_dir = tempfile::tempdir().unwrap();
        let _guard = shim_lock();
        let failing = bin_dir.path().join("fake-gh-fails");
        write_exec_script(&failing, "#!/bin/sh\necho 'boom' >&2\nexit 1\n");
        let err = retry_on_etxtbsy(|| open_pr_list(&failing, "rust-works/omni-dev")).unwrap_err();
        assert!(err.to_string().contains("gh pr list failed"), "{err:#}");
        assert!(err.to_string().contains("boom"), "{err:#}");

        let object = bin_dir.path().join("fake-gh-object");
        write_exec_script(&object, "#!/bin/sh\necho '{}'\n");
        let err = retry_on_etxtbsy(|| open_pr_list(&object, "rust-works/omni-dev")).unwrap_err();
        assert!(
            err.to_string().contains("did not return a JSON array"),
            "{err:#}"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_throttles_when_the_budget_is_over_warn() {
        // #1389, fix 6: over the ~80% warn threshold the poller holds its stretched
        // cadence and ignores even a grown watch, so no runaway can drain the shared
        // budget. A recent warm `last_poll` is seeded so the "first sight always
        // fetches" base case cannot mask the throttle — the only thing that could
        // fetch here is the grew-trigger, which the throttle suppresses.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim, counter) = counting_fake_gh(bin_dir.path(), "{}");

        let svc = WorktreesService::new();
        // Warm start with an *empty* watch but a fresh poll time: the registered
        // repo then reads as a grown watch, while `last_poll` is recent enough that
        // only the grew-trigger — not an elapsed backoff — could drive a fetch.
        *svc.pr_warm_start
            .lock()
            .unwrap_or_else(PoisonError::into_inner) = Some(PrWarmStart {
            watched: vec![],
            polled_at: Utc::now(),
        });
        // Budget over the warn threshold before the poller starts.
        svc.rate_limit_cache.replace(RateLimitSnapshot {
            graphql: Some(rl_resource(90)),
            core: Some(rl_resource(3)),
            search: None,
        });
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // `base` far larger than the test, so a fetch could only come from the
        // grew-trigger the throttle is meant to suppress.
        svc.start_pr_poller_with(Duration::from_secs(30), Duration::from_millis(10), fake);

        // Let the poller wake on the registration and run a while.
        tokio::time::sleep(Duration::from_millis(300)).await;
        svc.shutdown().await;
        assert_eq!(
            gh_spawn_count(&counter),
            0,
            "over WARN_PERCENT the poller must not fetch a grown watch (#1389, fix 6)"
        );
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_bumps_only_when_a_verdict_actually_moves() {
        // The diff-and-drop contract: an unchanged poll must not bump, or every
        // window re-renders on every tick — the cost this design exists to avoid.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"abc","statusCheckRollup":{"contexts":{"nodes":[
                  {"__typename":"CheckRun","status":"IN_PROGRESS","conclusion":null}
                ]}}},
                "associatedPullRequests":{"nodes":[{"number":1,"isDraft":false,"url":"u"}]}
            }}}}"#,
        );
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            fake.clone(),
        );

        tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if svc.pr_cache.get("rust-works", "omni-dev", "main").is_some() {
                    return;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("poller should resolve a badge through the fake gh");
        // The fake always answers identically, so after the first resolve every
        // subsequent poll is a no-change and must leave the generation alone.
        let settled = svc.registry.change_generation();
        tokio::time::sleep(Duration::from_millis(150)).await;
        assert_eq!(
            svc.registry.change_generation(),
            settled,
            "an unchanged poll must not bump the change-notify"
        );
        svc.shutdown().await;
    }

    #[tokio::test]
    // Holds the shim guard across awaits; see the note above.
    #[allow(clippy::await_holding_lock)]
    async fn pr_poller_resolves_a_negative_through_gh_and_bumps_once() {
        // The negative twin of `pr_poller_bumps_only_when_a_verdict_actually_moves`
        // (#1370): a PR-less branch resolves to NoPr end-to-end, reaches the wire
        // as `pr_none`, and — since the answer never changes — bumps the
        // change-notify only for the poll that first delivered it.
        let dir = tempfile::tempdir().unwrap();
        github_repo(dir.path());
        let bin_dir = tempfile::tempdir().unwrap();
        let (fake, _shim) = fake_gh(
            bin_dir.path(),
            r#"{"data":{"r0":{"b0":{
                "target":{"oid":"abc","statusCheckRollup":null},
                "associatedPullRequests":{"nodes":[]}
            }}}}"#,
        );
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w", "folders": [dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        // Polling defaults off (#1376): enable it for this repo so the poller/fold
        // act on it, as if the user had toggled it on.
        svc.registry.set_polling("rust-works", "omni-dev", true);
        svc.start_pr_poller_with(
            Duration::from_millis(50),
            Duration::from_millis(10),
            fake.clone(),
        );

        tokio::time::timeout(Duration::from_secs(30), async {
            loop {
                if svc.pr_cache.get("rust-works", "omni-dev", "main") == Some(PrResolution::NoPr) {
                    return;
                }
                tokio::time::sleep(Duration::from_millis(25)).await;
            }
        })
        .await
        .expect("poller should resolve the negative through the fake gh");

        // The negative reaches the wire the windows actually read.
        let wt = &repos_of(&svc.handle("tree", Value::Null).await.unwrap())[0]["worktrees"][0];
        assert_eq!(wt["pr_none"], json!(true));
        assert!(wt.get("pr").is_none(), "{wt:?}");

        // Identical re-polls of the same negative must not bump.
        let settled = svc.registry.change_generation();
        tokio::time::sleep(Duration::from_millis(150)).await;
        assert_eq!(
            svc.registry.change_generation(),
            settled,
            "an unchanged negative must not bump the change-notify"
        );
        svc.shutdown().await;
    }

    #[test]
    fn sync_indicator_formats_only_with_upstream() {
        assert_eq!(sync_indicator(Some(2), Some(1)).as_deref(), Some("(+2 -1)"));
        assert_eq!(sync_indicator(Some(0), Some(0)).as_deref(), Some("(+0 -0)"));
        assert_eq!(sync_indicator(None, None), None);
        // A partial pair (no real upstream) yields nothing.
        assert_eq!(sync_indicator(Some(1), None), None);
    }

    #[tokio::test]
    async fn list_enriches_entries_with_git_status() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [dir.path()], "repo": "r" }),
        )
        .await
        .unwrap();
        let payload = svc.handle("list", Value::Null).await.unwrap();
        let windows = windows_of(&payload);
        assert_eq!(windows.len(), 1);
        assert_eq!(
            windows[0].get("branch").and_then(Value::as_str),
            Some("main")
        );
        // No upstream configured → the ahead/behind keys are absent, not zero.
        assert!(windows[0].get("ahead").is_none());
        assert!(windows[0].get("behind").is_none());
        // The main repo name is enriched onto the entry.
        assert_eq!(
            windows[0].get("main_repo").and_then(Value::as_str),
            dir.path().file_name().and_then(|n| n.to_str())
        );

        // A non-repo folder is still listed, just without a branch or main repo.
        let plain = tempfile::tempdir().unwrap();
        svc.handle(
            "register",
            json!({ "key": "w2", "folders": [plain.path()], "repo": "plain" }),
        )
        .await
        .unwrap();
        let windows = windows_of(&svc.handle("list", Value::Null).await.unwrap()).clone();
        let w2 = windows
            .iter()
            .find(|w| w.get("key").and_then(Value::as_str) == Some("w2"))
            .unwrap();
        assert!(w2.get("branch").is_none());
        assert!(w2.get("main_repo").is_none());
    }

    #[test]
    fn window_label_prefers_git_branch_over_title() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let repo_name = dir.path().file_name().unwrap().to_str().unwrap();
        let entry = WindowEntry {
            key: "k".to_string(),
            folders: vec![dir.path().to_path_buf()],
            // Both the companion `repo` and `title` are overridden by the
            // git-derived main repo name and computed branch.
            repo: Some("companion-repo".to_string()),
            title: Some("ignored title".to_string()),
            pid: None,
            last_seen: Utc::now(),
        };
        // Main checkout: `repo · branch`, and with no upstream there is no sync.
        assert_eq!(window_label(&entry), format!("{repo_name} · main"));
    }

    #[tokio::test]
    async fn list_includes_ahead_behind_for_tracking_branch() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());

        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [dir.path()], "repo": "r" }),
        )
        .await
        .unwrap();
        let payload = svc.handle("list", Value::Null).await.unwrap();
        let windows = windows_of(&payload);
        // A tracking branch serializes branch plus both divergence counts.
        assert_eq!(
            windows[0].get("branch").and_then(Value::as_str),
            Some("main")
        );
        assert_eq!(windows[0].get("ahead").and_then(Value::as_u64), Some(1));
        assert_eq!(windows[0].get("behind").and_then(Value::as_u64), Some(1));
    }

    #[test]
    fn window_label_includes_sync_for_tracking_branch() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        let repo_name = dir.path().file_name().unwrap().to_str().unwrap();
        let entry = WindowEntry {
            key: "k".to_string(),
            folders: vec![dir.path().to_path_buf()],
            repo: Some("companion-repo".to_string()),
            title: None,
            pid: None,
            last_seen: Utc::now(),
        };
        // A tracking branch appends the `(+ahead -behind)` sync indicator.
        assert_eq!(window_label(&entry), format!("{repo_name} · main (+1 -1)"));
    }

    /// Adds a linked worktree of `repo` at `wt_path` checked out on a new
    /// `branch` pointed at `base`, mirroring `git worktree add -b <branch>
    /// <wt_path>`.
    fn add_worktree(repo: &Repository, base: git2::Oid, wt_path: &Path, branch: &str) {
        let commit = repo.find_commit(base).unwrap();
        repo.branch(branch, &commit, false).unwrap();
        let reference = repo
            .find_reference(&format!("refs/heads/{branch}"))
            .unwrap();
        let mut opts = git2::WorktreeAddOptions::new();
        opts.reference(Some(&reference));
        repo.worktree(branch, wt_path, Some(&opts)).unwrap();
    }

    #[test]
    fn git_status_marks_linked_worktree_and_names_parent_repo() {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();

        // A linked worktree checked out on a new `feature` branch, in a
        // directory whose basename is deliberately *not* the repo name.
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");

        let status = git_status(&wt_path);
        assert!(status.is_worktree);
        assert_eq!(status.branch.as_deref(), Some("feature"));
        // The worktree names its *parent* repo, not its worktree-folder basename.
        assert_eq!(
            status.main_repo.as_deref(),
            main_dir.path().file_name().and_then(|n| n.to_str())
        );

        // The main checkout resolves the same repo name and is not a worktree.
        let main_status = git_status(main_dir.path());
        assert!(!main_status.is_worktree);
        assert_eq!(main_status.main_repo, status.main_repo);
    }

    #[test]
    fn window_label_marks_worktree_with_fork_glyph() {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");

        let repo_name = main_dir.path().file_name().unwrap().to_str().unwrap();
        let entry = WindowEntry {
            key: "k".to_string(),
            folders: vec![wt_path],
            repo: Some("feature-wt".to_string()),
            title: None,
            pid: None,
            last_seen: Utc::now(),
        };
        // A worktree line: parent repo, the fork glyph, then the branch (no
        // upstream here, so no sync suffix).
        assert_eq!(window_label(&entry), format!("{repo_name} ⑂ feature"));
    }

    #[test]
    fn main_repo_name_derives_from_common_dir() {
        // Normal layout: the repo is the directory that contains `.git`.
        assert_eq!(
            main_repo_name(Path::new("/home/me/omni-dev/.git")).as_deref(),
            Some("omni-dev")
        );
        // A trailing slash on the common dir does not change the answer.
        assert_eq!(
            main_repo_name(Path::new("/home/me/omni-dev/.git/")).as_deref(),
            Some("omni-dev")
        );
        // A bare repo: its own directory name, without the `.git` suffix.
        assert_eq!(
            main_repo_name(Path::new("/srv/git/omni-dev.git")).as_deref(),
            Some("omni-dev")
        );
        // A `.git` at the filesystem root has no parent name to use.
        assert_eq!(main_repo_name(Path::new("/.git")), None);
    }

    // --- Repo/worktree tree (#1265) ----------------------------------------

    /// Pulls the `repos` array out of a `tree` payload (owned, so it survives a
    /// temporary payload).
    fn repos_of(payload: &Value) -> Vec<Value> {
        payload
            .get("repos")
            .and_then(Value::as_array)
            .expect("repos array")
            .clone()
    }

    fn github(owner: &str, name: &str) -> Option<GithubIdentity> {
        Some(GithubIdentity {
            owner: owner.to_string(),
            name: name.to_string(),
        })
    }

    #[test]
    fn github_identity_parses_supported_forms() {
        // https / http, with and without the `.git` suffix.
        assert_eq!(
            github_identity("https://github.com/rust-works/omni-dev.git"),
            github("rust-works", "omni-dev")
        );
        assert_eq!(
            github_identity("https://github.com/rust-works/omni-dev"),
            github("rust-works", "omni-dev")
        );
        assert_eq!(github_identity("http://github.com/o/r"), github("o", "r"));
        // SCP-like and ssh:// / git:// forms.
        assert_eq!(
            github_identity("git@github.com:rust-works/omni-dev.git"),
            github("rust-works", "omni-dev")
        );
        assert_eq!(
            github_identity("ssh://git@github.com/o/r.git"),
            github("o", "r")
        );
        assert_eq!(github_identity("git://github.com/o/r"), github("o", "r"));
        // A trailing slash and surrounding whitespace are tolerated.
        assert_eq!(
            github_identity("  https://github.com/o/r/  "),
            github("o", "r")
        );
    }

    #[test]
    fn github_identity_rejects_non_github_and_malformed() {
        // Non-GitHub hosts.
        assert_eq!(github_identity("https://gitlab.com/o/r.git"), None);
        assert_eq!(github_identity("git@example.com:o/r.git"), None);
        // Missing or extra path segments.
        assert_eq!(github_identity("https://github.com/onlyowner"), None);
        assert_eq!(github_identity("https://github.com/o/r/extra"), None);
        assert_eq!(github_identity("https://github.com/"), None);
        // Not a URL at all.
        assert_eq!(github_identity("not a url"), None);
    }

    #[test]
    fn remote_github_identity_reads_origin_then_falls_back() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        // No remotes → None.
        assert_eq!(remote_github_identity(&repo), None);
        // A non-GitHub origin is not a match.
        repo.remote("origin", "https://gitlab.com/o/r.git").unwrap();
        assert_eq!(remote_github_identity(&repo), None);
        // A GitHub origin resolves to its identity.
        repo.remote_set_url("origin", "git@github.com:rust-works/omni-dev.git")
            .unwrap();
        assert_eq!(
            remote_github_identity(&repo),
            github("rust-works", "omni-dev")
        );

        // Origin non-GitHub but another remote is GitHub: the fallback loop over
        // the remaining remotes finds it.
        repo.remote_set_url("origin", "https://gitlab.com/o/r.git")
            .unwrap();
        repo.remote("upstream", "https://github.com/other/proj.git")
            .unwrap();
        assert_eq!(remote_github_identity(&repo), github("other", "proj"));
    }

    #[tokio::test]
    async fn tree_is_empty_with_no_windows_and_skips_non_repos() {
        let svc = WorktreesService::new();
        // No windows → an empty repo set (not an error), toggle at its default.
        assert_eq!(
            svc.handle("tree", Value::Null).await.unwrap(),
            json!({ "repos": [], "show_closed": true })
        );
        // A plain non-repo folder is skipped rather than sinking the op.
        let plain = tempfile::tempdir().unwrap();
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [plain.path()], "repo": "plain" }),
        )
        .await
        .unwrap();
        assert!(repos_of(&svc.handle("tree", Value::Null).await.unwrap()).is_empty());
    }

    #[tokio::test]
    async fn tree_enumerates_main_and_linked_with_open_join_and_github() {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        // A GitHub origin so the repo carries an identity in the payload.
        repo.remote("origin", "git@github.com:rust-works/omni-dev.git")
            .unwrap();

        // A linked worktree on a new `feature` branch, in a directory whose
        // basename is deliberately not the repo name.
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");

        let svc = WorktreesService::new();
        // A window open on the main checkout and one on the linked worktree —
        // two windows, but one repo (they must dedupe).
        svc.handle(
            "register",
            json!({ "key": "wm", "folders": [main_dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();
        svc.handle(
            "register",
            json!({ "key": "wf", "folders": [wt_path], "repo": "feature-wt" }),
        )
        .await
        .unwrap();

        let repos = repos_of(&svc.handle("tree", Value::Null).await.unwrap());
        assert_eq!(
            repos.len(),
            1,
            "two worktrees of one repo dedupe: {repos:?}"
        );
        let repo0 = &repos[0];
        // Repo identity is the parent-repo name (not a worktree-folder basename).
        assert_eq!(
            repo0.get("main_repo").and_then(Value::as_str),
            main_dir.path().file_name().and_then(|n| n.to_str())
        );
        assert_eq!(
            repo0.pointer("/github/owner").and_then(Value::as_str),
            Some("rust-works")
        );
        assert_eq!(
            repo0.pointer("/github/name").and_then(Value::as_str),
            Some("omni-dev")
        );
        assert!(repo0.get("root").and_then(Value::as_str).is_some());

        let worktrees = repo0.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(worktrees.len(), 2);
        // Main working tree first: is_main, open, with the main window's key.
        let main_wt = &worktrees[0];
        assert_eq!(main_wt.get("is_main").and_then(Value::as_bool), Some(true));
        assert_eq!(main_wt.get("open").and_then(Value::as_bool), Some(true));
        assert_eq!(
            main_wt.get("window_key").and_then(Value::as_str),
            Some("wm")
        );
        assert_eq!(main_wt.get("branch").and_then(Value::as_str), Some("main"));
        // Linked worktree: not main, open via the feature window.
        let linked = &worktrees[1];
        assert_eq!(linked.get("is_main").and_then(Value::as_bool), Some(false));
        assert_eq!(linked.get("open").and_then(Value::as_bool), Some(true));
        assert_eq!(linked.get("window_key").and_then(Value::as_str), Some("wf"));
        assert_eq!(
            linked.get("branch").and_then(Value::as_str),
            Some("feature")
        );
    }

    #[tokio::test]
    async fn tree_marks_unopened_linked_worktree_closed_and_omits_github() {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        // No remote at all → the repo carries no `github` identity.
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");

        let svc = WorktreesService::new();
        // Only the main checkout has a window; the linked worktree has none.
        svc.handle(
            "register",
            json!({ "key": "wm", "folders": [main_dir.path()], "repo": "omni-dev" }),
        )
        .await
        .unwrap();

        let repos = repos_of(&svc.handle("tree", Value::Null).await.unwrap());
        assert_eq!(repos.len(), 1);
        assert!(repos[0].get("github").is_none(), "no remote → no github");
        let worktrees = repos[0].get("worktrees").and_then(Value::as_array).unwrap();
        let linked = worktrees
            .iter()
            .find(|w| w.get("is_main").and_then(Value::as_bool) == Some(false))
            .expect("the linked worktree");
        // Enumerated even though no window has it open, and marked closed.
        assert_eq!(linked.get("open").and_then(Value::as_bool), Some(false));
        assert!(linked.get("window_key").is_none());
    }

    // --- Close op (#1277) --------------------------------------------------

    /// Builds a repo whose main working tree is on `trunk` with one **clean**
    /// linked worktree on `feature`, returning the temp dirs (kept alive so the
    /// paths stay valid) and the linked worktree path.
    fn repo_with_linked_worktree() -> (tempfile::TempDir, tempfile::TempDir, PathBuf) {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");
        (main_dir, wt_parent, wt_path)
    }

    /// [`repo_with_linked_worktree`] with a **second** linked worktree of the same
    /// repo — the shape a multi-select delete fans out over, and the only one where
    /// two prunes share a `.git/worktrees` to race on (#1359).
    fn repo_with_two_linked_worktrees() -> (tempfile::TempDir, tempfile::TempDir, PathBuf, PathBuf)
    {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let first = wt_parent.path().join("first-wt");
        let second = wt_parent.path().join("second-wt");
        add_worktree(&repo, a, &first, "first");
        add_worktree(&repo, a, &second, "second");
        (main_dir, wt_parent, first, second)
    }

    #[tokio::test]
    async fn close_removes_two_linked_worktrees_of_one_repo_concurrently() {
        let (main_dir, _wtp, first, second) = repo_with_two_linked_worktrees();
        let svc = Arc::new(WorktreesService::new());

        // The multi-select fan-out: one `close` op per target, both in flight at
        // once against the one repo's shared admin state. Genuinely concurrent
        // even on this single-threaded runtime — each op's prune is a
        // `spawn_blocking`, so awaiting its join yields to the other op.
        //
        // This guards the fan-out end-to-end (both ops complete, neither is
        // starved or deadlocked by `prune_lock`); it is deliberately *not* sold as
        // a race detector for the lock, because it is not one — it passes with the
        // guard removed, the two prunes being far too quick to collide reliably.
        let close = |path: PathBuf| {
            let svc = svc.clone();
            async move {
                svc.handle(
                    "close",
                    json!({ "path": path, "remove": true, "confirmed": true }),
                )
                .await
            }
        };
        let (a, b) = tokio::join!(close(first.clone()), close(second.clone()));

        assert_eq!(a.unwrap(), json!({ "removed": true }));
        assert_eq!(b.unwrap(), json!({ "removed": true }));
        assert!(!first.exists());
        assert!(!second.exists());
        // Both *admin* entries pruned too, not merely the directories — the half
        // the two ops contend on.
        let repo = Repository::open(main_dir.path()).unwrap();
        assert!(repo.worktrees().unwrap().is_empty());
    }

    // --- Merge-queue op (#1401) --------------------------------------------

    /// Builds a repo on `branch` with one clean commit whose `origin/<branch>`
    /// upstream points at the **same** commit (nothing to push) and a github
    /// `origin` URL — the shape [`evaluate_local`] accepts. The empty tree means an
    /// empty (clean) working directory.
    fn pushed_github_repo(dir: &Path, url: &str, branch: &str) -> Repository {
        let repo = init_repo(dir);
        let refname = format!("refs/heads/{branch}");
        let head = empty_commit(&repo, Some(&refname), &[], "A");
        repo.reference(&format!("refs/remotes/origin/{branch}"), head, true, "o")
            .unwrap();
        repo.set_head(&refname).unwrap();
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", url).unwrap();
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str(&format!("branch.{branch}.remote"), "origin")
            .unwrap();
        cfg.set_str(&format!("branch.{branch}.merge"), &refname)
            .unwrap();
        repo
    }

    #[test]
    fn evaluate_local_accepts_a_clean_pushed_github_worktree() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = pushed_github_repo(
            dir.path(),
            "https://github.com/rust-works/omni-dev.git",
            "feature",
        );
        let ok = evaluate_local(dir.path()).expect("should be locally eligible");
        assert_eq!(
            ok.target,
            PrTarget {
                owner: "rust-works".into(),
                name: "omni-dev".into(),
                branch: "feature".into(),
            }
        );
        assert!(!ok.head_sha.is_empty());
    }

    #[test]
    fn evaluate_local_skips_an_unborn_head() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = init_repo(dir.path()); // no commits
        assert_eq!(evaluate_local(dir.path()).unwrap_err().kind, "no-commits");
    }

    #[test]
    fn evaluate_local_skips_a_branch_with_no_upstream() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        // A github URL but no tracking config → nothing was ever pushed.
        repo.config()
            .unwrap()
            .set_str("remote.origin.url", "https://github.com/o/r.git")
            .unwrap();
        assert_eq!(evaluate_local(dir.path()).unwrap_err().kind, "no-upstream");
    }

    #[test]
    fn evaluate_local_skips_unpushed_local_commits() {
        let dir = tempfile::tempdir().unwrap();
        let repo = init_repo(dir.path());
        let a = empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        let a_commit = repo.find_commit(a).unwrap();
        // origin/main stays at A; local advances to B → 1 ahead (unpushed).
        repo.reference("refs/remotes/origin/main", a, true, "o")
            .unwrap();
        empty_commit(&repo, Some("refs/heads/main"), &[&a_commit], "B");
        drop(a_commit);
        repo.set_head("refs/heads/main").unwrap();
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", "https://github.com/o/r.git")
            .unwrap();
        // The fetch refspec is what lets git2 map the branch to its tracking ref;
        // without it `upstream()` fails and the branch reads as having none.
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str("branch.main.remote", "origin").unwrap();
        cfg.set_str("branch.main.merge", "refs/heads/main").unwrap();
        assert_eq!(evaluate_local(dir.path()).unwrap_err().kind, "unpushed");
    }

    #[test]
    fn evaluate_local_skips_a_detached_head() {
        let dir = tempfile::tempdir().unwrap();
        let repo = pushed_github_repo(dir.path(), "https://github.com/o/r.git", "main");
        let head = repo.head().unwrap().target().unwrap();
        repo.set_head_detached(head).unwrap();
        assert_eq!(evaluate_local(dir.path()).unwrap_err().kind, "detached");
    }

    #[test]
    fn evaluate_local_skips_a_non_github_remote() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = pushed_github_repo(dir.path(), "https://gitlab.com/o/r.git", "main");
        assert_eq!(evaluate_local(dir.path()).unwrap_err().kind, "no-github");
    }

    #[test]
    fn evaluate_local_skips_a_path_that_is_not_a_repo() {
        // A path git cannot discover a repo from is refused up front (defensive:
        // the UI only ever sends real worktrees). A nonexistent path is used so the
        // result never depends on whether the temp dir sits inside a checkout.
        assert_eq!(
            evaluate_local(Path::new("/nonexistent/omni-dev-not-a-repo-xyz"))
                .unwrap_err()
                .kind,
            "not-a-repo"
        );
    }

    #[test]
    fn log_merge_check_records_the_counts_under_an_info_subscriber() {
        // The audit line's `tracing` field expressions only evaluate when an INFO
        // subscriber is active — the sync helper makes that testable.
        let req = MergeQueueRequest {
            paths: vec![PathBuf::from("/a"), PathBuf::from("/b")],
            requester_key: Some("win-9".into()),
            check: true,
            confirmed: false,
        };
        let logs = capture_info(|| log_merge_check(&req, 1, 1));
        assert!(logs.contains("merge-queue check"), "{logs}");
        assert!(logs.contains("win-9"), "{logs}");
        assert!(logs.contains("requested=2"), "{logs}");
        assert!(logs.contains("eligible=1"), "{logs}");
    }

    #[test]
    fn log_merge_enqueue_records_the_counts_under_an_info_subscriber() {
        // A CLI-style requester (no window key) logs the dash fallback.
        let req = MergeQueueRequest {
            paths: vec![PathBuf::from("/a")],
            requester_key: None,
            check: false,
            confirmed: true,
        };
        let logs = capture_info(|| log_merge_enqueue(&req, 2, 1, 0));
        assert!(logs.contains("merge-queue enqueue"), "{logs}");
        assert!(logs.contains("queued=2"), "{logs}");
        assert!(logs.contains("failed=1"), "{logs}");
    }

    #[test]
    fn evaluate_local_flags_dirty_then_untracked() {
        // A linked worktree with a real checked-out file, so status is meaningful.
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = commit_file(&repo, "refs/heads/main", "f.txt", b"hi", "A");
        repo.set_head("refs/heads/main").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");

        // Clean checkout → gate 1 passes (it trips a *later* gate, not dirty).
        let clean = evaluate_local(&wt_path).unwrap_err();
        assert_ne!(clean.kind, "dirty");
        assert_ne!(clean.kind, "untracked");

        // Modify the tracked file → dirty (gate 1, before any network call).
        std::fs::write(wt_path.join("f.txt"), b"changed").unwrap();
        assert_eq!(evaluate_local(&wt_path).unwrap_err().kind, "dirty");

        // Restore it, add a new file → untracked.
        std::fs::write(wt_path.join("f.txt"), b"hi").unwrap();
        std::fs::write(wt_path.join("new.txt"), b"x").unwrap();
        assert_eq!(evaluate_local(&wt_path).unwrap_err().kind, "untracked");
    }

    #[test]
    fn is_conflicting_blocks_only_dirty_and_conflicting() {
        assert!(is_conflicting(Some("CONFLICTING")));
        assert!(is_conflicting(Some("DIRTY")));
        assert!(!is_conflicting(Some("CLEAN")));
        assert!(!is_conflicting(Some("BLOCKED")));
        assert!(!is_conflicting(Some("UNKNOWN")));
        assert!(!is_conflicting(None));
    }

    #[test]
    fn merge_queue_request_parses_batch_and_phase_flags() {
        let req: MergeQueueRequest = serde_json::from_value(json!({
            "paths": ["/a", "/b"], "requester_key": "w1", "confirmed": true
        }))
        .unwrap();
        assert_eq!(req.paths.len(), 2);
        assert_eq!(req.requester_key.as_deref(), Some("w1"));
        assert!(req.confirmed);
        assert!(!req.check);
        // Minimal payload: just paths; every other field defaults.
        let req: MergeQueueRequest = serde_json::from_value(json!({ "paths": [] })).unwrap();
        assert!(req.paths.is_empty());
        assert!(!req.check && !req.confirmed && req.requester_key.is_none());
    }

    #[test]
    fn queued_pr_omits_already_queued_when_false() {
        let v = serde_json::to_value(QueuedPr {
            path: "/a".into(),
            number: 5,
            already_queued: false,
        })
        .unwrap();
        assert!(v.get("already_queued").is_none(), "{v}");
        let v = serde_json::to_value(QueuedPr {
            path: "/a".into(),
            number: 5,
            already_queued: true,
        })
        .unwrap();
        assert_eq!(v.get("already_queued").and_then(Value::as_bool), Some(true));
    }

    #[tokio::test]
    async fn merge_queue_check_on_empty_selection_reports_nothing() {
        let svc = WorktreesService::new();
        let reply = svc
            .handle("merge-queue", json!({ "paths": [], "check": true }))
            .await
            .unwrap();
        assert_eq!(reply, json!({ "eligible": [], "skipped": [] }));
    }

    #[tokio::test]
    async fn merge_queue_check_skips_a_locally_ineligible_worktree_without_reaching_github() {
        // An unborn repo is skipped by the *local* gates, so the op never shells
        // `gh` — the check completes with no network stub.
        let dir = tempfile::tempdir().unwrap();
        let _repo = init_repo(dir.path());
        let svc = WorktreesService::new();
        let reply = svc
            .handle(
                "merge-queue",
                json!({ "paths": [dir.path()], "check": true }),
            )
            .await
            .unwrap();
        let skipped = reply.get("skipped").and_then(Value::as_array).unwrap();
        assert_eq!(skipped.len(), 1);
        assert_eq!(
            skipped[0].get("kind").and_then(Value::as_str),
            Some("no-commits")
        );
        assert!(reply
            .get("eligible")
            .and_then(Value::as_array)
            .unwrap()
            .is_empty());
    }

    /// A clean, pushed, github worktree on `feature` plus its HEAD sha — the shape
    /// that clears the local gates, so a test can drive the *network* gates by
    /// varying the fake `gh` reply. Returns the temp dir (kept alive) and the sha.
    fn ready_worktree() -> (tempfile::TempDir, String) {
        let dir = tempfile::tempdir().unwrap();
        let repo = pushed_github_repo(
            dir.path(),
            "https://github.com/rust-works/omni-dev.git",
            "feature",
        );
        let head = repo.head().unwrap().target().unwrap().to_string();
        (dir, head)
    }

    /// The resolve reply a fake `gh` returns for branch alias r0/b0: a rollup with
    /// one check of `conclusion`, and one PR node `pr`.
    fn merge_resolve_reply(head: &str, conclusion: &str, pr: &str) -> String {
        format!(
            r#"{{"data":{{"r0":{{"b0":{{
                "target":{{"oid":"{head}","statusCheckRollup":{{"contexts":{{"nodes":[
                  {{"__typename":"CheckRun","status":"COMPLETED","conclusion":"{conclusion}"}}
                ]}}}}}},
                "associatedPullRequests":{{"nodes":[{pr}]}}
            }}}}}}}}"#
        )
    }

    /// Runs [`evaluate_batch`] for a `ready_worktree` against a fake `gh` returning
    /// `reply`, retrying the subprocess on the shim `ETXTBSY` race. Returns the
    /// single worktree's outcome as `Ok(number)` when eligible or `Err(skip.kind)`.
    fn network_gate_outcome(head_dir: &Path, reply: &str) -> std::result::Result<u64, String> {
        let ghdir = tempfile::tempdir().unwrap();
        let (bin, _shim) = fake_gh(ghdir.path(), reply);
        let paths = vec![head_dir.to_path_buf()];
        let (eligible, mut skipped) = retry_on_etxtbsy(|| evaluate_batch(&bin, &paths)).unwrap();
        if let Some(e) = eligible.first() {
            return Ok(e.number);
        }
        Err(skipped.remove(0).kind)
    }

    #[test]
    fn evaluate_batch_marks_a_ready_pr_eligible() {
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"PR_9","number":9,"isDraft":false,"url":"u9","headRefOid":"{head}","mergeStateStatus":"CLEAN","mergeQueueEntry":null}}"#
        );
        assert_eq!(
            network_gate_outcome(dir.path(), &merge_resolve_reply(&head, "SUCCESS", &pr)),
            Ok(9)
        );
    }

    #[test]
    fn evaluate_batch_skips_a_draft_pr() {
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"P","number":1,"isDraft":true,"url":"u","headRefOid":"{head}","mergeStateStatus":"CLEAN","mergeQueueEntry":null}}"#
        );
        assert_eq!(
            network_gate_outcome(dir.path(), &merge_resolve_reply(&head, "SUCCESS", &pr)),
            Err("draft".to_string())
        );
    }

    #[test]
    fn evaluate_batch_skips_a_conflicting_pr() {
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"P","number":1,"isDraft":false,"url":"u","headRefOid":"{head}","mergeStateStatus":"CONFLICTING","mergeQueueEntry":null}}"#
        );
        assert_eq!(
            network_gate_outcome(dir.path(), &merge_resolve_reply(&head, "SUCCESS", &pr)),
            Err("conflicting".to_string())
        );
    }

    #[test]
    fn evaluate_batch_skips_a_pr_with_failing_checks() {
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"P","number":1,"isDraft":false,"url":"u","headRefOid":"{head}","mergeStateStatus":"CLEAN","mergeQueueEntry":null}}"#
        );
        assert_eq!(
            network_gate_outcome(dir.path(), &merge_resolve_reply(&head, "FAILURE", &pr)),
            Err("checks-failing".to_string())
        );
    }

    #[test]
    fn evaluate_batch_skips_a_pr_whose_head_is_stale() {
        let (dir, head) = ready_worktree();
        // The remote PR head is a different commit than the local head.
        let pr = r#"{"id":"P","number":1,"isDraft":false,"url":"u","headRefOid":"0000000000000000000000000000000000000000","mergeStateStatus":"CLEAN","mergeQueueEntry":null}"#;
        assert_eq!(
            network_gate_outcome(dir.path(), &merge_resolve_reply(&head, "SUCCESS", pr)),
            Err("stale".to_string())
        );
    }

    #[test]
    fn evaluate_batch_skips_a_branch_with_no_open_pr() {
        let (dir, head) = ready_worktree();
        // The ref resolves but no open PR heads it.
        let reply = format!(
            r#"{{"data":{{"r0":{{"b0":{{"target":{{"oid":"{head}","statusCheckRollup":null}},"associatedPullRequests":{{"nodes":[]}}}}}}}}}}"#
        );
        assert_eq!(
            network_gate_outcome(dir.path(), &reply),
            Err("no-pr".to_string())
        );
    }

    #[test]
    fn enqueue_eligible_skips_already_queued_and_records_a_failed_enqueue() {
        // A bogus binary makes the real enqueue fail (Err → `failed[]`); the
        // already-queued PR needs no mutation and is reported queued.
        let eligible = vec![
            Eligible {
                path: PathBuf::from("/wt/a"),
                number: 1,
                url: "u".into(),
                branch: "a".into(),
                pr_id: "PR_A".into(),
                already_queued: true,
            },
            Eligible {
                path: PathBuf::from("/wt/b"),
                number: 2,
                url: "u".into(),
                branch: "b".into(),
                pr_id: "PR_B".into(),
                already_queued: false,
            },
        ];
        let (queued, failed) = enqueue_eligible(Path::new("/no/such/gh/xyzzy"), eligible);
        assert_eq!(queued.len(), 1);
        assert_eq!(queued[0].number, 1);
        assert!(queued[0].already_queued);
        assert_eq!(failed.len(), 1);
        assert_eq!(failed[0].number, 2);
    }

    #[test]
    fn enqueue_eligible_records_a_github_rejection_as_failed() {
        // A fake `gh` returning a GraphQL rejection (a 200 with an `errors` body)
        // drives the `EnqueueOutcome::Rejected` arm — the PR lands in `failed[]`
        // rather than sinking the batch.
        let ghdir = tempfile::tempdir().unwrap();
        let (bin, _shim) = fake_gh(
            ghdir.path(),
            r#"{"errors":[{"message":"Pull request is not mergeable"}]}"#,
        );
        let eligible = vec![Eligible {
            path: PathBuf::from("/wt/a"),
            number: 7,
            url: "u".into(),
            branch: "a".into(),
            pr_id: "PR_A".into(),
            already_queued: false,
        }];
        let (queued, failed) = enqueue_eligible(&bin, eligible);
        assert!(queued.is_empty(), "{queued:?}");
        assert_eq!(failed.len(), 1);
        assert_eq!(failed[0].number, 7);
        // A rejection carries a non-empty reason (an `ETXTBSY` exec race would
        // instead surface as an `Err`, still landing in `failed[]`).
        assert!(!failed[0].error.is_empty(), "{}", failed[0].error);
    }

    #[tokio::test]
    #[allow(clippy::await_holding_lock)] // the shim lock serializes subprocess execs
    async fn merge_queue_with_reports_a_ready_worktree_as_eligible() {
        // Phase 1 over a network-eligible worktree: the eligible list is non-empty,
        // exercising the `PrRef` mapping the empty-selection tests cannot.
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"PR_9","number":9,"isDraft":false,"url":"u9","headRefOid":"{head}","mergeStateStatus":"CLEAN","mergeQueueEntry":null}}"#
        );
        let ghdir = tempfile::tempdir().unwrap();
        let (bin, _shim) = fake_gh(ghdir.path(), &merge_resolve_reply(&head, "SUCCESS", &pr));
        let svc = WorktreesService::new();
        let req = MergeQueueRequest {
            paths: vec![dir.path().to_path_buf()],
            requester_key: None,
            check: true,
            confirmed: false,
        };
        // `merge_queue_with` shells the freshly-written `fake-gh` shim via
        // `spawn_blocking` — a test-only ETXTBSY exec race the `shim_lock`
        // guard alone does not retry (see test_support::shim's module docs).
        let reply = retry_on_etxtbsy_async(|| svc.merge_queue_with(req.clone(), bin.clone()))
            .await
            .unwrap();
        let eligible = reply.get("eligible").and_then(Value::as_array).unwrap();
        assert_eq!(eligible.len(), 1);
        assert_eq!(eligible[0].get("number").and_then(Value::as_u64), Some(9));
        assert_eq!(
            eligible[0].get("branch").and_then(Value::as_str),
            Some("feature")
        );
    }

    #[tokio::test]
    #[allow(clippy::await_holding_lock)] // the shim lock serializes subprocess execs
    async fn merge_queue_with_enqueues_a_ready_worktree_on_confirm() {
        // Phase 2 end-to-end: the argv-branching stub answers the resolve query and
        // the enqueue mutation distinctly, so the ready worktree's PR is queued.
        let (dir, head) = ready_worktree();
        let pr = format!(
            r#"{{"id":"PR_9","number":9,"isDraft":false,"url":"u9","headRefOid":"{head}","mergeStateStatus":"CLEAN","mergeQueueEntry":null}}"#
        );
        let resolve = merge_resolve_reply(&head, "SUCCESS", &pr);
        let ghdir = tempfile::tempdir().unwrap();
        let guard = shim_lock();
        let bin = ghdir.path().join("fake-gh");
        write_exec_script(
            &bin,
            &format!(
                "#!/bin/sh\ncase \"$*\" in\n  *enqueuePullRequest*) cat <<'JSON'\n{enqueue}\nJSON\n  ;;\n  *) cat <<'JSON'\n{resolve}\nJSON\n  ;;\nesac\n",
                enqueue =
                    r#"{"data":{"enqueuePullRequest":{"mergeQueueEntry":{"state":"QUEUED"}}}}"#,
            ),
        );
        let svc = WorktreesService::new();
        let req = MergeQueueRequest {
            paths: vec![dir.path().to_path_buf()],
            requester_key: Some("w1".into()),
            check: false,
            confirmed: true,
        };
        // `merge_queue_with` shells the freshly-written `fake-gh` shim (twice,
        // for the resolve then the enqueue) via `spawn_blocking` — a test-only
        // ETXTBSY exec race the `shim_lock` guard alone does not retry (see
        // test_support::shim's module docs).
        let reply = retry_on_etxtbsy_async(|| svc.merge_queue_with(req.clone(), bin.clone()))
            .await
            .unwrap();
        drop(guard);
        let queued = reply.get("queued").and_then(Value::as_array).unwrap();
        assert_eq!(queued.len(), 1, "{reply}");
        assert_eq!(queued[0].get("number").and_then(Value::as_u64), Some(9));
        assert!(reply
            .get("failed")
            .and_then(Value::as_array)
            .unwrap()
            .is_empty());
    }

    #[tokio::test]
    async fn concurrent_closes_overlap_their_heartbeat_waits() {
        let (_main, _wtp, first, second) = repo_with_two_linked_worktrees();
        let svc = Arc::new(WorktreesService::new());
        // Two *different* windows own the two targets — the multi-select shape.
        for (key, path) in [("w2", &first), ("w3", &second)] {
            svc.handle("register", json!({ "key": key, "folders": [path] }))
                .await
                .unwrap();
        }

        let spawn_close = |path: PathBuf| {
            let svc = svc.clone();
            tokio::spawn(async move {
                svc.handle(
                    "close",
                    json!({
                        "path": path,
                        "remove": true,
                        "confirmed": true,
                        "requester_key": "w1",
                    }),
                )
                .await
            })
        };
        let a = spawn_close(first.clone());
        let b = spawn_close(second.clone());

        // The crux of #1359, and the one thing pinning `prune_lock`'s placement:
        // *both* windows are told to close while *neither* op has finished, so the
        // two multi-second heartbeat waits are in flight at once. Take the guard
        // before `await_windows_closed` instead of after and this fails — op B
        // would sit on the lock without ever marking w3, restoring exactly the
        // N-stacked-waits latency the fan-out exists to remove.
        for key in ["w2", "w3"] {
            let mut saw_close = false;
            for _ in 0..400 {
                let hb = svc
                    .handle("heartbeat", json!({ "key": key }))
                    .await
                    .unwrap();
                if hb.get("close").and_then(Value::as_bool) == Some(true) {
                    saw_close = true;
                    break;
                }
                tokio::time::sleep(Duration::from_millis(5)).await;
            }
            assert!(saw_close, "{key} should have been told to close while the other target's close was still waiting");
        }
        assert!(
            !a.is_finished() && !b.is_finished(),
            "neither close can have finished: both windows are still registered"
        );

        // Both windows close; both ops then remove.
        for key in ["w2", "w3"] {
            svc.handle("unregister", json!({ "key": key }))
                .await
                .unwrap();
        }
        assert_eq!(a.await.unwrap().unwrap(), json!({ "removed": true }));
        assert_eq!(b.await.unwrap().unwrap(), json!({ "removed": true }));
        assert!(!first.exists());
        assert!(!second.exists());
    }

    #[tokio::test]
    async fn close_safety_check_reports_clean_linked_as_removable_with_no_risks() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // Phase 1 (confirmed absent) on a clean linked worktree: removable, not
        // main, no risks → the extension proceeds with no dialog.
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        assert_eq!(report.get("removable").and_then(Value::as_bool), Some(true));
        assert_eq!(report.get("is_main").and_then(Value::as_bool), Some(false));
        assert_eq!(report.get("open").and_then(Value::as_bool), Some(false));
        assert!(report
            .get("risks")
            .and_then(Value::as_array)
            .unwrap()
            .is_empty());
        // No side effects: the worktree still exists.
        assert!(wt_path.exists());
    }

    #[tokio::test]
    async fn close_removes_a_clean_linked_worktree() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        let reply = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));
        assert!(
            !wt_path.exists(),
            "the worktree directory should be deleted"
        );
    }

    // --- Close-op audit logging (#1364) ------------------------------------

    /// Thread-scoped log buffer for asserting on the `close` op's audit lines.
    /// Mirrors the WARN capture in `claude_cli.rs`: a shared buffer installed via
    /// `with_default`, so it never disturbs a global subscriber other tests set.
    /// The audit-line tests drive the sync helpers directly (no runtime, no
    /// `spawn_blocking`), so the captured events fire on this thread where the
    /// subscriber lives — a `tracing` event emitted after a heavy `spawn_blocking`
    /// under the parallel suite is *not* reliably captured this way.
    ///
    /// Thin alias over [`crate::test_support::capture_at`] at `INFO`.
    fn capture_info(f: impl FnOnce()) -> String {
        crate::test_support::capture_at(tracing::Level::INFO, f)
    }

    // ── rebase op (#1415) ──────────────────────────────────────────────────

    /// A `RebaseRequest` over `paths` with everything else defaulted.
    fn rebase_req(paths: Vec<PathBuf>) -> RebaseRequest {
        RebaseRequest {
            paths,
            requester_key: None,
            check: false,
            confirmed: false,
            keep_conflicts: false,
            autostash: false,
            onto: None,
        }
    }

    /// A repo whose `main` has advanced one commit past a linked `feature`
    /// worktree, returning `(repo dir, worktree parent dir, worktree path)`.
    ///
    /// Deliberately **no remote**: the daemon tests drive the op with a *local*
    /// `--onto` (`main`), which the engine resolves with no fetch at all. That
    /// keeps them offline and fast — the fetch-once-per-repo path is the engine's
    /// own concern and is covered in `worktree_rebase.rs`.
    fn behind_worktree() -> (tempfile::TempDir, tempfile::TempDir, PathBuf) {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let base = commit_file(&repo, "refs/heads/main", "f.txt", b"base\n", "base");
        repo.set_head("refs/heads/main").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, base, &wt_path, "feature");
        // `main` moves on; `feature` stays at `base`, so it is 1 behind.
        commit_file(&repo, "refs/heads/main", "g.txt", b"ahead\n", "ahead");
        (main_dir, wt_parent, wt_path)
    }

    #[tokio::test]
    async fn rebase_with_refuses_an_empty_selection() {
        // A bare `rebase` must be a usage error, never a silent mass-rebase.
        let svc = WorktreesService::new();
        let err = svc
            .rebase_with(rebase_req(Vec::new()), PathBuf::from("git"))
            .await
            .unwrap_err()
            .to_string();
        assert!(err.contains("at least one path"), "{err}");
    }

    #[tokio::test]
    async fn rebase_with_phase_one_reports_without_rebasing() {
        let (_main, _parent, wt) = behind_worktree();
        let before = Repository::open(&wt).unwrap().head().unwrap().target();

        let svc = WorktreesService::new();
        let reply = svc
            .rebase_with(
                RebaseRequest {
                    check: true,
                    onto: Some("main".into()),
                    ..rebase_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(worktrees.len(), 1, "{reply}");
        assert_eq!(
            worktrees[0].get("status").and_then(Value::as_str),
            Some("would-rebase"),
            "{reply}"
        );
        // A local onto ref means no fetch was attempted at all.
        let fetches = reply.get("fetches").and_then(Value::as_array).unwrap();
        assert_eq!(fetches.len(), 1);
        assert_eq!(
            fetches[0].get("fetched").and_then(Value::as_bool),
            Some(false)
        );
        assert_eq!(
            Repository::open(&wt).unwrap().head().unwrap().target(),
            before,
            "phase 1 must not move the branch"
        );
    }

    #[tokio::test]
    async fn rebase_with_phase_two_rebases_and_clears_the_rebasing_mark() {
        let (_main, _parent, wt) = behind_worktree();
        let svc = WorktreesService::new();
        let reply = svc
            .rebase_with(
                RebaseRequest {
                    confirmed: true,
                    onto: Some("main".into()),
                    ..rebase_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(
            worktrees[0].get("status").and_then(Value::as_str),
            Some("rebased"),
            "{reply}"
        );
        // The transient cue is cleared on the way out, so no row keeps spinning.
        assert!(
            svc.registry.rebasing_paths().is_empty(),
            "the rebasing mark must be cleared after the execute"
        );
    }

    #[tokio::test]
    async fn rebase_with_phase_two_reclassifies_rather_than_trusting_the_client() {
        // The re-validation that makes two-phase meaningful: a `confirmed` request
        // still runs the classifier, so a worktree that is dirty *now* is skipped
        // rather than rebased on the strength of an earlier phase-1 verdict.
        let (_main, _parent, wt) = behind_worktree();
        std::fs::write(wt.join("f.txt"), "local edit\n").unwrap();

        let svc = WorktreesService::new();
        let reply = svc
            .rebase_with(
                RebaseRequest {
                    confirmed: true,
                    onto: Some("main".into()),
                    ..rebase_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(
            worktrees[0].get("status").and_then(Value::as_str),
            Some("skipped"),
            "{reply}"
        );
        assert_eq!(
            worktrees[0].get("reason").and_then(Value::as_str),
            Some("dirty"),
            "{reply}"
        );
    }

    #[tokio::test]
    async fn rebase_with_never_disturbs_a_worktree_already_mid_rebase() {
        // The hazard the plan-under-the-lock ordering exists to prevent: if another
        // run has left a worktree mid-rebase, this one must classify it as
        // `operation-in-progress` and leave it alone — never run `git rebase`
        // against it, which (without `keep_conflicts`) would `--abort` and destroy
        // the conflict resolution in progress.
        let (_main, _parent, wt) = behind_worktree();
        // Fake a rebase in progress the way git does: the state directory's
        // presence is what `Repository::state()` keys on.
        std::fs::create_dir_all(wt.join(".git")).ok();
        let git_dir = Repository::open(&wt).unwrap().path().to_path_buf();
        std::fs::create_dir_all(git_dir.join("rebase-merge")).unwrap();
        std::fs::write(git_dir.join("rebase-merge").join("interactive"), "").unwrap();
        assert_ne!(
            Repository::open(&wt).unwrap().state(),
            RepositoryState::Clean,
            "precondition: the worktree looks mid-rebase to git2"
        );

        let svc = WorktreesService::new();
        let reply = svc
            .rebase_with(
                RebaseRequest {
                    confirmed: true,
                    onto: Some("main".into()),
                    ..rebase_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(
            worktrees[0].get("reason").and_then(Value::as_str),
            Some("operation-in-progress"),
            "{reply}"
        );
        // Still mid-rebase: nothing aborted it out from under whoever owns it.
        assert_ne!(
            Repository::open(&wt).unwrap().state(),
            RepositoryState::Clean
        );
    }

    #[test]
    fn rebase_request_maps_onto_engine_options() {
        let req = RebaseRequest {
            keep_conflicts: true,
            autostash: true,
            onto: Some("origin/release".into()),
            ..rebase_req(vec![PathBuf::from("/wt")])
        };
        let opts = req.options(PathBuf::from("/custom/git"));
        assert!(opts.keep_conflicts && opts.autostash);
        assert_eq!(opts.onto.as_deref(), Some("origin/release"));
        assert_eq!(opts.git_bin, Some(PathBuf::from("/custom/git")));
        // Phase 1 *is* the dry run (it calls `plan`, never `execute`), so the
        // engine's own flag stays off — setting it would be a second, redundant
        // gate that could silently no-op a confirmed execute.
        assert!(!opts.dry_run);
    }

    #[test]
    fn log_rebase_check_records_the_pending_count_under_an_info_subscriber() {
        let req = RebaseRequest {
            requester_key: Some("win-3".into()),
            check: true,
            ..rebase_req(vec![PathBuf::from("/a"), PathBuf::from("/b")])
        };
        let plan = worktree_rebase::Plan {
            fetches: vec![worktree_rebase::FetchOutcome {
                repo_root: PathBuf::from("/repo"),
                onto: "origin/main".into(),
                fetched: true,
                ok: false,
                detail: Some("host unreachable".into()),
            }],
            worktrees: vec![
                worktree_rebase::WorktreeOutcome {
                    path: PathBuf::from("/a"),
                    branch: Some("a".into()),
                    onto: "origin/main".into(),
                    result: worktree_rebase::RebaseResult::WouldRebase { behind: 2 },
                },
                worktree_rebase::WorktreeOutcome {
                    path: PathBuf::from("/b"),
                    branch: Some("b".into()),
                    onto: "origin/main".into(),
                    result: worktree_rebase::RebaseResult::UpToDate,
                },
            ],
        };
        let logs = capture_info(|| log_rebase_check(&req, &plan));
        assert!(logs.contains("rebase check"), "{logs}");
        assert!(logs.contains("win-3"), "{logs}");
        assert!(logs.contains("requested=2"), "{logs}");
        assert!(logs.contains("pending=1"), "{logs}");
        assert!(logs.contains("failed_fetches=1"), "{logs}");
    }

    #[test]
    fn log_rebase_execute_counts_left_in_place_conflicts_separately() {
        // A CLI-style requester (no window key) logs the dash fallback.
        let req = rebase_req(vec![PathBuf::from("/a"), PathBuf::from("/b")]);
        let outcome = |result| worktree_rebase::WorktreeOutcome {
            path: PathBuf::from("/x"),
            branch: Some("x".into()),
            onto: "origin/main".into(),
            result,
        };
        let outcomes = vec![
            outcome(worktree_rebase::RebaseResult::Rebased { behind: 1 }),
            outcome(worktree_rebase::RebaseResult::Conflict {
                detail: "CONFLICT".into(),
                left_in_place: true,
            }),
            outcome(worktree_rebase::RebaseResult::Skipped {
                reason: worktree_rebase::SkipReason::Dirty,
            }),
        ];
        let logs = capture_info(|| log_rebase_execute(&req, &outcomes));
        assert!(logs.contains("rebase execute"), "{logs}");
        assert!(logs.contains("rebased=1"), "{logs}");
        assert!(logs.contains("conflicts=1"), "{logs}");
        assert!(logs.contains("left_in_place=1"), "{logs}");
        assert!(logs.contains("skipped=1"), "{logs}");
        assert!(logs.contains(r#"requester="-""#), "{logs}");
    }

    // --- Push op (#1443) ---------------------------------------------------

    /// A `PushRequest` with every field defaulted, for terse test construction.
    fn push_req(paths: Vec<PathBuf>) -> PushRequest {
        PushRequest {
            paths,
            requester_key: None,
            check: false,
            confirmed: false,
        }
    }

    /// A bare `origin`, a local clone of `main`, and a linked `feature` worktree
    /// whose branch is published and then **rewritten** — i.e. exactly what a
    /// rebase leaves behind, the state `push` exists for.
    ///
    /// Shells out to `git` (so the push has a real remote to talk to) under the
    /// shared serialization guard the other git-heavy tests use.
    fn rewritten_worktree() -> (tempfile::TempDir, PathBuf, PathBuf) {
        // Held for the fixture only — that dozen-subprocess burst is what the lock
        // exists to cap — and released on return, before any `.await` in the test.
        let _guard = crate::git::worktree_batch::test_serial_lock();
        let root = tempfile::tempdir().unwrap();
        let origin = root.path().join("origin.git");
        let local = root.path().join("local");
        let wt = root.path().join("feature-wt");
        std::fs::create_dir_all(&origin).unwrap();
        std::fs::create_dir_all(&local).unwrap();

        let git = |dir: &Path, args: &[&str]| {
            let out = crate::git::worktree_batch::run_git_in(
                &crate::git::resolve_git_binary(),
                dir,
                args,
            )
            .unwrap();
            assert!(
                out.status.success(),
                "git {args:?} failed: {}",
                String::from_utf8_lossy(&out.stderr)
            );
        };

        git(&origin, &["init", "--bare", "-b", "main"]);
        git(&local, &["init", "-b", "main"]);
        git(&local, &["config", "user.name", "Test"]);
        git(&local, &["config", "user.email", "test@example.com"]);
        git(&local, &["config", "commit.gpgsign", "false"]);
        std::fs::write(local.join("f.txt"), "base\n").unwrap();
        git(&local, &["add", "f.txt"]);
        git(&local, &["commit", "-m", "base"]);
        git(
            &local,
            &["remote", "add", "origin", origin.to_str().unwrap()],
        );
        git(&local, &["push", "-u", "origin", "main"]);
        git(
            &local,
            &[
                "worktree",
                "add",
                "-b",
                "feature",
                wt.to_str().unwrap(),
                "main",
            ],
        );
        std::fs::write(wt.join("g.txt"), "work\n").unwrap();
        git(&wt, &["add", "g.txt"]);
        git(&wt, &["commit", "-m", "work"]);
        git(&wt, &["push", "-u", "origin", "feature"]);
        // The rewrite: `feature` now diverges from `origin/feature`.
        git(&wt, &["commit", "--amend", "-m", "rewritten"]);

        (root, origin, std::fs::canonicalize(&wt).unwrap())
    }

    /// The tip of `refname` in the bare origin, when it exists.
    fn origin_tip(origin: &Path, refname: &str) -> Option<git2::Oid> {
        Repository::open_bare(origin)
            .unwrap()
            .refname_to_id(refname)
            .ok()
    }

    #[tokio::test]
    async fn push_with_refuses_an_empty_selection() {
        // A bare `push` must be a usage error, never a silent mass-push.
        let svc = WorktreesService::new();
        let err = svc
            .push_with(push_req(Vec::new()), PathBuf::from("git"))
            .await
            .unwrap_err()
            .to_string();
        assert!(err.contains("at least one path"), "{err}");
    }

    #[tokio::test]
    async fn push_with_phase_one_reports_without_publishing() {
        let (_root, origin, wt) = rewritten_worktree();
        let before = origin_tip(&origin, "refs/heads/feature");

        let svc = WorktreesService::new();
        let reply = svc
            .push_with(
                PushRequest {
                    check: true,
                    ..push_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(worktrees.len(), 1, "{reply}");
        assert_eq!(
            worktrees[0].get("status").and_then(Value::as_str),
            Some("would-force"),
            "{reply}"
        );
        assert!(
            reply.get("fetches").is_none(),
            "a push plan contacts no remote, so it reports no fetches: {reply}"
        );
        assert_eq!(
            origin_tip(&origin, "refs/heads/feature"),
            before,
            "phase 1 must publish nothing"
        );
        assert!(
            svc.registry.pushing_paths().is_empty(),
            "phase 1 must not mark a row as in flight"
        );
    }

    #[tokio::test]
    async fn push_with_phase_two_force_pushes_and_clears_the_pushing_mark() {
        let (_root, origin, wt) = rewritten_worktree();
        let rewritten = Repository::open(&wt).unwrap().head().unwrap().target();

        let svc = WorktreesService::new();
        let reply = svc
            .push_with(
                PushRequest {
                    confirmed: true,
                    ..push_req(vec![wt.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(
            worktrees[0].get("status").and_then(Value::as_str),
            Some("pushed"),
            "{reply}"
        );
        assert_eq!(
            worktrees[0].get("forced").and_then(Value::as_bool),
            Some(true),
            "a rewritten branch is published under the lease: {reply}"
        );
        assert_eq!(
            origin_tip(&origin, "refs/heads/feature"),
            rewritten,
            "the remote must carry the rewritten tip"
        );
        assert!(
            svc.registry.pushing_paths().is_empty(),
            "the pushing mark must be cleared after the execute — a push writes no \
             on-disk state, so nothing else could ever correct a leftover"
        );
    }

    #[tokio::test]
    async fn push_resolves_the_git_binary_for_itself() {
        // The public entry point, which `push_with` exists to let the other tests
        // bypass. Safe to call for real: a `check` never reaches a subprocess at
        // all, because planning a push contacts no remote.
        let (_root, origin, wt) = rewritten_worktree();
        let before = origin_tip(&origin, "refs/heads/feature");

        let svc = WorktreesService::new();
        let reply = svc
            .push(PushRequest {
                check: true,
                ..push_req(vec![wt])
            })
            .await
            .unwrap();

        assert_eq!(
            reply.get("worktrees").and_then(Value::as_array).unwrap()[0]
                .get("status")
                .and_then(Value::as_str),
            Some("would-force"),
            "{reply}"
        );
        assert_eq!(origin_tip(&origin, "refs/heads/feature"), before);
    }

    #[tokio::test]
    async fn push_with_defaults_to_report_only_without_confirmation() {
        // Neither `check` nor `confirmed`: the safe reading is "report", matching
        // `rebase`. A client that forgets the flag must never publish.
        let (_root, origin, wt) = rewritten_worktree();
        let before = origin_tip(&origin, "refs/heads/feature");

        let svc = WorktreesService::new();
        let reply = svc
            .push_with(push_req(vec![wt]), crate::git::resolve_git_binary())
            .await
            .unwrap();

        assert_eq!(
            reply.get("worktrees").and_then(Value::as_array).unwrap()[0]
                .get("status")
                .and_then(Value::as_str),
            Some("would-force"),
            "{reply}"
        );
        assert_eq!(origin_tip(&origin, "refs/heads/feature"), before);
    }

    #[tokio::test]
    async fn push_with_refuses_to_force_the_remote_default_branch() {
        // The gate that inverts ADR-0060, enforced in the daemon rather than only
        // in the UI: a rewritten `main` is reported, never published.
        let (root, origin, _wt) = rewritten_worktree();
        let local = root.path().join("local");
        let before = origin_tip(&origin, "refs/heads/main");
        crate::git::worktree_batch::run_git_in(
            &crate::git::resolve_git_binary(),
            &local,
            &["commit", "--amend", "-m", "rewritten main"],
        )
        .unwrap();

        let svc = WorktreesService::new();
        let reply = svc
            .push_with(
                PushRequest {
                    confirmed: true,
                    ..push_req(vec![local.clone()])
                },
                crate::git::resolve_git_binary(),
            )
            .await
            .unwrap();

        let worktrees = reply.get("worktrees").and_then(Value::as_array).unwrap();
        assert_eq!(
            worktrees[0].get("reason").and_then(Value::as_str),
            Some("default-branch-force-push"),
            "{reply}"
        );
        assert_eq!(
            origin_tip(&origin, "refs/heads/main"),
            before,
            "the default branch's published history must be untouched"
        );
    }

    #[test]
    fn log_push_check_separates_the_force_count_from_the_pending_count() {
        let req = PushRequest {
            requester_key: Some("win-7".into()),
            check: true,
            ..push_req(vec![PathBuf::from("/a"), PathBuf::from("/b")])
        };
        let outcome = |result| worktree_push::WorktreeOutcome {
            path: PathBuf::from("/x"),
            branch: Some("x".into()),
            remote: "origin".into(),
            remote_branch: "x".into(),
            result,
        };
        let plan = worktree_push::Plan {
            worktrees: vec![
                outcome(worktree_push::PushResult::WouldForce {
                    ahead: 1,
                    behind: 1,
                }),
                outcome(worktree_push::PushResult::WouldFastForward { ahead: 2 }),
                outcome(worktree_push::PushResult::Skipped {
                    reason: worktree_push::SkipReason::DefaultBranchForcePush,
                }),
            ],
        };
        let logs = capture_info(|| log_push_check(&req, &plan));
        assert!(logs.contains("push check"), "{logs}");
        assert!(logs.contains("pending=2"), "{logs}");
        assert!(logs.contains("forced=1"), "{logs}");
        assert!(logs.contains("skipped=1"), "{logs}");
        assert!(logs.contains(r#"requester="win-7""#), "{logs}");
    }

    #[test]
    fn log_push_execute_counts_lease_refusals_separately() {
        let req = push_req(vec![PathBuf::from("/a")]);
        let outcome = |result| worktree_push::WorktreeOutcome {
            path: PathBuf::from("/x"),
            branch: Some("x".into()),
            remote: "origin".into(),
            remote_branch: "x".into(),
            result,
        };
        let outcomes = vec![
            outcome(worktree_push::PushResult::Pushed { forced: true }),
            outcome(worktree_push::PushResult::Pushed { forced: false }),
            outcome(worktree_push::PushResult::Created),
            outcome(worktree_push::PushResult::Rejected {
                detail: "stale info".into(),
                stale: true,
            }),
            outcome(worktree_push::PushResult::Rejected {
                detail: "pre-receive hook declined".into(),
                stale: false,
            }),
        ];
        let logs = capture_info(|| log_push_execute(&req, &outcomes));
        assert!(logs.contains("push execute"), "{logs}");
        assert!(logs.contains("pushed=2"), "{logs}");
        assert!(logs.contains("forced=1"), "{logs}");
        assert!(logs.contains("created=1"), "{logs}");
        assert!(logs.contains("rejected=2"), "{logs}");
        assert!(
            logs.contains("stale_rejected=1"),
            "a lease refusal is the interesting half of a rejection: {logs}"
        );
    }

    #[test]
    fn worktree_entry_marks_a_path_the_registry_reports_as_pushing() {
        let dir = tempfile::tempdir().unwrap();
        let path = canonical(dir.path());

        let quiet = worktree_entry(&path, true, &HashMap::new(), &InFlight::default());
        assert!(!quiet.pushing);
        let json = serde_json::to_value(&quiet).unwrap();
        assert!(
            json.get("pushing").is_none(),
            "an idle row stays byte-identical for an older client: {json}"
        );

        let busy = worktree_entry(
            &path,
            true,
            &HashMap::new(),
            &InFlight {
                pushing: [path.clone()].into(),
                rebasing: HashSet::new(),
            },
        );
        assert!(busy.pushing, "the registry's transient mark rides through");
        assert!(
            !busy.rebasing,
            "the two cues are independent — a push must not read as a rebase"
        );
        assert_eq!(
            serde_json::to_value(&busy).unwrap()["pushing"],
            serde_json::json!(true)
        );
    }

    #[test]
    fn operation_slug_names_each_in_progress_state_and_none_when_clean() {
        assert_eq!(operation_slug(RepositoryState::Clean), None);
        assert_eq!(
            operation_slug(RepositoryState::Rebase).as_deref(),
            Some("rebase")
        );
        assert_eq!(
            operation_slug(RepositoryState::RebaseMerge).as_deref(),
            Some("rebase"),
            "the merge-backend rebase is still just a rebase to the user"
        );
        assert_eq!(
            operation_slug(RepositoryState::RebaseInteractive).as_deref(),
            Some("rebase-interactive")
        );
        assert_eq!(
            operation_slug(RepositoryState::Merge).as_deref(),
            Some("merge")
        );
        assert_eq!(
            operation_slug(RepositoryState::CherryPickSequence).as_deref(),
            Some("cherry-pick")
        );
        assert_eq!(
            operation_slug(RepositoryState::RevertSequence).as_deref(),
            Some("revert")
        );
        assert_eq!(
            operation_slug(RepositoryState::Bisect).as_deref(),
            Some("bisect")
        );
        assert_eq!(
            operation_slug(RepositoryState::ApplyMailboxOrRebase).as_deref(),
            Some("apply-mailbox")
        );
    }

    #[test]
    fn git_status_omits_operation_for_a_clean_worktree() {
        let dir = tempfile::tempdir().unwrap();
        let _repo = diverging_repo(dir.path());
        assert_eq!(
            git_status(dir.path()).operation,
            None,
            "a clean worktree carries no operation, so the field stays off the wire"
        );
    }

    #[test]
    fn worktree_entry_marks_a_path_the_registry_reports_as_rebasing() {
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        empty_commit(&repo, Some("refs/heads/main"), &[], "A");
        repo.set_head("refs/heads/main").unwrap();
        let path = canonical(main_dir.path());

        let quiet = worktree_entry(&path, true, &HashMap::new(), &InFlight::default());
        assert!(!quiet.rebasing);
        // Byte-identical for a pre-#1415 client: neither new field is serialized.
        let json = serde_json::to_value(&quiet).unwrap();
        assert!(json.get("rebasing").is_none(), "{json}");
        assert!(json.get("operation").is_none(), "{json}");

        let busy = worktree_entry(
            &path,
            true,
            &HashMap::new(),
            &InFlight {
                rebasing: std::iter::once(path.clone()).collect(),
                pushing: HashSet::new(),
            },
        );
        assert!(busy.rebasing, "the registry's transient mark rides through");
        assert_eq!(
            serde_json::to_value(&busy).unwrap()["rebasing"],
            serde_json::Value::Bool(true)
        );
    }

    #[test]
    fn note_kinds_joins_slugs_and_maps_empty_to_a_dash() {
        assert_eq!(note_kinds(&[]), "-");
        assert_eq!(
            note_kinds(&[Note::new("dirty", "x"), Note::new("untracked", "y")]),
            "dirty,untracked"
        );
    }

    #[test]
    fn is_self_close_true_only_when_requester_owns_an_open_window() {
        let windows = vec![("w1".to_string(), 1usize), ("w2".to_string(), 2)];
        assert!(is_self_close(Some("w1"), &windows));
        assert!(
            !is_self_close(Some("w3"), &windows),
            "requester owns no window"
        );
        assert!(!is_self_close(None, &windows), "no requester");
        assert!(!is_self_close(Some("w1"), &[]), "no open windows");
    }

    #[test]
    fn log_and_map_removal_logs_and_maps_a_successful_prune() {
        let logs = capture_info(|| {
            let reply = log_and_map_removal(Path::new("/wt/feature"), Ok(Removal::Pruned)).unwrap();
            assert_eq!(reply, json!({ "removed": true }));
        });
        assert!(
            logs.contains("worktrees close: linked worktree pruned"),
            "a successful prune must log an INFO audit line, got: {logs}"
        );
        assert!(
            logs.contains("/wt/feature"),
            "the target path must ride the line, got: {logs}"
        );
    }

    #[test]
    fn log_and_map_removal_distinguishes_an_already_gone_no_op() {
        // The #1403 fix: an already-removed worktree still replies `removed: true`
        // (the row should go) but must NOT log the `pruned` line — it logs the
        // distinct `already-gone` outcome so the audit trail stops conflating the
        // two.
        let logs = capture_info(|| {
            let reply =
                log_and_map_removal(Path::new("/wt/feature"), Ok(Removal::AlreadyGone)).unwrap();
            assert_eq!(reply, json!({ "removed": true }));
        });
        assert!(
            logs.contains("worktrees close: nothing to prune, worktree already removed"),
            "an already-gone close must log its own outcome, got: {logs}"
        );
        assert!(
            !logs.contains("linked worktree pruned"),
            "an already-gone close must not claim it pruned, got: {logs}"
        );
    }

    #[test]
    fn log_close_error_logs_at_error_and_returns_the_error_unchanged() {
        // ERROR is more severe than the INFO cap, so `capture_info` records it.
        let logs = capture_info(|| {
            let err = log_close_error(
                Path::new("/wt/feature"),
                "safety check",
                anyhow!("not a git worktree"),
            );
            assert_eq!(
                err.to_string(),
                "not a git worktree",
                "err propagates unchanged"
            );
        });
        assert!(
            logs.contains("worktrees close: safety check failed"),
            "a failed phase must log an ERROR audit line, got: {logs}"
        );
        assert!(
            logs.contains("not a git worktree"),
            "the cause must ride the line, got: {logs}"
        );
        assert!(
            logs.contains("/wt/feature"),
            "the target path must ride the line, got: {logs}"
        );
    }

    #[test]
    fn log_and_map_removal_warns_and_propagates_a_prune_failure() {
        let logs = capture_info(|| {
            let err = log_and_map_removal(Path::new("/wt/feature"), Err(anyhow!("locked")));
            assert!(err.is_err(), "a prune failure must propagate");
        });
        assert!(
            logs.contains("worktrees close: worktree prune failed"),
            "a prune failure must log a WARN audit line, got: {logs}"
        );
        assert!(
            logs.contains("locked"),
            "the failure cause must ride the line, got: {logs}"
        );
    }

    #[test]
    fn log_safety_check_logs_the_verdict_and_owning_window_key() {
        let git = GitSafety {
            is_main: false,
            removable: true,
            risks: vec![Note::new("dirty", "x"), Note::new("untracked", "y")],
            info: vec![],
        };
        let logs = capture_info(|| {
            log_safety_check(Path::new("/wt/feature"), Some("win-42"), &git, true);
        });
        assert!(
            logs.contains("worktrees close: safety check"),
            "phase-1 must log a safety-check line, got: {logs}"
        );
        assert!(
            logs.contains("/wt/feature"),
            "the path must ride the line, got: {logs}"
        );
        assert!(
            logs.contains("window_key=\"win-42\""),
            "the owning window key must ride the line, got: {logs}"
        );
        assert!(logs.contains("removable=true"), "got: {logs}");
        assert!(logs.contains("is_main=false"), "got: {logs}");
        assert!(logs.contains("open=true"), "got: {logs}");
        assert!(
            logs.contains("risks=dirty,untracked"),
            "the blocking risk kinds must ride the line, got: {logs}"
        );
    }

    #[test]
    fn log_safety_check_renders_a_dash_when_no_window_owns_the_target() {
        let git = GitSafety {
            is_main: false,
            removable: true,
            risks: vec![],
            info: vec![],
        };
        let logs = capture_info(|| {
            log_safety_check(Path::new("/wt/feature"), None, &git, false);
        });
        assert!(
            logs.contains("window_key=\"-\""),
            "no owning window → dash, got: {logs}"
        );
        assert!(logs.contains("risks=-"), "no risks → dash, got: {logs}");
    }

    #[test]
    fn log_executing_logs_the_routing_decision() {
        let logs = capture_info(|| {
            log_executing(Path::new("/wt/feature"), Some("win-7"), true, false, 3);
        });
        assert!(
            logs.contains("worktrees close: executing"),
            "phase-2 must log the execute routing, got: {logs}"
        );
        assert!(
            logs.contains("requester=\"win-7\""),
            "the requester key must ride the line, got: {logs}"
        );
        assert!(logs.contains("remove=true"), "got: {logs}");
        assert!(logs.contains("self_close=false"), "got: {logs}");
        assert!(logs.contains("cross_window=3"), "got: {logs}");
    }

    #[test]
    fn log_close_abort_warns_that_a_signalled_window_did_not_close() {
        let logs = capture_info(|| {
            log_close_abort(
                Path::new("/wt/feature"),
                &anyhow!("window(s) did not close in time: win-9"),
            );
        });
        assert!(
            logs.contains("worktrees close: aborted"),
            "an abort must log a WARN audit line, got: {logs}"
        );
        assert!(
            logs.contains("/wt/feature"),
            "the path must ride the line, got: {logs}"
        );
        assert!(
            logs.contains("win-9"),
            "the still-open window must ride the line, got: {logs}"
        );
    }

    #[test]
    fn log_window_closed_logs_the_no_removal_outcome() {
        let logs = capture_info(|| {
            log_window_closed(Path::new("/wt/feature"));
        });
        assert!(
            logs.contains("worktrees close: window closed, no removal"),
            "a remove:false close must log the no-removal outcome, got: {logs}"
        );
        assert!(
            logs.contains("/wt/feature"),
            "the path must ride the line, got: {logs}"
        );
    }

    #[test]
    fn remove_worktree_deletes_the_directory_and_prunes_the_admin_metadata() {
        // The reorder (#1315) must still fully remove a worktree: both the
        // checked-out directory *and* the admin metadata git tracks it by, so it
        // no longer appears in `Repository::worktrees()`.
        let (main, _wtp, wt_path) = repo_with_linked_worktree();
        let admin = main.path().join(".git").join("worktrees").join("feature");
        assert!(admin.exists(), "admin metadata should exist before removal");

        assert_eq!(remove_worktree(&wt_path, &[]).unwrap(), Removal::Pruned);

        assert!(!wt_path.exists(), "the working directory should be gone");
        assert!(!admin.exists(), "the admin metadata should be pruned");
        let main_repo = Repository::open(main.path()).unwrap();
        assert_eq!(
            main_repo.worktrees().unwrap().len(),
            0,
            "git should no longer track the worktree"
        );
    }

    #[test]
    fn remove_worktree_recovers_a_half_removed_orphan() {
        // The exact #1315 leftover: the old ordering deleted the admin metadata
        // first, then failed to rmdir the working tree, orphaning the directory
        // with a dangling `.git` gitlink. `remove_worktree` must clean it up
        // rather than error with "not a git worktree".
        let (main, _wtp, wt_path) = repo_with_linked_worktree();
        let admin = main.path().join(".git").join("worktrees").join("feature");
        // Simulate the half-removed state: admin gone, directory (+gitlink) left.
        std::fs::remove_dir_all(&admin).unwrap();
        assert!(wt_path.join(".git").is_file(), "dangling gitlink remains");
        assert!(
            Repository::open(&wt_path).is_err(),
            "the orphan should not open as a repo"
        );

        assert_eq!(remove_worktree(&wt_path, &[]).unwrap(), Removal::Pruned);
        assert!(
            !wt_path.exists(),
            "the leftover directory should be removed"
        );
    }

    /// A linked worktree whose working directory has been deleted out-of-band,
    /// leaving the main repo's `.git/worktrees/<name>/` admin entry behind — the
    /// exact #1403 orphan. Roots are canonicalized up front so the gone-path
    /// comparison in [`worktree_name_for_path`] (which cannot resolve a symlink on
    /// a vanished path) stays exact on macOS's `/var`→`/private/var` links.
    /// Returns `(main dir, canonical main root, wt parent dir, gone wt path,
    /// admin dir)`.
    fn orphaned_admin_worktree() -> (
        tempfile::TempDir,
        PathBuf,
        tempfile::TempDir,
        PathBuf,
        PathBuf,
    ) {
        let main_dir = tempfile::tempdir().unwrap();
        let main_root = main_dir.path().canonicalize().unwrap();
        let repo = init_repo(&main_root);
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().canonicalize().unwrap().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");
        let admin = main_root.join(".git").join("worktrees").join("feature");
        assert!(admin.exists(), "admin metadata exists before the orphaning");
        // Delete the checkout out-of-band, leaving the admin entry `prunable`.
        std::fs::remove_dir_all(&wt_path).unwrap();
        (main_dir, main_root, wt_parent, wt_path, admin)
    }

    fn window_on(folder: &Path) -> WindowEntry {
        WindowEntry {
            key: "w".to_string(),
            folders: vec![folder.to_path_buf()],
            repo: None,
            title: None,
            pid: None,
            last_seen: Utc::now(),
        }
    }

    #[test]
    fn remove_worktree_prunes_orphaned_admin_via_a_registered_window() {
        // #1403: working tree gone, admin present. An external worktree shares no
        // ancestor with its repo, so the owner is found via a live window on the
        // main repo — the same window whose repo enumeration showed the stuck row.
        let (_main, main_root, _wtp, wt_path, admin) = orphaned_admin_worktree();

        let removed = remove_worktree(&wt_path, &[window_on(&main_root)]).unwrap();

        assert_eq!(
            removed,
            Removal::Pruned,
            "the orphaned admin must be pruned"
        );
        assert!(!admin.exists(), "the admin metadata should be gone");
        let main_repo = Repository::open(&main_root).unwrap();
        assert!(
            main_repo.worktrees().unwrap().is_empty(),
            "git should no longer track the orphaned worktree"
        );
    }

    #[test]
    fn remove_worktree_prunes_orphaned_admin_of_a_nested_worktree_via_ancestors() {
        // #1403 Option 1: a worktree nested under its own repo (the `.claude/
        // worktrees/<name>` shape that produced the reported orphans) is located
        // by walking the gone path's ancestors — no registered window needed.
        let main_dir = tempfile::tempdir().unwrap();
        let main_root = main_dir.path().canonicalize().unwrap();
        let repo = init_repo(&main_root);
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        // git2's `worktree()` creates the leaf but not intermediate parents.
        std::fs::create_dir_all(main_root.join(".nested")).unwrap();
        let wt_path = main_root.join(".nested").join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");
        let admin = main_root.join(".git").join("worktrees").join("feature");
        std::fs::remove_dir_all(main_root.join(".nested")).unwrap();

        let removed = remove_worktree(&wt_path, &[]).unwrap();

        assert_eq!(removed, Removal::Pruned);
        assert!(!admin.exists(), "the admin metadata should be gone");
    }

    #[test]
    fn remove_worktree_reports_already_gone_when_no_candidate_still_tracks_it() {
        // The other side of #1403: working tree gone AND admin already pruned. No
        // candidate repo tracks the path, so the honest outcome is `AlreadyGone`,
        // never a `pruned` lie.
        let (_main, main_root, _wtp, wt_path, admin) = orphaned_admin_worktree();
        // Prune the admin entry too, so nothing remains to remove.
        std::fs::remove_dir_all(&admin).unwrap();

        let removed = remove_worktree(&wt_path, &[window_on(&main_root)]).unwrap();

        assert_eq!(removed, Removal::AlreadyGone);
    }

    #[test]
    fn candidate_main_repos_finds_the_owner_via_ancestors_and_windows() {
        let (_main, main_root, _wtp, wt_path, _admin) = orphaned_admin_worktree();
        // External worktree: no ancestor is the repo, so only the window feed finds
        // it. The main root rides through, deduped to a single entry.
        let roots = candidate_main_repos(&wt_path, &[window_on(&main_root)]);
        assert!(
            roots.contains(&main_root),
            "the owning main repo must be a candidate, got: {roots:?}"
        );
    }

    #[test]
    fn prune_orphaned_admin_skips_a_candidate_that_is_not_a_repo() {
        // A candidate root that does not open as a repo (a stale registry folder,
        // a deleted repo) is skipped rather than fatal; the real owner that
        // follows still prunes.
        let (_main, main_root, _wtp, wt_path, admin) = orphaned_admin_worktree();
        let junk = tempfile::tempdir().unwrap();

        let removed =
            prune_orphaned_admin(&wt_path, &[junk.path().to_path_buf(), main_root]).unwrap();

        assert_eq!(removed, Removal::Pruned);
        assert!(
            !admin.exists(),
            "the real owner must still prune the orphan"
        );
    }

    #[test]
    fn prune_orphaned_admin_skips_a_candidate_that_is_itself_a_worktree() {
        // A candidate that opens as a repo but is a *linked* worktree carries no
        // `.git/worktrees/` admin dir, so it is skipped; the main repo behind it
        // is the real owner. (A live sibling worktree is exactly such a candidate.)
        let main_dir = tempfile::tempdir().unwrap();
        let main_root = main_dir.path().canonicalize().unwrap();
        let repo = init_repo(&main_root);
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_root = wt_parent.path().canonicalize().unwrap();
        let orphan = wt_root.join("orphan-wt");
        let sibling = wt_root.join("sibling-wt");
        add_worktree(&repo, a, &orphan, "orphan");
        add_worktree(&repo, a, &sibling, "sibling");
        let admin = main_root.join(".git").join("worktrees").join("orphan");
        std::fs::remove_dir_all(&orphan).unwrap();

        // The live sibling worktree first (opens, but `is_worktree()` → skip), the
        // main repo second (the actual owner).
        let removed = prune_orphaned_admin(&orphan, &[sibling, main_root]).unwrap();

        assert_eq!(removed, Removal::Pruned);
        assert!(
            !admin.exists(),
            "the orphan's admin metadata must be pruned"
        );
    }

    #[test]
    fn prune_orphaned_admin_refuses_a_locked_orphan() {
        // Locking is an admin-dir file, independent of the (gone) checkout, so an
        // orphaned worktree can still be locked. The prune must refuse it —
        // "unlock first" — rather than force past, mirroring the live path.
        let (_main, main_root, _wtp, wt_path, admin) = orphaned_admin_worktree();
        let main_repo = Repository::open(&main_root).unwrap();
        let name = worktree_name_for_path(&main_repo, &canonical(&wt_path)).unwrap();
        main_repo
            .find_worktree(&name)
            .unwrap()
            .lock(Some("in use"))
            .unwrap();

        let err = prune_orphaned_admin(&wt_path, &[main_root]).unwrap_err();

        assert!(
            err.to_string().contains("locked"),
            "a locked orphan must be refused, got: {err:#}"
        );
        assert!(admin.exists(), "a refused prune must leave the admin entry");
    }

    #[test]
    fn is_orphaned_worktree_only_matches_a_dangling_linked_gitlink() {
        let (main, _wtp, wt_path) = repo_with_linked_worktree();
        // A live worktree: gitlink resolves → not an orphan.
        assert!(!is_orphaned_worktree(&wt_path));
        // The main checkout has a `.git` directory → not an orphan.
        assert!(!is_orphaned_worktree(main.path()));
        // Drop the admin metadata → the gitlink now dangles → orphan.
        std::fs::remove_dir_all(main.path().join(".git").join("worktrees").join("feature"))
            .unwrap();
        assert!(is_orphaned_worktree(&wt_path));
    }

    #[test]
    fn remove_dir_all_retrying_is_idempotent_on_a_missing_directory() {
        let tmp = tempfile::tempdir().unwrap();
        let missing = tmp.path().join("gone");
        assert!(remove_dir_all_retrying(&missing).is_ok());
    }

    #[test]
    fn is_transient_rmdir_error_matches_only_the_repopulated_directory_race() {
        use std::io::Error;
        for errno in [nix::libc::ENOTEMPTY, nix::libc::EEXIST, nix::libc::EBUSY] {
            assert!(
                is_transient_rmdir_error(&Error::from_raw_os_error(errno)),
                "errno {errno} is the concurrent-writer race and must be retried"
            );
        }
        // A hard failure must surface immediately rather than burn the backoff
        // waiting for a condition that will never clear.
        for errno in [
            nix::libc::EACCES,
            nix::libc::EPERM,
            nix::libc::EROFS,
            nix::libc::ENOTDIR,
        ] {
            assert!(
                !is_transient_rmdir_error(&Error::from_raw_os_error(errno)),
                "errno {errno} is permanent and must not be retried"
            );
        }
        // Not from the OS at all, so there is no errno to classify.
        assert!(!is_transient_rmdir_error(&Error::other("synthetic")));
    }

    #[test]
    fn remove_dir_all_retrying_surfaces_a_non_transient_error_without_retrying() {
        // Removing a *file* as if it were a directory fails with ENOTDIR: not the
        // race, so it must fail on the first attempt with the original cause
        // attached, leaving the path untouched.
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("not-a-directory");
        std::fs::write(&file, b"x").unwrap();

        let mut attempts = 0;
        let err = remove_dir_all_retrying_with(&file, WORKTREE_RMDIR_BACKOFF, || {
            attempts += 1;
            std::fs::remove_dir_all(&file)
        })
        .unwrap_err();

        assert_eq!(attempts, 1, "a permanent error must not be retried");
        assert!(
            err.to_string()
                .contains("failed to remove worktree directory"),
            "unexpected error: {err:#}"
        );
        assert!(err.source().is_some(), "the io::Error cause is preserved");
        assert!(file.exists());
    }

    #[test]
    fn remove_dir_all_retrying_gives_up_after_the_backoff_is_exhausted() {
        // A writer that never quiesces: every sweep re-finds the directory
        // populated. Once the schedule runs out the ENOTEMPTY must surface rather
        // than the loop spinning forever.
        let tmp = tempfile::tempdir().unwrap();
        let mut attempts = 0;
        let backoff = [Duration::ZERO, Duration::ZERO];
        let err = remove_dir_all_retrying_with(tmp.path(), &backoff, || {
            attempts += 1;
            Err(std::io::Error::from_raw_os_error(nix::libc::ENOTEMPTY))
        })
        .unwrap_err();

        // One attempt per delay, plus the initial one.
        assert_eq!(attempts, backoff.len() + 1);
        assert!(
            err.to_string()
                .contains("failed to remove worktree directory"),
            "unexpected error: {err:#}"
        );
    }

    #[test]
    fn remove_dir_all_retrying_succeeds_once_the_writer_quiesces() {
        // The #1315 happy path, deterministically: the race clears partway through
        // the schedule and the removal then succeeds.
        let tmp = tempfile::tempdir().unwrap();
        let mut attempts = 0;
        let result = remove_dir_all_retrying_with(tmp.path(), WORKTREE_RMDIR_BACKOFF, || {
            attempts += 1;
            if attempts < 3 {
                Err(std::io::Error::from_raw_os_error(nix::libc::ENOTEMPTY))
            } else {
                Ok(())
            }
        });
        assert!(result.is_ok(), "{result:?}");
        assert_eq!(attempts, 3);
    }

    #[test]
    fn is_orphaned_worktree_ignores_a_git_file_that_is_not_a_gitlink() {
        // A `.git` file that is readable but carries no `gitdir:` pointer is not
        // something we may delete.
        let tmp = tempfile::tempdir().unwrap();
        std::fs::write(tmp.path().join(".git"), b"not a gitlink\n").unwrap();
        assert!(!is_orphaned_worktree(tmp.path()));
    }

    #[test]
    fn remove_worktree_rejects_a_path_that_is_not_a_worktree() {
        // Neither a repo nor an orphan: refuse it rather than recursively deleting
        // whatever directory was passed in.
        let tmp = tempfile::tempdir().unwrap();
        let plain = tmp.path().join("plain");
        std::fs::create_dir(&plain).unwrap();

        let err = remove_worktree(&plain, &[]).unwrap_err();

        assert!(
            err.to_string().contains("not a git worktree"),
            "unexpected error: {err:#}"
        );
        assert!(plain.exists(), "a non-worktree path must be left alone");
    }

    #[test]
    fn remove_worktree_succeeds_while_a_concurrent_writer_winds_down() {
        // Acceptance criterion (#1315): a language server / cargo still writing
        // into `target/` as the window closes makes the recursive rmdir race with
        // "Directory not empty". A background thread reproduces that by
        // repopulating `target/` for a bounded window; removal must retry past it
        // and still succeed once the writer stops.
        use std::sync::atomic::{AtomicBool, Ordering};
        use std::sync::Arc;

        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        // Created once, here — never inside the writer loop. `create_dir_all`
        // rebuilds every *parent* component, so calling it per iteration let the
        // writer resurrect the worktree root the instant removal won the race,
        // failing the final assertion on a directory removal had correctly
        // deleted and the test itself put back (#1410).
        let nested = wt_path.join("target").join("nested");
        std::fs::create_dir_all(&nested).unwrap();

        let stop = Arc::new(AtomicBool::new(false));
        let writer_stop = Arc::clone(&stop);
        let writer_dir = nested;
        let writer = std::thread::spawn(move || {
            let mut n = 0u64;
            // Churn hard for ~400ms (well under the ~2.75s retry budget), then
            // stop so a later removal pass finds the directory quiescent.
            let deadline = std::time::Instant::now() + Duration::from_millis(400);
            while !writer_stop.load(Ordering::Relaxed) && std::time::Instant::now() < deadline {
                // Best-effort, and deliberately creating no directory: `fs::write`
                // is `File::create`, which never makes parents. While `target/`
                // survives these keep it non-empty — the ENOTEMPTY removal has to
                // retry past — and once removal wins they simply fail with ENOENT.
                let _ = std::fs::write(writer_dir.join(format!("artifact-{n}.tmp")), b"x");
                n += 1;
            }
        });

        let result = remove_worktree(&wt_path, &[]);
        stop.store(true, Ordering::Relaxed);
        writer.join().unwrap();

        assert!(
            result.is_ok(),
            "removal should retry past the writer: {result:?}"
        );
        assert!(!wt_path.exists(), "the worktree directory should be gone");
    }

    #[tokio::test]
    async fn close_safety_check_flags_untracked_and_does_not_remove_without_confirmation() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        // An untracked file in the worktree would be lost on removal.
        std::fs::write(wt_path.join("scratch.txt"), b"work in progress").unwrap();

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        let risks = report.get("risks").and_then(Value::as_array).unwrap();
        assert!(
            risks
                .iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("untracked")),
            "expected an untracked risk: {report}"
        );
        // Still removable — the risk only means "confirm first", not "refuse".
        assert_eq!(report.get("removable").and_then(Value::as_bool), Some(true));
        // The unconfirmed check has no side effects.
        assert!(wt_path.exists());
    }

    #[tokio::test]
    async fn close_confirmed_removes_a_dirty_worktree() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        std::fs::write(wt_path.join("scratch.txt"), b"discard me").unwrap();
        let svc = WorktreesService::new();
        // With confirmation, the risks are overridden and removal proceeds.
        let reply = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));
        assert!(!wt_path.exists());
    }

    #[tokio::test]
    async fn close_refuses_to_remove_the_main_working_tree() {
        let (main, _wtp, _wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // Phase 1: the main tree reports not-removable, marked main.
        let report = svc
            .handle("close", json!({ "path": main.path(), "remove": true }))
            .await
            .unwrap();
        assert_eq!(report.get("is_main").and_then(Value::as_bool), Some(true));
        assert_eq!(
            report.get("removable").and_then(Value::as_bool),
            Some(false)
        );
        // Phase 2: even a confirmed delete of the main tree is refused
        // defensively, and the directory is untouched.
        assert!(svc
            .handle(
                "close",
                json!({ "path": main.path(), "remove": true, "confirmed": true }),
            )
            .await
            .is_err());
        assert!(main.path().exists());
    }

    #[tokio::test]
    async fn close_removes_a_linked_worktree_on_the_default_branch_and_keeps_the_branch() {
        // The case a naive impl would wrongly protect: a linked worktree checked
        // out on `main` (the default branch) is *still a linked worktree*, so it
        // is fully deletable — and `main` survives (removal never deletes a branch).
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("main-wt");
        add_worktree(&repo, a, &wt_path, "main");

        let svc = WorktreesService::new();
        let reply = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));
        assert!(!wt_path.exists());
        // The `main` branch is untouched by the worktree removal.
        assert!(
            repo.find_branch("main", git2::BranchType::Local).is_ok(),
            "the default branch must survive worktree removal"
        );
    }

    #[tokio::test]
    async fn close_is_idempotent_when_the_worktree_is_already_gone() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // First removal succeeds.
        svc.handle(
            "close",
            json!({ "path": wt_path, "remove": true, "confirmed": true }),
        )
        .await
        .unwrap();
        // A second confirmed close of the now-missing path is a clean success,
        // not an error (a stale snapshot must not crash).
        let reply = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));
    }

    #[tokio::test]
    async fn close_prunes_an_orphaned_admin_entry_and_the_row_disappears() {
        // The #1403 end-to-end: working tree deleted out-of-band, admin entry left
        // behind so the tree view keeps showing a `prunable` row. Closing it must
        // actually prune the admin metadata (via the registered window's repo), not
        // report a `pruned` no-op that leaves the row stuck.
        let (_main, main_root, _wtp, wt_path, admin) = orphaned_admin_worktree();
        let svc = WorktreesService::new();
        // A live window on the main repo — the vantage point the stuck row is
        // enumerated from, and the one the prune locates the owner through.
        svc.handle(
            "register",
            register_payload("main-w", None, &main_root.display().to_string()),
        )
        .await
        .unwrap();

        // Before: the orphaned linked worktree still shows alongside the main tree.
        let before = svc.handle("tree", Value::Null).await.unwrap();
        let worktrees_before = repos_of(&before)[0]["worktrees"].as_array().unwrap().len();
        assert_eq!(
            worktrees_before, 2,
            "the orphaned row is present before close"
        );

        let reply = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));

        // After: admin metadata pruned and the row is gone from the tree view.
        assert!(!admin.exists(), "the admin metadata must be pruned");
        let after = svc.handle("tree", Value::Null).await.unwrap();
        let worktrees_after = repos_of(&after)[0]["worktrees"].as_array().unwrap().len();
        assert_eq!(worktrees_after, 1, "only the main working tree remains");
    }

    #[tokio::test]
    async fn close_safety_check_detects_detached_head_unreachable_commits() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        // In the worktree, commit onto a detached HEAD so the new commit is
        // reachable from no ref — it would be GC'd on removal.
        let wt_repo = Repository::open(&wt_path).unwrap();
        let parent_oid = wt_repo.head().unwrap().target().unwrap();
        let parent = wt_repo.find_commit(parent_oid).unwrap();
        let orphan = empty_commit(&wt_repo, None, &[&parent], "orphan");
        wt_repo.set_head_detached(orphan).unwrap();

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        let risks = report.get("risks").and_then(Value::as_array).unwrap();
        assert!(
            risks
                .iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("unreachable-commits")),
            "expected an unreachable-commits risk: {report}"
        );
    }

    #[tokio::test]
    async fn close_self_close_removes_when_the_requester_owns_the_target() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // The requesting window itself has the worktree open: it is the only
        // owning window, so there is nothing to wait on — remove and reply, and
        // the extension closes its own window on `ok`.
        svc.handle(
            "register",
            json!({ "key": "w1", "folders": [wt_path], "repo": "feature-wt" }),
        )
        .await
        .unwrap();
        let reply = svc
            .handle(
                "close",
                json!({
                    "path": wt_path,
                    "remove": true,
                    "confirmed": true,
                    "requester_key": "w1",
                }),
            )
            .await
            .unwrap();
        assert_eq!(reply, json!({ "removed": true }));
        assert!(!wt_path.exists());
    }

    #[tokio::test]
    async fn close_safety_check_surfaces_the_owning_window() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // A multi-root window owns the target: the report surfaces its key and
        // folder count so the extension can warn "all N folders will close".
        svc.handle(
            "register",
            json!({ "key": "w2", "folders": [&wt_path, "/tmp/other"], "repo": "feature-wt" }),
        )
        .await
        .unwrap();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        assert_eq!(report.get("open").and_then(Value::as_bool), Some(true));
        assert_eq!(report.get("window_key").and_then(Value::as_str), Some("w2"));
        assert_eq!(
            report.get("window_folder_count").and_then(Value::as_u64),
            Some(2)
        );
    }

    #[tokio::test]
    async fn heartbeat_op_surfaces_a_pending_close_directive_once() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        // No directive → a plain `{ known: true }`, byte-identical to before.
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
        // Marked → the next heartbeat carries `close: true`, exactly once.
        svc.registry.mark_close_pending("w1");
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true, "close": true })
        );
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
    }

    // --- Reload op (#1417) -------------------------------------------------

    #[tokio::test]
    async fn heartbeat_op_surfaces_a_pending_reload_directive_once() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        // Nothing pending → `reload` is absent, so a companion that predates
        // #1417 sees a byte-identical reply.
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
        // Marked → the next heartbeat carries `reload: true`, exactly once.
        svc.registry.mark_reload_pending("w1");
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true, "reload": true })
        );
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
    }

    #[tokio::test]
    async fn heartbeat_op_carries_both_directives_when_both_are_pending() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        // Independent `if`s, not an `else`: both fields ride the same reply and
        // both are consumed, so neither directive can be stranded by the other.
        // The companion resolves the collision by checking `close` first.
        svc.registry.mark_close_pending("w1");
        svc.registry.mark_reload_pending("w1");
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true, "close": true, "reload": true })
        );
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
    }

    #[tokio::test]
    async fn reload_op_signals_live_windows_and_reports_unknown_keys() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        svc.handle("register", register_payload("w2", Some("r"), "/tmp/b"))
            .await
            .unwrap();

        // A key with no live window is reported, never an error: a window
        // closing between the client listing and sending is routine.
        let reply = svc
            .handle("reload", json!({ "target_keys": ["w1", "w2", "ghost"] }))
            .await
            .unwrap();
        assert_eq!(
            reply,
            json!({ "requested": 3, "signalled": 2, "unknown": ["ghost"] })
        );

        // Both live targets now have a directive waiting; the unknown one does
        // not (the daemon must not resurrect a key it never knew).
        assert!(svc.registry.take_reload_pending("w1"));
        assert!(svc.registry.take_reload_pending("w2"));
        assert!(!svc.registry.take_reload_pending("ghost"));
    }

    #[tokio::test]
    async fn reload_op_dedupes_repeated_keys_and_accepts_an_empty_batch() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();

        // A client repeating a key asks for one reload, not two — `requested`
        // counts distinct targets so the client's summary cannot overstate.
        assert_eq!(
            svc.handle("reload", json!({ "target_keys": ["w1", "w1"] }))
                .await
                .unwrap(),
            json!({ "requested": 1, "signalled": 1, "unknown": [] })
        );

        // An empty batch is a no-op success, and a missing field is an empty
        // batch — the callers filter their targets before sending.
        assert_eq!(
            svc.handle("reload", json!({ "target_keys": [] }))
                .await
                .unwrap(),
            json!({ "requested": 0, "signalled": 0, "unknown": [] })
        );
        assert_eq!(
            svc.handle("reload", json!({})).await.unwrap(),
            json!({ "requested": 0, "signalled": 0, "unknown": [] })
        );
    }

    #[tokio::test]
    async fn reload_op_directive_reaches_the_target_on_its_next_heartbeat() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        svc.handle("register", register_payload("w2", Some("r"), "/tmp/b"))
            .await
            .unwrap();

        // The end-to-end contract: `reload` marks, the target's own heartbeat
        // delivers. Unlike `close`, nothing waits — the op has already returned.
        svc.handle("reload", json!({ "target_keys": ["w2"] }))
            .await
            .unwrap();
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w2" }))
                .await
                .unwrap(),
            json!({ "known": true, "reload": true })
        );
        // A window that was not a target is untouched.
        assert_eq!(
            svc.handle("heartbeat", json!({ "key": "w1" }))
                .await
                .unwrap(),
            json!({ "known": true })
        );
    }

    #[tokio::test]
    async fn reload_op_treats_an_unregistered_window_as_unknown() {
        let svc = WorktreesService::new();
        svc.handle("register", register_payload("w1", Some("r"), "/tmp/a"))
            .await
            .unwrap();
        svc.handle("unregister", json!({ "key": "w1" }))
            .await
            .unwrap();
        // `list()` reaps on read, so a window that has gone away cannot be
        // signalled — it is reported instead.
        assert_eq!(
            svc.handle("reload", json!({ "target_keys": ["w1"] }))
                .await
                .unwrap(),
            json!({ "requested": 1, "signalled": 0, "unknown": ["w1"] })
        );
    }

    #[tokio::test]
    async fn close_signals_a_cross_window_target_then_removes_after_it_closes() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = Arc::new(WorktreesService::new());
        // A *different* window (not the requester) owns the target.
        svc.handle(
            "register",
            json!({ "key": "w2", "folders": [&wt_path], "repo": "feature-wt" }),
        )
        .await
        .unwrap();

        // Drive the destructive close concurrently: it marks w2 to close and
        // waits for it to unregister before removing.
        let svc2 = svc.clone();
        let path = wt_path.clone();
        let close = tokio::spawn(async move {
            svc2.handle(
                "close",
                json!({
                    "path": path,
                    "remove": true,
                    "confirmed": true,
                    "requester_key": "w1",
                }),
            )
            .await
        });

        // Simulate w2's extension: its next heartbeat sees `close: true`, so it
        // closes its window and unregisters. Poll until the directive appears.
        let mut saw_close = false;
        for _ in 0..200 {
            let hb = svc
                .handle("heartbeat", json!({ "key": "w2" }))
                .await
                .unwrap();
            if hb.get("close").and_then(Value::as_bool) == Some(true) {
                saw_close = true;
                svc.handle("unregister", json!({ "key": "w2" }))
                    .await
                    .unwrap();
                break;
            }
            tokio::time::sleep(Duration::from_millis(5)).await;
        }
        assert!(saw_close, "w2 should have been told to close");

        // Once w2 has unregistered, the close op removes the worktree.
        let reply = close.await.unwrap().unwrap();
        assert_eq!(reply, json!({ "removed": true }));
        assert!(!wt_path.exists());
    }

    #[tokio::test]
    async fn await_windows_closed_times_out_when_a_window_never_closes() {
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        svc.handle(
            "register",
            json!({ "key": "w2", "folders": [&wt_path], "repo": "feature-wt" }),
        )
        .await
        .unwrap();
        // The owning window never unregisters: the wait gives up (with a short
        // timeout here) rather than block, and names the still-open window.
        let err = await_windows_closed(
            &svc.registry,
            &wt_path,
            Some("w1"),
            Duration::from_millis(150),
            Duration::from_millis(25),
        )
        .await
        .unwrap_err();
        assert!(
            err.to_string().contains("w2"),
            "error names the window: {err}"
        );
        // The requester itself is excluded, so a self-only owner returns at once.
        await_windows_closed(
            &svc.registry,
            &wt_path,
            Some("w2"),
            Duration::from_millis(150),
            Duration::from_millis(25),
        )
        .await
        .unwrap();
    }

    #[tokio::test]
    async fn close_window_without_remove_replies_closed_and_never_deletes() {
        let (main, _wtp, _wt_path) = repo_with_linked_worktree();
        let svc = WorktreesService::new();
        // "Close Window" on the main tree: no git inspection, no removal.
        let reply = svc
            .handle("close", json!({ "path": main.path(), "remove": false }))
            .await
            .unwrap();
        assert_eq!(reply, json!({ "closed": true }));
        assert!(main.path().exists());
    }

    #[tokio::test]
    async fn close_safety_check_flags_modified_tracked_files() {
        // A tracked file, checked out into the linked worktree, then modified —
        // its content is lost on removal, so it is a `dirty` risk (distinct from
        // the untracked case).
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = commit_file(&repo, "refs/heads/trunk", "tracked.txt", b"original\n", "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");
        std::fs::write(wt_path.join("tracked.txt"), b"uncommitted change\n").unwrap();

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        let risks = report.get("risks").and_then(Value::as_array).unwrap();
        assert!(
            risks
                .iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("dirty")),
            "expected a dirty risk: {report}"
        );
    }

    #[tokio::test]
    async fn close_safety_check_flags_an_in_progress_operation() {
        // Plant a MERGE_HEAD in the worktree's gitdir so `repo.state()` reports a
        // non-Clean (interrupted merge) state — its progress is lost on removal.
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let wt_repo = Repository::open(&wt_path).unwrap();
        let head = wt_repo.head().unwrap().target().unwrap();
        std::fs::write(wt_repo.path().join("MERGE_HEAD"), format!("{head}\n")).unwrap();
        assert_ne!(wt_repo.state(), RepositoryState::Clean);

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        let risks = report.get("risks").and_then(Value::as_array).unwrap();
        assert!(
            risks
                .iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("in-progress")),
            "expected an in-progress risk: {report}"
        );
    }

    #[tokio::test]
    async fn close_safety_check_reports_unpushed_commits_as_info_not_a_risk() {
        // A linked worktree on `feature`, which tracks `origin/feature` and is one
        // commit ahead. The unpushed commit is INFO (the branch — and thus the
        // commit — survives removal), never a blocking risk.
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = empty_commit(&repo, Some("refs/heads/trunk"), &[], "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let a_commit = repo.find_commit(a).unwrap();
        repo.branch("feature", &a_commit, false).unwrap();
        repo.reference("refs/remotes/origin/feature", a, true, "origin feature")
            .unwrap();
        // `feature` advances one commit past `origin/feature`.
        empty_commit(&repo, Some("refs/heads/feature"), &[&a_commit], "B");
        drop(a_commit);
        let mut cfg = repo.config().unwrap();
        cfg.set_str("remote.origin.url", "https://example.invalid/x.git")
            .unwrap();
        cfg.set_str("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
            .unwrap();
        cfg.set_str("branch.feature.remote", "origin").unwrap();
        cfg.set_str("branch.feature.merge", "refs/heads/feature")
            .unwrap();
        // A worktree on the existing `feature` branch (not created fresh, so it
        // keeps the ahead-of-upstream divergence).
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        let reference = repo.find_reference("refs/heads/feature").unwrap();
        let mut opts = git2::WorktreeAddOptions::new();
        opts.reference(Some(&reference));
        repo.worktree("feature", &wt_path, Some(&opts)).unwrap();

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        // Unpushed commits appear as `info`, and the worktree is still cleanly
        // removable with no blocking risks.
        let info = report.get("info").and_then(Value::as_array).unwrap();
        assert!(
            info.iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("unpushed")),
            "expected an unpushed info note: {report}"
        );
        assert!(
            report
                .get("risks")
                .and_then(Value::as_array)
                .unwrap()
                .is_empty(),
            "unpushed commits alone must not block: {report}"
        );
        assert_eq!(report.get("removable").and_then(Value::as_bool), Some(true));
    }

    #[tokio::test]
    async fn close_safety_check_ignores_gitignored_files() {
        // With `.gitignore` committed, an ignored artifact is the only worktree
        // change — it must not count as untracked (it is regenerable), so the
        // worktree stays cleanly removable with no risks.
        let main_dir = tempfile::tempdir().unwrap();
        let repo = init_repo(main_dir.path());
        let a = commit_file(&repo, "refs/heads/trunk", ".gitignore", b"build/\n", "A");
        repo.set_head("refs/heads/trunk").unwrap();
        let wt_parent = tempfile::tempdir().unwrap();
        let wt_path = wt_parent.path().join("feature-wt");
        add_worktree(&repo, a, &wt_path, "feature");
        std::fs::create_dir(wt_path.join("build")).unwrap();
        std::fs::write(wt_path.join("build/artifact.o"), b"junk").unwrap();

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        assert!(
            report
                .get("risks")
                .and_then(Value::as_array)
                .unwrap()
                .is_empty(),
            "a gitignored file must not create a risk: {report}"
        );
        assert_eq!(report.get("removable").and_then(Value::as_bool), Some(true));
    }

    #[tokio::test]
    async fn close_safety_check_treats_a_missing_path_as_already_removed() {
        // The phase-1 check on a path that no longer exists reports it removable
        // with no risks (so the idempotent execute proceeds with no dialog).
        let svc = WorktreesService::new();
        let report = svc
            .handle(
                "close",
                json!({ "path": "/no/such/worktree/xyzzy", "remove": true }),
            )
            .await
            .unwrap();
        assert_eq!(report.get("removable").and_then(Value::as_bool), Some(true));
        assert_eq!(report.get("is_main").and_then(Value::as_bool), Some(false));
        assert!(report
            .get("risks")
            .and_then(Value::as_array)
            .unwrap()
            .is_empty());
        let info = report.get("info").and_then(Value::as_array).unwrap();
        assert!(info
            .iter()
            .any(|r| r.get("kind").and_then(Value::as_str) == Some("already-removed")));
    }

    #[tokio::test]
    async fn close_phase1_errors_on_a_non_git_worktree_path() {
        // An existing directory that is *not* a git worktree makes `git_safety`
        // fail; the error must propagate (rather than delete an unknown dir),
        // exercising the phase-1 `?` audit-and-return path (#1364). The ERROR
        // audit line itself is unit-tested via `log_close_error`.
        let dir = tempfile::tempdir().unwrap();
        let svc = WorktreesService::new();
        let result = svc
            .handle("close", json!({ "path": dir.path(), "remove": true }))
            .await;
        assert!(
            result.is_err(),
            "a non-git-worktree target must error the safety check, got: {result:?}"
        );
    }

    #[tokio::test]
    async fn close_refuses_a_locked_worktree() {
        // A locked worktree (git worktree lock) must be refused, not forced past
        // (failure mode #6), and left on disk.
        let (main, _wtp, wt_path) = repo_with_linked_worktree();
        let main_repo = Repository::open(main.path()).unwrap();
        main_repo
            .find_worktree("feature")
            .unwrap()
            .lock(Some("under test"))
            .unwrap();

        let svc = WorktreesService::new();
        let err = svc
            .handle(
                "close",
                json!({ "path": wt_path, "remove": true, "confirmed": true }),
            )
            .await
            .unwrap_err();
        assert!(
            err.to_string().contains("locked"),
            "expected a locked error: {err}"
        );
        assert!(wt_path.exists(), "a locked worktree must not be removed");
    }

    #[tokio::test]
    async fn close_safety_check_does_not_flag_a_detached_head_reachable_from_a_branch() {
        // A detached HEAD that still sits on a commit a branch points to loses
        // nothing on removal, so it must NOT produce an unreachable-commits risk
        // (the false-positive the reachability walk guards against).
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let wt_repo = Repository::open(&wt_path).unwrap();
        // The worktree is on `feature`; detach HEAD onto its current tip, which
        // the `feature` branch still references.
        let tip = wt_repo.head().unwrap().target().unwrap();
        wt_repo.set_head_detached(tip).unwrap();
        assert!(wt_repo.head_detached().unwrap());

        let svc = WorktreesService::new();
        let report = svc
            .handle("close", json!({ "path": wt_path, "remove": true }))
            .await
            .unwrap();
        let risks = report.get("risks").and_then(Value::as_array).unwrap();
        assert!(
            !risks
                .iter()
                .any(|r| r.get("kind").and_then(Value::as_str) == Some("unreachable-commits")),
            "a detached HEAD reachable from a branch must not be flagged: {report}"
        );
    }

    #[test]
    fn worktree_name_for_path_resolves_a_real_worktree_and_errors_otherwise() {
        let (main, _wtp, wt_path) = repo_with_linked_worktree();
        let main_repo = Repository::open(main.path()).unwrap();
        // The real linked worktree resolves to its registered name.
        assert_eq!(
            worktree_name_for_path(&main_repo, &canonical(&wt_path)).unwrap(),
            "feature"
        );
        // A path that is not one of this repo's worktrees is the defensive
        // "not registered" error (the guard behind removal).
        let err =
            worktree_name_for_path(&main_repo, Path::new("/no/such/worktree/xyzzy")).unwrap_err();
        assert!(
            err.to_string().contains("not registered"),
            "expected a not-registered error: {err}"
        );
    }

    #[test]
    fn count_dirty_untracked_degrades_to_zero_on_an_unreadable_index() {
        // A corrupt index makes `statuses()` fail; the count degrades to (0, 0)
        // rather than sinking the whole safety check.
        let (_main, _wtp, wt_path) = repo_with_linked_worktree();
        let repo = Repository::open(&wt_path).unwrap();
        std::fs::write(repo.path().join("index"), b"not a valid git index").unwrap();
        // Confirm the corruption actually breaks status enumeration, so the
        // count is exercising the error-degradation branch (not an empty repo).
        assert!(
            repo.statuses(Some(&mut StatusOptions::new())).is_err(),
            "a corrupt index should make statuses() fail"
        );
        assert_eq!(count_dirty_untracked(&repo), (0, 0));
    }
}