car_inference/

doctor.rs

//! `car doctor` — an offline health check + repair for a CAR install.
//!
//! Built to run *when things are broken*. It touches only the local filesystem
//! (`~/.car` and the shared HuggingFace model cache), never the daemon, so it
//! still works after a half-finished reinstall or when `car-server` won't even
//! start. It surfaces — and, in `--repair` mode, fixes what's safe to fix — the
//! failure modes that successive installs and a shared, externally-mutated cache
//! produce:
//!
//!   * **Corrupt model weights** — truncated/byte-rotted/externally-deleted files
//!     in the model cache (reuses the Task-1/2 integrity primitives in
//!     [`crate::download`]).
//!   * **Incomplete installs** — a managed model dir whose manifest was symlinked
//!     into the HuggingFace snapshot but whose weights never arrived, i.e. what
//!     an interrupted `car models pull` leaves behind (Parslee-ai/car#616).
//!   * **Unparseable state files** — a `~/.car/*.json` an older version wrote in a
//!     shape this binary can't read, or a partially-written file.
//!   * **Version skew** — state last written by a different CAR version than the
//!     binary now running (read from the `version.json` stamp).
//!   * **Abandoned partial downloads** — `*.sync.part` blobs stranded in the
//!     HuggingFace cache. Reported with sizes, never deleted (see
//!     [`find_leftovers`]).
//!   * **Empty event journals** — a zero-byte journal per session that never
//!     executed anything; reaped under `--repair` (see [`find_empty_journals`]).
//!   * **Leftovers** — top-level `~/.car` entries this version doesn't recognize,
//!     which may be debris from a previous install.
//!   * **An unusable daemon `TMPDIR`** — the daemon probes the temp directory it
//!     inherited when it starts and records the result under `<CAR_HOME>/doctor/`
//!     ([`record_daemon_tmpdir_probe`]). Doctor reads that record from disk, so a
//!     daemon handed a torn-down installer-sandbox `TMPDIR` is visible without
//!     contacting it (Parslee-ai/car#1494).
//!
//! Repair is deliberately conservative: it purges *provably* corrupt cache files
//! (so the next daemon run re-downloads them), backs up unparseable state files
//! to `<name>.corrupt.bak` rather than deleting them, removes provably-empty
//! journals, and refreshes the version stamp (reporting that only when the stamp
//! actually moved). It never deletes unrecognized entries, partial downloads in
//! the shared HuggingFace cache, or anything else it can't prove is bad —
//! diagnosis names them and leaves the decision to the operator.

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

use serde::{Deserialize, Serialize};

use crate::download::{
    cache_file_usable, purge_corrupt_cache_files, verify_cache_file, CacheIntegrity,
};

/// JSON state files CAR writes directly under `~/.car/`. Used both to validate
/// each (does it parse? what schema version?) and to tell recognized files from
/// possible leftovers. Owned across several crates, but the check is generic
/// (parse as JSON), so no cross-crate type dependency is needed.
const KNOWN_STATE_FILES: &[&str] = &[
    "messaging.json",
    "models.json",
    "connectors.json",
    "car-connectors.json",
    "agents.json",
    "routing.json",
    "declagents.json",
    "lane-defaults.json",
    "update-prefs.json",
    "upgrade-cache.json",
    "catalog-cache.json",
    "discovered_models.json",
    "a2a-peers.json",
    "external-agents.jsonl",
    "nudge-state.json",
    "benchmark_priors.json",
    "key_pool_stats.json",
    "model_profiles.json",
    "agent-permissions.json",
    "version.json",
    // Names-only index for the OS-keychain secret store (car-ffi-common's
    // `INDEX_FILE`), written on every platform whenever a secret is stored —
    // and load-bearing on Windows/Linux, whose keychains have no portable
    // enumeration. Absent on a fresh install with no stored secrets, which is
    // why its omission here only surfaced once `car auth login` / `car keys`
    // had run (e.g. validating on Windows): doctor wrongly flagged the live
    // file as a possible older-install leftover and invited its removal.
    "secret_index.json",
    // Durable "this Parslee environment has no OpenRouter upstream" observation
    // (car#786). Written by whichever process first gets that gateway answer, so
    // it is absent until one does — same shape as secret_index.json above, and
    // the same reason it belongs here: an unrecognized live state file gets
    // reported as possible debris from an older install and the user is invited
    // to delete it.
    "gateway-state.json",
    // Durable "the Parslee server rejected this credential" observation
    // (car#887), the sibling of gateway-state.json above and here for exactly
    // the same reason: written only once some process has actually been
    // rejected, so it is absent on a healthy install and would otherwise be
    // reported as older-install debris on precisely the machines where it is
    // doing its job.
    "parslee-credential-state.json",
    // Written by car-inference::resource_policy for the local-model resource policy.
    "model-resource-policy.json",
    // Written by car-auth::authority_hint for prompt-free Parslee auth discovery.
    "parslee-auth-authority.json",
];

/// Recognized files that are deliberately NOT JSON and must never be parsed or
/// moved aside. `env` is a dotenv `KEY=VALUE` file (loaded by `env_loader`,
/// holds API keys) — JSON-validating it would flag a healthy install and, under
/// `--repair`, rename the user's secrets file to `env.corrupt.bak`.
const KNOWN_NON_JSON_FILES: &[&str] = &[
    "env",
    // Written by car-server for the daemon's persistent peer signing identity.
    "peer-identity.key",
];

/// Subdirectories CAR creates under `~/.car/`. Anything else at the top level is
/// reported as unrecognized (a possible leftover), never auto-removed.
const KNOWN_DIRS: &[&str] = &[
    "models",
    "journals",
    "logs",
    "agents",
    "runs",
    "run",
    "workflow-runs",
    "workflows",
    "tasks",
    "trajectories",
    "registry",
    "meetings",
    "speech-runtime",
    "visual-runtime",
    "coder",
    "projects",
    "memory",
    // `car reason` state — created by car-cli, holds model_profiles.json. CAR
    // makes it on the in-process path, so it exists on any machine that has run
    // `car reason` once, and doctor was reporting a live directory as possible
    // leftover debris from an older install.
    "reason",
    "doctor",
    "bin",
    "voiceprints",
    "sync",
    // Written by car-server-core::run_store for completed-proposal owner indexes.
    "proposal-completed-index",
    // Written by car-server's self-healing detection ledger.
    "selfheal",
];

/// File-name suffixes for volatile/runtime artifacts that are never "leftovers":
/// lockfiles, temp/backup files, binary caches, and append-only logs.
const TOLERATED_SUFFIXES: &[&str] = &[".lock", ".tmp", ".bak", ".bin", ".jsonl"];

/// The on-disk version stamp (`~/.car/version.json`). Written by the daemon on
/// boot and refreshed by `doctor --repair`; read by `doctor` to detect skew
/// between the binary and the state it's operating on.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VersionStamp {
    /// The CAR package version (`CARGO_PKG_VERSION`) that last wrote state.
    pub car_version: String,
    /// The state-schema generation. Bumped only on a breaking change to the
    /// on-disk layout, independent of the package version. A reader newer than
    /// this can migrate; older than this should refuse rather than corrupt.
    pub state_schema_version: u32,
    /// The version that wrote the state THIS stamp replaced — the predecessor
    /// carried across the most recent upgrade.
    ///
    /// Without it, skew detection was dead on arrival (car#881): the daemon
    /// stamps on every boot and CarHost is a login item, so by the time anyone
    /// runs `car doctor` the stamp already reads as the running binary and the
    /// evidence that older state exists is gone. Observed directly — a stamp
    /// saying `0.47.0` beside an `agents.json` last written in the v0.39 era.
    ///
    /// Only updated when the version actually CHANGES. Rewriting it on every
    /// boot would collapse it to the current version and lose the real
    /// predecessor after one restart, which is the same bug one level down.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub previous_car_version: Option<String>,
    /// The schema generation of the state this stamp replaced. Same update rule.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub previous_state_schema_version: Option<u32>,
}

/// The current state-schema generation this binary writes/expects. Start at 1;
/// bump when a `~/.car` layout change requires migration.
pub const STATE_SCHEMA_VERSION: u32 = 1;

impl VersionStamp {
    /// The stamp this binary would write on a machine with no prior state.
    pub fn current() -> Self {
        VersionStamp {
            car_version: env!("CARGO_PKG_VERSION").to_string(),
            state_schema_version: STATE_SCHEMA_VERSION,
            previous_car_version: None,
            previous_state_schema_version: None,
        }
    }

    /// The stamp to write now, given what is already on disk.
    ///
    /// Carries the predecessor forward rather than overwriting it: an upgrade
    /// records what it replaced, and every later boot on the same version keeps
    /// that record instead of collapsing it to itself.
    pub fn succeeding(existing: Option<&VersionStamp>) -> Self {
        let mut next = VersionStamp::current();
        if let Some(prior) = existing {
            if prior.car_version != next.car_version
                || prior.state_schema_version != next.state_schema_version
            {
                next.previous_car_version = Some(prior.car_version.clone());
                next.previous_state_schema_version = Some(prior.state_schema_version);
            } else {
                next.previous_car_version = prior.previous_car_version.clone();
                next.previous_state_schema_version = prior.previous_state_schema_version;
            }
        }
        next
    }
}

/// What stamping observed. Returned so the daemon can act on an upgrade instead
/// of silently erasing the evidence of one.
#[derive(Debug, Clone)]
pub struct StampTransition {
    /// The stamp found on disk, if any. `None` on a fresh install — or when the
    /// file was unreadable, which is deliberately not distinguished here: both
    /// mean "no usable predecessor", and doctor reports an unparseable stamp
    /// separately.
    pub previous: Option<VersionStamp>,
    /// What was written.
    pub current: VersionStamp,
}

impl StampTransition {
    /// The package version changed since state was last written.
    pub fn upgraded(&self) -> bool {
        self.previous
            .as_ref()
            .is_some_and(|p| p.car_version != self.current.car_version)
    }

    /// On-disk state uses a schema generation NEWER than this binary
    /// understands — i.e. a downgrade.
    ///
    /// This is the case `STATE_SCHEMA_VERSION`'s own contract calls out ("older
    /// than this should refuse rather than corrupt") and that nothing acted on.
    /// A user reverting to an older CAR would silently operate on state written
    /// to a layout it does not know.
    pub fn schema_from_the_future(&self) -> bool {
        self.previous
            .as_ref()
            .is_some_and(|p| p.state_schema_version > self.current.state_schema_version)
    }
}

/// Canonical CAR **state** directory. Mirrors the resolution every other part
/// of CAR uses so `car doctor` always inspects the *same* directory the daemon
/// and registry write to.
///
/// That invariant is the whole point, and it is why this now honors `CAR_HOME`.
/// It used to refuse one, on the reasoning that "nothing else in CAR honors an
/// override, and a doctor that diagnoses a different dir than the real install
/// could report a corrupt install as healthy". The premise stopped being true
/// when `CAR_HOME` shipped: for a relocated daemon, `$CAR_HOME` *is* the real
/// install, and it is a doctor still reading `~/.car` that would grade the
/// wrong directory. The conclusion is unchanged — diagnose the install that is
/// actually running — so the resolution follows [`car_home::root_or_relative`]
/// wherever it goes.
///
/// State only, though. The same "diagnose what is running" argument cuts the
/// other way for model **weights**, which stay in the machine-shared
/// `~/.car/models` no matter where the state root points: following the
/// override there would make `car doctor` stop looking at the very cache the
/// relocated daemon loads from. [`diagnose`] therefore pairs this with
/// [`crate::default_models_dir`] instead of joining `models` onto it.
pub fn car_home() -> PathBuf {
    // `::` — this function shares its name with the crate it calls.
    ::car_home::root_or_relative()
}

/// Write/refresh the `version.json` stamp under `car_home`. Called on daemon
/// boot and by `doctor --repair`. Best-effort: a failure to stamp must never
/// block startup, so the caller logs and continues.
pub fn write_version_stamp(car_home: &Path) -> std::io::Result<()> {
    stamp_version(car_home).map(|_| ())
}

/// Read the existing stamp, write the succeeding one, and return both.
///
/// Read-before-write is the whole point (car#881). The old `write_version_stamp`
/// overwrote unconditionally, so the daemon destroyed the record of what wrote
/// the state before anything could look at it — and `car doctor`, the only
/// reader, runs solely when a human asks. Callers that care about an upgrade
/// call this and inspect [`StampTransition`].
pub fn stamp_version(car_home: &Path) -> std::io::Result<StampTransition> {
    std::fs::create_dir_all(car_home)?;
    let previous = read_version_stamp(car_home);
    let stamp = VersionStamp::succeeding(previous.as_ref());
    let json = serde_json::to_string_pretty(&stamp)
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
    // Atomic-ish: write a per-process temp file in the same dir, then rename
    // over. The pid-scoped name keeps two concurrent boots (or boot + repair)
    // from interleaving writes to one shared temp and tearing version.json.
    let tmp = car_home.join(format!("version.json.{}.tmp", std::process::id()));
    std::fs::write(&tmp, json)?;
    std::fs::rename(&tmp, car_home.join("version.json"))?;
    Ok(StampTransition {
        previous,
        current: stamp,
    })
}

/// Subdirectory of the state root for doctor-facing status records. It is in
/// [`KNOWN_DIRS`], so nothing written here is reported as older-install debris.
const DOCTOR_DIR: &str = "doctor";

/// The daemon's startup TMPDIR probe record, under [`DOCTOR_DIR`].
const DAEMON_TMPDIR_MARKER_FILE: &str = "daemon-tmpdir.json";

/// Bytes the TMPDIR probe writes. Tiny on purpose: the probe proves the
/// directory accepts create and write (and, on Unix, identity-safe remove).
const TMPDIR_PROBE_BYTES: &[u8] = b"car tmpdir probe\n";

/// What a daemon found when it probed its inherited `TMPDIR` at startup
/// (Parslee-ai/car#1494).
///
/// Every agent invocation creates a fresh scratch directory under the daemon's
/// `TMPDIR`. A daemon launched from inside the macOS installer can inherit a
/// `PKInstallSandbox` path that disappears when the install ends, and it keeps
/// that dead path for its whole lifetime, so every invocation fails while
/// `car doctor`, which never contacts the daemon, could not see why. The daemon
/// now leaves this record at `<CAR_HOME>/doctor/daemon-tmpdir.json`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DaemonTmpdirMarker {
    /// Process id of the daemon that ran the probe.
    pub pid: u32,
    /// When that daemon ran the probe at startup, in Unix seconds.
    pub booted_at_unix: u64,
    /// CAR version of that daemon.
    pub car_version: String,
    /// The temp directory the daemon resolved (`std::env::temp_dir()`, which
    /// follows `TMPDIR` on Unix).
    pub checked_path: String,
    /// The create/write probe succeeded, including identity-safe remove on Unix.
    pub ok: bool,
    /// The failing step and its OS error, when `ok` is false.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

/// How doctor classifies a daemon TMPDIR record without contacting the daemon.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "status")]
pub enum DaemonTmpdirStatus {
    /// The daemon that wrote the record is still running, so this is the
    /// running daemon's result. A failed probe here makes the report unhealthy.
    Current { marker: DaemonTmpdirMarker },
    /// The daemon that wrote the record is no longer running: no daemon is up,
    /// or a later one has not recorded. Shown, never a health failure.
    Stale { marker: DaemonTmpdirMarker },
    /// This platform has no liveness check, so the record cannot be tied to a
    /// running daemon. Shown with its result, never a health failure.
    Unverified { marker: DaemonTmpdirMarker },
    /// A record exists but could not be read or parsed. Informational: the
    /// next daemon start replaces it.
    Unreadable { error: String },
}

/// The daemon TMPDIR record as `car doctor` reports it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DaemonTmpdirCheck {
    /// Where the record lives (`<CAR_HOME>/doctor/daemon-tmpdir.json`).
    pub marker_path: String,
    #[serde(flatten)]
    pub status: DaemonTmpdirStatus,
}

impl DaemonTmpdirCheck {
    /// Only the running daemon's own failed probe is a problem. Stale,
    /// unverified and unreadable records are informational.
    pub fn is_failing(&self) -> bool {
        matches!(&self.status, DaemonTmpdirStatus::Current { marker } if !marker.ok)
    }
}

/// Where the daemon TMPDIR record lives under a state root.
pub fn daemon_tmpdir_marker_path(car_home: &Path) -> PathBuf {
    car_home.join(DOCTOR_DIR).join(DAEMON_TMPDIR_MARKER_FILE)
}

/// Probe `tmpdir` and record the result under `<car_home>/doctor/`. The daemon
/// calls this once at startup with `std::env::temp_dir()`.
///
/// The probe exclusively creates one uniquely named file in `tmpdir` (an
/// existing entry, symlink or not, is never opened), writes a few bytes, and,
/// on Unix, removes that file only after checking the path still names the file
/// it created. Off Unix, stable `std` exposes no portable file identity, so the
/// tiny probe file is deliberately left behind rather than risking deletion of
/// a substituted entry. The record is written to a private temporary file
/// beside the previous one and atomically replaced with CAR's no-follow state
/// helpers, so a reader sees the old record or the new one, never a torn one.
///
/// A failed probe is still a successful record: `Ok` with `ok: false`. `Err`
/// means the record itself could not be written. Either way the caller carries
/// on, because this is a diagnostic and never a startup gate.
pub fn record_daemon_tmpdir_probe(
    car_home: &Path,
    tmpdir: &Path,
) -> std::io::Result<DaemonTmpdirMarker> {
    let error = probe_daemon_tmpdir(tmpdir).err();
    record_daemon_tmpdir_probe_result(car_home, tmpdir, error)
}

/// Run only the filesystem round trip for the daemon TMPDIR probe.
///
/// Startup runs this on a dedicated thread, then records the returned outcome
/// itself. Keeping marker publication on the startup side prevents an abandoned
/// timed-out worker from later replacing the timeout record if its filesystem
/// operation eventually returns.
pub fn probe_daemon_tmpdir(tmpdir: &Path) -> Result<(), String> {
    probe_tmpdir(tmpdir, std::process::id())
}

/// Record an already-completed (or timed-out) daemon TMPDIR probe.
///
/// `error` is `None` for success and names the failed step otherwise. This is
/// separate from [`probe_daemon_tmpdir`] so startup can impose a deadline on
/// TMPDIR I/O and still persist a timeout result from the non-blocked side.
pub fn record_daemon_tmpdir_probe_result(
    car_home: &Path,
    tmpdir: &Path,
    error: Option<String>,
) -> std::io::Result<DaemonTmpdirMarker> {
    let marker = DaemonTmpdirMarker {
        pid: std::process::id(),
        booted_at_unix: std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0),
        car_version: env!("CARGO_PKG_VERSION").to_string(),
        checked_path: tmpdir.display().to_string(),
        ok: error.is_none(),
        error,
    };
    write_daemon_tmpdir_marker(car_home, &marker)?;
    Ok(marker)
}

/// Read the daemon TMPDIR record: `None` when there is none, `Some(Err)` when
/// one exists but cannot be read or parsed.
pub fn read_daemon_tmpdir_marker(car_home: &Path) -> Option<Result<DaemonTmpdirMarker, String>> {
    let text = match std::fs::read_to_string(daemon_tmpdir_marker_path(car_home)) {
        Ok(text) => text,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return None,
        Err(e) => return Some(Err(e.to_string())),
    };
    Some(serde_json::from_str(&text).map_err(|e| e.to_string()))
}

/// A name suffix no earlier probe or record write used: the pid plus the
/// current time in nanoseconds.
fn unique_probe_suffix(pid: u32) -> String {
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    format!("{pid}.{nanos}")
}

/// One create/write/remove round trip in `tmpdir`, the operations an agent
/// scratch workspace needs. Returns the failing step and its error.
fn probe_tmpdir(tmpdir: &Path, pid: u32) -> Result<(), String> {
    use std::io::Write;

    let path = tmpdir.join(format!(".car-tmpdir-probe.{}", unique_probe_suffix(pid)));
    // Follow directory symlinks by design: macOS normally reports TMPDIR below
    // /var/folders, while /var itself is a symlink to /private/var. The probe
    // must exercise the directory the daemon will actually use. Only the new
    // probe entry itself is protected against symlink substitution.
    let mut file = std::fs::OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(&path)
        .map_err(|e| format!("create failed: {e}"))?;
    let created = file.metadata().map_err(|e| format!("stat failed: {e}"));
    let wrote = file
        .write_all(TMPDIR_PROBE_BYTES)
        .map_err(|e| format!("write failed: {e}"));
    drop(file);

    // A failed handle stat must not short-circuit cleanup handling. Without the
    // created identity no deletion is safe, so report explicitly that the file
    // was left rather than silently leaking it.
    let removed = cleanup_probe_file(&path, &created);
    combine_probe_results(created.map(|_| ()).and(wrote), removed)
}

fn cleanup_probe_file(
    path: &Path,
    created: &Result<std::fs::Metadata, String>,
) -> Result<(), String> {
    match created {
        Ok(created) => remove_probe_file(path, created),
        Err(_) => Err(format!(
            "cleanup skipped: probe file identity could not be proven; left {}",
            path.display()
        )),
    }
}

fn combine_probe_results(
    operation: Result<(), String>,
    cleanup: Result<(), String>,
) -> Result<(), String> {
    match (operation, cleanup) {
        (Ok(()), Ok(())) => Ok(()),
        (Err(error), Ok(())) | (Ok(()), Err(error)) => Err(error),
        (Err(operation), Err(cleanup)) => Err(format!("{operation}; {cleanup}")),
    }
}

/// Remove the probe file, but only while `path` still names the regular file
/// the probe created. Anything else at that path is left alone.
#[cfg(unix)]
fn remove_probe_file(path: &Path, created: &std::fs::Metadata) -> Result<(), String> {
    use std::os::unix::fs::MetadataExt;

    // This is intentionally the last check before unlink: compare the open
    // handle's (dev, ino) with no-follow path metadata, and reject symlinks.
    let on_disk = std::fs::symlink_metadata(path).map_err(|e| format!("remove failed: {e}"))?;
    if !on_disk.file_type().is_file()
        || created.dev() != on_disk.dev()
        || created.ino() != on_disk.ino()
    {
        return Err(
            "remove skipped: the probe path no longer names the file the probe created".to_string(),
        );
    }
    std::fs::remove_file(path).map_err(|e| format!("remove failed: {e}"))
}

#[cfg(not(unix))]
fn remove_probe_file(_path: &Path, _created: &std::fs::Metadata) -> Result<(), String> {
    // Stable std has no portable identity comparison off Unix. A successful
    // create/write is enough to validate TMPDIR; leave the tiny uniquely named
    // file rather than unlinking a path an attacker could have substituted.
    Ok(())
}

/// Write `marker` to a new private temporary file beside the record and use
/// CAR's no-follow atomic state-file replacement to publish it.
fn write_daemon_tmpdir_marker(car_home: &Path, marker: &DaemonTmpdirMarker) -> std::io::Result<()> {
    use std::io::Write;

    let dir = car_home.join(DOCTOR_DIR);
    // Unlike TMPDIR, CAR state directories must never be followed through a
    // symlink. This helper securely walks and validates the path on Unix and
    // Windows rather than relying on a check followed by a path-based open.
    car_secrets::ensure_private_dir(&dir)?;
    let mut json = serde_json::to_vec_pretty(marker)
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
    json.push(b'\n');
    let tmp = dir.join(format!(
        "{DAEMON_TMPDIR_MARKER_FILE}.{}.tmp",
        unique_probe_suffix(marker.pid)
    ));
    // The state helper uses create-new plus O_NOFOLLOW/reparse-point checks and
    // validates the opened file. On a later error the private temp is left in
    // place: path-based cleanup would reintroduce the substitution race these
    // helpers close.
    let mut file = car_secrets::create_private_file(&tmp)?;
    file.write_all(&json)?;
    car_secrets::atomic_replace_private_file(&tmp, &dir.join(DAEMON_TMPDIR_MARKER_FILE))
}

/// Classify a record. `writer_alive` is `Some` where this platform can check
/// the writer's pid, `None` where it cannot.
fn classify_daemon_tmpdir_marker(
    marker: DaemonTmpdirMarker,
    writer_alive: Option<bool>,
) -> DaemonTmpdirStatus {
    match writer_alive {
        Some(true) => DaemonTmpdirStatus::Current { marker },
        Some(false) => DaemonTmpdirStatus::Stale { marker },
        None => DaemonTmpdirStatus::Unverified { marker },
    }
}

/// Whether the daemon that wrote a record is still running, where that can be
/// checked without contacting it.
///
/// Staleness rests on the pid alone, never on the recorded time. A daemon
/// records only after it holds the primary-daemon lock for its `CAR_HOME`, so a
/// later boot replaces the record, and a record whose writer is gone means no
/// daemon is running or the running one has not recorded.
fn daemon_writer_alive(pid: u32) -> Option<bool> {
    #[cfg(unix)]
    {
        Some(unix_pid_alive(pid))
    }
    #[cfg(not(unix))]
    {
        let _ = pid;
        None
    }
}

/// `kill(pid, 0)`, the same rule as `wait_for_parent_exit` in
/// `car-server/src/main.rs`: signal 0 sends nothing and only checks existence;
/// 0 or `EPERM` (alive, but not ours to signal) means alive, anything else
/// means gone.
///
/// Not proof against pid reuse, accepted exactly as that code accepts it: if
/// the writer exited and the OS recycled its pid onto an unrelated process,
/// this reads "alive" and a dead daemon's result is reported as current. Pids
/// are allocated sequentially, so that needs the counter to wrap onto the old
/// value, and re-running `car doctor` after relaunching CarHost clears it.
#[cfg(unix)]
fn unix_pid_alive(pid: u32) -> bool {
    // kill(2) reads 0 and negative pids as process groups, not a process.
    let Ok(pid) = libc::pid_t::try_from(pid) else {
        return false;
    };
    if pid <= 0 {
        return false;
    }
    // SAFETY: signal 0 delivers nothing; kill only checks that `pid` exists.
    let rc = unsafe { libc::kill(pid, 0) };
    rc == 0 || std::io::Error::last_os_error().raw_os_error() == Some(libc::EPERM)
}

/// The daemon TMPDIR record as doctor reports it; `None` when there is none.
fn check_daemon_tmpdir(home: &Path) -> Option<DaemonTmpdirCheck> {
    let status = match read_daemon_tmpdir_marker(home)? {
        Ok(marker) => {
            let writer_alive = daemon_writer_alive(marker.pid);
            classify_daemon_tmpdir_marker(marker, writer_alive)
        }
        Err(error) => DaemonTmpdirStatus::Unreadable { error },
    };
    Some(DaemonTmpdirCheck {
        marker_path: daemon_tmpdir_marker_path(home).display().to_string(),
        status,
    })
}

/// Options controlling a diagnosis run.
#[derive(Debug, Clone, Default)]
pub struct DoctorOptions {
    /// Deep-verify model weights (recompute sha256 vs etag) instead of the cheap
    /// resolves-and-non-empty check. Slow (hashes every weight) but catches
    /// truncated-but-non-empty corruption.
    pub deep: bool,
    /// Apply safe repairs: purge corrupt cache files, back up unparseable state,
    /// refresh the version stamp.
    pub repair: bool,
}

/// Verdict for a single `~/.car` JSON state file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "status")]
pub enum StateFileStatus {
    /// Not present — fine; most state files are created on first use.
    Absent,
    /// Present and parses as JSON.
    Ok { schema_version: Option<u32> },
    /// Present but does not parse — corrupt or written by an incompatible
    /// version. `backed_up_to` is set when `--repair` moved it aside.
    Unparseable {
        error: String,
        backed_up_to: Option<String>,
    },
}

/// One state-file check.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StateFileCheck {
    pub name: String,
    #[serde(flatten)]
    pub status: StateFileStatus,
}

/// Verdict for one installed model directory.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "status")]
pub enum ModelStatus {
    /// Weight files present and (for `--deep`) hash-verified.
    Healthy,
    /// At least one weight file is corrupt/missing. `purged` is how many were
    /// removed in `--repair` mode (so the next pull re-downloads them).
    Corrupt {
        bad_files: Vec<String>,
        purged: usize,
    },
    /// The directory looks like a model install — it has `config.json` /
    /// tokenizer stubs — but carries no resolvable weights at all. This is what
    /// an interrupted `car models pull` leaves behind, and it used to be
    /// invisible: `check_one_model` returned `None` for any dir with no weight
    /// files, so the report dropped it and `car doctor` said "none installed /
    /// Healthy" over a broken install (Parslee-ai/car#616).
    ///
    /// Note the loader already knew: `registry::ensure_local` gates reuse on
    /// `mlx_dir_has_weights` and re-downloads a config-only stub
    /// (car-releases#391). The diagnostic just disagreed with the runtime.
    Incomplete { detail: String },
}

/// A file left behind by an interrupted download.
///
/// Reported, never deleted — see [`find_leftovers`] for why.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Leftover {
    pub path: String,
    pub bytes: u64,
}

/// One model check.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelCheck {
    pub name: String,
    #[serde(flatten)]
    pub status: ModelStatus,
}

/// Health of one CAR-managed Python runtime venv (`speech-runtime`,
/// `visual-runtime`).
///
/// These venvs are how CAR runs every model architecture its in-process Rust
/// MLX backend does not implement, so a broken one silently removes the entire
/// external-runtime shelf — vision, speech, and every newer LLM family — while
/// the directory still looks fully populated on disk. A venv's `bin/python` is
/// an absolute symlink into the interpreter that built it, so an ordinary
/// Homebrew upgrade (`python@3.13` rotated away) is enough to do it.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RuntimeCheck {
    /// Directory name under `CAR_HOME` (e.g. `visual-runtime`).
    pub name: String,
    pub root: String,
    /// The venv directory exists. A runtime that was never provisioned is not
    /// unhealthy — it is simply absent, and provisions on first use.
    pub present: bool,
    /// The venv's interpreter actually runs. Only meaningful when `present`.
    pub interpreter_ok: bool,
}

impl RuntimeCheck {
    /// A runtime is broken when it exists but cannot run anything. Absent is
    /// fine (lazy-provisioned); present-and-working is fine.
    pub fn is_broken(&self) -> bool {
        self.present && !self.interpreter_ok
    }
}

/// The full diagnosis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DoctorReport {
    pub car_home: String,
    /// The version of the binary that produced this report.
    pub binary_version: String,
    /// The version stamp found on disk, if any (None ⇒ never stamped).
    pub on_disk_stamp: Option<VersionStamp>,
    /// True when the on-disk stamp's version differs from the binary.
    ///
    /// Near-useless on a machine that runs the daemon: it stamps at boot, so
    /// this reads false from then on. [`DoctorReport::carried_from_version`] is
    /// the field that survives (car#881).
    pub version_skew: bool,
    /// The version that wrote the state this install carried across its most
    /// recent upgrade, when the stamp recorded one.
    ///
    /// Unlike `version_skew` this outlives the daemon's boot stamp, so "state
    /// here predates the running binary" stays answerable rather than being
    /// erased seconds after it became true.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub carried_from_version: Option<String>,
    /// On-disk state uses a schema generation NEWER than this binary knows —
    /// a downgrade. `STATE_SCHEMA_VERSION` documents that a reader older than
    /// the state "should refuse rather than corrupt"; nothing enforced it.
    #[serde(default)]
    pub schema_from_the_future: bool,
    pub state_files: Vec<StateFileCheck>,
    pub models: Vec<ModelCheck>,
    /// Models whose CAR-managed weights are physically ready, using the same
    /// registry predicate as `models.list_unified`.
    #[serde(default)]
    pub installed_models: usize,
    /// Partial downloads abandoned in the HuggingFace cache. Informational —
    /// they waste disk but nothing is broken, so they don't affect
    /// [`DoctorReport::is_healthy`].
    #[serde(default)]
    pub leftovers: Vec<Leftover>,
    /// Health of the CAR-managed Python runtime venvs. Absent runtimes are
    /// omitted; only ones that exist are reported.
    #[serde(default)]
    pub runtimes: Vec<RuntimeCheck>,
    /// Top-level `~/.car` entries this version doesn't recognize.
    pub unrecognized: Vec<String>,
    /// Human-readable actions taken in `--repair` mode (empty otherwise).
    pub repairs: Vec<String>,
    /// The daemon's startup TMPDIR probe (Parslee-ai/car#1494), read from
    /// `<CAR_HOME>/doctor/daemon-tmpdir.json`. `None` when no daemon has
    /// recorded one, which is not an error; the key is then omitted, so a report
    /// without a record serializes exactly as before.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub daemon_tmpdir: Option<DaemonTmpdirCheck>,
}

impl DoctorReport {
    /// True when nothing actionable was found (modulo unrecognized entries,
    /// which are informational).
    pub fn is_healthy(&self) -> bool {
        // `carried_from_version` is deliberately NOT a health signal — carrying
        // state across an upgrade is the normal case, and flagging it would make
        // every upgraded install permanently "unhealthy". Running against state
        // from a schema this binary does not know IS a problem.
        !self.schema_from_the_future
            && !self.version_skew
            && self
                .state_files
                .iter()
                .all(|f| !matches!(f.status, StateFileStatus::Unparseable { .. }))
            && self
                .models
                .iter()
                .all(|m| matches!(m.status, ModelStatus::Healthy))
            && self.runtimes.iter().all(|r| !r.is_broken())
            // Only the running daemon's own failed TMPDIR probe counts. A stale,
            // unverified or unreadable record is informational.
            && !self
                .daemon_tmpdir
                .as_ref()
                .is_some_and(DaemonTmpdirCheck::is_failing)
    }
}

/// Run a diagnosis (and, if `opts.repair`, repairs) against the install that is
/// actually running: state under [`car_home`](fn@car_home), weights under the shared cache.
///
/// The two are the same tree by default and separate under `CAR_HOME`, which is
/// why they are passed separately. A relocated daemon still loads its weights
/// from `~/.car/models` — that cache is machine-global on purpose — so a doctor
/// that only looked under the state root would silently stop checking the
/// weights, which is the failure mode `car doctor` mainly exists to catch.
pub fn diagnose(opts: &DoctorOptions) -> DoctorReport {
    diagnose_at(&car_home(), &crate::default_models_dir(), opts)
}

/// Diagnosis against an explicit base dir, weights assumed at `<home>/models` —
/// the testable core, and the shape every caller wanted before `CAR_HOME` could
/// separate the two.
pub fn diagnose_in(home: &Path, opts: &DoctorOptions) -> DoctorReport {
    diagnose_at(home, &home.join("models"), opts)
}

/// Diagnosis with the state root and the weights cache named independently.
pub fn diagnose_at(home: &Path, models_dir: &Path, opts: &DoctorOptions) -> DoctorReport {
    let catalog_public_key = std::env::var("CAR_CATALOG_PUBKEY").ok();
    let registry = crate::registry::UnifiedRegistry::new_with_session(
        home.to_path_buf(),
        models_dir.to_path_buf(),
        catalog_public_key.as_deref(),
        crate::registry::SessionProbe::Inert,
    );
    diagnose_at_with_registry(home, models_dir, opts, &registry, None)
}

/// Deterministic diagnosis seam for cross-crate tests.
///
/// This stays `#[doc(hidden)]` instead of feature-gated because dependency
/// crates' integration tests link `car-inference` without inheriting `cfg(test)`.
/// Unlike [`diagnose_at`], this loads only local models discovered below the
/// explicit weights directory, scans only the explicit Hugging Face hub root,
/// and never consults a credential/session probe. Production feedback and
/// doctor paths deliberately continue to use [`diagnose_at`].
#[doc(hidden)]
pub fn diagnose_at_isolated(
    home: &Path,
    models_dir: &Path,
    huggingface_hub_root: &Path,
    opts: &DoctorOptions,
) -> DoctorReport {
    let registry = crate::registry::UnifiedRegistry::new_isolated_for_diagnosis(
        home.to_path_buf(),
        models_dir.to_path_buf(),
    );
    diagnose_at_with_registry(
        home,
        models_dir,
        opts,
        &registry,
        Some(huggingface_hub_root),
    )
}

fn diagnose_at_with_registry(
    home: &Path,
    models_dir: &Path,
    opts: &DoctorOptions,
    registry: &crate::registry::UnifiedRegistry,
    huggingface_hub_root: Option<&Path>,
) -> DoctorReport {
    let mut repairs = Vec::new();

    // --- version stamp / skew ------------------------------------------------
    let on_disk_stamp = read_version_stamp(home);
    let binary = VersionStamp::current();
    let version_skew = on_disk_stamp
        .as_ref()
        .map(|s| {
            s.car_version != binary.car_version
                || s.state_schema_version != binary.state_schema_version
        })
        .unwrap_or(false);
    // Survives the daemon's boot stamp; `version_skew` does not.
    let carried_from_version = on_disk_stamp
        .as_ref()
        .and_then(|s| s.previous_car_version.clone());
    let schema_from_the_future = on_disk_stamp
        .as_ref()
        .is_some_and(|s| s.state_schema_version > binary.state_schema_version);

    // --- state files ---------------------------------------------------------
    let mut state_files = Vec::new();
    for name in KNOWN_STATE_FILES {
        state_files.push(check_state_file(home, name, opts, &mut repairs));
    }

    // --- models --------------------------------------------------------------
    let models = check_models(models_dir, opts, &mut repairs);
    // Kept separate from `models`: those entries are per-directory integrity
    // checks, while this is the registry's physical installed-model count.
    let installed_models = registry
        .list()
        .into_iter()
        .filter(|schema| {
            schema.downloads_weights()
                && crate::registry::physical_weights_ready_with_huggingface_hub(
                    schema,
                    models_dir,
                    huggingface_hub_root,
                )
        })
        .count();

    // --- leftovers -----------------------------------------------------------
    let leftovers = match huggingface_hub_root {
        Some(hub) => find_leftovers_in(hub),
        None => find_leftovers(),
    };
    let unrecognized = find_unrecognized(home);

    // --- refresh stamp on repair --------------------------------------------
    if opts.repair {
        // Only *report* a stamp refresh when the stamp actually moved. It was
        // rewritten and announced unconditionally, so `car doctor --repair` on
        // a perfectly healthy install always printed a line under "Repairs:",
        // implying something had been wrong (Parslee-ai/car#626). The write
        // still happens either way — it's cheap and makes a missing stamp
        // appear — but a no-op write is not a repair.
        let already_current = on_disk_stamp
            .as_ref()
            .map(|s| {
                s.car_version == binary.car_version
                    && s.state_schema_version == binary.state_schema_version
            })
            .unwrap_or(false);
        match write_version_stamp(home) {
            Ok(()) if !already_current => repairs.push(format!(
                "refreshed version stamp to {} (schema v{})",
                binary.car_version, binary.state_schema_version
            )),
            Ok(()) => {}
            Err(e) => repairs.push(format!("failed to refresh version stamp: {e}")),
        }
    }

    // --- reap empty journals on repair ---------------------------------------
    let empty_journals = find_empty_journals(home);
    if opts.repair && !empty_journals.is_empty() {
        let mut removed = 0usize;
        for p in &empty_journals {
            if std::fs::remove_file(p).is_ok() {
                removed += 1;
            }
        }
        if removed > 0 {
            repairs.push(format!(
                "removed {removed} empty event journal(s) from journals/"
            ));
        }
    }

    // --- managed Python runtimes --------------------------------------------
    let runtimes = check_runtimes(home);

    // --- daemon TMPDIR probe record (car#1494) --------------------------------
    let daemon_tmpdir = check_daemon_tmpdir(home);

    DoctorReport {
        car_home: home.display().to_string(),
        binary_version: binary.car_version,
        on_disk_stamp,
        version_skew,
        carried_from_version,
        schema_from_the_future,
        state_files,
        models,
        installed_models,
        leftovers,
        runtimes,
        unrecognized,
        repairs,
        daemon_tmpdir,
    }
}

/// Directory names under `CAR_HOME` that hold a CAR-managed `uv` venv.
const MANAGED_RUNTIMES: &[&str] = &["speech-runtime", "visual-runtime"];

/// Check each managed Python runtime that has actually been provisioned.
///
/// Absent runtimes are skipped rather than reported unhealthy: they provision
/// on first use, so "not there yet" is the normal state on a fresh install and
/// flagging it would make every new machine read as broken.
fn check_runtimes(home: &Path) -> Vec<RuntimeCheck> {
    MANAGED_RUNTIMES
        .iter()
        .filter_map(|name| {
            let root = home.join(name);
            if !root.exists() {
                return None;
            }
            Some(RuntimeCheck {
                name: (*name).to_string(),
                root: root.display().to_string(),
                present: true,
                interpreter_ok: crate::managed_venv::interpreter_healthy(&root),
            })
        })
        .collect()
}

fn read_version_stamp(home: &Path) -> Option<VersionStamp> {
    let text = std::fs::read_to_string(home.join("version.json")).ok()?;
    serde_json::from_str(&text).ok()
}

fn check_state_file(
    home: &Path,
    name: &str,
    opts: &DoctorOptions,
    repairs: &mut Vec<String>,
) -> StateFileCheck {
    let path = home.join(name);
    let is_jsonl = name.ends_with(".jsonl");
    let status = match std::fs::read_to_string(&path) {
        Err(_) => StateFileStatus::Absent,
        Ok(text) if text.trim().is_empty() => StateFileStatus::Ok {
            schema_version: None,
        },
        // JSONL (one JSON value per line) must be validated line-by-line — the
        // whole file is not a single JSON document.
        Ok(text) if is_jsonl => match jsonl_first_bad_line(&text) {
            None => StateFileStatus::Ok {
                schema_version: None,
            },
            Some(e) => unparseable(&path, name, e, opts, repairs),
        },
        Ok(text) => match serde_json::from_str::<serde_json::Value>(&text) {
            Ok(value) => StateFileStatus::Ok {
                schema_version: value
                    .get("schema_version")
                    .and_then(serde_json::Value::as_u64)
                    .map(|v| v as u32),
            },
            Err(e) => unparseable(&path, name, e.to_string(), opts, repairs),
        },
    };
    StateFileCheck {
        name: name.to_string(),
        status,
    }
}

/// Validate each non-empty line of a JSONL file; return the first parse error
/// (with its line number) or `None` if all lines are valid JSON.
fn jsonl_first_bad_line(text: &str) -> Option<String> {
    for (i, line) in text.lines().enumerate() {
        if line.trim().is_empty() {
            continue;
        }
        if let Err(e) = serde_json::from_str::<serde_json::Value>(line) {
            return Some(format!("line {}: {e}", i + 1));
        }
    }
    None
}

/// Shared handling for an unparseable state file: in repair mode, move it aside
/// to `<name>.corrupt.bak` (never delete) so the owning crate writes a fresh
/// default on next run; otherwise just record the error.
fn unparseable(
    path: &Path,
    name: &str,
    error: String,
    opts: &DoctorOptions,
    repairs: &mut Vec<String>,
) -> StateFileStatus {
    let backed_up_to = if opts.repair {
        // Don't clobber a previous backup — keeps the "never delete" promise
        // honest if the same file goes corrupt twice. First backup gets the
        // plain name; a collision falls back to an epoch-suffixed one.
        let plain = path.with_file_name(format!("{name}.corrupt.bak"));
        let bak = if plain.exists() {
            let epoch = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_secs())
                .unwrap_or(0);
            path.with_file_name(format!("{name}.corrupt.{epoch}.bak"))
        } else {
            plain
        };
        match std::fs::rename(path, &bak) {
            Ok(()) => {
                repairs.push(format!("backed up unparseable {name} → {}", bak.display()));
                Some(bak.display().to_string())
            }
            Err(err) => {
                repairs.push(format!("failed to back up {name}: {err}"));
                None
            }
        }
    } else {
        None
    };
    StateFileStatus::Unparseable {
        error,
        backed_up_to,
    }
}

fn check_models(
    models_dir: &Path,
    opts: &DoctorOptions,
    repairs: &mut Vec<String>,
) -> Vec<ModelCheck> {
    let Ok(entries) = std::fs::read_dir(models_dir) else {
        return Vec::new();
    };
    let mut out = Vec::new();
    for entry in entries.filter_map(Result::ok) {
        let dir = entry.path();
        if !dir.is_dir() {
            continue;
        }
        let name = entry.file_name().to_string_lossy().to_string();
        // Skip dirs with no weight files of their own: a managed MLX dir is
        // often just a config stub whose weights live in the HF snapshot cache,
        // and flagging that as broken would be a false positive. We only assess
        // weights that are actually present here.
        if let Some(status) = check_one_model(&dir, opts, &name, repairs) {
            out.push(ModelCheck { name, status });
        }
    }
    out.sort_by(|a, b| a.name.cmp(&b.name));
    out
}

fn check_one_model(
    dir: &Path,
    opts: &DoctorOptions,
    name: &str,
    repairs: &mut Vec<String>,
) -> Option<ModelStatus> {
    let weights = weight_files(dir);
    if weights.is_empty() {
        // No weight file of any kind — not even a dangling symlink (those DO
        // show up in `weight_files` and are caught as Corrupt below). Two very
        // different situations share this shape:
        //
        //   1. the dir isn't a model install at all — none of our business, and
        //      flagging it would be the false positive the old blanket `None`
        //      was protecting against;
        //   2. an install that got interrupted before its weights landed:
        //      `config.json` and the tokenizer stubs are there, the
        //      `*.safetensors` never arrived.
        //
        // Case 2 is exactly what a Ctrl-C'd `car models pull` leaves, and
        // returning `None` for it is what made a broken install read as
        // "Healthy" (Parslee-ai/car#616). Tell them apart on whether the dir
        // carries a model manifest.
        if is_interrupted_install(dir) {
            return Some(ModelStatus::Incomplete {
                detail: format!(
                    "manifest linked into the HuggingFace cache but no weights resolve — \
                     re-pull with `car models pull {name}`"
                ),
            });
        }
        return None;
    }
    let mut bad_files = Vec::new();
    for w in &weights {
        let corrupt = if opts.deep {
            verify_cache_file(w) == CacheIntegrity::Corrupt
        } else {
            !cache_file_usable(w)
        };
        if corrupt {
            bad_files.push(
                w.file_name()
                    .unwrap_or_default()
                    .to_string_lossy()
                    .to_string(),
            );
        }
    }
    if bad_files.is_empty() {
        return Some(ModelStatus::Healthy);
    }
    let purged = if opts.repair {
        let n = purge_corrupt_cache_files(dir);
        if n > 0 {
            repairs.push(format!(
                "purged {n} corrupt file(s) from model '{name}' — re-pull with `car models pull {name}`"
            ));
        }
        n
    } else {
        0
    };
    Some(ModelStatus::Corrupt { bad_files, purged })
}

/// Weight files (`.safetensors` / `.gguf`) anywhere under a model dir. Recurses
/// to full depth so detection matches `purge_corrupt_cache_files`' recursion —
/// a corrupt weight nested ≥2 levels down (uncommon but possible) is still seen.
/// Cheap: no hashing here, just extension matching.
/// Is this a managed dir left half-built by an interrupted pull?
///
/// Called only for dirs with no weight file of any kind. Distinguishing an
/// interrupted install from a directory that was never a model needs care,
/// because over-eager flagging here is a known past false positive — see
/// `config_only_stub_is_skipped_not_flagged`, which pins a hand-made
/// config-only dir as *not* broken.
///
/// The discriminator is **how the manifest got there**. `car models pull`
/// populates a managed dir by symlinking into the HuggingFace snapshot cache
/// (`registry.rs`, "try symlink first"), writing the small config/tokenizer
/// files before the multi-gigabyte weights. So a dir that holds symlinked
/// manifest files but no resolvable weights is one CAR built and did not
/// finish — the exact residue of a Ctrl-C'd pull. A hand-made stub, or one
/// created by the copy fallback, has real files and no symlinks, and is left
/// alone.
///
/// Deliberately conservative: it under-reports (a stub whose links were later
/// cleaned up reads as "not a model") rather than resurrecting the false
/// positive. Weight *presence* uses the same `mlx_dir_has_weights` predicate
/// the loader gates on, so the diagnosis and the runtime agree — the whole
/// point of Parslee-ai/car#616, where `ensure_local` re-downloaded a stub the
/// doctor was calling healthy.
fn is_interrupted_install(dir: &Path) -> bool {
    const MANIFESTS: &[&str] = &[
        "config.json",
        "model_index.json",
        "tokenizer.json",
        "tokenizer_config.json",
        "model.safetensors.index.json",
    ];
    let has_symlinked_manifest = MANIFESTS.iter().any(|m| {
        let p = dir.join(m);
        std::fs::symlink_metadata(&p)
            .map(|meta| meta.file_type().is_symlink())
            .unwrap_or(false)
    });
    has_symlinked_manifest && !crate::registry::mlx_dir_has_weights(dir)
}

/// Zero-byte `*.jsonl` files under `~/.car/journals/`.
///
/// The daemon opens a journal per session; one that never executes a proposal
/// leaves an empty file behind and nothing reaps it, so they accumulate
/// indefinitely — 35 of 43 on the install that prompted this
/// (Parslee-ai/car#626).
///
/// Unlike the HuggingFace partials, these ARE safe for `--repair` to delete:
/// they live in CAR's own directory, a zero-length journal provably holds no
/// events, and `EventLog::load` on a missing file behaves the same as on an
/// empty one. Only exactly-zero-length files qualify — anything with a byte in
/// it is left alone.
fn find_empty_journals(home: &Path) -> Vec<PathBuf> {
    let dir = home.join("journals");
    let Ok(entries) = std::fs::read_dir(&dir) else {
        return Vec::new();
    };
    let mut out: Vec<PathBuf> = entries
        .filter_map(Result::ok)
        .filter(|e| {
            e.path().extension().and_then(|x| x.to_str()) == Some("jsonl")
                && e.metadata()
                    .map(|m| m.is_file() && m.len() == 0)
                    .unwrap_or(false)
        })
        .map(|e| e.path())
        .collect();
    out.sort();
    out
}

/// Partial downloads abandoned in the HuggingFace cache (`*.sync.part`).
///
/// Reported, **never deleted**, for two reasons. The shared HF cache belongs to
/// every tool on the machine, not just CAR (managed model dirs are only
/// symlinks into it), and a `.sync.part` may belong to a download that is
/// running *right now* — removing it would corrupt a live transfer. That also
/// keeps faith with `--repair`'s documented promise to never delete "anything
/// not provably corrupt": an in-flight partial is not corrupt, it is unfinished.
/// Surfacing the path and the size is the part that was missing
/// (Parslee-ai/car#616) — the operator decides.
///
/// Scans only `<cache>/hub/*/blobs/`, where hf-hub puts them, so this stays
/// cheap on a large cache rather than walking the whole tree.
fn find_leftovers() -> Vec<Leftover> {
    find_leftovers_in(&crate::registry::huggingface_cache_root())
}

fn find_leftovers_in(hub: &Path) -> Vec<Leftover> {
    let mut out = Vec::new();
    let Ok(repos) = std::fs::read_dir(hub) else {
        return out;
    };
    for repo in repos.filter_map(Result::ok) {
        let blobs = repo.path().join("blobs");
        let Ok(entries) = std::fs::read_dir(&blobs) else {
            continue;
        };
        for e in entries.filter_map(Result::ok) {
            let p = e.path();
            let is_partial = p
                .file_name()
                .and_then(|n| n.to_str())
                .map(|n| n.ends_with(".sync.part") || n.ends_with(".incomplete"))
                .unwrap_or(false);
            if !is_partial {
                continue;
            }
            // Apparent size can far exceed blocks actually allocated (these are
            // written sparsely); `len()` is what the operator sees in `ls -lh`.
            let bytes = e.metadata().map(|m| m.len()).unwrap_or(0);
            out.push(Leftover {
                path: p.display().to_string(),
                bytes,
            });
        }
    }
    out.sort_by(|a, b| b.bytes.cmp(&a.bytes).then_with(|| a.path.cmp(&b.path)));
    out
}

fn weight_files(dir: &Path) -> Vec<PathBuf> {
    fn is_weight(p: &Path) -> bool {
        matches!(
            p.extension().and_then(|e| e.to_str()),
            Some("safetensors") | Some("gguf")
        )
    }
    let mut out = Vec::new();
    let Ok(entries) = std::fs::read_dir(dir) else {
        return out;
    };
    for entry in entries.filter_map(Result::ok) {
        let p = entry.path();
        // `file_type` doesn't follow symlinks, so weight *symlinks* (the normal
        // case) are seen as files, not recursed into — only real subdirs recurse.
        if entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
            out.extend(weight_files(&p));
        } else if is_weight(&p) {
            out.push(p);
        }
    }
    out
}

fn find_unrecognized(home: &Path) -> Vec<String> {
    let Ok(entries) = std::fs::read_dir(home) else {
        return Vec::new();
    };
    let mut out: Vec<String> = entries
        .filter_map(Result::ok)
        .filter_map(|e| {
            let name = e.file_name().to_string_lossy().to_string();
            let is_dir = e.file_type().map(|t| t.is_dir()).unwrap_or(false);
            let known = if is_dir {
                KNOWN_DIRS.contains(&name.as_str())
            } else {
                KNOWN_STATE_FILES.contains(&name.as_str())
                    || KNOWN_NON_JSON_FILES.contains(&name.as_str())
                    // Volatile runtime artifacts (locks, temps, backups, binary
                    // caches, append-only logs) are not "leftovers".
                    || TOLERATED_SUFFIXES.iter().any(|s| name.ends_with(s))
                    // Hidden dotfiles are config/runtime, not leftovers.
                    || name.starts_with('.')
            };
            if known {
                None
            } else {
                Some(name)
            }
        })
        .collect();
    out.sort();
    out
}

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

    fn opts(deep: bool, repair: bool) -> DoctorOptions {
        DoctorOptions { deep, repair }
    }

    fn diagnose_repair_with_isolated_model_roots(home: &Path) -> DoctorReport {
        let models_dir = TempDir::new().unwrap();
        let huggingface_hub = TempDir::new().unwrap();
        let blobs = huggingface_hub.path().join("models--fixture/blobs");
        std::fs::create_dir_all(&blobs).unwrap();
        std::fs::write(blobs.join("isolated.sync.part"), b"partial").unwrap();

        let report = diagnose_at_isolated(
            home,
            models_dir.path(),
            huggingface_hub.path(),
            &opts(false, true),
        );
        assert_eq!(
            report.leftovers.len(),
            1,
            "the isolated seam must scan its injected Hugging Face root, not skip leftovers"
        );
        assert!(
            Path::new(&report.leftovers[0].path).starts_with(huggingface_hub.path()),
            "the leftover must come from the test-owned Hugging Face root"
        );
        report
    }

    #[test]
    fn clean_home_is_healthy() {
        let tmp = TempDir::new().unwrap();
        std::fs::write(tmp.path().join("models.json"), "{}").unwrap();
        std::fs::create_dir_all(tmp.path().join("models")).unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, false));
        assert!(r.is_healthy(), "clean home should be healthy: {r:?}");
        assert!(r.unrecognized.is_empty());
    }

    #[test]
    fn secret_index_is_recognized_not_a_leftover() {
        // The names-only secret index is a live current-version file (written by
        // the OS-keychain store on every platform). doctor once flagged it as a
        // possible older-install leftover and told the user to remove it — only
        // visible once a secret had been stored, e.g. after `car auth login` on
        // Windows. It must be recognized state, and it must parse as JSON.
        let tmp = TempDir::new().unwrap();
        std::fs::write(tmp.path().join("models.json"), "{}").unwrap();
        std::fs::create_dir_all(tmp.path().join("models")).unwrap();
        std::fs::write(tmp.path().join("secret_index.json"), r#"{"entries":[]}"#).unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, false));
        assert!(
            !r.unrecognized.contains(&"secret_index.json".to_string()),
            "secret_index.json must not be flagged as unrecognized: {:?}",
            r.unrecognized
        );
        assert!(
            r.is_healthy(),
            "home with a secret index should be healthy: {r:?}"
        );
    }

    #[test]
    fn unparseable_state_file_is_flagged_and_backed_up_on_repair() {
        let tmp = TempDir::new().unwrap();
        std::fs::write(tmp.path().join("connectors.json"), "{not json").unwrap();

        // Read-only: flagged, not moved.
        let r = diagnose_in(tmp.path(), &opts(false, false));
        let c = r
            .state_files
            .iter()
            .find(|f| f.name == "connectors.json")
            .unwrap();
        assert!(matches!(
            c.status,
            StateFileStatus::Unparseable {
                backed_up_to: None,
                ..
            }
        ));
        assert!(!r.is_healthy());
        assert!(
            tmp.path().join("connectors.json").exists(),
            "untouched without --repair"
        );

        // Repair: moved to .corrupt.bak, original gone.
        let r = diagnose_in(tmp.path(), &opts(false, true));
        let c = r
            .state_files
            .iter()
            .find(|f| f.name == "connectors.json")
            .unwrap();
        assert!(matches!(
            c.status,
            StateFileStatus::Unparseable {
                backed_up_to: Some(_),
                ..
            }
        ));
        assert!(!tmp.path().join("connectors.json").exists());
        assert!(tmp.path().join("connectors.json.corrupt.bak").exists());
    }

    #[test]
    fn dotenv_env_file_is_never_parsed_or_moved() {
        // ~/.car/env is dotenv (KEY=VALUE), not JSON. It must be recognized
        // (not a leftover), never flagged Unparseable, and never moved aside by
        // --repair (it holds secrets).
        let tmp = TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("env"),
            "ANTHROPIC_API_KEY=sk-secret\nFOO=bar\n",
        )
        .unwrap();

        let r = diagnose_in(tmp.path(), &opts(false, true));
        assert!(
            r.is_healthy(),
            "dotenv env must not make the install unhealthy"
        );
        assert!(
            !r.unrecognized.contains(&"env".to_string()),
            "env is recognized"
        );
        assert!(
            r.state_files.iter().all(|f| f.name != "env"),
            "env is never JSON-checked"
        );
        assert!(
            tmp.path().join("env").exists(),
            "repair must not move the secrets file"
        );
        assert!(!tmp.path().join("env.corrupt.bak").exists());
    }

    #[test]
    fn empty_state_file_is_ok() {
        let tmp = TempDir::new().unwrap();
        std::fs::write(tmp.path().join("messaging.json"), "").unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, false));
        let c = r
            .state_files
            .iter()
            .find(|f| f.name == "messaging.json")
            .unwrap();
        assert!(matches!(c.status, StateFileStatus::Ok { .. }));
    }

    /// Parslee-ai/car#616 — the residue of an interrupted `car models pull`:
    /// the small manifest files got symlinked into the HF snapshot, the weights
    /// never arrived. Observed live as `~/.car/models/Qwen3-4B-MLX/` holding
    /// three symlinks and nothing else, while `car doctor --deep --repair`
    /// reported "none installed / ✓ Healthy".
    #[test]
    #[cfg(unix)]
    fn interrupted_pull_is_reported_not_skipped() {
        let tmp = TempDir::new().unwrap();
        // Stand in for the HF snapshot the manifests link into.
        let snap = tmp.path().join("hfsnap");
        std::fs::create_dir_all(&snap).unwrap();
        std::fs::write(snap.join("config.json"), "{}").unwrap();
        std::fs::write(snap.join("tokenizer.json"), "{}").unwrap();

        let m = tmp.path().join("models").join("Qwen3-4B-MLX");
        std::fs::create_dir_all(&m).unwrap();
        std::os::unix::fs::symlink(snap.join("config.json"), m.join("config.json")).unwrap();
        std::os::unix::fs::symlink(snap.join("tokenizer.json"), m.join("tokenizer.json")).unwrap();
        // No *.safetensors anywhere — the pull died before the weights.

        let r = diagnose_in(tmp.path(), &opts(false, false));
        let check = r
            .models
            .iter()
            .find(|c| c.name == "Qwen3-4B-MLX")
            .expect("an interrupted install must appear in the report, not be dropped");
        assert!(
            matches!(check.status, ModelStatus::Incomplete { .. }),
            "expected Incomplete, got {:?}",
            check.status
        );
        assert!(
            !r.is_healthy(),
            "a half-installed model must not read as healthy"
        );
    }

    /// The other half of #616: abandoned partial downloads were invisible.
    /// Reported with sizes, and deliberately never deleted — the HF cache is
    /// shared, and a `.sync.part` may belong to a live transfer.
    #[test]
    fn abandoned_partial_downloads_are_reported_never_deleted() {
        let hf = TempDir::new().unwrap();
        let blobs = hf.path().join("hub").join("models--x--y").join("blobs");
        std::fs::create_dir_all(&blobs).unwrap();
        let part = blobs.join("deadbeef.sync.part");
        std::fs::write(&part, vec![0u8; 4096]).unwrap();
        std::fs::write(blobs.join("finished"), b"whole").unwrap();

        let home = TempDir::new().unwrap();
        // `find_leftovers` reads HF_HOME through the registry's cache resolver.
        let prev = std::env::var_os("HF_HOME");
        std::env::set_var("HF_HOME", hf.path());
        let r = diagnose_in(home.path(), &opts(false, true));
        match prev {
            Some(v) => std::env::set_var("HF_HOME", v),
            None => std::env::remove_var("HF_HOME"),
        }

        assert_eq!(
            r.leftovers.len(),
            1,
            "expected one partial: {:?}",
            r.leftovers
        );
        assert_eq!(r.leftovers[0].bytes, 4096);
        assert!(r.leftovers[0].path.ends_with("deadbeef.sync.part"));
        assert!(
            part.exists(),
            "--repair must NOT delete a partial: the HF cache is shared and the \
             transfer may still be running"
        );
        // Wasted disk is informational, not breakage.
        assert!(r.is_healthy());
    }

    /// Parslee-ai/car#626 — `--repair` on a healthy install listed "refreshed
    /// version stamp" every time, implying it had fixed something.
    #[test]
    fn repair_does_not_report_an_unchanged_version_stamp() {
        let tmp = TempDir::new().unwrap();
        // First repair on an unstamped home: the stamp genuinely appears.
        let first = diagnose_in(tmp.path(), &opts(false, true));
        assert!(
            first.repairs.iter().any(|r| r.contains("version stamp")),
            "writing a missing stamp IS a repair: {:?}",
            first.repairs
        );
        // Second repair, nothing changed: silence.
        let second = diagnose_in(tmp.path(), &opts(false, true));
        assert!(
            !second.repairs.iter().any(|r| r.contains("version stamp")),
            "an unchanged stamp is not a repair: {:?}",
            second.repairs
        );
    }

    /// Parslee-ai/car#626 — a journal per session that never executed anything
    /// left an empty file nobody reaped (35 of 43 on the reporting install).
    /// Safe for `--repair`: zero length provably means zero events.
    #[test]
    fn empty_journals_are_reaped_on_repair_only() {
        let tmp = TempDir::new().unwrap();
        let journals = tmp.path().join("journals");
        std::fs::create_dir_all(&journals).unwrap();
        let empty = journals.join("aaaaaaaaaaaa.jsonl");
        let full = journals.join("bbbbbbbbbbbb.jsonl");
        let other = journals.join("notes.txt");
        std::fs::write(&empty, b"").unwrap();
        std::fs::write(&full, b"{\"kind\":\"proposal_received\"}\n").unwrap();
        std::fs::write(&other, b"").unwrap();

        // Read-only: nothing removed.
        let _ = diagnose_in(tmp.path(), &opts(false, false));
        assert!(empty.exists(), "no --repair, no deletion");

        let r = diagnose_in(tmp.path(), &opts(false, true));
        assert!(!empty.exists(), "empty journal should be reaped");
        assert!(full.exists(), "a journal with events must be kept");
        assert!(other.exists(), "non-.jsonl files are not ours to remove");
        assert!(
            r.repairs.iter().any(|x| x.contains("empty event journal")),
            "the reap should be reported: {:?}",
            r.repairs
        );
    }

    #[test]
    fn config_only_stub_is_skipped_not_flagged() {
        // A managed dir with only a config (weights live in the HF cache) must
        // NOT be reported as broken — that was a false positive.
        let tmp = TempDir::new().unwrap();
        let m = tmp.path().join("models").join("Stub");
        std::fs::create_dir_all(&m).unwrap();
        std::fs::write(m.join("config.json"), "{}").unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, false));
        assert!(
            r.models.iter().all(|m| m.name != "Stub"),
            "stub should be skipped"
        );
        assert!(r.is_healthy());
    }

    #[cfg(unix)]
    #[test]
    fn corrupt_model_weight_is_purged_on_repair() {
        let tmp = TempDir::new().unwrap();
        let m = tmp.path().join("models").join("Qwen3-Test");
        std::fs::create_dir_all(&m).unwrap();
        // A dangling weight symlink reads as corrupt under the cheap check.
        std::os::unix::fs::symlink(m.join("gone"), m.join("model.safetensors")).unwrap();

        let r = diagnose_in(tmp.path(), &opts(false, false));
        let mc = r.models.iter().find(|m| m.name == "Qwen3-Test").unwrap();
        assert!(matches!(mc.status, ModelStatus::Corrupt { purged: 0, .. }));

        let r = diagnose_in(tmp.path(), &opts(false, true));
        let mc = r.models.iter().find(|m| m.name == "Qwen3-Test").unwrap();
        match &mc.status {
            ModelStatus::Corrupt { purged, .. } => assert_eq!(*purged, 1),
            other => panic!("expected Corrupt, got {other:?}"),
        }
        assert!(std::fs::symlink_metadata(m.join("model.safetensors")).is_err());
    }

    #[test]
    fn shared_huggingface_weights_count_as_installed() {
        let tmp = TempDir::new().unwrap();
        let models_dir = tmp.path().join("models");
        std::fs::create_dir(&models_dir).unwrap();
        let huggingface_hub = tmp.path().join("huggingface-hub");
        let snapshot = huggingface_hub
            .join("models--example--doctor-only")
            .join("snapshots")
            .join("revision");
        std::fs::create_dir_all(&snapshot).unwrap();
        std::fs::write(snapshot.join("config.json"), b"{}").unwrap();
        std::fs::write(snapshot.join("model.safetensors"), b"weights").unwrap();

        let schema: crate::schema::ModelSchema = serde_json::from_value(serde_json::json!({
            "id": "example/doctor-only:4bit",
            "name": "doctor-only",
            "provider": "example",
            "family": "doctor-test",
            "capabilities": ["generate"],
            "context_length": 4096,
            "source": {
                "type": "mlx",
                "hf_repo": "example/doctor-only",
                "hf_weight_file": null
            }
        }))
        .unwrap();
        let mut registry = crate::registry::UnifiedRegistry::new_empty(models_dir.clone());
        registry.register(schema);

        let report = diagnose_at_with_registry(
            tmp.path(),
            &models_dir,
            &opts(false, false),
            &registry,
            Some(&huggingface_hub),
        );
        assert!(
            report.models.is_empty(),
            "shared-cache weights do not create a managed model directory check"
        );
        assert_eq!(
            report.installed_models, 1,
            "registry physical readiness must count shared-cache-only weights"
        );
    }

    #[test]
    fn current_version_state_entries_are_recognized() {
        let tmp = TempDir::new().unwrap();
        for name in ["model-resource-policy.json", "parslee-auth-authority.json"] {
            std::fs::write(tmp.path().join(name), b"{}").unwrap();
        }
        for name in ["proposal-completed-index", "selfheal"] {
            std::fs::create_dir(tmp.path().join(name)).unwrap();
        }

        let unrecognized = find_unrecognized(tmp.path());
        assert!(
            unrecognized.is_empty(),
            "current-version state must not be reported as older-install debris: {unrecognized:?}"
        );
    }

    #[test]
    fn repair_never_json_validates_or_moves_the_binary_peer_identity_key() {
        let tmp = TempDir::new().unwrap();
        let key_path = tmp.path().join("peer-identity.key");
        let key_bytes = b"0123456789abcdef0123456789abcdef";
        std::fs::write(&key_path, key_bytes).unwrap();

        let report = diagnose_repair_with_isolated_model_roots(tmp.path());

        assert_eq!(
            std::fs::read(&key_path).unwrap(),
            key_bytes,
            "repair must preserve the binary peer identity byte-for-byte"
        );
        assert!(
            !tmp.path().join("peer-identity.key.corrupt.bak").exists(),
            "the non-JSON identity key must never be classified as corrupt JSON"
        );
        assert!(
            report
                .state_files
                .iter()
                .all(|file| file.name != "peer-identity.key"),
            "the peer identity belongs to the non-JSON allowlist"
        );
        assert!(
            !report
                .unrecognized
                .contains(&"peer-identity.key".to_string()),
            "the live identity key must be recognized"
        );
    }

    /// Exercises the known-non-JSON branch: invalid UTF-8 must bypass
    /// `check_state_file` (whose read-to-string error branch reports Absent),
    /// remain recognized by `find_unrecognized`, and survive repair untouched.
    #[test]
    fn repair_preserves_a_non_utf8_peer_identity_key() {
        let tmp = TempDir::new().unwrap();
        let key_path = tmp.path().join("peer-identity.key");
        let key_bytes = [0xff, 0xfe, 0xfd, 0x00, 0x80, 0x81, 0x82, 0x83];
        std::fs::write(&key_path, key_bytes).unwrap();

        let report = diagnose_repair_with_isolated_model_roots(tmp.path());

        assert_eq!(
            std::fs::read(&key_path).unwrap(),
            key_bytes,
            "repair must preserve genuinely non-UTF-8 identity bytes"
        );
        assert!(
            !tmp.path().join("peer-identity.key.corrupt.bak").exists(),
            "repair must not create a corrupt-JSON backup for a binary key"
        );
        assert!(
            report
                .state_files
                .iter()
                .all(|file| file.name != "peer-identity.key"),
            "the binary key must bypass the JSON state-file checker"
        );
        assert!(
            !report
                .unrecognized
                .contains(&"peer-identity.key".to_string()),
            "the binary key must take the recognized non-JSON branch"
        );
    }

    #[test]
    fn unrecognized_entries_are_reported_not_removed() {
        let tmp = TempDir::new().unwrap();
        std::fs::write(tmp.path().join("mystery-leftover.json"), "{}").unwrap();
        std::fs::create_dir_all(tmp.path().join("old_install_dir")).unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, true));
        assert!(r
            .unrecognized
            .contains(&"mystery-leftover.json".to_string()));
        assert!(r.unrecognized.contains(&"old_install_dir".to_string()));
        // Repair must NOT delete unrecognized entries.
        assert!(tmp.path().join("mystery-leftover.json").exists());
        assert!(tmp.path().join("old_install_dir").exists());
    }

    #[test]
    fn version_skew_detected() {
        let tmp = TempDir::new().unwrap();
        let stale = VersionStamp {
            car_version: "0.0.1-ancient".to_string(),
            state_schema_version: 1,
            previous_car_version: None,
            previous_state_schema_version: None,
        };
        std::fs::write(
            tmp.path().join("version.json"),
            serde_json::to_string(&stale).unwrap(),
        )
        .unwrap();
        let r = diagnose_in(tmp.path(), &opts(false, false));
        assert!(r.version_skew);
        assert!(!r.is_healthy());

        // Repair refreshes the stamp to the current binary, clearing skew next run.
        let _ = diagnose_in(tmp.path(), &opts(false, true));
        let r = diagnose_in(tmp.path(), &opts(false, false));
        assert!(!r.version_skew, "stamp refreshed, skew cleared");
    }
}

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

    fn write(home: &Path, stamp: &VersionStamp) {
        std::fs::create_dir_all(home).unwrap();
        std::fs::write(
            home.join("version.json"),
            serde_json::to_string_pretty(stamp).unwrap(),
        )
        .unwrap();
    }

    fn stamp(version: &str, schema: u32) -> VersionStamp {
        VersionStamp {
            car_version: version.to_string(),
            state_schema_version: schema,
            previous_car_version: None,
            previous_state_schema_version: None,
        }
    }

    /// The car#881 bug, as a test. A daemon boot used to overwrite the stamp
    /// unconditionally, so the fact that an older CAR wrote this state was gone
    /// before `car doctor` — the only reader — could ever be run.
    #[test]
    fn stamping_after_an_upgrade_preserves_what_it_replaced() {
        let dir = tempfile::tempdir().unwrap();
        write(dir.path(), &stamp("0.39.0", 1));

        let t = stamp_version(dir.path()).unwrap();
        assert!(t.upgraded(), "0.39.0 -> current is an upgrade");
        assert_eq!(
            t.current.previous_car_version.as_deref(),
            Some("0.39.0"),
            "the predecessor must survive the stamp that replaced it"
        );

        let report = diagnose_in(dir.path(), &DoctorOptions::default());
        assert_eq!(
            report.carried_from_version.as_deref(),
            Some("0.39.0"),
            "doctor must still see it AFTER the daemon stamped"
        );
    }

    /// The subtler half. Rewriting `previous` on every boot would collapse it to
    /// the current version after one restart — the same erasure, one level down.
    #[test]
    fn rebooting_on_the_same_version_keeps_the_original_predecessor() {
        let dir = tempfile::tempdir().unwrap();
        write(dir.path(), &stamp("0.39.0", 1));

        stamp_version(dir.path()).unwrap(); // the upgrade
        for _ in 0..5 {
            stamp_version(dir.path()).unwrap(); // ordinary reboots
        }

        let report = diagnose_in(dir.path(), &DoctorOptions::default());
        assert_eq!(
            report.carried_from_version.as_deref(),
            Some("0.39.0"),
            "five reboots must not rewrite the predecessor to the current version"
        );
    }

    #[test]
    fn a_fresh_install_records_no_predecessor() {
        let dir = tempfile::tempdir().unwrap();
        let t = stamp_version(dir.path()).unwrap();
        assert!(t.previous.is_none());
        assert!(!t.upgraded());
        assert!(t.current.previous_car_version.is_none());
        assert!(!diagnose_in(dir.path(), &DoctorOptions::default()).schema_from_the_future);
    }

    /// A downgrade. STATE_SCHEMA_VERSION's contract says a reader older than the
    /// state should refuse rather than corrupt; nothing acted on it before.
    #[test]
    fn state_from_a_newer_schema_is_flagged() {
        let dir = tempfile::tempdir().unwrap();
        write(dir.path(), &stamp("99.0.0", STATE_SCHEMA_VERSION + 7));

        let t = stamp_version(dir.path()).unwrap();
        assert!(
            t.schema_from_the_future(),
            "newer on-disk schema must be flagged"
        );

        // And it must be visible to doctor as unhealthy, not merely noted.
        write(dir.path(), &stamp("99.0.0", STATE_SCHEMA_VERSION + 7));
        let report = diagnose_in(dir.path(), &DoctorOptions::default());
        assert!(report.schema_from_the_future);
        assert!(!report.is_healthy());
    }

    /// Carrying state across an upgrade is the NORMAL case. Treating it as a
    /// health problem would make every upgraded install permanently unhealthy,
    /// which is how a warning gets ignored.
    #[test]
    fn carrying_state_across_an_upgrade_is_not_unhealthy() {
        let dir = tempfile::tempdir().unwrap();
        write(dir.path(), &stamp("0.39.0", STATE_SCHEMA_VERSION));
        stamp_version(dir.path()).unwrap();

        let report = diagnose_in(dir.path(), &DoctorOptions::default());
        assert!(report.carried_from_version.is_some());
        assert!(report.is_healthy(), "an ordinary upgrade is not a defect");
    }

    /// An older stamp has no `previous_*` keys at all. It must deserialize, not
    /// blow up the boot path.
    #[test]
    fn a_pre_existing_stamp_without_the_new_fields_still_loads() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path()).unwrap();
        std::fs::write(
            dir.path().join("version.json"),
            r#"{"car_version":"0.39.0","state_schema_version":1}"#,
        )
        .unwrap();

        let t = stamp_version(dir.path()).unwrap();
        assert_eq!(
            t.previous.as_ref().map(|p| p.car_version.as_str()),
            Some("0.39.0")
        );
        assert_eq!(t.current.previous_car_version.as_deref(), Some("0.39.0"));
    }

    /// A corrupt stamp must not stop the daemon stamping — it is best-effort by
    /// contract, and refusing to boot over an unreadable version file would be a
    /// far worse failure than the one it guards.
    #[test]
    fn a_corrupt_stamp_is_treated_as_absent_and_replaced() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path()).unwrap();
        std::fs::write(dir.path().join("version.json"), "{ not json").unwrap();

        let t = stamp_version(dir.path()).unwrap();
        assert!(t.previous.is_none(), "unreadable == no usable predecessor");
        assert_eq!(t.current.car_version, VersionStamp::current().car_version);
    }
}

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

    /// A never-provisioned runtime is absent, not broken — a fresh install must
    /// not read as unhealthy.
    #[test]
    fn absent_runtimes_are_not_reported() {
        let dir = tempfile::tempdir().unwrap();
        assert!(check_runtimes(dir.path()).is_empty());
    }

    /// The failure this check exists for: the venv directory is fully populated
    /// but its interpreter symlink points at a Homebrew formula that is gone.
    // Unix-only because the *setup* needs a POSIX symlink, not because the
    // behaviour is. Same shape as `interrupted_pull_is_reported_not_skipped`.
    #[cfg(unix)]
    #[test]
    fn rotated_away_interpreter_is_reported_broken() {
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("visual-runtime").join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        std::os::unix::fs::symlink(
            "/opt/homebrew/opt/python@0.0/bin/python0.0",
            bin.join("python"),
        )
        .unwrap();

        let checks = check_runtimes(dir.path());
        assert_eq!(checks.len(), 1);
        assert_eq!(checks[0].name, "visual-runtime");
        assert!(checks[0].present);
        assert!(!checks[0].interpreter_ok);
        assert!(checks[0].is_broken());
    }

    /// A broken runtime must sink `is_healthy` — the whole point is that this
    /// stops being silent.
    #[test]
    fn broken_runtime_makes_report_unhealthy() {
        let mut report = DoctorReport {
            car_home: "/tmp/x".into(),
            binary_version: VersionStamp::current().car_version,
            on_disk_stamp: None,
            version_skew: false,
            carried_from_version: None,
            schema_from_the_future: false,
            state_files: Vec::new(),
            models: Vec::new(),
            installed_models: 0,
            leftovers: Vec::new(),
            runtimes: Vec::new(),
            unrecognized: Vec::new(),
            repairs: Vec::new(),
            daemon_tmpdir: None,
        };
        assert!(report.is_healthy());

        report.runtimes.push(RuntimeCheck {
            name: "speech-runtime".into(),
            root: "/tmp/x/speech-runtime".into(),
            present: true,
            interpreter_ok: false,
        });
        assert!(!report.is_healthy());
    }
}

/// Parslee-ai/car#1494: the daemon's startup TMPDIR probe record, written by
/// [`record_daemon_tmpdir_probe`] and read by the offline doctor. Temp dirs and
/// injected paths only.
#[cfg(test)]
mod daemon_tmpdir_tests {
    use super::*;

    const NOT_A_DIRECTORY: &[u8] = b"a regular file where TMPDIR should be";

    fn marker(pid: u32, ok: bool) -> DaemonTmpdirMarker {
        DaemonTmpdirMarker {
            pid,
            booted_at_unix: 1_789_000_000,
            car_version: VersionStamp::current().car_version,
            checked_path: "/private/tmp/PKInstallSandbox.test/tmp".to_string(),
            ok,
            error: (!ok)
                .then(|| "create failed: No such file or directory (os error 2)".to_string()),
        }
    }

    fn write_marker(home: &Path, marker: &DaemonTmpdirMarker) {
        let path = daemon_tmpdir_marker_path(home);
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(path, serde_json::to_string_pretty(marker).unwrap()).unwrap();
    }

    /// Doctor against `home`, with the weights and Hugging Face roots isolated
    /// in temp dirs so nothing outside the test is read.
    fn diagnose_home(home: &Path) -> DoctorReport {
        let models = tempfile::tempdir().unwrap();
        let hub = tempfile::tempdir().unwrap();
        diagnose_at_isolated(home, models.path(), hub.path(), &DoctorOptions::default())
    }

    fn status_of(report: &DoctorReport) -> DaemonTmpdirStatus {
        report
            .daemon_tmpdir
            .clone()
            .expect("the record must be reported")
            .status
    }

    /// A pid that named a real process a moment ago and no longer does: a
    /// short-lived child, spawned and reaped.
    #[cfg(unix)]
    fn dead_pid() -> u32 {
        let mut child = std::process::Command::new("true")
            .spawn()
            .expect("spawn `true`");
        let pid = child.id();
        child.wait().expect("reap `true`");
        assert!(
            !unix_pid_alive(pid),
            "a reaped child's pid must read as gone"
        );
        pid
    }

    fn healthy_tmpdir(parent: &Path) -> PathBuf {
        let dir = parent.join("healthy-tmpdir");
        std::fs::create_dir(&dir).unwrap();
        dir
    }

    #[test]
    fn probing_a_file_tmpdir_records_a_failure() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        let tmpdir = tmp.path().join("tmpdir-is-a-file");
        std::fs::write(&tmpdir, NOT_A_DIRECTORY).unwrap();

        let recorded = record_daemon_tmpdir_probe(&home, &tmpdir)
            .expect("a failed probe is still a successful record");

        assert!(!recorded.ok, "{recorded:?}");
        assert_eq!(recorded.pid, std::process::id());
        assert_eq!(recorded.checked_path, tmpdir.display().to_string());
        let error = recorded.error.clone().expect("a failure names its error");
        assert!(error.starts_with("create failed"), "{error}");
        #[cfg(unix)]
        assert!(
            error.contains(&format!("os error {}", libc::ENOTDIR)),
            "a file where the directory should be is ENOTDIR: {error}"
        );
        assert_eq!(read_daemon_tmpdir_marker(&home), Some(Ok(recorded)));
        assert_eq!(std::fs::read(&tmpdir).unwrap(), NOT_A_DIRECTORY);
    }

    #[test]
    fn a_healthy_probe_replaces_a_prior_failure_and_leaves_nothing_behind() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        let broken = tmp.path().join("tmpdir-is-a-file");
        std::fs::write(&broken, NOT_A_DIRECTORY).unwrap();
        let healthy = healthy_tmpdir(tmp.path());

        assert!(!record_daemon_tmpdir_probe(&home, &broken).unwrap().ok);
        let recorded = record_daemon_tmpdir_probe(&home, &healthy).unwrap();

        assert!(recorded.ok, "{recorded:?}");
        assert_eq!(recorded.error, None);
        assert_eq!(read_daemon_tmpdir_marker(&home), Some(Ok(recorded)));
        #[cfg(unix)]
        assert!(
            std::fs::read_dir(&healthy).unwrap().next().is_none(),
            "the probe removes the one file it created after proving its identity"
        );
        #[cfg(not(unix))]
        assert_eq!(
            std::fs::read_dir(&healthy).unwrap().count(),
            1,
            "without portable file identity the tiny probe file is left safely behind"
        );
        let names: Vec<_> = std::fs::read_dir(home.join(DOCTOR_DIR))
            .unwrap()
            .map(|entry| entry.unwrap().file_name())
            .collect();
        assert_eq!(
            names,
            vec![std::ffi::OsString::from(DAEMON_TMPDIR_MARKER_FILE)],
            "no temporary record may be left behind"
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_symlinked_tmpdir_is_followed_and_its_probe_file_is_removed() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        let target = healthy_tmpdir(tmp.path());
        let link = tmp.path().join("tmpdir-link");
        std::os::unix::fs::symlink(&target, &link).unwrap();

        let recorded = record_daemon_tmpdir_probe(&home, &link).unwrap();

        assert!(
            recorded.ok,
            "a directory symlink is valid TMPDIR: {recorded:?}"
        );
        assert_eq!(recorded.checked_path, link.display().to_string());
        assert!(
            std::fs::read_dir(&target).unwrap().next().is_none(),
            "the identity-checked probe file is removed from the resolved directory"
        );
    }

    #[cfg(unix)]
    #[test]
    fn cleanup_does_not_remove_a_different_file_at_the_probe_path() {
        let tmp = tempfile::tempdir().unwrap();
        let created_path = tmp.path().join("created");
        let probe_path = tmp.path().join("substitute");
        std::fs::write(&created_path, b"created").unwrap();
        std::fs::write(&probe_path, b"substitute").unwrap();
        let created = std::fs::metadata(&created_path).unwrap();

        let error = remove_probe_file(&probe_path, &created).unwrap_err();

        assert!(error.starts_with("remove skipped"), "{error}");
        assert_eq!(std::fs::read(&probe_path).unwrap(), b"substitute");
    }

    #[test]
    fn a_failed_handle_stat_records_that_the_probe_file_was_left() {
        let tmp = tempfile::tempdir().unwrap();
        let probe_path = tmp.path().join("probe");
        std::fs::write(&probe_path, TMPDIR_PROBE_BYTES).unwrap();
        let created = Err("stat failed: injected failure".to_string());

        let cleanup = cleanup_probe_file(&probe_path, &created);
        let error = combine_probe_results(created.map(|_| ()), cleanup).unwrap_err();

        assert!(error.contains("stat failed: injected failure"), "{error}");
        assert!(error.contains("identity could not be proven"), "{error}");
        assert!(error.contains("left"), "{error}");
        assert_eq!(std::fs::read(&probe_path).unwrap(), TMPDIR_PROBE_BYTES);
    }

    #[test]
    fn the_record_does_not_trip_find_unrecognized() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        let healthy = healthy_tmpdir(tmp.path());

        record_daemon_tmpdir_probe(&home, &healthy).unwrap();

        assert!(daemon_tmpdir_marker_path(&home).is_file());
        assert!(KNOWN_DIRS.contains(&DOCTOR_DIR));
        assert!(
            find_unrecognized(&home).is_empty(),
            "{:?}",
            find_unrecognized(&home)
        );
        assert!(diagnose_home(&home).unrecognized.is_empty());
    }

    #[test]
    fn an_absent_record_is_not_an_error_and_adds_no_json_key() {
        let home = tempfile::tempdir().unwrap();
        let report = diagnose_home(home.path());
        assert!(report.daemon_tmpdir.is_none());
        assert!(report.is_healthy(), "{report:?}");
        let json = serde_json::to_value(&report).unwrap();
        assert!(
            json.get("daemon_tmpdir").is_none(),
            "additive: a report without a record serializes as before"
        );
    }

    #[cfg(unix)]
    #[test]
    fn doctor_reads_failure_healthy_stale_and_absent_records() {
        let home = tempfile::tempdir().unwrap();
        let live = std::process::id();

        let absent = diagnose_home(home.path());
        assert!(absent.daemon_tmpdir.is_none() && absent.is_healthy());

        let failed = marker(live, false);
        write_marker(home.path(), &failed);
        let report = diagnose_home(home.path());
        assert_eq!(
            status_of(&report),
            DaemonTmpdirStatus::Current { marker: failed }
        );
        assert!(!report.is_healthy(), "failure from the running daemon");

        let healthy = marker(live, true);
        write_marker(home.path(), &healthy);
        let report = diagnose_home(home.path());
        assert_eq!(
            status_of(&report),
            DaemonTmpdirStatus::Current { marker: healthy }
        );
        assert!(
            report.is_healthy(),
            "healthy record from the running daemon"
        );

        let stale = marker(dead_pid(), false);
        write_marker(home.path(), &stale);
        let report = diagnose_home(home.path());
        assert_eq!(
            status_of(&report),
            DaemonTmpdirStatus::Stale { marker: stale }
        );
        assert!(report.is_healthy(), "a stale failure is not failing");
    }

    #[cfg(unix)]
    #[test]
    fn a_running_daemons_failed_probe_is_unhealthy() {
        let home = tempfile::tempdir().unwrap();
        let recorded = marker(std::process::id(), false);
        write_marker(home.path(), &recorded);

        let report = diagnose_home(home.path());

        let check = report
            .daemon_tmpdir
            .clone()
            .expect("the record is reported");
        assert_eq!(
            check.marker_path,
            daemon_tmpdir_marker_path(home.path()).display().to_string()
        );
        assert_eq!(
            check.status,
            DaemonTmpdirStatus::Current { marker: recorded }
        );
        assert!(check.is_failing());
        assert!(!report.is_healthy(), "{report:?}");
    }

    #[cfg(unix)]
    #[test]
    fn a_record_from_a_daemon_that_is_gone_is_stale_not_failing() {
        let home = tempfile::tempdir().unwrap();
        let recorded = marker(dead_pid(), false);
        write_marker(home.path(), &recorded);

        let report = diagnose_home(home.path());

        let check = report
            .daemon_tmpdir
            .clone()
            .expect("the record is reported");
        assert_eq!(check.status, DaemonTmpdirStatus::Stale { marker: recorded });
        assert!(!check.is_failing());
        assert!(report.is_healthy(), "{report:?}");
    }

    #[test]
    fn an_ok_record_is_healthy() {
        let home = tempfile::tempdir().unwrap();
        let recorded = marker(std::process::id(), true);
        write_marker(home.path(), &recorded);

        let report = diagnose_home(home.path());

        #[cfg(unix)]
        assert_eq!(
            status_of(&report),
            DaemonTmpdirStatus::Current { marker: recorded }
        );
        #[cfg(not(unix))]
        assert_eq!(
            status_of(&report),
            DaemonTmpdirStatus::Unverified { marker: recorded }
        );
        assert!(report.is_healthy(), "{report:?}");
    }

    /// Off Unix there is no liveness check: the record is shown with its
    /// result and never folded into health as a failure.
    #[test]
    fn without_a_liveness_check_a_failed_record_is_unverified_not_failing() {
        let recorded = marker(std::process::id(), false);
        let status = classify_daemon_tmpdir_marker(recorded.clone(), None);
        assert_eq!(status, DaemonTmpdirStatus::Unverified { marker: recorded });
        let check = DaemonTmpdirCheck {
            marker_path: "doctor/daemon-tmpdir.json".to_string(),
            status,
        };
        assert!(!check.is_failing());
    }

    #[test]
    fn an_unreadable_record_is_reported_not_failing() {
        let home = tempfile::tempdir().unwrap();
        let path = daemon_tmpdir_marker_path(home.path());
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(&path, "{ not json").unwrap();

        let report = diagnose_home(home.path());

        assert!(
            matches!(status_of(&report), DaemonTmpdirStatus::Unreadable { .. }),
            "{:?}",
            report.daemon_tmpdir
        );
        assert!(report.is_healthy(), "{report:?}");
    }

    #[test]
    fn a_record_serializes_additively_and_round_trips() {
        let home = tempfile::tempdir().unwrap();
        write_marker(home.path(), &marker(std::process::id(), true));

        let json = serde_json::to_value(diagnose_home(home.path())).unwrap();

        let record = json
            .get("daemon_tmpdir")
            .expect("the record serializes under `daemon_tmpdir`");
        assert!(
            record.get("status").is_some() && record.get("marker_path").is_some(),
            "{record}"
        );
        assert_eq!(record["marker"]["ok"], serde_json::Value::Bool(true));
        let back: DoctorReport = serde_json::from_value(json).unwrap();
        assert!(back.daemon_tmpdir.is_some());
    }

    #[cfg(unix)]
    #[test]
    fn the_record_is_never_written_through_a_symlinked_doctor_dir() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        std::fs::create_dir(&home).unwrap();
        let elsewhere = tmp.path().join("elsewhere");
        std::fs::create_dir(&elsewhere).unwrap();
        std::os::unix::fs::symlink(&elsewhere, home.join(DOCTOR_DIR)).unwrap();
        let healthy = healthy_tmpdir(tmp.path());

        assert!(record_daemon_tmpdir_probe(&home, &healthy).is_err());
        assert!(
            std::fs::read_dir(&elsewhere).unwrap().next().is_none(),
            "nothing may land where the symlink points"
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_symlink_at_the_record_path_is_replaced_not_followed() {
        let tmp = tempfile::tempdir().unwrap();
        let home = tmp.path().join("car-home");
        std::fs::create_dir_all(home.join(DOCTOR_DIR)).unwrap();
        let victim = tmp.path().join("victim");
        std::fs::write(&victim, b"victim").unwrap();
        std::os::unix::fs::symlink(&victim, daemon_tmpdir_marker_path(&home)).unwrap();
        let healthy = healthy_tmpdir(tmp.path());

        let recorded = record_daemon_tmpdir_probe(&home, &healthy).unwrap();

        assert_eq!(std::fs::read(&victim).unwrap(), b"victim");
        assert!(std::fs::symlink_metadata(daemon_tmpdir_marker_path(&home))
            .unwrap()
            .file_type()
            .is_file());
        assert_eq!(read_daemon_tmpdir_marker(&home), Some(Ok(recorded)));
    }
}