Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
36.3 KB
Raw Blame
//! `ai-memory status` — report runtime config and persisted counts.
//!
//! Thin HTTP client. Calls `GET /admin/status` on the configured
//! server; renders the response as human text or JSON. Never opens
//! the store directly — the server is the source of truth.

mod presentation;

use ai_memory_core::fix_lines;
use ai_memory_llm::{ProviderHealthSnapshot, ProviderHealthStatus, ProviderRoleHealthSnapshot};
use anyhow::Result;
use serde::{Deserialize, Serialize};

use super::hook_spool::{SpoolHealth, spool_dir, spool_health};
use crate::cli::StatusArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, get_json};

/// Server-side hook-ingestion counters. `Option` at the call site so a
/// newer CLI pointed at an older server renders the rest of `status`
/// instead of failing to deserialise the whole report.
#[derive(Debug, Deserialize, Serialize)]
struct IngestReport {
    accepted: u64,
    #[serde(default)]
    dropped_unauthorized: u64,
    #[serde(default)]
    stored: u64,
    #[serde(default)]
    replayed: u64,
    #[serde(default)]
    resumed: u64,
    #[serde(default)]
    ignored_end: u64,
    #[serde(default)]
    dropped_collision: u64,
    #[serde(default)]
    dropped_invalid: u64,
    #[serde(default)]
    failed: u64,

    dropped_by_policy: u64,
    shed_saturated: u64,
    shed_rate_limited: u64,
    last_persisted_ms: Option<u64>,
}

/// Server-shaped response. Mirrors `ai_memory_mcp::admin::StatusReport`.
#[derive(Debug, Deserialize, Serialize)]
struct Report {
    /// Server binary version.
    version: String,
    /// Server-side data directory path.
    data_dir: String,
    /// Server bind address.
    bind: String,
    /// Server-side SQLite path.
    db_path: String,
    /// Lifetime counts.
    counts: Counts,
    /// Derived-index diagnostics.
    #[serde(default)]
    derived: Derived,
    /// Physical storage figures (absent from pre-#549 servers).
    #[serde(default)]
    storage: Storage,
    /// Hook-ingestion counters from the server process.
    #[serde(default)]
    ingest: Option<IngestReport>,
    /// Passive process-scoped provider health.
    #[serde(default)]
    providers: ProviderHealthSnapshot,
    /// Write-queue depth `(queued, capacity)` (2.0 servers).
    #[serde(default)]
    write_queue: Option<(usize, usize)>,
    /// Wiki-format state (2.0 servers).
    #[serde(default)]
    wiki_format: Option<WikiFormatReport>,
    /// SessionEnd consolidation queue (#1692). Absent from older servers, and
    /// skipped on the way out so their shape is unchanged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    consolidation: Option<ConsolidationReport>,
}

/// Consolidation queue as the server reports it: counts plus the sessions that
/// gave up, so a watchdog reads one JSON field instead of parsing logs.
#[derive(Debug, Clone, Deserialize, Serialize)]
struct ConsolidationReport {
    #[serde(default)]
    pending: u64,
    #[serde(default)]
    running: u64,
    #[serde(default)]
    completed: u64,
    #[serde(default)]
    failed: u64,
    #[serde(default)]
    failed_sessions: Vec<FailedConsolidationSession>,
}

/// One failed session from [`ConsolidationReport`].
#[derive(Debug, Clone, Deserialize, Serialize)]
struct FailedConsolidationSession {
    session_id: String,
    #[serde(default)]
    attempts: u32,
    #[serde(default)]
    failed_at_us: i64,
    #[serde(default)]
    last_error: String,
}

#[derive(Debug, Default, Deserialize, Serialize)]
struct WikiFormatReport {
    #[serde(default)]
    okf_migrated: bool,
    #[serde(default)]
    backup_archive: Option<String>,
    #[serde(default)]
    backup_archive_bytes: Option<u64>,
}

#[derive(Debug, Deserialize, Serialize)]
struct Counts {
    pages_latest: u64,
    pages_all: u64,
    sessions: u64,
    observations: u64,
}

#[derive(Debug, Default, Deserialize, Serialize)]
struct Derived {
    pages_rows: u64,
    pages_fts_rows: u64,
    observations_rows: u64,
    observations_fts_rows: u64,
    latest_pages_missing_embeddings: u64,
    #[serde(default)]
    latest_pages_unembeddable: u64,
    #[serde(default)]
    typed_links_from_latest_pages: Vec<(String, u64)>,
    #[serde(default)]
    embed_failures_unresolved: u64,
    #[serde(default)]
    embed_failures_recovered: u64,
    embedding_rows: u64,
    embedding_triples: Vec<EmbeddingTriple>,
    links_from_latest_pages: u64,
    unresolved_links_from_latest_pages: u64,
    stale_links_from_latest_pages: u64,
}

#[derive(Debug, Default, Deserialize, Serialize)]
struct Storage {
    page_size: u64,
    page_count: u64,
    freelist_count: u64,
    database_bytes: u64,
    reclaimable_bytes: u64,
    /// Free space on the filesystem holding the database (absent from
    /// pre-#629 servers).
    #[serde(default)]
    data_dir_free_bytes: Option<u64>,
}

#[derive(Debug, Deserialize, Serialize)]
struct EmbeddingTriple {
    provider: String,
    model: String,
    dim: u32,
    count: u64,
}

/// Run the `status` subcommand.
///
/// # Errors
/// Print local spool state when the server could not be reached.
///
/// Goes to stderr so it cannot corrupt `--json` consumers, which expect a
/// single object on stdout and get a non-zero exit here anyway. The
/// unreachable-server error still propagates unchanged; this only adds the
/// local half of the picture that the caller can actually act on.
/// Render the last-persisted stamp as an age, or `-` when this server
/// process has not written an event yet.
///
/// An age rather than a wall-clock time: the useful question is "how long
/// since anything landed", and the server may be in another timezone.
fn last_write_line(unix_ms: Option<u64>) -> String {
    let Some(ms) = unix_ms else {
        return "-".to_string();
    };
    let now = jiff::Timestamp::now().as_millisecond();
    let now_ms = u64::try_from(now).unwrap_or(0);
    spool_age_line(Some(now_ms.saturating_sub(ms)))
}

fn report_offline_spool(spool: &SpoolHealth, json: bool) {
    if json {
        if let Ok(rendered) = serde_json::to_string(spool) {
            eprintln!("local spool (server unreachable): {rendered}");
        }
        return;
    }
    eprintln!("local spool (server unreachable):");
    eprintln!("  pending:    {}", spool.pending);
    eprintln!("  oldest:     {}", spool_age_line(spool.oldest_age_ms));
    eprintln!("  retries:    {}", spool.retries_total);
    if spool.at_capacity() {
        eprintln!(
            "  The spool is full ({} events): newly captured events are dropped until \
             space is available. Bring the server back to stop the loss.",
            spool.capacity
        );
    } else if spool.pending > 0 {
        eprintln!(
            "  {} event(s) are queued locally and will be delivered once the \
             server is reachable again.",
            spool.pending
        );
    }
}

/// One line pointing at `ai-memory recover` while the server is down, when
/// there is actually something waiting: queued hook events or journaled
/// outage runs. Goes to stderr like the spool block above, so `--json`
/// consumers' stdout stays a single object.
fn report_offline_recovery_hint(config: &Config, spool: &SpoolHealth, json: bool) {
    for line in offline_recovery_hint_lines(config, spool, json) {
        eprintln!("{line}");
    }
}

/// The hint's lines, or empty when there is nothing to say. Split out from
/// the `eprintln!` wrapper so both renderings are assertable without a
/// running server.
///
/// An unreadable journal is reported in BOTH renderings. It is what opens
/// this gate in the first place (it defeats the early return), and a journal
/// we cannot parse reports `0` pending: staying silent about the error turned
/// the human line into `repair unrecorded runs (0 journaled)` and the
/// `--json` object into an all-clear, for a journal that is actually broken.
/// The online path at `status/presentation.rs` and `journal_error` in
/// [`json_report`] already treat it as reportable; this matches their label
/// and key.
fn offline_recovery_hint_lines(config: &Config, spool: &SpoolHealth, json: bool) -> Vec<String> {
    let (journal_pending, _, _, journal_error) = super::recovery::journal_summary(&config.data_dir);
    if spool.pending == 0 && journal_pending == 0 && journal_error.is_none() {
        return Vec::new();
    }
    if json {
        let rendered = serde_json::json!({
            "journal_pending": journal_pending,
            "journal_error": journal_error,
            "spool_pending": spool.pending,
        });
        return vec![format!("recovery hint (server unreachable): {rendered}")];
    }
    let mut lines = Vec::new();
    if let Some(error) = &journal_error {
        lines.push(format!("  error:      {error}"));
    }
    lines.push(format!(
        "  run `{}` once the server is back to deliver queued events and \
         repair unrecorded runs ({journal_pending} journaled)",
        fix_lines::RECOVER
    ));
    lines
}

/// The missing logon binary while the server is down, on stderr like the
/// spool block, so `--json` consumers' stdout stays a single object.
fn report_offline_logon_binary(
    problem: Option<&super::user_service::MissingLogonBinary>,
    json: bool,
) {
    let Some(problem) = problem else {
        return;
    };
    if json {
        if let Ok(rendered) = serde_json::to_string(problem) {
            eprintln!("windows logon (server unreachable): {rendered}");
        }
        return;
    }
    eprint!("{}", problem.render_human());
}

/// Which capture mode the hook would enforce for this install (#446).
///
/// Reads the same file the hook reads rather than keeping a second source of
/// truth that could drift from the one actually gating events. Anything
/// unreadable or unrecognised reports the historical default, matching the
/// hook's own fallback.
fn resolve_capture_mode(data_dir: &std::path::Path) -> &'static str {
    match std::fs::read_to_string(data_dir.join(crate::commands::hook::CAPTURE_MODE_FILE)) {
        Ok(text) if text.trim().eq_ignore_ascii_case("allowlist") => "allowlist",
        _ => "denylist",
    }
}

/// Returns an error if the server is unreachable, returns non-2xx, or
/// the response can't be parsed.
pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
    let ep = ServerEndpoint::from_config_resolving_auth(config).await;
    let capture_mode = resolve_capture_mode(&config.data_dir);

    // Read the spool BEFORE contacting the server, and surface it even when
    // that call fails.
    //
    // The spool exists to buffer hook events while the server is
    // unreachable, so "how much is queued locally?" is most worth answering
    // precisely when the server is down. Computing it after `get_json` meant
    // the one question this section exists for could not be asked in the one
    // situation that prompts it.
    let spool = spool_health(&spool_dir(&config.data_dir));
    // Also local, and for the same reason: a quarantined binary (#1280)
    // usually means nothing is listening.
    let windows_logon = super::user_service::check_logon_binary(&config.data_dir);

    let report: Report = match get_json::<Report>(&ep, "/admin/status", &[]).await {
        Ok(report) => report,
        Err(err) => {
            report_offline_spool(&spool, args.json);
            report_offline_recovery_hint(config, &spool, args.json);
            report_offline_logon_binary(windows_logon.as_ref(), args.json);
            return Err(err);
        }
    };
    let (journal_pending, journal_degraded, journal_finish_failed, journal_error) =
        super::recovery::journal_summary(&config.data_dir);
    // `/admin/status` answered. Without a credential that can only mean the
    // server does not require one.
    let auth_posture = crate::local_auth::AuthPosture::classify(ep.auth_token.is_none(), &ep.url);

    if args.json {
        println!(
            "{}",
            serde_json::to_string_pretty(&json_report(
                report,
                spool,
                journal_pending,
                journal_degraded,
                journal_finish_failed,
                journal_error,
                capture_mode,
                &ep,
                auth_posture,
                windows_logon.as_ref(),
            ))?
        );
    } else {
        presentation::render(
            &crate::terminal::Terminal::stdout(&config.runtime_env),
            presentation::View {
                report: &report,
                ep: &ep,
                spool: &spool,
                journal_pending,
                journal_degraded,
                journal_finish_failed,
                journal_error: journal_error.as_deref(),
                capture_mode,
                auth_posture,
                windows_logon: windows_logon.as_ref(),
            },
        );
    }
    Ok(())
}

/// One line per `llm_candidates` entry: label, whether it answered the last
/// completed call, and its most notable state (an open circuit takes
/// priority over a stale last-error status).
fn fallback_candidate_line(candidate: &ai_memory_llm::CandidateHealth) -> String {
    let mut line = format!("{}/{}", candidate.provider, candidate.model);
    if candidate.last_selected {
        line.push_str(" (last selected)");
    }
    if let Some(until) = &candidate.circuit_open_until {
        line.push_str(&format!(" — circuit open until {until}"));
    } else if let Some(status) = candidate.last_error_status {
        line.push_str(&format!(" — last error: status {status}"));
    } else if let Some(class) = &candidate.last_error_class {
        line.push_str(&format!(" — last error: {class}"));
    }
    line
}

/// Render a spool age (ms) as a compact human duration, or `-` when the spool
/// holds no events. Allowed to saturate: an operator reading a stuck-spool
/// diagnosis wants the magnitude, not sub-second precision.
pub(super) fn spool_age_line(age_ms: Option<u64>) -> String {
    let Some(ms) = age_ms else {
        return "-".to_string();
    };
    let secs = ms / 1000;
    if secs < 60 {
        format!("{secs}s")
    } else if secs < 3600 {
        format!("{}m {}s", secs / 60, secs % 60)
    } else if secs < 86_400 {
        format!("{}h {}m", secs / 3600, (secs % 3600) / 60)
    } else {
        format!("{}d {}h", secs / 86_400, (secs % 86_400) / 3600)
    }
}

/// This binary's version. `report.version` is the server's, and the two drift
/// apart when a split install (native client, server in a container or on
/// another host) upgrades only one side.
const CLIENT_VERSION: &str = env!("CARGO_PKG_VERSION");

/// The client line of the human report, plus a warning when the client and
/// the server differ in major version, the only difference the semver policy
/// treats as breaking. A version that does not start with a number never
/// warns.
fn client_version_lines(server_version: &str, client_version: &str) -> Vec<String> {
    let mut lines = vec![format!("ai-memory {client_version} (client)")];
    let major = |version: &str| -> Option<u64> {
        version
            .trim_start_matches('v')
            .split('.')
            .next()?
            .parse()
            .ok()
    };
    if let (Some(server), Some(client)) = (major(server_version), major(client_version))
        && server != client
    {
        lines.push(format!(
            "⚠ The client is {client_version} but the server is {server_version}: across a \
             major version they may not understand each other's requests. Upgrade the older side."
        ));
    }
    lines
}

#[allow(clippy::too_many_arguments)]
fn json_report(
    report: Report,
    spool: SpoolHealth,
    journal_pending: usize,
    journal_degraded: usize,
    journal_finish_failed: usize,
    journal_error: Option<String>,
    capture_mode: &str,
    endpoint: &ServerEndpoint,
    auth_posture: crate::local_auth::AuthPosture,
    windows_logon: Option<&super::user_service::MissingLogonBinary>,
) -> serde_json::Value {
    let mut value = serde_json::json!({
        "version": report.version,
        "data_dir": report.data_dir,
        "bind": report.bind,
        "db_path": report.db_path,
        "counts": {
            "pages_latest": report.counts.pages_latest,
            "pages_all": report.counts.pages_all,
            "sessions": report.counts.sessions,
            "observations": report.counts.observations,
        },
        "derived": report.derived,
        "storage": report.storage,
        "providers": report.providers,
        "spool": spool,
        "recovery": {
            "journal_pending": journal_pending,
            "degraded_runs": journal_degraded,
            "finish_failed_runs": journal_finish_failed,
            "journal_error": journal_error,
        },
        "capture_mode": capture_mode,
        "ingest": report.ingest,
        "client": {
            "version": CLIENT_VERSION,
            "server_url": endpoint.url,
            "auth": endpoint.auth_token.is_some(),
        },
        "auth_posture": { "posture": auth_posture, "fix": auth_posture.fix() },
    });
    // Absent when there is nothing to say, so the shape consumers read is
    // unchanged.
    if let Some(problem) = windows_logon {
        value["windows_logon"] = serde_json::json!(problem);
    }
    // Present whenever the server reports it; an older server has no queue in
    // `/admin/status`, and its shape stays exactly as before (#1692).
    if let Some(consolidation) = report.consolidation {
        value["consolidation"] = serde_json::json!(consolidation);
    }
    value
}

fn provider_health_line(role: &ProviderRoleHealthSnapshot) -> String {
    match role.status {
        ProviderHealthStatus::Disabled => "disabled".to_string(),
        ProviderHealthStatus::Unknown => {
            format!("{} unknown (no calls yet)", provider_label(role))
        }
        ProviderHealthStatus::Ok => {
            let when = role
                .last_call_at
                .as_ref()
                .map(ToString::to_string)
                .unwrap_or_else(|| "unknown time".to_string());
            format!("{} ok (last call: {when})", provider_label(role))
        }
        ProviderHealthStatus::Error => {
            let detail = error_detail(role);
            format!("{} error ({detail})", provider_label(role))
        }
    }
}

fn provider_label(role: &ProviderRoleHealthSnapshot) -> String {
    match (&role.provider, &role.model, role.dim) {
        (Some(provider), Some(model), Some(dim)) => format!("{provider}/{model} ({dim}d)"),
        (Some(provider), Some(model), None) => format!("{provider}/{model}"),
        (Some(provider), None, _) => provider.clone(),
        _ => "provider".to_string(),
    }
}

fn error_detail(role: &ProviderRoleHealthSnapshot) -> String {
    let mut parts = Vec::new();
    if let Some(status) = role.last_error_status {
        parts.push(format!("status {status}"));
    }
    if let Some(message) = &role.last_error_message
        && !message.is_empty()
    {
        parts.push(message.clone());
    }
    if let Some(when) = &role.last_error_at {
        parts.push(format!("last error: {when}"));
    }
    if parts.is_empty() {
        "last call failed".to_string()
    } else {
        parts.join("; ")
    }
}

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

    #[test]
    fn status_json_keeps_existing_fields_and_adds_recovery_compatibly() {
        let report_json = serde_json::json!({
            "version": "2.6.0",
            "data_dir": "/data",
            "bind": "127.0.0.1:49374",
            "db_path": "/data/db/memory.sqlite",
            "counts": {"pages_latest": 1, "pages_all": 2, "sessions": 3, "observations": 4},
            "derived": {
                "pages_rows": 0, "pages_fts_rows": 0,
                "observations_rows": 0, "observations_fts_rows": 0,
                "latest_pages_missing_embeddings": 0,
                "embedding_rows": 0, "embedding_triples": [],
                "links_from_latest_pages": 0,
                "unresolved_links_from_latest_pages": 0,
                "stale_links_from_latest_pages": 0
            },
            "storage": {
                "page_size": 0, "page_count": 0, "freelist_count": 0,
                "database_bytes": 0, "reclaimable_bytes": 0
            },
            "providers": ProviderHealthSnapshot::default(),
            "ingest": null,
            "write_queue": null,
            "wiki_format": null
        });
        let report: Report = serde_json::from_value(report_json.clone()).unwrap();
        let endpoint = ServerEndpoint::from_pair(Some("http://127.0.0.1:49374".into()), None);
        let value = json_report(
            report,
            SpoolHealth::default(),
            2,
            1,
            1,
            None,
            "denylist",
            &endpoint,
            crate::local_auth::AuthPosture::NoneLoopback,
            None,
        );
        assert!(value.get("windows_logon").is_none(), "{value}");
        assert_eq!(value["auth_posture"]["posture"], "none_loopback");
        assert_eq!(value["auth_posture"]["fix"], "ai-memory auth enable");
        for key in [
            "version",
            "data_dir",
            "bind",
            "db_path",
            "counts",
            "derived",
            "storage",
            "providers",
            "spool",
            "capture_mode",
            "ingest",
            "client",
        ] {
            assert!(value.get(key).is_some(), "missing legacy status key {key}");
        }
        assert_eq!(value["recovery"]["journal_pending"], 2);
        assert_eq!(value["counts"]["observations"], 4);
        assert!(
            value.get("consolidation").is_none(),
            "an older server has no queue, and its shape is unchanged: {value}"
        );

        // A server that reports its queue adds exactly that one key (#1692).
        let mut with_queue = report_json.clone();
        with_queue["consolidation"] = serde_json::json!({
            "pending": 2,
            "running": 0,
            "completed": 9,
            "failed": 1,
            "failed_sessions": [{
                "session_id": "0192b6a1-4c2e-7d3f-8a5b-1234567890ab",
                "attempts": 5,
                "failed_at_us": 1_700_000_000_000_000_i64,
                "last_error": "provider error 400: quota exceeded",
            }],
        });
        let queued = json_report(
            serde_json::from_value(with_queue).unwrap(),
            SpoolHealth::default(),
            0,
            0,
            0,
            None,
            "denylist",
            &endpoint,
            crate::local_auth::AuthPosture::NoneLoopback,
            None,
        );
        assert_eq!(queued["consolidation"]["failed"], 1);
        assert_eq!(queued["consolidation"]["pending"], 2);
        assert_eq!(
            queued["consolidation"]["failed_sessions"][0]["session_id"],
            "0192b6a1-4c2e-7d3f-8a5b-1234567890ab"
        );
        assert_eq!(queued["consolidation"]["failed_sessions"][0]["attempts"], 5);

        // The server's version stays at the top level; the client's is new.
        assert_eq!(value["version"], "2.6.0");
        assert_eq!(value["client"]["version"], env!("CARGO_PKG_VERSION"));
        assert_eq!(value["client"]["server_url"], "http://127.0.0.1:49374");
        assert!(
            value.get("consolidation").is_none(),
            "an older server has no queue, and its shape is unchanged: {value}"
        );

        // A server that reports its queue adds exactly that one key (#1692).
        let mut with_queue = report_json.clone();
        with_queue["consolidation"] = serde_json::json!({
            "pending": 2,
            "running": 0,
            "completed": 9,
            "failed": 1,
            "failed_sessions": [{
                "session_id": "0192b6a1-4c2e-7d3f-8a5b-1234567890ab",
                "attempts": 5,
                "failed_at_us": 1_700_000_000_000_000_i64,
                "last_error": "provider error 400: quota exceeded",
            }],
        });
        let queued = json_report(
            serde_json::from_value(with_queue).unwrap(),
            SpoolHealth::default(),
            0,
            0,
            0,
            None,
            "denylist",
            &endpoint,
            crate::local_auth::AuthPosture::NoneLoopback,
            None,
        );
        assert_eq!(queued["consolidation"]["failed"], 1);
        assert_eq!(queued["consolidation"]["pending"], 2);
        assert_eq!(
            queued["consolidation"]["failed_sessions"][0]["session_id"],
            "0192b6a1-4c2e-7d3f-8a5b-1234567890ab"
        );
        assert_eq!(queued["consolidation"]["failed_sessions"][0]["attempts"], 5);

        // A missing logon binary (#1280) adds one key and changes no other.
        let problem = super::super::user_service::MissingLogonBinary {
            classification: super::super::user_service::LOGON_BINARY_MISSING,
            executable: r"C:\bin\ai-memory.exe".into(),
            detail: "gone".into(),
            fix: "restore it",
        };
        let warned = json_report(
            serde_json::from_value(report_json).unwrap(),
            SpoolHealth::default(),
            2,
            1,
            1,
            None,
            "denylist",
            &endpoint,
            crate::local_auth::AuthPosture::NoneLoopback,
            Some(&problem),
        );
        assert_eq!(
            warned["windows_logon"]["classification"],
            "logon_binary_missing"
        );
        assert_eq!(
            warned["windows_logon"]["executable"],
            r"C:\bin\ai-memory.exe"
        );
        assert_eq!(warned["windows_logon"]["fix"], "restore it");
        let mut without = warned.clone();
        without.as_object_mut().unwrap().remove("windows_logon");
        assert_eq!(without, value);
    }

    #[test]
    fn client_version_line_warns_only_across_a_major_version() {
        let same = client_version_lines("3.1.1", "3.1.1");
        assert_eq!(same, ["ai-memory 3.1.1 (client)"]);
        // A minor or patch difference is shown, not warned about.
        assert_eq!(client_version_lines("3.2.0", "3.1.1").len(), 1);
        assert_eq!(client_version_lines("v3.0.0", "3.1.1").len(), 1);

        let across = client_version_lines("2.6.0", "3.1.1");
        assert_eq!(across.len(), 2, "{across:?}");
        assert!(
            across[1].contains("client is 3.1.1 but the server is 2.6.0"),
            "{across:?}"
        );
        assert_eq!(client_version_lines("4.0.0", "3.1.1").len(), 2);
    }

    #[test]
    fn client_version_line_never_warns_on_an_unparseable_version() {
        assert_eq!(client_version_lines("dev", "3.1.1").len(), 1);
        assert_eq!(client_version_lines("", "3.1.1").len(), 1);
    }

    #[test]
    fn ingest_additions_default_for_older_servers_and_roundtrip() {
        let old = serde_json::json!({"accepted": 2, "dropped_by_policy": 1, "shed_saturated": 0, "shed_rate_limited": 0, "last_persisted_ms": null});
        let report: IngestReport = serde_json::from_value(old).unwrap();
        let mut value = serde_json::to_value(report).unwrap();
        for name in [
            "stored",
            "replayed",
            "resumed",
            "ignored_end",
            "dropped_unauthorized",
            "dropped_collision",
            "dropped_invalid",
            "failed",
        ] {
            assert_eq!(value[name], 0);
            value[name] = serde_json::json!(7);
        }
        let current: IngestReport = serde_json::from_value(value.clone()).unwrap();
        assert_eq!(serde_json::to_value(current).unwrap(), value);
    }

    /// #428's counters and #446's gate compose into a trap: under allowlist
    /// mode an unmarked repository never sends, so `accepted: 0` with an empty
    /// spool looks exactly like a broken install. `status` must be able to say
    /// which of the two it is. Resolved from the same file the hook enforces
    /// from, so the two cannot drift.
    #[test]
    fn capture_mode_defaults_to_denylist_when_unset() {
        let tmp = tempfile::tempdir().unwrap();
        assert_eq!(resolve_capture_mode(tmp.path()), "denylist");
    }

    #[test]
    fn capture_mode_reports_allowlist_when_the_hook_would_enforce_it() {
        let tmp = tempfile::tempdir().unwrap();
        std::fs::write(
            tmp.path().join(crate::commands::hook::CAPTURE_MODE_FILE),
            "allowlist\n",
        )
        .unwrap();
        assert_eq!(resolve_capture_mode(tmp.path()), "allowlist");
        // The status reader and the hook enforcer must agree.
        assert_eq!(
            crate::commands::hook::CAPTURE_MODE_FILE,
            "capture-mode",
            "status reads the file the hook enforces from"
        );
    }
    use jiff::Timestamp;

    /// The offline path must be readable and, critically, must not write the
    /// spool object to stdout in `--json` mode: consumers there expect one
    /// object and this call exits non-zero anyway.
    #[test]
    fn offline_spool_report_is_content_free_and_serialises() {
        let spool = SpoolHealth {
            pending: 2,
            oldest_age_ms: Some(900_000),
            retries_total: 4,
            ..SpoolHealth::default()
        };
        let rendered = serde_json::to_string(&spool).expect("SpoolHealth serialises");
        assert_eq!(
            rendered,
            r#"{"pending":2,"oldest_age_ms":900000,"retries_total":4,"capacity":3}"#
        );
        // The shape is the contract: counts and ages only. If a field
        // carrying captured text is ever added, this fails loudly.
        let value: serde_json::Value = serde_json::from_str(&rendered).unwrap();
        let keys: Vec<_> = value.as_object().unwrap().keys().cloned().collect();
        assert_eq!(
            keys,
            vec!["pending", "oldest_age_ms", "retries_total", "capacity"]
        );

        // Both render paths must tolerate an empty spool.
        report_offline_spool(&SpoolHealth::default(), false);
        report_offline_spool(&SpoolHealth::default(), true);
        report_offline_spool(&spool, false);
        report_offline_spool(&spool, true);
    }

    /// A pre-#629 server's `/admin/status` response has no
    /// `data_dir_free_bytes` key at all; the field must default to `None`
    /// rather than fail the whole `storage` object.
    #[test]
    fn storage_deserializes_without_free_space_from_an_older_server() {
        let storage: Storage = serde_json::from_str(
            r#"{"page_size":4096,"page_count":10,"freelist_count":0,
                "database_bytes":40960,"reclaimable_bytes":0}"#,
        )
        .unwrap();
        assert_eq!(storage.data_dir_free_bytes, None);
    }

    /// The signal #629 adds: once a server reports free space, it round-trips
    /// through the CLI's own struct unchanged.
    #[test]
    fn storage_deserializes_free_space_from_a_current_server() {
        let storage: Storage = serde_json::from_str(
            r#"{"page_size":4096,"page_count":10,"freelist_count":0,
                "database_bytes":40960,"reclaimable_bytes":0,
                "data_dir_free_bytes":80740352}"#,
        )
        .unwrap();
        assert_eq!(storage.data_dir_free_bytes, Some(80_740_352));
    }

    #[test]
    fn provider_health_line_renders_unknown_and_disabled() {
        assert_eq!(
            provider_health_line(&ProviderRoleHealthSnapshot::default()),
            "disabled"
        );

        let role = ProviderRoleHealthSnapshot {
            status: ProviderHealthStatus::Unknown,
            provider: Some("openai".to_string()),
            model: Some("gpt-5.5".to_string()),
            ..ProviderRoleHealthSnapshot::default()
        };
        assert_eq!(
            provider_health_line(&role),
            "openai/gpt-5.5 unknown (no calls yet)"
        );
    }

    #[test]
    fn provider_health_line_renders_error_details() {
        let when = "2026-05-28T12:00:00Z".parse::<Timestamp>().unwrap();
        let role = ProviderRoleHealthSnapshot {
            status: ProviderHealthStatus::Error,
            provider: Some("anthropic-oauth".to_string()),
            model: Some("claude-sonnet-4-6".to_string()),
            last_error_at: Some(when),
            last_error_status: Some(401),
            last_error_message: Some("bad token".to_string()),
            ..ProviderRoleHealthSnapshot::default()
        };

        assert!(provider_health_line(&role).contains("anthropic-oauth/claude-sonnet-4-6 error"));
        assert!(provider_health_line(&role).contains("status 401"));
        assert!(provider_health_line(&role).contains("bad token"));
    }

    #[test]
    fn fallback_candidate_line_marks_the_last_selected_candidate() {
        let candidate = ai_memory_llm::CandidateHealth {
            provider: "gemini".to_string(),
            model: "gemini-3.5-flash".to_string(),
            last_selected: true,
            last_success_at: Some("2026-05-28T12:00:00Z".parse::<Timestamp>().unwrap()),
            last_error_at: None,
            last_error_status: None,
            last_error_class: None,
            circuit_open_until: None,
        };
        let line = fallback_candidate_line(&candidate);
        assert!(line.contains("gemini/gemini-3.5-flash"));
        assert!(line.contains("last selected"));
    }

    #[test]
    fn fallback_candidate_line_surfaces_an_open_circuit_over_a_stale_error() {
        let when = "2026-05-28T12:00:30Z".parse::<Timestamp>().unwrap();
        let candidate = ai_memory_llm::CandidateHealth {
            provider: "openai-compat".to_string(),
            model: "local-router".to_string(),
            last_selected: false,
            last_success_at: None,
            last_error_at: Some(when),
            last_error_status: Some(503),
            last_error_class: Some("provider".to_string()),
            circuit_open_until: Some(when),
        };
        let line = fallback_candidate_line(&candidate);
        assert!(line.contains("openai-compat/local-router"));
        assert!(line.contains("circuit open until"));
        assert!(!line.contains("last error"));
    }

    /// A `Config` whose data dir is `dir`, so the journal read under test
    /// hits a temp dir rather than the developer's real install.
    fn config_for(dir: &std::path::Path) -> Config {
        Config {
            data_dir: dir.to_path_buf(),
            ..Config::default()
        }
    }

    #[test]
    fn offline_recovery_hint_reports_an_unreadable_journal_to_humans() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::write(
            super::super::recovery::journal_path(temp.path()),
            b"not json",
        )
        .unwrap();
        let lines =
            offline_recovery_hint_lines(&config_for(temp.path()), &SpoolHealth::default(), false);
        let rendered = lines.join("\n");
        assert!(
            rendered.contains("error:"),
            "an unreadable journal must be named, not reported as `0 journaled`: {rendered}"
        );
        assert!(
            rendered.contains("recovery-journal.json"),
            "the error must say which file failed: {rendered}"
        );
    }

    #[test]
    fn offline_recovery_hint_json_reports_an_unreadable_journal() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::write(
            super::super::recovery::journal_path(temp.path()),
            b"not json",
        )
        .unwrap();
        let lines =
            offline_recovery_hint_lines(&config_for(temp.path()), &SpoolHealth::default(), true);
        assert_eq!(lines.len(), 1, "{lines:?}");
        let payload = lines[0].split_once(": ").expect("prefix then object").1;
        let value: serde_json::Value = serde_json::from_str(payload).unwrap();
        assert_eq!(value["journal_pending"], 0);
        assert!(
            value["journal_error"].is_string(),
            "a monitoring consumer must not read `journal_pending: 0` as an \
             all-clear while the journal is unreadable: {value}"
        );
    }

    #[test]
    fn offline_recovery_hint_stays_quiet_on_a_healthy_install() {
        let temp = tempfile::tempdir().unwrap();
        for json in [false, true] {
            assert!(
                offline_recovery_hint_lines(
                    &config_for(temp.path()),
                    &SpoolHealth::default(),
                    json
                )
                .is_empty(),
                "nothing queued and no journal error must print nothing (json={json})"
            );
        }
    }

    #[test]
    fn spool_age_line_renders_durations_and_empty() {
        assert_eq!(spool_age_line(None), "-");
        assert_eq!(spool_age_line(Some(0)), "0s");
        assert_eq!(spool_age_line(Some(59_999)), "59s");
        assert_eq!(spool_age_line(Some(60_000)), "1m 0s");
        assert_eq!(spool_age_line(Some(3_661_000)), "1h 1m");
        assert_eq!(spool_age_line(Some(172_800_000)), "2d 0h");
    }
}