openlatch-client 0.5.4

//! The single diagnostic model shared by `init`, `doctor`, `status` and the
//! per-subsystem status commands.
//!
//! Before this module every command answered "is OpenLatch healthy?" its own
//! way, and the answers disagreed. `doctor` reported a disabled model relay
//! as a **pass** while `status` printed it as `disabled` and `model-relay status`
//! called the same state `down` and suggested a command that could not fix it.
//! One model, one renderer, one exit code.
//!
//! ## The contract
//!
//! - **P1** Green means *enabled AND proven working*. Nothing else is green.
//! - **P2** Deliberately disabled is a warning, never silence.
//! - **P3** Enabled but not working is a failure, even when the failure is
//!   tolerated at runtime.
//! - **P6** The same [`Section`]s are always reported, in the same order, even
//!   when empty — "I don't know" is a state, not an omission.
//! - **P7** Everything in the human rendering exists in the JSON rendering.
//!
//! ## Anti-cascade
//!
//! A failure does not propagate. When the daemon is dead, the sections that
//! depend on it report [`State::Unknown`] — a *warning* naming the blocker —
//! rather than each inventing a failure of its own. One outage, one cross.

use crate::cli::color;
use crate::cli::output::{OutputConfig, OutputFormat};

/// Display width of the field [`State::mark`] always occupies, separator
/// included.
const MARK_WIDTH: usize = 5;

/// Width of the section-title cell in the grouped rendering. The longest title
/// is `Environment` / `Persistence`, both eleven.
const TITLE_WIDTH: usize = 11;

/// Indent for a check's continuation lines — detail, source, remedy — in the
/// single-section view.
///
/// Two spaces of indent plus [`MARK_WIDTH`], so a continuation starts exactly
/// under the headline it belongs to rather than a space further in.
const CONTINUATION: &str = "       ";

/// Pad `text` out to `width` display columns, told its visible width.
///
/// `format!("{text:<width$}")` counts bytes, and a dimmed cell carries eight of
/// them before the first visible character. That aligns the columns in no-color
/// mode — the mode a test runs in — and leaves them ragged for everyone
/// actually reading the output.
fn pad_to(text: &str, visible: usize, width: usize) -> String {
    format!("{text}{}", " ".repeat(width.saturating_sub(visible)))
}

/// The agent cell that precedes a check's headline, `width` columns wide.
///
/// A host-wide check inside an otherwise per-agent section is padded rather
/// than named, so the headlines stay in one column and the absence of a name is
/// itself the statement that the finding belongs to no single agent.
fn agent_cell(check: &Check, width: usize, color_enabled: bool) -> String {
    if width == 0 {
        return String::new();
    }
    match check.agent {
        Some(agent) => pad_to(
            &color::dim(agent, color_enabled),
            agent.chars().count(),
            width,
        ),
        None => " ".repeat(width),
    }
}

/// Everything requested is running, but at least one subsystem is switched off
/// or not at full capability.
///
/// **Why 7 and not 2.** The exit-code table in `.claude/rules/error-handling.md`
/// is a public contract, and it already spends 2 on usage errors — which clap
/// produces itself for a mistyped flag, before any of our code runs. Reusing it
/// would leave a script unable to tell `openlatch doctor --bogus` from
/// `openlatch doctor` on a host with the model relay switched off. 3
/// (not found), 4 (permission), 5 (conflict — reserved for `OL-1501`, which
/// `systemd`'s `RestartPreventExitStatus=5` keys off) and 6 (`update`'s
/// daemon-unreachable) are likewise taken. 7 is the first free number.
///
/// It is deliberately NOT 0: `openlatch doctor && deploy` succeeding on a host
/// where nothing is captured or enforced is the failure mode this whole
/// contract exists to close.
pub const EXIT_DEGRADED: i32 = 7;

/// Process-level verdict recorded by a diagnostic rendering, read by `main`
/// when the command itself returned `Ok`.
///
/// Exists because a command can succeed at *running* and still need to report
/// that the machine is degraded: `doctor` finding a disabled model relay is not an
/// `OlError` — printing "Error:" in front of it would be a lie — but it must
/// not exit 0 either, or `openlatch doctor && deploy` ships with enforcement
/// off. `update` solves the same problem by calling `process::exit` directly,
/// which silently skips the `command_invoked` telemetry; this keeps the normal
/// return path intact.
mod verdict {
    use std::sync::atomic::{AtomicI32, Ordering};

    static PENDING: AtomicI32 = AtomicI32::new(0);

    /// Severity of an exit status, since the numbers do not order themselves:
    /// `1` (failure) outranks `7` (degraded), which outranks `0`.
    fn severity(code: i32) -> u8 {
        match code {
            0 => 0,
            super::EXIT_DEGRADED => 1,
            _ => 2,
        }
    }

    /// Record the exit status a successful command wants the process to carry.
    /// Worst wins, so a later benign rendering cannot clear an earlier failure.
    pub fn record(code: i32) {
        let mut current = PENDING.load(Ordering::SeqCst);
        while severity(code) > severity(current) {
            match PENDING.compare_exchange(current, code, Ordering::SeqCst, Ordering::SeqCst) {
                Ok(_) => return,
                Err(observed) => current = observed,
            }
        }
    }

    /// The recorded status, or 0 when nothing was recorded.
    pub fn pending() -> i32 {
        PENDING.load(Ordering::SeqCst)
    }

    /// Reset — tests only; the process runs one command.
    #[cfg(test)]
    pub fn reset() {
        PENDING.store(0, Ordering::SeqCst);
    }
}

#[cfg(test)]
pub use verdict::reset as reset_exit_code;
pub use verdict::{pending as pending_exit_code, record as record_exit_code};

// ---------------------------------------------------------------------------
// Groups
// ---------------------------------------------------------------------------

/// The three questions a reader asks, in the order they ask them.
///
/// Eleven flat sections is a bad ratio — eleven headings for twenty lines of
/// content, and the marks scattered across as many columns. Grouping puts every
/// section on one scan column and lets the green ones collapse to a line, so
/// what is left on screen is mostly the things that need attention.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Group {
    /// Is it running, and will it keep running?
    Runtime,
    /// Is it seeing everything, and is it enforcing?
    Coverage,
    /// Is any of what it sees leaving this machine?
    Platform,
}

impl Group {
    pub const ALL: [Group; 3] = [Group::Runtime, Group::Coverage, Group::Platform];

    pub fn title(self) -> &'static str {
        match self {
            Group::Runtime => "Runtime",
            Group::Coverage => "Coverage",
            Group::Platform => "Platform",
        }
    }

    pub fn key(self) -> &'static str {
        match self {
            Group::Runtime => "runtime",
            Group::Coverage => "coverage",
            Group::Platform => "platform",
        }
    }
}

// ---------------------------------------------------------------------------
// Sections
// ---------------------------------------------------------------------------

/// A subsystem of the install, ordered from most fundamental to most
/// peripheral. A section whose upstream dependency failed reports
/// [`State::Unknown`] rather than a failure of its own.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Section {
    /// Agent detection, `~/.claude`, `~/.openlatch`, config readability, build.
    Environment,
    /// The daemon process: alive, bound, healthy, and serving the installed
    /// version.
    Daemon,
    /// `settings.json` entries, the staged hook binary, token and port match.
    Hooks,
    /// The model-relay listener and the agent's `ANTHROPIC_BASE_URL`.
    ModelRelay,
    /// OS-native supervision (launchd / systemd-user / Task Scheduler).
    Persistence,
    /// How this host reaches the platform: direct, or through a proxy. Owns the
    /// first hop, so "cannot reach the proxy" and "cannot reach the platform"
    /// are two rows rather than one collapsed `Cloud` failure.
    Connection,
    /// Forwarding to the OpenLatch platform. Never [`State::Off`] — the
    /// forwarding is constitutive of the product and cannot be switched off.
    Cloud,
    /// Local policy bundle: present, fresh, enforcing.
    Policy,
    /// The configuration plane monitor.
    Inventory,
    /// Anonymous usage telemetry consent.
    Telemetry,
    /// Drift between the installed binary and the one being served.
    Update,
    /// HMAC key, tamper log, hook markers.
    Integrity,
}

impl Section {
    /// Every section, in reporting order. Rendering walks this, not the order
    /// checks happened to be pushed in.
    pub const ALL: [Section; 12] = [
        // Runtime
        Section::Environment,
        Section::Daemon,
        Section::Persistence,
        Section::Update,
        // Coverage
        Section::Hooks,
        Section::ModelRelay,
        Section::Policy,
        Section::Inventory,
        Section::Integrity,
        // Platform — Connection first: it is the hop Cloud travels over, so a
        // reader meets the route before the thing at the end of it.
        Section::Connection,
        Section::Cloud,
        Section::Telemetry,
    ];

    /// Which question this section answers.
    ///
    /// `Policy` sits in `Coverage` rather than `Platform` on purpose: the
    /// bundle arrives from the cloud, but the evaluation is local and
    /// authoritative — it is about what this host enforces, not about what
    /// leaves it. `Inventory` is local observation for the same reason, and
    /// `Update` is in `Runtime` because version drift answers "which binary is
    /// actually running".
    pub fn group(self) -> Group {
        match self {
            Section::Environment | Section::Daemon | Section::Persistence | Section::Update => {
                Group::Runtime
            }
            Section::Hooks
            | Section::ModelRelay
            | Section::Policy
            | Section::Inventory
            | Section::Integrity => Group::Coverage,
            Section::Connection | Section::Cloud | Section::Telemetry => Group::Platform,
        }
    }

    /// Every section in a group, in reading order.
    pub fn of_group(group: Group) -> impl Iterator<Item = Section> {
        Section::ALL.into_iter().filter(move |s| s.group() == group)
    }

    /// Human-facing section title.
    pub fn title(self) -> &'static str {
        match self {
            Section::Environment => "Environment",
            Section::Daemon => "Daemon",
            Section::Hooks => "Hooks",
            Section::ModelRelay => "Model Relay",
            Section::Persistence => "Persistence",
            Section::Connection => "Connection",
            Section::Cloud => "Cloud",
            Section::Policy => "Policy",
            Section::Inventory => "Inventory",
            Section::Telemetry => "Telemetry",
            Section::Update => "Update",
            Section::Integrity => "Integrity",
        }
    }

    /// Stable machine key for the JSON rendering.
    pub fn key(self) -> &'static str {
        match self {
            Section::Environment => "environment",
            Section::Daemon => "daemon",
            Section::Hooks => "hooks",
            Section::ModelRelay => "model_relay",
            Section::Persistence => "persistence",
            Section::Connection => "connection",
            Section::Cloud => "cloud",
            Section::Policy => "policy",
            Section::Inventory => "inventory",
            Section::Telemetry => "telemetry",
            Section::Update => "update",
            Section::Integrity => "integrity",
        }
    }
}

// ---------------------------------------------------------------------------
// State
// ---------------------------------------------------------------------------

/// What one check found.
///
/// The mapping to marks and exit codes is normative — see [`State::mark`] and
/// [`Report::exit_code`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum State {
    /// Enabled and proven working. The only green state.
    Ok,
    /// Deliberately switched off — config, flag, or an explicit user opt-out.
    /// A warning: the user is entitled to this state, and entitled to be
    /// reminded they are in it.
    Off,
    /// Enabled, working, losing nothing — but not at full capability.
    Degraded,
    /// Enabled, verification still in flight. Ask again shortly.
    Pending,
    /// Enabled and not working.
    Failed,
    /// Indeterminable because the named section failed. Warns, never fails —
    /// this is what keeps one outage from printing eight crosses.
    Unknown(Section),
    /// Absent from this build or irrelevant on this platform. Not a problem,
    /// and not a success either.
    NotApplicable,
}

impl State {
    /// Severity for "worst wins" aggregation. Not a public ordering: it exists
    /// only to fold a section's checks into one state.
    fn severity(self) -> u8 {
        match self {
            State::NotApplicable => 0,
            State::Ok => 1,
            State::Pending => 2,
            State::Off => 3,
            State::Degraded => 4,
            State::Unknown(_) => 5,
            State::Failed => 6,
        }
    }

    /// Stable machine key for the JSON rendering.
    pub fn key(self) -> &'static str {
        match self {
            State::Ok => "ok",
            State::Off => "off",
            State::Degraded => "degraded",
            State::Pending => "pending",
            State::Failed => "failed",
            State::Unknown(_) => "unknown",
            State::NotApplicable => "not_applicable",
        }
    }

    /// Does this state count as a failure for the exit code?
    pub fn is_failure(self) -> bool {
        self == State::Failed
    }

    /// Does this state count as a warning for the exit code?
    pub fn is_warning(self) -> bool {
        matches!(
            self,
            State::Off | State::Degraded | State::Pending | State::Unknown(_)
        )
    }

    /// Must this state carry a code and a remedy?
    ///
    /// Everything the operator is expected to act on must say what to do. The
    /// rule is enforced by [`Check::validate`] and asserted in tests, not left
    /// to review.
    pub fn requires_remedy(self) -> bool {
        self.is_failure() || self.is_warning()
    }

    /// The mark plus its separator, as a fixed five-column field so section
    /// blocks line up in both color and no-color mode.
    ///
    /// The separator is part of the field rather than the format string
    /// because the no-color labels are not all the same length: `WARN` fills
    /// four columns and `OK` two, so a single space in the caller renders
    /// `WARNDisabled` next to `OK  Running`.
    pub fn mark(self, color_enabled: bool) -> String {
        if color_enabled {
            let glyph = match self {
                State::Ok => color::checkmark(true).to_string(),
                State::Failed => color::cross(true).to_string(),
                State::NotApplicable => color::dim("\u{00b7}", true),
                _ => color::warning_mark(true).to_string(),
            };
            format!("{glyph}    ")
        } else {
            let label = match self {
                State::Ok => "OK   ",
                State::Failed => "ERR  ",
                State::NotApplicable => "--   ",
                _ => "WARN ",
            };
            label.to_string()
        }
    }
}

// ---------------------------------------------------------------------------
// Check
// ---------------------------------------------------------------------------

/// One diagnostic finding, belonging to exactly one [`Section`].
///
/// A section holds one or more of these; its state is the worst among them.
#[derive(Debug, Clone)]
pub struct Check {
    pub section: Section,
    pub state: State,
    /// One factual line. No remediation, no hedging.
    pub headline: String,
    /// Extra context lines, rendered indented under the headline.
    pub detail: Vec<String>,
    /// `OL-XXXX`. Required whenever [`State::requires_remedy`].
    pub code: Option<&'static str>,
    /// An exact command or edit. Required whenever [`State::requires_remedy`].
    pub remedy: Option<String>,
    /// Where the state came from — `config.toml:59`, `--no-persistence`,
    /// `keychain`. This is the field that turns "the model relay is off" into
    /// "the model relay is off *because of this line in this file*".
    pub source: Option<String>,
    /// Which agent this check is about — the CloudEvents `source` wire value
    /// (`"claude-code"`). `None` for a host-wide check that belongs to no
    /// single agent. Serialized only when set: absent, never `null`.
    pub agent: Option<&'static str>,
    /// Whether `headline` is still the one [`Check::unknown`] generated, which
    /// already names the blocker. Decides whether the block rendering adds the
    /// separate `waiting on :` line — without it, the default headline and that
    /// line said the same thing twice, one under the other.
    generated_headline: bool,
}

impl Check {
    fn new(section: Section, state: State, headline: impl Into<String>) -> Self {
        Self {
            section,
            state,
            headline: headline.into(),
            detail: Vec::new(),
            code: None,
            remedy: None,
            source: None,
            agent: None,
            generated_headline: false,
        }
    }

    /// Enabled and proven working.
    pub fn ok(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::Ok, headline)
    }

    /// Deliberately switched off.
    pub fn off(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::Off, headline)
    }

    /// Working but not at full capability.
    pub fn degraded(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::Degraded, headline)
    }

    /// Verification still in flight.
    pub fn pending(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::Pending, headline)
    }

    /// Enabled and not working.
    pub fn failed(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::Failed, headline)
    }

    /// Indeterminable because `blocker` failed. Carries its own code and
    /// remedy, so it satisfies the remedy rule without every call site
    /// repeating the same two strings.
    pub fn unknown(section: Section, blocker: Section) -> Self {
        Self {
            section,
            state: State::Unknown(blocker),
            headline: format!("Cannot check — waiting on {}", blocker.title()),
            detail: Vec::new(),
            code: Some(crate::error::ERR_SUBSYSTEM_DEGRADED),
            remedy: Some(format!(
                "Fix {} first, then run `openlatch doctor` again.",
                blocker.title()
            )),
            source: None,
            agent: None,
            generated_headline: true,
        }
    }

    /// Absent from the build or irrelevant on this platform.
    pub fn not_applicable(section: Section, headline: impl Into<String>) -> Self {
        Self::new(section, State::NotApplicable, headline)
    }

    /// Attach the `OL-XXXX` code.
    #[must_use]
    pub fn code(mut self, code: &'static str) -> Self {
        self.code = Some(code);
        self
    }

    /// Attach the exact command or edit that resolves this.
    #[must_use]
    pub fn remedy(mut self, remedy: impl Into<String>) -> Self {
        self.remedy = Some(remedy.into());
        self
    }

    /// Attach where the state came from.
    #[must_use]
    pub fn source(mut self, source: impl Into<String>) -> Self {
        self.source = Some(source.into());
        self
    }

    /// Replace the headline.
    ///
    /// Mostly for [`Check::unknown`], whose generated wording says only that
    /// something is blocked. In a section that also holds green checks, the
    /// compact one-line rendering shows the worst check — so "not determinable"
    /// with no subject reads as if nothing about the section is known, when in
    /// fact one cross-check out of four is waiting on the daemon.
    ///
    /// Overriding it moves the blocker onto its own line in the block
    /// rendering, so it is named exactly once either way.
    #[must_use]
    pub fn headline(mut self, headline: impl Into<String>) -> Self {
        self.headline = headline.into();
        self.generated_headline = false;
        self
    }

    /// Attach one context line.
    #[must_use]
    pub fn detail(mut self, line: impl Into<String>) -> Self {
        self.detail.push(line.into());
        self
    }

    /// Attach one context line when there is one, and nothing when there is not.
    ///
    /// For call sites holding an `Option<String>` a binding already answered —
    /// [`crate::hooks::binding::LivenessReport::detail`] is the one in the tree.
    #[must_use]
    pub fn detail_opt(mut self, line: Option<impl Into<String>>) -> Self {
        if let Some(line) = line {
            self.detail.push(line.into());
        }
        self
    }

    /// Attach the agent this check is about — the wire `agent_type()`.
    ///
    /// A check left unstamped is host-wide, and its JSON carries no `agent`
    /// key at all.
    #[must_use]
    pub fn agent(mut self, agent: &'static str) -> Self {
        self.agent = Some(agent);
        self
    }

    /// Why this check violates the contract, if it does.
    ///
    /// Returns `None` for a well-formed check. Used by [`Report::validate`],
    /// which every rendering path runs under `debug_assert`.
    pub fn validate(&self) -> Option<String> {
        if !self.state.requires_remedy() {
            return None;
        }
        match (self.code, &self.remedy) {
            (Some(_), Some(_)) => None,
            (None, Some(_)) => Some(format!(
                "{}: '{}' is {} but carries no OL-XXXX code",
                self.section.title(),
                self.headline,
                self.state.key()
            )),
            (Some(_), None) => Some(format!(
                "{}: '{}' is {} but carries no remedy",
                self.section.title(),
                self.headline,
                self.state.key()
            )),
            (None, None) => Some(format!(
                "{}: '{}' is {} but carries neither code nor remedy",
                self.section.title(),
                self.headline,
                self.state.key()
            )),
        }
    }

    pub fn to_json(&self) -> serde_json::Value {
        let mut value = serde_json::json!({
            "section": self.section.key(),
            "state": self.state.key(),
            "blocked_by": match self.state {
                State::Unknown(b) => Some(b.key()),
                _ => None,
            },
            // Kept for consumers written against the pre-contract `doctor
            // --json`, where `pass` meant "not a failure" and warnings counted
            // as passes. `state` carries the detail.
            "pass": !self.state.is_failure(),
            "headline": self.headline,
            "detail": self.detail,
            "code": self.code,
            "remedy": self.remedy,
            "source": self.source,
        });
        // Absent, never null: a host-wide check emits no `agent` key at all.
        if let (Some(agent), Some(object)) = (self.agent, value.as_object_mut()) {
            object.insert("agent".into(), serde_json::json!(agent));
        }
        value
    }
}

// ---------------------------------------------------------------------------
// Report
// ---------------------------------------------------------------------------

/// How the machine is doing, as one word.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Overall {
    /// Nothing failed, nothing warned.
    Healthy,
    /// Nothing failed, something warned.
    Degraded,
    /// Something failed.
    Broken,
}

impl Overall {
    pub fn key(self) -> &'static str {
        match self {
            Overall::Healthy => "healthy",
            Overall::Degraded => "degraded",
            Overall::Broken => "broken",
        }
    }

    fn label(self) -> &'static str {
        match self {
            Overall::Healthy => "HEALTHY",
            Overall::Degraded => "DEGRADED",
            Overall::Broken => "BROKEN",
        }
    }
}

/// Tally of check outcomes.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Counts {
    pub ok: usize,
    pub warned: usize,
    pub failed: usize,
}

/// An ordered set of [`Check`]s covering the install.
#[derive(Debug, Clone, Default)]
pub struct Report {
    checks: Vec<Check>,
}

impl Report {
    pub fn new() -> Self {
        Self::default()
    }

    /// Record one finding.
    pub fn push(&mut self, check: Check) {
        debug_assert!(
            check.validate().is_none(),
            "contract violation: {}",
            check.validate().unwrap_or_default()
        );
        self.checks.push(check);
    }

    /// Record one finding, chainable.
    #[must_use]
    pub fn with(mut self, check: Check) -> Self {
        self.push(check);
        self
    }

    /// Drop everything filed under `section` and file `check` instead.
    ///
    /// For the caller that knows something the detectors cannot: `init
    /// --no-start` deliberately leaves the daemon down, and a report that calls
    /// that a failure is describing the flag, not the machine.
    pub fn replace_section(&mut self, section: Section, check: Check) {
        self.checks.retain(|c| c.section != section);
        self.push(check);
    }

    pub fn is_empty(&self) -> bool {
        self.checks.is_empty()
    }

    pub fn checks(&self) -> &[Check] {
        &self.checks
    }

    /// Every check filed under `section`, in push order.
    pub fn section_checks(&self, section: Section) -> impl Iterator<Item = &Check> {
        self.checks.iter().filter(move |c| c.section == section)
    }

    /// The worst state among a section's checks.
    ///
    /// A section with no checks is [`State::NotApplicable`]: the caller either
    /// had nothing to say or the section is absent from the build. Sections are
    /// never silently dropped from the rendering — see [`Report::validate`].
    pub fn section_state(&self, section: Section) -> State {
        self.section_checks(section)
            .map(|c| c.state)
            .max_by_key(|s| s.severity())
            .unwrap_or(State::NotApplicable)
    }

    /// Every agent any check is stamped with, in first-seen order.
    ///
    /// Read off the checks rather than handed in: `check_environment` pushes one
    /// row per detected agent before any other detector runs, so this *is* the
    /// detected set, in detection order. Taking it as a second input would be a
    /// second source of truth about which agents the host has, free to disagree
    /// with the one every check already carries.
    pub fn agents(&self) -> Vec<&'static str> {
        let mut seen: Vec<&'static str> = Vec::new();
        for agent in self.checks.iter().filter_map(|c| c.agent) {
            if !seen.contains(&agent) {
                seen.push(agent);
            }
        }
        seen
    }

    /// The worst state among `agent`'s checks in `section`, or `None` when it
    /// files none there.
    ///
    /// `None` is absence, and deliberately not [`State::NotApplicable`]: that
    /// variant has exactly three sanctioned carve-outs
    /// (`.claude/rules/cli-output-contract.md`), and "this agent has nothing to
    /// say in this section" is not a fourth. The matrix renders it as an em
    /// dash for the same reason.
    pub fn agent_section_state(&self, agent: &str, section: Section) -> Option<State> {
        self.section_checks(section)
            .filter(|c| c.agent.is_some_and(|a| a == agent))
            .map(|c| c.state)
            .max_by_key(|s| s.severity())
    }

    /// The sections carrying at least one agent-tagged check — the matrix's
    /// rows.
    ///
    /// A host-wide check never puts its section on this list. That is what
    /// keeps the relay *listener*, which belongs to the host, out of a table
    /// about per-agent *wiring* — while leaving it exactly where it was in the
    /// section list above.
    fn agent_sections(&self) -> Vec<Section> {
        Section::ALL
            .into_iter()
            .filter(|s| self.section_checks(*s).any(|c| c.agent.is_some()))
            .collect()
    }

    /// Width of the agent-name column on a check row, or `0` when there is no
    /// column to draw.
    ///
    /// Zero on a single-agent host by construction: one agent's name repeated
    /// down every row is a column of the same word, and the rendering there has
    /// to stay byte-identical to a build that had never heard of agents.
    fn agent_column_width(&self) -> usize {
        let agents = self.agents();
        if agents.len() < 2 {
            return 0;
        }
        agents.iter().map(|a| a.chars().count()).max().unwrap_or(0) + 2
    }

    /// Tally across every check.
    pub fn counts(&self) -> Counts {
        let mut counts = Counts::default();
        for check in &self.checks {
            if check.state.is_failure() {
                counts.failed += 1;
            } else if check.state.is_warning() {
                counts.warned += 1;
            } else if check.state == State::Ok {
                counts.ok += 1;
            }
        }
        counts
    }

    pub fn overall(&self) -> Overall {
        let counts = self.counts();
        if counts.failed > 0 {
            Overall::Broken
        } else if counts.warned > 0 {
            Overall::Degraded
        } else {
            Overall::Healthy
        }
    }

    /// The process exit status this report implies.
    ///
    /// `0` healthy · [`EXIT_DEGRADED`] warnings only · `1` at least one
    /// failure.
    pub fn exit_code(&self) -> i32 {
        match self.overall() {
            Overall::Healthy => 0,
            Overall::Degraded => EXIT_DEGRADED,
            Overall::Broken => 1,
        }
    }

    /// Record [`Report::exit_code`] as the process verdict.
    pub fn record_verdict(&self) {
        record_exit_code(self.exit_code());
    }

    /// Every way this report violates the contract.
    ///
    /// Two rules: each non-`Ok`, non-`NotApplicable` check carries a code and a
    /// remedy, and all eleven sections are represented. Empty means conforming.
    pub fn validate(&self) -> Vec<String> {
        let mut problems: Vec<String> = self.checks.iter().filter_map(Check::validate).collect();
        for section in Section::ALL {
            if self.section_checks(section).next().is_none() {
                problems.push(format!(
                    "{} has no check — every section is always reported (P6)",
                    section.title()
                ));
            }
        }
        problems
    }

    /// The actionable half of every non-green check, ready to print under the
    /// section blocks.
    pub fn issues(&self) -> Vec<String> {
        self.checks
            .iter()
            .filter(|c| c.state.requires_remedy())
            .map(|c| {
                let mut line = format!("{} — {}", c.section.title(), c.headline);
                if let Some(remedy) = &c.remedy {
                    line.push(' ');
                    line.push_str(remedy);
                }
                line
            })
            .collect()
    }

    // -----------------------------------------------------------------------
    // Rendering
    // -----------------------------------------------------------------------

    /// The full section-by-section rendering used by `doctor` and by the report
    /// half of `init`.
    ///
    /// A section holding exactly one `Ok` or `NotApplicable` check collapses to
    /// a single padded line; anything the operator might need to act on gets a
    /// full block with its source and remedy. The rule is mechanical, so the
    /// same state always renders the same way.
    pub fn render(&self, output: &OutputConfig) {
        debug_assert!(
            self.validate().is_empty(),
            "contract violations: {:?}",
            self.validate()
        );
        if output.format == OutputFormat::Json || output.quiet {
            return;
        }

        let counts = self.counts();
        let overall = self.overall();
        let headline = format!(
            "Overall: {} — {} failed, {} warning{}, {} ok",
            overall.label(),
            counts.failed,
            counts.warned,
            if counts.warned == 1 { "" } else { "s" },
            counts.ok,
        );
        eprintln!(
            "{}",
            match overall {
                Overall::Healthy => color::green(&headline, output.color),
                Overall::Degraded => headline.clone(),
                Overall::Broken => color::red(&headline, output.color),
            }
        );
        eprintln!();

        // Three group headings, eleven section lines, and detail only where
        // something needs attention.
        //
        // The flat form gave every section its own heading, which is eleven
        // headings for twenty lines of content — and once the sections that
        // held a single check collapsed onto their title line, the marks
        // scattered across as many columns as there were title lengths.
        // Grouping fixes both: one scan column for the marks, and the green
        // sections fold into a line each, so what stays on screen is mostly
        // the things that do not pass. `--verbose` unfolds everything.
        for group in Group::ALL {
            eprintln!("{}", color::bold(group.title(), output.color));
            for section in Section::of_group(group) {
                self.render_section_line(section, output);
            }
            eprintln!();
        }

        // Which agent, on a host with more than one. The section lines above
        // answer "is anything wrong"; a worst-wins rollup cannot also answer
        // "wrong for whom", and on a two-agent host that is most of the
        // question.
        let matrix = self.agent_matrix_lines(0, 2, output);
        if !matrix.is_empty() {
            for line in &matrix {
                eprintln!("{line}");
            }
            eprintln!();
        }
    }

    /// One section as a line under its group, plus whatever needs saying.
    fn render_section_line(&self, section: Section, output: &OutputConfig) {
        for line in self.section_lines(section, output) {
            eprintln!("{line}");
        }
    }

    /// One section's lines under its group heading, ready to print.
    ///
    /// A green section is a line. A section with anything else on it lists each
    /// non-green check, every mark in the same column, each followed by its own
    /// detail, source and remedy.
    ///
    /// Built rather than printed because the claim this rendering now carries —
    /// a single-agent host looks exactly as it did, a multi-agent one names the
    /// agent on every row belonging to one — is a claim about bytes, and bytes
    /// on a process's stderr are not assertable from a unit test.
    fn section_lines(&self, section: Section, output: &OutputConfig) -> Vec<String> {
        let state = self.section_state(section);
        let title_cell = format!("  {:<TITLE_WIDTH$}  ", section.title());
        // Blank cell of the same width, so a second finding in one section puts
        // its mark under the first rather than after the title.
        let blank_cell = " ".repeat(title_cell.len());

        let interesting: Vec<&Check> = if output.verbose {
            self.section_checks(section).collect()
        } else {
            self.section_checks(section)
                .filter(|c| c.state.requires_remedy())
                .collect()
        };

        if interesting.is_empty() {
            return vec![format!(
                "{title_cell}{}{}",
                state.mark(output.color),
                self.section_summary(section)
            )];
        }

        // The agent column is drawn only where there is an agent to name. A
        // section whose findings are all host-wide — Daemon, Cloud, Persistence
        // — renders exactly as it does on a one-agent host, rather than carrying
        // an empty column for a distinction it does not have.
        let agent_width = if interesting.iter().any(|c| c.agent.is_some()) {
            self.agent_column_width()
        } else {
            0
        };
        let indent = " ".repeat(title_cell.len() + MARK_WIDTH + agent_width);

        let mut lines = Vec::new();
        for (index, check) in interesting.iter().enumerate() {
            let cell = if index == 0 { &title_cell } else { &blank_cell };
            lines.push(format!(
                "{cell}{}{}{}{}",
                check.state.mark(output.color),
                agent_cell(check, agent_width, output.color),
                check.headline,
                match check.code {
                    Some(code) if check.state.requires_remedy() =>
                        format!("   {}", color::dim(&format!("[{code}]"), output.color)),
                    _ => String::new(),
                }
            ));
            lines.extend(self.continuation_lines(check, &indent, output));
        }
        lines
    }

    /// The agent × subsystem matrix: which agent is in what state, where.
    ///
    /// Empty on a single-agent host — one column is a list, and the section
    /// lines above already are that list — and empty when nothing is tagged.
    ///
    /// A cell is the worst state among that agent's checks in that section: the
    /// same rollup [`Report::section_state`] applies to a section as a whole,
    /// applied per agent. That is the whole point of the table. `section_state`
    /// stays worst-wins, because if one agent is broken something *is* broken;
    /// this says *which*.
    ///
    /// A cell for an agent that files nothing in that section is an em dash — a
    /// rendering fact about absence, not [`State::NotApplicable`].
    fn agent_matrix_lines(
        &self,
        heading_indent: usize,
        row_indent: usize,
        output: &OutputConfig,
    ) -> Vec<String> {
        let agents = self.agents();
        let sections = self.agent_sections();
        if agents.len() < 2 || sections.is_empty() {
            return Vec::new();
        }

        // Each column as wide as its own heading, and never narrower than the
        // mark it has to hold.
        let widths: Vec<usize> = agents
            .iter()
            .map(|a| a.chars().count().max(MARK_WIDTH) + 2)
            .collect();

        let mut lines = vec![format!(
            "{}{}",
            " ".repeat(heading_indent),
            color::bold("Agents", output.color)
        )];

        let row = " ".repeat(row_indent);
        let mut header = format!("{row}{}", " ".repeat(TITLE_WIDTH + 2));
        for (agent, width) in agents.iter().zip(&widths) {
            header.push_str(&pad_to(
                &color::dim(agent, output.color),
                agent.chars().count(),
                *width,
            ));
        }
        lines.push(header.trim_end().to_string());

        for section in sections {
            let mut line = format!("{row}{:<TITLE_WIDTH$}  ", section.title());
            for (agent, width) in agents.iter().zip(&widths) {
                line.push_str(&match self.agent_section_state(agent, section) {
                    Some(state) => pad_to(&state.mark(output.color), MARK_WIDTH, *width),
                    None => pad_to(&color::dim("\u{2014}", output.color), 1, *width),
                });
            }
            lines.push(line.trim_end().to_string());
        }
        lines
    }

    /// The one line a section that needs no attention gets.
    ///
    /// A single check speaks for itself. Several collapse to a count — and the
    /// count separates "passed" from "not applicable", because a build without
    /// crash reporting has not passed a crash-reporting check, it has skipped
    /// one.
    fn section_summary(&self, section: Section) -> String {
        let checks: Vec<&Check> = self.section_checks(section).collect();
        match checks.as_slice() {
            [] => "no data".to_string(),
            [only] => only.headline.clone(),
            many => {
                let passed = many.iter().filter(|c| c.state == State::Ok).count();
                let skipped = many.len() - passed;
                if skipped == 0 {
                    format!("{passed} checks passed")
                } else {
                    format!("{passed} passed, {skipped} not applicable")
                }
            }
        }
    }

    /// A check's detail, source and remedy, at a caller-chosen indent.
    fn continuation_lines(
        &self,
        check: &Check,
        indent: &str,
        output: &OutputConfig,
    ) -> Vec<String> {
        let mut lines = Vec::new();
        // Structural, not prose: an `Unknown` whose headline was replaced names
        // its blocker on its own line, so a reader — and a test — can rely on
        // the line rather than on a phrase surviving an edit. Skipped when the
        // headline is still the generated one, which already carries the
        // blocker; printing both put the same sentence twice.
        if let (State::Unknown(blocker), false) = (check.state, check.generated_headline) {
            lines.push(format!(
                "{indent}{}",
                color::dim(&format!("waiting on : {}", blocker.title()), output.color)
            ));
        }
        for line in &check.detail {
            lines.push(format!("{indent}{}", color::dim(line, output.color)));
        }
        if let Some(source) = &check.source {
            lines.push(format!(
                "{indent}{}",
                color::dim(&format!("found in : {source}"), output.color)
            ));
        }
        if let Some(remedy) = &check.remedy {
            lines.push(format!(
                "{indent}{}",
                color::dim(&format!("to fix : {remedy}"), output.color)
            ));
        }
        lines
    }

    /// Print one section's block — title, every check, sources and remedies.
    ///
    /// The building block behind both [`Report::render`] and the
    /// per-subsystem status commands, so `openlatch system hooks status` and the Hooks
    /// block of `openlatch doctor` are the same text by construction.
    pub fn render_section(&self, section: Section, output: &OutputConfig) {
        if output.format == OutputFormat::Json || output.quiet {
            return;
        }
        eprintln!("{}", color::bold(section.title(), output.color));
        let checks: Vec<&Check> = self.section_checks(section).collect();
        // Same rule as the grouped rendering: name the agent wherever there is
        // one to name, and leave a section of host-wide findings alone.
        let agent_width = if checks.iter().any(|c| c.agent.is_some()) {
            self.agent_column_width()
        } else {
            0
        };
        let indent = format!("{CONTINUATION}{}", " ".repeat(agent_width));
        for check in checks {
            eprintln!(
                "  {}{}{}{}",
                check.state.mark(output.color),
                agent_cell(check, agent_width, output.color),
                check.headline,
                match check.code {
                    Some(code) if check.state.requires_remedy() =>
                        format!("   {}", color::dim(&format!("[{code}]"), output.color)),
                    _ => String::new(),
                }
            );
            for line in self.continuation_lines(check, &indent, output) {
                eprintln!("{line}");
            }
        }
    }

    /// One line per section, worst state wins — the `status` rendering.
    ///
    /// Carries no remedies on purpose: `status` is the glance, `doctor` is the
    /// diagnosis. A non-green section here points at `doctor`.
    pub fn render_compact(&self, output: &OutputConfig) {
        if output.format == OutputFormat::Json || output.quiet {
            return;
        }
        // Same groups and the same columns as `doctor`, one line per section
        // and nothing else. `status` is the glance; a reader who wants the
        // cause and the remedy is one command away, and told so.
        for group in Group::ALL {
            eprintln!("  {}", color::bold(group.title(), output.color));
            for section in Section::of_group(group) {
                let state = self.section_state(section);
                // The worst check is the one worth summarising; ties go to the
                // first pushed, which is the most fundamental by construction.
                let headline = if state.requires_remedy() {
                    self.section_checks(section)
                        .filter(|c| c.state == state)
                        .map(|c| c.headline.clone())
                        .next()
                        .unwrap_or_else(|| "no data".to_string())
                } else {
                    self.section_summary(section)
                };
                eprintln!(
                    "    {:<TITLE_WIDTH$}  {}{}",
                    section.title(),
                    state.mark(output.color),
                    headline
                );
            }
        }

        // `status` is the glance, so it gets the matrix and not the labelled
        // rows: the rows it prints are section rollups, and a rollup belongs to
        // no single agent. The matrix is the whole per-agent answer at a glance.
        let matrix = self.agent_matrix_lines(2, 4, output);
        if !matrix.is_empty() {
            eprintln!();
            for line in &matrix {
                eprintln!("{line}");
            }
        }

        if self.overall() != Overall::Healthy {
            eprintln!();
            eprintln!("  Run `openlatch doctor` for causes and remedies.");
        }
    }

    /// The machine rendering. Isomorphic to the human one (P7).
    pub fn to_json(&self) -> serde_json::Value {
        let counts = self.counts();

        // The per-agent rollup, keyed by agent rather than listed, so a
        // consumer indexes into it — and so everything else `doctor` has to say
        // about one agent lands in the same object rather than in a second
        // top-level key about the same subject.
        //
        // Built here rather than inline in the `json!` below: a multi-line
        // expression carrying a turbofish in a `json!` value position is a
        // tt-muncher away from silently producing the wrong shape, and this one
        // was — it emitted `{}` in the shipped binary while this module's own
        // tests saw the right thing.
        //
        // A section an agent files nothing in is absent from its list rather
        // than null: the rule the per-check `agent` tag follows, and the JSON of
        // the matrix's em dash.
        let mut agents = serde_json::Map::new();
        for agent in self.agents() {
            let sections: Vec<serde_json::Value> = Section::ALL
                .iter()
                .filter_map(|section| {
                    self.agent_section_state(agent, *section).map(|state| {
                        serde_json::json!({
                            "section": section.key(),
                            "state": state.key(),
                        })
                    })
                })
                .collect();
            agents.insert(
                agent.to_string(),
                serde_json::json!({ "sections": sections }),
            );
        }
        let sections: Vec<serde_json::Value> = Section::ALL
            .iter()
            .map(|section| {
                serde_json::json!({
                    "section": section.key(),
                    "group": section.group().key(),
                    "state": self.section_state(*section).key(),
                    "summary": self.section_summary(*section),
                    "checks": self
                        .section_checks(*section)
                        .map(Check::to_json)
                        .collect::<Vec<_>>(),
                })
            })
            .collect();

        serde_json::json!({
            "overall": self.overall().key(),
            "exit_code": self.exit_code(),
            "groups": Group::ALL
                .iter()
                .map(|g| serde_json::json!({
                    "group": g.key(),
                    "sections": Section::of_group(*g)
                        .map(|s| s.key())
                        .collect::<Vec<_>>(),
                }))
                .collect::<Vec<_>>(),
            "summary": {
                "ok": counts.ok,
                "warned": counts.warned,
                "failed": counts.failed,
            },
            "sections": sections,
            "issues": self.issues(),
            // Additive and last: every key above keeps its shape and its
            // position. An empty object on a host with no agent, never a
            // missing key, so a consumer indexes into one shape everywhere.
            "agents": serde_json::Value::Object(agents),
        })
    }
}

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

    fn plain() -> OutputConfig {
        OutputConfig {
            format: OutputFormat::Human,
            verbose: false,
            debug: false,
            quiet: true, // rendering is exercised separately; keep tests silent
            color: false,
        }
    }

    /// Fill every section with a passing check so a test can then override the
    /// one section it cares about.
    fn all_green() -> Report {
        let mut report = Report::new();
        for section in Section::ALL {
            report.push(Check::ok(section, "fine"));
        }
        report
    }

    #[test]
    fn a_healthy_report_exits_zero() {
        let report = all_green();
        assert_eq!(report.overall(), Overall::Healthy);
        assert_eq!(report.exit_code(), 0);
    }

    #[test]
    fn a_disabled_feature_warns_and_exits_two() {
        let mut report = all_green();
        report.push(
            Check::off(Section::ModelRelay, "Disabled in config")
                .code(crate::error::ERR_MODEL_RELAY_NOT_RUNNING)
                .remedy("set [model_relay] enabled = true, then `openlatch restart`"),
        );
        assert_eq!(report.section_state(Section::ModelRelay), State::Off);
        assert_eq!(report.overall(), Overall::Degraded);
        assert_eq!(report.exit_code(), EXIT_DEGRADED);
    }

    #[test]
    fn a_failure_outranks_a_warning() {
        let mut report = all_green();
        report.push(
            Check::off(Section::Persistence, "Disabled")
                .code(crate::error::ERR_NO_SUPERVISOR)
                .remedy("`openlatch system supervision enable`"),
        );
        report.push(
            Check::failed(Section::ModelRelay, "Cannot bind 7600")
                .code(crate::error::ERR_MODEL_RELAY_PORT_IN_USE)
                .remedy("free the port"),
        );
        assert_eq!(report.overall(), Overall::Broken);
        assert_eq!(report.exit_code(), 1);
    }

    #[test]
    fn a_section_takes_the_worst_state_of_its_checks() {
        let mut report = all_green();
        report.push(Check::ok(Section::Daemon, "port bound"));
        report.push(
            Check::degraded(Section::Daemon, "one subsystem restarting")
                .code(crate::error::ERR_SUBSYSTEM_DEGRADED)
                .remedy("check the daemon log"),
        );
        assert_eq!(report.section_state(Section::Daemon), State::Degraded);
    }

    #[test]
    fn every_non_ok_check_carries_a_code_and_a_remedy() {
        // The rule, exercised over every constructor that can produce a
        // remedy-requiring state.
        let offenders = [
            Check::off(Section::Cloud, "x"),
            Check::degraded(Section::Cloud, "x"),
            Check::pending(Section::Cloud, "x"),
            Check::failed(Section::Cloud, "x"),
        ];
        for check in offenders {
            assert!(
                check.validate().is_some(),
                "{} without code/remedy must be rejected",
                check.state.key()
            );
        }
        // `unknown` supplies its own, so it is well-formed out of the box.
        assert!(Check::unknown(Section::Cloud, Section::Daemon)
            .validate()
            .is_none());
        // As are the two states that need no action.
        assert!(Check::ok(Section::Cloud, "x").validate().is_none());
        assert!(Check::not_applicable(Section::Cloud, "x")
            .validate()
            .is_none());
    }

    #[test]
    fn a_dead_daemon_produces_exactly_one_failure() {
        // Anti-cascade: the daemon fails, the seven sections behind it report
        // Unknown, and the report still shows a single cross.
        let mut report = Report::new();
        report.push(Check::ok(Section::Environment, "fine"));
        report.push(
            Check::failed(Section::Daemon, "not running")
                .code(crate::error::ERR_DAEMON_START_FAILED)
                .remedy("`openlatch start`"),
        );
        for section in [
            Section::Hooks,
            Section::ModelRelay,
            Section::Connection,
            Section::Cloud,
            Section::Policy,
            Section::Inventory,
            Section::Integrity,
        ] {
            report.push(Check::unknown(section, Section::Daemon));
        }
        report.push(Check::ok(Section::Persistence, "fine"));
        report.push(Check::not_applicable(Section::Telemetry, "opt-out"));
        report.push(Check::ok(Section::Update, "current"));

        assert_eq!(report.counts().failed, 1);
        assert_eq!(report.overall(), Overall::Broken);
        assert!(report.validate().is_empty(), "{:?}", report.validate());
    }

    #[test]
    fn validate_rejects_a_missing_section() {
        let mut report = Report::new();
        report.push(Check::ok(Section::Daemon, "fine"));
        let problems = report.validate();
        assert!(
            problems.iter().any(|p| p.contains("Model Relay")),
            "a missing section must be reported: {problems:?}"
        );
    }

    #[test]
    fn every_section_belongs_to_exactly_one_non_empty_group() {
        // The taxonomy has to partition the sections: a section in no group
        // would vanish from the rendering, and an empty group would print a
        // heading with nothing under it.
        let grouped: Vec<Section> = Group::ALL
            .iter()
            .flat_map(|g| Section::of_group(*g))
            .collect();
        assert_eq!(
            grouped.len(),
            Section::ALL.len(),
            "every section belongs to exactly one group"
        );
        for group in Group::ALL {
            assert!(
                Section::of_group(group).next().is_some(),
                "{} has no sections",
                group.title()
            );
        }
    }

    #[test]
    fn section_order_follows_group_order() {
        // The rendering walks groups and then sections; `Section::ALL` is what
        // the JSON walks. If the two disagree, a reader comparing `doctor` with
        // `doctor --json` sees the same sections in two different orders.
        let grouped: Vec<Section> = Group::ALL
            .iter()
            .flat_map(|g| Section::of_group(*g))
            .collect();
        assert_eq!(grouped, Section::ALL.to_vec());
    }

    #[test]
    fn a_green_section_collapses_and_a_problem_does_not() {
        let mut report = Report::new();
        for section in Section::ALL {
            report.push(Check::ok(section, "fine"));
        }
        report.push(Check::ok(Section::Hooks, "also fine"));
        assert_eq!(
            report.section_summary(Section::Hooks),
            "2 checks passed",
            "several green checks collapse to a count"
        );
        assert_eq!(
            report.section_summary(Section::Daemon),
            "fine",
            "a lone check speaks for itself"
        );

        // "Passed" and "skipped" are different claims: a build without crash
        // reporting has not passed a crash-reporting check.
        report.push(Check::not_applicable(Section::Update, "not compiled in"));
        assert_eq!(
            report.section_summary(Section::Update),
            "1 passed, 1 not applicable"
        );
    }

    #[test]
    fn human_and_json_carry_the_same_sections() {
        let report = all_green();
        let json = report.to_json();
        let sections = json["sections"].as_array().expect("sections array");
        assert_eq!(sections.len(), Section::ALL.len());
        for (rendered, expected) in sections.iter().zip(Section::ALL) {
            assert_eq!(rendered["section"], expected.key());
        }
    }

    #[test]
    fn json_keeps_the_legacy_pass_field_meaning_not_a_failure() {
        let warn = Check::off(Section::ModelRelay, "off")
            .code(crate::error::ERR_MODEL_RELAY_NOT_RUNNING)
            .remedy("x");
        assert_eq!(warn.to_json()["pass"], serde_json::Value::Bool(true));
        let fail = Check::failed(Section::ModelRelay, "broken")
            .code(crate::error::ERR_MODEL_RELAY_PORT_IN_USE)
            .remedy("x");
        assert_eq!(fail.to_json()["pass"], serde_json::Value::Bool(false));
    }

    #[test]
    fn check_agent_is_absent_not_null_when_unset() {
        // A host-wide check emits no `agent` key at all — an unconditional
        // `"agent": null` on every check would move the JSON of every existing
        // consumer, which is what the byte-diff gate exists to catch.
        let host_wide = Check::ok(Section::ModelRelay, "listening");
        let json = host_wide.to_json();
        assert!(
            json.get("agent").is_none(),
            "an unstamped check must carry no `agent` key, not a null one: {json}"
        );

        let stamped = Check::ok(Section::Hooks, "installed").agent("claude-code");
        assert_eq!(stamped.to_json()["agent"], serde_json::json!("claude-code"));
    }

    #[test]
    fn a_blocker_is_named_exactly_once() {
        // Two renderings, one fact. The generated headline carries the blocker
        // and the structural line is suppressed; an overridden headline says
        // something more useful and the structural line supplies the blocker.
        let generated = Check::unknown(Section::Policy, Section::Cloud);
        assert!(
            generated.headline.contains("Cloud"),
            "the generated headline must name the blocker for the compact view"
        );
        assert!(
            generated.generated_headline,
            "an untouched `unknown` keeps its generated headline"
        );

        let overridden = Check::unknown(Section::Policy, Section::Cloud)
            .headline("Enforcement state unknown — the platform is unreachable");
        assert!(
            !overridden.generated_headline,
            "overriding the headline hands the blocker to the structural line"
        );
        assert!(
            !overridden.headline.contains("Cloud"),
            "an overridden headline is free not to repeat the blocker"
        );
    }

    #[test]
    fn marks_are_five_columns_wide_in_no_color_mode() {
        for state in [
            State::Ok,
            State::Off,
            State::Degraded,
            State::Pending,
            State::Failed,
            State::Unknown(Section::Daemon),
            State::NotApplicable,
        ] {
            assert_eq!(state.mark(false).len(), 5, "{:?} misaligns", state);
        }
    }

    #[test]
    fn the_recorded_verdict_keeps_the_worst_code() {
        // Severity, not numeric order: a failure must survive a later warning.
        reset_exit_code();
        record_exit_code(EXIT_DEGRADED);
        record_exit_code(1);
        assert_eq!(pending_exit_code(), 1, "failure outranks degraded");

        reset_exit_code();
        record_exit_code(1);
        record_exit_code(EXIT_DEGRADED);
        assert_eq!(pending_exit_code(), 1, "degraded cannot clear a failure");

        reset_exit_code();
        record_exit_code(EXIT_DEGRADED);
        record_exit_code(0);
        assert_eq!(
            pending_exit_code(),
            EXIT_DEGRADED,
            "success cannot clear a warning"
        );

        reset_exit_code();
        assert_eq!(pending_exit_code(), 0);
    }

    #[test]
    fn rendering_is_silent_in_quiet_mode() {
        // Not an output assertion — a smoke test that the guarded paths do not
        // panic on a fully-populated report.
        let report = all_green();
        report.render(&plain());
        report.render_compact(&plain());
        // The same, with the per-agent renderings live.
        let two = two_agent_report();
        two.render(&plain());
        two.render_compact(&plain());
    }

    // -----------------------------------------------------------------------
    // Per-agent reporting
    // -----------------------------------------------------------------------

    /// Everything unfolded: the non-verbose rendering shows only what needs
    /// acting on, and half of what these tests assert is how a *passing* row
    /// renders.
    fn unfolded() -> OutputConfig {
        OutputConfig {
            verbose: true,
            ..plain()
        }
    }

    /// A two-agent host: hooks enforcing for one and dead for the other, a
    /// model relay wired for one and unread for the other, and every section
    /// also carrying the untagged host-wide check `all_green` pushes.
    fn two_agent_report() -> Report {
        let mut report = all_green();
        report.push(Check::ok(Section::Environment, "Agent: Claude Code").agent("claude-code"));
        report.push(Check::ok(Section::Environment, "Agent: Codex CLI").agent("codex-cli"));
        report.push(Check::ok(Section::Hooks, "Enforced").agent("claude-code"));
        report.push(
            Check::failed(
                Section::Hooks,
                "Monitored — installed and capturing, enforcing nothing",
            )
            .code(crate::error::ERR_HOOK_CONFLICT)
            .remedy("Trust the hook group.")
            .agent("codex-cli"),
        );
        report.push(
            Check::ok(Section::ModelRelay, "Agent wired to the listener").agent("claude-code"),
        );
        report
    }

    #[test]
    fn agents_are_named_once_each_in_detection_order() {
        // Order is detection order because Environment pushes one row per
        // detected agent first. A set would sort them, and the columns would
        // stop matching the Environment rows a reader just scanned.
        let report = two_agent_report();
        assert_eq!(report.agents(), vec!["claude-code", "codex-cli"]);
        assert_eq!(
            all_green().agents(),
            Vec::<&str>::new(),
            "a report with nothing tagged names no agents"
        );
    }

    #[test]
    fn a_cell_is_the_worst_of_that_agents_checks_in_that_section() {
        let mut report = two_agent_report();
        report.push(
            Check::degraded(Section::Hooks, "Staged binary is a release behind")
                .code(crate::error::ERR_HOOK_CONFLICT)
                .remedy("`openlatch doctor --fix`")
                .agent("claude-code"),
        );
        // Degraded now outranks the Ok, for that agent only.
        assert_eq!(
            report.agent_section_state("claude-code", Section::Hooks),
            Some(State::Degraded)
        );
        assert_eq!(
            report.agent_section_state("codex-cli", Section::Hooks),
            Some(State::Failed)
        );
        // And the section rollup stays worst-wins across both, unchanged: the
        // matrix answers *which*, the section answers *is anything wrong*.
        assert_eq!(report.section_state(Section::Hooks), State::Failed);
    }

    #[test]
    fn an_agent_that_files_nothing_in_a_section_has_no_state() {
        // Absence, not a state — and specifically not `NotApplicable`, which has
        // three sanctioned carve-outs and no room for a fourth.
        let report = two_agent_report();
        assert_eq!(
            report.agent_section_state("codex-cli", Section::ModelRelay),
            None
        );
        let matrix = report.agent_matrix_lines(0, 2, &plain()).join("\n");
        let relay = matrix
            .lines()
            .find(|l| l.contains(Section::ModelRelay.title()))
            .expect("the matrix must carry a Model Relay row");
        assert!(
            relay.contains('\u{2014}'),
            "an agent with no check there renders an em dash: {relay:?}"
        );
        assert!(
            !relay.contains(State::NotApplicable.mark(false).trim()),
            "the em dash must not be a NotApplicable mark in disguise: {relay:?}"
        );
    }

    #[test]
    fn a_host_wide_check_never_reaches_the_matrix() {
        // The relay listener belongs to the host; the wiring belongs to an
        // agent. The matrix renders only the tagged half — and the untagged
        // half stays exactly where it was, in the section list.
        let mut report = all_green();
        report.push(Check::ok(Section::Environment, "Agent: Claude Code").agent("claude-code"));
        report.push(Check::ok(Section::Environment, "Agent: Codex CLI").agent("codex-cli"));
        report.push(Check::ok(
            Section::ModelRelay,
            "Listening on 127.0.0.1:7600",
        ));

        let matrix = report.agent_matrix_lines(0, 2, &plain()).join("\n");
        assert!(
            !matrix.contains(Section::ModelRelay.title()),
            "an untagged section has no matrix row: {matrix}"
        );
        assert!(
            matrix.contains(Section::Environment.title()),
            "the tagged section does: {matrix}"
        );
        assert!(
            report
                .section_lines(Section::ModelRelay, &unfolded())
                .iter()
                .any(|l| l.contains("Listening on")),
            "the host-wide check still renders in its own section"
        );
    }

    #[test]
    fn a_single_agent_host_renders_exactly_as_an_untagged_one() {
        // The whole per-agent rendering is switched off below two agents: one
        // name repeated down every row is a column of the same word, and a
        // matrix with one column is the list that is already above it.
        let mut tagged = all_green();
        tagged.push(Check::ok(Section::Environment, "Agent: Claude Code").agent("claude-code"));
        tagged.push(Check::ok(Section::Hooks, "Enforced").agent("claude-code"));

        let mut untagged = all_green();
        untagged.push(Check::ok(Section::Environment, "Agent: Claude Code"));
        untagged.push(Check::ok(Section::Hooks, "Enforced"));

        for section in Section::ALL {
            assert_eq!(
                tagged.section_lines(section, &unfolded()),
                untagged.section_lines(section, &unfolded()),
                "{} renders differently once a single agent is tagged",
                section.title()
            );
        }
        assert_eq!(tagged.agent_column_width(), 0);
        assert!(tagged.agent_matrix_lines(0, 2, &unfolded()).is_empty());
    }

    #[test]
    fn both_agents_are_named_on_the_rows_that_belong_to_them() {
        // The symptom this closes: `✓ Enforced` over `✗ Monitored`, under one
        // heading, with nothing saying which agent is which.
        let report = two_agent_report();
        let hooks = report.section_lines(Section::Hooks, &unfolded());
        let enforced = hooks
            .iter()
            .find(|l| l.contains("Enforced"))
            .expect("the passing row");
        let monitored = hooks
            .iter()
            .find(|l| l.contains("Monitored"))
            .expect("the failing row");
        assert!(enforced.contains("claude-code"), "{enforced:?}");
        assert!(monitored.contains("codex-cli"), "{monitored:?}");

        // The host-wide check in the same section is padded, not named, and the
        // headlines all start in one column.
        let host_wide = hooks
            .iter()
            .find(|l| l.contains("fine"))
            .expect("the untagged row");
        assert!(!host_wide.contains("claude-code") && !host_wide.contains("codex-cli"));
        let column = |line: &str, needle: &str| line.find(needle).expect("headline");
        assert_eq!(
            column(enforced, "Enforced"),
            column(monitored, "Monitored"),
            "headlines must share a column"
        );
        assert_eq!(column(enforced, "Enforced"), column(host_wide, "fine"));
    }

    #[test]
    fn the_matrix_has_one_column_per_agent_and_one_row_per_tagged_section() {
        let report = two_agent_report();
        let lines = report.agent_matrix_lines(0, 2, &plain());
        let header = &lines[1];
        assert!(header.contains("claude-code") && header.contains("codex-cli"));

        let rows: Vec<&String> = lines[2..].iter().collect();
        let titles: Vec<&str> = rows
            .iter()
            .map(|l| l.trim_start().split("  ").next().unwrap_or_default())
            .collect();
        assert_eq!(
            titles,
            vec![
                Section::Environment.title(),
                Section::Hooks.title(),
                Section::ModelRelay.title()
            ],
            "only the sections carrying agent-tagged checks get a row, in section order"
        );
    }

    #[test]
    fn three_agents_still_fit_eighty_columns() {
        let mut report = all_green();
        for agent in ["claude-code", "codex-cli", "cline"] {
            report.push(Check::ok(Section::Environment, format!("Agent: {agent}")).agent(agent));
            report.push(Check::ok(Section::Hooks, "Enforced").agent(agent));
        }
        for line in report.agent_matrix_lines(2, 4, &plain()) {
            assert!(
                line.chars().count() <= 80,
                "the matrix must not overflow 80 columns: {} wide — {line:?}",
                line.chars().count()
            );
        }
    }

    #[test]
    fn json_gains_a_per_agent_rollup_and_moves_nothing() {
        let report = two_agent_report();
        let before = all_green().to_json();
        let json = report.to_json();

        // Every pre-existing key keeps its shape.
        for key in [
            "overall",
            "exit_code",
            "groups",
            "summary",
            "sections",
            "issues",
        ] {
            assert!(json.get(key).is_some(), "{key} must survive");
        }
        // An empty OBJECT, never a missing key: a consumer indexes into one
        // shape on every host, including one with no agent at all.
        assert_eq!(before["agents"], serde_json::json!({}));

        let agents = json["agents"].as_object().expect("an agents object");
        assert_eq!(agents.len(), 2);
        assert!(agents.contains_key("claude-code") && agents.contains_key("codex-cli"));

        let codex: Vec<(&str, &str)> = agents["codex-cli"]["sections"]
            .as_array()
            .expect("sections")
            .iter()
            .map(|s| {
                (
                    s["section"].as_str().unwrap_or_default(),
                    s["state"].as_str().unwrap_or_default(),
                )
            })
            .collect();
        assert_eq!(
            codex,
            vec![("environment", "ok"), ("hooks", "failed")],
            "a section the agent files nothing in is absent, not null"
        );
    }

    #[test]
    fn the_rollup_is_an_object_a_consumer_can_index() {
        // Pinned because it was wrong once, and silently. The rollup began as an
        // inline expression in a `json!` value position, and the macro produced
        // `{}` in the shipped binary while this module's own tests saw the right
        // thing — the shape was never asserted, only its contents. Assert the
        // type.
        let json = two_agent_report().to_json();
        assert!(
            json["agents"].is_object(),
            "the rollup is keyed by agent, not listed: {}",
            json["agents"]
        );
        assert!(json["agents"]["claude-code"]["sections"].is_array());
    }
}