rch 2.1.25

//! Diagnostic command implementation for `rch doctor`.
//!
//! Runs comprehensive diagnostics and optionally auto-fixes common issues.

use crate::agent::{AgentKind, install_hook};
use crate::commands::{
    DoctorCheck, DoctorCheckStatus, DoctorFixApplied, DoctorResponse, DoctorSummary, config_dir,
    load_workers_from_config, send_daemon_command,
};
use crate::state::primitives::IdempotentResult;
use crate::status_display::query_daemon_full_status;
use crate::status_types::{
    DaemonFullStatusResponse, RepoConvergenceStatusFromApi, WorkerStatusFromApi, extract_json_body,
};
use crate::ui::context::OutputContext;
use crate::ui::theme::StatusIndicator;
use anyhow::Result;
use directories::ProjectDirs;
use rch_common::rsync_flavor::{ResolvedRsync, RsyncFlavor, RsyncResolveError, resolve_rsync};
use rch_common::{ApiResponse, ReliabilityReasonCode};
use rch_telemetry::TelemetryStorage;
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use std::io::{self, Read, Write};
#[cfg(unix)]
use std::os::unix::fs::PermissionsExt;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::time::{Duration, Instant};
use which::which;

/// Default socket path (XDG_RUNTIME_DIR -> ~/.cache/rch -> /tmp fallback).
fn default_socket_path() -> PathBuf {
    PathBuf::from(rch_common::default_socket_path())
}

fn configured_or_default_socket_path() -> PathBuf {
    crate::commands::configured_socket_path()
        .map(PathBuf::from)
        .unwrap_or_else(|_| default_socket_path())
}

/// Maximum size of a config / settings file we'll read into memory.
/// Bounds OOM risk if a hostile or corrupted file is gigabytes in size.
/// Real RCH/Claude config files are well under 1 MB; 16 MB gives an
/// order-of-magnitude headroom for unusual but legitimate cases.
const MAX_CONFIG_FILE_BYTES: u64 = 16 * 1024 * 1024;

/// Read a config file with a hard size cap. Returns the same Err shape
/// as `std::fs::read_to_string` so callers can pattern-match on `io::Error`,
/// but converts an oversize file into `io::Error::new(InvalidData, ...)`
/// rather than blindly OOM-ing on `std::fs::read_to_string`.
fn read_config_capped(path: &Path) -> std::io::Result<String> {
    let file = std::fs::File::open(path)?;
    let metadata = file.metadata()?;
    if metadata.len() > MAX_CONFIG_FILE_BYTES {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!(
                "config file {} is {} bytes, exceeds {}-byte cap",
                path.display(),
                metadata.len(),
                MAX_CONFIG_FILE_BYTES
            ),
        ));
    }
    read_config_capped_from_reader(
        file,
        MAX_CONFIG_FILE_BYTES,
        &format!("config file {}", path.display()),
    )
}

fn read_config_capped_from_reader<R: Read>(
    reader: R,
    max_bytes: u64,
    source: &str,
) -> std::io::Result<String> {
    let mut limited = reader.take(max_bytes.saturating_add(1));
    let mut bytes = Vec::new();
    limited.read_to_end(&mut bytes)?;
    let max_bytes_usize = usize::try_from(max_bytes).unwrap_or(usize::MAX);
    if bytes.len() > max_bytes_usize {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("{source} exceeds {max_bytes}-byte cap"),
        ));
    }
    String::from_utf8(bytes)
        .map_err(|err| std::io::Error::new(std::io::ErrorKind::InvalidData, err))
}

// Type aliases for backward compatibility within this module
type CheckResult = DoctorCheck;
type CheckStatus = DoctorCheckStatus;
type FixApplied = DoctorFixApplied;

// `rch doctor` emits a long human report. A downstream consumer such as
// `head` may close stdout early; treat that as normal Unix pipe behavior
// instead of letting Rust's standard print macros panic.
macro_rules! print {
    ($($arg:tt)*) => {{
        write_stdout(format_args!($($arg)*), false);
    }};
}

macro_rules! println {
    () => {{
        write_stdout(format_args!(""), true);
    }};
    ($($arg:tt)*) => {{
        write_stdout(format_args!($($arg)*), true);
    }};
}

fn write_stdout(args: std::fmt::Arguments<'_>, newline: bool) {
    let stdout = io::stdout();
    let mut out = stdout.lock();
    let result = out.write_fmt(args).and_then(|()| {
        if newline {
            out.write_all(b"\n")
        } else {
            Ok(())
        }
    });

    if let Err(err) = result {
        if err.kind() == io::ErrorKind::BrokenPipe {
            std::process::exit(0);
        }
        let _ = writeln!(
            io::stderr().lock(),
            "rch doctor: failed to write output: {err}"
        );
        std::process::exit(1);
    }
}

// =============================================================================
// Doctor Command Options
// =============================================================================

/// Options for the doctor command.
pub struct DoctorOptions {
    /// Attempt to fix safe issues.
    pub fix: bool,
    /// Show what would be fixed without making changes.
    pub dry_run: bool,
    /// Run reliability-focused diagnostics instead of the general doctor suite.
    pub reliability: bool,
    /// Include schema compatibility checks in reliability mode.
    pub check_schemas: bool,
    /// Detailed output.
    pub verbose: bool,
    /// `--strict`: promote `Degraded` to exit code 2 (treat warnings as failures
    /// for tight CI gates). JSON `data.summary.overall` is unaffected.
    pub strict: bool,
    /// `--lenient`: demote `Failing` to exit code 1 (log only, never block).
    /// JSON `data.summary.overall` is unaffected.
    pub lenient: bool,
    /// `--scope=<list>`: subset of probes to run. Default = `[All]`.
    pub scope: ReliabilityScopeSet,
    /// `--watch`: continuous monitoring mode. The doctor re-runs every
    /// `watch_interval_secs` and emits diff-aware output (transitions
    /// since the prior sweep). Exits cleanly on SIGINT with a final
    /// summary on stderr.
    pub watch: bool,
    /// `--watch-interval=<seconds>`: time between sweeps in `--watch`
    /// mode. Clamped by the CLI handler to 1..=3600. Default: 5.
    pub watch_interval_secs: u64,
    /// `--transitions-only`: in `--watch` mode, suppress unchanged
    /// iterations and emit only when the diagnostic set OR verdict
    /// differs from the prior sweep.
    pub transitions_only: bool,
    /// `--watch-snapshot=PATH`: on `--watch` exit, write a final
    /// summary JSON to PATH (sweep count, verdict transitions count,
    /// final verdict). Useful for tmux/split-window setups.
    pub watch_snapshot: Option<std::path::PathBuf>,
}

// Live schema-version constants are sourced from the central
// `rch_common::schema_versions` registry. The `EXPECTED_*` constants
// below are intentionally pinned literals: the reliability doctor must
// compare live component versions against the versions this doctor knows
// how to consume, not against aliases of those same live constants.
const RELIABILITY_DOCTOR_SCHEMA_VERSION: &str =
    rch_common::schema_version(rch_common::SchemaComponent::DoctorReliability);
const EXPECTED_RELIABILITY_DOCTOR_SCHEMA_VERSION: &str = "1.0.0";
const EXPECTED_STATUS_SCHEMA_VERSION: &str = "1.0.0";
const EXPECTED_REPO_UPDATER_CONTRACT_SCHEMA_VERSION: &str = "1.0.0";
const EXPECTED_PROCESS_TRIAGE_CONTRACT_SCHEMA_VERSION: &str = "1.0.0";

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(rename_all = "snake_case")]
enum ReliabilitySeverity {
    Pass,
    Info,
    Warning,
    Critical,
}

/// Stable lowercase token for a severity (matches the `snake_case` serde
/// spelling). Used to attribute diagnostics in webhook payloads.
fn reliability_severity_token(severity: ReliabilitySeverity) -> &'static str {
    match severity {
        ReliabilitySeverity::Pass => "pass",
        ReliabilitySeverity::Info => "info",
        ReliabilitySeverity::Warning => "warning",
        ReliabilitySeverity::Critical => "critical",
    }
}

/// Tri-state aggregate verdict for the reliability doctor.
///
/// - `Healthy`  — every diagnostic passed (or only Info diagnostics).
/// - `Degraded` — at least one Warning, no Criticals.
/// - `Failing`  — at least one Critical.
///
/// Maps to process exit codes via `ReliabilityVerdict::exit_code`. Operators key
/// alerting policy off this tri-state (sibling t25 watch / t28 webhooks).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReliabilityVerdict {
    Healthy,
    Degraded,
    Failing,
}

impl ReliabilityVerdict {
    /// Default exit-code mapping (without `--strict` / `--lenient`):
    /// Healthy → 0, Degraded → 1, Failing → 2.
    #[must_use]
    pub const fn default_exit_code(self) -> i32 {
        match self {
            Self::Healthy => 0,
            Self::Degraded => 1,
            Self::Failing => 2,
        }
    }

    /// Apply `--strict` / `--lenient` exit-code policy. Returns the mapped
    /// exit code. JSON `data.summary.overall` is unaffected — flags only shift
    /// the process exit.
    #[must_use]
    pub const fn exit_code(self, strict: bool, lenient: bool) -> i32 {
        // Caller must guarantee strict and lenient are not both set.
        if strict {
            // Promote: Degraded becomes Failing-equivalent (exit 2).
            match self {
                Self::Healthy => 0,
                Self::Degraded | Self::Failing => 2,
            }
        } else if lenient {
            // Demote: Failing becomes Degraded-equivalent (exit 1).
            match self {
                Self::Healthy => 0,
                Self::Degraded | Self::Failing => 1,
            }
        } else {
            self.default_exit_code()
        }
    }

    /// Human-readable label, used in banner rendering.
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::Healthy => "Healthy",
            Self::Degraded => "Degraded",
            Self::Failing => "Failing",
        }
    }
}

/// Pure aggregator: max-severity-wins.
///
/// - Any `Critical` → `Failing`.
/// - Else any `Warning` → `Degraded`.
/// - Else (Pass / Info / empty) → `Healthy`.
///
/// Empty input is honestly `Healthy` — caller is responsible for adding a
/// "no probes ran" diagnostic if that's the wrong default for their context.
fn aggregate_verdict(diagnostics: &[ReliabilityDiagnostic]) -> ReliabilityVerdict {
    let mut has_warning = false;
    for diag in diagnostics {
        match diag.severity {
            ReliabilitySeverity::Critical => return ReliabilityVerdict::Failing,
            ReliabilitySeverity::Warning => has_warning = true,
            ReliabilitySeverity::Pass | ReliabilitySeverity::Info => {}
        }
    }
    if has_warning {
        ReliabilityVerdict::Degraded
    } else {
        ReliabilityVerdict::Healthy
    }
}

/// Serialized in snake_case so `--json` consumers see the same tokens as
/// `as_str()`, the webhook payload, and `rch_common::errors::reliability::
/// ReliabilityCategoryKind` (`"topology"`, `"repo_presence"`, ...). Keep
/// the serde rename and `as_str` in lockstep.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(rename_all = "snake_case")]
enum ReliabilityCategory {
    Topology,
    RepoPresence,
    DiskPressure,
    ProcessDebt,
    HelperCompatibility,
    RolloutPosture,
    SchemaCompatibility,
    MirrorOwnership,
}

impl ReliabilityCategory {
    fn as_str(self) -> &'static str {
        match self {
            Self::Topology => "topology",
            Self::RepoPresence => "repo_presence",
            Self::DiskPressure => "disk_pressure",
            Self::ProcessDebt => "process_debt",
            Self::HelperCompatibility => "helper_compatibility",
            Self::RolloutPosture => "rollout_posture",
            Self::SchemaCompatibility => "schema_compatibility",
            Self::MirrorOwnership => "mirror_ownership",
        }
    }
}

/// One scope bucket per reliability probe, plus an `All` sentinel that
/// runs every probe (default behavior).
///
/// Each named variant maps to one of the `reliability_*_diagnostics`
/// probes in `run_reliability_doctor`. Operators triaging a known
/// symptom can pass `--scope=pressure` (or any subset, comma-separated)
/// to skip the irrelevant probes — typical 8-probe sweep takes ~2s
/// against an 8-worker fleet (the ownership fan-out adds one bounded
/// SSH round-trip per worker, run concurrently), scope=topology is
/// still ~50ms.
///
/// Naming uses the operator-facing labels per the bead: `convergence`
/// (not `repo_presence`), `triage` (not `process_debt`), `helpers`
/// (not `helper_compatibility`), `rollout` (not `rollout_posture`),
/// `schema` (not `schema_compatibility`). `ownership` probes per-worker
/// mirror-tree ownership drift (bd-kugfc).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ReliabilityScope {
    All,
    Topology,
    Ownership,
    Convergence,
    Pressure,
    Triage,
    Helpers,
    Rollout,
    Schema,
}

impl ReliabilityScope {
    /// Operator-facing label (matches clap value names).
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::All => "all",
            Self::Topology => "topology",
            Self::Ownership => "ownership",
            Self::Convergence => "convergence",
            Self::Pressure => "pressure",
            Self::Triage => "triage",
            Self::Helpers => "helpers",
            Self::Rollout => "rollout",
            Self::Schema => "schema",
        }
    }
}

impl std::str::FromStr for ReliabilityScope {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let trimmed = s.trim().to_ascii_lowercase();
        match trimmed.as_str() {
            "all" => Ok(Self::All),
            "topology" => Ok(Self::Topology),
            "ownership" => Ok(Self::Ownership),
            "convergence" => Ok(Self::Convergence),
            "pressure" => Ok(Self::Pressure),
            "triage" => Ok(Self::Triage),
            "helpers" => Ok(Self::Helpers),
            "rollout" => Ok(Self::Rollout),
            "schema" => Ok(Self::Schema),
            other => Err(format!(
                "unknown scope value '{other}' (valid: all, topology, ownership, convergence, pressure, triage, helpers, rollout, schema)"
            )),
        }
    }
}

/// Comma-separated set of scopes. Wraps `Vec<ReliabilityScope>` because
/// clap's `value_parser` requires a single type for the field; the parser
/// splits on `,`, deduplicates while preserving first-appearance order,
/// and treats `all` as dominant (collapses any other entries to a
/// 1-element `[All]` set with an INFO trace event noting redundancy).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReliabilityScopeSet(pub Vec<ReliabilityScope>);

impl Default for ReliabilityScopeSet {
    fn default() -> Self {
        Self(vec![ReliabilityScope::All])
    }
}

impl ReliabilityScopeSet {
    /// Returns true if this set contains the `All` sentinel OR the
    /// given scope explicitly. Used to gate each probe.
    #[must_use]
    pub fn matches(&self, scope: ReliabilityScope) -> bool {
        self.0
            .iter()
            .any(|s| matches!(s, ReliabilityScope::All) || *s == scope)
    }

    /// Lowercase string form for `data.scope` JSON.
    #[must_use]
    pub fn as_strings(&self) -> Vec<String> {
        self.0.iter().map(|s| s.as_str().to_string()).collect()
    }

    fn needs_worker_config(&self) -> bool {
        self.matches(ReliabilityScope::Topology) || self.matches(ReliabilityScope::Ownership)
    }

    fn needs_daemon_status(&self) -> bool {
        [
            ReliabilityScope::Topology,
            ReliabilityScope::Pressure,
            ReliabilityScope::Triage,
        ]
        .into_iter()
        .any(|scope| self.matches(scope))
    }

    fn needs_repo_convergence_status(&self) -> bool {
        self.matches(ReliabilityScope::Convergence)
    }

    fn needs_rollout_config(&self) -> bool {
        self.matches(ReliabilityScope::Rollout)
    }

    fn runs_schema_probe(&self, check_schemas: bool) -> bool {
        self.0.contains(&ReliabilityScope::Schema)
            || (check_schemas && self.matches(ReliabilityScope::Schema))
    }

    fn probe_names_to_run(&self, check_schemas: bool) -> Vec<&'static str> {
        let mut names = Vec::new();
        for (scope, name) in [
            (ReliabilityScope::Topology, "topology"),
            (ReliabilityScope::Ownership, "ownership"),
            (ReliabilityScope::Convergence, "convergence"),
            (ReliabilityScope::Pressure, "pressure"),
            (ReliabilityScope::Triage, "triage"),
            (ReliabilityScope::Helpers, "helpers"),
            (ReliabilityScope::Rollout, "rollout"),
        ] {
            if self.matches(scope) {
                names.push(name);
            }
        }
        if self.runs_schema_probe(check_schemas) {
            names.push("schema");
        }
        names
    }
}

impl std::str::FromStr for ReliabilityScopeSet {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let trimmed = s.trim();
        if trimmed.is_empty() {
            return Err("scope list is empty (pass --scope=all or one of: topology, ownership, convergence, pressure, triage, helpers, rollout, schema)".to_string());
        }
        let mut out: Vec<ReliabilityScope> = Vec::new();
        for segment in trimmed.split(',') {
            let scope: ReliabilityScope = segment.parse()?;
            if !out.contains(&scope) {
                out.push(scope);
            }
        }
        // `all` dominates: if mixed with other names, collapse to [All]
        // and log the redundancy at INFO level.
        if out.contains(&ReliabilityScope::All) && out.len() > 1 {
            let redundant: Vec<String> = out
                .iter()
                .filter(|s| **s != ReliabilityScope::All)
                .map(|s| s.as_str().to_string())
                .collect();
            tracing::info!(
                target: "rch::doctor::scope",
                redundant = ?redundant,
                "doctor.scope.all_dominates_redundant",
            );
            out = vec![ReliabilityScope::All];
        }
        Ok(Self(out))
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
enum ReliabilityDoctorMode {
    Check,
    DryRun,
    Fix,
}

#[derive(Debug, Clone, Serialize)]
struct ReliabilityDiagnostic {
    category: ReliabilityCategory,
    check_name: String,
    severity: ReliabilitySeverity,
    message: String,
    /// Canonical `RCH-Rnnn` reason code (per `ReliabilityReasonCode`).
    /// Serializes as the string form (e.g., `"RCH-R001"`).
    code: ReliabilityReasonCode,
    #[serde(skip_serializing_if = "Option::is_none")]
    details: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    worker_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    remediation_command: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    validation_check: Option<String>,
    dry_run_safe: bool,
}

#[derive(Debug, Clone, Serialize)]
struct ReliabilityDoctorSummary {
    total_checks: usize,
    pass: usize,
    info: usize,
    warning: usize,
    critical: usize,
    categories_checked: Vec<ReliabilityCategory>,
    /// Tri-state aggregate verdict (t02). Replaces the prior boolean
    /// `overall_healthy`. Per AGENTS.md "no backwards compatibility":
    /// JSON consumers update to read `summary.overall` (string) instead
    /// of `summary.overall_healthy` (bool).
    overall: ReliabilityVerdict,
}

#[derive(Debug, Clone, Serialize)]
struct ReliabilityRemediationStep {
    order: u32,
    category: ReliabilityCategory,
    /// Canonical reason code of the diagnostic that produced this step. Lets
    /// the `--fix` executor decide whether an idempotent auto-flip applies.
    code: ReliabilityReasonCode,
    description: String,
    command: String,
    validation: String,
    requires_restart: bool,
    dry_run_safe: bool,
    /// True when an idempotent auto-remediation (config flip) exists for this
    /// step, i.e. `--fix` can resolve it without operator intervention.
    auto_fixable: bool,
}

/// A structured, idempotent config flip that `--fix` can apply automatically.
///
/// Limited to self-healing posture toggles: these are the only remediations
/// safe to apply unattended (they enable resilience features, are trivially
/// reversible with `rch config set <key> false`, and never touch fleet/worker
/// state). Everything else stays a manual operator command.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct AutoConfigFlip {
    key: &'static str,
    value: &'static str,
}

/// Map a diagnostic reason code to the idempotent config flip that resolves it,
/// or `None` when remediation requires a manual operator command.
fn auto_config_flip(code: ReliabilityReasonCode) -> Option<AutoConfigFlip> {
    match code {
        ReliabilityReasonCode::HookAutoStartDisabled => Some(AutoConfigFlip {
            key: "self_healing.hook_starts_daemon",
            value: "true",
        }),
        ReliabilityReasonCode::DaemonHookRepairDisabled => Some(AutoConfigFlip {
            key: "self_healing.daemon_installs_hooks",
            value: "true",
        }),
        _ => None,
    }
}

/// Pre-write plan for an auto-fixable step (pure; no I/O). Encodes the
/// (intent × execute) matrix for the auto case before any disk write is
/// attempted — the actual write only happens for [`AutoFlipPlan::Apply`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum AutoFlipPlan {
    /// Config already at the desired value — idempotent no-op.
    AlreadySatisfied,
    /// `--fix --dry-run`: report the intent without mutating anything.
    WouldApply,
    /// `--fix`: perform the write (result becomes `Applied` or `Failed`).
    Apply,
}

/// Classify an auto-fixable step before touching disk. `already` is whether the
/// flip is already satisfied; `preview` is true under `--fix --dry-run`.
fn plan_auto_flip(already: bool, preview: bool) -> AutoFlipPlan {
    if already {
        AutoFlipPlan::AlreadySatisfied
    } else if preview {
        AutoFlipPlan::WouldApply
    } else {
        AutoFlipPlan::Apply
    }
}

/// Is `flip` already satisfied by the loaded config? Used to recognise
/// idempotent no-ops so a `--fix` re-run reports `AlreadySatisfied` instead of
/// rewriting the file.
fn config_flip_satisfied(config: &rch_common::RchConfig, flip: AutoConfigFlip) -> bool {
    match flip.key {
        "self_healing.hook_starts_daemon" => {
            config.self_healing.hook_starts_daemon.to_string() == flip.value
        }
        "self_healing.daemon_installs_hooks" => {
            config.self_healing.daemon_installs_hooks.to_string() == flip.value
        }
        _ => false,
    }
}

/// Outcome of one remediation step under `--fix` / `--fix --dry-run`.
///
/// The (intent × execute) matrix:
/// - `--check` / plain `--dry-run`: executor is a no-op (no outcomes emitted).
/// - `--fix`: each auto step is `Applied` / `AlreadySatisfied` / `Failed`.
/// - `--fix --dry-run`: each auto step is `WouldApply` (nothing mutated).
/// - Manual steps (no safe auto-flip) are always reported `Manual` so the
///   operator learns exactly what `--fix` could not do.
#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
enum RemediationOutcomeStatus {
    Applied,
    AlreadySatisfied,
    WouldApply,
    Failed,
    Manual,
}

impl RemediationOutcomeStatus {
    fn label(self) -> &'static str {
        match self {
            RemediationOutcomeStatus::Applied => "applied",
            RemediationOutcomeStatus::AlreadySatisfied => "already-satisfied",
            RemediationOutcomeStatus::WouldApply => "would-apply",
            RemediationOutcomeStatus::Failed => "failed",
            RemediationOutcomeStatus::Manual => "manual",
        }
    }
}

#[derive(Debug, Clone, Serialize)]
struct ReliabilityRemediationOutcome {
    order: u32,
    code: ReliabilityReasonCode,
    description: String,
    /// The command that was applied (auto steps) or that the operator must run
    /// (manual steps).
    command: String,
    status: RemediationOutcomeStatus,
    #[serde(skip_serializing_if = "Option::is_none")]
    detail: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
struct ReliabilityDoctorResponse {
    schema_version: String,
    mode: ReliabilityDoctorMode,
    /// Scope set the operator requested (always present, single-element
    /// `["all"]` by default). Agents inspect this field to confirm their
    /// `--scope` arg was honored.
    scope: Vec<String>,
    /// True when ANY probe could not reach the daemon. Operators see this
    /// top-level marker instead of grepping diagnostic messages for the
    /// daemon-down case. (t05)
    daemon_unreachable: bool,
    /// Per-probe failures that contributed to `daemon_unreachable=true`.
    /// Empty when `daemon_unreachable=false`. Forensic detail so log
    /// consumers can attribute the unreachability to a specific probe
    /// (e.g., "process_debt: daemon status unavailable"). (t05)
    daemon_unreachable_reasons: Vec<String>,
    diagnostics: Vec<ReliabilityDiagnostic>,
    summary: ReliabilityDoctorSummary,
    remediation_plan: Vec<ReliabilityRemediationStep>,
    /// True when the operator passed `--fix`, even if `--dry-run` downgraded
    /// `mode` to `DryRun`. Distinguishes a "preview of fix" (`--fix --dry-run`)
    /// from a plain read-only dry run (`--dry-run`). (bead 2s99h.12, issue #2)
    fix_requested: bool,
    /// Per-step results of the `--fix` executor. Empty unless `--fix` was
    /// requested; populated by `apply_reliability_remediations`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    remediation_outcomes: Vec<ReliabilityRemediationOutcome>,
}

impl ReliabilityDiagnostic {
    fn new(
        category: ReliabilityCategory,
        check_name: impl Into<String>,
        severity: ReliabilitySeverity,
        message: impl Into<String>,
        code: ReliabilityReasonCode,
    ) -> Self {
        Self {
            category,
            check_name: check_name.into(),
            severity,
            message: message.into(),
            code,
            details: None,
            worker_id: None,
            remediation_command: None,
            validation_check: None,
            dry_run_safe: true,
        }
    }

    fn with_details(mut self, details: impl Into<String>) -> Self {
        self.details = Some(details.into());
        self
    }

    fn with_worker(mut self, worker_id: impl Into<String>) -> Self {
        self.worker_id = Some(worker_id.into());
        self
    }

    fn with_remediation(
        mut self,
        command: impl Into<String>,
        validation_check: impl Into<String>,
    ) -> Self {
        self.remediation_command = Some(command.into());
        self.validation_check = Some(validation_check.into());
        self
    }
}

// =============================================================================
// Main Doctor Function
// =============================================================================

pub(crate) fn local_build_check(
    observation: &crate::local_builds::LocalBuildObservation,
) -> CheckResult {
    let mut details: Vec<String> = observation
        .builds
        .iter()
        .map(|build| {
            format!(
                "pid={} comm={} exe={}",
                build.pid,
                build.comm,
                build
                    .exe
                    .as_ref()
                    .map_or_else(|| "unknown".to_string(), |path| path.display().to_string())
            )
        })
        .collect();
    if let Some(error) = &observation.scan_error {
        details.push(format!("Scan: {error}"));
    }
    if let Some(error) = &observation.state_error {
        details.push(format!("Alarm state: {error}"));
    }
    let warning = observation.warning();
    CheckResult {
        category: "local_builds".to_string(),
        name: "dispatcher_local_builds".to_string(),
        status: if warning.is_some() { CheckStatus::Warning } else { CheckStatus::Pass },
        message: warning.unwrap_or_else(|| "No unmanaged local builds on this dispatcher".to_string()),
        details: (!details.is_empty()).then(|| details.join("; ")),
        suggestion: (!observation.builds.is_empty()).then(||
            "Run rch shim status; check PATH order and absolute-path toolchain Cargo invocations".to_string()),
        fixable: false,
        fix_applied: false,
        fix_message: None,
    }
}

fn dispatcher_shim_check(role: rch_common::BoxRole, problems: Vec<String>) -> CheckResult {
    let required = role == rch_common::BoxRole::Dispatcher;
    let unhealthy = required && !problems.is_empty();
    CheckResult {
        category: "configuration".to_string(),
        name: "dispatcher_shim".to_string(),
        status: if unhealthy { CheckStatus::Warning } else { CheckStatus::Pass },
        message: if unhealthy {
            "role=dispatcher: Cargo interception needs repair".to_string()
        } else if required {
            "role=dispatcher: Cargo shims are current and effective on PATH".to_string()
        } else {
            format!("role={}: dispatcher shims are not required", role.as_str())
        },
        details: unhealthy.then(|| problems.join("; ")),
        suggestion: unhealthy.then(||
            "Run rch shim install and put ~/.rch/shims first on PATH; restart existing agent shells".to_string()),
        fixable: false,
        fix_applied: false,
        fix_message: None,
    }
}

fn reliability_local_build_diagnostics(
    observation: Option<&crate::local_builds::LocalBuildObservation>,
) -> Vec<ReliabilityDiagnostic> {
    let Some(observation) = observation else {
        return Vec::new();
    };
    let check = local_build_check(observation);
    let code = if !observation.builds.is_empty() {
        ReliabilityReasonCode::LocalBuildsDetected
    } else if observation.scan_error.is_some() {
        ReliabilityReasonCode::LocalBuildScanUnavailable
    } else if observation.state_error.is_some() {
        ReliabilityReasonCode::LocalBuildAlarmStateUnavailable
    } else {
        ReliabilityReasonCode::LocalBuildsAbsent
    };
    let mut diagnostic = ReliabilityDiagnostic::new(
        ReliabilityCategory::ProcessDebt,
        check.name,
        if check.status == CheckStatus::Warning {
            ReliabilitySeverity::Warning
        } else {
            ReliabilitySeverity::Pass
        },
        check.message,
        code,
    );
    diagnostic.details = check.details;
    vec![diagnostic]
}

/// Run all diagnostic checks.
pub async fn run_doctor(ctx: &OutputContext, options: DoctorOptions) -> Result<()> {
    if options.reliability {
        return run_reliability_doctor(ctx, &options).await;
    }

    let style = ctx.theme();
    let mut checks: Vec<CheckResult> = Vec::new();
    let mut fixes_applied: Vec<FixApplied> = Vec::new();

    if !ctx.is_json() {
        println!("{}", style.format_header("RCH Diagnostic Report"));
        println!();
    }

    // Local dispatcher warnings do not depend on daemon or worker availability.
    if let Ok(config) = crate::config::load_config() {
        let problems = if config.general.role == rch_common::BoxRole::Dispatcher {
            crate::commands::shim::dispatcher_shim_problems()
                .unwrap_or_else(|error| vec![format!("Cannot inspect shims: {error:#}")])
        } else {
            Vec::new()
        };
        let check = dispatcher_shim_check(config.general.role, problems);
        print_check_result(&check, ctx);
        checks.push(check);
        if let Some(observation) = crate::local_builds::observe(config.general.role) {
            let check = local_build_check(&observation);
            print_check_result(&check, ctx);
            checks.push(check);
        }
    }

    // Run all checks
    check_prerequisites(&mut checks, ctx, &options);
    check_configuration(&mut checks, ctx, &options);
    checks.extend(rustc_wrapper_checks());
    check_ssh_keys(&mut checks, ctx, &options, &mut fixes_applied);
    check_hooks(&mut checks, ctx, &options, &mut fixes_applied);
    check_daemon(&mut checks, ctx, &options, &mut fixes_applied);
    check_cancellation_health(&mut checks, ctx).await;
    check_workers(&mut checks, ctx, &options).await;
    check_telemetry_database(&mut checks, ctx, &options);

    // Calculate summary
    let fixed = checks.iter().filter(|c| c.fix_applied).count();
    let would_fix = if options.fix && options.dry_run {
        checks
            .iter()
            .filter(|c| matches!(c.fix_message.as_deref(), Some(msg) if msg.starts_with("Would ")))
            .count()
    } else {
        0
    };
    let summary = DoctorSummary {
        total: checks.len(),
        passed: checks
            .iter()
            .filter(|c| c.status == CheckStatus::Pass)
            .count(),
        warnings: checks
            .iter()
            .filter(|c| c.status == CheckStatus::Warning)
            .count(),
        failed: checks
            .iter()
            .filter(|c| c.status == CheckStatus::Fail)
            .count(),
        fixed,
        would_fix,
    };

    // Output results
    if ctx.is_json() {
        let _ = ctx.json(&ApiResponse::ok(
            "doctor",
            DoctorResponse {
                // t05: same schema-version on legacy doctor as on
                // reliability mode; sourced from the central registry.
                schema_version: rch_common::schema_version(
                    rch_common::SchemaComponent::DoctorReliability,
                )
                .to_string(),
                checks,
                summary,
                fixes_applied,
            },
        ));
    } else {
        // Print summary
        println!();
        println!("{}", style.format_header("Summary"));
        println!();
        println!(
            "  {} {} passed",
            StatusIndicator::Success.display(style),
            style.highlight(&summary.passed.to_string())
        );
        if summary.warnings > 0 {
            println!(
                "  {} {} warnings",
                StatusIndicator::Warning.display(style),
                style.highlight(&summary.warnings.to_string())
            );
        }
        if summary.failed > 0 {
            println!(
                "  {} {} failed",
                StatusIndicator::Error.display(style),
                style.highlight(&summary.failed.to_string())
            );
        }
        if summary.fixed > 0 {
            println!(
                "  {} {} fixed",
                StatusIndicator::Success.display(style),
                style.highlight(&summary.fixed.to_string())
            );
        }
        if summary.would_fix > 0 {
            println!(
                "  {} {} would fix",
                StatusIndicator::Pending.display(style),
                style.highlight(&summary.would_fix.to_string())
            );
        }

        // Show fixes applied
        if !fixes_applied.is_empty() {
            println!();
            println!("{}", style.format_header("Fixes Applied"));
            for fix in &fixes_applied {
                if fix.success {
                    println!(
                        "  {} {}: {}",
                        StatusIndicator::Success.display(style),
                        style.highlight(&fix.check_name),
                        style.muted(&fix.action)
                    );
                } else {
                    println!(
                        "  {} {}: {} - {}",
                        StatusIndicator::Error.display(style),
                        style.highlight(&fix.check_name),
                        style.muted(&fix.action),
                        style.error(fix.error.as_deref().unwrap_or("unknown error"))
                    );
                }
            }
        }

        // Final status
        println!();
        if summary.failed > 0 {
            println!(
                "{}",
                style.format_error("Some checks failed. Run with --fix to attempt auto-repair.")
            );
        } else if summary.warnings > 0 {
            println!(
                "{}",
                style.format_warning("System is operational with warnings.")
            );
        } else {
            println!("{}", style.format_success("All checks passed!"));
        }
    }

    Ok(())
}

/// The report has already been rendered; the CLI must preserve this status
/// without printing a second error response, after flushing telemetry.
#[derive(Debug, thiserror::Error)]
#[error("command finished with exit code {0} (result already reported)")]
pub(crate) struct DoctorExit(pub i32);

async fn run_reliability_doctor(ctx: &OutputContext, options: &DoctorOptions) -> Result<()> {
    // Watch mode short-circuits the single-shot path: it loops, diffs,
    // and returns only after SIGINT or a signal-handler error.
    if options.watch {
        return run_reliability_watch_loop(ctx, options).await;
    }
    let mut response = collect_reliability_response_once(options).await;

    // `--fix` (and `--fix --dry-run`) execution. No-op for Check / plain DryRun.
    apply_reliability_remediations(&mut response);

    if ctx.is_json() {
        // t05: command tag is a single dotted token ("doctor.reliability")
        // for agent-friendly jq-matching. Per AGENTS.md no-back-compat:
        // consumers update to the dotted form directly.
        let _ = ctx.json(&ApiResponse::ok("doctor.reliability", &response));
    } else {
        print_reliability_doctor_response(ctx, &response);
    }

    // Verdict → exit-code mapping (t02). Honors --strict / --lenient. Logged
    // for forensics so log consumers can correlate exit codes with verdicts.
    let exit_code = response
        .summary
        .overall
        .exit_code(options.strict, options.lenient);
    let metric_scope = match options.scope.0.as_slice() {
        [scope] => scope.as_str(),
        // Count one verdict for a multi-scope report without pretending that
        // its aggregate verdict belongs to each individual scope.
        _ => "other",
    };
    tracing::info!(
        target: "rch::doctor::verdict",
        verdict = response.summary.overall.label(),
        scope = metric_scope,
        daemon_unreachable = response.daemon_unreachable,
        exit_code,
        strict = options.strict,
        lenient = options.lenient,
        pass = response.summary.pass,
        info = response.summary.info,
        warning = response.summary.warning,
        critical = response.summary.critical,
        "doctor.verdict",
    );
    if exit_code == 0 {
        Ok(())
    } else {
        // Return the already-rendered status so the CLI can flush its exporter
        // before exiting, without replacing this report with an error envelope.
        let _ = std::io::Write::flush(&mut std::io::stdout());
        let _ = std::io::Write::flush(&mut std::io::stderr());
        Err(DoctorExit(exit_code).into())
    }
}

/// Per-probe timeout for the I/O collection phase (RCH bd-62u24.8). A
/// hung daemon RPC or a stuck `which()` subprocess can't sink the whole
/// doctor: each probe is bounded by this timeout and falls back to a
/// `None`/empty result that downstream diagnostic builders interpret as
/// "unavailable" (Warning verdict).
const PROBE_TIMEOUT: Duration = Duration::from_secs(10);

/// Measure each async probe in its own task, before results are joined.
/// Only completed observations are exported here; panic/cancellation remain
/// forensic events without fabricated zero-duration histogram samples.
async fn timed_async_probe<T, E>(
    probe: &'static str,
    future: impl std::future::Future<Output = Result<T, E>>,
) -> Result<Result<T, E>, tokio::time::error::Elapsed> {
    let started = Instant::now();
    let result = tokio::time::timeout(PROBE_TIMEOUT, future).await;
    let outcome = match &result {
        Ok(Ok(_)) => "completed",
        Ok(Err(_)) => "inner_error",
        Err(_) => "timeout",
    };
    tracing::info!(
        target: "rch::doctor::probe_duration",
        probe,
        result = outcome,
        duration_seconds = started.elapsed().as_secs_f64(),
        "doctor.probe.end",
    );
    result
}

/// Single-shot collection of a reliability doctor response. Extracted
/// from `run_reliability_doctor` so both the single-shot path and the
/// `--watch` loop (t25) can re-use the exact same probe gating, scope
/// honoring, and verdict aggregation. Pure async data collection — no
/// stdout/stderr writes, no `process::exit` — callers decide how to
/// surface the result.
///
/// # Parallelism (bd-62u24.8)
///
/// The three I/O-bearing data sources run **concurrently** via
/// `tokio::spawn` + (for sync work) `tokio::task::spawn_blocking`:
///
///   1. `query_daemon_full_status()` — daemon RPC for fleet topology /
///      disk pressure / process debt data.
///   2. `query_repo_convergence_status()` — daemon RPC for repo
///      convergence status.
///   3. `reliability_helper_compatibility_diagnostics()` — sync work
///      that spawns `which()` + version-probe subprocesses (4 helpers ×
///      2 subprocesses each = 8 forks). Moved to the blocking thread
///      pool so its subprocess waits don't block the runtime's worker
///      threads.
///
/// Each spawned task is bounded by `PROBE_TIMEOUT` and lives behind a
/// `JoinHandle` so a panic in one probe is caught by `JoinError` and
/// surfaces as a downgraded "unavailable" diagnostic for that scope —
/// the other probes still produce their results. This satisfies the
/// per-probe panic-isolation acceptance criterion.
///
/// The order of diagnostics in the final response is independent of the
/// parallelism order: the `scope.matches(...)` branches at the bottom
/// iterate in a fixed (Topology, Ownership, Convergence, Pressure,
/// Triage, Helpers, Rollout, Schema) sequence over the joined results,
/// so output is byte-stable across runs even if probes finish in
/// different orders.
async fn collect_reliability_response_once(options: &DoctorOptions) -> ReliabilityDoctorResponse {
    // Probe gating per --scope (t01). Each branch runs only when the
    // operator-supplied scope set matches. Default `[All]` runs everything.
    let scope = &options.scope;

    // Phase 1 — kick off the three I/O probes concurrently. Each one is
    // spawn-isolated for panic safety, timeout-bounded for hung-RPC
    // safety, and conditionally skipped per scope gating (so a scoped
    // run doesn't pay the I/O cost it can't consume).
    let join_start = Instant::now();
    let daemon_handle = scope.needs_daemon_status().then(|| {
        tokio::spawn(
            async move { timed_async_probe("daemon_status", query_daemon_full_status()).await },
        )
    });
    let convergence_handle = scope.needs_repo_convergence_status().then(|| {
        tokio::spawn(async move {
            timed_async_probe("repo_convergence", query_repo_convergence_status()).await
        })
    });
    // Helper-compat probe is sync subprocess work. `spawn_blocking` puts
    // it on tokio's blocking pool so it runs in parallel with the async
    // daemon RPCs above without starving runtime worker threads.
    let helpers_handle = scope
        .matches(ReliabilityScope::Helpers)
        .then(|| tokio::task::spawn_blocking(reliability_helper_compatibility_diagnostics));

    // Phase 2 — sync file I/O. These are microseconds each and can run
    // on the current thread while the spawned probes are in flight.
    let config_result = if scope.needs_rollout_config()
        || scope.matches(ReliabilityScope::Ownership)
        || scope.matches(ReliabilityScope::Triage)
    {
        Some(crate::config::load_config())
    } else {
        None
    };
    tracing::debug!(
        target: "rch::doctor::config_loads",
        loaded = matches!(config_result.as_ref(), Some(Ok(_))),
        skipped = !(scope.needs_rollout_config() || scope.matches(ReliabilityScope::Ownership)
            || scope.matches(ReliabilityScope::Triage)),
        "doctor.config.load",
    );
    let local_observation = if scope.matches(ReliabilityScope::Triage) {
        config_result
            .as_ref()
            .and_then(|result| result.as_ref().ok())
            .and_then(|config| crate::local_builds::observe(config.general.role))
    } else {
        None
    };

    // bd-kugfc: resolve the canonical mirror root from config (falling
    // back to the compiled-in default only when config loads cleanly but
    // leaves it unset). A config-load failure is surfaced by the
    // ownership diagnostics builder as an unprobeable state rather than
    // silently probing a possibly-wrong default tree.
    let ownership_canonical_root: Result<PathBuf, String> =
        if scope.matches(ReliabilityScope::Ownership) {
            match config_result.as_ref() {
                Some(Ok(config)) => Ok(config
                    .path_topology
                    .to_policy()
                    .canonical_root()
                    .to_path_buf()),
                Some(Err(error)) => Err(error.to_string()),
                None => Err("config load skipped unexpectedly".to_string()),
            }
        } else {
            Err("ownership scope not selected".to_string())
        };

    let (workers, worker_config_error) = if scope.needs_worker_config() {
        match load_workers_from_config() {
            Ok(workers) => (Some(workers), None),
            Err(err) => (None, Some(err.to_string())),
        }
    } else {
        (None, None)
    };
    // Phase 2.5 — bd-kugfc: the ownership probe needs the loaded worker
    // list, so it spawns after Phase 2 and joins with everything else in
    // Phase 3. Each worker gets one bounded SSH round-trip, run
    // concurrently; per-worker results are placed back by index so the
    // diagnostic order stays byte-stable regardless of completion order.
    let ownership_handle: Option<
        tokio::task::JoinHandle<Vec<crate::hook::ssh::MirrorOwnershipProbe>>,
    > = if scope.matches(ReliabilityScope::Ownership) && ownership_canonical_root.is_ok() {
        workers.as_ref().filter(|ws| !ws.is_empty()).map(|ws| {
            let workers = ws.clone();
            let workers_len = workers.len();
            let root = ownership_canonical_root
                .as_ref()
                .expect("checked is_ok above")
                .clone();
            tokio::spawn(async move {
                let mut set = tokio::task::JoinSet::new();
                for (idx, worker) in workers.into_iter().enumerate() {
                    let root = root.clone();
                    set.spawn(async move {
                        let probe =
                            crate::hook::ssh::probe_worker_mirror_ownership(&worker, &root).await;
                        (idx, probe)
                    });
                }
                // Slots start honestly unprobeable; a panicked task leaves
                // its slot in that state instead of masquerading as healthy.
                let mut results = vec![
                    crate::hook::ssh::MirrorOwnershipProbe::Unprobeable(
                        "probe task did not report".to_string(),
                    );
                    workers_len
                ];
                while let Some(joined) = set.join_next().await {
                    if let Ok((idx, probe)) = joined
                        && let Some(slot) = results.get_mut(idx)
                    {
                        *slot = probe;
                    }
                }
                results
            })
        })
    } else {
        None
    };

    // Phase 3 — join the spawned probes. `join_isolated_probe` collapses
    // the three failure modes (timeout, panic, RPC error) into the
    // single `None` outcome that downstream diagnostic builders
    // already handle by emitting an "unavailable" Warning diagnostic.
    let (daemon_status, daemon_outcome) =
        join_isolated_async_probe("daemon_status", daemon_handle).await;
    let (convergence_status, convergence_outcome) =
        join_isolated_async_probe("repo_convergence", convergence_handle).await;
    let (helper_diags_override, helpers_outcome) =
        join_isolated_blocking_probe("helper_compatibility", helpers_handle).await;
    let (ownership_results, ownership_outcome) = join_ownership_probe(ownership_handle).await;
    let join_elapsed_ms = join_start.elapsed().as_millis() as u64;
    tracing::info!(
        target: "rch::doctor::probes",
        daemon = %daemon_outcome.label(),
        repo_convergence = %convergence_outcome.label(),
        helpers = %helpers_outcome.label(),
        join_elapsed_ms,
        "doctor.probes.joined",
    );

    let probes_to_run = scope.probe_names_to_run(options.check_schemas);
    tracing::info!(
        target: "rch::doctor::scope",
        scope = ?scope.as_strings(),
        probes_to_run = ?probes_to_run,
        probes_count = probes_to_run.len(),
        "doctor.scope.applied",
    );
    let mut diagnostics = Vec::new();
    if scope.matches(ReliabilityScope::Topology) {
        diagnostics.extend(reliability_topology_diagnostics(
            workers.as_deref(),
            daemon_status.as_ref(),
            worker_config_error.clone(),
        ));
    }
    if scope.matches(ReliabilityScope::Ownership) {
        diagnostics.extend(reliability_mirror_ownership_diagnostics(
            workers.as_deref(),
            worker_config_error,
            ownership_results.as_ref(),
            ownership_outcome,
            ownership_canonical_root.as_ref().err(),
        ));
    }
    if scope.matches(ReliabilityScope::Convergence) {
        diagnostics.extend(reliability_repo_diagnostics(convergence_status.as_ref()));
    }
    if scope.matches(ReliabilityScope::Pressure) {
        diagnostics.extend(reliability_disk_pressure_diagnostics(
            daemon_status.as_ref(),
        ));
    }
    if scope.matches(ReliabilityScope::Triage) {
        diagnostics.extend(reliability_local_build_diagnostics(
            local_observation.as_ref(),
        ));
        diagnostics.extend(reliability_process_debt_diagnostics(daemon_status.as_ref()));
    }
    if scope.matches(ReliabilityScope::Helpers) {
        diagnostics.extend(helper_diagnostics_from_probe_result(
            helper_diags_override,
            helpers_outcome,
        ));
    }
    if scope.matches(ReliabilityScope::Rollout) {
        let config_load: Result<&rch_common::RchConfig, String> = match config_result.as_ref() {
            Some(Ok(config)) => Ok(config),
            Some(Err(error)) => Err(error.to_string()),
            None => Err("config load skipped unexpectedly".to_string()),
        };
        diagnostics.extend(reliability_rollout_posture_diagnostics(
            config_load.as_ref().map(|c| *c).map_err(|e| e.as_str()),
        ));
        // Hook/socket drift diagnostics (bd-...-3.3): does the rch PreToolUse
        // hook exist, and does the configured socket match the canonical
        // daemon socket? Read-only probe of the real settings file.
        let config_socket = config_load
            .as_ref()
            .ok()
            .map(|cfg| cfg.general.socket_path.as_str());
        diagnostics.extend(reliability_hook_consistency_diagnostics(
            rch_common::hooks::installed_rch_hook_command().as_deref(),
            config_socket,
            &rch_common::default_socket_path(),
        ));
    }
    if scope.runs_schema_probe(options.check_schemas) {
        diagnostics.extend(reliability_schema_compatibility_diagnostics());
    }

    let mode = if options.dry_run {
        ReliabilityDoctorMode::DryRun
    } else if options.fix {
        ReliabilityDoctorMode::Fix
    } else {
        ReliabilityDoctorMode::Check
    };
    let mut response = build_reliability_doctor_response(mode, scope, diagnostics);
    // `--fix --dry-run` downgrades `mode` to DryRun; `fix_requested` preserves
    // the operator's intent so the executor previews instead of staying inert,
    // and JSON consumers can tell a fix-preview from a plain dry run.
    response.fix_requested = options.fix;
    response
}

// =============================================================================
// Probe Parallelism Plumbing (bd-62u24.8)
// =============================================================================

/// Outcome label for the `doctor.probes.joined` tracing event. One value
/// per spawned probe per doctor invocation; operators correlate these
/// with verdict shifts during deployment.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ProbeOutcome {
    /// Probe completed; result is populated.
    Ok,
    /// Probe was skipped (its scope wasn't selected).
    Skipped,
    /// Probe completed but its RPC/inner work returned an Err.
    InnerError,
    /// Probe exceeded `PROBE_TIMEOUT`.
    Timeout,
    /// Probe panicked. Surfaced as `None` for the result; tracing captures the payload.
    Panicked,
    /// Probe task was cancelled (e.g., runtime shutdown).
    Cancelled,
}

impl ProbeOutcome {
    fn label(self) -> &'static str {
        match self {
            Self::Ok => "ok",
            Self::Skipped => "skipped",
            Self::InnerError => "inner_error",
            Self::Timeout => "timeout",
            Self::Panicked => "panicked",
            Self::Cancelled => "cancelled",
        }
    }
}

/// Join a spawned async probe with panic isolation + timeout reporting.
/// Returns `(Option<T>, outcome)` — `None` on any failure mode so
/// callers can fall through to "unavailable" diagnostic synthesis
/// without needing to distinguish timeout/panic/error in the response
/// schema. The outcome is reported separately so the
/// `doctor.probes.joined` tracing event carries the forensic detail.
///
/// `handle` is `Option` so a scoped-out probe (its scope wasn't
/// selected) maps cleanly to `(None, Skipped)` without spinning up a
/// task whose result we'd ignore.
async fn join_isolated_async_probe<T, E>(
    probe_name: &'static str,
    handle: Option<tokio::task::JoinHandle<Result<Result<T, E>, tokio::time::error::Elapsed>>>,
) -> (Option<T>, ProbeOutcome)
where
    T: Send + 'static,
    E: std::fmt::Display + Send + 'static,
{
    let Some(handle) = handle else {
        return (None, ProbeOutcome::Skipped);
    };
    match handle.await {
        Ok(Ok(Ok(value))) => (Some(value), ProbeOutcome::Ok),
        Ok(Ok(Err(err))) => {
            tracing::debug!(
                target: "rch::doctor::probes",
                probe = probe_name,
                error = %err,
                "doctor.probe.inner_error",
            );
            (None, ProbeOutcome::InnerError)
        }
        Ok(Err(_elapsed)) => {
            tracing::warn!(
                target: "rch::doctor::probes",
                probe = probe_name,
                timeout_secs = PROBE_TIMEOUT.as_secs(),
                "doctor.probe.timeout",
            );
            (None, ProbeOutcome::Timeout)
        }
        Err(join_err) if join_err.is_panic() => {
            // `into_panic()` returns Box<dyn Any + Send>. The payload is
            // typically a String (panic! formatted) or &'static str.
            // Both downcasts attempted; otherwise emit a placeholder.
            let payload = join_err.into_panic();
            let panic_msg = payload
                .downcast::<String>()
                .map(|b| *b)
                .or_else(|p| p.downcast::<&'static str>().map(|b| (*b).to_string()))
                .unwrap_or_else(|_| "<non-string panic payload>".to_string());
            tracing::error!(
                target: "rch::doctor::probes",
                probe = probe_name,
                panic = %panic_msg,
                "doctor.probe.panicked",
            );
            (None, ProbeOutcome::Panicked)
        }
        Err(join_err) => {
            tracing::warn!(
                target: "rch::doctor::probes",
                probe = probe_name,
                error = %join_err,
                "doctor.probe.cancelled",
            );
            (None, ProbeOutcome::Cancelled)
        }
    }
}

/// Dedicated joiner for the mirror-ownership probe: unlike the generic async
/// probe helper, the ownership fan-out has no tokio-level timeout layer (each
/// SSH round-trip is individually bounded inside `probe_worker_mirror_ownership`),
/// so the JoinHandle resolves straight to the collected per-worker results.
async fn join_ownership_probe(
    handle: Option<tokio::task::JoinHandle<Vec<crate::hook::ssh::MirrorOwnershipProbe>>>,
) -> (
    Option<Vec<crate::hook::ssh::MirrorOwnershipProbe>>,
    ProbeOutcome,
) {
    let Some(handle) = handle else {
        return (None, ProbeOutcome::Skipped);
    };
    match handle.await {
        Ok(value) => (Some(value), ProbeOutcome::Ok),
        Err(join_err) if join_err.is_panic() => {
            let payload = join_err.into_panic();
            let panic_msg = payload
                .downcast::<String>()
                .map(|b| *b)
                .or_else(|p| p.downcast::<&'static str>().map(|b| (*b).to_string()))
                .unwrap_or_else(|_| "<non-string panic payload>".to_string());
            tracing::error!(
                target: "rch::doctor::probes",
                probe = "mirror_ownership",
                panic = %panic_msg,
                "doctor.probe.panicked",
            );
            (None, ProbeOutcome::Panicked)
        }
        Err(join_err) => {
            tracing::warn!(
                target: "rch::doctor::probes",
                probe = "mirror_ownership",
                error = %join_err,
                "doctor.probe.cancelled",
            );
            (None, ProbeOutcome::Cancelled)
        }
    }
}

/// Same as `join_isolated_async_probe` but for `spawn_blocking` tasks
/// (sync work moved to the blocking pool). The inner future is already
/// resolved when the JoinHandle resolves — there's no per-task timeout
/// at the tokio level for spawn_blocking tasks, so we apply one via
/// `tokio::time::timeout` around the `await`. Sync blocking work that
/// outruns `PROBE_TIMEOUT` will keep running on the blocking pool until
/// it finishes (we can't preempt blocking work) but the doctor still
/// returns promptly and surfaces the timeout outcome.
async fn join_isolated_blocking_probe<T>(
    probe_name: &'static str,
    handle: Option<tokio::task::JoinHandle<T>>,
) -> (Option<T>, ProbeOutcome)
where
    T: Send + 'static,
{
    join_isolated_blocking_probe_with_timeout(probe_name, handle, PROBE_TIMEOUT).await
}

async fn join_isolated_blocking_probe_with_timeout<T>(
    probe_name: &'static str,
    handle: Option<tokio::task::JoinHandle<T>>,
    timeout: Duration,
) -> (Option<T>, ProbeOutcome)
where
    T: Send + 'static,
{
    let Some(handle) = handle else {
        return (None, ProbeOutcome::Skipped);
    };
    match tokio::time::timeout(timeout, handle).await {
        Ok(Ok(value)) => (Some(value), ProbeOutcome::Ok),
        Ok(Err(join_err)) if join_err.is_panic() => {
            let payload = join_err.into_panic();
            let panic_msg = payload
                .downcast::<String>()
                .map(|b| *b)
                .or_else(|p| p.downcast::<&'static str>().map(|b| (*b).to_string()))
                .unwrap_or_else(|_| "<non-string panic payload>".to_string());
            tracing::error!(
                target: "rch::doctor::probes",
                probe = probe_name,
                panic = %panic_msg,
                "doctor.probe.panicked",
            );
            (None, ProbeOutcome::Panicked)
        }
        Ok(Err(join_err)) => {
            tracing::warn!(
                target: "rch::doctor::probes",
                probe = probe_name,
                error = %join_err,
                "doctor.probe.cancelled",
            );
            (None, ProbeOutcome::Cancelled)
        }
        Err(_elapsed) => {
            tracing::warn!(
                target: "rch::doctor::probes",
                probe = probe_name,
                timeout_secs = timeout.as_secs(),
                "doctor.probe.timeout",
            );
            (None, ProbeOutcome::Timeout)
        }
    }
}

async fn query_repo_convergence_status() -> Result<RepoConvergenceStatusFromApi> {
    let response = send_daemon_command("GET /repo-convergence/status\n").await?;
    let json = extract_json_body(&response)
        .ok_or_else(|| anyhow::anyhow!("Invalid response format from daemon"))?;
    serde_json::from_str(json).map_err(Into::into)
}

// =============================================================================
// `--watch` Continuous Monitoring (t25)
// =============================================================================

/// Stable identity for a single diagnostic across sweeps. Two diagnostics
/// from different sweeps refer to the "same issue" iff their keys match.
/// `worker_id` distinguishes per-worker diagnostics (the same `check_name`
/// is emitted once per worker for topology rows).
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct DiagnosticKey {
    category: ReliabilityCategory,
    check_name: String,
    worker_id: Option<String>,
}

impl DiagnosticKey {
    fn from_diagnostic(d: &ReliabilityDiagnostic) -> Self {
        Self {
            category: d.category,
            check_name: d.check_name.clone(),
            worker_id: d.worker_id.clone(),
        }
    }

    /// Human-rendered form used in diff output banners.
    fn render(&self) -> String {
        match &self.worker_id {
            Some(w) => format!(
                "{}/{}[worker={}]",
                self.category.as_str(),
                self.check_name,
                w
            ),
            None => format!("{}/{}", self.category.as_str(), self.check_name),
        }
    }
}

/// The subset of a diagnostic that determines whether a state has
/// changed across sweeps. We deliberately exclude `details` from the
/// fingerprint because some details rotate every sweep (e.g.,
/// `uptime_secs=12345`) and would generate noise for `--transitions-only`.
#[derive(Debug, Clone, PartialEq, Eq)]
struct DiagnosticFingerprint {
    severity: ReliabilitySeverity,
    code: ReliabilityReasonCode,
    message: String,
}

impl DiagnosticFingerprint {
    fn from_diagnostic(d: &ReliabilityDiagnostic) -> Self {
        Self {
            severity: d.severity,
            code: d.code,
            message: d.message.clone(),
        }
    }
}

/// Cross-sweep diff result. `added` are diagnostics present this sweep
/// but absent last sweep; `cleared` are the inverse; `changed` are
/// diagnostics whose fingerprint shifted (severity/code/message).
#[derive(Debug, Default)]
struct DiagnosticDiff {
    added: Vec<(DiagnosticKey, DiagnosticFingerprint)>,
    cleared: Vec<(DiagnosticKey, DiagnosticFingerprint)>,
    changed: Vec<(DiagnosticKey, DiagnosticFingerprint, DiagnosticFingerprint)>,
}

impl DiagnosticDiff {
    fn has_changes(&self) -> bool {
        !self.added.is_empty() || !self.cleared.is_empty() || !self.changed.is_empty()
    }

    fn total_transitions(&self) -> usize {
        self.added.len() + self.cleared.len() + self.changed.len()
    }
}

/// Compute the diff between two sorted fingerprint maps. Pure function —
/// trivially unit-testable without spinning up the daemon or running probes.
fn diff_fingerprint_maps(
    previous: &std::collections::BTreeMap<DiagnosticKey, DiagnosticFingerprint>,
    current: &std::collections::BTreeMap<DiagnosticKey, DiagnosticFingerprint>,
) -> DiagnosticDiff {
    let mut diff = DiagnosticDiff::default();
    for (key, fp) in current {
        match previous.get(key) {
            None => diff.added.push((key.clone(), fp.clone())),
            Some(prev_fp) if prev_fp != fp => {
                diff.changed
                    .push((key.clone(), prev_fp.clone(), fp.clone()));
            }
            Some(_) => {}
        }
    }
    for (key, fp) in previous {
        if !current.contains_key(key) {
            diff.cleared.push((key.clone(), fp.clone()));
        }
    }
    diff
}

/// Build the fingerprint map for a response. Deterministic ordering by
/// `DiagnosticKey` so machine output is stable across runs.
fn fingerprint_map_of(
    response: &ReliabilityDoctorResponse,
) -> std::collections::BTreeMap<DiagnosticKey, DiagnosticFingerprint> {
    let mut map = std::collections::BTreeMap::new();
    for d in &response.diagnostics {
        map.insert(
            DiagnosticKey::from_diagnostic(d),
            DiagnosticFingerprint::from_diagnostic(d),
        );
    }
    map
}

/// State threaded through the watch loop. `last_*` fields are `None`
/// before the first sweep (so the initial sweep is always a transition).
struct WatchState {
    started_at: Instant,
    sweep_count: u64,
    /// Number of sweeps where the diff had ANY changes (i.e., something
    /// transitioned). Logged in the final summary.
    transitions_count: u64,
    last_verdict: Option<ReliabilityVerdict>,
    last_fingerprints: std::collections::BTreeMap<DiagnosticKey, DiagnosticFingerprint>,
    /// Highest-severity verdict observed across all sweeps. Useful for
    /// CI tripwires that want a single answer at the end.
    worst_verdict: Option<ReliabilityVerdict>,
}

fn worst_reliability_verdict(
    observed: Option<ReliabilityVerdict>,
    candidate: ReliabilityVerdict,
) -> ReliabilityVerdict {
    match (observed, candidate) {
        (Some(ReliabilityVerdict::Failing), _) | (_, ReliabilityVerdict::Failing) => {
            ReliabilityVerdict::Failing
        }
        (Some(ReliabilityVerdict::Degraded), _) | (_, ReliabilityVerdict::Degraded) => {
            ReliabilityVerdict::Degraded
        }
        (Some(ReliabilityVerdict::Healthy), ReliabilityVerdict::Healthy)
        | (None, ReliabilityVerdict::Healthy) => ReliabilityVerdict::Healthy,
    }
}

impl WatchState {
    fn new() -> Self {
        Self {
            started_at: Instant::now(),
            sweep_count: 0,
            transitions_count: 0,
            last_verdict: None,
            last_fingerprints: std::collections::BTreeMap::new(),
            worst_verdict: None,
        }
    }

    /// Update the worst-observed verdict using max-severity-wins.
    fn observe_verdict(&mut self, verdict: ReliabilityVerdict) {
        self.worst_verdict = Some(worst_reliability_verdict(self.worst_verdict, verdict));
    }
}

/// Machine sweep payload (one of these per emitted iteration in
/// machine-readable mode). Schema matches the agent contract: agents
/// inspect `verdict` / `diff_summary` for tripwire behavior.
#[derive(Debug, Clone, Serialize)]
struct WatchSweepMachineLine<'a> {
    /// Logical command tag — matches the dotted-token convention used
    /// elsewhere ("doctor.reliability.watch") so log consumers can split
    /// single-shot vs continuous traffic by tag alone.
    command: &'static str,
    schema_version: &'a str,
    sweep_index: u64,
    elapsed_secs: u64,
    verdict: &'static str,
    verdict_changed: bool,
    diff_summary: WatchDiffSummary,
    /// Full response (so a single machine output record is self-contained).
    response: &'a ReliabilityDoctorResponse,
}

#[derive(Debug, Clone, Serialize)]
struct WatchDiffSummary {
    added: usize,
    cleared: usize,
    changed: usize,
    has_changes: bool,
}

/// `--watch-snapshot` final summary. Written once at exit.
#[derive(Debug, Clone, Serialize)]
struct WatchSnapshot<'a> {
    command: &'static str,
    schema_version: &'a str,
    sweeps_total: u64,
    transitions_total: u64,
    elapsed_secs: u64,
    final_verdict: &'static str,
    /// Worst verdict observed at any point during the watch session.
    /// Distinct from `final_verdict` because the system may have
    /// recovered before exit; CI gates often want the worst-case.
    worst_verdict: &'static str,
    /// Final per-diagnostic state (so the snapshot can be diffed against
    /// the next session's first sweep).
    final_diagnostics: &'a Vec<ReliabilityDiagnostic>,
}

/// Run the continuous-monitoring watch loop until SIGINT. Each sweep
/// re-runs the full reliability probe suite, computes a diff against
/// the prior sweep, and emits output (suppressed under
/// `--transitions-only` when nothing changed).
async fn run_reliability_watch_loop(ctx: &OutputContext, options: &DoctorOptions) -> Result<()> {
    let interval_secs = options.watch_interval_secs.max(1);
    let interval = Duration::from_secs(interval_secs);
    let snapshot_path = options.watch_snapshot.clone();
    let style = ctx.theme();
    let schema_version =
        rch_common::schema_version(rch_common::SchemaComponent::DoctorReliability).to_string();

    tracing::info!(
        target: "rch::doctor::watch",
        interval_secs,
        transitions_only = options.transitions_only,
        snapshot_path = ?snapshot_path,
        scope = ?options.scope.as_strings(),
        "doctor.watch.start",
    );

    if !ctx.is_json() {
        eprintln!(
            "{} (interval={interval_secs}s, scope={:?}, press Ctrl-C to exit)",
            style.format_header("RCH Doctor — continuous watch mode"),
            options.scope.as_strings(),
        );
        if options.transitions_only {
            eprintln!(
                "{}",
                style.muted("    --transitions-only: emitting only when state changes")
            );
        }
        eprintln!();
    }

    // Build the verdict-transition webhook dispatcher from config. `None`
    // (the common case: no endpoints configured) costs nothing per sweep.
    // Config-load failure is non-fatal — webhooks are an add-on, never
    // load-bearing for the watch verdict.
    let webhook_dispatcher = match crate::config::load_config() {
        Ok(cfg) => crate::doctor_webhooks::WebhookDispatcher::from_config(&cfg.doctor.webhooks),
        Err(e) => {
            tracing::warn!(
                target: "rch::doctor::webhook",
                error = %e,
                "doctor.webhook.config_load_failed",
            );
            None
        }
    };

    let mut state = WatchState::new();
    // `tokio::time::interval` ticks immediately on the first call to
    // `tick()`. That's exactly what we want — sweep at t=0, then every
    // `interval_secs` thereafter. `Skip` behavior ensures we don't build
    // up a backlog if a sweep happens to overrun the interval.
    let mut ticker = tokio::time::interval(interval);
    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);

    // Single-shot SIGINT future. We `pin!` it so the borrow can survive
    // across loop iterations; we break the moment it fires (never poll
    // again).
    let sigint = tokio::signal::ctrl_c();
    tokio::pin!(sigint);

    loop {
        tokio::select! {
            // Bias toward the SIGINT branch so a Ctrl-C delivered at the
            // exact same instant as a tick exits cleanly rather than
            // running one more (potentially slow) sweep.
            biased;
            sig = &mut sigint => {
                if let Err(e) = sig {
                    tracing::warn!(
                        target: "rch::doctor::watch",
                        error = %e,
                        "ctrl_c handler installation failed; exiting watch loop"
                    );
                }
                break;
            }
            _ = ticker.tick() => {
                state.sweep_count += 1;
                let sweep_started = Instant::now();
                let response = collect_reliability_response_once(options).await;
                let current_fp = fingerprint_map_of(&response);
                let diff = diff_fingerprint_maps(&state.last_fingerprints, &current_fp);
                let verdict = response.summary.overall;
                let verdict_changed = state.last_verdict != Some(verdict);
                let any_change = diff.has_changes() || verdict_changed;
                // transitions_count must count VERDICT transitions only — that is
                // what the "transitions"/"transitions_total" summary fields report
                // and what the webhooks fire on. A diagnostic-text-only diff (the
                // verdict unchanged) must not inflate it, or it misleads CI gates
                // keying on transitions_total (bd-review-doctor-transitions-count).
                // `any_change` still drives --transitions-only output below.
                if verdict_changed {
                    state.transitions_count += 1;
                }
                state.observe_verdict(verdict);

                // Fire verdict-transition webhooks. The implicit baseline for
                // the very first sweep is `Healthy`, so a watch session that
                // starts in a bad state still pages (`any_to_failing` etc.).
                if verdict_changed
                    && let Some(dispatcher) = &webhook_dispatcher
                {
                    let from = state.last_verdict.unwrap_or(ReliabilityVerdict::Healthy);
                    let transition = crate::doctor_webhooks::WebhookTransition {
                        from,
                        to: verdict,
                        host: crate::doctor_webhooks::hostname(),
                        ts: chrono::Utc::now().to_rfc3339(),
                        scope: response.scope.clone(),
                        diagnostics: response
                            .diagnostics
                            .iter()
                            .map(|d| crate::doctor_webhooks::WebhookDiagnostic {
                                code: d.code.to_string(),
                                severity: reliability_severity_token(d.severity).to_string(),
                                category: d.category.as_str().to_string(),
                                message: d.message.clone(),
                            })
                            .collect(),
                    };
                    let fired = dispatcher.on_transition(&transition);
                    if fired > 0 {
                        tracing::info!(
                            target: "rch::doctor::webhook",
                            from = from.label(),
                            to = verdict.label(),
                            endpoints = fired,
                            "doctor.webhook.transition_dispatched",
                        );
                    }
                }

                let sweep_elapsed_ms = sweep_started.elapsed().as_millis();

                let should_emit = !options.transitions_only || any_change || state.sweep_count == 1;
                tracing::debug!(
                    target: "rch::doctor::watch",
                    sweep = state.sweep_count,
                    verdict = verdict.label(),
                    verdict_changed,
                    added = diff.added.len(),
                    cleared = diff.cleared.len(),
                    changed = diff.changed.len(),
                    transition_items = diff.total_transitions(),
                    sweep_elapsed_ms,
                    suppressed = !should_emit,
                    "doctor.watch.sweep",
                );

                if should_emit {
                    if ctx.is_json() {
                        emit_watch_sweep_machine_line(
                            ctx,
                            &response,
                            &diff,
                            verdict_changed,
                            &schema_version,
                            state.sweep_count,
                            state.started_at,
                        );
                    } else {
                        emit_watch_sweep_human(
                            ctx,
                            &response,
                            &diff,
                            verdict_changed,
                            state.sweep_count,
                            state.started_at,
                            sweep_elapsed_ms,
                        );
                    }
                }

                state.last_verdict = Some(verdict);
                state.last_fingerprints = current_fp;
            }
        }
    }

    // SIGINT or signal-handler error fell through. Emit a final summary on
    // stderr (so JSON consumers piping stdout to a file still see it)
    // and write the snapshot file if requested.
    //
    // When a snapshot is requested, collect the exit-time response before
    // rendering the summary so stderr, tracing, and the snapshot file all
    // describe the same final state.
    let final_response_for_snapshot = if snapshot_path.is_some() {
        Some(collect_reliability_response_once(options).await)
    } else {
        None
    };
    let final_verdict = final_response_for_snapshot.as_ref().map_or_else(
        || state.last_verdict.unwrap_or(ReliabilityVerdict::Healthy),
        |r| r.summary.overall,
    );
    let worst_verdict = worst_reliability_verdict(state.worst_verdict, final_verdict);
    let elapsed_secs = state.started_at.elapsed().as_secs();
    if !ctx.is_json() {
        eprintln!();
        eprintln!(
            "{} {} sweeps, {} transitions, {}s elapsed — final={}, worst={}",
            style.format_header("Watch session ended"),
            style.highlight(&state.sweep_count.to_string()),
            style.highlight(&state.transitions_count.to_string()),
            style.highlight(&elapsed_secs.to_string()),
            style.highlight(final_verdict.label()),
            style.highlight(worst_verdict.label()),
        );
    } else {
        // In JSON mode, still write a final summary line so log consumers
        // can detect clean exit vs hard kill. Emitted on stderr to keep
        // the machine stream on stdout uninterrupted.
        eprintln!(
            r#"{{"command":"doctor.reliability.watch.end","sweeps_total":{},"transitions_total":{},"elapsed_secs":{},"final_verdict":"{}","worst_verdict":"{}"}}"#,
            state.sweep_count,
            state.transitions_count,
            elapsed_secs,
            final_verdict.label(),
            worst_verdict.label(),
        );
    }
    tracing::info!(
        target: "rch::doctor::watch",
        sweeps_total = state.sweep_count,
        transitions_total = state.transitions_count,
        elapsed_secs,
        final_verdict = final_verdict.label(),
        worst_verdict = worst_verdict.label(),
        "doctor.watch.end",
    );

    if let (Some(path), Some(final_response)) = (snapshot_path, final_response_for_snapshot) {
        // The in-flight state only holds fingerprints; the full diagnostics
        // list requires this final probe pass. This is intentional: the
        // snapshot reflects state at exit, not state at the last emitted
        // sweep.
        let snapshot = WatchSnapshot {
            command: "doctor.reliability.watch.snapshot",
            schema_version: &schema_version,
            sweeps_total: state.sweep_count,
            transitions_total: state.transitions_count,
            elapsed_secs,
            final_verdict: final_response.summary.overall.label(),
            worst_verdict: worst_verdict.label(),
            final_diagnostics: &final_response.diagnostics,
        };
        let body = serde_json::to_string_pretty(&snapshot)
            .map_err(|e| anyhow::anyhow!("serialize watch snapshot: {e}"))?;
        // Atomic temp+rename so partial writes can't leave a corrupt
        // snapshot on disk if the process is killed mid-write.
        let tmp = path.with_extension("json.partial");
        tokio::fs::write(&tmp, body.as_bytes())
            .await
            .map_err(|e| anyhow::anyhow!("write watch snapshot tmp file: {e}"))?;
        tokio::fs::rename(&tmp, &path)
            .await
            .map_err(|e| anyhow::anyhow!("rename watch snapshot to final path: {e}"))?;
        tracing::info!(
            target: "rch::doctor::watch",
            path = %path.display(),
            "doctor.watch.snapshot.written",
        );
        if !ctx.is_json() {
            eprintln!(
                "{} {}",
                style.muted("    snapshot:"),
                style.highlight(&path.display().to_string())
            );
        }
    }

    Ok(())
}

/// Human-form sweep emitter: prints a compact one-line header per
/// sweep on stderr, followed by indented bullets for each transition.
/// Severity gets verdict-aware coloring through the theme. Output is
/// designed to be readable in a long-running terminal session — no
/// full panel redraws, no clear-screen. Bullets are sortable.
fn emit_watch_sweep_human(
    ctx: &OutputContext,
    response: &ReliabilityDoctorResponse,
    diff: &DiagnosticDiff,
    verdict_changed: bool,
    sweep: u64,
    started_at: Instant,
    sweep_elapsed_ms: u128,
) {
    let style = ctx.theme();
    let verdict = response.summary.overall;
    let verdict_label = verdict.label();
    let colored_verdict = match verdict {
        ReliabilityVerdict::Healthy => style.format_success(verdict_label),
        ReliabilityVerdict::Degraded => style.format_warning(verdict_label),
        ReliabilityVerdict::Failing => style.format_error(verdict_label),
    };
    let elapsed = started_at.elapsed().as_secs();
    let arrow = if verdict_changed { " (CHANGED)" } else { "" };
    eprintln!(
        "[sweep {sweep:>4} t+{elapsed:>4}s] verdict={colored_verdict}{arrow} \
         pass={p} info={i} warn={w} crit={c} probe_ms={ms} \
         diff: +{added} -{cleared} ~{changed}",
        p = response.summary.pass,
        i = response.summary.info,
        w = response.summary.warning,
        c = response.summary.critical,
        ms = sweep_elapsed_ms,
        added = diff.added.len(),
        cleared = diff.cleared.len(),
        changed = diff.changed.len(),
    );
    // Bullets — keyed by stable DiagnosticKey so output is sortable.
    for (key, fp) in &diff.added {
        eprintln!(
            "    {} {} [{}] {}",
            style.format_warning("+ new"),
            key.render(),
            severity_short(fp.severity),
            fp.message,
        );
    }
    for (key, fp) in &diff.cleared {
        eprintln!(
            "    {} {} [{}] {}",
            style.format_success("- cleared"),
            key.render(),
            severity_short(fp.severity),
            fp.message,
        );
    }
    for (key, prev, cur) in &diff.changed {
        eprintln!(
            "    {} {} [{}→{}] {} → {}",
            style.muted("~ changed"),
            key.render(),
            severity_short(prev.severity),
            severity_short(cur.severity),
            prev.message,
            cur.message,
        );
    }
}

/// Machine-mode sweep emitter: one self-contained JSON or TOON object
/// per line on stdout. Designed for structured-log consumers.
fn emit_watch_sweep_machine_line(
    ctx: &OutputContext,
    response: &ReliabilityDoctorResponse,
    diff: &DiagnosticDiff,
    verdict_changed: bool,
    schema_version: &str,
    sweep: u64,
    started_at: Instant,
) {
    let payload = WatchSweepMachineLine {
        command: "doctor.reliability.watch",
        schema_version,
        sweep_index: sweep,
        elapsed_secs: started_at.elapsed().as_secs(),
        verdict: response.summary.overall.label(),
        verdict_changed,
        diff_summary: WatchDiffSummary {
            added: diff.added.len(),
            cleared: diff.cleared.len(),
            changed: diff.changed.len(),
            has_changes: diff.has_changes(),
        },
        response,
    };
    // `json_compact` honors the configured machine format and writes one
    // record per line, preserving parseable stdout for watch consumers.
    let _ = ctx.json_compact(&payload);
}

/// Short single-letter severity glyph used in the human watch output.
/// Keeps diff lines compact when many transitions fire at once.
fn severity_short(severity: ReliabilitySeverity) -> &'static str {
    match severity {
        ReliabilitySeverity::Pass => "PASS",
        ReliabilitySeverity::Info => "INFO",
        ReliabilitySeverity::Warning => "WARN",
        ReliabilitySeverity::Critical => "CRIT",
    }
}

fn reliability_topology_diagnostics(
    workers: Option<&[rch_common::WorkerConfig]>,
    daemon_status: Option<&DaemonFullStatusResponse>,
    worker_config_error: Option<String>,
) -> Vec<ReliabilityDiagnostic> {
    let mut diagnostics = Vec::new();

    if let Some(error) = worker_config_error {
        diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::Topology,
                "workers_config",
                ReliabilitySeverity::Critical,
                "Worker configuration could not be loaded",
                ReliabilityReasonCode::WorkersConfigUnreadable,
            )
            .with_details(error)
            .with_remediation(
                "rch config doctor --json",
                "rch doctor --reliability --json",
            ),
        );
    } else if let Some(workers) = workers {
        if workers.is_empty() {
            diagnostics.push(
                ReliabilityDiagnostic::new(
                    ReliabilityCategory::Topology,
                    "workers_config",
                    ReliabilitySeverity::Critical,
                    "No workers are configured, so all builds will run locally",
                    ReliabilityReasonCode::NoWorkersConfigured,
                )
                .with_remediation("rch workers init", "rch workers list --json"),
            );
        } else {
            let worker_ids = workers
                .iter()
                .map(|worker| worker.id.to_string())
                .collect::<Vec<_>>()
                .join(", ");
            diagnostics.push(
                ReliabilityDiagnostic::new(
                    ReliabilityCategory::Topology,
                    "workers_config",
                    ReliabilitySeverity::Pass,
                    format!("{} worker(s) configured", workers.len()),
                    ReliabilityReasonCode::WorkersConfigured,
                )
                .with_details(worker_ids),
            );
        }
    }

    let Some(status) = daemon_status else {
        diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::Topology,
                "daemon_status",
                ReliabilitySeverity::Warning,
                "Daemon status is unavailable; reliability health is partial",
                ReliabilityReasonCode::DaemonStatusUnavailable,
            )
            .with_remediation("rch daemon start", "rch status --json"),
        );
        return diagnostics;
    };

    let daemon = &status.daemon;
    let (severity, code, message) = if daemon.workers_total == 0 {
        (
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::DaemonHasNoWorkers,
            "Daemon has no registered workers".to_string(),
        )
    } else if daemon.workers_healthy == 0 {
        (
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::AllWorkersUnhealthy,
            format!("0/{} workers are healthy", daemon.workers_total),
        )
    } else if daemon.workers_healthy < daemon.workers_total {
        (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::PartialWorkerCapacity,
            format!(
                "{}/{} workers are healthy",
                daemon.workers_healthy, daemon.workers_total
            ),
        )
    } else {
        (
            ReliabilitySeverity::Pass,
            ReliabilityReasonCode::WorkersHealthy,
            format!("All {} workers are healthy", daemon.workers_total),
        )
    };
    let mut daemon_diag = ReliabilityDiagnostic::new(
        ReliabilityCategory::Topology,
        "daemon_worker_capacity",
        severity,
        message,
        code,
    )
    .with_details(format!(
        "slots_available={}, slots_total={}, uptime_secs={}",
        daemon.slots_available, daemon.slots_total, daemon.uptime_secs
    ));
    if severity != ReliabilitySeverity::Pass {
        daemon_diag =
            daemon_diag.with_remediation("rch workers probe --all", "rch status --workers --json");
    }
    diagnostics.push(daemon_diag);

    diagnostics.extend(status.workers.iter().map(worker_topology_diagnostic));
    diagnostics
}

/// bd-kugfc: build mirror-ownership diagnostics from the per-worker
/// detection-only probe results.
///
/// Inputs arrive pre-joined: `probe_results` is `Some` only when the
/// fan-out task itself completed (per-worker slots then carry their own
/// outcome, including per-task panics as [`MirrorOwnershipProbe::Unprobeable`]);
/// `None` means the whole probe bucket failed to produce data (timeout,
/// panic in the fan-out task) and one fleet-level unprobeable diagnostic
/// is synthesized instead. Ordering follows the caller's worker-config
/// order, so output stays byte-stable across runs.
fn reliability_mirror_ownership_diagnostics(
    workers: Option<&[rch_common::WorkerConfig]>,
    worker_config_error: Option<String>,
    probe_results: Option<&Vec<crate::hook::ssh::MirrorOwnershipProbe>>,
    outcome: ProbeOutcome,
    canonical_root_error: Option<&String>,
) -> Vec<ReliabilityDiagnostic> {
    let validation = "rch doctor --reliability --scope=ownership --json";

    if let Some(error) = worker_config_error {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::MirrorOwnership,
                "mirror_ownership",
                ReliabilitySeverity::Warning,
                "Workers configuration unavailable; mirror-tree ownership not probed",
                ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable,
            )
            .with_details(format!("workers config error: {error}"))
            .with_remediation("rch config doctor --json", validation),
        ];
    }

    if let Some(error) = canonical_root_error {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::MirrorOwnership,
                "mirror_ownership",
                ReliabilitySeverity::Warning,
                "Config load failed; cannot resolve the canonical mirror root to probe",
                ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable,
            )
            .with_details(format!("config error: {error}"))
            .with_remediation("rch config doctor --json", validation),
        ];
    }

    let Some(workers) = workers else {
        return vec![];
    };
    if workers.is_empty() {
        return vec![ReliabilityDiagnostic::new(
            ReliabilityCategory::MirrorOwnership,
            "mirror_ownership",
            ReliabilitySeverity::Info,
            "No workers are configured; nothing to probe for ownership drift",
            ReliabilityReasonCode::MirrorOwnershipNoWorkers,
        )];
    }

    // The fan-out task died without producing per-worker slots — report
    // honestly at fleet level using the join outcome forensics.
    let Some(results) = probe_results else {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::MirrorOwnership,
                "mirror_ownership",
                ReliabilitySeverity::Warning,
                format!(
                    "Mirror-ownership probe did not complete ({})",
                    outcome.label()
                ),
                ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable,
            )
            .with_remediation("rch workers probe --all", validation),
        ];
    };

    workers
        .iter()
        .zip(results.iter())
        .filter_map(|(worker, probe)| {
            let worker_id = worker.id.to_string();
            match probe {
                crate::hook::ssh::MirrorOwnershipProbe::Skipped => None,
                crate::hook::ssh::MirrorOwnershipProbe::Healthy => Some(
                    ReliabilityDiagnostic::new(
                        ReliabilityCategory::MirrorOwnership,
                        "mirror_ownership",
                        ReliabilitySeverity::Pass,
                        "Mirror tree has no root-owned entries",
                        ReliabilityReasonCode::WorkerMirrorOwnershipHealthy,
                    )
                    .with_worker(worker_id),
                ),
                crate::hook::ssh::MirrorOwnershipProbe::Drift { count } => {
                    let user = &worker.user;
                    let host = &worker.host;
                    let manual_fix = format!(
                        "ssh {user}@{host} 'sudo find <canonical-root> -xdev -user root -exec chown -h {user} {{}} +'"
                    );
                    Some(
                        ReliabilityDiagnostic::new(
                            ReliabilityCategory::MirrorOwnership,
                            "mirror_ownership",
                            ReliabilitySeverity::Warning,
                            format!(
                                "{count} root-owned entr{} under the canonical mirror tree; \
                                 rsync-as-{user} will fail exit 23 until repaired",
                                if *count == 1 { "y" } else { "ies" }
                            ),
                            ReliabilityReasonCode::WorkerMirrorOwnershipDrift,
                        )
                        .with_worker(worker_id)
                        .with_details(format!(
                            "drift_count={count}; self-heals at the next dispatch preflight (bd-8iwkm)"
                        ))
                        .with_remediation(manual_fix, validation),
                    )
                }
                crate::hook::ssh::MirrorOwnershipProbe::CheckUnavailable => Some(
                    ReliabilityDiagnostic::new(
                        ReliabilityCategory::MirrorOwnership,
                        "mirror_ownership",
                        ReliabilitySeverity::Warning,
                        "Passwordless sudo unavailable on worker; ownership check \
                         cannot run and dispatch-time repair fails open",
                        ReliabilityReasonCode::WorkerMirrorOwnershipCheckUnavailable,
                    )
                    .with_worker(worker_id.clone())
                    .with_remediation(
                        format!("ssh {worker_id} 'sudo -n true'"),
                        validation,
                    ),
                ),
                crate::hook::ssh::MirrorOwnershipProbe::Unprobeable(reason) => Some(
                    ReliabilityDiagnostic::new(
                        ReliabilityCategory::MirrorOwnership,
                        "mirror_ownership",
                        ReliabilitySeverity::Warning,
                        "Ownership probe could not reach the worker; drift state unknown",
                        ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable,
                    )
                    .with_worker(worker_id)
                    .with_details(reason.clone())
                    .with_remediation("rch workers probe --all", validation),
                ),
            }
        })
        .collect()
}

/// Outcome of a defensive parse: a known categorical value OR the raw
/// (trim+lowercased) input that we couldn't recognize. The raw form is
/// preserved so the resulting diagnostic carries forensics for operators.
#[derive(Debug, Clone, PartialEq, Eq)]
enum ParsedStatus {
    Known(KnownStatus),
    Unrecognized(String),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum KnownStatus {
    /// Healthy/available/ready/idle/running — counts as "ready".
    Ready,
    /// Known non-ready statuses reported by daemon/status UIs.
    Degraded,
    /// Unreachable/offline/error/failed — critical.
    Unreachable,
}

#[derive(Debug, Clone, PartialEq, Eq)]
enum ParsedCircuit {
    Known(KnownCircuit),
    Unrecognized(String),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum KnownCircuit {
    Closed,
    Open,
    HalfOpen,
}

/// Trim + lowercase + match against the known status set. Known
/// non-ready states remain `WorkerDegraded`; unknown values become
/// `Unrecognized(raw)` so the caller can surface protocol drift rather
/// than silently mapping to `Pass` (the prior default-to-success bug).
fn parse_worker_ready_status(raw: &str) -> ParsedStatus {
    let normalized = raw.trim().to_ascii_lowercase();
    if matches!(
        normalized.as_str(),
        "healthy" | "available" | "ready" | "idle" | "running"
    ) {
        ParsedStatus::Known(KnownStatus::Ready)
    } else if matches!(
        normalized.as_str(),
        "unreachable" | "offline" | "error" | "failed"
    ) {
        ParsedStatus::Known(KnownStatus::Unreachable)
    } else if matches!(
        normalized.as_str(),
        "busy" | "degraded" | "draining" | "drained" | "disabled" | "unhealthy"
    ) {
        ParsedStatus::Known(KnownStatus::Degraded)
    } else {
        ParsedStatus::Unrecognized(normalized)
    }
}

/// Same discipline as [`parse_worker_ready_status`] but for the
/// circuit-breaker state field. `closed` is the healthy default;
/// `open` is critical; `half_open` is degraded; anything else
/// (including empty string, whitespace, unexpected casings of unknown
/// variants like `OPEN_FORCED`) surfaces as `Unrecognized`.
fn parse_worker_circuit_state(raw: &str) -> ParsedCircuit {
    let normalized = raw.trim().to_ascii_lowercase();
    match normalized.as_str() {
        "closed" => ParsedCircuit::Known(KnownCircuit::Closed),
        "open" => ParsedCircuit::Known(KnownCircuit::Open),
        "half_open" | "half-open" => ParsedCircuit::Known(KnownCircuit::HalfOpen),
        _ => ParsedCircuit::Unrecognized(normalized),
    }
}

fn worker_topology_diagnostic(worker: &WorkerStatusFromApi) -> ReliabilityDiagnostic {
    let parsed_status = parse_worker_ready_status(&worker.status);
    let parsed_circuit = parse_worker_circuit_state(&worker.circuit_state);

    let (severity, code, message) = match (&parsed_circuit, &parsed_status) {
        // Unrecognized values surface as Warnings with the raw value
        // in the diagnostic context. Default-to-degraded — never Pass.
        (ParsedCircuit::Unrecognized(raw), _) => (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::WorkerCircuitStateUnrecognized,
            format!(
                "Worker {} circuit_state is unrecognized ({raw:?})",
                worker.id
            ),
        ),
        (_, ParsedStatus::Unrecognized(raw)) => (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::WorkerStatusUnrecognized,
            format!("Worker {} status is unrecognized ({raw:?})", worker.id),
        ),
        // Known values: same routing as before.
        (ParsedCircuit::Known(KnownCircuit::Open), _) => (
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::WorkerCircuitOpen,
            format!("Worker {} circuit is open", worker.id),
        ),
        (_, ParsedStatus::Known(KnownStatus::Unreachable)) => (
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::WorkerUnreachable,
            format!("Worker {} is {}", worker.id, worker.status),
        ),
        (ParsedCircuit::Known(KnownCircuit::HalfOpen), _) => (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::WorkerDegraded,
            format!(
                "Worker {} is degraded (status={}, circuit={})",
                worker.id, worker.status, worker.circuit_state
            ),
        ),
        (_, ParsedStatus::Known(KnownStatus::Degraded)) => (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::WorkerDegraded,
            format!(
                "Worker {} is degraded (status={}, circuit={})",
                worker.id, worker.status, worker.circuit_state
            ),
        ),
        // Closed circuit + Ready status = healthy.
        (ParsedCircuit::Known(KnownCircuit::Closed), ParsedStatus::Known(KnownStatus::Ready)) => (
            ReliabilitySeverity::Pass,
            ReliabilityReasonCode::WorkerReady,
            format!("Worker {} is ready", worker.id),
        ),
    };

    let mut diagnostic = ReliabilityDiagnostic::new(
        ReliabilityCategory::Topology,
        "worker_topology",
        severity,
        message,
        code,
    )
    .with_worker(worker.id.clone())
    .with_details(format!(
        "host={}, used_slots={}, total_slots={}, speed_score={:.2}, consecutive_failures={}",
        worker.host,
        worker.used_slots,
        worker.total_slots,
        worker.speed_score,
        worker.consecutive_failures
    ));

    if severity != ReliabilitySeverity::Pass {
        diagnostic = diagnostic.with_remediation(
            format!("rch workers probe {} --force", worker.id),
            "rch status --workers --json",
        );
    }

    // Emit a tracing event whenever we see an unrecognized value so log
    // consumers can spot protocol drift between daemon versions.
    if let ParsedStatus::Unrecognized(raw) = &parsed_status {
        tracing::warn!(
            target: "rch::doctor::parse",
            worker = %worker.id,
            field = "status",
            raw = %raw,
            "doctor.parse.unrecognized",
        );
    }
    if let ParsedCircuit::Unrecognized(raw) = &parsed_circuit {
        tracing::warn!(
            target: "rch::doctor::parse",
            worker = %worker.id,
            field = "circuit_state",
            raw = %raw,
            "doctor.parse.unrecognized",
        );
    }

    diagnostic
}

fn reliability_repo_diagnostics(
    convergence: Option<&RepoConvergenceStatusFromApi>,
) -> Vec<ReliabilityDiagnostic> {
    let Some(convergence) = convergence else {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::RepoPresence,
                "repo_convergence",
                ReliabilitySeverity::Warning,
                "Repo-convergence status is unavailable",
                ReliabilityReasonCode::RepoConvergenceUnavailable,
            )
            .with_remediation("rch daemon start", "rch status --json"),
        ];
    };

    let summary = &convergence.summary;
    let mut diagnostics = Vec::new();
    let (severity, code, message) = if summary.failed > 0 {
        (
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::RepoConvergenceFailed,
            format!("{} worker(s) failed repo convergence", summary.failed),
        )
    } else if summary.drifting > 0 || summary.stale > 0 {
        (
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::RepoConvergenceDrift,
            format!(
                "{} drifting and {} stale worker(s)",
                summary.drifting, summary.stale
            ),
        )
    } else if summary.total_workers == 0 {
        (
            ReliabilitySeverity::Info,
            ReliabilityReasonCode::RepoConvergenceNoWorkers,
            "No worker repo-convergence records were reported".to_string(),
        )
    } else {
        (
            ReliabilitySeverity::Pass,
            ReliabilityReasonCode::RepoConvergenceReady,
            format!("{} worker(s) are repo-converged", summary.ready),
        )
    };

    let mut summary_diag = ReliabilityDiagnostic::new(
        ReliabilityCategory::RepoPresence,
        "repo_convergence",
        severity,
        message,
        code,
    )
    .with_details(format!(
        "status={}, total={}, ready={}, converging={}, drifting={}, failed={}, stale={}",
        convergence.status,
        summary.total_workers,
        summary.ready,
        summary.converging,
        summary.drifting,
        summary.failed,
        summary.stale
    ));
    if matches!(
        severity,
        ReliabilitySeverity::Critical | ReliabilitySeverity::Warning
    ) {
        summary_diag =
            summary_diag.with_remediation("rch workers probe --all", "rch status --json");
    }
    diagnostics.push(summary_diag);

    diagnostics.extend(convergence.workers.iter().filter_map(|worker| {
        if worker.missing_repos.is_empty() && worker.drift_state == "ready" {
            return None;
        }

        let severity = if worker.drift_state == "failed" {
            ReliabilitySeverity::Critical
        } else {
            ReliabilitySeverity::Warning
        };
        let missing = if worker.missing_repos.is_empty() {
            "none".to_string()
        } else {
            worker.missing_repos.join(", ")
        };
        let mut diagnostic = ReliabilityDiagnostic::new(
            ReliabilityCategory::RepoPresence,
            "worker_repo_presence",
            severity,
            format!(
                "Worker {} repo state is {}",
                worker.worker_id, worker.drift_state
            ),
            ReliabilityReasonCode::WorkerRepoNotReady,
        )
        .with_worker(worker.worker_id.clone())
        .with_details(format!(
            "confidence={:.2}, missing_repos={}, attempts_remaining={}, time_budget_ms={}",
            worker.drift_confidence,
            missing,
            worker.attempt_budget_remaining,
            worker.time_budget_remaining_ms
        ));

        if let Some(command) = worker.remediation.first() {
            diagnostic =
                diagnostic.with_remediation(command.clone(), "rch status --workers --json");
        } else {
            diagnostic = diagnostic
                .with_remediation("rch workers probe --all", "rch status --workers --json");
        }

        Some(diagnostic)
    }));

    diagnostics
}

fn reliability_disk_pressure_diagnostics(
    status: Option<&DaemonFullStatusResponse>,
) -> Vec<ReliabilityDiagnostic> {
    let Some(status) = status else {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::DiskPressure,
                "disk_pressure",
                ReliabilitySeverity::Warning,
                "Disk-pressure telemetry is unavailable because daemon status could not be read",
                ReliabilityReasonCode::DiskPressureUnavailable,
            )
            .with_remediation("rch daemon start", "rch status --workers --json"),
        ];
    };

    if status.workers.is_empty() {
        return vec![ReliabilityDiagnostic::new(
            ReliabilityCategory::DiskPressure,
            "disk_pressure",
            ReliabilitySeverity::Info,
            "No workers reported disk-pressure telemetry",
            ReliabilityReasonCode::DiskPressureNoWorkers,
        )];
    }

    status
        .workers
        .iter()
        .map(|worker| {
            let state = worker
                .pressure_state
                .as_deref()
                .unwrap_or("telemetry_gap");
            let (severity, code, message) = match state {
                "critical" => (
                    ReliabilitySeverity::Critical,
                    ReliabilityReasonCode::WorkerDiskPressureCritical,
                    format!(
                        "Worker {} has critical disk pressure ({})",
                        worker.id,
                        format_disk_free(worker.pressure_disk_free_gb)
                    ),
                ),
                "warning" => (
                    ReliabilitySeverity::Warning,
                    ReliabilityReasonCode::WorkerDiskPressureWarning,
                    format!(
                        "Worker {} has elevated disk pressure ({})",
                        worker.id,
                        format_disk_free(worker.pressure_disk_free_gb)
                    ),
                ),
                "healthy" => (
                    ReliabilitySeverity::Pass,
                    ReliabilityReasonCode::WorkerDiskPressureHealthy,
                    format!(
                        "Worker {} disk pressure is healthy ({})",
                        worker.id,
                        format_disk_free(worker.pressure_disk_free_gb)
                    ),
                ),
                _ => (
                    ReliabilitySeverity::Warning,
                    ReliabilityReasonCode::WorkerDiskPressureTelemetryGap,
                    format!("Worker {} is missing fresh disk telemetry", worker.id),
                ),
            };

            // t11: build the details string with a single preallocated
            // buffer + write! macro instead of 7 intermediate
            // `.map(|v| format!(...)).unwrap_or_else(|| "unknown".to_string())`
            // chains. Saves ~7 allocations per worker; for a 50-worker
            // fleet that's ~350 transient Strings eliminated per run.
            let mut details = String::with_capacity(256);
            use std::fmt::Write as _;
            let _ = write!(
                details,
                "state={state}, confidence={}, free_gb=",
                worker.pressure_confidence.as_deref().unwrap_or("unknown")
            );
            push_opt_f64(&mut details, worker.pressure_disk_free_gb, 2);
            details.push_str(", total_gb=");
            push_opt_f64(&mut details, worker.pressure_disk_total_gb, 2);
            details.push_str(", free_ratio=");
            push_opt_f64(&mut details, worker.pressure_disk_free_ratio, 3);
            details.push_str(", io_util_pct=");
            push_opt_f64(&mut details, worker.pressure_disk_io_util_pct, 1);
            details.push_str(", memory_pressure=");
            push_opt_f64(&mut details, worker.pressure_memory_pressure, 2);
            details.push_str(", telemetry_age_secs=");
            push_opt_display(&mut details, worker.pressure_telemetry_age_secs);
            details.push_str(", telemetry_fresh=");
            push_opt_display(&mut details, worker.pressure_telemetry_fresh);

            let mut diagnostic = ReliabilityDiagnostic::new(
                ReliabilityCategory::DiskPressure,
                "worker_disk_pressure",
                severity,
                message,
                code,
            )
            .with_worker(worker.id.clone())
            .with_details(details);

            if severity != ReliabilitySeverity::Pass {
                // Shell-escape worker.user and worker.host: the remediation
                // string is shown verbatim to agents (and frequently
                // copy-pasted into a shell). A workers.toml entry like
                // `host = "evil; rm -rf ~"` MUST NOT produce a runnable
                // destructive command. Each component is escaped
                // independently so the resulting `ssh user@host '...'`
                // shape stays valid even when user / host contain shell
                // metachars.
                let user_q = shell_escape::escape(worker.user.clone().into());
                let host_q = shell_escape::escape(worker.host.clone().into());
                diagnostic = diagnostic.with_remediation(
                    format!(
                        "ssh {user_q}@{host_q} 'df -h / /tmp && du -sh /tmp/rch-* /tmp/rch_target_* 2>/dev/null'",
                    ),
                    "rch status --workers --json",
                );
            }

            diagnostic
        })
        .collect()
}

fn format_disk_free(value: Option<f64>) -> String {
    value
        .map(|gb| format!("{gb:.1} GB free"))
        .unwrap_or_else(|| "free space unknown".to_string())
}

/// t11: Append an `Option<f64>` to `buf` with the given precision, or
/// "unknown" if None. Replaces the prior `.map(|v| format!("{:.N}",
/// v)).unwrap_or_else(|| "unknown".to_string())` pattern which
/// allocated an intermediate String per worker × field.
fn push_opt_f64(buf: &mut String, value: Option<f64>, precision: usize) {
    use std::fmt::Write as _;
    match value {
        Some(v) => {
            let _ = write!(buf, "{v:.precision$}");
        }
        None => buf.push_str("unknown"),
    }
}

/// t11: Append any `Option<T: Display>` to `buf`, or "unknown" if None.
/// Avoids the intermediate `Option::map(|v| v.to_string())` allocation.
fn push_opt_display<T: std::fmt::Display>(buf: &mut String, value: Option<T>) {
    use std::fmt::Write as _;
    match value {
        Some(v) => {
            let _ = write!(buf, "{v}");
        }
        None => buf.push_str("unknown"),
    }
}

fn reliability_process_debt_diagnostics(
    status: Option<&DaemonFullStatusResponse>,
) -> Vec<ReliabilityDiagnostic> {
    let Some(status) = status else {
        return vec![
            ReliabilityDiagnostic::new(
                ReliabilityCategory::ProcessDebt,
                "process_debt",
                ReliabilitySeverity::Warning,
                "Process-debt health is unavailable because daemon status could not be read",
                ReliabilityReasonCode::ProcessDebtUnavailable,
            )
            .with_remediation("rch daemon start", "rch status --jobs --json"),
        ];
    };

    let cancellation = evaluate_cancellation_health(status);
    let severity = match cancellation.status {
        CheckStatus::Pass => ReliabilitySeverity::Pass,
        CheckStatus::Warning => ReliabilitySeverity::Warning,
        CheckStatus::Fail => ReliabilitySeverity::Critical,
        CheckStatus::Skipped => ReliabilitySeverity::Info,
    };
    let mut diagnostic = ReliabilityDiagnostic::new(
        ReliabilityCategory::ProcessDebt,
        "cancellation_cleanup",
        severity,
        cancellation.message,
        match severity {
            ReliabilitySeverity::Pass => ReliabilityReasonCode::CancellationCleanupHealthy,
            ReliabilitySeverity::Info => ReliabilityReasonCode::CancellationCleanupSkipped,
            ReliabilitySeverity::Warning => ReliabilityReasonCode::CancellationCleanupDegraded,
            ReliabilitySeverity::Critical => ReliabilityReasonCode::CancellationCleanupFailed,
        },
    );
    if let Some(details) = cancellation.details {
        diagnostic = diagnostic.with_details(details);
    }
    if let Some(suggestion) = cancellation.suggestion {
        diagnostic = diagnostic.with_remediation(suggestion, "rch status --jobs --json");
    }
    vec![diagnostic]
}

fn reliability_helper_compatibility_diagnostics() -> Vec<ReliabilityDiagnostic> {
    [
        ("ssh", "SSH transport", ReliabilitySeverity::Critical),
        (
            "rsync",
            "incremental transfer",
            ReliabilitySeverity::Critical,
        ),
        ("zstd", "compressed transfer", ReliabilitySeverity::Critical),
        ("cargo", "Rust build fallback", ReliabilitySeverity::Warning),
    ]
    .into_iter()
    .map(|(cmd, description, missing_severity)| {
        // rsync is resolved the way the transfer pipeline resolves it (issue
        // #66): a modern binary in a well-known location beats a legacy PATH
        // one, and the flavour is what decides the argv.
        let rsync = (cmd == "rsync").then(|| {
            let configured = crate::config::load_config()
                .ok()
                .and_then(|config| config.transfer.rsync_bin);
            resolve_rsync(configured.as_deref())
        });
        let available = match &rsync {
            Some(resolution) => resolution.is_ok(),
            None => which(cmd).is_ok(),
        };
        if available {
            let mut diagnostic = ReliabilityDiagnostic::new(
                ReliabilityCategory::HelperCompatibility,
                cmd,
                ReliabilitySeverity::Pass,
                format!("{cmd} is available for {description}"),
                ReliabilityReasonCode::HelperAvailable,
            );
            let details = match &rsync {
                Some(Ok(resolved)) => Some(resolved.describe()),
                _ => command_version(cmd),
            };
            if let Some(details) = details {
                diagnostic = diagnostic.with_details(details);
            }
            diagnostic
        } else {
            ReliabilityDiagnostic::new(
                ReliabilityCategory::HelperCompatibility,
                cmd,
                missing_severity,
                format!("{cmd} is missing; {description} may fail or fall back"),
                ReliabilityReasonCode::HelperMissing,
            )
            .with_remediation(
                format!("Install {cmd} with the system package manager"),
                "rch doctor --reliability --json",
            )
        }
    })
    .collect()
}

fn helper_diagnostics_from_probe_result(
    prefetched: Option<Vec<ReliabilityDiagnostic>>,
    outcome: ProbeOutcome,
) -> Vec<ReliabilityDiagnostic> {
    if let Some(diagnostics) = prefetched {
        return diagnostics;
    }

    vec![
        ReliabilityDiagnostic::new(
            ReliabilityCategory::HelperCompatibility,
            "helper_probe",
            ReliabilitySeverity::Warning,
            "Helper compatibility could not be checked within the probe budget",
            ReliabilityReasonCode::HelperProbeUnavailable,
        )
        .with_details(format!(
            "probe_outcome={} timeout_secs={}",
            outcome.label(),
            PROBE_TIMEOUT.as_secs()
        ))
        .with_remediation(
            "rch doctor --reliability --scope helpers --json",
            "rch doctor --reliability --scope helpers --json",
        ),
    ]
}

/// Build rollout-posture diagnostics from a pre-loaded config snapshot.
///
/// Takes the result of a single `crate::config::load_config()` call shared
/// across every probe in `run_reliability_doctor`, so the doctor pays the
/// TOML-parse cost exactly once per invocation and every probe sees a
/// consistent snapshot even if the config file is rewritten mid-run.
fn reliability_rollout_posture_diagnostics(
    config_load: Result<&rch_common::RchConfig, &str>,
) -> Vec<ReliabilityDiagnostic> {
    let mut diagnostics = Vec::new();

    match config_load {
        Ok(config) => {
            let mut hook_diag = if config.self_healing.hook_starts_daemon {
                ReliabilityDiagnostic::new(
                    ReliabilityCategory::RolloutPosture,
                    "hook_starts_daemon",
                    ReliabilitySeverity::Pass,
                    "Hook auto-start is enabled",
                    ReliabilityReasonCode::HookAutoStartEnabled,
                )
            } else {
                ReliabilityDiagnostic::new(
                    ReliabilityCategory::RolloutPosture,
                    "hook_starts_daemon",
                    ReliabilitySeverity::Warning,
                    "Hook auto-start is disabled; daemon outages may silently force local builds",
                    ReliabilityReasonCode::HookAutoStartDisabled,
                )
                .with_remediation(
                    "rch config set self_healing.hook_starts_daemon true",
                    "rch config get self_healing.hook_starts_daemon --json",
                )
            };
            hook_diag = hook_diag.with_details(format!(
                "cooldown_secs={}, timeout_secs={}",
                config.self_healing.auto_start_cooldown_secs,
                config.self_healing.auto_start_timeout_secs
            ));
            diagnostics.push(hook_diag);

            if config.self_healing.daemon_installs_hooks {
                diagnostics.push(ReliabilityDiagnostic::new(
                    ReliabilityCategory::RolloutPosture,
                    "daemon_installs_hooks",
                    ReliabilitySeverity::Pass,
                    "Daemon hook repair is enabled",
                    ReliabilityReasonCode::DaemonHookRepairEnabled,
                ));
            } else {
                diagnostics.push(
                    ReliabilityDiagnostic::new(
                        ReliabilityCategory::RolloutPosture,
                        "daemon_installs_hooks",
                        ReliabilitySeverity::Warning,
                        "Daemon hook repair is disabled; hook drift may persist",
                        ReliabilityReasonCode::DaemonHookRepairDisabled,
                    )
                    .with_remediation(
                        "rch config set self_healing.daemon_installs_hooks true",
                        "rch config get self_healing.daemon_installs_hooks --json",
                    ),
                );
            }
        }
        Err(err) => diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::RolloutPosture,
                "config_load",
                ReliabilitySeverity::Warning,
                "Configuration could not be loaded; rollout posture is partial",
                ReliabilityReasonCode::ConfigLoadFailed,
            )
            .with_details(err)
            .with_remediation(
                "rch config doctor --json",
                "rch doctor --reliability --json",
            ),
        ),
    }

    diagnostics.push(ReliabilityDiagnostic::new(
        ReliabilityCategory::RolloutPosture,
        "status_surface",
        ReliabilitySeverity::Pass,
        "Unified status surface is compiled in",
        ReliabilityReasonCode::StatusSurfaceAvailable,
    ));
    diagnostics.push(ReliabilityDiagnostic::new(
        ReliabilityCategory::RolloutPosture,
        "repo_convergence_gate",
        ReliabilitySeverity::Pass,
        "Repo-convergence status endpoint is wired into the CLI",
        ReliabilityReasonCode::RepoConvergenceSurfaceAvailable,
    ));
    diagnostics.push(ReliabilityDiagnostic::new(
        ReliabilityCategory::RolloutPosture,
        "disk_pressure_gate",
        ReliabilitySeverity::Pass,
        "Disk-pressure fields are wired into worker status",
        ReliabilityReasonCode::DiskPressureSurfaceAvailable,
    ));

    diagnostics
}

/// Hook/socket drift diagnostics (bd-session-history-remediation-ocv9i.3.3).
///
/// Detects the two silent-fallback drift modes from session history and emits
/// remediation steps the `--fix` executor surfaces with machine-readable
/// outcomes:
/// - the Claude Code PreToolUse `rch` hook is missing (builds never offload);
/// - the configured `general.socket_path` diverges from the canonical daemon
///   socket (the hook cannot reach the daemon).
///
/// Pure over its inputs so it can be exercised against fixtures rather than the
/// real `~/.claude/settings.json`. Both remediations are operator actions
/// (hook install, socket realignment) — they are deliberately NOT auto-applied
/// by `--fix`, which only flips idempotent self-healing config; they surface as
/// `Manual` outcomes with the exact command.
fn reliability_hook_consistency_diagnostics(
    installed_hook_command: Option<&str>,
    config_socket: Option<&str>,
    canonical_socket: &str,
) -> Vec<ReliabilityDiagnostic> {
    let mut diagnostics = Vec::new();

    match installed_hook_command {
        Some(cmd) => diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::RolloutPosture,
                "hook_installed",
                ReliabilitySeverity::Pass,
                "Claude Code PreToolUse rch hook is installed",
                ReliabilityReasonCode::HookInstalled,
            )
            .with_details(format!("hook command: {cmd}")),
        ),
        None => diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::RolloutPosture,
                "hook_installed",
                ReliabilitySeverity::Warning,
                "Claude Code PreToolUse rch hook is missing; builds will not offload",
                ReliabilityReasonCode::HookNotInstalled,
            )
            .with_remediation("rch hook install", "rch hook status --json"),
        ),
    }

    // Socket consistency: the hook/CLI reaches the daemon at the configured
    // socket; if that diverges from the canonical socket the daemon binds by
    // default, the hook silently misses the daemon. An explicitly-matching or
    // absent (=> canonical) config is consistent.
    let socket_consistent = match config_socket {
        None => true,
        Some(configured) => configured.trim() == canonical_socket,
    };
    if socket_consistent {
        diagnostics.push(ReliabilityDiagnostic::new(
            ReliabilityCategory::RolloutPosture,
            "socket_path",
            ReliabilitySeverity::Pass,
            "Configured socket path matches the canonical daemon socket",
            ReliabilityReasonCode::SocketPathConsistent,
        ));
    } else {
        let configured = config_socket.unwrap_or("").trim();
        diagnostics.push(
            ReliabilityDiagnostic::new(
                ReliabilityCategory::RolloutPosture,
                "socket_path",
                ReliabilitySeverity::Warning,
                "Configured socket path diverges from the canonical daemon socket; \
                the hook may not reach the daemon",
                ReliabilityReasonCode::SocketPathMismatch,
            )
            .with_details(format!(
                "configured={configured}, canonical={canonical_socket}"
            ))
            .with_remediation(
                format!("rch config set general.socket_path {canonical_socket}"),
                "rch doctor --reliability --json",
            ),
        );
    }

    diagnostics
}

fn reliability_schema_compatibility_diagnostics() -> Vec<ReliabilityDiagnostic> {
    // Each entry pairs the component's live schema constant with the
    // version this doctor knows how to consume. These expected versions
    // are deliberately separate constants; comparing a schema constant
    // to itself would make this diagnostic permanently green.
    let entries: [(&str, &str, &str, &str); 4] = [
        (
            "doctor_reliability",
            RELIABILITY_DOCTOR_SCHEMA_VERSION,
            EXPECTED_RELIABILITY_DOCTOR_SCHEMA_VERSION,
            "reliability doctor response",
        ),
        (
            "status",
            crate::status_types::STATUS_SCHEMA_VERSION,
            EXPECTED_STATUS_SCHEMA_VERSION,
            "CLI status response",
        ),
        (
            "repo_updater_contract",
            rch_common::REPO_UPDATER_CONTRACT_SCHEMA_VERSION,
            EXPECTED_REPO_UPDATER_CONTRACT_SCHEMA_VERSION,
            "repo updater contract",
        ),
        (
            "process_triage_contract",
            rch_common::e2e::PROCESS_TRIAGE_CONTRACT_SCHEMA_VERSION,
            EXPECTED_PROCESS_TRIAGE_CONTRACT_SCHEMA_VERSION,
            "process triage contract",
        ),
    ];
    entries
        .into_iter()
        .map(|(name, actual, expected, description)| {
            schema_compatibility_diagnostic(name, actual, expected, description)
        })
        .collect()
}

fn schema_compatibility_diagnostic(
    name: &str,
    actual: &str,
    expected: &str,
    description: &str,
) -> ReliabilityDiagnostic {
    if actual == expected {
        ReliabilityDiagnostic::new(
            ReliabilityCategory::SchemaCompatibility,
            name,
            ReliabilitySeverity::Pass,
            format!("{description} schema version is compatible"),
            ReliabilityReasonCode::SchemaCompatible,
        )
        .with_details(format!("schema_version={actual} expected={expected}"))
    } else {
        ReliabilityDiagnostic::new(
            ReliabilityCategory::SchemaCompatibility,
            name,
            ReliabilitySeverity::Critical,
            format!("{description} schema version is incompatible"),
            ReliabilityReasonCode::SchemaIncompatible,
        )
        .with_details(format!("expected={expected}, actual={actual}"))
        .with_remediation(
            "Upgrade rch/rchd/rch-wkr binaries to the same release",
            "rch doctor --reliability --check-schemas --json",
        )
    }
}

/// Reason codes whose presence in the diagnostic list indicates the
/// daemon could not be reached. Each of these is emitted by a probe
/// whose query specifically depends on a live daemon socket — so any
/// one of them implies `daemon_unreachable=true`. (t05)
const DAEMON_UNREACHABLE_REASON_CODES: &[ReliabilityReasonCode] = &[
    ReliabilityReasonCode::DaemonStatusUnavailable,
    ReliabilityReasonCode::DiskPressureUnavailable,
    ReliabilityReasonCode::ProcessDebtUnavailable,
    ReliabilityReasonCode::RepoConvergenceUnavailable,
];

fn build_reliability_doctor_response(
    mode: ReliabilityDoctorMode,
    scope: &ReliabilityScopeSet,
    diagnostics: Vec<ReliabilityDiagnostic>,
) -> ReliabilityDoctorResponse {
    let mut categories = BTreeSet::new();
    let mut pass = 0;
    let mut info = 0;
    let mut warning = 0;
    let mut critical = 0;
    for diagnostic in &diagnostics {
        categories.insert(diagnostic.category);
        match diagnostic.severity {
            ReliabilitySeverity::Pass => pass += 1,
            ReliabilitySeverity::Info => info += 1,
            ReliabilitySeverity::Warning => warning += 1,
            ReliabilitySeverity::Critical => critical += 1,
        }
    }

    // Compute daemon_unreachable + per-probe attribution (t05). Walk
    // the diagnostics list looking for the "this probe needed the
    // daemon but couldn't reach it" reason codes. The reasons list
    // gives operators which specific probe failed.
    let daemon_unreachable_reasons: Vec<String> = diagnostics
        .iter()
        .filter(|d| DAEMON_UNREACHABLE_REASON_CODES.contains(&d.code))
        .map(|d| format!("{}: {}", d.check_name, d.message))
        .collect();
    let daemon_unreachable = !daemon_unreachable_reasons.is_empty();

    let remediation_plan = build_reliability_remediation_plan(&diagnostics);
    let summary = ReliabilityDoctorSummary {
        total_checks: diagnostics.len(),
        pass,
        info,
        warning,
        critical,
        categories_checked: categories.into_iter().collect(),
        overall: aggregate_verdict(&diagnostics),
    };

    ReliabilityDoctorResponse {
        schema_version: RELIABILITY_DOCTOR_SCHEMA_VERSION.to_string(),
        mode,
        scope: scope.as_strings(),
        daemon_unreachable,
        daemon_unreachable_reasons,
        diagnostics,
        summary,
        remediation_plan,
        // `fix_requested` is set by the caller (`collect_reliability_response_once`)
        // from the CLI flags; outcomes are filled by the `--fix` executor.
        fix_requested: false,
        remediation_outcomes: Vec::new(),
    }
}

fn build_reliability_remediation_plan(
    diagnostics: &[ReliabilityDiagnostic],
) -> Vec<ReliabilityRemediationStep> {
    let mut actionable = diagnostics
        .iter()
        .filter(|diagnostic| {
            matches!(
                diagnostic.severity,
                ReliabilitySeverity::Critical | ReliabilitySeverity::Warning
            ) && diagnostic.remediation_command.is_some()
        })
        .collect::<Vec<_>>();

    actionable.sort_by_key(|diagnostic| match diagnostic.severity {
        ReliabilitySeverity::Critical => 0,
        ReliabilitySeverity::Warning => 1,
        ReliabilitySeverity::Info => 2,
        ReliabilitySeverity::Pass => 3,
    });

    actionable
        .into_iter()
        .enumerate()
        .map(|(index, diagnostic)| ReliabilityRemediationStep {
            order: u32::try_from(index + 1).unwrap_or(u32::MAX),
            category: diagnostic.category,
            code: diagnostic.code,
            description: format!("{}: {}", diagnostic.check_name, diagnostic.message),
            command: diagnostic.remediation_command.clone().unwrap_or_default(),
            validation: diagnostic
                .validation_check
                .clone()
                .unwrap_or_else(|| "rch doctor --reliability --json".to_string()),
            requires_restart: diagnostic.code.requires_restart(),
            dry_run_safe: diagnostic.dry_run_safe,
            auto_fixable: auto_config_flip(diagnostic.code).is_some(),
        })
        .collect()
}

/// Execute the `--fix` remediation pass over a collected response, populating
/// `response.remediation_outcomes`.
///
/// Behaviour by (intent × execute) — see [`RemediationOutcomeStatus`]:
/// - `fix_requested == false`: no-op (Check / plain DryRun stay read-only).
/// - `mode == DryRun` (i.e. `--fix --dry-run`): preview only — every auto step
///   is `WouldApply`, nothing is written to disk.
/// - `mode == Fix`: apply each idempotent config flip (`Applied` /
///   `AlreadySatisfied` / `Failed`); manual steps are reported `Manual`.
///
/// Config is loaded once up front to recognise already-satisfied flips so a
/// re-run is a clean idempotent no-op. Every step is emitted as a structured
/// `rch::doctor::remediation` tracing event for post-incident forensics.
fn apply_reliability_remediations(response: &mut ReliabilityDoctorResponse) {
    if !response.fix_requested {
        return;
    }
    let preview = matches!(response.mode, ReliabilityDoctorMode::DryRun);

    // Snapshot current config to short-circuit already-satisfied flips. A load
    // failure doesn't abort the pass — we just can't detect no-ops, so an
    // otherwise-satisfied flip is re-applied (still idempotent on disk).
    let current = crate::config::load_config().ok();

    let mut outcomes = Vec::with_capacity(response.remediation_plan.len());
    for step in &response.remediation_plan {
        let started = Instant::now();
        let outcome = match auto_config_flip(step.code) {
            Some(flip) => {
                let already = current
                    .as_ref()
                    .is_some_and(|cfg| config_flip_satisfied(cfg, flip));
                let command = format!("rch config set {} {}", flip.key, flip.value);
                let (status, detail) = match plan_auto_flip(already, preview) {
                    AutoFlipPlan::AlreadySatisfied => {
                        (RemediationOutcomeStatus::AlreadySatisfied, None)
                    }
                    AutoFlipPlan::WouldApply => (
                        RemediationOutcomeStatus::WouldApply,
                        Some(format!("would set {} = {}", flip.key, flip.value)),
                    ),
                    AutoFlipPlan::Apply => {
                        match crate::commands::default_config_path().and_then(|path| {
                            crate::commands::apply_config_set(&path, flip.key, flip.value)
                        }) {
                            Ok(()) => (
                                RemediationOutcomeStatus::Applied,
                                Some(format!("set {} = {}", flip.key, flip.value)),
                            ),
                            Err(e) => (RemediationOutcomeStatus::Failed, Some(e.to_string())),
                        }
                    }
                };
                ReliabilityRemediationOutcome {
                    order: step.order,
                    code: step.code,
                    description: step.description.clone(),
                    command,
                    status,
                    detail,
                }
            }
            None => ReliabilityRemediationOutcome {
                order: step.order,
                code: step.code,
                description: step.description.clone(),
                command: step.command.clone(),
                status: RemediationOutcomeStatus::Manual,
                detail: None,
            },
        };

        tracing::info!(
            target: "rch::doctor::remediation",
            order = outcome.order,
            code = outcome.code.code(),
            status = outcome.status.label(),
            duration_seconds = started.elapsed().as_secs_f64(),
            preview,
            command = %outcome.command,
            detail = outcome.detail.as_deref().unwrap_or(""),
            "doctor.remediation.step",
        );
        outcomes.push(outcome);
    }

    response.remediation_outcomes = outcomes;
}

fn print_reliability_doctor_response(ctx: &OutputContext, response: &ReliabilityDoctorResponse) {
    let style = ctx.theme();

    println!("{}", style.format_header("RCH Reliability Doctor"));
    println!();

    // t05: daemon-unreachable prefix so the operator immediately sees
    // the limited scope of this report. Suppressed in JSON mode where
    // the envelope's data.daemon_unreachable flag carries the same
    // signal for machine consumers.
    if response.daemon_unreachable && !ctx.is_json() {
        println!(
            "  {} [daemon down — local-only checks]",
            StatusIndicator::Warning.display(style)
        );
    }

    println!(
        "  {} schema {}",
        StatusIndicator::Info.display(style),
        style.value(&response.schema_version)
    );
    let verdict_indicator = match response.summary.overall {
        ReliabilityVerdict::Healthy => StatusIndicator::Success,
        ReliabilityVerdict::Degraded => StatusIndicator::Warning,
        ReliabilityVerdict::Failing => StatusIndicator::Error,
    };
    println!(
        "  {} verdict: {} ({} check(s): {} pass, {} info, {} warning, {} critical)",
        verdict_indicator.display(style),
        style.highlight(response.summary.overall.label()),
        response.summary.total_checks,
        response.summary.pass,
        response.summary.info,
        response.summary.warning,
        response.summary.critical
    );
    println!();

    for diagnostic in &response.diagnostics {
        let indicator = match diagnostic.severity {
            ReliabilitySeverity::Pass => StatusIndicator::Success,
            ReliabilitySeverity::Info => StatusIndicator::Info,
            ReliabilitySeverity::Warning => StatusIndicator::Warning,
            ReliabilitySeverity::Critical => StatusIndicator::Error,
        };
        println!(
            "  {} [{}] {}: {}",
            indicator.display(style),
            diagnostic.category.as_str(),
            style.highlight(&diagnostic.check_name),
            diagnostic.message
        );
        if ctx.is_verbose() {
            if let Some(details) = &diagnostic.details {
                println!("      {}", style.muted(details));
            }
            if let Some(command) = &diagnostic.remediation_command {
                println!("      remediation: {}", style.value(command));
            }
        }
    }

    if !response.remediation_plan.is_empty() {
        println!();
        println!("{}", style.format_header("Remediation Plan"));
        for step in &response.remediation_plan {
            let auto = if step.auto_fixable {
                style.success(" [auto-fixable]")
            } else {
                style.muted(" [manual]")
            };
            println!(
                "  {}. [{}] {}{}",
                step.order,
                step.category.as_str(),
                step.description,
                auto
            );
            println!("     {}", style.value(&step.command));
            println!("     validate: {}", style.value(&step.validation));
        }
    }

    if !response.remediation_outcomes.is_empty() {
        println!();
        let header = match response.mode {
            ReliabilityDoctorMode::DryRun => "Fix Preview (--fix --dry-run, no changes applied)",
            _ => "Fix Results",
        };
        println!("{}", style.format_header(header));
        for outcome in &response.remediation_outcomes {
            let indicator = match outcome.status {
                RemediationOutcomeStatus::Applied | RemediationOutcomeStatus::AlreadySatisfied => {
                    StatusIndicator::Success
                }
                RemediationOutcomeStatus::WouldApply => StatusIndicator::Info,
                RemediationOutcomeStatus::Manual => StatusIndicator::Warning,
                RemediationOutcomeStatus::Failed => StatusIndicator::Error,
            };
            println!(
                "  {} {}. {} — {}",
                indicator.display(style),
                outcome.order,
                style.highlight(outcome.status.label()),
                outcome.description
            );
            if let Some(detail) = &outcome.detail {
                println!("     {}", style.muted(detail));
            }
        }
    }

    println!();
    if response.summary.critical > 0 {
        println!(
            "{}",
            style.format_error("Reliability-critical issues found.")
        );
    } else if response.summary.warning > 0 {
        println!(
            "{}",
            style.format_warning("Reliability checks found warnings.")
        );
    } else {
        println!("{}", style.format_success("Reliability checks passed."));
    }

    // t05: meta footer for first-time operators — only in human mode
    // (verbose or default). Hook/JSON modes get the same info via the
    // envelope and the --schema endpoint.
    if !ctx.is_json() {
        println!();
        println!(
            "  {} Run with {} for machine-readable output",
            StatusIndicator::Info.display(style),
            style.value("--json")
        );
        println!(
            "  {} Exit codes: 0 = healthy, 1 = degraded, 2 = failing (with --strict: degraded → 2; with --lenient: failing → 1)",
            StatusIndicator::Info.display(style),
        );
    }
}

/// Quick health check result for post-hook-install display.
///
/// **t03 contract change:** `workers_healthy` is `Option<usize>` — `None`
/// means "not probed / unknown", explicitly distinguishing the "fast
/// check, no network probes" case from the "every worker is healthy"
/// case. Prior shape unconditionally returned `Some(worker_count)`
/// without probing, which silently treated unhealthy fleets as healthy.
/// `is_healthy()` now requires `workers_healthy == Some(worker_count)`
/// — `None` is NEVER reported as healthy.
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub struct QuickCheckResult {
    pub daemon_running: bool,
    pub worker_count: usize,
    /// `None` = not probed (the default for `run_quick_check`, which is
    /// designed to be fast / no-network).
    /// `Some(n)` = `n` of the configured workers were probed and reported
    /// healthy.
    pub workers_healthy: Option<usize>,
    pub hook_installed: bool,
    pub warnings: Vec<String>,
    pub errors: Vec<String>,
}

impl QuickCheckResult {
    /// Check if the system is fully operational.
    ///
    /// **Contract:** returns `true` ONLY when daemon is running, hook is
    /// installed, warnings/errors are empty, AND every configured worker
    /// has been probed and reported healthy. `workers_healthy == None`
    /// (unknown) is NEVER healthy — this is the default-to-degraded
    /// discipline per t03's bead body.
    pub fn is_healthy(&self) -> bool {
        self.daemon_running
            && self.worker_count > 0
            && self.hook_installed
            && self.warnings.is_empty()
            && self.errors.is_empty()
            && self.workers_healthy == Some(self.worker_count)
    }

    /// Check if there are any issues.
    #[allow(dead_code)]
    pub fn has_issues(&self) -> bool {
        !self.warnings.is_empty() || !self.errors.is_empty()
    }
}

/// Run a quick health check (for post-install feedback).
///
/// This runs fast local-only checks (no network probes). Worker health
/// is reported as `None` (unknown) — callers needing real worker
/// probes should run `rch doctor --reliability` (which performs the
/// SSH-based health checks). This honest "unknown" signal is the t03
/// fix for the prior default-to-success behavior that silently treated
/// every configured worker as healthy.
pub fn run_quick_check() -> QuickCheckResult {
    let socket_path = configured_or_default_socket_path();
    let daemon_running = socket_path.exists() && daemon_socket_accepts_connections(&socket_path);

    // Check workers — fast check only counts configured entries; we do
    // NOT probe each worker over the network here (that's `rch doctor
    // --reliability`'s job). Health is reported as `None` (unknown)
    // since we genuinely don't know without probing.
    let (worker_count, workers_healthy) = match load_workers_from_config() {
        // Fast-check: count configured workers; health is unknown
        // until a real probe is performed (default-to-degraded discipline).
        Ok(workers) => (workers.len(), None),
        Err(_) => (0, None),
    };

    // Check hook
    let hook_installed = {
        let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("/tmp"));
        let settings_path = home.join(".claude").join("settings.json");
        if settings_path.exists() {
            read_config_capped(&settings_path)
                .ok()
                .and_then(|content| serde_json::from_str::<serde_json::Value>(&content).ok())
                .map(|settings| {
                    settings
                        .get("hooks")
                        .and_then(|h| h.get("PreToolUse"))
                        .is_some()
                })
                .unwrap_or(false)
        } else {
            false
        }
    };

    // Collect warnings
    let mut warnings = Vec::new();
    let mut errors = Vec::new();

    if !daemon_running {
        warnings.push("Daemon is not running".to_string());
    }
    if worker_count == 0 {
        warnings.push("No workers configured".to_string());
    }
    if !hook_installed {
        errors.push("Hook not installed".to_string());
    }
    // Honest signal that this is a fast-check, not a real probe.
    if worker_count > 0 && workers_healthy.is_none() {
        warnings.push(
            "Worker health not probed by quick-check; run `rch doctor --reliability` for full status".to_string(),
        );
    }

    let result = QuickCheckResult {
        daemon_running,
        worker_count,
        workers_healthy,
        hook_installed,
        warnings,
        errors,
    };

    tracing::debug!(
        target: "rch::doctor::quick_check",
        daemon_running,
        worker_count,
        workers_healthy = ?result.workers_healthy,
        hook_installed,
        is_healthy = result.is_healthy(),
        "doctor.quick_check.complete",
    );

    result
}

/// Print a quick health check summary to the console.
pub fn print_quick_check_summary(result: &QuickCheckResult, ctx: &OutputContext) {
    let style = ctx.theme();

    println!();
    println!("{}", style.highlight("Quick Health Check"));
    println!();

    // Daemon status
    if result.daemon_running {
        println!(
            "  {} Daemon running",
            StatusIndicator::Success.display(style)
        );
    } else {
        println!(
            "  {} Daemon not running",
            StatusIndicator::Warning.display(style)
        );
    }

    // Workers status
    if result.worker_count > 0 {
        println!(
            "  {} {} worker(s) configured",
            StatusIndicator::Success.display(style),
            result.worker_count
        );
    } else {
        println!(
            "  {} No workers configured",
            StatusIndicator::Warning.display(style)
        );
    }

    // Hook status
    if result.hook_installed {
        println!(
            "  {} Hook installed",
            StatusIndicator::Success.display(style)
        );
    } else {
        println!(
            "  {} Hook not installed",
            StatusIndicator::Error.display(style)
        );
    }

    println!();

    // Summary
    if result.is_healthy() {
        println!(
            "{}",
            style.format_success("Setup complete! Your next cargo build will compile remotely.")
        );
    } else if !result.errors.is_empty() {
        println!(
            "{}",
            style.format_error(&format!(
                "Issues found: {} error(s). Run 'rch doctor' for details.",
                result.errors.len()
            ))
        );
    } else if !result.warnings.is_empty() {
        println!(
            "{}",
            style.format_warning(&format!(
                "Setup complete with {} warning(s). Run 'rch doctor' for details.",
                result.warnings.len()
            ))
        );
    }
}

// =============================================================================
// Prerequisite Checks
// =============================================================================

fn check_prerequisites(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    _options: &DoctorOptions,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Prerequisites"));
        println!();
    }

    // Check rsync (issue #66): presence is not enough — a stock macOS
    // `/usr/bin/rsync` is openrsync, which rejects the rsync 3.x flags rch
    // prefers. Resolve exactly the way the transfer pipeline does and gate on
    // the probed flavour.
    let configured_rsync_bin = crate::config::load_config()
        .ok()
        .and_then(|config| config.transfer.rsync_bin);
    let rsync_result = classify_rsync_check(resolve_rsync(configured_rsync_bin.as_deref()));
    print_check_result(&rsync_result, ctx);
    checks.push(rsync_result);

    // Check zstd
    let zstd_result = check_command_exists("zstd", "Compression tool");
    print_check_result(&zstd_result, ctx);
    checks.push(zstd_result);

    // Check ssh
    let ssh_result = check_command_exists("ssh", "SSH client");
    print_check_result(&ssh_result, ctx);
    checks.push(ssh_result);

    // Check rustup
    let rustup_result = check_command_exists("rustup", "Rust toolchain manager");
    print_check_result(&rustup_result, ctx);
    checks.push(rustup_result);

    // Check cargo
    let cargo_result = check_command_exists("cargo", "Rust build tool");
    print_check_result(&cargo_result, ctx);
    checks.push(cargo_result);

    if !ctx.is_json() {
        println!();
    }
}

/// Platform-specific way to get a modern (3.x) rsync.
fn modern_rsync_install_hint() -> &'static str {
    if cfg!(target_os = "macos") {
        "brew install rsync (rch prefers /opt/homebrew/bin/rsync over the stock openrsync automatically)"
    } else {
        "install rsync 3.x with your package manager (e.g. apt install rsync)"
    }
}

/// Turn an rsync resolution into the `prerequisites/rsync` doctor check.
///
/// - modern rsync (3.1+): pass, details name the binary and flavour;
/// - openrsync / rsync 2.6.9: pass in compatibility mode, with the exact
///   remedy as the hint (the compatibility argv works but loses zstd
///   compression, cumulative progress, and the zero-build-output proof);
/// - unrecognized `--version` banner: warning (rch assumes the 3.x argv);
/// - older than 2.6.9, missing, misconfigured, or unable to run: fail.
fn classify_rsync_check(resolution: Result<ResolvedRsync, RsyncResolveError>) -> CheckResult {
    let result = |status: CheckStatus,
                  message: String,
                  details: Option<String>,
                  suggestion: Option<String>| {
        CheckResult {
            category: "prerequisites".to_string(),
            name: "rsync".to_string(),
            status,
            message,
            details,
            suggestion,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }
    };
    let resolved = match resolution {
        Ok(resolved) => resolved,
        Err(error @ RsyncResolveError::NotFound) => {
            return result(
                CheckStatus::Fail,
                "File synchronization not found".to_string(),
                Some(error.to_string()),
                Some(format!("Install rsync: {}", modern_rsync_install_hint())),
            );
        }
        Err(error @ RsyncResolveError::OverrideMissing { origin, .. }) => {
            return result(
                CheckStatus::Fail,
                "configured rsync binary is not executable".to_string(),
                Some(error.to_string()),
                Some(format!(
                    "Fix or unset {origin} so rch can pick a binary; to get a modern rsync: {}",
                    modern_rsync_install_hint()
                )),
            );
        }
        Err(error @ RsyncResolveError::ProbeFailed { .. }) => {
            return result(
                CheckStatus::Fail,
                "rsync is present but `rsync --version` failed".to_string(),
                Some(error.to_string()),
                Some(format!("Reinstall rsync: {}", modern_rsync_install_hint())),
            );
        }
    };

    let flavor = resolved.flavor;
    let capabilities = resolved.capabilities();
    let details = if resolved.version_line.is_empty() {
        resolved.describe()
    } else {
        format!("{} — {}", resolved.describe(), resolved.version_line)
    };
    if flavor == RsyncFlavor::Unknown {
        return result(
            CheckStatus::Warning,
            "rsync flavour could not be determined from `rsync --version`".to_string(),
            Some(details),
            Some(format!(
                "rch will use the rsync 3.x argv; if transfers fail with `unrecognized option`, \
                 set [transfer] rsync_bin (or RCH_RSYNC_BIN) to a modern rsync: {}",
                modern_rsync_install_hint()
            )),
        );
    }
    if !flavor.is_supported() {
        let (major, minor, patch) = rch_common::rsync_flavor::MIN_SUPPORTED_RSYNC;
        return result(
            CheckStatus::Fail,
            format!("{flavor} is too old (rch needs rsync {major}.{minor}.{patch} or newer)"),
            Some(details),
            Some(format!("Upgrade rsync: {}", modern_rsync_install_hint())),
        );
    }
    if capabilities.is_compatibility_mode() {
        // Name exactly the flags this binary lacks (rsync 3.0.x keeps
        // `--append-verify`; openrsync and 2.6.9 lose everything).
        let mut rejected = vec!["`--info=*`"];
        if !capabilities.compress_choice {
            rejected.push("`--compress-choice=zstd`");
        }
        if !capabilities.append_verify {
            rejected.push("`--append-verify`");
        }
        let compression = if capabilities.compress_choice {
            "zstd compression"
        } else {
            "zlib compression"
        };
        return result(
            CheckStatus::Pass,
            format!("File synchronization is installed ({flavor}, compatibility mode)"),
            Some(details),
            Some(format!(
                "{flavor} rejects {}; rch drives it with `--progress --stats -vv` and {compression}, \
                 and the zero-build-output detector fails open. For full-speed transfers and \
                 diagnostics: {}",
                rejected.join(", "),
                modern_rsync_install_hint()
            )),
        );
    }
    result(
        CheckStatus::Pass,
        "File synchronization is installed".to_string(),
        Some(details),
        None,
    )
}

fn check_command_exists(cmd: &str, description: &str) -> CheckResult {
    let exists = which(cmd).is_ok();
    let version = exists.then(|| command_version(cmd)).flatten();

    CheckResult {
        category: "prerequisites".to_string(),
        name: cmd.to_string(),
        status: if exists {
            CheckStatus::Pass
        } else {
            CheckStatus::Fail
        },
        message: if exists {
            format!("{} is installed", description)
        } else {
            format!("{} not found", description)
        },
        details: version,
        suggestion: if exists {
            None
        } else {
            Some(format!("Install {} using your package manager", cmd))
        },
        fixable: !exists,
        fix_applied: false,
        fix_message: None,
    }
}

/// Run `<cmd> <version-flag>` with a hard timeout and capture the first
/// non-empty line of output. A misbehaving rustup proxy or cargo waiting
/// on the network MUST NOT hang doctor forever; without a timeout
/// `--version` could block on a stalled credential prompt or registry
/// fetch (rustup updates, in particular). Default cap: 5 seconds.
fn command_version(cmd: &str) -> Option<String> {
    use std::process::Stdio;
    use std::time::{Duration, Instant};

    let (program, mut command) = match cmd {
        "rsync" => {
            let mut command = Command::new("rsync");
            command.arg("--version");
            ("rsync", command)
        }
        "zstd" => {
            let mut command = Command::new("zstd");
            command.arg("--version");
            ("zstd", command)
        }
        "ssh" => {
            let mut command = Command::new("ssh");
            command.arg("-V");
            ("ssh", command)
        }
        "rustup" => {
            let mut command = Command::new("rustup");
            command.arg("--version");
            ("rustup", command)
        }
        "cargo" => {
            let mut command = Command::new("cargo");
            command.arg("--version");
            ("cargo", command)
        }
        _ => return None,
    };

    let timeout = Duration::from_secs(5);
    let mut child = command
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .ok()?;

    let started = Instant::now();
    // Poll every 50ms instead of waiting forever on `child.wait()`.
    // For most healthy `--version` invocations this loop exits on the
    // first poll (subprocess returns instantly).
    let exited = loop {
        match child.try_wait() {
            Ok(Some(status)) => break Some(status),
            Ok(None) => {
                if started.elapsed() >= timeout {
                    break None;
                }
                std::thread::sleep(Duration::from_millis(50));
            }
            Err(_) => return None,
        }
    };

    if exited.is_none() {
        // Timed out — kill the child and return None. A logged warning
        // helps diagnose flaky workers without breaking the doctor.
        let _ = child.kill();
        let _ = child.wait();
        tracing::warn!(
            target: "rch::doctor",
            cmd = %program,
            timeout_secs = timeout.as_secs(),
            "version-probe subprocess timed out; killed"
        );
        return None;
    }

    // Drain stdout + stderr; child has exited so reads should not block.
    let output = child.wait_with_output().ok()?;
    let stdout = String::from_utf8_lossy(&output.stdout);
    let stderr = String::from_utf8_lossy(&output.stderr);
    let text = if stdout.trim().is_empty() {
        stderr.as_ref()
    } else {
        stdout.as_ref()
    };
    text.lines()
        .map(str::trim)
        .find(|line| !line.is_empty())
        .map(str::to_string)
}

// =============================================================================
// Configuration Checks
// =============================================================================

fn check_configuration(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    _options: &DoctorOptions,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Configuration"));
        println!();
    }

    // Check config directory
    let config_dir_result = check_config_directory();
    print_check_result(&config_dir_result, ctx);
    checks.push(config_dir_result);

    // Check config.toml
    let config_result = check_config_file();
    print_check_result(&config_result, ctx);
    checks.push(config_result);

    // Check workers.toml
    let workers_result = check_workers_file();
    print_check_result(&workers_result, ctx);
    checks.push(workers_result);

    // Check remediation knobs (bd-...remediation-ocv9i.17.2) so `rch doctor`
    // — including the installer/easy-mode post-install run — surfaces unsafe or
    // contradictory [remediation] settings rather than letting them drift.
    for result in check_remediation_results() {
        print_check_result(&result, ctx);
        checks.push(result);
    }

    if !ctx.is_json() {
        println!();
    }
}

/// Validate the central remediation knobs (bd-...remediation-ocv9i.17.2).
///
/// Returns one `Pass` when the `[remediation]` section is valid (defaults apply
/// where unset), or one check per `RemediationConfig::validate()` finding with a
/// concrete suggestion. Config-load failures are reported by the config checks,
/// so this stays silent in that case.
fn check_remediation_results() -> Vec<CheckResult> {
    let Ok(config) = crate::config::load_config() else {
        return Vec::new();
    };
    let issues = config.remediation.validate();
    if issues.is_empty() {
        return vec![CheckResult {
            category: "configuration".to_string(),
            name: "remediation_config".to_string(),
            status: CheckStatus::Pass,
            message: "Remediation settings valid".to_string(),
            details: Some(
                "[remediation] knobs within safe ranges (defaults apply where unset)".to_string(),
            ),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }];
    }
    issues
        .into_iter()
        .map(|issue| {
            let status = match issue.severity {
                rch_common::remediation_config::IssueSeverity::Error => CheckStatus::Fail,
                rch_common::remediation_config::IssueSeverity::Warning => CheckStatus::Warning,
            };
            CheckResult {
                category: "configuration".to_string(),
                name: "remediation_config".to_string(),
                status,
                message: format!("{}: {}", issue.field, issue.message),
                details: None,
                suggestion: Some(format!(
                    "Adjust `{}` under [remediation] (or the matching RCH_REMEDIATION_* env var)",
                    issue.field
                )),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            }
        })
        .collect()
}

fn check_config_directory() -> CheckResult {
    match config_dir() {
        Some(dir) => {
            if dir.exists() {
                CheckResult {
                    category: "configuration".to_string(),
                    name: "config_directory".to_string(),
                    status: CheckStatus::Pass,
                    message: "Config directory exists".to_string(),
                    details: Some(dir.display().to_string()),
                    suggestion: None,
                    fixable: false,
                    fix_applied: false,
                    fix_message: None,
                }
            } else {
                CheckResult {
                    category: "configuration".to_string(),
                    name: "config_directory".to_string(),
                    status: CheckStatus::Warning,
                    message: "Config directory does not exist".to_string(),
                    details: Some(dir.display().to_string()),
                    suggestion: Some("Run 'rch config init' to create it".to_string()),
                    fixable: true,
                    fix_applied: false,
                    fix_message: None,
                }
            }
        }
        None => CheckResult {
            category: "configuration".to_string(),
            name: "config_directory".to_string(),
            status: CheckStatus::Fail,
            message: "Could not determine config directory".to_string(),
            details: None,
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        },
    }
}

fn check_config_file() -> CheckResult {
    let config_path = match config_dir() {
        Some(d) => d.join("config.toml"),
        None => {
            return CheckResult {
                category: "configuration".to_string(),
                name: "config.toml".to_string(),
                status: CheckStatus::Skipped,
                message: "Skipped (no config directory)".to_string(),
                details: None,
                suggestion: None,
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
        }
    };

    if !config_path.exists() {
        return CheckResult {
            category: "configuration".to_string(),
            name: "config.toml".to_string(),
            status: CheckStatus::Warning,
            message: "config.toml not found (using defaults)".to_string(),
            details: Some(config_path.display().to_string()),
            suggestion: Some("Run 'rch config init' to create default config".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        };
    }

    match read_config_capped(&config_path) {
        Ok(content) => match toml::from_str::<toml::Value>(&content) {
            Ok(_) => CheckResult {
                category: "configuration".to_string(),
                name: "config.toml".to_string(),
                status: CheckStatus::Pass,
                message: "config.toml is valid".to_string(),
                details: Some(config_path.display().to_string()),
                suggestion: None,
                fixable: false,
                fix_applied: false,
                fix_message: None,
            },
            Err(e) => CheckResult {
                category: "configuration".to_string(),
                name: "config.toml".to_string(),
                status: CheckStatus::Fail,
                message: "config.toml has syntax errors".to_string(),
                details: Some(e.to_string()),
                suggestion: Some("Fix TOML syntax errors in config file".to_string()),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            },
        },
        Err(e) => CheckResult {
            category: "configuration".to_string(),
            name: "config.toml".to_string(),
            status: CheckStatus::Fail,
            message: "Could not read config.toml".to_string(),
            details: Some(e.to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        },
    }
}

fn check_workers_file() -> CheckResult {
    let workers_path = match config_dir() {
        Some(d) => d.join("workers.toml"),
        None => {
            return CheckResult {
                category: "configuration".to_string(),
                name: "workers.toml".to_string(),
                status: CheckStatus::Skipped,
                message: "Skipped (no config directory)".to_string(),
                details: None,
                suggestion: None,
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
        }
    };

    if !workers_path.exists() {
        return CheckResult {
            category: "configuration".to_string(),
            name: "workers.toml".to_string(),
            status: CheckStatus::Fail,
            message: "workers.toml not found".to_string(),
            details: Some(workers_path.display().to_string()),
            suggestion: Some("Run 'rch config init' to create example workers config".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        };
    }

    match read_config_capped(&workers_path) {
        Ok(content) => match toml::from_str::<toml::Value>(&content) {
            Ok(parsed) => {
                let worker_count = parsed
                    .get("workers")
                    .and_then(|w| w.as_array())
                    .map(|a| a.len())
                    .unwrap_or(0);

                if worker_count == 0 {
                    CheckResult {
                        category: "configuration".to_string(),
                        name: "workers.toml".to_string(),
                        status: CheckStatus::Warning,
                        message: "workers.toml is valid but has no workers defined".to_string(),
                        details: Some(workers_path.display().to_string()),
                        suggestion: Some("Add worker definitions to workers.toml".to_string()),
                        fixable: false,
                        fix_applied: false,
                        fix_message: None,
                    }
                } else {
                    CheckResult {
                        category: "configuration".to_string(),
                        name: "workers.toml".to_string(),
                        status: CheckStatus::Pass,
                        message: format!("workers.toml is valid ({} workers)", worker_count),
                        details: Some(workers_path.display().to_string()),
                        suggestion: None,
                        fixable: false,
                        fix_applied: false,
                        fix_message: None,
                    }
                }
            }
            Err(e) => CheckResult {
                category: "configuration".to_string(),
                name: "workers.toml".to_string(),
                status: CheckStatus::Fail,
                message: "workers.toml has syntax errors".to_string(),
                details: Some(e.to_string()),
                suggestion: Some("Fix TOML syntax errors in workers file".to_string()),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            },
        },
        Err(e) => CheckResult {
            category: "configuration".to_string(),
            name: "workers.toml".to_string(),
            status: CheckStatus::Fail,
            message: "Could not read workers.toml".to_string(),
            details: Some(e.to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        },
    }
}

// =============================================================================
// SSH Key Checks
// =============================================================================

fn check_ssh_keys(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
    fixes_applied: &mut Vec<FixApplied>,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("SSH Keys"));
        println!();
    }

    // Check common SSH key locations
    let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("/tmp"));
    let ssh_dir = home.join(".ssh");

    let key_files = vec![
        ssh_dir.join("id_ed25519"),
        ssh_dir.join("id_rsa"),
        ssh_dir.join("id_ecdsa"),
    ];

    let mut found_key = false;

    for key_path in key_files {
        if key_path.exists() {
            found_key = true;
            let result = check_ssh_key_permissions(&key_path, options, fixes_applied);
            print_check_result(&result, ctx);
            checks.push(result);
        }
    }

    if !found_key {
        let default_key = ssh_dir.join("id_ed25519");
        let result = CheckResult {
            category: "ssh".to_string(),
            name: "ssh_keys".to_string(),
            status: CheckStatus::Warning,
            message: "No standard SSH keys found".to_string(),
            details: Some("Checked: ~/.ssh/id_{ed25519,rsa,ecdsa}".to_string()),
            suggestion: Some(format!(
                "Generate an SSH key: ssh-keygen -t ed25519 -f {} && ssh-add {}",
                default_key.display(),
                default_key.display()
            )),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
        print_check_result(&result, ctx);
        checks.push(result);
    }

    // Check worker identity files from config
    check_worker_identity_files(checks, ctx, options, fixes_applied);

    // Check SSH config
    let ssh_config_result = check_ssh_config();
    print_check_result(&ssh_config_result, ctx);
    checks.push(ssh_config_result);

    if !ctx.is_json() {
        println!();
    }
}

#[cfg(unix)]
fn check_ssh_key_permissions(
    key_path: &Path,
    options: &DoctorOptions,
    fixes_applied: &mut Vec<FixApplied>,
) -> CheckResult {
    let key_name = key_path
        .file_name()
        .map(|n| n.to_string_lossy().to_string())
        .unwrap_or_else(|| "unknown".to_string());

    match std::fs::metadata(key_path) {
        Ok(meta) => {
            let mode = meta.permissions().mode();
            let perms = mode & 0o777;

            // SSH keys should be 0600 or 0400
            if perms == 0o600 || perms == 0o400 {
                CheckResult {
                    category: "ssh".to_string(),
                    name: key_name,
                    status: CheckStatus::Pass,
                    message: format!("SSH key exists with correct permissions (0{:o})", perms),
                    details: Some(key_path.display().to_string()),
                    suggestion: None,
                    fixable: false,
                    fix_applied: false,
                    fix_message: None,
                }
            } else {
                // Try to fix if requested
                if options.fix {
                    if options.dry_run {
                        return CheckResult {
                            category: "ssh".to_string(),
                            name: key_name,
                            status: CheckStatus::Warning,
                            message: format!("SSH key has loose permissions (0{:o})", perms),
                            details: Some(key_path.display().to_string()),
                            suggestion: Some(format!("Run: chmod 600 {}", key_path.display())),
                            fixable: true,
                            fix_applied: false,
                            fix_message: Some(format!(
                                "Would change permissions from 0{:o} to 0600",
                                perms
                            )),
                        };
                    }
                    match std::fs::set_permissions(key_path, std::fs::Permissions::from_mode(0o600))
                    {
                        Ok(()) => {
                            fixes_applied.push(FixApplied {
                                check_name: key_name.clone(),
                                action: format!("Changed permissions from 0{:o} to 0600", perms),
                                success: true,
                                error: None,
                            });
                            CheckResult {
                                category: "ssh".to_string(),
                                name: key_name,
                                status: CheckStatus::Pass,
                                message: "SSH key permissions fixed to 0600".to_string(),
                                details: Some(key_path.display().to_string()),
                                suggestion: None,
                                fixable: false,
                                fix_applied: true,
                                fix_message: Some(format!(
                                    "Changed permissions from 0{:o} to 0600",
                                    perms
                                )),
                            }
                        }
                        Err(e) => {
                            fixes_applied.push(FixApplied {
                                check_name: key_name.clone(),
                                action: "Failed to fix permissions".to_string(),
                                success: false,
                                error: Some(e.to_string()),
                            });
                            CheckResult {
                                category: "ssh".to_string(),
                                name: key_name,
                                status: CheckStatus::Warning,
                                message: format!(
                                    "SSH key has loose permissions (0{:o}), fix failed",
                                    perms
                                ),
                                details: Some(e.to_string()),
                                suggestion: Some(format!("Run: chmod 600 {}", key_path.display())),
                                fixable: true,
                                fix_applied: false,
                                fix_message: Some(format!("Failed to fix permissions: {}", e)),
                            }
                        }
                    }
                } else {
                    CheckResult {
                        category: "ssh".to_string(),
                        name: key_name,
                        status: CheckStatus::Warning,
                        message: format!("SSH key has loose permissions (0{:o})", perms),
                        details: Some(key_path.display().to_string()),
                        suggestion: Some(format!("Run: chmod 600 {}", key_path.display())),
                        fixable: true,
                        fix_applied: false,
                        fix_message: None,
                    }
                }
            }
        }
        Err(e) => CheckResult {
            category: "ssh".to_string(),
            name: key_name,
            status: CheckStatus::Fail,
            message: "Could not read SSH key metadata".to_string(),
            details: Some(e.to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        },
    }
}

#[cfg(not(unix))]
fn check_ssh_key_permissions(
    key_path: &Path,
    _options: &DoctorOptions,
    _fixes_applied: &mut Vec<FixApplied>,
) -> CheckResult {
    let key_name = key_path
        .file_name()
        .map(|n| n.to_string_lossy().to_string())
        .unwrap_or_else(|| "unknown".to_string());

    CheckResult {
        category: "ssh".to_string(),
        name: key_name,
        status: CheckStatus::Skipped,
        message: "SSH key permission checks are not supported on this platform".to_string(),
        details: Some(key_path.display().to_string()),
        suggestion: None,
        fixable: false,
        fix_applied: false,
        fix_message: None,
    }
}

fn check_worker_identity_files(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
    fixes_applied: &mut Vec<FixApplied>,
) {
    let workers = match load_workers_from_config() {
        Ok(w) => w,
        Err(_) => return,
    };

    for worker in workers {
        let key_path = PathBuf::from(shellexpand::tilde(&worker.identity_file).to_string());
        let name = format!("worker_key:{}", worker.id.as_str());
        let suggestion = ssh_worker_suggestion(&worker.user, &worker.host, &key_path);

        if !key_path.exists() {
            let result = CheckResult {
                category: "ssh".to_string(),
                name,
                status: CheckStatus::Warning,
                message: format!("Identity file missing for worker {}", worker.id.as_str()),
                details: Some(key_path.display().to_string()),
                suggestion: Some(suggestion),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
            print_check_result(&result, ctx);
            checks.push(result);
            continue;
        }

        let key_result = check_ssh_key_permissions(&key_path, options, fixes_applied);
        let status = key_result.status;
        let mut message = key_result.message;
        message.push_str(&format!(" (worker {})", worker.id.as_str()));

        let result = CheckResult {
            category: "ssh".to_string(),
            name,
            status,
            message,
            details: key_result.details,
            suggestion: Some(suggestion),
            fixable: key_result.fixable,
            fix_applied: key_result.fix_applied,
            fix_message: key_result.fix_message,
        };
        print_check_result(&result, ctx);
        checks.push(result);
    }
}

fn ssh_worker_suggestion(user: &str, host: &str, key_path: &Path) -> String {
    // Shell-escape every component before splicing into a runnable shell
    // string. Suggestions are surfaced to agents and copy-pasted into a
    // shell; a `workers.toml` entry like `host = "evil; rm -rf ~"` (or
    // a key path with spaces) MUST NOT produce a destructive command.
    let key_q = shell_escape::escape(key_path.to_string_lossy());
    let user_q = shell_escape::escape(user.into());
    let host_q = shell_escape::escape(host.into());
    format!(
        "Copy key: ssh-copy-id -i {key_q} {user_q}@{host_q}; \
Test: ssh -i {key_q} {user_q}@{host_q} echo \"success\"; \
Agent: eval $(ssh-agent) && ssh-add {key_q}; \
Debug: ssh -vvv -i {key_q} {user_q}@{host_q}",
    )
}

fn check_ssh_config() -> CheckResult {
    let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("/tmp"));
    let ssh_config = home.join(".ssh").join("config");

    if ssh_config.exists() {
        CheckResult {
            category: "ssh".to_string(),
            name: "ssh_config".to_string(),
            status: CheckStatus::Pass,
            message: "SSH config file exists".to_string(),
            details: Some(ssh_config.display().to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }
    } else {
        CheckResult {
            category: "ssh".to_string(),
            name: "ssh_config".to_string(),
            status: CheckStatus::Warning,
            message: "No SSH config file".to_string(),
            details: Some(ssh_config.display().to_string()),
            suggestion: Some(
                "Consider creating ~/.ssh/config for custom host settings".to_string(),
            ),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }
    }
}

// =============================================================================
// Daemon Checks
// =============================================================================

fn which_rchd_path() -> PathBuf {
    // Try to find rchd in same directory as current executable
    if let Ok(exe_path) = std::env::current_exe()
        && let Some(dir) = exe_path.parent()
    {
        let rchd = dir.join("rchd");
        if rchd.exists() {
            return rchd;
        }
    }

    // Fallback to path lookup
    which("rchd").unwrap_or_else(|_| PathBuf::from("rchd"))
}

/// Ask systemd's user-scope manager to start `rchd.service` (idempotent if
/// already active). Returns Ok only if `systemctl start` succeeds AND a
/// daemon actually accepts a connection on `socket_path` within the timeout.
/// Any failure returns Err so the caller falls back to direct spawn.
///
/// Note: this assumes the unit's configured socket path matches the one the
/// caller wants. On hosts where they differ, `wait_for_live_socket` will
/// time out and the caller falls back to nohup — same net effect as before.
fn start_rchd_via_systemd_user(socket_path: &Path) -> Result<(), String> {
    // Skip the redundant `is-enabled` probe: `systemctl start` already
    // fails cleanly for missing units (and also handles disabled-but-defined
    // ones, which `is-enabled` would have wrongly excluded). It's idempotent
    // when the unit is already active, so calling it on every miss is cheap.
    let start = Command::new("systemctl")
        .args(["--user", "start", "rchd.service"])
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status()
        .map_err(|e| format!("systemctl start failed to invoke: {e}"))?;
    if !start.success() {
        return Err(format!(
            "systemctl --user start rchd.service exited {start}"
        ));
    }

    // Probe for a real live listener, not just a socket file. The file may
    // exist as a leftover from a previous crash; `connect()` is the only
    // reliable proof that *some* rchd is currently serving on the path.
    if wait_for_socket(socket_path, Duration::from_secs(5)) {
        Ok(())
    } else {
        Err("systemd started rchd but no listener appeared on the socket within 5s".into())
    }
}

fn spawn_rchd(rchd_path: &Path, socket_path: &Path) -> Result<(), String> {
    let mut cmd = Command::new("nohup");
    cmd.arg(rchd_path)
        .arg("-s")
        .arg(socket_path)
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .stdin(Stdio::null());

    let mut child = cmd.spawn().map_err(|e| match e.kind() {
        std::io::ErrorKind::NotFound => "nohup not found while launching rchd".to_string(),
        _ => e.to_string(),
    })?;

    // Immediate-death detection: deadline-based polling instead of a one-shot
    // 100ms sleep + try_wait (qqa0y: under load a wrapper that exited at
    // 100-500ms slipped past the single check, and the caller then reported a
    // misleading "did not accept connections" instead of the real exit
    // status). Doctor is an interactive path with no tight latency contract,
    // so a 500ms window is a fine trade for reliable attribution.
    let spawn_deadline = Instant::now() + Duration::from_millis(500);
    loop {
        if let Some(status) = child.try_wait().map_err(|e| e.to_string())? {
            return if status.success() {
                Ok(())
            } else {
                Err(format!(
                    "rchd launch wrapper exited unsuccessfully: {status}"
                ))
            };
        }
        if Instant::now() >= spawn_deadline {
            break;
        }
        std::thread::sleep(Duration::from_millis(10));
    }

    // `nohup` does not daemonize by itself; it execs/wraps rchd as our
    // direct child. Keep a detached waiter while doctor continues so a
    // later daemon exit is reaped instead of becoming a zombie.
    std::thread::spawn(move || {
        let _ = child.wait();
    });
    Ok(())
}

/// Wait up to `timeout` for a daemon to actually accept a connection on
/// `socket_path`. Previously this checked only file existence, which would
/// falsely return Ok when a stale socket file lingered from a prior crash —
/// the caller then hit "connection refused" on first use. Using the live
/// probe is strictly more correct and benefits every call site
/// (start_daemon_with_binary, start_rchd_via_systemd_user, etc.).
fn wait_for_socket(socket_path: &Path, timeout: Duration) -> bool {
    let deadline = Instant::now() + timeout;
    while Instant::now() < deadline {
        if daemon_socket_accepts_connections(socket_path) {
            return true;
        }
        std::thread::sleep(Duration::from_millis(100));
    }
    daemon_socket_accepts_connections(socket_path)
}

fn start_daemon_with_binary(
    socket_path: &Path,
    rchd_path: &Path,
    timeout: Duration,
) -> Result<(), String> {
    if let Some(parent) = socket_path.parent() {
        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    }

    spawn_rchd(rchd_path, socket_path)?;

    if wait_for_socket(socket_path, timeout) {
        return Ok(());
    }

    Err(format!(
        "daemon process started but did not accept connections within {}s",
        timeout.as_secs()
    ))
}

// ============================================================================
// RUSTC_WRAPPER first-enable cold-rebuild advisory (C013 / bead .21.13)
// ============================================================================

// Cargo folds `RUSTC_WRAPPER` / `RUSTC_WORKSPACE_WRAPPER` into the
// fingerprint of every crate, so enabling a wrapper — or changing the
// wrapper binary's identity — recompiles the workspace exactly once.
// Users read that as a regression; this check detects first enablement
// and identity change against a small cache-file marker and explains
// the semantics before they do.

/// Last-seen wrapper identity per env var (blake3 hex of binary prefix).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
struct RustcWrapperState {
    wrappers: BTreeMap<String, String>,
}

const RUSTC_WRAPPER_STATE_FILE: &str = "doctor-rustc-wrapper-state.json";

fn rustc_wrapper_state_path() -> Option<PathBuf> {
    dirs::cache_dir().map(|d| d.join("rch").join(RUSTC_WRAPPER_STATE_FILE))
}

fn load_rustc_wrapper_state() -> RustcWrapperState {
    let Some(path) = rustc_wrapper_state_path() else {
        return RustcWrapperState::default();
    };
    match std::fs::read(&path) {
        Ok(bytes) => serde_json::from_slice(&bytes).unwrap_or_default(),
        Err(_) => RustcWrapperState::default(),
    }
}

fn store_rustc_wrapper_state(state: &RustcWrapperState) -> bool {
    let Some(path) = rustc_wrapper_state_path() else {
        return false;
    };
    if let Some(parent) = path.parent() {
        let _ = std::fs::create_dir_all(parent);
    }
    match serde_json::to_vec(state) {
        Ok(bytes) => std::fs::write(&path, bytes).is_ok(),
        Err(_) => false,
    }
}

/// One observed wrapper env var: raw value plus resolved binary digest.
#[derive(Debug, Clone)]
struct WrapperObservation {
    env_var: &'static str,
    raw_value: String,
    resolved: Option<PathBuf>,
    /// blake3 hex over the first 4 MiB of the wrapper binary; `None`
    /// when the binary is missing or unreadable.
    identity: Option<String>,
}

const WRAPPER_IDENTITY_PREFIX_BYTES: u64 = 4 * 1024 * 1024;

fn hash_wrapper_identity(path: &Path) -> Option<String> {
    let file = std::fs::File::open(path).ok()?;
    let mut hasher = blake3::Hasher::new();
    std::io::copy(&mut file.take(WRAPPER_IDENTITY_PREFIX_BYTES), &mut hasher).ok()?;
    let hex = hasher.finalize().to_hex();
    Some(hex.as_str()[..32].to_string())
}

fn wrapper_binary_path(raw: &str) -> Option<PathBuf> {
    if raw.contains('/') {
        // Explicit path (cargo resolves it relative to cwd; doctor
        // reports what it can see from its own cwd).
        let candidate = Path::new(raw);
        if candidate.is_file() {
            Some(candidate.to_path_buf())
        } else {
            None
        }
    } else {
        which(raw).ok()
    }
}

fn observe_wrapper(env_var: &'static str) -> Option<WrapperObservation> {
    let raw_value = std::env::var(env_var).ok()?;
    if raw_value.trim().is_empty() {
        return None;
    }
    let resolved = wrapper_binary_path(&raw_value);
    let identity = resolved.as_deref().and_then(hash_wrapper_identity);
    Some(WrapperObservation {
        env_var,
        raw_value,
        resolved,
        identity,
    })
}

/// What the recorded state says about this observation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WrapperVerdict {
    FirstEnablement,
    Unchanged,
    IdentityChanged,
}

fn wrapper_verdict(state: &RustcWrapperState, obs: &WrapperObservation) -> WrapperVerdict {
    // Only called with a hashed identity; unhashable binaries are
    // reported by their own check arm before this runs.
    match state.wrappers.get(obs.env_var) {
        None => WrapperVerdict::FirstEnablement,
        Some(prev) if *prev == obs.identity.as_deref().expect("hashed") => {
            WrapperVerdict::Unchanged
        }
        Some(_) => WrapperVerdict::IdentityChanged,
    }
}

/// Pure core of the check: verdicts for already-observed wrappers.
/// State is loaded by the caller and rewritten best-effort afterwards.
fn rustc_wrapper_results(
    state: &RustcWrapperState,
    observed: &[WrapperObservation],
) -> Vec<CheckResult> {
    const MONITORING_DOC: &str = "docs/guides/monitoring.md (RUSTC_WRAPPER section)";
    if observed.is_empty() {
        return vec![CheckResult {
            category: "toolchain".to_string(),
            name: "rustc_wrapper".to_string(),
            status: CheckStatus::Pass,
            message: "RUSTC_WRAPPER not set".to_string(),
            details: Some(
                "No compile wrapper configured; no wrapper-related fingerprint churn possible."
                    .to_string(),
            ),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }];
    }

    let mut results = Vec::new();
    let mut new_state = state.clone();
    for obs in observed {
        let (status, message, details, suggestion);
        // Empirically pinned on cargo 1.100-nightly (see the fixture):
        // plain RUSTC_WRAPPER is NOT part of any fingerprint — enable,
        // swap, or remove never recompiles. RUSTC_WORKSPACE_WRAPPER IS
        // fingerprinted: first use of a given value compiles once, and
        // removal falls back to previously valid artifacts.
        let fingerprinted = obs.env_var == "RUSTC_WORKSPACE_WRAPPER";
        match (&obs.resolved, &obs.identity) {
            (None, _) => {
                status = CheckStatus::Warning;
                message = format!(
                    "{} set to '{}' but the wrapper binary was not found",
                    obs.env_var, obs.raw_value
                );
                details = Some(
                    "Cargo invokes this binary for every compilation; a missing \
                     wrapper breaks or stalls builds."
                        .to_string(),
                );
                suggestion = Some(
                    "Fix the path, unset the variable, or install the wrapper binary".to_string(),
                );
            }
            (Some(path), identity) if !fingerprinted => {
                status = CheckStatus::Pass;
                message = format!("{} wrapper active: '{}'", obs.env_var, obs.raw_value);
                details = Some(format!(
                    "Wrapper binary: {}. Plain RUSTC_WRAPPER is not part of \
                     Cargo's fingerprints (verified on current cargo): enabling, \
                     swapping, or removing it does NOT force a rebuild. The \
                     wrapper must still exec the real compiler.",
                    path.display()
                ));
                suggestion = None;
                // No identity tracking needed when nothing is fingerprinted;
                // drop any stale marker so old state cannot confuse later
                // toolchains that change semantics.
                new_state.wrappers.remove(obs.env_var);
                let _ = identity;
            }
            (Some(path), Some(_)) => match wrapper_verdict(state, obs) {
                WrapperVerdict::FirstEnablement => {
                    status = CheckStatus::Warning;
                    message = format!(
                        "{} wrapper enabled (first observation): '{}'",
                        obs.env_var, obs.raw_value
                    );
                    details = Some(format!(
                        "Wrapper binary: {}. Cargo fingerprints include this \
                         variable, so its first use compiles the workspace once \
                         — expected, NOT a regression. Subsequent builds are \
                         incremental; removing it falls back to previously \
                         valid artifacts without recompiling.",
                        path.display()
                    ));
                    suggestion = Some(format!("See {MONITORING_DOC}"));
                }
                WrapperVerdict::Unchanged => {
                    status = CheckStatus::Pass;
                    message = format!("{} wrapper unchanged since last doctor run", obs.env_var);
                    details = Some(format!(
                        "Wrapper binary: {} — identity matches the recorded \
                         marker; no rebuild expected.",
                        path.display()
                    ));
                    suggestion = None;
                }
                WrapperVerdict::IdentityChanged => {
                    status = CheckStatus::Warning;
                    message = format!(
                        "{} wrapper value changed since last doctor run",
                        obs.env_var
                    );
                    details = Some(format!(
                        "Wrapper binary: {}. A new wrapper value compiles the \
                         workspace once (the value is fingerprinted, not the \
                         binary contents) — expected after upgrading or \
                         replacing the wrapper, NOT a regression.",
                        path.display()
                    ));
                    suggestion = Some(format!("See {MONITORING_DOC}"));
                }
            },
            (Some(path), None) => {
                status = CheckStatus::Warning;
                message = format!(
                    "{} wrapper binary exists but could not be hashed",
                    obs.env_var
                );
                details = Some(format!(
                    "Wrapper binary: {}. Identity tracking skipped for this run.",
                    path.display()
                ));
                suggestion = Some("Check file permissions".to_string());
            }
        }
        if fingerprinted && let Some(identity) = &obs.identity {
            new_state
                .wrappers
                .insert(obs.env_var.to_string(), identity.clone());
        }
        results.push(CheckResult {
            category: "toolchain".to_string(),
            name: "rustc_wrapper".to_string(),
            status,
            message,
            details,
            suggestion,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        });
    }
    // Best-effort persistence: a failed write degrades the next run to
    // "first observation" wording, never blocks the check itself.
    let _ = store_rustc_wrapper_state(&new_state);
    results
}

fn rustc_wrapper_checks() -> Vec<CheckResult> {
    let observed: Vec<WrapperObservation> = ["RUSTC_WRAPPER", "RUSTC_WORKSPACE_WRAPPER"]
        .into_iter()
        .filter_map(observe_wrapper)
        .collect();
    let state = load_rustc_wrapper_state();
    rustc_wrapper_results(&state, &observed)
}

fn start_daemon_for_doctor(socket_path: &Path, timeout: Duration) -> Result<(), String> {
    if let Some(parent) = socket_path.parent() {
        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    }

    // Prefer the systemd-managed daemon in production. Keeping this policy out
    // of `start_daemon_with_binary` makes explicit-binary tests deterministic
    // and prevents them from consulting or starting the host's real service.
    if cfg!(target_os = "linux") {
        match start_rchd_via_systemd_user(socket_path) {
            Ok(()) => return Ok(()),
            Err(reason) => {
                eprintln!(
                    "rch: not using systemd --user rchd.service ({reason}); \
                     falling back to direct spawn"
                );
            }
        }
    }

    start_daemon_with_binary(socket_path, &which_rchd_path(), timeout)
}

fn check_daemon(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
    fixes_applied: &mut Vec<FixApplied>,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Daemon"));
        println!();
    }

    let socket_path = configured_or_default_socket_path();
    let socket_exists = socket_path.exists();
    let socket_live = socket_exists && daemon_socket_accepts_connections(&socket_path);
    let mut result = if socket_live {
        CheckResult {
            category: "daemon".to_string(),
            name: "daemon_socket".to_string(),
            status: CheckStatus::Pass,
            message: "Daemon is accepting connections".to_string(),
            details: Some(socket_path.to_string_lossy().to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }
    } else if socket_exists {
        CheckResult {
            category: "daemon".to_string(),
            name: "daemon_socket".to_string(),
            status: CheckStatus::Warning,
            message: "Daemon socket is stale or unreachable".to_string(),
            details: Some(socket_path.to_string_lossy().to_string()),
            suggestion: Some("Restart daemon with: rch daemon restart".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        }
    } else {
        CheckResult {
            category: "daemon".to_string(),
            name: "daemon_socket".to_string(),
            status: CheckStatus::Warning,
            message: "Daemon is not running".to_string(),
            details: Some(socket_path.to_string_lossy().to_string()),
            suggestion: Some("Start daemon with: rch daemon start".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        }
    };

    let mut fix_line: Option<(StatusIndicator, String)> = None;
    if options.fix && result.fixable && result.status != CheckStatus::Pass {
        if options.dry_run {
            let msg = "Would start RCH daemon".to_string();
            result.fix_message = Some(msg.clone());
            fix_line = Some((StatusIndicator::Pending, format!("Would fix: {}", msg)));
        } else {
            match start_daemon_for_doctor(&socket_path, Duration::from_secs(3)) {
                Ok(()) => {
                    let msg = "Started RCH daemon".to_string();
                    result.status = CheckStatus::Pass;
                    result.message = "Daemon started (fixed)".to_string();
                    result.details = Some(socket_path.to_string_lossy().to_string());
                    result.suggestion = None;
                    result.fixable = false;
                    result.fix_applied = true;
                    result.fix_message = Some(msg.clone());
                    fix_line = Some((StatusIndicator::Success, format!("Fixed: {}", msg)));
                    fixes_applied.push(FixApplied {
                        check_name: "daemon_socket".to_string(),
                        action: msg,
                        success: true,
                        error: None,
                    });
                }
                Err(e) => {
                    let msg = format!("Failed to start daemon: {}", e);
                    result.fix_message = Some(msg.clone());
                    fix_line = Some((StatusIndicator::Error, msg.clone()));
                    fixes_applied.push(FixApplied {
                        check_name: "daemon_socket".to_string(),
                        action: "Start RCH daemon".to_string(),
                        success: false,
                        error: Some(e),
                    });
                }
            }
        }
    }

    if let Some((indicator, line)) = fix_line
        && !ctx.is_json()
    {
        let rendered = match indicator {
            StatusIndicator::Success => style.success(&line),
            StatusIndicator::Pending => style.muted(&line),
            StatusIndicator::Error => style.error(&line),
            _ => style.info(&line),
        };
        println!("  {} {}", indicator.display(style), rendered);
    }

    print_check_result(&result, ctx);
    checks.push(result);

    // Warn if a legacy /tmp socket exists but the configured path has moved.
    let legacy_socket = Path::new("/tmp/rch.sock");
    if socket_path != legacy_socket && legacy_socket.exists() {
        let legacy_result = CheckResult {
            category: "daemon".to_string(),
            name: "legacy_socket_path".to_string(),
            status: CheckStatus::Warning,
            message: "Legacy /tmp socket detected".to_string(),
            details: Some(legacy_socket.display().to_string()),
            suggestion: Some(
                "Restart the daemon so it binds to the configured socket path".to_string(),
            ),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
        print_check_result(&legacy_result, ctx);
        checks.push(legacy_result);
    }

    if !ctx.is_json() {
        println!();
    }
}

fn daemon_socket_accepts_connections(socket_path: &Path) -> bool {
    #[cfg(unix)]
    {
        std::os::unix::net::UnixStream::connect(socket_path).is_ok()
    }

    #[cfg(not(unix))]
    {
        socket_path.exists()
    }
}

// =============================================================================
// Cancellation Health Checks
// =============================================================================

fn evaluate_cancellation_health(
    status: &crate::status_types::DaemonFullStatusResponse,
) -> CheckResult {
    let mut total = 0usize;
    let mut cleanup_failures = 0usize;
    let mut sigkill_escalations = 0usize;
    let mut unreachable_workers = 0usize;
    let mut operations = Vec::new();

    for build in &status.recent_builds {
        let Some(cancellation) = &build.cancellation else {
            continue;
        };
        total += 1;
        operations.push(cancellation.operation_id.clone());
        if !cancellation.cleanup_ok {
            cleanup_failures += 1;
        }
        if cancellation.escalation_stage == "sigkill" {
            sigkill_escalations += 1;
        }
        if cancellation
            .worker_health
            .as_ref()
            .is_some_and(|health| health.status == "unreachable")
        {
            unreachable_workers += 1;
        }
    }

    if total == 0 {
        return CheckResult {
            category: "cancellation".to_string(),
            name: "cancellation_health".to_string(),
            status: CheckStatus::Pass,
            message: "No recent cancellation events detected".to_string(),
            details: None,
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
    }

    let details = Some(format!(
        "recent={}, cleanup_failures={}, sigkill_escalations={}, unreachable_workers={}, operations={}",
        total,
        cleanup_failures,
        sigkill_escalations,
        unreachable_workers,
        operations.join(",")
    ));

    if cleanup_failures > 0 {
        return CheckResult {
            category: "cancellation".to_string(),
            name: "cancellation_health".to_string(),
            status: CheckStatus::Fail,
            message: format!(
                "{} cancellation(s) ended with cleanup failures",
                cleanup_failures
            ),
            details,
            suggestion: Some(
                "Run `rch workers probe --all` and inspect daemon `cancellation_failed` events before retrying affected builds.".to_string(),
            ),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
    }

    if sigkill_escalations > 0 || unreachable_workers > 0 {
        return CheckResult {
            category: "cancellation".to_string(),
            name: "cancellation_health".to_string(),
            status: CheckStatus::Warning,
            message: format!(
                "{} cancellation(s) required escalation and/or involved unreachable workers",
                total
            ),
            details,
            suggestion: Some(
                "Review `rch status --jobs` for stuck phases and verify worker connectivity with `rch workers probe --all`.".to_string(),
            ),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
    }

    CheckResult {
        category: "cancellation".to_string(),
        name: "cancellation_health".to_string(),
        status: CheckStatus::Pass,
        message: format!(
            "{} recent cancellation(s) completed with deterministic cleanup",
            total
        ),
        details,
        suggestion: None,
        fixable: false,
        fix_applied: false,
        fix_message: None,
    }
}

async fn check_cancellation_health(checks: &mut Vec<CheckResult>, ctx: &OutputContext) {
    let style = ctx.theme();
    if !ctx.is_json() {
        println!("{}", style.highlight("Cancellation Health"));
        println!();
    }

    let socket_path = configured_or_default_socket_path();
    let result = if !socket_path.exists() {
        CheckResult {
            category: "cancellation".to_string(),
            name: "cancellation_health".to_string(),
            status: CheckStatus::Skipped,
            message: "Daemon socket not present; skipping cancellation diagnostics".to_string(),
            details: Some(socket_path.display().to_string()),
            suggestion: Some("Start daemon with: rch daemon start".to_string()),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        }
    } else {
        match query_daemon_full_status().await {
            Ok(status) => evaluate_cancellation_health(&status),
            Err(e) => CheckResult {
                category: "cancellation".to_string(),
                name: "cancellation_health".to_string(),
                status: CheckStatus::Warning,
                message: "Unable to query daemon status for cancellation diagnostics".to_string(),
                details: Some(e.to_string()),
                suggestion: Some(
                    "Ensure daemon is responsive (`rch status`) and retry `rch doctor`."
                        .to_string(),
                ),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            },
        }
    };

    print_check_result(&result, ctx);
    checks.push(result);

    if !ctx.is_json() {
        println!();
    }
}

// =============================================================================
// Hook Checks
// =============================================================================

fn check_hooks(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
    fixes_applied: &mut Vec<FixApplied>,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Hooks"));
        println!();
    }

    // Check Claude Code hook
    let mut claude_result = check_claude_code_hook();
    let mut fix_message: Option<String> = None;
    let mut fix_applied = false;
    let mut fix_line: Option<(StatusIndicator, String)> = None;

    if options.fix && claude_result.fixable && claude_result.status != CheckStatus::Pass {
        match install_hook(AgentKind::ClaudeCode, options.dry_run) {
            Ok(IdempotentResult::Changed) => {
                fix_applied = true;
                let msg = "Installed Claude Code hook".to_string();
                fix_message = Some(msg.clone());
                fix_line = Some((StatusIndicator::Success, format!("Fixed: {}", msg)));
                fixes_applied.push(FixApplied {
                    check_name: "claude_code_hook".to_string(),
                    action: msg.clone(),
                    success: true,
                    error: None,
                });
                claude_result.status = CheckStatus::Pass;
                claude_result.message = "Claude Code PreToolUse hook installed (fixed)".to_string();
                claude_result.suggestion = None;
                claude_result.fixable = false;
            }
            Ok(IdempotentResult::WouldChange(msg)) => {
                fix_message = Some(msg.clone());
                fix_line = Some((StatusIndicator::Pending, format!("Would fix: {}", msg)));
            }
            Ok(IdempotentResult::Unchanged) => {
                fix_message = Some("Claude Code hook already installed".to_string());
                claude_result.status = CheckStatus::Pass;
                claude_result.message = "Claude Code PreToolUse hook already installed".to_string();
                claude_result.suggestion = None;
                claude_result.fixable = false;
            }
            Ok(other) => {
                let msg = format!("Hook install result: {}", other);
                fix_message = Some(msg.clone());
                fix_line = Some((StatusIndicator::Success, format!("Fixed: {}", msg)));
                if !options.dry_run {
                    fix_applied = true;
                    fixes_applied.push(FixApplied {
                        check_name: "claude_code_hook".to_string(),
                        action: msg.clone(),
                        success: true,
                        error: None,
                    });
                    claude_result.status = CheckStatus::Pass;
                    claude_result.message =
                        "Claude Code PreToolUse hook installed (fixed)".to_string();
                    claude_result.suggestion = None;
                    claude_result.fixable = false;
                }
            }
            Err(e) => {
                let msg = format!("Failed to install hook: {}", e);
                fix_message = Some(msg.clone());
                fix_line = Some((StatusIndicator::Error, msg.clone()));
                if !options.dry_run {
                    fixes_applied.push(FixApplied {
                        check_name: "claude_code_hook".to_string(),
                        action: "Install Claude Code hook".to_string(),
                        success: false,
                        error: Some(e.to_string()),
                    });
                }
            }
        }
    }

    claude_result.fix_applied = fix_applied;
    claude_result.fix_message = fix_message;

    if let Some((indicator, line)) = fix_line
        && !ctx.is_json()
    {
        let rendered = match indicator {
            StatusIndicator::Success => style.success(&line),
            StatusIndicator::Pending => style.muted(&line),
            StatusIndicator::Error => style.error(&line),
            _ => style.info(&line),
        };
        println!("  {} {}", indicator.display(style), rendered);
    }
    print_check_result(&claude_result, ctx);
    checks.push(claude_result);

    if !ctx.is_json() {
        println!();
    }
}

fn check_claude_code_hook() -> CheckResult {
    let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("/tmp"));
    let settings_path = home.join(".claude").join("settings.json");

    if !settings_path.exists() {
        return CheckResult {
            category: "hooks".to_string(),
            name: "claude_code_hook".to_string(),
            status: CheckStatus::Warning,
            message: "Claude Code settings not found".to_string(),
            details: Some(settings_path.display().to_string()),
            suggestion: Some("Install hook with: rch hook install".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        };
    }

    match read_config_capped(&settings_path) {
        Ok(content) => match serde_json::from_str::<serde_json::Value>(&content) {
            Ok(settings) => {
                let has_hook = settings
                    .get("hooks")
                    .and_then(|h| h.get("PreToolUse"))
                    .is_some();

                if has_hook {
                    CheckResult {
                        category: "hooks".to_string(),
                        name: "claude_code_hook".to_string(),
                        status: CheckStatus::Pass,
                        message: "Claude Code PreToolUse hook is installed".to_string(),
                        details: Some(settings_path.display().to_string()),
                        suggestion: None,
                        fixable: false,
                        fix_applied: false,
                        fix_message: None,
                    }
                } else {
                    CheckResult {
                        category: "hooks".to_string(),
                        name: "claude_code_hook".to_string(),
                        status: CheckStatus::Warning,
                        message: "Claude Code PreToolUse hook not configured".to_string(),
                        details: Some(settings_path.display().to_string()),
                        suggestion: Some("Install hook with: rch hook install".to_string()),
                        fixable: true,
                        fix_applied: false,
                        fix_message: None,
                    }
                }
            }
            Err(e) => CheckResult {
                category: "hooks".to_string(),
                name: "claude_code_hook".to_string(),
                status: CheckStatus::Fail,
                message: "Could not parse Claude Code settings".to_string(),
                details: Some(e.to_string()),
                suggestion: None,
                fixable: false,
                fix_applied: false,
                fix_message: None,
            },
        },
        Err(e) => CheckResult {
            category: "hooks".to_string(),
            name: "claude_code_hook".to_string(),
            status: CheckStatus::Fail,
            message: "Could not read Claude Code settings".to_string(),
            details: Some(e.to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        },
    }
}

// =============================================================================
// Worker Checks
// =============================================================================

async fn check_workers(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Workers"));
        println!();
    }

    // Only check connectivity if verbose mode or explicitly requested
    let workers = match load_workers_from_config() {
        Ok(w) => w,
        Err(_) => {
            let result = CheckResult {
                category: "workers".to_string(),
                name: "worker_config".to_string(),
                status: CheckStatus::Skipped,
                message: "Could not load workers configuration".to_string(),
                details: None,
                suggestion: Some("Run 'rch config init' to create workers.toml".to_string()),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
            print_check_result(&result, ctx);
            checks.push(result);
            return;
        }
    };

    if workers.is_empty() {
        let result = CheckResult {
            category: "workers".to_string(),
            name: "worker_count".to_string(),
            status: CheckStatus::Warning,
            message: "No workers configured".to_string(),
            details: None,
            suggestion: Some("Add workers to workers.toml".to_string()),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
        print_check_result(&result, ctx);
        checks.push(result);
        return;
    }

    // Report worker count
    let count_result = CheckResult {
        category: "workers".to_string(),
        name: "worker_count".to_string(),
        status: CheckStatus::Pass,
        message: format!("{} worker(s) configured", workers.len()),
        details: Some(
            workers
                .iter()
                .map(|w| w.id.as_str().to_string())
                .collect::<Vec<_>>()
                .join(", "),
        ),
        suggestion: None,
        fixable: false,
        fix_applied: false,
        fix_message: None,
    };
    print_check_result(&count_result, ctx);
    checks.push(count_result);

    // Only probe workers in verbose mode
    if options.verbose && !ctx.is_json() {
        println!(
            "  {}",
            style.muted("(use --verbose to probe worker connectivity)")
        );
    }

    if !ctx.is_json() {
        println!();
    }
}

// =============================================================================
// Telemetry Database Checks
// =============================================================================

fn check_telemetry_database(
    checks: &mut Vec<CheckResult>,
    ctx: &OutputContext,
    options: &DoctorOptions,
) {
    let style = ctx.theme();

    if !ctx.is_json() {
        println!("{}", style.highlight("Telemetry Database"));
        println!();
    }

    // Get the default telemetry database path
    let db_path = match ProjectDirs::from("com", "rch", "rch") {
        Some(dirs) => dirs.data_local_dir().join("telemetry").join("telemetry.db"),
        None => {
            let result = CheckResult {
                category: "telemetry".to_string(),
                name: "telemetry_database".to_string(),
                status: CheckStatus::Skipped,
                message: "Could not determine telemetry database path".to_string(),
                details: None,
                suggestion: None,
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
            print_check_result(&result, ctx);
            checks.push(result);
            return;
        }
    };

    // Check if database file exists
    if !db_path.exists() {
        let result = CheckResult {
            category: "telemetry".to_string(),
            name: "telemetry_database".to_string(),
            status: CheckStatus::Warning,
            message: "Telemetry database does not exist yet".to_string(),
            details: Some(db_path.display().to_string()),
            suggestion: Some("Database will be created when daemon starts".to_string()),
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };
        print_check_result(&result, ctx);
        checks.push(result);
        return;
    }

    // Try to open and check the database
    match TelemetryStorage::new(&db_path, 30, 24, 365, 100) {
        Ok(storage) => {
            // Run integrity check
            match storage.integrity_check() {
                Ok(()) => {
                    // Get stats if verbose
                    let details = if options.verbose {
                        storage.stats().ok().map(|s| {
                            format!(
                                "Snapshots: {}, Aggregates: {}, SpeedScores: {}, Tests: {}, Size: {} KB",
                                s.telemetry_snapshots,
                                s.hourly_aggregates,
                                s.speedscore_entries,
                                s.test_runs,
                                s.db_size_bytes / 1024
                            )
                        })
                    } else {
                        Some(db_path.display().to_string())
                    };

                    let result = CheckResult {
                        category: "telemetry".to_string(),
                        name: "telemetry_database".to_string(),
                        status: CheckStatus::Pass,
                        message: "Telemetry database is healthy".to_string(),
                        details,
                        suggestion: None,
                        fixable: false,
                        fix_applied: false,
                        fix_message: None,
                    };
                    print_check_result(&result, ctx);
                    checks.push(result);
                }
                Err(e) => {
                    let result = CheckResult {
                        category: "telemetry".to_string(),
                        name: "telemetry_database".to_string(),
                        status: CheckStatus::Fail,
                        message: "Telemetry database integrity check failed".to_string(),
                        details: Some(e.to_string()),
                        suggestion: Some(
                            "Database may be corrupted. Delete and let daemon recreate it"
                                .to_string(),
                        ),
                        fixable: false,
                        fix_applied: false,
                        fix_message: None,
                    };
                    print_check_result(&result, ctx);
                    checks.push(result);
                }
            }
        }
        Err(e) => {
            let result = CheckResult {
                category: "telemetry".to_string(),
                name: "telemetry_database".to_string(),
                status: CheckStatus::Fail,
                message: "Could not open telemetry database".to_string(),
                details: Some(e.to_string()),
                suggestion: Some(
                    "Check file permissions or delete and let daemon recreate it".to_string(),
                ),
                fixable: false,
                fix_applied: false,
                fix_message: None,
            };
            print_check_result(&result, ctx);
            checks.push(result);
        }
    }

    if !ctx.is_json() {
        println!();
    }
}

// =============================================================================
// Helper Functions
// =============================================================================

fn print_check_result(result: &CheckResult, ctx: &OutputContext) {
    if ctx.is_json() {
        return;
    }

    let style = ctx.theme();
    let indicator = match result.status {
        CheckStatus::Pass => StatusIndicator::Success,
        CheckStatus::Warning => StatusIndicator::Warning,
        CheckStatus::Fail => StatusIndicator::Error,
        CheckStatus::Skipped => StatusIndicator::Pending,
    };

    print!(
        "  {} {} {}",
        indicator.display(style),
        style.highlight(&result.name),
        style.muted("-")
    );

    match result.status {
        CheckStatus::Pass => println!(" {}", style.success(&result.message)),
        CheckStatus::Warning => println!(" {}", style.warning(&result.message)),
        CheckStatus::Fail => println!(" {}", style.error(&result.message)),
        CheckStatus::Skipped => println!(" {}", style.muted(&result.message)),
    }

    if let Some(ref details) = result.details
        && ctx.is_verbose()
    {
        println!("    {}", style.muted(details));
    }

    if let Some(ref suggestion) = result.suggestion {
        println!("    {} {}", style.muted("Hint:"), style.info(suggestion));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use tempfile::TempDir;

    #[test]
    fn dispatcher_role_shim_check_is_read_only_and_preserves_findings() {
        use rch_common::BoxRole;
        let problems = vec![
            "missing cargo".to_string(),
            "PATH bypasses shim".to_string(),
        ];
        let check = dispatcher_shim_check(BoxRole::Dispatcher, problems.clone());
        assert_eq!(check.status, CheckStatus::Warning);
        assert_eq!(
            check.details.as_deref(),
            Some("missing cargo; PATH bypasses shim")
        );
        assert!(
            check
                .suggestion
                .as_deref()
                .unwrap()
                .contains("rch shim install")
        );
        assert!(!check.fixable && !check.fix_applied);
        assert_eq!(
            dispatcher_shim_check(BoxRole::Dispatcher, vec![]).status,
            CheckStatus::Pass
        );
        for role in [BoxRole::Worker, BoxRole::Hybrid] {
            let check = dispatcher_shim_check(role, problems.clone());
            assert_eq!(check.status, CheckStatus::Pass);
            assert!(check.message.contains(role.as_str()));
            assert!(check.details.is_none() && check.suggestion.is_none());
        }
    }

    #[test]
    fn local_build_diagnostics_preserve_current_warning_and_failure_details() {
        let mut observation = crate::local_builds::LocalBuildObservation {
            builds: vec![crate::local_builds::LocalBuild {
                pid: 4242,
                comm: "cargo-rch-real".to_string(),
                exe: None,
            }],
            scan_error: None,
            state_error: Some("cache denied".to_string()),
            transition: None,
        };
        let check = local_build_check(&observation);
        assert_eq!(check.status, CheckStatus::Warning);
        assert!(check.message.contains("1 local builds on a dispatcher"));
        assert!(check.details.as_ref().unwrap().contains("pid=4242"));
        assert!(check.details.as_ref().unwrap().contains("cache denied"));
        assert!(!check.fixable);
        let diagnostics = reliability_local_build_diagnostics(Some(&observation));
        assert_eq!(
            diagnostics[0].code,
            ReliabilityReasonCode::LocalBuildsDetected
        );
        assert_eq!(diagnostics[0].severity, ReliabilitySeverity::Warning);

        observation.builds.clear();
        observation.scan_error = Some("proc denied".to_string());
        assert_eq!(
            reliability_local_build_diagnostics(Some(&observation))[0].code,
            ReliabilityReasonCode::LocalBuildScanUnavailable
        );
        observation.scan_error = None;
        assert_eq!(
            reliability_local_build_diagnostics(Some(&observation))[0].code,
            ReliabilityReasonCode::LocalBuildAlarmStateUnavailable
        );
        observation.state_error = None;
        let diagnostics = reliability_local_build_diagnostics(Some(&observation));
        assert_eq!(
            diagnostics[0].code,
            ReliabilityReasonCode::LocalBuildsAbsent
        );
        assert_eq!(diagnostics[0].severity, ReliabilitySeverity::Pass);
        assert!(reliability_local_build_diagnostics(None).is_empty());
    }

    fn worker_status(
        id: &str,
        status: &str,
        circuit_state: &str,
    ) -> crate::status_types::WorkerStatusFromApi {
        serde_json::from_value(json!({
            "id": id,
            "host": "worker.example",
            "user": "ubuntu",
            "status": status,
            "circuit_state": circuit_state,
            "used_slots": 0,
            "total_slots": 8,
            "speed_score": 99.0,
            "last_error": null
        }))
        .expect("worker status fixture should parse")
    }

    // ========================
    // Reliability diagnostic coverage (bead 2s99h.16)
    // ========================

    fn diag(severity: ReliabilitySeverity, code: ReliabilityReasonCode) -> ReliabilityDiagnostic {
        ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            "fixture",
            severity,
            "fixture diagnostic",
            code,
        )
    }

    /// Build a `DaemonFullStatusResponse` with the given worker rows and
    /// daemon health counts; all build/queue lists empty.
    fn daemon_status(
        workers_total: usize,
        workers_healthy: usize,
        workers: serde_json::Value,
    ) -> crate::status_types::DaemonFullStatusResponse {
        serde_json::from_value(json!({
            "daemon": {
                "pid": 1,
                "uptime_secs": 10,
                "version": "0.1.0",
                "socket_path": "/tmp/rch.sock",
                "started_at": "2026-01-01T00:00:00Z",
                "workers_total": workers_total,
                "workers_healthy": workers_healthy,
                "slots_total": 8,
                "slots_available": 4
            },
            "workers": workers,
            "active_builds": [],
            "queued_builds": [],
            "recent_builds": [],
            "issues": [],
            "alerts": [],
            "stats": {
                "total_builds": 0,
                "success_count": 0,
                "failure_count": 0,
                "remote_count": 0,
                "local_count": 0,
                "avg_duration_ms": 0
            },
            "test_stats": null,
            "saved_time": null
        }))
        .expect("daemon status fixture should parse")
    }

    // ========================
    // Mirror-ownership diagnostics (bd-kugfc)
    // ========================

    fn ownership_worker(id: &str) -> rch_common::WorkerConfig {
        serde_json::from_value(json!({
            "id": id,
            "host": "worker.example",
            "user": "ubuntu",
            "identity_file": "/tmp/id_ed25519",
            "total_slots": 8
        }))
        .expect("worker config fixture should parse")
    }

    #[test]
    fn mirror_ownership_maps_each_probe_outcome_to_its_code() {
        let workers = vec![
            ownership_worker("w-clean"),
            ownership_worker("w-drift"),
            ownership_worker("w-sudo"),
            ownership_worker("w-dead"),
            ownership_worker("w-mock"),
        ];
        let results = vec![
            crate::hook::ssh::MirrorOwnershipProbe::Healthy,
            crate::hook::ssh::MirrorOwnershipProbe::Drift { count: 3 },
            crate::hook::ssh::MirrorOwnershipProbe::CheckUnavailable,
            crate::hook::ssh::MirrorOwnershipProbe::Unprobeable("ssh refused".to_string()),
            crate::hook::ssh::MirrorOwnershipProbe::Skipped,
        ];

        let diags = reliability_mirror_ownership_diagnostics(
            Some(&workers),
            None,
            Some(&results),
            ProbeOutcome::Ok,
            None,
        );

        let by_code = |code: ReliabilityReasonCode| {
            diags.iter().filter(|d| d.code == code).collect::<Vec<_>>()
        };

        assert_eq!(
            by_code(ReliabilityReasonCode::WorkerMirrorOwnershipHealthy).len(),
            1
        );
        let drift = by_code(ReliabilityReasonCode::WorkerMirrorOwnershipDrift);
        assert_eq!(drift.len(), 1);
        assert_eq!(drift[0].severity, ReliabilitySeverity::Warning);
        assert_eq!(drift[0].worker_id.as_deref(), Some("w-drift"));
        assert!(
            drift[0]
                .remediation_command
                .as_deref()
                .unwrap_or_default()
                .contains("chown"),
            "drift remediation must name the chown fix"
        );
        assert_eq!(
            by_code(ReliabilityReasonCode::WorkerMirrorOwnershipCheckUnavailable).len(),
            1
        );
        let dead = by_code(ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable);
        assert_eq!(dead.len(), 1);
        assert_eq!(dead[0].worker_id.as_deref(), Some("w-dead"));
        // Skipped workers emit nothing; total = healthy + drift + sudo + dead.
        assert_eq!(diags.len(), 4);
    }

    #[test]
    fn mirror_ownership_fleet_fallback_when_probe_bucket_dies() {
        let workers = vec![ownership_worker("w1"), ownership_worker("w2")];
        let diags = reliability_mirror_ownership_diagnostics(
            Some(&workers),
            None,
            None,
            ProbeOutcome::Timeout,
            None,
        );
        assert_eq!(diags.len(), 1);
        assert_eq!(
            diags[0].code,
            ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable
        );
        assert_eq!(diags[0].severity, ReliabilitySeverity::Warning);
        assert!(diags[0].message.contains("timeout"), "{}", diags[0].message);
    }

    #[test]
    fn mirror_ownership_reports_empty_fleet_and_config_failures() {
        let empty: Vec<rch_common::WorkerConfig> = Vec::new();
        let diags = reliability_mirror_ownership_diagnostics(
            Some(&empty),
            None,
            Some(&Vec::new()),
            ProbeOutcome::Ok,
            None,
        );
        assert_eq!(diags.len(), 1);
        assert_eq!(
            diags[0].code,
            ReliabilityReasonCode::MirrorOwnershipNoWorkers
        );
        assert_eq!(diags[0].severity, ReliabilitySeverity::Info);

        let config_err = reliability_mirror_ownership_diagnostics(
            None,
            Some("parse error".to_string()),
            None,
            ProbeOutcome::Ok,
            None,
        );
        assert_eq!(config_err.len(), 1);
        assert_eq!(
            config_err[0].code,
            ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable
        );
        assert!(
            config_err[0]
                .details
                .as_deref()
                .unwrap_or_default()
                .contains("parse error")
        );

        let root_err = reliability_mirror_ownership_diagnostics(
            None,
            None,
            None,
            ProbeOutcome::Ok,
            Some(&"toml broken".to_string()),
        );
        assert_eq!(root_err.len(), 1);
        assert_eq!(
            root_err[0].code,
            ReliabilityReasonCode::WorkerMirrorOwnershipUnprobeable
        );
    }

    #[test]
    fn aggregate_verdict_is_healthy_for_empty_and_pass_info() {
        assert_eq!(aggregate_verdict(&[]), ReliabilityVerdict::Healthy);
        let diags = vec![
            diag(
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::StatusSurfaceAvailable,
            ),
            diag(
                ReliabilitySeverity::Info,
                ReliabilityReasonCode::DiskPressureNoWorkers,
            ),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Healthy);
    }

    #[test]
    fn aggregate_verdict_warning_is_degraded() {
        let diags = vec![
            diag(
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::StatusSurfaceAvailable,
            ),
            diag(
                ReliabilitySeverity::Warning,
                ReliabilityReasonCode::HookAutoStartDisabled,
            ),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Degraded);
    }

    #[test]
    fn aggregate_verdict_critical_dominates_warning_regardless_of_order() {
        let warn = diag(
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::HookAutoStartDisabled,
        );
        let crit = diag(
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::NoWorkersConfigured,
        );
        assert_eq!(
            aggregate_verdict(&[warn.clone(), crit.clone()]),
            ReliabilityVerdict::Failing
        );
        // Order independence: critical still wins when it comes first.
        assert_eq!(
            aggregate_verdict(&[crit, warn]),
            ReliabilityVerdict::Failing
        );
    }

    #[test]
    fn reliability_severity_token_maps_all_severities() {
        assert_eq!(
            reliability_severity_token(ReliabilitySeverity::Pass),
            "pass"
        );
        assert_eq!(
            reliability_severity_token(ReliabilitySeverity::Info),
            "info"
        );
        assert_eq!(
            reliability_severity_token(ReliabilitySeverity::Warning),
            "warning"
        );
        assert_eq!(
            reliability_severity_token(ReliabilitySeverity::Critical),
            "critical"
        );
    }

    #[test]
    fn hook_consistency_pass_when_hook_present_and_socket_matches() {
        let diags = reliability_hook_consistency_diagnostics(
            Some("/usr/local/bin/rch"),
            Some("/home/u/.cache/rch/rch.sock"),
            "/home/u/.cache/rch/rch.sock",
        );
        let hook = diags
            .iter()
            .find(|d| d.check_name == "hook_installed")
            .unwrap();
        assert_eq!(hook.severity, ReliabilitySeverity::Pass);
        assert_eq!(hook.code, ReliabilityReasonCode::HookInstalled);
        let socket = diags
            .iter()
            .find(|d| d.check_name == "socket_path")
            .unwrap();
        assert_eq!(socket.severity, ReliabilitySeverity::Pass);
        assert_eq!(socket.code, ReliabilityReasonCode::SocketPathConsistent);
    }

    #[test]
    fn hook_consistency_warns_with_remediation_when_hook_missing() {
        let diags = reliability_hook_consistency_diagnostics(None, None, "/c/rch.sock");
        let hook = diags
            .iter()
            .find(|d| d.check_name == "hook_installed")
            .unwrap();
        assert_eq!(hook.severity, ReliabilitySeverity::Warning);
        assert_eq!(hook.code, ReliabilityReasonCode::HookNotInstalled);
        assert_eq!(
            hook.remediation_command.as_deref(),
            Some("rch hook install")
        );
        // Absent config socket defaults to canonical => consistent.
        let socket = diags
            .iter()
            .find(|d| d.check_name == "socket_path")
            .unwrap();
        assert_eq!(socket.code, ReliabilityReasonCode::SocketPathConsistent);
    }

    #[test]
    fn hook_consistency_warns_on_socket_mismatch_with_realign_remediation() {
        let diags = reliability_hook_consistency_diagnostics(
            Some("rch"),
            Some("/tmp/custom.sock"),
            "/home/u/.cache/rch/rch.sock",
        );
        let socket = diags
            .iter()
            .find(|d| d.check_name == "socket_path")
            .unwrap();
        assert_eq!(socket.severity, ReliabilitySeverity::Warning);
        assert_eq!(socket.code, ReliabilityReasonCode::SocketPathMismatch);
        assert_eq!(
            socket.remediation_command.as_deref(),
            Some("rch config set general.socket_path /home/u/.cache/rch/rch.sock")
        );
    }

    #[test]
    fn hook_consistency_steps_are_manual_not_auto_fixable() {
        // Hook-install and socket-realign are operator actions: they must NOT
        // be auto-applied by --fix (which only flips idempotent self-healing
        // config); they surface as remediation-plan steps that are not
        // auto-fixable.
        assert!(auto_config_flip(ReliabilityReasonCode::HookNotInstalled).is_none());
        assert!(auto_config_flip(ReliabilityReasonCode::SocketPathMismatch).is_none());
        let diags =
            reliability_hook_consistency_diagnostics(None, Some("/tmp/x.sock"), "/c/rch.sock");
        let plan = build_reliability_remediation_plan(&diags);
        assert_eq!(plan.len(), 2, "both warnings become remediation steps");
        assert!(plan.iter().all(|s| !s.auto_fixable));
    }

    #[test]
    fn schema_compatibility_diagnostics_are_deterministic_and_categorised() {
        let a = reliability_schema_compatibility_diagnostics();
        let b = reliability_schema_compatibility_diagnostics();
        assert!(!a.is_empty(), "schema probe must emit diagnostics");
        assert_eq!(a.len(), b.len(), "schema probe must be deterministic");
        assert!(
            a.iter()
                .all(|d| d.category == ReliabilityCategory::SchemaCompatibility)
        );
    }

    #[test]
    fn rollout_posture_passes_when_self_healing_enabled() {
        let mut config = rch_common::RchConfig::default();
        config.self_healing.hook_starts_daemon = true;
        config.self_healing.daemon_installs_hooks = true;
        let diags = reliability_rollout_posture_diagnostics(Ok(&config));
        // The two self-healing toggles must be Pass; no auto-fix remediation.
        let hook = diags
            .iter()
            .find(|d| d.check_name == "hook_starts_daemon")
            .expect("hook diagnostic present");
        assert_eq!(hook.severity, ReliabilitySeverity::Pass);
        assert!(hook.remediation_command.is_none());
    }

    #[test]
    fn rollout_posture_warns_with_remediation_when_disabled() {
        let mut config = rch_common::RchConfig::default();
        config.self_healing.hook_starts_daemon = false;
        config.self_healing.daemon_installs_hooks = false;
        let diags = reliability_rollout_posture_diagnostics(Ok(&config));
        let hook = diags
            .iter()
            .find(|d| d.check_name == "hook_starts_daemon")
            .expect("hook diagnostic present");
        assert_eq!(hook.severity, ReliabilitySeverity::Warning);
        assert_eq!(
            hook.remediation_command.as_deref(),
            Some("rch config set self_healing.hook_starts_daemon true")
        );
        assert_eq!(hook.code, ReliabilityReasonCode::HookAutoStartDisabled);
    }

    #[test]
    fn rollout_posture_warns_on_config_load_failure() {
        let diags = reliability_rollout_posture_diagnostics(Err("boom"));
        let load = diags
            .iter()
            .find(|d| d.check_name == "config_load")
            .expect("config_load diagnostic present");
        assert_eq!(load.severity, ReliabilitySeverity::Warning);
        assert_eq!(load.code, ReliabilityReasonCode::ConfigLoadFailed);
    }

    #[test]
    fn build_response_counts_severities_and_defaults_fix_fields() {
        let scope = ReliabilityScopeSet::default();
        let diags = vec![
            diag(
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::StatusSurfaceAvailable,
            ),
            diag(
                ReliabilitySeverity::Warning,
                ReliabilityReasonCode::HookAutoStartDisabled,
            ),
            diag(
                ReliabilitySeverity::Critical,
                ReliabilityReasonCode::NoWorkersConfigured,
            ),
        ];
        let response =
            build_reliability_doctor_response(ReliabilityDoctorMode::Check, &scope, diags);
        assert_eq!(response.summary.total_checks, 3);
        assert_eq!(response.summary.pass, 1);
        assert_eq!(response.summary.warning, 1);
        assert_eq!(response.summary.critical, 1);
        assert_eq!(response.summary.overall, ReliabilityVerdict::Failing);
        // No daemon-unavailable codes => not flagged unreachable.
        assert!(!response.daemon_unreachable);
        // Fix scaffolding defaults until the executor / caller set them.
        assert!(!response.fix_requested);
        assert!(response.remediation_outcomes.is_empty());
    }

    #[test]
    fn build_response_flags_daemon_unreachable_from_reason_codes() {
        let scope = ReliabilityScopeSet::default();
        let diags = vec![diag(
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::DaemonStatusUnavailable,
        )];
        let response =
            build_reliability_doctor_response(ReliabilityDoctorMode::Check, &scope, diags);
        assert!(response.daemon_unreachable);
        assert_eq!(response.daemon_unreachable_reasons.len(), 1);
    }

    #[test]
    fn remediation_plan_orders_critical_before_warning_and_skips_unactionable() {
        // Warning WITH remediation, Critical WITH remediation, Pass (ignored),
        // Warning WITHOUT remediation (ignored).
        let warn = ReliabilityDiagnostic::new(
            ReliabilityCategory::RolloutPosture,
            "warn_fix",
            ReliabilitySeverity::Warning,
            "warn",
            ReliabilityReasonCode::HookAutoStartDisabled,
        )
        .with_remediation("rch config set self_healing.hook_starts_daemon true", "v");
        let crit = ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            "crit_fix",
            ReliabilitySeverity::Critical,
            "crit",
            ReliabilityReasonCode::NoWorkersConfigured,
        )
        .with_remediation("rch workers init", "v");
        let pass = diag(
            ReliabilitySeverity::Pass,
            ReliabilityReasonCode::StatusSurfaceAvailable,
        );
        let warn_no_cmd = diag(
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::DaemonHookRepairDisabled,
        );

        let plan = build_reliability_remediation_plan(&[warn, crit, pass, warn_no_cmd]);
        assert_eq!(plan.len(), 2, "only actionable diagnostics become steps");
        // Critical sorts ahead of Warning and gets order 1.
        assert_eq!(plan[0].order, 1);
        assert_eq!(plan[0].code, ReliabilityReasonCode::NoWorkersConfigured);
        assert_eq!(plan[1].order, 2);
        assert_eq!(plan[1].code, ReliabilityReasonCode::HookAutoStartDisabled);
        // The hook flip is auto-fixable; the workers-add step is manual.
        assert!(!plan[0].auto_fixable);
        assert!(plan[1].auto_fixable);
    }

    #[test]
    fn topology_critical_when_worker_config_unreadable() {
        let diags =
            reliability_topology_diagnostics(None, None, Some("permission denied".to_string()));
        assert!(
            diags
                .iter()
                .any(|d| d.severity == ReliabilitySeverity::Critical
                    && d.code == ReliabilityReasonCode::WorkersConfigUnreadable)
        );
    }

    #[test]
    fn topology_critical_when_no_workers_configured() {
        let workers: Vec<rch_common::WorkerConfig> = Vec::new();
        let diags = reliability_topology_diagnostics(Some(&workers), None, None);
        assert!(
            diags
                .iter()
                .any(|d| d.severity == ReliabilitySeverity::Critical
                    && d.code == ReliabilityReasonCode::NoWorkersConfigured)
        );
    }

    #[test]
    fn topology_passes_worker_config_and_warns_on_missing_daemon() {
        let worker = rch_common::WorkerConfig {
            id: rch_common::WorkerId("worker-a".to_string()),
            ..Default::default()
        };
        let workers = vec![worker];
        let diags = reliability_topology_diagnostics(Some(&workers), None, None);
        assert!(
            diags.iter().any(
                |d| d.check_name == "workers_config" && d.severity == ReliabilitySeverity::Pass
            )
        );
        // Daemon status absent => a daemon_status warning is emitted.
        assert!(
            diags
                .iter()
                .any(|d| d.severity == ReliabilitySeverity::Warning
                    && d.code == ReliabilityReasonCode::DaemonStatusUnavailable)
        );
    }

    #[test]
    fn repo_diagnostics_unavailable_when_convergence_missing() {
        let diags = reliability_repo_diagnostics(None);
        assert!(
            diags
                .iter()
                .any(|d| d.code == ReliabilityReasonCode::RepoConvergenceUnavailable)
        );
    }

    #[test]
    fn disk_pressure_unavailable_when_status_missing() {
        let diags = reliability_disk_pressure_diagnostics(None);
        assert_eq!(diags.len(), 1);
        assert_eq!(diags[0].severity, ReliabilitySeverity::Warning);
        assert_eq!(
            diags[0].code,
            ReliabilityReasonCode::DiskPressureUnavailable
        );
    }

    #[test]
    fn disk_pressure_info_when_no_workers_report() {
        let status = daemon_status(0, 0, json!([]));
        let diags = reliability_disk_pressure_diagnostics(Some(&status));
        assert_eq!(diags.len(), 1);
        assert_eq!(diags[0].severity, ReliabilitySeverity::Info);
        assert_eq!(diags[0].code, ReliabilityReasonCode::DiskPressureNoWorkers);
    }

    #[test]
    fn disk_pressure_critical_for_worker_under_critical_pressure() {
        let status = daemon_status(
            1,
            1,
            json!([{
                "id": "worker-a",
                "host": "worker.example",
                "user": "ubuntu",
                "status": "ready",
                "circuit_state": "closed",
                "used_slots": 0,
                "total_slots": 8,
                "speed_score": 99.0,
                "last_error": null,
                "pressure_state": "critical",
                "pressure_reason_code": "disk_free_below_critical_gb"
            }]),
        );
        let diags = reliability_disk_pressure_diagnostics(Some(&status));
        assert!(
            diags
                .iter()
                .any(|d| d.severity == ReliabilitySeverity::Critical
                    && d.code == ReliabilityReasonCode::WorkerDiskPressureCritical)
        );
    }

    #[test]
    fn process_debt_unavailable_when_status_missing() {
        let diags = reliability_process_debt_diagnostics(None);
        assert!(
            diags
                .iter()
                .any(|d| d.code == ReliabilityReasonCode::ProcessDebtUnavailable)
        );
    }

    #[test]
    fn process_debt_emits_diagnostics_for_present_status() {
        let status = daemon_status(1, 1, json!([]));
        let diags = reliability_process_debt_diagnostics(Some(&status));
        assert!(!diags.is_empty());
        assert!(
            diags
                .iter()
                .all(|d| d.category == ReliabilityCategory::ProcessDebt)
        );
    }

    #[test]
    fn helper_compatibility_diagnostics_cover_helper_category() {
        let diags = reliability_helper_compatibility_diagnostics();
        assert!(!diags.is_empty());
        assert!(
            diags
                .iter()
                .all(|d| d.category == ReliabilityCategory::HelperCompatibility)
        );
    }

    // ========================
    // --fix remediation executor tests (bead 2s99h.12)
    // ========================

    #[test]
    fn auto_config_flip_maps_self_healing_codes_only() {
        let hook = auto_config_flip(ReliabilityReasonCode::HookAutoStartDisabled)
            .expect("hook auto-start disabled is auto-fixable");
        assert_eq!(hook.key, "self_healing.hook_starts_daemon");
        assert_eq!(hook.value, "true");

        let repair = auto_config_flip(ReliabilityReasonCode::DaemonHookRepairDisabled)
            .expect("daemon hook repair disabled is auto-fixable");
        assert_eq!(repair.key, "self_healing.daemon_installs_hooks");
        assert_eq!(repair.value, "true");

        // A code with no safe idempotent flip stays manual.
        assert!(auto_config_flip(ReliabilityReasonCode::NoWorkersConfigured).is_none());
    }

    #[test]
    fn config_flip_satisfied_reads_the_target_key() {
        let mut config = rch_common::RchConfig::default();
        config.self_healing.hook_starts_daemon = false;
        let flip = auto_config_flip(ReliabilityReasonCode::HookAutoStartDisabled).unwrap();
        assert!(!config_flip_satisfied(&config, flip));
        config.self_healing.hook_starts_daemon = true;
        assert!(config_flip_satisfied(&config, flip));
    }

    #[test]
    fn plan_auto_flip_covers_the_intent_execute_matrix() {
        // already-satisfied dominates regardless of preview.
        assert_eq!(plan_auto_flip(true, false), AutoFlipPlan::AlreadySatisfied);
        assert_eq!(plan_auto_flip(true, true), AutoFlipPlan::AlreadySatisfied);
        // not satisfied + preview => would-apply (no write).
        assert_eq!(plan_auto_flip(false, true), AutoFlipPlan::WouldApply);
        // not satisfied + execute => apply (write).
        assert_eq!(plan_auto_flip(false, false), AutoFlipPlan::Apply);
    }

    fn remediation_step(
        order: u32,
        code: ReliabilityReasonCode,
        command: &str,
    ) -> ReliabilityRemediationStep {
        ReliabilityRemediationStep {
            order,
            category: ReliabilityCategory::RolloutPosture,
            code,
            description: format!("step {order}"),
            command: command.to_string(),
            validation: "rch doctor --reliability --json".to_string(),
            requires_restart: false,
            dry_run_safe: true,
            auto_fixable: auto_config_flip(code).is_some(),
        }
    }

    fn response_with_plan(
        mode: ReliabilityDoctorMode,
        fix_requested: bool,
        plan: Vec<ReliabilityRemediationStep>,
    ) -> ReliabilityDoctorResponse {
        let scope = ReliabilityScopeSet::default();
        let mut response = build_reliability_doctor_response(mode, &scope, Vec::new());
        response.remediation_plan = plan;
        response.fix_requested = fix_requested;
        response
    }

    #[test]
    fn executor_is_noop_without_fix_requested() {
        // Plain --dry-run / --check: fix not requested => no outcomes, ever.
        let plan = vec![remediation_step(
            1,
            ReliabilityReasonCode::HookAutoStartDisabled,
            "rch config set self_healing.hook_starts_daemon true",
        )];
        let mut response = response_with_plan(ReliabilityDoctorMode::DryRun, false, plan);
        apply_reliability_remediations(&mut response);
        assert!(
            response.remediation_outcomes.is_empty(),
            "no fix requested must yield no outcomes"
        );
    }

    #[test]
    fn executor_preview_never_applies_and_classifies_manual_steps() {
        // --fix --dry-run (mode downgraded to DryRun, fix_requested=true).
        let plan = vec![
            remediation_step(
                1,
                ReliabilityReasonCode::HookAutoStartDisabled,
                "rch config set self_healing.hook_starts_daemon true",
            ),
            // A non-auto-fixable code -> Manual.
            remediation_step(
                2,
                ReliabilityReasonCode::NoWorkersConfigured,
                "rch workers init",
            ),
        ];
        let mut response = response_with_plan(ReliabilityDoctorMode::DryRun, true, plan);
        apply_reliability_remediations(&mut response);

        assert_eq!(response.remediation_outcomes.len(), 2);
        // The auto step is previewed, never applied (no disk write in DryRun).
        // Ambient config decides would-apply vs already-satisfied; both are
        // valid "no mutation occurred" outcomes — never Applied/Failed.
        let auto = &response.remediation_outcomes[0];
        assert!(
            matches!(
                auto.status,
                RemediationOutcomeStatus::WouldApply | RemediationOutcomeStatus::AlreadySatisfied
            ),
            "preview auto step must not mutate: {:?}",
            auto.status
        );
        // The manual step is always Manual and carries the operator command.
        let manual = &response.remediation_outcomes[1];
        assert_eq!(manual.status, RemediationOutcomeStatus::Manual);
        assert_eq!(manual.command, "rch workers init");
    }

    #[test]
    fn remediation_plan_marks_auto_fixable_steps() {
        let diag = ReliabilityDiagnostic::new(
            ReliabilityCategory::RolloutPosture,
            "hook_starts_daemon",
            ReliabilitySeverity::Warning,
            "Hook auto-start is disabled",
            ReliabilityReasonCode::HookAutoStartDisabled,
        )
        .with_remediation(
            "rch config set self_healing.hook_starts_daemon true",
            "rch config get self_healing.hook_starts_daemon --json",
        );
        let plan = build_reliability_remediation_plan(&[diag]);
        assert_eq!(plan.len(), 1);
        assert!(plan[0].auto_fixable);
        assert_eq!(plan[0].code, ReliabilityReasonCode::HookAutoStartDisabled);
    }

    #[test]
    fn test_worker_topology_known_non_ready_status_is_degraded() {
        for status in ["degraded", "draining", "drained", "disabled", "busy"] {
            let worker = worker_status("worker-a", status, "closed");
            let diagnostic = worker_topology_diagnostic(&worker);

            assert_eq!(diagnostic.severity, ReliabilitySeverity::Warning);
            assert_eq!(diagnostic.code, ReliabilityReasonCode::WorkerDegraded);
            assert!(
                diagnostic.message.contains(status),
                "message should preserve the known non-ready status, got: {}",
                diagnostic.message
            );
        }
    }

    #[test]
    fn test_worker_topology_unknown_status_reports_protocol_drift() {
        let worker = worker_status("worker-a", "parked", "closed");
        let diagnostic = worker_topology_diagnostic(&worker);

        assert_eq!(diagnostic.severity, ReliabilitySeverity::Warning);
        assert_eq!(
            diagnostic.code,
            ReliabilityReasonCode::WorkerStatusUnrecognized
        );
        assert!(
            diagnostic.message.contains("status is unrecognized"),
            "unexpected message: {}",
            diagnostic.message
        );
    }

    // ========================================================================
    // t07 — defensive parsers for worker.ready_status + circuit_state.
    // Pure-function tests (no doctor/daemon harness) for the parser
    // contracts that drive worker_topology_diagnostic.
    // ========================================================================

    #[test]
    fn test_parse_ready_status_known_ready_variants() {
        for v in ["healthy", "available", "ready", "idle", "running"] {
            assert_eq!(
                parse_worker_ready_status(v),
                ParsedStatus::Known(KnownStatus::Ready),
                "{v} should parse as Ready"
            );
        }
    }

    #[test]
    fn test_parse_ready_status_known_degraded_variants() {
        for v in [
            "busy",
            "degraded",
            "draining",
            "drained",
            "disabled",
            "unhealthy",
        ] {
            assert_eq!(
                parse_worker_ready_status(v),
                ParsedStatus::Known(KnownStatus::Degraded),
                "{v} should parse as Degraded"
            );
        }
    }

    #[test]
    fn test_parse_ready_status_known_unreachable_variants() {
        for v in ["unreachable", "offline", "error", "failed"] {
            assert_eq!(
                parse_worker_ready_status(v),
                ParsedStatus::Known(KnownStatus::Unreachable),
                "{v} should parse as Unreachable"
            );
        }
    }

    #[test]
    fn test_parse_ready_status_trims_and_lowers() {
        // Whitespace + casing variations all hit the same bucket.
        for v in [
            "  healthy  ",
            "\tHealthy\n",
            "READY",
            "  Ready ",
            "\u{00A0}healthy\u{00A0}", // non-breaking space (Rust trim handles)
        ] {
            assert_eq!(
                parse_worker_ready_status(v),
                ParsedStatus::Known(KnownStatus::Ready),
                "{v:?} should normalize to Ready"
            );
        }
    }

    #[test]
    fn test_parse_ready_status_unknown_preserves_normalized_input() {
        // The Unrecognized variant carries the trim+lowered value so the
        // resulting diagnostic can surface it to operators.
        assert_eq!(
            parse_worker_ready_status("  PARKED  "),
            ParsedStatus::Unrecognized("parked".to_string())
        );
    }

    #[test]
    fn test_parse_ready_status_empty_string_unrecognized() {
        assert_eq!(
            parse_worker_ready_status(""),
            ParsedStatus::Unrecognized(String::new())
        );
        assert_eq!(
            parse_worker_ready_status("   \t  "),
            ParsedStatus::Unrecognized(String::new())
        );
    }

    #[test]
    fn test_parse_circuit_state_known_variants() {
        assert_eq!(
            parse_worker_circuit_state("closed"),
            ParsedCircuit::Known(KnownCircuit::Closed)
        );
        assert_eq!(
            parse_worker_circuit_state("open"),
            ParsedCircuit::Known(KnownCircuit::Open)
        );
        assert_eq!(
            parse_worker_circuit_state("half_open"),
            ParsedCircuit::Known(KnownCircuit::HalfOpen)
        );
        // dash form also accepted (some serializers use it).
        assert_eq!(
            parse_worker_circuit_state("half-open"),
            ParsedCircuit::Known(KnownCircuit::HalfOpen)
        );
    }

    #[test]
    fn test_parse_circuit_state_trims_and_lowers() {
        for v in ["  Open  ", "\tOPEN\n", "OPEN"] {
            assert_eq!(
                parse_worker_circuit_state(v),
                ParsedCircuit::Known(KnownCircuit::Open),
                "{v:?} should normalize to Open"
            );
        }
    }

    #[test]
    fn test_parse_circuit_state_unknown_preserves_normalized() {
        // Forensics: Unrecognized carries the offending value.
        assert_eq!(
            parse_worker_circuit_state("OPEN_FORCED"),
            ParsedCircuit::Unrecognized("open_forced".to_string())
        );
        assert_eq!(
            parse_worker_circuit_state("closed_for_maintenance"),
            ParsedCircuit::Unrecognized("closed_for_maintenance".to_string())
        );
        assert_eq!(
            parse_worker_circuit_state(""),
            ParsedCircuit::Unrecognized(String::new())
        );
    }

    #[test]
    fn test_worker_topology_unknown_circuit_state_reports_protocol_drift() {
        // The conjugate of the existing ready_status test: unknown
        // circuit_state values must surface as Warning with the
        // dedicated reason code, never silently mapped to Pass.
        let worker = worker_status("worker-a", "healthy", "OPEN_FORCED");
        let diagnostic = worker_topology_diagnostic(&worker);

        assert_eq!(diagnostic.severity, ReliabilitySeverity::Warning);
        assert_eq!(
            diagnostic.code,
            ReliabilityReasonCode::WorkerCircuitStateUnrecognized
        );
        assert!(
            diagnostic.message.contains("circuit_state is unrecognized"),
            "unexpected message: {}",
            diagnostic.message
        );
    }

    #[test]
    fn test_worker_topology_circuit_unrecognized_dominates_status() {
        // When BOTH fields are unrecognized, circuit drift is reported
        // first (the match-arm ordering encodes operator priority).
        let worker = worker_status("worker-a", "parked", "UNKNOWN");
        let diagnostic = worker_topology_diagnostic(&worker);
        assert_eq!(
            diagnostic.code,
            ReliabilityReasonCode::WorkerCircuitStateUnrecognized
        );
    }

    #[test]
    fn test_read_config_capped_reader_rejects_bytes_past_cap() {
        let err = read_config_capped_from_reader(
            std::io::Cursor::new(b"abcd".to_vec()),
            3,
            "test config",
        )
        .expect_err("reader that yields more than the cap must be rejected");

        assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
        assert!(
            err.to_string().contains("exceeds 3-byte cap"),
            "unexpected error message: {err}"
        );
    }

    #[test]
    fn test_read_config_capped_reader_accepts_exact_cap() {
        let content =
            read_config_capped_from_reader(std::io::Cursor::new(b"abc".to_vec()), 3, "test config")
                .expect("reader at the cap should be accepted");

        assert_eq!(content, "abc");
    }

    #[test]
    fn test_schema_compatibility_diagnostic_flags_mismatch() {
        let diagnostic =
            schema_compatibility_diagnostic("status", "2.0.0", "1.0.0", "CLI status response");

        assert_eq!(
            diagnostic.category,
            ReliabilityCategory::SchemaCompatibility
        );
        assert_eq!(diagnostic.severity, ReliabilitySeverity::Critical);
        assert_eq!(diagnostic.code, ReliabilityReasonCode::SchemaIncompatible);
        assert_eq!(
            diagnostic.details.as_deref(),
            Some("expected=1.0.0, actual=2.0.0")
        );
        assert!(
            diagnostic.remediation_command.is_some(),
            "schema mismatch should include remediation"
        );
    }

    #[test]
    fn test_schema_compatibility_diagnostic_passes_match() {
        let diagnostic =
            schema_compatibility_diagnostic("status", "1.0.0", "1.0.0", "CLI status response");

        assert_eq!(diagnostic.severity, ReliabilitySeverity::Pass);
        assert_eq!(diagnostic.code, ReliabilityReasonCode::SchemaCompatible);
        assert_eq!(
            diagnostic.details.as_deref(),
            Some("schema_version=1.0.0 expected=1.0.0")
        );
        assert!(diagnostic.remediation_command.is_none());
    }

    #[test]
    fn test_schema_compatibility_diagnostics_use_pinned_expected_versions() {
        let diagnostics = reliability_schema_compatibility_diagnostics();

        assert_eq!(diagnostics.len(), 4);
        for check_name in [
            "doctor_reliability",
            "status",
            "repo_updater_contract",
            "process_triage_contract",
        ] {
            let diagnostic = diagnostics
                .iter()
                .find(|diagnostic| diagnostic.check_name == check_name);
            assert!(
                diagnostic.is_some(),
                "missing schema diagnostic for {check_name}"
            );
            let Some(diagnostic) = diagnostic else {
                return;
            };

            assert_eq!(diagnostic.severity, ReliabilitySeverity::Pass);
            assert_eq!(diagnostic.code, ReliabilityReasonCode::SchemaCompatible);
            assert!(
                diagnostic
                    .details
                    .as_deref()
                    .is_some_and(|details| details.ends_with(" expected=1.0.0")),
                "{check_name} should compare against this doctor's pinned expected schema version"
            );
        }
    }

    #[test]
    fn test_check_command_exists_which() {
        // 'which' should exist on most systems
        let result = check_command_exists("which", "which command");
        assert_eq!(result.status, CheckStatus::Pass);
    }

    #[test]
    fn test_check_command_exists_nonexistent() {
        let result = check_command_exists("totally_nonexistent_command_12345", "fake command");
        assert_eq!(result.status, CheckStatus::Fail);
        assert!(result.suggestion.is_some());
    }

    #[test]
    fn test_check_status_serialization() {
        let pass = serde_json::to_string(&CheckStatus::Pass).unwrap();
        assert_eq!(pass, "\"pass\"");

        let fail = serde_json::to_string(&CheckStatus::Fail).unwrap();
        assert_eq!(fail, "\"fail\"");
    }

    #[test]
    fn test_doctor_summary() {
        let summary = DoctorSummary {
            total: 10,
            passed: 7,
            warnings: 2,
            failed: 1,
            fixed: 0,
            would_fix: 0,
        };

        let json = serde_json::to_string(&summary).unwrap();
        assert!(json.contains("\"total\":10"));
        assert!(json.contains("\"passed\":7"));
    }

    #[test]
    fn test_evaluate_cancellation_health_fails_on_cleanup_failure() {
        let status: crate::status_types::DaemonFullStatusResponse = serde_json::from_value(json!({
            "daemon": {
                "pid": 1,
                "uptime_secs": 10,
                "version": "0.1.0",
                "socket_path": "/tmp/rch.sock",
                "started_at": "2026-01-01T00:00:00Z",
                "workers_total": 1,
                "workers_healthy": 1,
                "slots_total": 8,
                "slots_available": 4
            },
            "workers": [],
            "active_builds": [],
            "queued_builds": [],
            "recent_builds": [{
                "id": 9,
                "started_at": "2026-01-01T00:00:00Z",
                "completed_at": "2026-01-01T00:00:05Z",
                "project_id": "proj",
                "worker_id": "worker-a",
                "command": "cargo test",
                "exit_code": 130,
                "duration_ms": 5000,
                "location": "remote",
                "bytes_transferred": 1024,
                "timing": null,
                "cancellation": {
                    "operation_id": "cancel-9",
                    "origin": "timeout",
                    "reason_code": "timeout",
                    "decision_path": ["requested", "term_sent", "remote_kill_sent", "escalated", "completed"],
                    "escalation_stage": "sigkill",
                    "escalation_count": 2,
                    "remote_kill_attempted": true,
                    "cleanup_ok": false,
                    "history_cancelled": true,
                    "final_state": "completed",
                    "worker_health": {
                        "status": "unreachable",
                        "speed_score": 0.0,
                        "used_slots": 4,
                        "available_slots": 0,
                        "pressure_state": "critical",
                        "pressure_reason_code": "disk_free_below_critical_gb"
                    }
                }
            }],
            "issues": [],
            "alerts": [],
            "stats": {
                "total_builds": 1,
                "success_count": 0,
                "failure_count": 1,
                "remote_count": 1,
                "local_count": 0,
                "avg_duration_ms": 5000
            },
            "test_stats": null,
            "saved_time": null
        }))
        .expect("status json should parse");

        let result = evaluate_cancellation_health(&status);
        assert_eq!(result.status, CheckStatus::Fail);
        assert!(result.message.contains("cleanup failures"));
    }

    #[test]
    fn test_evaluate_cancellation_health_passes_on_clean_cancel() {
        let status: crate::status_types::DaemonFullStatusResponse = serde_json::from_value(json!({
            "daemon": {
                "pid": 1,
                "uptime_secs": 10,
                "version": "0.1.0",
                "socket_path": "/tmp/rch.sock",
                "started_at": "2026-01-01T00:00:00Z",
                "workers_total": 1,
                "workers_healthy": 1,
                "slots_total": 8,
                "slots_available": 4
            },
            "workers": [],
            "active_builds": [],
            "queued_builds": [],
            "recent_builds": [{
                "id": 10,
                "started_at": "2026-01-01T00:00:00Z",
                "completed_at": "2026-01-01T00:00:03Z",
                "project_id": "proj",
                "worker_id": "worker-a",
                "command": "cargo check",
                "exit_code": 130,
                "duration_ms": 3000,
                "location": "remote",
                "bytes_transferred": 1024,
                "timing": null,
                "cancellation": {
                    "operation_id": "cancel-10",
                    "origin": "user",
                    "reason_code": "user",
                    "decision_path": ["requested", "term_sent", "completed"],
                    "escalation_stage": "term",
                    "escalation_count": 0,
                    "remote_kill_attempted": false,
                    "cleanup_ok": true,
                    "history_cancelled": true,
                    "final_state": "completed",
                    "worker_health": {
                        "status": "healthy",
                        "speed_score": 97.2,
                        "used_slots": 0,
                        "available_slots": 8,
                        "pressure_state": "healthy",
                        "pressure_reason_code": "healthy"
                    }
                }
            }],
            "issues": [],
            "alerts": [],
            "stats": {
                "total_builds": 1,
                "success_count": 0,
                "failure_count": 1,
                "remote_count": 1,
                "local_count": 0,
                "avg_duration_ms": 3000
            },
            "test_stats": null,
            "saved_time": null
        }))
        .expect("status json should parse");

        let result = evaluate_cancellation_health(&status);
        assert_eq!(result.status, CheckStatus::Pass);
        assert!(result.message.contains("deterministic cleanup"));
    }

    #[test]
    fn test_quick_check_result_is_healthy() {
        let healthy = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(healthy.is_healthy());

        let no_daemon = QuickCheckResult {
            daemon_running: false,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(!no_daemon.is_healthy());

        let no_workers = QuickCheckResult {
            daemon_running: true,
            worker_count: 0,
            workers_healthy: None,
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(!no_workers.is_healthy());

        let no_hook = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: false,
            warnings: vec![],
            errors: vec![],
        };
        assert!(!no_hook.is_healthy());

        let with_warning = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec!["Worker health stale".to_string()],
            errors: vec![],
        };
        assert!(
            !with_warning.is_healthy(),
            "warnings are issues and must not report full quick-check health"
        );
    }

    #[test]
    fn test_quick_check_result_has_issues() {
        let no_issues = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(!no_issues.has_issues());

        let with_warnings = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec!["Some warning".to_string()],
            errors: vec![],
        };
        assert!(with_warnings.has_issues());

        let with_errors = QuickCheckResult {
            daemon_running: true,
            worker_count: 1,
            workers_healthy: Some(1),
            hook_installed: true,
            warnings: vec![],
            errors: vec!["Some error".to_string()],
        };
        assert!(with_errors.has_issues());
    }

    #[test]
    fn test_run_quick_check_returns_result() {
        // This test just verifies that run_quick_check executes without panicking
        // and returns a valid result structure
        let result = run_quick_check();
        // We can't assert on specific values because they depend on system state,
        // but we can verify the result is accessible and properly structured
        let _total_issues = result.warnings.len() + result.errors.len();
    }

    // =========================================================================
    // t03 — run_quick_check contract: Option<usize> for workers_healthy +
    // honest "unknown" signal + is_healthy() never defaults to success.
    // =========================================================================

    #[test]
    fn test_quick_check_unknown_workers_health_is_not_healthy() {
        // The bead's headline regression: workers_healthy=None must
        // never be treated as healthy. Even if everything else is ok,
        // unknown worker state means "not healthy until probed".
        let unknown = QuickCheckResult {
            daemon_running: true,
            worker_count: 3,
            workers_healthy: None, // not probed
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(
            !unknown.is_healthy(),
            "is_healthy() must NOT return true when workers_healthy is None"
        );
    }

    #[test]
    fn test_quick_check_partial_health_is_not_healthy() {
        // 5 workers configured, only 3 probed healthy: definitively NOT healthy.
        let partial = QuickCheckResult {
            daemon_running: true,
            worker_count: 5,
            workers_healthy: Some(3),
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(!partial.is_healthy());
    }

    #[test]
    fn test_quick_check_full_health_is_healthy() {
        // worker_count == workers_healthy.unwrap() AND everything else ok.
        let full = QuickCheckResult {
            daemon_running: true,
            worker_count: 3,
            workers_healthy: Some(3),
            hook_installed: true,
            warnings: vec![],
            errors: vec![],
        };
        assert!(full.is_healthy());
    }

    #[test]
    fn test_quick_check_does_not_default_to_success() {
        // Explicit regression for the original bug: the prior code had
        //   Ok(workers) => (workers.len(), workers.len()) // assume healthy
        // which silently treated configured workers as healthy. Now we
        // require an explicit Some(n) AND n == worker_count for is_healthy()
        // to return true. NO path through run_quick_check() can satisfy
        // this without an honest probe.
        let result = run_quick_check();
        // Since run_quick_check is fast-only (no network probes), it
        // CANNOT report Some(_) for workers_healthy. The contract is
        // verified by the implementation: workers_healthy is always None.
        assert_eq!(
            result.workers_healthy, None,
            "fast-only run_quick_check must report unknown worker health"
        );
        // Confirms is_healthy() returns false for fast-only checks.
        assert!(
            !result.is_healthy(),
            "fast-only check must never report healthy without a probe"
        );
    }

    #[test]
    fn test_quick_check_emits_warning_about_unprobed_workers() {
        // When worker_count > 0 but workers_healthy is None, surface a
        // warning so operators understand they ran a fast-check, not a
        // real probe. (Only fires if there are configured workers; an
        // empty fleet is reported via "No workers configured" warning.)
        // Since we can't easily inject a fake fleet here, we test the
        // logic at the struct level: build a synthetic result and
        // verify the warning text would be emitted.
        let r = QuickCheckResult {
            daemon_running: true,
            worker_count: 3,
            workers_healthy: None,
            hook_installed: true,
            warnings: vec![
                "Worker health not probed by quick-check; run `rch doctor --reliability` for full status".to_string(),
            ],
            errors: vec![],
        };
        assert!(
            r.warnings.iter().any(|w| w.contains("not probed")),
            "expected fast-check to surface 'not probed' warning"
        );
        // is_healthy still returns false because workers_healthy is None.
        assert!(!r.is_healthy());
    }

    // =========================================================================
    // Individual Check Tests
    // =========================================================================

    #[test]
    fn test_check_config_directory_with_existing_dir() {
        // TEST START: check_config_directory with existing directory
        // This test verifies config directory check handles existing directories
        let result = check_config_directory();
        // Config directory check should return a valid result regardless of state
        assert!(
            matches!(
                result.status,
                CheckStatus::Pass | CheckStatus::Warning | CheckStatus::Fail
            ),
            "Config directory check returned unexpected status"
        );
        assert_eq!(result.category, "configuration");
        assert_eq!(result.name, "config_directory");
        // TEST PASS: check_config_directory
    }

    #[test]
    fn test_check_config_file_structure() {
        // TEST START: check_config_file structure validation
        let result = check_config_file();
        assert_eq!(result.category, "configuration");
        assert_eq!(result.name, "config.toml");
        // Check that we get valid status and proper field population
        assert!(
            matches!(
                result.status,
                CheckStatus::Pass | CheckStatus::Warning | CheckStatus::Fail | CheckStatus::Skipped
            ),
            "Config file check returned unexpected status"
        );
        // If skipped, should have appropriate message
        if result.status == CheckStatus::Skipped {
            assert!(result.message.contains("Skipped"));
        }
        // TEST PASS: check_config_file structure
    }

    #[test]
    fn test_check_workers_file_structure() {
        // TEST START: check_workers_file structure validation
        let result = check_workers_file();
        assert_eq!(result.category, "configuration");
        assert_eq!(result.name, "workers.toml");
        // Should return valid CheckResult regardless of file existence
        assert!(
            matches!(
                result.status,
                CheckStatus::Pass | CheckStatus::Warning | CheckStatus::Fail | CheckStatus::Skipped
            ),
            "Workers file check returned unexpected status"
        );
        // TEST PASS: check_workers_file structure
    }

    #[test]
    fn test_check_ssh_config_returns_valid_result() {
        // TEST START: check_ssh_config validation
        let result = check_ssh_config();
        assert_eq!(result.category, "ssh");
        assert_eq!(result.name, "ssh_config");
        // SSH config is optional, so either Pass or Warning is acceptable
        assert!(
            matches!(result.status, CheckStatus::Pass | CheckStatus::Warning),
            "SSH config check should return Pass or Warning, got {:?}",
            result.status
        );
        // TEST PASS: check_ssh_config
    }

    #[test]
    fn test_check_claude_code_hook_returns_valid_result() {
        // TEST START: check_claude_code_hook validation
        let result = check_claude_code_hook();
        assert_eq!(result.category, "hooks");
        assert_eq!(result.name, "claude_code_hook");
        // Hook may or may not be installed
        assert!(
            matches!(
                result.status,
                CheckStatus::Pass | CheckStatus::Warning | CheckStatus::Fail
            ),
            "Claude Code hook check returned unexpected status"
        );
        // Should always have details pointing to settings path
        assert!(result.details.is_some() || result.status == CheckStatus::Fail);
        // TEST PASS: check_claude_code_hook
    }

    #[test]
    fn test_check_command_exists_common_tools() {
        // TEST START: check_command_exists for common system tools
        // These should exist on any Unix-like system
        let tools = [
            ("ls", "List command"),
            ("cat", "Concatenate command"),
            ("echo", "Echo command"),
        ];

        for (cmd, desc) in tools {
            let result = check_command_exists(cmd, desc);
            assert_eq!(
                result.status,
                CheckStatus::Pass,
                "Expected {} to exist on system",
                cmd
            );
            assert_eq!(result.category, "prerequisites");
            assert_eq!(result.name, cmd);
            assert!(result.message.contains("installed"));
        }
        // TEST PASS: check_command_exists for common tools
    }

    #[test]
    fn test_check_command_exists_returns_version_info() {
        // TEST START: check_command_exists captures version info
        let result = check_command_exists("ls", "List command");
        if result.status == CheckStatus::Pass {
            // Most tools return version info, but some may not
            // We just verify the field exists
            let _ = &result.details;
        }
        // TEST PASS: check_command_exists version info
    }

    #[test]
    fn test_check_command_exists_provides_suggestion_for_missing() {
        // TEST START: check_command_exists suggestions for missing commands
        let result = check_command_exists("rch_nonexistent_test_cmd_xyz", "fake tool");
        assert_eq!(result.status, CheckStatus::Fail);
        assert!(
            result.suggestion.is_some(),
            "Missing command should provide installation suggestion"
        );
        assert!(
            result.suggestion.unwrap().contains("package manager"),
            "Suggestion should mention package manager"
        );
        // TEST PASS: check_command_exists suggestions
    }

    // =========================================================================
    // CheckResult Structure Tests
    // =========================================================================

    #[test]
    fn test_check_result_json_serialization() {
        // TEST START: CheckResult JSON serialization
        let result = CheckResult {
            category: "test".to_string(),
            name: "test_check".to_string(),
            status: CheckStatus::Pass,
            message: "Test passed".to_string(),
            details: Some("Extra details".to_string()),
            suggestion: None,
            fixable: false,
            fix_applied: false,
            fix_message: None,
        };

        let json = serde_json::to_string(&result).unwrap();
        assert!(json.contains("\"category\":\"test\""));
        assert!(json.contains("\"name\":\"test_check\""));
        assert!(json.contains("\"status\":\"pass\""));
        assert!(json.contains("\"message\":\"Test passed\""));
        assert!(json.contains("\"details\":\"Extra details\""));
        // Optional fields that are None should be skipped
        assert!(!json.contains("\"suggestion\":"));
        assert!(!json.contains("\"fix_message\":"));
        // TEST PASS: CheckResult JSON serialization
    }

    #[test]
    fn test_check_result_with_fix_info() {
        // TEST START: CheckResult with fix information
        let result = CheckResult {
            category: "ssh".to_string(),
            name: "key_permissions".to_string(),
            status: CheckStatus::Warning,
            message: "Loose permissions".to_string(),
            details: Some("/home/user/.ssh/id_ed25519".to_string()),
            suggestion: Some("chmod 600 /path/to/key".to_string()),
            fixable: true,
            fix_applied: true,
            fix_message: Some("Changed permissions to 0600".to_string()),
        };

        let json = serde_json::to_string(&result).unwrap();
        assert!(json.contains("\"fixable\":true"));
        assert!(json.contains("\"fix_applied\":true"));
        assert!(json.contains("\"fix_message\":"));
        // TEST PASS: CheckResult with fix info
    }

    #[test]
    fn test_all_check_statuses_serialize() {
        // TEST START: All CheckStatus variants serialize correctly
        let statuses = [
            (CheckStatus::Pass, "\"pass\""),
            (CheckStatus::Warning, "\"warning\""),
            (CheckStatus::Fail, "\"fail\""),
            (CheckStatus::Skipped, "\"skipped\""),
        ];

        for (status, expected) in statuses {
            let json = serde_json::to_string(&status).unwrap();
            assert_eq!(
                json, expected,
                "CheckStatus::{:?} serialized incorrectly",
                status
            );
        }
        // TEST PASS: All CheckStatus variants serialize
    }

    // =========================================================================
    // DoctorResponse Structure Tests
    // =========================================================================

    // =========================================================================
    // rsync prerequisite classification (issue #66)
    // =========================================================================

    fn resolved_rsync_fixture(flavor: RsyncFlavor, path: &str) -> ResolvedRsync {
        ResolvedRsync {
            path: PathBuf::from(path),
            flavor,
            version_line: "banner".to_string(),
            source: rch_common::rsync_flavor::RsyncSource::Path,
            shadowed: None,
        }
    }

    #[test]
    fn rsync_check_passes_cleanly_on_modern_rsync() {
        let check = classify_rsync_check(Ok(resolved_rsync_fixture(
            RsyncFlavor::Rsync {
                major: 3,
                minor: 4,
                patch: 1,
            },
            "/opt/homebrew/bin/rsync",
        )));
        assert_eq!(check.category, "prerequisites");
        assert_eq!(check.name, "rsync");
        assert_eq!(check.status, CheckStatus::Pass);
        assert!(check.suggestion.is_none(), "{:?}", check.suggestion);
        let details = check.details.expect("details");
        assert!(details.contains("rsync 3.4.1"), "{details}");
        assert!(details.contains("/opt/homebrew/bin/rsync"), "{details}");
        assert!(!check.fixable);
    }

    #[test]
    fn rsync_check_reports_shadowed_path_binary() {
        let mut resolved = resolved_rsync_fixture(
            RsyncFlavor::Rsync {
                major: 3,
                minor: 4,
                patch: 1,
            },
            "/opt/homebrew/bin/rsync",
        );
        resolved.source = rch_common::rsync_flavor::RsyncSource::PreferredLocation;
        resolved.shadowed = Some(rch_common::rsync_flavor::ShadowedRsync {
            path: PathBuf::from("/usr/bin/rsync"),
            flavor: RsyncFlavor::OpenRsync { protocol: Some(29) },
        });
        let check = classify_rsync_check(Ok(resolved));
        assert_eq!(check.status, CheckStatus::Pass);
        let details = check.details.expect("details");
        assert!(
            details.contains("PATH rsync is openrsync (protocol 29) at /usr/bin/rsync"),
            "{details}"
        );
    }

    #[test]
    fn rsync_check_passes_openrsync_in_compatibility_mode_with_remedy() {
        let check = classify_rsync_check(Ok(resolved_rsync_fixture(
            RsyncFlavor::OpenRsync { protocol: Some(29) },
            "/usr/bin/rsync",
        )));
        assert_eq!(check.status, CheckStatus::Pass);
        assert!(
            check.message.contains("compatibility mode"),
            "{}",
            check.message
        );
        assert!(
            check.message.contains("openrsync (protocol 29)"),
            "{}",
            check.message
        );
        let suggestion = check.suggestion.expect("remedy hint");
        assert!(
            suggestion.contains("--progress --stats -vv"),
            "{suggestion}"
        );
        assert!(suggestion.contains("install"), "{suggestion}");
        if cfg!(target_os = "macos") {
            assert!(suggestion.contains("brew install rsync"), "{suggestion}");
        }
    }

    #[test]
    fn rsync_check_warns_on_unrecognized_banner() {
        let check = classify_rsync_check(Ok(resolved_rsync_fixture(
            RsyncFlavor::Unknown,
            "/usr/local/bin/rsync",
        )));
        assert_eq!(check.status, CheckStatus::Warning);
        assert!(
            check.message.contains("could not be determined"),
            "{}",
            check.message
        );
        let suggestion = check.suggestion.expect("hint");
        assert!(suggestion.contains("rsync_bin"), "{suggestion}");
    }

    #[test]
    fn rsync_check_fails_on_too_old_rsync() {
        let check = classify_rsync_check(Ok(resolved_rsync_fixture(
            RsyncFlavor::Rsync {
                major: 2,
                minor: 5,
                patch: 7,
            },
            "/usr/bin/rsync",
        )));
        assert_eq!(check.status, CheckStatus::Fail);
        assert!(check.message.contains("too old"), "{}", check.message);
        assert!(check.message.contains("2.6.9"), "{}", check.message);
    }

    #[test]
    fn rsync_check_fails_when_missing_or_misconfigured() {
        let missing = classify_rsync_check(Err(RsyncResolveError::NotFound));
        assert_eq!(missing.status, CheckStatus::Fail);
        assert_eq!(missing.message, "File synchronization not found");
        assert!(missing.suggestion.expect("hint").contains("Install rsync"));

        let bad_override = classify_rsync_check(Err(RsyncResolveError::OverrideMissing {
            origin: rch_common::rsync_flavor::RsyncSource::Config,
            path: PathBuf::from("/nonexistent/rsync"),
        }));
        assert_eq!(bad_override.status, CheckStatus::Fail);
        assert!(
            bad_override.message.contains("configured rsync"),
            "{}",
            bad_override.message
        );
        let hint = bad_override.suggestion.expect("hint");
        assert!(hint.contains("[transfer] rsync_bin"), "{hint}");
        let details = bad_override.details.expect("details");
        assert!(details.contains("/nonexistent/rsync"), "{details}");

        let broken = classify_rsync_check(Err(RsyncResolveError::ProbeFailed {
            path: PathBuf::from("/usr/bin/rsync"),
            reason: "timed out after 5s".to_string(),
        }));
        assert_eq!(broken.status, CheckStatus::Fail);
        assert!(broken.message.contains("--version"), "{}", broken.message);
        assert!(broken.details.expect("details").contains("timed out"));
    }

    #[test]
    fn test_doctor_response_serialization() {
        // TEST START: DoctorResponse full serialization
        let response = DoctorResponse {
            schema_version: "1.0.0".to_string(),
            checks: vec![
                CheckResult {
                    category: "prerequisites".to_string(),
                    name: "rsync".to_string(),
                    status: CheckStatus::Pass,
                    message: "rsync is installed".to_string(),
                    details: Some("rsync version 3.2.7".to_string()),
                    suggestion: None,
                    fixable: false,
                    fix_applied: false,
                    fix_message: None,
                },
                CheckResult {
                    category: "configuration".to_string(),
                    name: "config.toml".to_string(),
                    status: CheckStatus::Warning,
                    message: "config.toml not found".to_string(),
                    details: None,
                    suggestion: Some("Run rch config init".to_string()),
                    fixable: true,
                    fix_applied: false,
                    fix_message: None,
                },
            ],
            summary: DoctorSummary {
                total: 2,
                passed: 1,
                warnings: 1,
                failed: 0,
                fixed: 0,
                would_fix: 0,
            },
            fixes_applied: vec![],
        };

        let json = serde_json::to_string(&response).unwrap();
        assert!(json.contains("\"checks\":["));
        assert!(json.contains("\"summary\":{"));
        assert!(json.contains("\"fixes_applied\":[]"));
        // TEST PASS: DoctorResponse serialization
    }

    #[test]
    fn test_doctor_response_with_fixes() {
        // TEST START: DoctorResponse with applied fixes
        let response = DoctorResponse {
            schema_version: "1.0.0".to_string(),
            checks: vec![],
            summary: DoctorSummary {
                total: 1,
                passed: 1,
                warnings: 0,
                failed: 0,
                fixed: 1,
                would_fix: 0,
            },
            fixes_applied: vec![FixApplied {
                check_name: "ssh_key_perms".to_string(),
                action: "Changed permissions to 0600".to_string(),
                success: true,
                error: None,
            }],
        };

        let json = serde_json::to_string(&response).unwrap();
        assert!(json.contains("\"fixes_applied\":[{"));
        assert!(json.contains("\"check_name\":\"ssh_key_perms\""));
        assert!(json.contains("\"success\":true"));
        // TEST PASS: DoctorResponse with fixes
    }

    // =========================================================================
    // Fix Applied Structure Tests
    // =========================================================================

    #[test]
    fn test_fix_applied_success() {
        // TEST START: FixApplied success case
        let fix = FixApplied {
            check_name: "id_ed25519".to_string(),
            action: "Changed permissions from 0644 to 0600".to_string(),
            success: true,
            error: None,
        };

        let json = serde_json::to_string(&fix).unwrap();
        assert!(json.contains("\"success\":true"));
        assert!(!json.contains("\"error\""));
        // TEST PASS: FixApplied success
    }

    #[test]
    fn test_fix_applied_failure() {
        // TEST START: FixApplied failure case
        let fix = FixApplied {
            check_name: "id_rsa".to_string(),
            action: "Attempted to change permissions".to_string(),
            success: false,
            error: Some("Permission denied".to_string()),
        };

        let json = serde_json::to_string(&fix).unwrap();
        assert!(json.contains("\"success\":false"));
        assert!(json.contains("\"error\":\"Permission denied\""));
        // TEST PASS: FixApplied failure
    }

    // =========================================================================
    // DoctorOptions Tests
    // =========================================================================

    #[test]
    fn test_doctor_options_default_values() {
        // TEST START: DoctorOptions can be constructed with various combinations
        let opts_minimal = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        assert!(!opts_minimal.fix);
        assert!(!opts_minimal.dry_run);

        let opts_fix = DoctorOptions {
            fix: true,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        assert!(opts_fix.fix);

        let opts_dry_run = DoctorOptions {
            fix: true,
            dry_run: true,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        assert!(opts_dry_run.fix);
        assert!(opts_dry_run.dry_run);

        let opts_verbose = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: true,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        assert!(opts_verbose.verbose);
        // TEST PASS: DoctorOptions construction
    }

    // =========================================================================
    // DoctorSummary Tests
    // =========================================================================

    #[test]
    fn test_doctor_summary_all_passed() {
        // TEST START: DoctorSummary all checks passed
        let summary = DoctorSummary {
            total: 15,
            passed: 15,
            warnings: 0,
            failed: 0,
            fixed: 0,
            would_fix: 0,
        };

        let json = serde_json::to_string(&summary).unwrap();
        assert!(json.contains("\"total\":15"));
        assert!(json.contains("\"passed\":15"));
        assert!(json.contains("\"failed\":0"));
        // TEST PASS: DoctorSummary all passed
    }

    #[test]
    fn test_doctor_summary_with_failures() {
        // TEST START: DoctorSummary with failures
        let summary = DoctorSummary {
            total: 10,
            passed: 5,
            warnings: 2,
            failed: 3,
            fixed: 0,
            would_fix: 0,
        };

        // Verify counts add up
        assert_eq!(
            summary.passed + summary.warnings + summary.failed,
            summary.total
        );
        // TEST PASS: DoctorSummary with failures
    }

    #[test]
    fn test_doctor_summary_with_fixes() {
        // TEST START: DoctorSummary tracking fixes
        let summary = DoctorSummary {
            total: 10,
            passed: 8,
            warnings: 0,
            failed: 0,
            fixed: 2,
            would_fix: 0,
        };

        let json = serde_json::to_string(&summary).unwrap();
        assert!(json.contains("\"fixed\":2"));
        // TEST PASS: DoctorSummary with fixes
    }

    #[test]
    fn test_doctor_summary_dry_run_would_fix() {
        // TEST START: DoctorSummary dry run would_fix count
        let summary = DoctorSummary {
            total: 10,
            passed: 7,
            warnings: 3,
            failed: 0,
            fixed: 0,
            would_fix: 3,
        };

        let json = serde_json::to_string(&summary).unwrap();
        assert!(json.contains("\"would_fix\":3"));
        // TEST PASS: DoctorSummary dry run
    }

    // =========================================================================
    // QuickCheckResult Extended Tests
    // =========================================================================

    #[test]
    fn test_quick_check_result_multiple_issues() {
        // TEST START: QuickCheckResult with multiple issues
        let result = QuickCheckResult {
            daemon_running: false,
            worker_count: 0,
            workers_healthy: None,
            hook_installed: false,
            warnings: vec![
                "Daemon not running".to_string(),
                "No workers configured".to_string(),
            ],
            errors: vec!["Hook not installed".to_string()],
        };

        assert!(!result.is_healthy());
        assert!(result.has_issues());
        assert_eq!(result.warnings.len(), 2);
        assert_eq!(result.errors.len(), 1);
        // TEST PASS: QuickCheckResult multiple issues
    }

    #[test]
    fn test_quick_check_result_partial_health() {
        // TEST START: QuickCheckResult partial health
        // Updated for t03 contract (2s99h.11): partial worker health is
        // NOT healthy. Previously this test asserted is_healthy()=true
        // with a warning, encoding the default-to-success behavior.
        // The new contract: workers_healthy < worker_count means the
        // system is NOT healthy.
        let result = QuickCheckResult {
            daemon_running: true,
            worker_count: 2,
            workers_healthy: Some(1), // Only 1 of 2 healthy
            hook_installed: true,
            warnings: vec!["Worker css is offline".to_string()],
            errors: vec![],
        };

        // Partial health is now NOT healthy (default-to-degraded discipline).
        assert!(
            !result.is_healthy(),
            "1/2 workers healthy must NOT report system-healthy"
        );
        assert!(result.has_issues());
        // TEST PASS: QuickCheckResult partial health
    }

    // =========================================================================
    // SSH Worker Suggestion Tests
    // =========================================================================

    #[test]
    fn test_ssh_worker_suggestion_format() {
        // TEST START: ssh_worker_suggestion generates correct commands
        let suggestion = ssh_worker_suggestion(
            "ubuntu",
            "build-server.local",
            Path::new("/home/user/.ssh/id_ed25519"),
        );

        // Should contain ssh-copy-id command
        assert!(
            suggestion.contains("ssh-copy-id"),
            "Should suggest ssh-copy-id"
        );
        // Should contain test command
        assert!(
            suggestion.contains("ssh -i"),
            "Should suggest testing with ssh -i"
        );
        // Should contain agent commands
        assert!(
            suggestion.contains("ssh-agent") && suggestion.contains("ssh-add"),
            "Should suggest ssh-agent setup"
        );
        // Should contain debug command
        assert!(suggestion.contains("-vvv"), "Should suggest verbose debug");
        // Should use correct user and host
        assert!(suggestion.contains("ubuntu@build-server.local"));
        // TEST PASS: ssh_worker_suggestion format
    }

    #[test]
    fn test_ssh_worker_suggestion_with_special_path() {
        // TEST START: ssh_worker_suggestion handles special paths
        let suggestion =
            ssh_worker_suggestion("admin", "192.168.1.100", Path::new("/custom/path/my_key"));

        assert!(suggestion.contains("/custom/path/my_key"));
        assert!(suggestion.contains("admin@192.168.1.100"));
        // TEST PASS: ssh_worker_suggestion special path
    }

    #[test]
    fn test_ssh_worker_suggestion_quotes_shell_metachars() {
        // TEST START: shell-injection defense — fields with `;`, `$`, etc.
        // must be shell-escaped so a hostile workers.toml cannot produce a
        // runnable destructive command when an agent copy-pastes the
        // suggestion.
        let suggestion = ssh_worker_suggestion(
            "evil; rm -rf ~",
            "host\"$(touch /tmp/pwned)",
            Path::new("/keys/with spaces/id"),
        );
        // The literal `; rm -rf ~` MUST NOT appear unquoted — it would
        // execute when the user pastes the string into a shell.
        // shell_escape::escape produces single-quoted strings for posix
        // shells; a string containing a single-quote is broken across
        // multiple quoted segments. Either way, the dangerous payload is
        // contained inside quoted/escaped boundaries.
        let dangerous_unquoted = "; rm -rf ~"; // the bare metachar sequence
        // We require that the dangerous sequence does NOT appear AT a
        // shell-relevant position — i.e., it must always be inside the
        // quoting that shell_escape produces. The simplest robust check:
        // the suggestion must contain the escape character or quoting
        // around the user field rather than a bare `;`.
        // shell_escape always outputs a fully-quoted form when the input
        // contains shell metachars; assert the input form is preserved
        // by counting that the dangerous chars are wrapped.
        let user_segment_starts = suggestion.find("evil").expect("user appears");
        // The character immediately preceding the user value must be `'`
        // (POSIX-shell single-quote escaping) or `"` (double-quote).
        let prev_char = suggestion[..user_segment_starts]
            .chars()
            .last()
            .expect("preceding char");
        assert!(
            matches!(prev_char, '\'' | '"'),
            "user field must be inside shell quoting; got prev_char={:?} in suggestion={}",
            prev_char,
            suggestion
        );
        // Strong safety property: passing the suggestion through `sh -n`
        // (parse-only) MUST succeed — i.e., it's syntactically valid
        // shell, no runaway `;` or unterminated quote. This catches any
        // future regression where the escaping breaks the syntax.
        let parse_check = std::process::Command::new("sh")
            .arg("-n")
            .arg("-c")
            .arg(&suggestion)
            .output();
        if let Ok(out) = parse_check {
            assert!(
                out.status.success(),
                "shell parse-only check failed for: {}\nstderr: {}",
                suggestion,
                String::from_utf8_lossy(&out.stderr)
            );
        }
        // The dangerous payload should never appear *unquoted* at a
        // statement boundary. If it did, the test_ssh_worker_suggestion
        // test would still pass (the substring is still in the string)
        // but the parse_check above would catch the syntax break.
        let _ = dangerous_unquoted; // referenced for clarity; not asserted directly.
        // TEST PASS: shell injection defense holds
    }

    // =========================================================================
    // Default Socket Path Tests
    // =========================================================================

    #[test]
    fn test_default_socket_path_returns_valid_path() {
        // TEST START: default_socket_path returns non-empty path
        let path = default_socket_path();
        assert!(
            !path.as_os_str().is_empty(),
            "Socket path should not be empty"
        );
        // Should end with a reasonable filename
        let filename = path.file_name().map(|f| f.to_string_lossy().to_string());
        assert!(
            filename.is_some(),
            "Socket path should have a filename component"
        );
        // TEST PASS: default_socket_path
    }

    #[test]
    fn test_configured_or_default_socket_path_uses_config_override() {
        // TEST START: doctor socket path follows active config
        let _guard = rch_common::test_guard!();
        struct ResetConfigOverride;
        impl Drop for ResetConfigOverride {
            fn drop(&mut self) {
                crate::config::set_test_config_override(None);
            }
        }

        let mut config = rch_common::RchConfig::default();
        config.general.socket_path = "/tmp/rch-doctor-custom.sock".to_string();
        crate::config::set_test_config_override(Some(config));
        let _reset = ResetConfigOverride;

        assert_eq!(
            configured_or_default_socket_path(),
            PathBuf::from("/tmp/rch-doctor-custom.sock")
        );
        // TEST PASS: active config socket path used
    }

    #[cfg(unix)]
    #[test]
    fn test_daemon_check_warns_on_stale_socket_file() {
        // TEST START: daemon check does not treat a stale socket file as running
        use crate::ui::context::{OutputConfig, OutputContext};

        let _guard = rch_common::test_guard!();
        struct ResetConfigOverride;
        impl Drop for ResetConfigOverride {
            fn drop(&mut self) {
                crate::config::set_test_config_override(None);
            }
        }

        let tmp = TempDir::new().unwrap();
        let socket_path = tmp.path().join("stale.sock");
        std::fs::write(&socket_path, "not a unix socket").unwrap();

        let mut config = rch_common::RchConfig::default();
        config.general.socket_path = socket_path.display().to_string();
        crate::config::set_test_config_override(Some(config));
        let _reset = ResetConfigOverride;

        let ctx = OutputContext::new(OutputConfig::default());
        let options = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        let mut checks = Vec::new();
        let mut fixes_applied = Vec::new();

        check_daemon(&mut checks, &ctx, &options, &mut fixes_applied);

        let daemon_socket = checks
            .iter()
            .find(|check| check.name == "daemon_socket")
            .expect("daemon socket check");
        assert_eq!(daemon_socket.status, CheckStatus::Warning);
        assert_eq!(
            daemon_socket.message,
            "Daemon socket is stale or unreachable"
        );
        // TEST PASS: stale socket is not a daemon pass
    }

    // =========================================================================
    // Integration-Style Tests (Still No Mocks)
    // =========================================================================

    #[test]
    fn test_prerequisite_checks_run_without_panic() {
        // TEST START: Prerequisites check runs safely
        use crate::ui::context::{OutputConfig, OutputContext};

        let ctx = OutputContext::new(OutputConfig::default());
        let options = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };

        let mut checks = Vec::new();
        // This should not panic regardless of system state
        check_prerequisites(&mut checks, &ctx, &options);

        // Should have checked at least the core tools (rsync, zstd, ssh, rustup, cargo)
        assert!(
            checks.len() >= 5,
            "Should check at least 5 prerequisite tools, got {}",
            checks.len()
        );

        // All results should have valid structure
        for check in &checks {
            assert_eq!(check.category, "prerequisites");
            assert!(!check.name.is_empty());
            assert!(!check.message.is_empty());
        }
        // TEST PASS: Prerequisites check runs
    }

    #[test]
    fn test_configuration_checks_run_without_panic() {
        // TEST START: Configuration checks run safely
        use crate::ui::context::{OutputConfig, OutputContext};

        let ctx = OutputContext::new(OutputConfig::default());
        let options = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };

        let mut checks = Vec::new();
        check_configuration(&mut checks, &ctx, &options);

        // Should check config directory, config.toml, workers.toml
        assert!(
            checks.len() >= 3,
            "Should check at least 3 config items, got {}",
            checks.len()
        );

        for check in &checks {
            assert_eq!(check.category, "configuration");
        }
        // TEST PASS: Configuration checks run
    }

    #[test]
    fn test_daemon_check_runs_without_panic() {
        // TEST START: Daemon check runs safely
        use crate::ui::context::{OutputConfig, OutputContext};

        let ctx = OutputContext::new(OutputConfig::default());
        let options = DoctorOptions {
            fix: false,
            dry_run: false,
            reliability: false,
            check_schemas: false,
            verbose: false,
            strict: false,
            lenient: false,
            scope: ReliabilityScopeSet::default(),
            watch: false,
            watch_interval_secs: 5,
            transitions_only: false,
            watch_snapshot: None,
        };
        let mut fixes_applied = Vec::new();

        let mut checks = Vec::new();
        check_daemon(&mut checks, &ctx, &options, &mut fixes_applied);

        // Should check at least daemon socket
        assert!(!checks.is_empty(), "Should have daemon checks");

        for check in &checks {
            assert_eq!(check.category, "daemon");
        }
        // TEST PASS: Daemon check runs
    }

    #[test]
    fn test_wait_for_socket_times_out() {
        // TEST START: wait_for_socket times out when socket never appears
        let tmp = TempDir::new().unwrap();
        let socket_path = tmp.path().join("missing.sock");
        assert!(!wait_for_socket(&socket_path, Duration::from_millis(50)));
        // TEST PASS: wait_for_socket timeout
    }

    #[cfg(unix)]
    #[test]
    fn test_wait_for_socket_accepts_live_listener() {
        let tmp = TempDir::new().unwrap();
        let socket_path = tmp.path().join("live.sock");
        let _listener = std::os::unix::net::UnixListener::bind(&socket_path).unwrap();

        assert!(wait_for_socket(&socket_path, Duration::from_millis(50)));
    }

    #[cfg(unix)]
    #[test]
    fn test_start_daemon_with_fake_rchd_rejects_regular_socket_file() {
        // A successful wrapper exit and a file at the requested `-s` path are
        // not readiness; only a live Unix listener satisfies the contract.
        let tmp = TempDir::new().unwrap();
        let socket_path = tmp.path().join("daemon.sock");
        let fake_rchd = tmp.path().join("rchd");

        let script = "#!/usr/bin/env sh\n\
sock=\"\"\n\
while [ \"$#\" -gt 0 ]; do\n\
  if [ \"$1\" = \"-s\" ] || [ \"$1\" = \"--socket\" ]; then\n\
    shift\n\
    sock=\"$1\"\n\
  fi\n\
  shift\n\
done\n\
[ -n \"$sock\" ] || exit 1\n\
: > \"$sock\"\n\
exit 0\n"
            .to_string();
        std::fs::write(&fake_rchd, script).unwrap();
        let mut perms = std::fs::metadata(&fake_rchd).unwrap().permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&fake_rchd, perms).unwrap();

        let error = start_daemon_with_binary(&socket_path, &fake_rchd, Duration::from_millis(50))
            .unwrap_err();
        assert!(error.contains("did not accept connections"));
        // Under load the fake may still be finishing its `: > "$sock"` when
        // the (short, deliberate) 50ms socket wait gives up — poll briefly
        // rather than flake on scheduler timing.
        let deadline = Instant::now() + Duration::from_secs(2);
        while !socket_path.is_file() && Instant::now() < deadline {
            std::thread::sleep(Duration::from_millis(20));
        }
        assert!(
            socket_path.is_file(),
            "fake must receive the -s socket path"
        );
    }

    #[cfg(unix)]
    #[test]
    fn test_start_daemon_with_failing_fake_rchd_reports_exit() {
        let tmp = TempDir::new().unwrap();
        let socket_path = tmp.path().join("daemon.sock");
        let fake_rchd = tmp.path().join("rchd");

        std::fs::write(&fake_rchd, "#!/usr/bin/env sh\nexit 42\n").unwrap();
        let mut perms = std::fs::metadata(&fake_rchd).unwrap().permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&fake_rchd, perms).unwrap();

        let err =
            start_daemon_with_binary(&socket_path, &fake_rchd, Duration::from_secs(1)).unwrap_err();
        assert!(
            err.contains("exited unsuccessfully") && err.contains("42"),
            "unexpected error: {err}"
        );
        assert!(!socket_path.exists());
    }

    #[test]
    fn test_check_result_fixable_field_semantics() {
        // TEST START: CheckResult fixable field has correct semantics
        // A check that passes should not be fixable (nothing to fix)
        let pass_result = CheckResult {
            category: "test".to_string(),
            name: "passing_check".to_string(),
            status: CheckStatus::Pass,
            message: "All good".to_string(),
            details: None,
            suggestion: None,
            fixable: false, // Correct: passing checks aren't fixable
            fix_applied: false,
            fix_message: None,
        };
        assert!(!pass_result.fixable);

        // A failing check that can be auto-fixed should be marked fixable
        let fixable_fail = CheckResult {
            category: "test".to_string(),
            name: "fixable_issue".to_string(),
            status: CheckStatus::Warning,
            message: "Permission issue".to_string(),
            details: None,
            suggestion: Some("Run chmod 600".to_string()),
            fixable: true, // Correct: this can be fixed
            fix_applied: false,
            fix_message: None,
        };
        assert!(fixable_fail.fixable);

        // A failing check that cannot be auto-fixed should not be fixable
        let unfixable_fail = CheckResult {
            category: "test".to_string(),
            name: "unfixable_issue".to_string(),
            status: CheckStatus::Fail,
            message: "Missing hardware".to_string(),
            details: None,
            suggestion: Some("Buy new hardware".to_string()),
            fixable: false, // Correct: can't auto-fix hardware
            fix_applied: false,
            fix_message: None,
        };
        assert!(!unfixable_fail.fixable);
        // TEST PASS: fixable field semantics
    }

    #[test]
    fn test_check_result_fix_applied_and_message_consistency() {
        // TEST START: fix_applied and fix_message should be consistent
        // If fix_applied is true, fix_message should be Some
        let fixed_result = CheckResult {
            category: "test".to_string(),
            name: "fixed_check".to_string(),
            status: CheckStatus::Pass,
            message: "Fixed!".to_string(),
            details: None,
            suggestion: None,
            fixable: false,
            fix_applied: true,
            fix_message: Some("Changed X to Y".to_string()),
        };
        assert!(fixed_result.fix_applied);
        assert!(fixed_result.fix_message.is_some());

        // If fix_applied is false, fix_message typically should be None
        let not_fixed = CheckResult {
            category: "test".to_string(),
            name: "not_fixed".to_string(),
            status: CheckStatus::Warning,
            message: "Issue detected".to_string(),
            details: None,
            suggestion: Some("Run fix command".to_string()),
            fixable: true,
            fix_applied: false,
            fix_message: None,
        };
        assert!(!not_fixed.fix_applied);
        // TEST PASS: fix_applied and fix_message consistency
    }

    // ========================================================================
    // Config-cache hoisting (t10) — verify the rollout-posture probe accepts
    // a borrowed config and produces the same diagnostics regardless of how
    // many times the caller invokes it.
    // ========================================================================

    #[test]
    fn test_rollout_posture_takes_borrowed_config() {
        // Borrowed-Ok path: probe consumes a shared snapshot.
        let config = rch_common::RchConfig::default();
        let diags = reliability_rollout_posture_diagnostics(Ok(&config));
        // 5 always-on diagnostics: hook_starts_daemon, daemon_installs_hooks,
        // status_surface, repo_convergence_gate, disk_pressure_gate.
        assert!(
            diags.len() >= 4,
            "expected at least 4 diagnostics (got {}): {:?}",
            diags.len(),
            diags.iter().map(|d| &d.check_name).collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_rollout_posture_handles_borrowed_err() {
        // Borrowed-Err path: probe surfaces a single ConfigLoadFailed
        // diagnostic and continues with the rollout-surface checks.
        let diags = reliability_rollout_posture_diagnostics(Err("synthetic toml parse failure"));
        let warning_count = diags
            .iter()
            .filter(|d| {
                matches!(d.severity, ReliabilitySeverity::Warning)
                    && d.code == ReliabilityReasonCode::ConfigLoadFailed
            })
            .count();
        assert_eq!(
            warning_count,
            1,
            "expected exactly one ConfigLoadFailed diagnostic, got: {:?}",
            diags
                .iter()
                .map(|d| (&d.check_name, &d.code))
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_rollout_posture_idempotent_for_same_config() {
        // Calling the probe twice with the same borrowed config must
        // produce byte-identical diagnostics — confirms the function is
        // pure with respect to its config input.
        let config = rch_common::RchConfig::default();
        let a = reliability_rollout_posture_diagnostics(Ok(&config));
        let b = reliability_rollout_posture_diagnostics(Ok(&config));
        assert_eq!(a.len(), b.len());
        for (da, db) in a.iter().zip(b.iter()) {
            assert_eq!(da.check_name, db.check_name);
            assert_eq!(da.severity, db.severity);
            assert_eq!(da.message, db.message);
            assert_eq!(da.code, db.code);
        }
    }

    #[test]
    fn test_rollout_posture_two_configs_isolated() {
        // Different config snapshots produce different diagnostics —
        // confirms no shared mutable state between invocations.
        let mut config_a = rch_common::RchConfig::default();
        config_a.self_healing.hook_starts_daemon = true;
        let mut config_b = rch_common::RchConfig::default();
        config_b.self_healing.hook_starts_daemon = false;

        let a = reliability_rollout_posture_diagnostics(Ok(&config_a));
        let b = reliability_rollout_posture_diagnostics(Ok(&config_b));

        let a_hook = a
            .iter()
            .find(|d| d.check_name == "hook_starts_daemon")
            .expect("hook diag in a");
        let b_hook = b
            .iter()
            .find(|d| d.check_name == "hook_starts_daemon")
            .expect("hook diag in b");
        assert_eq!(a_hook.code, ReliabilityReasonCode::HookAutoStartEnabled);
        assert_eq!(b_hook.code, ReliabilityReasonCode::HookAutoStartDisabled);
    }

    // ========================================================================
    // Verdict tri-state (t02) — aggregator + exit-code mapping + serde shape.
    // ========================================================================

    fn make_diag(severity: ReliabilitySeverity) -> ReliabilityDiagnostic {
        ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            "synthetic",
            severity,
            "test",
            ReliabilityReasonCode::WorkersConfigured,
        )
    }

    #[test]
    fn test_aggregate_verdict_empty_is_healthy() {
        // Empty input is honest — caller decorates with "no probes ran" if needed.
        assert_eq!(aggregate_verdict(&[]), ReliabilityVerdict::Healthy);
    }

    #[test]
    fn test_aggregate_verdict_all_pass_is_healthy() {
        let diags = vec![make_diag(ReliabilitySeverity::Pass); 5];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Healthy);
    }

    #[test]
    fn test_aggregate_verdict_pass_plus_info_is_healthy() {
        let diags = vec![
            make_diag(ReliabilitySeverity::Pass),
            make_diag(ReliabilitySeverity::Info),
            make_diag(ReliabilitySeverity::Pass),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Healthy);
    }

    #[test]
    fn test_aggregate_verdict_one_warning_is_degraded() {
        let diags = vec![
            make_diag(ReliabilitySeverity::Pass),
            make_diag(ReliabilitySeverity::Warning),
            make_diag(ReliabilitySeverity::Info),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Degraded);
    }

    #[test]
    fn test_aggregate_verdict_one_critical_is_failing() {
        let diags = vec![
            make_diag(ReliabilitySeverity::Pass),
            make_diag(ReliabilitySeverity::Warning),
            make_diag(ReliabilitySeverity::Critical),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Failing);
    }

    #[test]
    fn test_aggregate_verdict_critical_dominates_warning() {
        let diags = vec![
            make_diag(ReliabilitySeverity::Critical),
            make_diag(ReliabilitySeverity::Warning),
        ];
        assert_eq!(aggregate_verdict(&diags), ReliabilityVerdict::Failing);
    }

    #[test]
    fn test_verdict_serde_lowercase_strings() {
        // JSON wire form: "healthy" / "degraded" / "failing".
        let h = serde_json::to_string(&ReliabilityVerdict::Healthy).unwrap();
        let d = serde_json::to_string(&ReliabilityVerdict::Degraded).unwrap();
        let f = serde_json::to_string(&ReliabilityVerdict::Failing).unwrap();
        assert_eq!(h, "\"healthy\"");
        assert_eq!(d, "\"degraded\"");
        assert_eq!(f, "\"failing\"");
        // Roundtrip
        let back: ReliabilityVerdict = serde_json::from_str(&d).unwrap();
        assert_eq!(back, ReliabilityVerdict::Degraded);
    }

    #[test]
    fn test_default_exit_code_mapping() {
        assert_eq!(ReliabilityVerdict::Healthy.default_exit_code(), 0);
        assert_eq!(ReliabilityVerdict::Degraded.default_exit_code(), 1);
        assert_eq!(ReliabilityVerdict::Failing.default_exit_code(), 2);
    }

    #[test]
    fn test_strict_promotes_degraded_to_two() {
        assert_eq!(ReliabilityVerdict::Healthy.exit_code(true, false), 0);
        assert_eq!(ReliabilityVerdict::Degraded.exit_code(true, false), 2);
        assert_eq!(ReliabilityVerdict::Failing.exit_code(true, false), 2);
    }

    #[test]
    fn test_lenient_demotes_failing_to_one() {
        assert_eq!(ReliabilityVerdict::Healthy.exit_code(false, true), 0);
        assert_eq!(ReliabilityVerdict::Degraded.exit_code(false, true), 1);
        assert_eq!(ReliabilityVerdict::Failing.exit_code(false, true), 1);
    }

    #[test]
    fn test_default_no_strict_no_lenient_uses_default_mapping() {
        for v in [
            ReliabilityVerdict::Healthy,
            ReliabilityVerdict::Degraded,
            ReliabilityVerdict::Failing,
        ] {
            assert_eq!(v.exit_code(false, false), v.default_exit_code());
        }
    }

    #[test]
    fn test_verdict_label_matches_variant_name() {
        assert_eq!(ReliabilityVerdict::Healthy.label(), "Healthy");
        assert_eq!(ReliabilityVerdict::Degraded.label(), "Degraded");
        assert_eq!(ReliabilityVerdict::Failing.label(), "Failing");
    }

    #[test]
    fn test_summary_overall_uses_aggregate_verdict() {
        // Build a response with mixed severities and assert the summary's
        // verdict matches the aggregator.
        let diags = vec![
            make_diag(ReliabilitySeverity::Pass),
            make_diag(ReliabilitySeverity::Warning),
        ];
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            diags,
        );
        assert_eq!(response.summary.overall, ReliabilityVerdict::Degraded);
    }

    #[test]
    fn test_summary_overall_failing_when_critical_present() {
        let diags = vec![
            make_diag(ReliabilitySeverity::Pass),
            make_diag(ReliabilitySeverity::Critical),
        ];
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            diags,
        );
        assert_eq!(response.summary.overall, ReliabilityVerdict::Failing);
    }

    // ========================================================================
    // Scope filter (t01) — parser, set semantics, gating, response wiring.
    // ========================================================================

    #[test]
    fn test_scope_default_is_all() {
        let s = ReliabilityScopeSet::default();
        assert_eq!(s.0, vec![ReliabilityScope::All]);
        assert!(s.matches(ReliabilityScope::Topology));
        assert!(s.matches(ReliabilityScope::Pressure));
        // matches() returns true for every named scope when All is present.
        for v in [
            ReliabilityScope::All,
            ReliabilityScope::Topology,
            ReliabilityScope::Convergence,
            ReliabilityScope::Pressure,
            ReliabilityScope::Triage,
            ReliabilityScope::Helpers,
            ReliabilityScope::Rollout,
            ReliabilityScope::Schema,
        ] {
            assert!(s.matches(v));
        }
    }

    #[test]
    fn test_scope_parses_single_value() {
        let s: ReliabilityScopeSet = "topology".parse().unwrap();
        assert_eq!(s.0, vec![ReliabilityScope::Topology]);
        assert!(s.matches(ReliabilityScope::Topology));
        assert!(!s.matches(ReliabilityScope::Pressure));
    }

    #[test]
    fn test_scope_parses_multi_value_csv() {
        let s: ReliabilityScopeSet = "topology,pressure".parse().unwrap();
        assert_eq!(
            s.0,
            vec![ReliabilityScope::Topology, ReliabilityScope::Pressure]
        );
        assert!(s.matches(ReliabilityScope::Topology));
        assert!(s.matches(ReliabilityScope::Pressure));
        assert!(!s.matches(ReliabilityScope::Helpers));
    }

    #[test]
    fn test_scope_dedups_keeping_first_occurrence() {
        let s: ReliabilityScopeSet = "topology,pressure,topology,pressure".parse().unwrap();
        assert_eq!(
            s.0,
            vec![ReliabilityScope::Topology, ReliabilityScope::Pressure]
        );
    }

    #[test]
    fn test_scope_all_dominates_when_mixed() {
        // `all,topology` collapses to `[All]` — operator gets the full sweep.
        let s: ReliabilityScopeSet = "all,topology".parse().unwrap();
        assert_eq!(s.0, vec![ReliabilityScope::All]);
    }

    #[test]
    fn test_scope_empty_string_errors() {
        let err = ""
            .parse::<ReliabilityScopeSet>()
            .expect_err("empty must err");
        assert!(err.contains("scope list is empty"));
    }

    #[test]
    fn test_scope_unknown_segment_errors_with_offender() {
        let err = "topology,bogus"
            .parse::<ReliabilityScopeSet>()
            .expect_err("unknown segment must err");
        assert!(
            err.contains("bogus"),
            "error should name the offender, got: {err}"
        );
    }

    #[test]
    fn test_scope_case_insensitive_segment_parse() {
        let s: ReliabilityScopeSet = "Topology,PRESSURE".parse().unwrap();
        assert_eq!(
            s.0,
            vec![ReliabilityScope::Topology, ReliabilityScope::Pressure]
        );
    }

    #[test]
    fn test_scope_whitespace_trimmed() {
        let s: ReliabilityScopeSet = "  topology  ".parse().unwrap();
        assert_eq!(s.0, vec![ReliabilityScope::Topology]);
    }

    #[test]
    fn test_scope_as_strings_stable_order() {
        let s = ReliabilityScopeSet(vec![ReliabilityScope::Pressure, ReliabilityScope::Topology]);
        assert_eq!(s.as_strings(), vec!["pressure", "topology"]);
    }

    #[test]
    fn test_scope_response_field_records_what_was_asked() {
        let scope =
            ReliabilityScopeSet(vec![ReliabilityScope::Topology, ReliabilityScope::Pressure]);
        let response =
            build_reliability_doctor_response(ReliabilityDoctorMode::Check, &scope, vec![]);
        assert_eq!(response.scope, vec!["topology", "pressure"]);
    }

    #[test]
    fn test_scope_response_default_is_all_array() {
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            vec![],
        );
        // data.scope is always an array (even single-element).
        assert_eq!(response.scope, vec!["all"]);
    }

    #[test]
    fn test_scope_prefetch_dependencies_are_precise() {
        let all = ReliabilityScopeSet::default();
        assert!(all.needs_worker_config());
        assert!(all.needs_daemon_status());
        assert!(all.needs_repo_convergence_status());
        assert!(all.needs_rollout_config());

        let topology: ReliabilityScopeSet = "topology".parse().unwrap();
        assert!(topology.needs_worker_config());
        assert!(topology.needs_daemon_status());
        assert!(!topology.needs_repo_convergence_status());
        assert!(!topology.needs_rollout_config());

        let pressure: ReliabilityScopeSet = "pressure".parse().unwrap();
        assert!(!pressure.needs_worker_config());
        assert!(pressure.needs_daemon_status());
        assert!(!pressure.needs_repo_convergence_status());
        assert!(!pressure.needs_rollout_config());

        let convergence: ReliabilityScopeSet = "convergence".parse().unwrap();
        assert!(!convergence.needs_worker_config());
        assert!(!convergence.needs_daemon_status());
        assert!(convergence.needs_repo_convergence_status());
        assert!(!convergence.needs_rollout_config());

        let rollout: ReliabilityScopeSet = "rollout".parse().unwrap();
        assert!(!rollout.needs_worker_config());
        assert!(!rollout.needs_daemon_status());
        assert!(!rollout.needs_repo_convergence_status());
        assert!(rollout.needs_rollout_config());

        let local_only: ReliabilityScopeSet = "helpers,schema".parse().unwrap();
        assert!(!local_only.needs_worker_config());
        assert!(!local_only.needs_daemon_status());
        assert!(!local_only.needs_repo_convergence_status());
        assert!(!local_only.needs_rollout_config());
    }

    #[test]
    fn test_scope_probe_names_honor_schema_gate() {
        let all = ReliabilityScopeSet::default();
        assert_eq!(
            all.probe_names_to_run(false),
            vec![
                "topology",
                "ownership",
                "convergence",
                "pressure",
                "triage",
                "helpers",
                "rollout"
            ]
        );
        assert_eq!(
            all.probe_names_to_run(true),
            vec![
                "topology",
                "ownership",
                "convergence",
                "pressure",
                "triage",
                "helpers",
                "rollout",
                "schema"
            ]
        );

        let schema_only: ReliabilityScopeSet = "schema".parse().unwrap();
        assert_eq!(schema_only.probe_names_to_run(false), vec!["schema"]);
        assert_eq!(schema_only.probe_names_to_run(true), vec!["schema"]);

        let helpers_schema: ReliabilityScopeSet = "helpers,schema".parse().unwrap();
        assert_eq!(
            helpers_schema.probe_names_to_run(false),
            vec!["helpers", "schema"]
        );
    }

    // ========================================================================
    // t05 — envelope harmonization. Verify command tag is the dotted
    // form, daemon_unreachable + reasons populate correctly, and the
    // legacy DoctorResponse carries a schema_version.
    // ========================================================================

    fn synthetic_diagnostic(
        code: ReliabilityReasonCode,
        check_name: &str,
        message: &str,
        severity: ReliabilitySeverity,
    ) -> ReliabilityDiagnostic {
        ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            check_name,
            severity,
            message,
            code,
        )
    }

    #[test]
    fn test_daemon_unreachable_false_when_all_reachable() {
        // No daemon-unreachable codes in the diagnostics → false + empty list.
        let diags = vec![
            synthetic_diagnostic(
                ReliabilityReasonCode::WorkersHealthy,
                "daemon_worker_capacity",
                "All 7 workers healthy",
                ReliabilitySeverity::Pass,
            ),
            synthetic_diagnostic(
                ReliabilityReasonCode::WorkerReady,
                "worker_topology",
                "Worker css ready",
                ReliabilitySeverity::Pass,
            ),
        ];
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            diags,
        );
        assert!(!response.daemon_unreachable);
        assert!(response.daemon_unreachable_reasons.is_empty());
    }

    #[test]
    fn test_daemon_unreachable_true_when_status_unavailable() {
        // Single probe reports DaemonStatusUnavailable → flag flips.
        let diags = vec![synthetic_diagnostic(
            ReliabilityReasonCode::DaemonStatusUnavailable,
            "daemon_status",
            "Daemon status is unavailable",
            ReliabilitySeverity::Warning,
        )];
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            diags,
        );
        assert!(response.daemon_unreachable);
        assert_eq!(response.daemon_unreachable_reasons.len(), 1);
        // The reason text should attribute it to the probe name + message.
        assert!(
            response.daemon_unreachable_reasons[0].contains("daemon_status"),
            "reason text should name the probe: {:?}",
            response.daemon_unreachable_reasons
        );
        assert!(
            response.daemon_unreachable_reasons[0].contains("unavailable"),
            "reason text should include the diagnostic message"
        );
    }

    #[test]
    fn test_daemon_unreachable_aggregates_multiple_probes() {
        // Multiple unreachable codes → all attributed.
        let diags = vec![
            synthetic_diagnostic(
                ReliabilityReasonCode::DaemonStatusUnavailable,
                "daemon_status",
                "daemon down",
                ReliabilitySeverity::Warning,
            ),
            synthetic_diagnostic(
                ReliabilityReasonCode::DiskPressureUnavailable,
                "disk_pressure",
                "disk surface gone",
                ReliabilitySeverity::Warning,
            ),
            synthetic_diagnostic(
                ReliabilityReasonCode::ProcessDebtUnavailable,
                "process_debt",
                "triage unavailable",
                ReliabilitySeverity::Warning,
            ),
            // Non-unreachable diagnostic should NOT appear in the reasons.
            synthetic_diagnostic(
                ReliabilityReasonCode::WorkersHealthy,
                "daemon_worker_capacity",
                "ignored",
                ReliabilitySeverity::Pass,
            ),
        ];
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            diags,
        );
        assert!(response.daemon_unreachable);
        assert_eq!(
            response.daemon_unreachable_reasons.len(),
            3,
            "expected 3 reasons (the 3 unreachable codes), got {:?}",
            response.daemon_unreachable_reasons
        );
        // None of the reasons should mention the "ignored" Pass diagnostic.
        for r in &response.daemon_unreachable_reasons {
            assert!(
                !r.contains("ignored"),
                "Pass diagnostics should NOT contribute to reasons: {r}"
            );
        }
    }

    #[test]
    fn test_reliability_response_carries_schema_version() {
        // schema_version is non-empty and sourced from the registry.
        let response = build_reliability_doctor_response(
            ReliabilityDoctorMode::Check,
            &ReliabilityScopeSet::default(),
            vec![],
        );
        assert!(!response.schema_version.is_empty());
        // Format check: should look like a semver string (digits + dots).
        assert!(
            response
                .schema_version
                .chars()
                .all(|c| c.is_ascii_digit() || c == '.'),
            "schema_version must be numeric+dots: {:?}",
            response.schema_version
        );
    }

    #[test]
    fn test_doctor_unreachable_codes_table_is_subset_of_known_codes() {
        // The hand-maintained DAEMON_UNREACHABLE_REASON_CODES list must
        // only contain codes that exist in ReliabilityReasonCode::ALL.
        // Catches typos or removed-but-still-referenced variants.
        for c in DAEMON_UNREACHABLE_REASON_CODES {
            assert!(
                ReliabilityReasonCode::ALL.contains(c),
                "DAEMON_UNREACHABLE_REASON_CODES contains {c:?} which is not in ALL"
            );
        }
        // And shouldn't have duplicates.
        let unique: std::collections::HashSet<_> = DAEMON_UNREACHABLE_REASON_CODES.iter().collect();
        assert_eq!(unique.len(), DAEMON_UNREACHABLE_REASON_CODES.len());
    }

    // ========================================================================
    // t11 — alloc-discipline helpers. Verify that push_opt_f64 / push_opt_display
    // produce byte-identical output to the old `.map().unwrap_or_else()` chains.
    // ========================================================================

    #[test]
    fn test_push_opt_f64_some_at_precision_1() {
        let mut buf = String::new();
        push_opt_f64(&mut buf, Some(7.654), 1);
        assert_eq!(buf, "7.7");
    }

    #[test]
    fn test_push_opt_f64_some_at_precision_2() {
        let mut buf = String::new();
        push_opt_f64(&mut buf, Some(0.123456), 2);
        assert_eq!(buf, "0.12");
    }

    #[test]
    fn test_push_opt_f64_some_at_precision_3() {
        let mut buf = String::new();
        push_opt_f64(&mut buf, Some(0.123456), 3);
        assert_eq!(buf, "0.123");
    }

    #[test]
    fn test_push_opt_f64_none_writes_unknown() {
        let mut buf = String::new();
        push_opt_f64(&mut buf, None, 2);
        assert_eq!(buf, "unknown");
    }

    #[test]
    fn test_push_opt_f64_appends_to_existing_content() {
        // The buffer is not cleared — the helper appends. (Value chosen
        // to avoid clippy::approx_constant lint that flags PI-like literals.)
        let mut buf = String::from("prefix=");
        push_opt_f64(&mut buf, Some(2.5), 1);
        assert_eq!(buf, "prefix=2.5");
    }

    #[test]
    fn test_push_opt_display_some_u64() {
        let mut buf = String::new();
        push_opt_display(&mut buf, Some(42u64));
        assert_eq!(buf, "42");
    }

    #[test]
    fn test_push_opt_display_some_bool() {
        let mut buf = String::new();
        push_opt_display(&mut buf, Some(true));
        assert_eq!(buf, "true");
    }

    #[test]
    fn test_push_opt_display_none_writes_unknown() {
        let mut buf = String::new();
        push_opt_display::<i64>(&mut buf, None);
        assert_eq!(buf, "unknown");
    }

    #[test]
    fn test_t11_helpers_match_old_format_behavior() {
        // Byte-identical equivalence: the new push_opt_* helpers produce
        // the same text the old `.map(|v| format!(...)).unwrap_or_else(||
        // "unknown".to_string())` chains produced.
        //
        // pressure_disk_free_gb (precision 2):
        let v = Some(123.456);
        let old: String = v
            .map(|value| format!("{value:.2}"))
            .unwrap_or_else(|| "unknown".to_string());
        let mut new_buf = String::new();
        push_opt_f64(&mut new_buf, v, 2);
        assert_eq!(old, new_buf, "precision-2 helper must match old format");

        // pressure_disk_free_ratio (precision 3):
        let old: String = v
            .map(|value| format!("{value:.3}"))
            .unwrap_or_else(|| "unknown".to_string());
        let mut new_buf = String::new();
        push_opt_f64(&mut new_buf, v, 3);
        assert_eq!(old, new_buf, "precision-3 helper must match old format");

        // pressure_telemetry_age_secs (Option<u64>):
        let v: Option<u64> = Some(3600);
        let old: String = v
            .map(|value| value.to_string())
            .unwrap_or_else(|| "unknown".to_string());
        let mut new_buf = String::new();
        push_opt_display(&mut new_buf, v);
        assert_eq!(old, new_buf, "Display helper for u64 must match old format");

        // None path for all three:
        let none_f64: Option<f64> = None;
        let old: String = none_f64
            .map(|value| format!("{value:.2}"))
            .unwrap_or_else(|| "unknown".to_string());
        let mut new_buf = String::new();
        push_opt_f64(&mut new_buf, none_f64, 2);
        assert_eq!(
            old, new_buf,
            "None precision-2 helper must match old format"
        );

        let none_u64: Option<u64> = None;
        let old: String = none_u64
            .map(|value| value.to_string())
            .unwrap_or_else(|| "unknown".to_string());
        let mut new_buf = String::new();
        push_opt_display(&mut new_buf, none_u64);
        assert_eq!(old, new_buf, "None Display helper must match old format");
    }

    // =========================================================================
    // `--watch` Diff Function Tests (t25)
    // =========================================================================
    //
    // These tests pin the contract of `diff_fingerprint_maps`. The watch
    // loop relies on this purely-functional diff to compute added /
    // cleared / changed sets. Regressions here would produce wrong
    // `--transitions-only` suppression behavior and would silently
    // miss-emit machine sweep deltas — so we cover empty-vs-empty,
    // first-sweep (empty-vs-populated), severity flip, message rotation
    // (not a fingerprint change), and the worker_id-keyed case where
    // the same `check_name` appears once per worker.

    fn make_watch_diag(
        category: ReliabilityCategory,
        check_name: &str,
        severity: ReliabilitySeverity,
        code: ReliabilityReasonCode,
        message: &str,
        worker_id: Option<&str>,
    ) -> ReliabilityDiagnostic {
        let mut d = ReliabilityDiagnostic::new(category, check_name, severity, message, code);
        if let Some(w) = worker_id {
            d = d.with_worker(w);
        }
        d
    }

    fn fp_map_of(
        diags: &[ReliabilityDiagnostic],
    ) -> std::collections::BTreeMap<DiagnosticKey, DiagnosticFingerprint> {
        let mut map = std::collections::BTreeMap::new();
        for d in diags {
            map.insert(
                DiagnosticKey::from_diagnostic(d),
                DiagnosticFingerprint::from_diagnostic(d),
            );
        }
        map
    }

    // =========================================================================
    // Probe Parallelism Tests (bd-62u24.8)
    // =========================================================================
    //
    // These tests pin the contract of `join_isolated_async_probe` and
    // `join_isolated_blocking_probe`. The doctor relies on these to
    // surface probe failures (timeout, panic, RPC error) as a uniform
    // `(None, ProbeOutcome)` pair so downstream diagnostic builders can
    // fall through to "unavailable" Warning diagnostics without caring
    // about the exact failure mode. Regressions here would let a probe
    // panic bring down the whole doctor or leak runaway subprocesses.

    #[test]
    fn probe_outcome_label_is_lowercase_and_stable() {
        // TEST START: tracing field values are part of the operator contract
        assert_eq!(ProbeOutcome::Ok.label(), "ok");
        assert_eq!(ProbeOutcome::Skipped.label(), "skipped");
        assert_eq!(ProbeOutcome::InnerError.label(), "inner_error");
        assert_eq!(ProbeOutcome::Timeout.label(), "timeout");
        assert_eq!(ProbeOutcome::Panicked.label(), "panicked");
        assert_eq!(ProbeOutcome::Cancelled.label(), "cancelled");
        // TEST PASS: label stability
    }

    #[tokio::test]
    async fn join_isolated_async_probe_returns_skipped_for_none_handle() {
        // TEST START: a scoped-out probe (no handle) yields (None, Skipped)
        let (result, outcome) =
            join_isolated_async_probe::<String, std::io::Error>("ghost", None).await;
        assert_eq!(result, None);
        assert_eq!(outcome, ProbeOutcome::Skipped);
        // TEST PASS: skip path
    }

    #[tokio::test]
    async fn join_isolated_async_probe_returns_ok_for_successful_task() {
        // TEST START: a Future returning Ok produces (Some(value), Ok)
        let handle = tokio::spawn(async {
            tokio::time::timeout(PROBE_TIMEOUT, async {
                Ok::<_, std::io::Error>("probe_value".to_string())
            })
            .await
        });
        let (result, outcome) = join_isolated_async_probe("ok_probe", Some(handle)).await;
        assert_eq!(result.as_deref(), Some("probe_value"));
        assert_eq!(outcome, ProbeOutcome::Ok);
        // TEST PASS: success path
    }

    #[tokio::test]
    async fn join_isolated_async_probe_classifies_inner_error() {
        // TEST START: an inner Err is reported as InnerError, not Timeout
        let handle = tokio::spawn(async {
            tokio::time::timeout(PROBE_TIMEOUT, async {
                Err::<String, std::io::Error>(std::io::Error::other("inner fault"))
            })
            .await
        });
        let (result, outcome) = join_isolated_async_probe("err_probe", Some(handle)).await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::InnerError);
        // TEST PASS: inner-error classification
    }

    #[tokio::test]
    async fn join_isolated_async_probe_surfaces_timeout() {
        // TEST START: a future that exceeds PROBE_TIMEOUT yields (None, Timeout)
        // Use a much shorter timeout for the test by chaining the outer
        // tokio::time::timeout — this mirrors the production wrapping.
        let handle = tokio::spawn(async {
            tokio::time::timeout(std::time::Duration::from_millis(20), async {
                tokio::time::sleep(std::time::Duration::from_secs(60)).await;
                Ok::<_, std::io::Error>("never returned".to_string())
            })
            .await
        });
        let (result, outcome) = join_isolated_async_probe("slow_probe", Some(handle)).await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::Timeout);
        // TEST PASS: timeout classification
    }

    #[tokio::test]
    async fn join_isolated_async_probe_isolates_panic() {
        // TEST START: a panic in the spawned task is caught by JoinError
        // and reported as (None, Panicked). The caller does NOT panic.
        let handle = tokio::spawn(async {
            tokio::time::timeout(PROBE_TIMEOUT, async {
                std::panic::panic_any("probe explosion (intentional, for test)".to_string());
                #[expect(unreachable_code)]
                Ok::<_, std::io::Error>("never".to_string())
            })
            .await
        });
        let (result, outcome) = join_isolated_async_probe("panic_probe", Some(handle)).await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::Panicked);
        // TEST PASS: panic isolation
    }

    #[tokio::test]
    async fn join_isolated_blocking_probe_returns_value_for_successful_task() {
        // TEST START: sync spawn_blocking task returns its value cleanly
        let handle = tokio::task::spawn_blocking(|| vec!["a".to_string(), "b".to_string()]);
        let (result, outcome) = join_isolated_blocking_probe("blocking_ok", Some(handle)).await;
        assert_eq!(
            result.as_deref(),
            Some(&["a".to_string(), "b".to_string()][..])
        );
        assert_eq!(outcome, ProbeOutcome::Ok);
        // TEST PASS: blocking success path
    }

    #[tokio::test]
    async fn join_isolated_blocking_probe_isolates_panic() {
        // TEST START: panic in spawn_blocking yields (None, Panicked) —
        // critical because the helper-compat probe is exactly this shape
        // and a panic there must not sink the doctor.
        let handle = tokio::task::spawn_blocking(|| -> Vec<String> {
            std::panic::panic_any("blocking probe explosion (intentional, for test)".to_string());
        });
        let (result, outcome) = join_isolated_blocking_probe("blocking_panic", Some(handle)).await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::Panicked);
        // TEST PASS: blocking panic isolation
    }

    #[tokio::test]
    async fn join_isolated_blocking_probe_returns_skipped_for_none_handle() {
        // TEST START: defensive — scoped-out path yields Skipped, not panic
        let (result, outcome): (Option<Vec<String>>, ProbeOutcome) =
            join_isolated_blocking_probe("ghost", None).await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::Skipped);
        // TEST PASS: skip path for blocking variant
    }

    #[tokio::test]
    async fn join_isolated_blocking_probe_surfaces_timeout_promptly() {
        // TEST START: timeout around a spawn_blocking JoinHandle returns
        // promptly. The blocking task may finish later; the doctor must not
        // wait for it before emitting partial diagnostics.
        let start = std::time::Instant::now();
        let handle = tokio::task::spawn_blocking(|| {
            std::thread::sleep(std::time::Duration::from_millis(80));
            vec!["too_late".to_string()]
        });
        let (result, outcome) = join_isolated_blocking_probe_with_timeout(
            "blocking_timeout",
            Some(handle),
            std::time::Duration::from_millis(10),
        )
        .await;
        assert!(result.is_none());
        assert_eq!(outcome, ProbeOutcome::Timeout);
        assert!(
            start.elapsed() < std::time::Duration::from_millis(60),
            "blocking timeout should return promptly"
        );
        // TEST PASS: timeout classification for blocking probe
    }

    #[test]
    fn helper_probe_failure_emits_unavailable_diagnostic_without_rerun() {
        // TEST START: a failed helper prefetch must not synchronously run
        // the same subprocess-heavy probe again. It emits one bounded
        // warning instead.
        let diagnostics = helper_diagnostics_from_probe_result(None, ProbeOutcome::Timeout);
        assert_eq!(diagnostics.len(), 1);
        let diagnostic = &diagnostics[0];
        assert_eq!(
            diagnostic.category,
            ReliabilityCategory::HelperCompatibility
        );
        assert_eq!(diagnostic.check_name, "helper_probe");
        assert_eq!(diagnostic.severity, ReliabilitySeverity::Warning);
        assert_eq!(
            diagnostic.code,
            ReliabilityReasonCode::HelperProbeUnavailable
        );
        assert!(
            diagnostic
                .details
                .as_deref()
                .is_some_and(|details| details.contains("probe_outcome=timeout")),
            "details should retain the probe outcome"
        );
        // TEST PASS: failed helper probe stays bounded and visible
    }

    #[tokio::test]
    async fn timed_async_probe_exports_measured_outcomes_once() {
        use tracing_subscriber::prelude::*;

        let metrics = rch_telemetry::metrics::Metrics::new().unwrap();
        let subscriber = tracing_subscriber::registry()
            .with(rch_telemetry::metrics::MetricsLayer::new(metrics.clone()));
        let _subscriber = tracing::subscriber::set_default(subscriber);

        let success = timed_async_probe("daemon_status", async {
            tokio::time::sleep(Duration::from_millis(5)).await;
            Ok::<_, &str>(42)
        })
        .await;
        assert_eq!(success.unwrap().unwrap(), 42);
        let error =
            timed_async_probe("repo_convergence", async { Err::<(), _>("rpc failed") }).await;
        assert_eq!(error.unwrap().unwrap_err(), "rpc failed");
        let timeout =
            timed_async_probe("daemon_status", std::future::pending::<Result<(), &str>>()).await;
        assert!(timeout.is_err());

        for (probe, outcome, minimum) in [
            ("daemon_status", "completed", 0.005),
            ("repo_convergence", "inner_error", 0.0),
            ("daemon_status", "timeout", PROBE_TIMEOUT.as_secs_f64()),
        ] {
            let histogram = metrics
                .doctor_probe_duration_seconds
                .with_label_values(&[probe, outcome]);
            assert_eq!(histogram.get_sample_count(), 1, "{probe}/{outcome}");
            assert!(histogram.get_sample_sum() >= minimum, "{probe}/{outcome}");
            assert!(histogram.get_sample_sum() > 0.0, "{probe}/{outcome}");
        }
    }

    #[tokio::test]
    async fn probes_actually_run_in_parallel_not_serial() {
        // TEST START: integration-style proof that the join is concurrent.
        // Three tasks each sleep 100ms; with serial execution wallclock
        // would be ~300ms+ ; with parallel execution it's ~100ms +
        // join overhead. We assert wallclock < 250ms to leave wide
        // headroom for CI variability while still rejecting any
        // accidental return to sequential await.
        let start = std::time::Instant::now();
        let h1 = tokio::spawn(async {
            tokio::time::timeout(PROBE_TIMEOUT, async {
                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                Ok::<_, std::io::Error>("a".to_string())
            })
            .await
        });
        let h2 = tokio::spawn(async {
            tokio::time::timeout(PROBE_TIMEOUT, async {
                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                Ok::<_, std::io::Error>("b".to_string())
            })
            .await
        });
        let h3 = tokio::task::spawn_blocking(|| {
            std::thread::sleep(std::time::Duration::from_millis(100));
            vec!["c".to_string()]
        });
        let (r1, _) = join_isolated_async_probe("p1", Some(h1)).await;
        let (r2, _) = join_isolated_async_probe("p2", Some(h2)).await;
        let (r3, _) = join_isolated_blocking_probe("p3", Some(h3)).await;
        let elapsed = start.elapsed();
        assert_eq!(r1.as_deref(), Some("a"));
        assert_eq!(r2.as_deref(), Some("b"));
        assert_eq!(r3.as_deref(), Some(&["c".to_string()][..]));
        assert!(
            elapsed < std::time::Duration::from_millis(250),
            "probes must run in parallel: elapsed={elapsed:?} (serial would be ~300ms+)"
        );
        // TEST PASS: actual parallelism (not just structural)
    }

    #[test]
    fn diff_empty_vs_empty_is_quiet() {
        // TEST START: empty → empty diff must be no-op
        let prev = std::collections::BTreeMap::new();
        let curr = std::collections::BTreeMap::new();
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert!(!diff.has_changes(), "empty→empty must be quiet");
        assert_eq!(diff.added.len(), 0);
        assert_eq!(diff.cleared.len(), 0);
        assert_eq!(diff.changed.len(), 0);
        assert_eq!(diff.total_transitions(), 0);
        // TEST PASS: empty→empty diff
    }

    #[test]
    fn diff_first_sweep_classifies_everything_as_added() {
        // TEST START: empty→populated first sweep — every diagnostic is "added"
        let prev = std::collections::BTreeMap::new();
        let curr_diags = vec![
            make_watch_diag(
                ReliabilityCategory::Topology,
                "workers_config",
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::WorkersConfigured,
                "3 workers configured",
                None,
            ),
            make_watch_diag(
                ReliabilityCategory::DiskPressure,
                "disk_pressure",
                ReliabilitySeverity::Warning,
                ReliabilityReasonCode::PartialWorkerCapacity,
                "disk pressure observed",
                Some("css"),
            ),
        ];
        let curr = fp_map_of(&curr_diags);
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert!(diff.has_changes());
        assert_eq!(diff.added.len(), 2, "first sweep must mark all as added");
        assert_eq!(diff.cleared.len(), 0);
        assert_eq!(diff.changed.len(), 0);
        assert_eq!(diff.total_transitions(), 2);
        // TEST PASS: first sweep added classification
    }

    #[test]
    fn diff_cleared_when_diagnostic_disappears() {
        // TEST START: a diagnostic gone from prev→curr is "cleared"
        let prev_diags = vec![make_watch_diag(
            ReliabilityCategory::Topology,
            "workers_config",
            ReliabilitySeverity::Critical,
            ReliabilityReasonCode::NoWorkersConfigured,
            "no workers configured",
            None,
        )];
        let prev = fp_map_of(&prev_diags);
        let curr = std::collections::BTreeMap::new();
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert_eq!(diff.added.len(), 0);
        assert_eq!(diff.cleared.len(), 1);
        assert_eq!(diff.changed.len(), 0);
        // TEST PASS: cleared diagnostic
    }

    #[test]
    fn diff_severity_flip_is_changed_not_cleared_plus_added() {
        // TEST START: same key, different severity → "changed" (not cleared+added)
        let prev_diags = vec![make_watch_diag(
            ReliabilityCategory::Topology,
            "workers_config",
            ReliabilitySeverity::Warning,
            ReliabilityReasonCode::PartialWorkerCapacity,
            "2/3 workers healthy",
            None,
        )];
        let curr_diags = vec![make_watch_diag(
            ReliabilityCategory::Topology,
            "workers_config",
            ReliabilitySeverity::Critical, // <-- flipped from Warning
            ReliabilityReasonCode::AllWorkersUnhealthy,
            "0/3 workers healthy",
            None,
        )];
        let prev = fp_map_of(&prev_diags);
        let curr = fp_map_of(&curr_diags);
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert_eq!(diff.added.len(), 0, "must not double-count flip as added");
        assert_eq!(
            diff.cleared.len(),
            0,
            "must not double-count flip as cleared"
        );
        assert_eq!(
            diff.changed.len(),
            1,
            "severity flip is a single 'changed' event"
        );
        let (key, prev_fp, cur_fp) = &diff.changed[0];
        assert_eq!(key.check_name, "workers_config");
        assert_eq!(prev_fp.severity, ReliabilitySeverity::Warning);
        assert_eq!(cur_fp.severity, ReliabilitySeverity::Critical);
        // TEST PASS: severity flip classification
    }

    #[test]
    fn diff_identical_fingerprint_is_quiet() {
        // TEST START: same fingerprint twice → diff is empty (drives --transitions-only)
        let diags = vec![make_watch_diag(
            ReliabilityCategory::Topology,
            "workers_config",
            ReliabilitySeverity::Pass,
            ReliabilityReasonCode::WorkersConfigured,
            "3 workers configured",
            None,
        )];
        let prev = fp_map_of(&diags);
        let curr = fp_map_of(&diags);
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert!(
            !diff.has_changes(),
            "identical fingerprints must not flag changes"
        );
        // TEST PASS: identical fingerprint quiet
    }

    #[test]
    fn diff_per_worker_keys_are_independent() {
        // TEST START: same check_name on different workers are independent rows
        // (so a flip on one worker doesn't get attributed to the other).
        let prev_diags = vec![
            make_watch_diag(
                ReliabilityCategory::Topology,
                "worker_health",
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::WorkersHealthy,
                "ok",
                Some("css"),
            ),
            make_watch_diag(
                ReliabilityCategory::Topology,
                "worker_health",
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::WorkersHealthy,
                "ok",
                Some("dlx"),
            ),
        ];
        let curr_diags = vec![
            make_watch_diag(
                ReliabilityCategory::Topology,
                "worker_health",
                ReliabilitySeverity::Pass,
                ReliabilityReasonCode::WorkersHealthy,
                "ok",
                Some("css"),
            ),
            // dlx flipped
            make_watch_diag(
                ReliabilityCategory::Topology,
                "worker_health",
                ReliabilitySeverity::Critical,
                ReliabilityReasonCode::AllWorkersUnhealthy,
                "down",
                Some("dlx"),
            ),
        ];
        let prev = fp_map_of(&prev_diags);
        let curr = fp_map_of(&curr_diags);
        let diff = diff_fingerprint_maps(&prev, &curr);
        assert_eq!(diff.added.len(), 0);
        assert_eq!(diff.cleared.len(), 0);
        assert_eq!(
            diff.changed.len(),
            1,
            "only the dlx row should be marked changed"
        );
        let (key, _, _) = &diff.changed[0];
        assert_eq!(key.worker_id.as_deref(), Some("dlx"));
        // TEST PASS: per-worker key independence
    }

    #[test]
    fn watch_state_observe_verdict_tracks_worst_case() {
        // TEST START: WatchState.observe_verdict is monotone non-decreasing
        // (Healthy → Degraded → Failing). Once worst is Failing it stays
        // Failing even if subsequent sweeps recover. CI tripwires read
        // worst_verdict at exit.
        let mut state = WatchState::new();
        assert!(state.worst_verdict.is_none());
        state.observe_verdict(ReliabilityVerdict::Healthy);
        assert_eq!(state.worst_verdict, Some(ReliabilityVerdict::Healthy));
        state.observe_verdict(ReliabilityVerdict::Degraded);
        assert_eq!(state.worst_verdict, Some(ReliabilityVerdict::Degraded));
        state.observe_verdict(ReliabilityVerdict::Healthy); // recovery
        assert_eq!(
            state.worst_verdict,
            Some(ReliabilityVerdict::Degraded),
            "recovery must not lower the worst-observed verdict"
        );
        state.observe_verdict(ReliabilityVerdict::Failing);
        assert_eq!(state.worst_verdict, Some(ReliabilityVerdict::Failing));
        state.observe_verdict(ReliabilityVerdict::Healthy); // recovery from Failing
        assert_eq!(
            state.worst_verdict,
            Some(ReliabilityVerdict::Failing),
            "worst_verdict is sticky once Failing"
        );
        // TEST PASS: worst_verdict monotonicity
    }

    #[test]
    fn watch_worst_verdict_includes_exit_snapshot_probe() {
        // TEST START: the exit-time snapshot probe is folded into
        // worst_verdict, not just the completed watch sweeps.
        assert_eq!(
            worst_reliability_verdict(
                Some(ReliabilityVerdict::Healthy),
                ReliabilityVerdict::Failing
            ),
            ReliabilityVerdict::Failing,
            "a failing exit snapshot must promote worst_verdict"
        );
        assert_eq!(
            worst_reliability_verdict(
                Some(ReliabilityVerdict::Degraded),
                ReliabilityVerdict::Healthy
            ),
            ReliabilityVerdict::Degraded,
            "a recovered exit snapshot must not lower the observed worst verdict"
        );
        assert_eq!(
            worst_reliability_verdict(None, ReliabilityVerdict::Degraded),
            ReliabilityVerdict::Degraded,
            "snapshot-only sessions must use the exit probe verdict"
        );
        // TEST PASS: exit snapshot verdict folded into worst_verdict
    }

    #[test]
    fn diagnostic_key_render_includes_worker_when_present() {
        // TEST START: DiagnosticKey.render() produces stable human-readable form
        let key_no_worker = DiagnosticKey {
            category: ReliabilityCategory::Topology,
            check_name: "workers_config".to_string(),
            worker_id: None,
        };
        assert_eq!(key_no_worker.render(), "topology/workers_config");
        let key_with_worker = DiagnosticKey {
            category: ReliabilityCategory::DiskPressure,
            check_name: "disk_pressure".to_string(),
            worker_id: Some("css".to_string()),
        };
        assert_eq!(
            key_with_worker.render(),
            "disk_pressure/disk_pressure[worker=css]"
        );
        // TEST PASS: render format stable
    }

    #[test]
    fn fingerprint_excludes_details_so_rotating_uptime_does_not_churn() {
        // TEST START: fingerprint must NOT include `details` field — some
        // details rotate every sweep (e.g., `uptime_secs=12345`) and would
        // generate constant noise under --transitions-only.
        let d_a = ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            "daemon_worker_capacity",
            ReliabilitySeverity::Pass,
            "All 3 workers healthy",
            ReliabilityReasonCode::WorkersHealthy,
        )
        .with_details("uptime_secs=100");
        let d_b = ReliabilityDiagnostic::new(
            ReliabilityCategory::Topology,
            "daemon_worker_capacity",
            ReliabilitySeverity::Pass,
            "All 3 workers healthy",
            ReliabilityReasonCode::WorkersHealthy,
        )
        .with_details("uptime_secs=200");
        let fp_a = DiagnosticFingerprint::from_diagnostic(&d_a);
        let fp_b = DiagnosticFingerprint::from_diagnostic(&d_b);
        assert_eq!(
            fp_a, fp_b,
            "rotating details must NOT change the fingerprint"
        );
        // TEST PASS: fingerprint stability across rotating details
    }
}

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

    fn obs(
        env_var: &'static str,
        raw: &str,
        resolved: Option<&str>,
        identity: Option<&str>,
    ) -> WrapperObservation {
        WrapperObservation {
            env_var,
            raw_value: raw.to_string(),
            resolved: resolved.map(PathBuf::from),
            identity: identity.map(str::to_string),
        }
    }

    fn single(observation: &WrapperObservation) -> CheckResult {
        let state = RustcWrapperState::default();
        rustc_wrapper_results(&state, std::slice::from_ref(observation))
            .pop()
            .expect("one check per observed wrapper")
    }

    #[test]
    fn no_wrappers_yields_single_pass() {
        let results = rustc_wrapper_results(&RustcWrapperState::default(), &[]);
        assert_eq!(results.len(), 1);
        assert_eq!(results[0].status, CheckStatus::Pass);
        assert!(results[0].message.contains("not set"));
    }

    #[test]
    fn workspace_first_enablement_warns_and_explains_one_time_rebuild() {
        let check = single(&obs(
            "RUSTC_WORKSPACE_WRAPPER",
            "/usr/local/bin/sccache",
            Some("/usr/local/bin/sccache"),
            Some("deadbeef"),
        ));
        assert_eq!(check.status, CheckStatus::Warning);
        assert!(
            check.message.contains("first observation"),
            "{:?}",
            check.message
        );
        assert!(
            check
                .details
                .as_deref()
                .unwrap_or_default()
                .contains("NOT a regression"),
            "must explicitly defuse the regression interpretation"
        );
    }

    #[test]
    fn plain_wrapper_is_pass_and_not_fingerprinted() {
        // Verified on current cargo: plain RUSTC_WRAPPER never moves
        // fingerprints, so a healthy wrapper is a Pass with an explicit
        // "no rebuild" explanation — not a warning.
        let check = single(&obs(
            "RUSTC_WRAPPER",
            "/usr/local/bin/sccache",
            Some("/usr/local/bin/sccache"),
            Some("deadbeef"),
        ));
        assert_eq!(check.status, CheckStatus::Pass);
        assert!(check.message.contains("wrapper active"));
        assert!(
            check
                .details
                .as_deref()
                .unwrap_or_default()
                .contains("does NOT force a rebuild"),
        );
    }

    #[test]
    fn plain_wrapper_drops_stale_state_marker() {
        // Semantics changed across cargo versions; a marker recorded for
        // the plain variable must be removed, never consulted.
        let state = RustcWrapperState {
            wrappers: BTreeMap::from([("RUSTC_WRAPPER".to_string(), "stale".to_string())]),
        };
        let results = rustc_wrapper_results(
            &state,
            &[obs(
                "RUSTC_WRAPPER",
                "/usr/bin/true",
                Some("/usr/bin/true"),
                Some("beef"),
            )],
        );
        assert_eq!(results[0].status, CheckStatus::Pass);
    }

    #[test]
    fn workspace_unchanged_wrapper_passes() {
        let state = RustcWrapperState {
            wrappers: BTreeMap::from([(
                "RUSTC_WORKSPACE_WRAPPER".to_string(),
                "deadbeef".to_string(),
            )]),
        };
        let results = rustc_wrapper_results(
            &state,
            &[obs(
                "RUSTC_WORKSPACE_WRAPPER",
                "/usr/bin/sccache",
                Some("/usr/bin/sccache"),
                Some("deadbeef"),
            )],
        );
        assert_eq!(results[0].status, CheckStatus::Pass);
        assert!(results[0].message.contains("unchanged"));
    }

    #[test]
    fn changed_value_warns() {
        let state = RustcWrapperState {
            wrappers: BTreeMap::from([(
                "RUSTC_WORKSPACE_WRAPPER".to_string(),
                "cafebabe".to_string(),
            )]),
        };
        let results = rustc_wrapper_results(
            &state,
            &[obs(
                "RUSTC_WORKSPACE_WRAPPER",
                "/usr/bin/sccache",
                Some("/usr/bin/sccache"),
                Some("deadbeef"),
            )],
        );
        assert_eq!(results[0].status, CheckStatus::Warning);
        assert!(results[0].message.contains("value changed"));
    }

    #[test]
    fn missing_binary_warns() {
        let check = single(&obs("RUSTC_WRAPPER", "/nope/missing-wrapper", None, None));
        assert_eq!(check.status, CheckStatus::Warning);
        assert!(check.message.contains("was not found"));
    }

    #[test]
    fn unhashable_workspace_wrapper_warns_and_skips_tracking() {
        // Without a hash we cannot track identity across runs, so this
        // is a warning every run — truthful and rare (unreadable file).
        let state = RustcWrapperState {
            wrappers: BTreeMap::from([(
                "RUSTC_WORKSPACE_WRAPPER".to_string(),
                "mywrapper".to_string(),
            )]),
        };
        let results = rustc_wrapper_results(
            &state,
            &[obs(
                "RUSTC_WORKSPACE_WRAPPER",
                "mywrapper",
                Some("/bin/mywrapper"),
                None,
            )],
        );
        assert_eq!(results[0].status, CheckStatus::Warning);
        assert!(results[0].message.contains("could not be hashed"));
    }

    #[test]
    fn workspace_wrapper_is_observed_independently() {
        let results = rustc_wrapper_results(
            &RustcWrapperState::default(),
            &[obs(
                "RUSTC_WORKSPACE_WRAPPER",
                "/usr/bin/true",
                Some("/usr/bin/true"),
                Some("beef"),
            )],
        );
        assert_eq!(results.len(), 1);
        assert!(results[0].message.contains("RUSTC_WORKSPACE_WRAPPER"));
    }

    #[test]
    fn wrapper_binary_path_resolves_via_which() {
        // `sh` exists on every dev/CI box; no PATH entry needed.
        let found = wrapper_binary_path("sh");
        assert!(found.is_some(), "which(sh) should resolve");
        assert!(!found.unwrap().as_os_str().is_empty());
        assert!(wrapper_binary_path("/definitely/not/here").is_none());
        assert!(wrapper_binary_path("definitely-not-a-real-binary-xyz").is_none());
    }

    #[test]
    fn identity_hash_is_stable_and_bounded() {
        let dir = tempfile::tempdir().expect("dir");
        let bin = dir.path().join("wrapper");
        std::fs::write(&bin, b"#!/bin/sh\nexec \"$@\"\n").expect("write");
        let a = hash_wrapper_identity(&bin).expect("hash");
        let b = hash_wrapper_identity(&bin).expect("hash");
        assert_eq!(a, b);
        assert_eq!(a.len(), 32);
        std::fs::write(&bin, b"#!/bin/sh\nexit 0\n").expect("rewrite");
        let c = hash_wrapper_identity(&bin).expect("hash");
        assert_ne!(a, c, "content change must change identity");
    }
}