majordomus_cli/capability/builtin/

server.rs

//! The `server` module: the shared server of this checkout, and of every other checkout of
//! the same git repository — what each lease says, whether the server it names answers,
//! and whether what answers is the code on disk.
//!
//! The lease has always carried this — the pid, the address, when the server started, the
//! executable it runs — and nothing served it: a person read the file with `cat`, a shell
//! recipe parsed it with `sed`, and a client learned only what the election happened to
//! log. Two readers had grown their own ideas of "ready" on the way (the environment's
//! connection attempt, the health route's registry count), and neither asked the question
//! the lease can answer: is the process behind this address current? This is that answer,
//! on every surface the registry projects to, from the one typed reading of the file
//! ([`crate::lease::LeaseFile`]).
//!
//! # One repository, every server of it
//!
//! A server serves a checkout; a linked worktree is a checkout of its own with a lease of
//! its own, and until now nothing said that the two belong to one repository. The status
//! lists every checkout git registers for the repository,
//! reads the lease of each (through the worktree topology reader), and names the git repository they share
//! ([`crate::repository::git_identity`]), so that a session in one worktree can see the
//! servers — and through them the peers — of the others.
//!
//! # Two questions, two costs
//!
//! Listing every checkout costs a lease read and a probe per checkout, and a machine with
//! forty worktrees registered pays forty of each. A caller that only wants to know about
//! the checkout it is in says so — `checkouts: this` — and that answer reads one lease and
//! probes one server; no other checkout is enumerated, read or probed. The default is
//! `repository`, the whole list, because that is what every caller of this capability got
//! before the field existed.
//!
//! Read on every call and never cached: the lease is written by other processes.
//!
//! ```
//! use majordomus_cli::capability::builtin::server::{
//!     module, standing_of, Checkouts, ServerStanding, ServerStatusInput,
//! };
//! use majordomus_cli::lease::LeaseFile;
//! use std::time::Duration;
//!
//! // asking nothing asks the wide question, as it always did
//! assert_eq!(
//!     serde_json::from_str::<ServerStatusInput>("{}").unwrap().checkouts,
//!     Checkouts::Repository
//! );
//!
//! // the module composes one capability, and its decision is a pure function
//! let m = module();
//! assert_eq!(m.id.as_str(), "server");
//! assert!(m.capabilities.iter().any(|e| e.capability.id.to_string() == "server.status"));
//! let (standing, reason) = standing_of(&LeaseFile::Absent, Duration::ZERO, |_| false, "1.0.0");
//! assert_eq!(standing, ServerStanding::Absent);
//! assert!(reason.is_none());
//! ```

use std::path::{Path, PathBuf};
use std::time::Duration;

use clap::ValueEnum;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::capability::benchmark::{BenchmarkCases, CaseContext, NamedCase};
use crate::capability::handler::{CapabilityError, Context};
use crate::capability::model::{
    CachePolicy, CliExposure, Exposure, McpExposure, McpResource, Stability,
};
use crate::capability::module::ModuleDescriptor;
use crate::lease::{self, ExecutableIdentity, LeaseDocument, LeaseFile, VersionVerdict};
use crate::repository::{self, GitIdentity, Repository};
use crate::{capability, module};

use super::get;

/// The URI under which `server.status` is read as an MCP resource.
pub const SERVER_URI: &str = "majordomus://server";

/// Which checkouts a reading of the server status covers.
///
/// The two answers cost differently and that is the whole reason the choice exists: the
/// repository's checkouts are read from git's registry of them and each one costs a lease
/// read and a probe, while this checkout alone costs one of each and enumerates nothing.
/// The word each variant serialises to is the word the query parameter, the tool input and
/// the command-line flag all take.
///
/// ```
/// use majordomus_cli::capability::builtin::server::Checkouts;
/// assert_eq!(serde_json::to_value(Checkouts::This).unwrap(), "this");
/// assert_eq!(serde_json::to_value(Checkouts::Repository).unwrap(), "repository");
/// assert_eq!(Checkouts::default(), Checkouts::Repository, "the wide answer is what a caller who says nothing has always got");
/// ```
#[derive(
    Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema, ValueEnum,
)]
#[serde(rename_all = "snake_case")]
pub enum Checkouts {
    /// Every checkout git registers for the repository, the primary first — a lease read
    /// and a probe each. The default, because it is the answer this capability gave before
    /// there was anything to ask.
    #[default]
    Repository,
    /// This checkout alone. No other checkout is enumerated, no other lease is read and no
    /// other server is probed; `servers` holds the one entry, and it is this one.
    This,
}

/// What to ask of `server.status`: how wide the answer is.
///
/// One field, because the standing of a server is not something a caller filters — it is
/// something a caller wants for one checkout or for all of them, and the difference is
/// forty round trips on a machine with forty worktrees.
///
/// ```
/// use majordomus_cli::capability::builtin::server::{Checkouts, ServerStatusInput};
/// // the field is optional on every surface, and its absence is the wide answer
/// let asked_nothing: ServerStatusInput = serde_json::from_str("{}").unwrap();
/// assert_eq!(asked_nothing.checkouts, Checkouts::Repository);
/// let narrow: ServerStatusInput = serde_json::from_str(r#"{"checkouts":"this"}"#).unwrap();
/// assert_eq!(narrow.checkouts, Checkouts::This);
/// ```
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ServerStatusInput {
    /// Which checkouts the answer covers. Absent means `repository`.
    #[serde(default)]
    pub checkouts: Checkouts,
}

impl BenchmarkCases for ServerStatusInput {
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        // both questions are timed, because the difference between them is the point of
        // the field; both appear as examples in the OpenAPI document
        vec![
            NamedCase::new(
                "repository",
                ServerStatusInput {
                    checkouts: Checkouts::Repository,
                },
            ),
            NamedCase::new(
                "this-checkout",
                ServerStatusInput {
                    checkouts: Checkouts::This,
                },
            ),
        ]
    }
}

/// Where a checkout's server stands, decided from its lease, whether the server the lease
/// names answers for that checkout, and whether what answers is this executable's code.
///
/// ```
/// use majordomus_cli::capability::builtin::server::ServerStanding;
/// let all = [ServerStanding::Absent, ServerStanding::Starting, ServerStanding::Ready,
///            ServerStanding::Outdated, ServerStanding::Stale];
/// let words: Vec<&str> = all.iter().map(|s| s.as_str()).collect();
/// assert_eq!(words, ["absent", "starting", "ready", "outdated", "stale"]);
/// assert_eq!(serde_json::from_str::<ServerStanding>("\"stale\"").unwrap(), ServerStanding::Stale);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ServerStanding {
    /// No lease: nothing serves this checkout.
    Absent,
    /// A lease without an address, young enough that its owner is still binding.
    Starting,
    /// The server the lease names answers for this checkout, from the code on disk, at
    /// this executable's version.
    Ready,
    /// The server answers, but from older code than this executable, or from a file that
    /// has been replaced since it started: everything it says is yesterday's.
    Outdated,
    /// The lease names a server that does not answer, or is not a lease at all.
    Stale,
}

impl ServerStanding {
    /// The word every surface prints: the same one the JSON carries, so that a shell
    /// comparing the two never has to know which case each side chose.
    ///
    /// ```
    /// use majordomus_cli::capability::builtin::server::ServerStanding;
    /// assert_eq!(ServerStanding::Outdated.as_str(), "outdated");
    /// assert_eq!(serde_json::to_value(ServerStanding::Outdated).unwrap(), "outdated");
    /// ```
    pub fn as_str(self) -> &'static str {
        match self {
            ServerStanding::Absent => "absent",
            ServerStanding::Starting => "starting",
            ServerStanding::Ready => "ready",
            ServerStanding::Outdated => "outdated",
            ServerStanding::Stale => "stale",
        }
    }
}

/// What this executable would want a server of this checkout to be: the address it would
/// bind, the version and the executable it would serve from. What `standing` is measured
/// against.
///
/// ```
/// use majordomus_cli::capability::builtin::server::Desired;
/// let d = Desired { host: "127.0.0.1".into(), port: 8741, version: "1.0.0".into(), executable: None };
/// let v = serde_json::to_value(&d).unwrap();
/// assert_eq!(v["port"], 8741);
/// assert!(v.get("executable").is_none(), "an executable that cannot be located is not written as null");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Desired {
    /// The interface a server started here would bind: what `MAJORDOMUS_HTTP_HOST` names
    /// in this process's environment, and loopback when it names nothing.
    pub host: String,
    /// The port it asks for first.
    pub port: u16,
    /// This executable's version.
    pub version: String,
    /// This executable, when it can be located.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub executable: Option<ExecutableIdentity>,
}

/// A lease as a reader sees it: what the server wrote about itself, without the token that
/// makes the file the server's own.
///
/// ```
/// use majordomus_cli::capability::builtin::server::LeaseView;
/// let view = LeaseView { pid: 7, url: Some("http://127.0.0.1:8741".into()),
///     started_at: "2026-09-10T00:00:00Z".into(), executable: None, version: Some("1.0.0".into()) };
/// let v = serde_json::to_value(&view).unwrap();
/// assert_eq!(v["pid"], 7);
/// assert!(v.get("token").is_none() && v.get("root").is_none());
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct LeaseView {
    /// The server's process id. Not proof of a live server — only a probe that is answered
    /// is — but decisions are made from it: a live pid earns a server that does not answer
    /// the election's busy wait before its lease is taken over, and `serve ensure`'s patience
    /// before it starts another; `serve stop` sends its `SIGTERM` to this pid.
    pub pid: u32,
    /// The address, once bound.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// When the server took the lease, RFC 3339.
    pub started_at: String,
    /// The executable the server was started from, when it could be located.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub executable: Option<ExecutableIdentity>,
    /// The executable's version; absent for a server too old to have written one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
}

impl LeaseView {
    fn of(d: &LeaseDocument) -> Self {
        LeaseView {
            pid: d.pid,
            url: d.url.clone(),
            started_at: d.started_at.clone(),
            executable: d.executable.clone(),
            version: d.version.clone(),
        }
    }
}

/// One checkout of the repository, and the server its lease names.
///
/// ```
/// use majordomus_cli::capability::builtin::server::{ServerStanding, ServerView};
/// let view = ServerView { worktree: "/r".into(), branch: Some("master".into()), checkout_id: "c".into(),
///     primary: true, this_checkout: true, standing: ServerStanding::Absent, reason: None, lease: None, peers: None };
/// let v = serde_json::to_value(&view).unwrap();
/// assert_eq!(v["standing"], "absent");
/// assert!(v.get("lease").is_none() && v.get("peers").is_none(), "what there is not is not written");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ServerView {
    /// The checkout, absolute and canonical.
    pub worktree: PathBuf,
    /// The branch checked out there, when git names one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub branch: Option<String>,
    /// The checkout's identity: what its server answers as `repository_id`.
    pub checkout_id: String,
    /// Whether this is the primary checkout rather than a linked worktree.
    pub primary: bool,
    /// Whether this is the checkout the answering process serves.
    pub this_checkout: bool,
    /// Where its server stands.
    pub standing: ServerStanding,
    /// Why, when the standing is not `ready`: what the lease held, or what answered.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// The lease, when the file holds one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub lease: Option<LeaseView>,
    /// How many peers the server reports attached, when it answers.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peers: Option<usize>,
}

/// The shared server of this checkout and of every other checkout of the repository.
///
/// ```
/// use majordomus_cli::capability::builtin::server::{Desired, ServerStanding, ServerStatus};
/// let status = ServerStatus { checkout_id: "c".into(), git: None,
///     desired: Desired { host: "127.0.0.1".into(), port: 8741, version: "1.0.0".into(), executable: None },
///     this_process: None, standing: ServerStanding::Absent, servers: Vec::new(),
///     connections: None };
/// let text = serde_json::to_string(&status).unwrap();
/// assert_eq!(serde_json::from_str::<ServerStatus>(&text).unwrap(), status);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ServerStatus {
    /// This checkout's identity: what this process answers as `repository_id`.
    pub checkout_id: String,
    /// The git repository this checkout belongs to; absent where git cannot be asked.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub git: Option<GitIdentity>,
    /// What this executable would serve, and what `standing` is measured against.
    pub desired: Desired,
    /// The lease this process holds, when it is the server; absent when the question was
    /// answered by a process that serves nothing.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub this_process: Option<LeaseView>,
    /// Where this checkout's server stands.
    pub standing: ServerStanding,
    /// Every checkout of the repository, the primary first, each with its server. One entry
    /// — this checkout — where git cannot be asked.
    pub servers: Vec<ServerView>,
    /// What this process's HTTP server did to connections that held it without a request:
    /// the read deadline it applies, the connections that deadline closed, and the requests
    /// refused because every handler was busy. Absent when this process serves no HTTP.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub connections: Option<crate::http::deadline::ConnectionCounts>,
}

/// Decide where a server stands from what its lease file holds, how old the file is,
/// whether the server it names answers for the checkout, and this executable's version.
///
/// Pure, so that every branch of the decision is a test rather than a deployment:
///
/// ```
/// use majordomus_cli::capability::builtin::server::{standing_of, ServerStanding};
/// use majordomus_cli::lease::{LeaseDocument, LeaseFile, SCHEMA};
/// use std::time::Duration;
///
/// let young = Duration::ZERO;
/// let never = |_: &str| false;
/// let always = |_: &str| true;
/// assert_eq!(standing_of(&LeaseFile::Absent, young, never, "1.0.0").0, ServerStanding::Absent);
/// assert_eq!(standing_of(&LeaseFile::Empty, young, never, "1.0.0").0, ServerStanding::Starting);
/// assert_eq!(standing_of(&LeaseFile::Corrupt("not JSON".into()), young, never, "1.0.0").0, ServerStanding::Stale);
///
/// let lease = |url: Option<&str>, version: Option<&str>| LeaseDocument {
///     schema: SCHEMA.into(), pid: 1, token: "t".into(), root: "/r".into(),
///     url: url.map(str::to_string), started_at: "2026-09-10T00:00:00Z".into(),
///     executable: None, version: version.map(str::to_string),
/// };
/// // still binding, then abandoned
/// assert_eq!(standing_of(&LeaseFile::Document(lease(None, None)), young, never, "1.0.0").0, ServerStanding::Starting);
/// assert_eq!(standing_of(&LeaseFile::Document(lease(None, None)), Duration::from_secs(3600), never, "1.0.0").0, ServerStanding::Stale);
/// // names a server that does not answer
/// assert_eq!(standing_of(&LeaseFile::Document(lease(Some("http://127.0.0.1:1"), Some("1.0.0"))), young, never, "1.0.0").0, ServerStanding::Stale);
/// // answers from this version
/// assert_eq!(standing_of(&LeaseFile::Document(lease(Some("http://127.0.0.1:1"), Some("1.0.0"))), young, always, "1.0.0").0, ServerStanding::Ready);
/// // answers from another version, or from before versions were written down
/// assert_eq!(standing_of(&LeaseFile::Document(lease(Some("http://127.0.0.1:1"), Some("0.9.0"))), young, always, "1.0.0").0, ServerStanding::Outdated);
/// assert_eq!(standing_of(&LeaseFile::Document(lease(Some("http://127.0.0.1:1"), None)), young, always, "1.0.0").0, ServerStanding::Outdated);
/// ```
pub fn standing_of(
    file: &LeaseFile,
    age: Duration,
    answers: impl Fn(&str) -> bool,
    version: &str,
) -> (ServerStanding, Option<String>) {
    let doc = match file {
        LeaseFile::Absent => return (ServerStanding::Absent, None),
        LeaseFile::Empty if age > lease::timings().bind_grace => {
            return (
                ServerStanding::Stale,
                Some("empty lease: its owner never wrote it".into()),
            )
        }
        LeaseFile::Empty => return (ServerStanding::Starting, None),
        LeaseFile::Corrupt(reason) => {
            return (
                ServerStanding::Stale,
                Some(format!("corrupt lease: {reason}")),
            )
        }
        LeaseFile::Document(doc) => doc,
    };
    let Some(url) = doc.url.as_deref() else {
        return if age > lease::timings().bind_grace {
            (
                ServerStanding::Stale,
                Some("abandoned lease: its owner never published a URL".into()),
            )
        } else {
            (ServerStanding::Starting, None)
        };
    };
    if !answers(url) {
        return (
            ServerStanding::Stale,
            Some(format!(
                "the server the lease names at {url} does not answer for this checkout"
            )),
        );
    }
    if let Some(reason) = doc
        .executable
        .as_ref()
        .and_then(ExecutableIdentity::replaced)
    {
        return (ServerStanding::Outdated, Some(reason));
    }
    let theirs = doc.version.as_deref().unwrap_or_default();
    match lease::version_verdict(doc.version.as_deref(), version) {
        VersionVerdict::Same => (ServerStanding::Ready, None),
        VersionVerdict::Unpublished => (
            ServerStanding::Outdated,
            Some(format!(
                "the server published no version, so it is older than this executable ({version})"
            )),
        ),
        VersionVerdict::ServerOlder => (
            ServerStanding::Outdated,
            Some(format!(
                "the server is serving version {theirs}, older than this executable ({version}); the next client or `serve ensure` of this executable replaces it"
            )),
        ),
        VersionVerdict::ServerNewer => (
            ServerStanding::Outdated,
            Some(format!(
                "the server is serving version {theirs}, newer than this executable ({version}); clients of this executable attach to it and say they are older"
            )),
        ),
        VersionVerdict::Unordered => (
            ServerStanding::Outdated,
            Some(format!(
                "the server is serving version {theirs}; this executable is {version}"
            )),
        ),
    }
}

/// The repository-relative path of a checkout's local half — the directory its lease is
/// written into — or the layer's default when no manifest can be read at that checkout.
///
/// A directory that is not a repository of the layer still gets an answer, because "does a
/// server serve this checkout" is a question about a path and not about a manifest.
///
/// ```
/// use majordomus_cli::capability::builtin::server::local_half;
/// assert_eq!(local_half(std::path::Path::new("/nonexistent/checkout")), ".ai/local");
/// ```
pub fn local_half(root: &Path) -> String {
    Repository::open(root)
        .map(|r| r.local_path())
        .unwrap_or_else(|_| ".ai/local".to_string())
}

/// Where the server of one checkout stands, with the lease the verdict was read from.
///
/// [`standing_of`] is the decision; this is the one reading that feeds it — the lease file
/// of `worktree` under `local_half`, how old that file is, one probe of the address it
/// names, against this executable's version. Every surface that asks where a server stands
/// asks through here, so that `server.status` and the `server` check of `health.report`
/// cannot drift into two answers.
///
/// Costs one small file read, and one HTTP round trip bounded by the declared probe timeout
/// ([`crate::lease::timings`]) when the lease names an address. Nothing is cached: the
/// file is written by other processes.
///
/// ```
/// use majordomus_cli::capability::builtin::server::{local_half, standing_at, ServerStanding};
/// let nowhere = std::path::Path::new("/nonexistent/checkout");
/// let (standing, reason, lease) = standing_at(nowhere, &local_half(nowhere));
/// assert_eq!(standing, ServerStanding::Absent);
/// assert!(reason.is_none(), "there is nothing to explain: no lease, no server");
/// assert!(lease.document().is_none());
/// ```
pub fn standing_at(
    worktree: &Path,
    local_half: &str,
) -> (ServerStanding, Option<String>, LeaseFile) {
    let file = lease::lease_file(worktree, local_half);
    let read = LeaseFile::read(&file);
    // this process's own lease is answered from memory: a probe would be a request to
    // itself, queued behind the very request asking (lease::is_own)
    let own = read.document().is_some_and(lease::is_own);
    let (standing, reason) = standing_of(
        &read,
        lease::file_age(&file),
        |url| own || lease::probe(url, worktree),
        crate::VERSION,
    );
    (standing, reason, read)
}

/// How many peers the server at `url` reports, through the route the registry declares
/// for `peers.list`. `None` when it does not answer or the route is not declared.
fn peers_of(ctx: &Context, url: &str) -> Option<usize> {
    let path = ctx
        .registry
        .get("peers.list")?
        .exposure
        .http
        .as_ref()?
        .path
        .clone();
    // the probe timeout the policy declares, as the election reads it (I2129)
    let timeout = lease::timings().probe_timeout;
    let reply = crate::mcp::bridge::request(url, "GET", &path, &[], None, timeout).ok()?;
    if reply.status != 200 {
        return None;
    }
    let value: serde_json::Value = serde_json::from_str(&reply.body).ok()?;
    value["count"].as_u64().map(|n| n as usize)
}

/// The checkouts one reading covers: every checkout git registers for the repository, the
/// primary first, or this one alone.
///
/// The narrow answer is the cheap one by construction rather than by filtering — git is
/// not asked for its registry of work trees, so nothing downstream has another checkout's
/// path to read a lease at or a server to probe. It spawns no process of its own either:
/// `primary` comes from the one stat `git_identity` already did (a linked work tree has a
/// `.git` file, the primary a directory) and the branch from that checkout's own HEAD, so
/// the narrow entry says everything about this checkout that the wide list would have
/// said, at the price of two file reads.
pub(crate) fn checkouts_of(
    root: &Path,
    git: Option<&GitIdentity>,
    which: Checkouts,
) -> Vec<(PathBuf, Option<String>, bool)> {
    let here = |primary: bool| vec![(root.to_path_buf(), repository::branch_at(root), primary)];
    let Some(git) = git else {
        // not a git repository: this checkout is the only one there is, and it is the
        // primary of nothing
        return here(true);
    };
    if which == Checkouts::This {
        return here(!git.linked);
    }
    match crate::worktree::topology::read(root) {
        Ok(records) => records
            .into_iter()
            .filter(|r| !r.bare)
            .enumerate()
            .map(|(i, r)| (r.path, r.branch, i == 0))
            .collect(),
        Err(_) => here(!git.linked),
    }
}

fn server_status(ctx: &Context, input: ServerStatusInput) -> Result<ServerStatus, CapabilityError> {
    let root = PathBuf::from(&ctx.index.repository.root);
    let root = root.canonicalize().unwrap_or(root);
    let local_half = local_half(&root);
    let git = repository::git_identity(&root);
    let linked = git.as_ref().is_some_and(|g| g.linked);
    let checkouts = checkouts_of(&root, git.as_ref(), input.checkouts);
    let mut servers = Vec::with_capacity(checkouts.len());
    for (path, branch, primary) in checkouts {
        let worktree = path.canonicalize().unwrap_or(path);
        let (standing, reason, read) = standing_at(&worktree, &local_half);
        let peers = match standing {
            // this process's own board is in memory; asking it over the wire would queue
            // behind this very request (lease::is_own)
            ServerStanding::Ready | ServerStanding::Outdated
                if read.document().is_some_and(lease::is_own) =>
            {
                Some(ctx.peers.list().iter().filter(|p| p.attached).count())
            }
            ServerStanding::Ready | ServerStanding::Outdated => read
                .document()
                .and_then(|d| d.url.as_deref())
                .and_then(|url| peers_of(ctx, url)),
            _ => None,
        };
        servers.push(ServerView {
            checkout_id: repository::identity(&worktree),
            primary,
            this_checkout: worktree == root,
            branch,
            standing,
            reason,
            lease: read.document().map(LeaseView::of),
            peers,
            worktree,
        });
    }
    let standing = servers
        .iter()
        .find(|s| s.this_checkout)
        .map(|s| s.standing)
        .unwrap_or(ServerStanding::Absent);
    Ok(ServerStatus {
        checkout_id: repository::identity(&root),
        git,
        desired: Desired {
            host: desired_host(linked),
            // the port this checkout asks for on every start (I2702)
            port: crate::cli::checkout_port(&root),
            version: crate::VERSION.into(),
            executable: lease::executable_identity(),
        },
        this_process: lease::held().as_ref().map(LeaseView::of),
        standing,
        servers,
        connections: crate::http::deadline::counts(),
    })
}

/// The interface a server started from this environment would bind — the same resolution
/// `serve` and `mcp` make for this checkout, without a flag, so that `desired` and a bind
/// cannot disagree.
fn desired_host(linked: bool) -> String {
    let environment = std::env::var(crate::cli::HTTP_HOST_ENV).ok();
    crate::cli::resolve_checkout_http_host(None, environment.as_deref(), linked).0
}

/// The module: one capability, `server.status`, composed into the application by
/// `builtin::modules`; adding a second capability to it touches this file alone.
///
/// ```
/// use majordomus_cli::capability::builtin::server::module;
/// assert_eq!(module().capabilities.len(), 1);
/// ```
pub fn module() -> ModuleDescriptor {
    module! {
        id: "server",
        title: "Server",
        description: "The shared server of this checkout and of every other checkout of the same git repository: what each lease says, whether the server it names answers, whether what answers is the code on disk at this executable's version, and how many peers each one holds.",
        stability: Stability::BehaviorallyVerified,
        capabilities: [
            capability! {
                id: "server.status",
                title: "The shared server, and every server of the repository",
                description: "Where this checkout's server stands — absent, starting, ready, outdated or stale — measured against what this executable would serve; the lease this process holds when it is the server; and, unless `checkouts` narrows it to this one, every checkout git registers for the repository, the primary first, each with its lease, its standing and the reason, and the peers its server reports. `checkouts: this` reads one lease and probes one server and enumerates no other checkout, which is what a caller asking only about the checkout it is in should pay. Read from the lease files and the servers on every call; nothing is cached, because the leases are written by other processes.",
                input: ServerStatusInput,
                output: ServerStatus,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: Some(McpExposure {
                        tool: Some("majordomus_server".into()),
                        resource: Some(McpResource { uri: SERVER_URI.into(), name: "server".into() }),
                    }),
                    http: get("/api/v1/server"),
                    cli: Some(CliExposure { path: vec!["serve".into(), "status".into()] }),
                },
                tags: ["server", "lease", "coordination", "introspection"],
                cache: CachePolicy::Disabled,
                handler: server_status,
            },
        ]
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A server whose version cannot be ordered against this executable's — a pre-release
    /// beside its release — is outdated, and the reason names both versions without
    /// claiming which is older.
    #[test]
    fn a_version_that_cannot_be_ordered_is_outdated_naming_both() {
        let doc = LeaseDocument {
            schema: lease::SCHEMA.into(),
            pid: 1,
            token: "t".into(),
            root: "/r".into(),
            url: Some("http://127.0.0.1:1".into()),
            started_at: "2026-09-10T00:00:00Z".into(),
            executable: None,
            version: Some("1.0.0-rc.1".into()),
        };
        let (standing, reason) =
            standing_of(&LeaseFile::Document(doc), Duration::ZERO, |_| true, "1.0.0");
        assert_eq!(standing, ServerStanding::Outdated);
        let reason = reason.expect("a reason");
        assert_eq!(
            reason,
            "the server is serving version 1.0.0-rc.1; this executable is 1.0.0"
        );
    }
}