mahbot 0.6.4

//! chrome-use daemon health monitoring and bounded auto-recovery.
//!
//! The chrome-use CLI talks to a per-session background daemon that drives
//! Chrome through the extension relay. When the daemon or relay dies, CLI
//! commands hang inside its own 5-retry loop (~152 s) instead of failing fast.
//! This module classifies health from a daemon-free `status` snapshot
//! (extension disabled, relay down, host missing, …) and auto-restarts the
//! daemon with bounded backoff and thrash protection. Real wedge detection is
//! per-call: a chrome command that fails with the daemon-unavailable signature
//! marks the daemon unhealthy and wakes the watchdog, which recovers from that
//! stored classification — the daemon-free status cannot see a wedged daemon,
//! so the watchdog never re-evaluates over a fail-fast classification. It also
//! owns the chrome-use CLI invocation primitives (binary name, `--version`
//! check) so the chrome tool depends on this module and not vice versa; the
//! shared command env/setup lives in [`crate::chrome::spawn`].
//!
//! mahbot drives the user's real, logged-in Chrome through the chrome-use
//! extension relay — no chrome-use `--launch` mode, no profile copies, no CDP
//! fallbacks. When the relay is down because Chrome is closed, the watchdog
//! silently auto-launches the user's real Chrome (approved product decision; a
//! window may appear unasked — the launch inherits the user's real profile/
//! environment) under its own bounded launch budget, separate from daemon
//! restarts. An absent extension is unfixable by any launch or restart and
//! pauses auto-recovery.
//!
//! Verified tab-sweep: mahbot-owned session tab groups (`link-enricher-*`) are
//! closed through the CLI and verified by round-over-round re-enumeration. A
//! bare `session stop` cannot settle them: a group can hold tabs the session
//! ADOPTED, which stop never closes and never reports (the ended-run release in
//! [`crate::tools::chrome_release`] relies on stop only for tabs its run itself
//! CREATED), and this file's own stop (`stop_session_daemon`) is bounded by
//! `CLI_TIMEOUT` — which expires as the daemon's shutdown grace does, so the
//! reclaim that follows never runs and a scratch tab it misses is orphaned
//! forever (no other mechanism ever reclaims it). What a stop proves and what it
//! costs is stated by the live-verified behaviours below.
//!
//! Trade-offs:
//! - A genuine daemon wedge surfaces on the first real chrome call, which pays
//!   the CLI's ~152 s internal retry before fail-fast marks it unhealthy (worst
//!   case, rare, and self-healing — the restart clears the wedge).
//! - `daemon restart` destroys all session state; recovery guidance notes that
//!   existing chrome sessions are reset.
//! - The Chrome auto-launch shares the user's profile and environment, so it may
//!   open a window unasked; on display-less hosts it is paused rather than spend
//!   the launch budget (launching can never help there).

use crate::chrome::contract::{
    ChromeResponse, is_daemon_unavailable_error, is_relay_unavailable_error,
    is_unreachable_tab_error,
};
use crate::chrome::spawn::{CliRun, CliSpawn, CliTimeout, ensure_chrome_env, spawn_cli};
use crate::util::UnwrapPoison;
use serde_json::Value;
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::sync::{Mutex, OnceLock};
use std::time::{Duration, Instant};
use tokio::process::Command;
use tracing::{debug, error, info, warn};

// ── Bounds (pinned for deterministic recovery) ────────────────────────────
/// How long a CLI health/sweep command may take before it is considered
/// wedged. A healthy daemon answers in milliseconds; a wedged one hangs for
/// the CLI's internal 45s read timeouts × 5 retries.
const CLI_TIMEOUT: Duration = Duration::from_secs(8);
/// Cache TTL for a healthy evaluation (fresh enough for per-call checks).
const HEALTH_TTL: Duration = Duration::from_secs(10);
/// Longer TTL for a confirmed-down result, so repeated chrome calls fail fast
/// instead of re-evaluating on every invocation.
const UNHEALTHY_TTL: Duration = Duration::from_mins(1);
/// Watchdog cadence between automatic health evaluations.
const WATCHDOG_INTERVAL: Duration = Duration::from_secs(30);
/// How often the watchdog re-verifies CLI presence on hosts where it was
/// found — the binary can be uninstalled while the daemon runs, but checking
/// every watchdog interval would spawn `--version` needlessly.
const CLI_RECHECK: Duration = Duration::from_mins(5);
/// Consecutive definitive-missing CLI probes before the watchdog stands down —
/// a single transient probe failure (spawn EAGAIN/EMFILE under process
/// pressure) must not take the watchdog out of service.
const CLI_MISSING_THRESHOLD: u32 = 2;
/// Consecutive failed restarts before auto-recovery halts (thrash protection).
const MAX_RESTART_ATTEMPTS: u32 = 3;
/// Consecutive failed Chrome auto-launches before the launch budget halts —
/// independent of the daemon-restart budget (a closed browser is a different
/// problem than a wedged daemon; fixing one must not consume the other's).
const MAX_LAUNCH_ATTEMPTS: u32 = 3;
/// Sustained-health window: the restart-attempt counter resets only after the
/// daemon-free status has been healthy for this long (≥2 watchdog intervals).
/// A transient healthy right after a restart must not reopen a bounded cycle
/// early, or a runaway restart loop can never trip the halt. Daemon-free
/// status cannot see wedges — for a persistent wedge the budget keeps
/// resetting between sparse real calls, so the halt engages only for
/// service-level causes (accepted with per-call wedge detection).
const SUSTAINED_HEALTHY_WINDOW: Duration = Duration::from_mins(1);
/// Backoff between restart attempts (30s → 2min → 10min).
const RESTART_BACKOFF: [Duration; 3] = [
    Duration::from_secs(30),
    Duration::from_mins(2),
    Duration::from_mins(10),
];
/// Backoff between Chrome auto-launch attempts (30s → 2min → 10min), mirroring
/// the restart backoff so a host that keeps failing cannot spam launches.
const LAUNCH_BACKOFF: [Duration; 3] = [
    Duration::from_secs(30),
    Duration::from_mins(2),
    Duration::from_mins(10),
];
/// Cooldown after the max restart attempts, before a fresh bounded cycle.
const HALT_COOLDOWN: Duration = Duration::from_mins(30);
/// How long recovery waits for the extension relay to republish after a
/// `daemon restart` on a relay-drop — the MV3 service worker revives on its
/// keepalive (~30 s) and only then writes the relay endpoint back.
const RELAY_REVIVE_WAIT: Duration = Duration::from_secs(40);

// ── Verified-close sweep bounds (pinned for deterministic recovery) ──────
/// Total budget for one sweep invocation, starting before the service-state
/// skip gate. Every CLI call checks the deadline before
/// spawning (one call may overshoot by at most [`CLI_TIMEOUT`] — the
/// in-flight bound). On expiry the sweep defers: leftover tabs are retried by
/// the next sweep/startup (self-healing), never a permanent orphan.
const SWEEP_TOTAL_BUDGET: Duration = Duration::from_secs(15);
/// Convergence rounds before a sweep gives up for this invocation. The budget
/// is the hard cap; this only bounds the number of enumerate/close/stop cycles
/// (a healthy host converges in 3 rounds; a retried failed close needs 4–5).
const SWEEP_MAX_ROUNDS: u32 = 5;

/// Classified cause for a failed health check. Drives cause-specific warnings
/// and decides whether auto-recovery can help at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ProbeFailure {
    /// chrome-use extension or native host is not installed.
    NotInstalled,
    /// Native host manifest present but launcher/target broken.
    HostBroken,
    /// Extension installed but disabled (Chrome reports disable reasons).
    ExtensionDisabled,
    /// The chrome-use extension is absent from Chrome entirely — unfixable by
    /// any daemon restart or launch; the user must install it from the store.
    ExtensionAbsent,
    /// Extension enabled but the relay is down — transient, self-heals.
    RelayDown,
    /// No Chrome/Chromium-family browser process is running. NOT unfixable —
    /// auto-recovery launches the user's real Chrome (never a daemon restart).
    ChromeNotRunning,
    /// The session's tab lost its debugger attach (orphaned) — the daemon and
    /// relay are up; only closing the tab by hand unblocks the session.
    UnreachableTab,
    /// The daemon socket hung or errored (daemon-side wedge).
    DaemonWedge,
}

/// Result of a health evaluation: healthy, or down with a classified cause.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ProbeOutcome {
    Healthy,
    Down(ProbeFailure),
}

impl ProbeOutcome {
    fn is_healthy(self) -> bool {
        matches!(self, ProbeOutcome::Healthy)
    }

    fn failure(self) -> Option<ProbeFailure> {
        match self {
            ProbeOutcome::Healthy => None,
            ProbeOutcome::Down(f) => Some(f),
        }
    }
}

impl ProbeFailure {
    /// Causes a daemon restart cannot fix — reported with their concrete fix
    /// and never consume restart attempts. `ChromeNotRunning` is deliberately
    /// NOT here: a closed browser is fixed by launching it, not by restarting
    /// the daemon.
    fn is_unfixable(self) -> bool {
        matches!(
            self,
            ProbeFailure::NotInstalled
                | ProbeFailure::HostBroken
                | ProbeFailure::ExtensionDisabled
                | ProbeFailure::ExtensionAbsent
                | ProbeFailure::UnreachableTab
        )
    }
}

/// Outcome of a Chrome auto-launch attempt, for honest down messaging about
/// what the watchdog actually did (never attempted = `None` on [`DaemonHealth`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ChromeLaunchOutcome {
    /// Chrome was spawned (and the relay is still down afterward).
    Launched,
    /// No Chrome/Chromium binary found, or it could not be started.
    Failed,
    /// No display session on this host — launching would never help.
    NoDisplay,
}

/// One bounded attempt budget (backoff between attempts, halt + cooldown after
/// `max` failures). Pure state — the bounded state machine is unit-testable.
#[derive(Default)]
struct AttemptBudget {
    attempts: u32,
    next_at: Option<Instant>,
    halted: bool,
    halted_until: Option<Instant>,
}

impl AttemptBudget {
    /// Decide whether an attempt is allowed, updating the bookkeeping in place.
    /// Backoff is checked before the attempt cap, so the final long grace after
    /// the last attempt is honored before the halt fires. Cooldown expiry resets
    /// and opens a fresh bounded cycle.
    fn gate(
        &mut self,
        max: u32,
        backoff: &[Duration],
        cooldown: Duration,
        now: Instant,
    ) -> RecoveryGate {
        if self.halted {
            if self.halted_until.is_some_and(|until| now < until) {
                return RecoveryGate::Cooldown;
            }
            // Cooldown expired — reset and allow a fresh bounded cycle.
            self.halted = false;
            self.attempts = 0;
            self.halted_until = None;
            self.next_at = None;
        }
        // Backoff is checked before the attempt cap, so the final long grace
        // after the last attempt is honored before the halt fires.
        if self.next_at.is_some_and(|next| now < next) {
            return RecoveryGate::Backoff;
        }
        if self.attempts >= max {
            self.halted = true;
            self.halted_until = Some(now + cooldown);
            return RecoveryGate::Halted;
        }
        let attempt = self.attempts + 1;
        self.attempts = attempt;
        self.next_at = Some(now + backoff[(attempt as usize - 1).min(backoff.len() - 1)]);
        RecoveryGate::Allowed(attempt)
    }

    /// Whether a recovery timer is currently pending — when it is, the timer IS
    /// the wait (callers must not stack their own relay-revive polls on top of it).
    fn is_waiting(&self, now: Instant) -> bool {
        self.halted_until.is_some_and(|until| now < until)
            || self.next_at.is_some_and(|next| now < next)
    }

    /// Reset to a fresh bounded cycle (sustained health / cooldown expiry).
    fn reset(&mut self) {
        self.attempts = 0;
        self.next_at = None;
        self.halted = false;
        self.halted_until = None;
    }
}

#[derive(Default)]
struct DaemonHealth {
    healthy: Option<bool>,
    last_probe: Option<Instant>,
    /// Restart bounded cycle — backoff between attempts, halt + cooldown after
    /// [`MAX_RESTART_ATTEMPTS`] failures (thrash protection).
    restart_budget: AttemptBudget,
    /// Chrome auto-launch bounded cycle — separate from the restart budget (a
    /// closed browser and a wedged daemon are independent failures, so neither
    /// should consume the other's bounded cycle).
    launch_budget: AttemptBudget,
    /// Outcome of the last Chrome auto-launch — `None` when never attempted or
    /// superseded by health. Failure outcomes survive until health or the
    /// sustained-health reset clears them, so down messaging stays honest.
    launch_outcome: Option<ChromeLaunchOutcome>,
    /// Last classified failure — surfaces the cause in LLM-facing
    /// messages and drives transition-based warning logging.
    last_failure: Option<ProbeFailure>,
    /// The failure cause the last transition-based warning named — reset on
    /// recovery so the same cause warns again after a healthy spell.
    last_cause_warned: Option<ProbeFailure>,
    /// Start of the current sustained-healthy streak — the restart budget
    /// resets only once this reaches [`SUSTAINED_HEALTHY_WINDOW`]; any failure
    /// aborts the streak.
    healthy_since: Option<Instant>,
}

/// Decision from [`DaemonHealth::gate_restart`] / [`DaemonHealth::gate_launch`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RecoveryGate {
    /// Attempt N is allowed now.
    Allowed(u32),
    /// Backoff between attempts not yet elapsed.
    Backoff,
    /// Thrash halt cooldown in progress.
    Cooldown,
    /// Max consecutive attempts exhausted — auto-recovery just halted.
    Halted,
}

impl DaemonHealth {
    /// Decide whether a daemon restart attempt is allowed.
    fn gate_restart(&mut self, now: Instant) -> RecoveryGate {
        self.restart_budget
            .gate(MAX_RESTART_ATTEMPTS, &RESTART_BACKOFF, HALT_COOLDOWN, now)
    }

    /// Decide whether a Chrome launch attempt is allowed — a separate bounded
    /// budget from the restart one (a closed browser is not a wedged daemon).
    fn gate_launch(&mut self, now: Instant) -> RecoveryGate {
        self.launch_budget
            .gate(MAX_LAUNCH_ATTEMPTS, &LAUNCH_BACKOFF, HALT_COOLDOWN, now)
    }

    /// Apply a health observation. A healthy result opens the sustained-healthy
    /// window ([`SUSTAINED_HEALTHY_WINDOW`]); the restart AND launch budgets
    /// reset only after the window completes, so a transient healthy right after
    /// a restart or launch (the post-recovery verification —
    /// `seed_window = false` — or a single watchdog interval) cannot reopen a
    /// bounded cycle early. Any failure aborts the window.
    fn apply_outcome(&mut self, outcome: ProbeOutcome, now: Instant, seed_window: bool) {
        let healthy = outcome.is_healthy();
        if healthy {
            if self
                .healthy_since
                .is_some_and(|since| now.duration_since(since) >= SUSTAINED_HEALTHY_WINDOW)
            {
                // Sustained health — open a fresh bounded cycle for both budgets.
                self.restart_budget.reset();
                self.launch_budget.reset();
                self.last_cause_warned = None;
            }
            if seed_window && self.healthy_since.is_none() {
                self.healthy_since = Some(now);
            }
            // Any healthy observation supersedes a stale launch record — the
            // relay is back up, so there is nothing honest to report about the
            // last launch. Failure outcomes do NOT clear it (it must survive so
            // the down message stays honest about what happened).
            self.launch_outcome = None;
        } else {
            self.healthy_since = None;
        }
        // A cause change never resets the restart budget — flapping causes (e.g.
        // RelayDown ↔ DaemonWedge) must not evade the attempt halt. Only
        // sustained health (or the cooldown expiry in gate_restart) opens a
        // fresh cycle.
        self.last_failure = outcome.failure();
        self.healthy = Some(healthy);
        self.last_probe = Some(now);
    }
}

static HEALTH: OnceLock<Mutex<DaemonHealth>> = OnceLock::new();
static WAKE: OnceLock<tokio::sync::Notify> = OnceLock::new();

fn health() -> &'static Mutex<DaemonHealth> {
    HEALTH.get_or_init(|| Mutex::new(DaemonHealth::default()))
}

fn wake() -> &'static tokio::sync::Notify {
    WAKE.get_or_init(tokio::sync::Notify::new)
}

/// Record the outcome of a Chrome auto-launch attempt so down messaging stays
/// honest about what the watchdog actually did (survives until health clears it).
fn record_launch_outcome(outcome: ChromeLaunchOutcome) {
    health().lock().unwrap_poison().launch_outcome = Some(outcome);
}

/// Classify a fast CLI failure text into a health cause. Unreachable-tab
/// errors are their own state — the daemon and relay are up, only the
/// session's tab is orphaned, so recovery must NOT run for them. The signature
/// also appears wrapped inside the auto-connect envelope ('Could not drive your
/// Chrome…') and the daemon wrapper ('Auto-launch failed'), so it wins over
/// both. The relay signature is more specific than the daemon wrapper it is
/// wrapped in — both the watchdog and the fail-fast path must agree on the
/// cause.
fn classify_failure_text(msg: &str) -> Option<ProbeFailure> {
    if is_unreachable_tab_error(msg) {
        Some(ProbeFailure::UnreachableTab)
    } else if is_relay_unavailable_error(msg) {
        Some(ProbeFailure::RelayDown)
    } else if is_daemon_unavailable_error(msg) {
        Some(ProbeFailure::DaemonWedge)
    } else {
        None
    }
}

/// Get the platform-appropriate chrome-use binary name.
pub(crate) const fn chrome_bin() -> &'static str {
    if cfg!(target_os = "windows") {
        "chrome-use.exe"
    } else {
        "chrome-use"
    }
}

/// Result of a CLI availability probe — distinguishes definitive absence
/// from transient failures so callers never report "not installed" for a
/// resource-exhaustion or wedged-binary failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum CliStatus {
    /// `chrome-use --version` ran successfully.
    Available,
    /// Binary definitively absent (not on PATH, not in common install
    /// locations, or the resolved binary vanished).
    Missing,
    /// Probe failed — the binary is present but could not be confirmed
    /// working. Structured so user messages distinguish a transient spawn
    /// failure from a deterministic broken-install or wedge.
    Transient(CliProbeFailure),
}

/// Why a CLI probe of a present binary failed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum CliProbeFailure {
    /// Spawn failed (EAGAIN/EMFILE/ENOMEM under process pressure, …) —
    /// temporary; retry rather than standing down.
    Spawn(String),
    /// `--version` ran but exited non-zero — the install is broken.
    BadVersion(String),
    /// The bounded probe timed out — the binary may be wedged.
    Timeout,
}

impl std::fmt::Display for CliProbeFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CliProbeFailure::Spawn(reason) => write!(f, "spawn failed ({reason})"),
            CliProbeFailure::BadVersion(status) => write!(f, "--version check failed ({status})"),
            CliProbeFailure::Timeout => write!(f, "probe timed out"),
        }
    }
}

/// GitHub repo whose releases host the chrome-use binary (single source of truth).
const CHROME_USE_RELEASE_REPO: &str = "leeguooooo/chrome-use";

/// Timeout for a chrome-use release download (archives are ~9 MB).
const CHROME_USE_DOWNLOAD_TIMEOUT: Duration = Duration::from_secs(300);

/// Timeout for resolving the latest chrome-use release tag.
const CHROME_USE_RELEASE_TIMEOUT: Duration = Duration::from_secs(30);

/// Timeout for a chrome-use native-host registration subprocess (`extension
/// install`): a hung registration must not block the background install task
/// indefinitely.
const CHROME_USE_INSTALL_TIMEOUT: Duration = Duration::from_secs(120);

/// Install hint for the definitive not-found case — appended to every
/// user-facing message that names the chrome-use CLI as missing. chrome-use
/// installs itself automatically in the background at startup (the user
/// accepted quiet-install risk), so if it is still missing the quiet install
/// failed and will retry on the next boot.
pub(crate) const CHROME_USE_INSTALL_HINT: &str = "It installs automatically in the background at \
     startup — if it is still missing the quiet install failed; check the logs \
     and it will retry on the next boot.";

/// Resolved absolute path of the chrome-use binary (managed dir first, then
/// PATH, then common install locations), cached after the first probe.
/// Re-resolves only when the cached path vanished or was never found, so a
/// late installation is picked up by the next probe.
static CLI_PATH: OnceLock<Mutex<Option<PathBuf>>> = OnceLock::new();

/// Absolute path of the chrome-use binary, or `None` when definitively not
/// installed. Spawns must go through this (not the bare name) so PATH mutations
/// and non-PATH install locations cannot break them.
pub(crate) fn cli_path() -> Option<PathBuf> {
    let mut cache = CLI_PATH
        .get_or_init(|| Mutex::new(None))
        .lock()
        .unwrap_poison();
    // Same executability predicate as the resolver, so a cached binary that
    // loses its execute bit mid-run is re-resolved (a non-executable path
    // would otherwise pin every probe in a permanent PermissionDenied).
    if let Some(path) = cache.as_ref().filter(|p| crate::util::is_executable(p)) {
        return Some(path.clone());
    }
    let found = find_cli_binary();
    cache.clone_from(&found);
    found
}

/// Clear the cached CLI path so a relocated binary is re-resolved on the next
/// probe — after a first install the binary lands at a fresh managed-dir path
/// that a stale cache would not see.
fn invalidate_cli_path() {
    *CLI_PATH
        .get_or_init(|| Mutex::new(None))
        .lock()
        .unwrap_poison() = None;
}

/// Locate the chrome-use binary: the mahbot-managed install dir first
/// (`<storage root>/bin`, always resolved by
/// `crate::util::managed_bin::storage_bin_dir`), then a PATH
/// lookup, then the common install locations the old curl installer targeted
/// (`~/.local/bin`, `~/.cargo/bin`, `/usr/local/bin`, `/opt/homebrew/bin` —
/// the first two in the installer's order so a fresh curl install wins over a
/// stale cargo one). The managed dir is probed FIRST on every OS (on Windows
/// it is the only reliable mahbot-install probe, since the PATH there may not
/// include it) so the first-install location and the auto-update swap
/// location are always the same path. Home resolution
/// goes through [`crate::util::cargo_bin_dir`] and `directories::UserDirs`
/// (not `$HOME`) so the fallback still works on HOME-less hosts (docker); when
/// `CARGO_HOME` is set the literal `~/.cargo/bin` is probed too
/// (belt-and-suspenders, mirroring the shell module's
/// `extra_shell_path_prefixes`). Candidates must be executable (`execvp` would
/// skip a non-executable PATH entry, so we do too).
fn find_cli_binary() -> Option<PathBuf> {
    let name = chrome_bin();
    if let Some(dir) = crate::util::managed_bin::storage_bin_dir() {
        let candidate = dir.join(name);
        if crate::util::is_executable(&candidate) {
            return Some(candidate);
        }
    }
    if let Some(paths) = std::env::var_os("PATH") {
        for dir in std::env::split_paths(&paths) {
            let candidate = dir.join(name);
            if crate::util::is_executable(&candidate) {
                return Some(candidate);
            }
        }
    }
    if !cfg!(target_os = "windows") {
        let home = directories::UserDirs::new().map(|d| d.home_dir().to_path_buf());
        let literal_cargo_bin = match (std::env::var_os("CARGO_HOME"), home.as_deref()) {
            (Some(cargo_home), Some(h)) if !cargo_home.is_empty() => Some(h.join(".cargo/bin")),
            _ => None,
        };
        for base in [
            home.as_deref().map(|h| h.join(".local/bin")),
            crate::util::cargo_bin_dir(),
            literal_cargo_bin,
            Some(PathBuf::from("/usr/local/bin")),
            Some(PathBuf::from("/opt/homebrew/bin")),
        ]
        .into_iter()
        .flatten()
        {
            let candidate = base.join(name);
            if crate::util::is_executable(&candidate) {
                return Some(candidate);
            }
        }
    }
    None
}

/// Classify a `--version` spawn failure: only a genuinely missing binary
/// (`NotFound`) is definitive absence; every other spawn error (EAGAIN,
/// EMFILE, ENOMEM, …) is a transient failure.
fn classify_spawn_error(e: &std::io::Error) -> CliStatus {
    if e.kind() == std::io::ErrorKind::NotFound {
        CliStatus::Missing
    } else {
        debug!("chrome-use CLI probe spawn failed: {e}");
        CliStatus::Transient(CliProbeFailure::Spawn(e.to_string()))
    }
}

/// Probe the chrome-use CLI: run `--version` via the resolved absolute path,
/// bounded by [`CLI_TIMEOUT`], kill-on-drop, with the no-update-check browser
/// env. Only definitive absence reports [`CliStatus::Missing`]; spawn errors,
/// timeouts, and non-zero exits are [`CliStatus::Transient`].
pub(crate) async fn cli_probe() -> CliStatus {
    let Some(path) = cli_path() else {
        return CliStatus::Missing;
    };
    let mut cmd = Command::new(&path);
    ensure_chrome_env(&mut cmd);
    cmd.arg("--version")
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .kill_on_drop(true);
    let status = match tokio::time::timeout(CLI_TIMEOUT, cmd.status()).await {
        Ok(Ok(status)) => status,
        Ok(Err(e)) => return classify_spawn_error(&e),
        Err(_) => {
            debug!("chrome-use CLI probe timed out");
            return CliStatus::Transient(CliProbeFailure::Timeout);
        }
    };
    if status.success() {
        CliStatus::Available
    } else {
        debug!("chrome-use CLI probe failed: --version exited with {status}");
        CliStatus::Transient(CliProbeFailure::BadVersion(status.to_string()))
    }
}

/// Extract the chrome-use version from `--version` stdout. The banner carries
/// extra lines (bug-report URL etc.), so scan every whitespace token for the
/// first parseable semver rather than assuming a position. Release tags are
/// `v`-prefixed; CLI output is bare — both parse via the shared tag parser.
fn parse_cli_version(stdout: &str) -> Option<semver::Version> {
    stdout
        .split_whitespace()
        .find_map(|t| crate::util::managed_bin::parse_tag_version(t, "v"))
}

/// Release-asset platform tag for chrome-use archives, e.g. `darwin-arm64`
/// or `linux-musl-x64`. `None` on platform/arch combos the vendor does not
/// publish. Testable pure function; [`release_asset_name`] wraps it with
/// the compile-time target triple.
#[must_use]
fn release_asset_platform(os: &str, arch: &str, musl: bool) -> Option<String> {
    let asset = match (os, arch, musl) {
        ("macos", "x86_64", _) => "darwin-x64",
        ("macos", "aarch64", _) => "darwin-arm64",
        ("linux", "x86_64", false) => "linux-x64",
        ("linux", "aarch64", false) => "linux-arm64",
        ("linux", "x86_64", true) => "linux-musl-x64",
        ("linux", "aarch64", true) => "linux-musl-arm64",
        ("windows", "x86_64", _) => "win32-x64",
        _ => return None,
    };
    Some(asset.to_string())
}

/// Asset platform tag for THIS build, or `Err` naming the unsupported
/// platform. Uses the compile-time target triple (`cfg!`) so it is correct
/// regardless of the runtime host; on Linux, musl is detected by the presence
/// of a musl loader in `/lib` (mirrors the vendor installer — no `ldd`).
fn release_asset_name() -> Result<String, String> {
    let (os, arch) = crate::util::managed_bin::host_os_arch()?;
    let musl = os == "linux" && crate::util::managed_bin::linux_host_is_musl();
    release_asset_platform(os, arch, musl)
        .ok_or_else(|| format!("chrome-use has no release asset for {os}-{arch}"))
}

/// Parse the local chrome-use version from `--version` stdout, bounded by
/// [`CLI_TIMEOUT`]. `None` when the CLI is missing, times out, exits non-zero,
/// or its output is not a parseable semver — callers distinguish "not
/// installed" (via [`cli_path`]) from "unparseable version" (proceed assuming
/// outdated).
pub(crate) async fn cli_version() -> Option<semver::Version> {
    let path = cli_path()?;
    let mut cmd = Command::new(&path);
    ensure_chrome_env(&mut cmd);
    cmd.arg("--version")
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .kill_on_drop(true);
    let out = tokio::time::timeout(CLI_TIMEOUT, cmd.output())
        .await
        .ok()?
        .ok()?;
    if !out.status.success() {
        return None;
    }
    parse_cli_version(&String::from_utf8_lossy(&out.stdout))
}

/// The probed-path variant of [`run_cli_bounded_at`], bounded by [`CLI_TIMEOUT`]
/// — a wedged daemon hangs inside the CLI's own ~152 s retry loop, so every call
/// must be bounded.
async fn run_cli_bounded(args: &[&str], session: Option<&str>) -> Option<std::process::Output> {
    let path = cli_path()?;
    run_cli_bounded_at(&path, args, session, CLI_TIMEOUT).await
}

/// A bounded chrome-use CLI call through [`crate::chrome::spawn::spawn_cli`]
/// (shared env, `--json`, optional `--session`) against an already-resolved binary,
/// so a caller that resolves the path itself does not pay for a second probe.
/// `timeout` is the caller's own bound: the shared [`CLI_TIMEOUT`] for everything
/// that must fail fast, a longer one for a call that waits on the CLI's own cleanup.
async fn run_cli_bounded_at(
    path: &Path,
    args: &[&str],
    session: Option<&str>,
    timeout: Duration,
) -> Option<std::process::Output> {
    match spawn_cli(CliSpawn {
        path,
        args,
        session,
        json: true,
        capture_stderr: false,
        timeout: CliTimeout::Bounded(timeout),
        cancel_kills: true,
        input: None,
        chrome_deadline: None,
    })
    .await
    {
        CliRun::Output(out) => Some(out),
        CliRun::SpawnFailure | CliRun::TimedOut => None,
    }
}

/// The probed-path variant of [`run_cli_json_at`], bounded by [`CLI_TIMEOUT`].
async fn run_cli_json_opt(args: &[&str], session: Option<&str>) -> Result<Value, Option<String>> {
    run_cli_bounded(args, session)
        .await
        .as_ref()
        .ok_or(None)
        .and_then(json_outcome)
}

/// [`run_cli_bounded_at`] plus the `--json` envelope contract: `Ok(value)` on
/// success; `Err(Some(msg))` when the CLI answered with a structured error (the
/// message survives for signature detection); `Err(None)` on timeout/spawn/parse
/// failure. The path-and-timeout-taking entry point, for a caller that has resolved
/// the binary itself and knows what its own bound must be.
pub(crate) async fn run_cli_json_at(
    path: &Path,
    args: &[&str],
    session: Option<&str>,
    timeout: Duration,
) -> Result<Value, Option<String>> {
    run_cli_bounded_at(path, args, session, timeout)
        .await
        .as_ref()
        .ok_or(None)
        .and_then(json_outcome)
}

/// One bounded call's envelope verdict: the decoded JSON on a zero exit with
/// `success: true`, else the structured error the CLI reported.
fn json_outcome(out: &std::process::Output) -> Result<Value, Option<String>> {
    let v: Value = serde_json::from_slice(&out.stdout).map_err(|_| None)?;
    let env = ChromeResponse::from_value(&v);
    if !out.status.success() || env.verdict() != Some(true) {
        return Err(env.error.filter(|e| !e.is_empty()));
    }
    Ok(v)
}

/// Non-session variant for daemon-free commands (`status`, `extension
/// status`): errors are dropped — callers treat an unavailable status as
/// healthy (the per-call fail-fast path still catches wedges).
async fn run_cli_json(args: &[&str]) -> Option<Value> {
    run_cli_json_opt(args, None).await.ok()
}

/// Daemon-free service-state snapshot: `status --json` classifies extension /
/// native-host / relay problems without spawning a daemon or tab. Returns a
/// classified failure when the service is unusable; `None` when the status is
/// unavailable (old CLI or broken binary) or it looks healthy — wedge
/// detection then relies entirely on the per-call fail-fast path.
async fn service_state() -> Option<ProbeFailure> {
    let status = run_cli_json(&["status"]).await?;
    classify_service_state(&status).await
}

/// Classify a `status --json` snapshot (see [`service_state`]). Note:
/// pre-1.5.86 CLIs whose `status` lacks extension data fall through to `None`
/// (healthy). On a relay drop, the cause is resolved with deterministic
/// precedence ([`classify_relay_down`]): extension disabled/absent first (no
/// recovery action can fix them), then a browser-running probe, then the
/// transient relay drop.
async fn classify_service_state(status: &Value) -> Option<ProbeFailure> {
    let ext = status.get("data")?.get("extension")?;
    if ext.get("hostInstalled").and_then(Value::as_bool) == Some(false) {
        return Some(ProbeFailure::NotInstalled);
    }
    if ext.get("hostHealthy").and_then(Value::as_bool) == Some(false) {
        return Some(ProbeFailure::HostBroken);
    }
    if ext.get("relayUp").and_then(Value::as_bool) == Some(false) {
        let ext_state = extension_state().await;
        // The browser-running probe is only meaningful when launching could
        // help: an absent/disabled extension cannot be fixed by launching
        // Chrome, so skip the probe and let the classifier pick the cause.
        let chrome = if matches!(ext_state, ExtensionState::Present | ExtensionState::Unknown) {
            chrome_running().await
        } else {
            None
        };
        return Some(classify_relay_down(ext_state, chrome));
    }
    None
}

/// Extension presence from `extension status --json` (daemon-free; reads
/// Chrome's Secure Preferences). Pure so parsing is unit-testable.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ExtensionState {
    Present,
    Disabled,
    Absent,
    Unknown,
}

/// Parse extension presence from a `extension status --json` value. An absent
/// `chromeExtension` (an explicit `null`) means the extension is not installed
/// in Chrome at all — distinct from `NotInstalled` (native host missing) and
/// `Disabled` (installed but disabled). A MISSING `chromeExtension` key on a
/// successful envelope is shape-uncertain (old CLI, or a CLI that omits the key
/// for other reasons) — never claim the unfixable absent cause from it; it
/// fails open through the transient-relay path as `Unknown`. A FAILED status
/// command also yields `Unknown` (see [`extension_state`]).
fn extension_state_from(status: &Value) -> ExtensionState {
    match status.get("data").and_then(|d| d.get("chromeExtension")) {
        // A missing key on a SUCCESSFUL envelope is shape-uncertain (old CLI, or a
        // CLI that omits the key for other reasons) — never claim the unfixable
        // absent cause from it; it fails open through the transient-relay path.
        None => ExtensionState::Unknown,
        // The CLI's absence signal: an explicit null chromeExtension.
        Some(c) if c.is_null() => ExtensionState::Absent,
        Some(c) => {
            if c.get("disableReasons")
                .and_then(Value::as_array)
                .is_some_and(|r| !r.is_empty())
            {
                ExtensionState::Disabled
            } else {
                ExtensionState::Present
            }
        }
    }
}

/// Whether the chrome-use extension is present, disabled, or absent, from
/// `extension status --json`. A FAILED status command (spawn error, timeout,
/// structured CLI error) is never "absent" — unknown fails open to the
/// transient-relay path, since a mere CLI hiccup must not be reported as an
/// uninstalled extension.
async fn extension_state() -> ExtensionState {
    run_cli_json_opt(&["extension", "status"], None)
        .await
        .map_or(ExtensionState::Unknown, |v| extension_state_from(&v))
}

/// Relay-down cause with deterministic precedence: unfixable Chrome-side
/// causes first (no recovery action can fix them), then the browser-running
/// probe, then the transient relay drop. `chrome_running == None` means the
/// probe was inconclusive or not applicable — degrade to RelayDown.
fn classify_relay_down(ext: ExtensionState, chrome_running: Option<bool>) -> ProbeFailure {
    match ext {
        ExtensionState::Disabled => ProbeFailure::ExtensionDisabled,
        ExtensionState::Absent => ProbeFailure::ExtensionAbsent,
        ExtensionState::Present | ExtensionState::Unknown => {
            if chrome_running == Some(false) {
                ProbeFailure::ChromeNotRunning
            } else {
                ProbeFailure::RelayDown
            }
        }
    }
}

/// macOS app process names for Chrome/Chromium-family browsers.
#[cfg(not(target_os = "windows"))]
const CHROME_PROCESS_NAMES: [&str; 6] = [
    "Google Chrome",
    "Chromium",
    "Brave Browser",
    "chrome",
    "chromium",
    "brave",
];
/// Windows image names for the same browsers.
#[cfg(target_os = "windows")]
const WINDOWS_CHROME_PROCESS_NAMES: [&str; 3] = ["chrome.exe", "chromium.exe", "brave.exe"];

/// Whether a Chrome/Chromium-family browser process is running. Unix probes
/// `pgrep -x <ERE alternation>` over the known process names in a single spawn
/// (macOS bundle binaries plus Linux `comm` names); Windows probes `tasklist`
/// image-name filters. Any match → `Some(true)`; all no-match → `Some(false)`;
/// spawn error, other exit code, or timeout → `None` (inconclusive → the
/// classifier degrades to RelayDown). A closed browser is recovered by
/// launching, not by restarting the daemon.
pub(crate) async fn chrome_running() -> Option<bool> {
    #[cfg(not(target_os = "windows"))]
    {
        pgrep_running(&CHROME_PROCESS_NAMES.join("|")).await
    }
    #[cfg(target_os = "windows")]
    {
        for name in WINDOWS_CHROME_PROCESS_NAMES {
            if tasklist_has(name).await? {
                return Some(true);
            }
        }
        Some(false)
    }
}

/// Single `pgrep -x <ERE alternation>` probe: exit 0 → a Chrome/Chromium-family
/// browser process is running, exit 1 → none, any other exit code / spawn error /
/// timeout → inconclusive.
#[cfg(not(target_os = "windows"))]
async fn pgrep_running(pattern: &str) -> Option<bool> {
    let mut cmd = Command::new("pgrep");
    cmd.args(["-x", pattern])
        // Only the exit code matters — a piped-but-undrained stdout kills a
        // matching pgrep with SIGPIPE before it can report its status.
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .kill_on_drop(true);
    let status = tokio::time::timeout(CLI_TIMEOUT, cmd.status())
        .await
        .ok()?
        .ok()?;
    match status.code() {
        Some(0) => Some(true),
        Some(1) => Some(false), // no process matched
        _ => None,
    }
}

/// `tasklist` image-name probe (Windows): CSV output containing the image name
/// → running; empty → no match; invocation failure → inconclusive.
#[cfg(target_os = "windows")]
async fn tasklist_has(name: &str) -> Option<bool> {
    let mut cmd = Command::new("tasklist");
    cmd.args(["/FI", &format!("IMAGENAME eq {name}"), "/NH", "/FO", "CSV"])
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .kill_on_drop(true);
    let out = tokio::time::timeout(CLI_TIMEOUT, cmd.output())
        .await
        .ok()?
        .ok()?;
    if !out.status.success() {
        return None;
    }
    Some(String::from_utf8_lossy(&out.stdout).contains(name))
}

/// Classify daemon health from the daemon-free `status` snapshot. Wedges are
/// invisible to this check by design — a real chrome call that fails with the
/// daemon-unavailable signature marks the daemon unhealthy via [`note_unhealthy`]
/// (fail-fast) and wakes the watchdog, which recovers from that stored cause.
/// A healthy snapshot also drives the extension-skew advisory (single `status`
/// spawn per evaluation).
async fn evaluate_health() -> ProbeOutcome {
    let Some(status) = run_cli_json(&["status"]).await else {
        // Status unavailable (old CLI or broken binary) — treat as healthy;
        // the per-call fail-fast path still catches wedges.
        return ProbeOutcome::Healthy;
    };
    if let Some(failure) = classify_service_state(&status).await {
        return ProbeOutcome::Down(failure);
    }
    advise_extension_skew(&status);
    ProbeOutcome::Healthy
}

/// One tab in a session's tab group, from `tab list --json`. The `active` flag
/// is deliberately not tracked: a fresh daemon pins adopted leftovers exactly
/// like its own scratch, so it cannot tell the two apart (see the pinned
/// chrome-use behaviors below). Identity is `target_id` — the stable CDP id
/// that survives daemon restarts — while `tab_id` (`t<N>`) is the ref the
/// `close` command resolves.
struct SweepTab {
    tab_id: String,
    target_id: String,
}

// chrome-use CLI behaviors this sweep relies on (live-verified against
// 1.5.100; note the installed CLI auto-updates past that version, and that
// ≥1.5.101 idle keeps external tabs alive — the explicit close/stop the sweep
// uses still cleans up, so the verified behaviors below are unchanged):
// - `tab list --session <name>` enumerates only that session's tab group (the
//   relay scopes `Target.getTargets` per announced group, leeguooooo/chrome-use#40). When the
//   session has no daemon the CLI spawns one: an empty group makes it create a
//   fresh scratch tab; a non-empty group makes it ADOPT the existing tabs
//   without marking them created (`created_targets` stays empty).
// - Both the created scratch and adopted leftovers are pinned, so `active: true`
//   does NOT identify the daemon's own tab — the sweep tracks its own scratch
//   by stable `targetId` instead.
// - `close <ref>` closes one tab through the relay; it refuses to close the
//   last tab of a session ("Cannot close the last tab"), so the sweep creates
//   its own scratch first to keep the count ≥ 2 until every listed tab is
//   closed. The daemon discards the closeTarget result, so even a successful
//   JSON response is not proof of closure — only re-enumeration is, and a
//   failed close REAPPEARS in the next same-daemon `tab list` (resync adopts
//   still-open tabs again), which is the convergence loop.
// - `session stop` SIGTERMs the daemon — whose shutdown handler closes its
//   created tabs best-effort through the relay — waits out the daemon's shutdown
//   grace (an upstream chrome-use figure, not a constant of this repo: 8 s on the
//   installed CLI, 1 s before leeguooooo/chrome-use#192), then SIGKILLs. That
//   shutdown close is best-effort and NOT proof of anything. What follows it IS:
//   chrome-use then reconnects to the browser endpoint and reclaims the session's
//   PERSISTED created-tab ownership record under its own 20 s timeout — ≈28 s end
//   to end on the installed CLI, the whole of what one stop may legitimately spend,
//   which is the budget the ended-run release's attempt bound has to clear (this
//   file's `CLI_TIMEOUT` deliberately fails fast instead) — dropping a tab's id only
//   when its close was acknowledged, and exits non-zero while the record still holds
//   anything. So a successful stop proves that every tab the session CREATED is
//   gone, and proves nothing for a tab the session ADOPTED (stop never closes
//   adopted tabs) — which is why the sweep verifies by round-over-round
//   re-enumeration rather than by the stop's own exit code.
//
// Residual limits (accepted): the sweep's scratch tab is about:blank and the
// extension refuses to re-attach `about:` URLs (its `eligible()`/`SKIP_URL`
// filter). An orphan that lost its attach while the daemon kept a stale
// binding (relay blip, kill during an outage) fails every command with the
// unreachable-tab signatures — the sweep logs the 'close it by hand in
// Chrome' signal and keeps retrying; live orphans whose attach survived
// heal automatically. An orphan the extension fully dropped (Chrome
// service-worker restart unmarks ineligible about: tabs and never re-attaches
// them; the relay's group is fed only by attach announcements) is invisible
// to every CLI path: `tab list` succeeds with only the fresh scratch and the
// sweep converges to Clean with no log. That case is undetectable by design —
// no CLI path can enumerate a tab the extension no longer announces; it stays
// in Chrome until closed by hand. Dead-daemon link-enricher orphans are
// similarly not enumerable (their session names are per-message and the
// daemon inventory drops dead pids) — documented residual.
/// Close every tab in a mahbot-owned session's tab group except the sweep's own
/// scratch, verifying closure by round-over-round re-enumeration. Shared by the
/// startup sweep and the link-enricher per-fetch close, which keep to mahbot-owned
/// names — a name that is not one is not ours to touch, so the refusal below is a
/// fail-closed backstop rather than a live path.
pub(crate) async fn sweep_session(name: &str) {
    if !is_mahbot_session_name(name) {
        warn!(
            session = name,
            "tab sweep refused: not a mahbot-owned session (user/default/other-agent sessions are never touched)"
        );
        return;
    }
    // Skip on known service outage: no close is possible while the relay is
    // down, and every CLI call would cost the full step timeout for nothing.
    // Tabs stay until the browser is reachable again (next sweep/startup). The
    // deadline starts before the skip gate so the gate counts against the
    // total budget.
    let deadline = Instant::now() + SWEEP_TOTAL_BUDGET;
    if let Some(failure) = service_state().await {
        debug!(
            session = name,
            ?failure,
            "tab sweep skipped — chrome service unavailable"
        );
        return;
    }
    // The sweep's own scratch tab — the ONE tab it creates via `tab new` and
    // tracks by stable targetId; everything else in the group is a leftover
    // that must be closed. `stopped` marks the round after a daemon stop: the
    // enumeration then spawned a fresh daemon, so a lone tab is provably that
    // daemon's own scratch (clean) unless it is our tracked scratch that
    // survived the stop (close it again — it was adopted, not owned).
    let mut scratch: Option<String> = None;
    let mut stopped = false;
    for _round in 1..=SWEEP_MAX_ROUNDS {
        if Instant::now() >= deadline {
            break;
        }
        let Some(tabs) = session_tab_list(name, deadline).await else {
            return; // warning already emitted by the enumerator
        };
        if tabs.is_empty() {
            // Live daemon whose tabs were all closed externally — nothing to
            // close; stop it so the next round spawns a fresh daemon (which
            // creates its own scratch).
            let _ = stop_session_daemon(name, deadline).await;
            stopped = true;
            scratch = None;
            continue;
        }
        if stopped {
            // Verification round: the previous stop either closed our scratch
            // (the fresh daemon created its own → clean) or failed to (our
            // scratch survives, now adopted → must be closed again).
            if tabs.len() == 1 && scratch.as_deref() != Some(tabs[0].target_id.as_str()) {
                // Clean: the group holds only the fresh daemon's own scratch.
                clear_sweep_warn();
                let _ = stop_session_daemon(name, deadline).await;
                return;
            }
            stopped = false;
            scratch = None; // adopted by the fresh daemon — no longer owned
        }
        if tabs.len() == 1 && scratch.as_deref() == Some(tabs[0].target_id.as_str()) {
            // Only our owned scratch remains — every listed leftover is closed
            // and verified (same-daemon re-enumeration). Stop closes it.
            let _ = stop_session_daemon(name, deadline).await;
            stopped = true;
            continue;
        }
        // Close cycle: ensure an owned scratch exists, then close every other
        // listed tab. Closing our own scratch is refused (last-tab rule) only
        // once all leftovers are gone — handled by the stop branch above.
        if scratch.is_none() {
            let Some(target_id) = session_tab_new_scratch(name, deadline).await else {
                return; // every None path already emitted its SweepWarn
            };
            scratch = Some(target_id);
        }
        for tab in &tabs {
            if tab.target_id == *scratch.as_deref().unwrap_or_default() {
                continue; // never close our own scratch
            }
            if Instant::now() >= deadline {
                break;
            }
            // Per-tab errors are swallowed by the CLI close path — the next
            // round's same-daemon enumeration is the only proof of closure.
            let _ = session_close_tab(name, &tab.tab_id, deadline).await;
        }
    }
    sweep_warn_transition(SweepWarn::Deferred);
}

/// Only mahbot-owned session names may be swept — link-enricher-* and ephemeral
/// `mahbot-chrome-ephemeral-*` CLI sessions (orphan protection). Named
/// `mahbot-chrome-<name>` sessions and user/default/agent-tab sessions are
/// never touched (strict-scope rule). The legacy pre-rename
/// `mahbot-browser-ephemeral-*` prefix still matches so orphans left by older
/// builds don't leak.
pub(crate) fn is_mahbot_session_name(name: &str) -> bool {
    name.starts_with("link-enricher-")
        || name.starts_with(crate::chrome::CLI_EPHEMERAL_PREFIX)
        || name.starts_with("mahbot-browser-ephemeral-")
}

/// Causes the sweep warns about — warn once per cause transition so a
/// persistent orphan does not spam every sweep, and warn again after
/// a healthy sweep cleared the previous cause.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SweepWarn {
    /// Leftover tab the daemon can no longer re-drive (stale binding on an
    /// about:blank tab the extension never re-attaches) — manual intervention
    /// required. Only fires while a command still errors; an orphan the
    /// extension fully dropped is invisible (see the pinned-behaviors note).
    UnreachableTab,
    /// Relay/daemon unreachable mid-sweep; retried next sweep/startup.
    CannotEnumerate,
    /// Budget exhausted without convergence; retried next sweep/startup.
    Deferred,
}

/// Last-cause anti-spam state, global across sessions: a clean sweep in one
/// session clears it for all, so a persistent orphan in another session can
/// re-warn once after that convergence — acceptable tradeoff, no per-session
/// map needed.
static LAST_SWEEP_WARN: OnceLock<Mutex<Option<SweepWarn>>> = OnceLock::new();

fn sweep_warn_transition(cause: SweepWarn) {
    let mut last = LAST_SWEEP_WARN
        .get_or_init(|| Mutex::new(None))
        .lock()
        .unwrap_poison();
    if *last == Some(cause) {
        return;
    }
    *last = Some(cause);
    match cause {
        SweepWarn::UnreachableTab => warn!(
            "tab sweep: a leftover tab is unreachable (the extension lost its debugger attach; \
             about:blank tabs are never re-attached) — close the leftover tab in Chrome to \
             unblock this session; the sweep keeps retrying"
        ),
        SweepWarn::CannotEnumerate => warn!(
            "tab sweep: cannot enumerate session tabs (relay/daemon unreachable or malformed \
             response) — deferring to the next sweep"
        ),
        SweepWarn::Deferred => {
            warn!("tab sweep: group not clean within budget — deferring to the next sweep");
        }
    }
}

fn clear_sweep_warn() {
    *LAST_SWEEP_WARN
        .get_or_init(|| Mutex::new(None))
        .lock()
        .unwrap_poison() = None;
}

/// Map a session-CLI error to its [`SweepWarn`] and return `None` for the
/// caller's `Option<T>` (the error path never yields a value). Generic over
/// the Ok type so both `tab list` (`Vec<SweepTab>`) and `tab new` (`String`)
/// callers compile with the same one-liner; every error emits its warn, so a
/// deferral is never silent.
fn sweep_none_on_cli_error<T>(name: &str, err: Option<&str>) -> Option<T> {
    let msg = err.unwrap_or_default();
    if is_unreachable_tab_error(msg) {
        tracing::debug!(
            session = name,
            error = msg,
            "tab sweep: unreachable-tab detail"
        );
        sweep_warn_transition(SweepWarn::UnreachableTab);
    } else {
        sweep_warn_transition(SweepWarn::CannotEnumerate);
    }
    None
}

/// Bounded `tab list --json` on a session. `None` on timeout, CLI failure, an
/// error response, or a malformed entry (a missing tabId/targetId makes the
/// count unreliable — defer rather than risk a false-clean verdict). Every
/// `None` path emits its [`SweepWarn`], so a deferral is never silent.
async fn session_tab_list(name: &str, deadline: Instant) -> Option<Vec<SweepTab>> {
    if Instant::now() >= deadline {
        sweep_warn_transition(SweepWarn::Deferred);
        return None;
    }
    let v = match run_session_cli_json(&["tab", "list"], name).await {
        Ok(v) => v,
        Err(err) => return sweep_none_on_cli_error(name, err.as_deref()),
    };
    let Some(tabs) = v
        .get("data")
        .and_then(|d| d.get("tabs"))
        .and_then(Value::as_array)
    else {
        sweep_warn_transition(SweepWarn::CannotEnumerate);
        return None;
    };
    let parsed: Option<Vec<SweepTab>> = tabs
        .iter()
        .map(|t| {
            Some(SweepTab {
                tab_id: t.get("tabId")?.as_str()?.to_string(),
                target_id: t.get("targetId")?.as_str()?.to_string(),
            })
        })
        .collect();
    parsed.or_else(|| {
        sweep_warn_transition(SweepWarn::CannotEnumerate);
        None
    })
}

/// Create a scratch tab and return its stable targetId, matched by the `t<N>`
/// ref from the `tab new` response in the next enumeration (same daemon, so
/// refs are stable until a stop). Every `None` path emits its [`SweepWarn`]
/// (or the re-enumeration's `session_tab_list` already did), so callers return
/// without re-warning and never override a more specific cause.
async fn session_tab_new_scratch(name: &str, deadline: Instant) -> Option<String> {
    if Instant::now() >= deadline {
        sweep_warn_transition(SweepWarn::Deferred);
        return None;
    }
    let resp = match run_session_cli_json(&["tab", "new"], name).await {
        Ok(v) => v,
        Err(err) => return sweep_none_on_cli_error(name, err.as_deref()),
    };
    let Some(tab_id) = resp
        .get("data")
        .and_then(|d| d.get("tabId"))
        .and_then(Value::as_str)
        .map(String::from)
    else {
        sweep_warn_transition(SweepWarn::CannotEnumerate);
        return None;
    };
    let after = session_tab_list(name, deadline).await?; // warns on None
    after
        .iter()
        .find(|t| t.tab_id == tab_id)
        .map(|t| t.target_id.clone())
        .or_else(|| {
            sweep_warn_transition(SweepWarn::CannotEnumerate);
            None
        })
}

async fn session_close_tab(name: &str, tab_id: &str, deadline: Instant) -> Option<()> {
    if Instant::now() >= deadline {
        return None;
    }
    run_session_cli_json(&["close", tab_id], name)
        .await
        .ok()
        .map(|_| ())
}

/// Bounded `session stop` — its outcome is deliberately ignored: the sweep
/// proves closure by round-over-round re-enumeration. Skipped when the sweep is
/// already over budget (the daemon idles out on its own and the next sweep
/// retries). The session is named by the helper's `--session` flag alone.
async fn stop_session_daemon(name: &str, deadline: Instant) -> Option<()> {
    if Instant::now() >= deadline {
        return None;
    }
    run_session_cli_json(&["session", "stop"], name)
        .await
        .ok()
        .map(|_| ())
}

/// Session-scoped variant — the structured error message survives for
/// signature detection.
async fn run_session_cli_json(args: &[&str], session: &str) -> Result<Value, Option<String>> {
    run_cli_json_opt(args, Some(session)).await
}

fn set_health(outcome: ProbeOutcome) {
    let mut h = health().lock().unwrap_poison();
    h.apply_outcome(outcome, Instant::now(), true);
}

/// Health update for the verification right after a recovery action (daemon
/// restart or Chrome launch). Healthy here must NOT seed the sustained-healthy
/// window — the window counts consecutive watchdog interval evaluations after
/// recovery, not the immediate verification.
fn set_health_after_recovery(outcome: ProbeOutcome) {
    let mut h = health().lock().unwrap_poison();
    h.apply_outcome(outcome, Instant::now(), false);
}

/// Async availability for call paths: uses a fresh cached evaluation when
/// possible, otherwise re-evaluates the daemon-free status (bounded) and
/// caches the result. A fresh down-result wakes the watchdog so recovery
/// starts without waiting for the next interval.
pub(crate) async fn is_available() -> bool {
    let cached = {
        let h = health().lock().unwrap_poison();
        let ttl = if h.healthy == Some(false) {
            UNHEALTHY_TTL
        } else {
            HEALTH_TTL
        };
        h.last_probe
            .filter(|t| t.elapsed() < ttl)
            .map(|_| h.healthy)
    };
    if let Some(Some(healthy)) = cached {
        return healthy;
    }
    let outcome = evaluate_health().await;
    let healthy = outcome.is_healthy();
    set_health(outcome);
    if !healthy {
        wake().notify_one();
    }
    healthy
}

/// Sync availability for tool advertisement (never evaluates — uses the last
/// known state). Unknown → advertise optimistically; only a confirmed-down
/// evaluation hides the tool.
pub(crate) fn is_advertised() -> bool {
    health().lock().unwrap_poison().healthy != Some(false)
}

/// Mark the daemon unhealthy immediately (fail-fast path) with the cause the
/// error text points to, and wake the watchdog so recovery starts without
/// waiting for the next interval. Unreachable-tab errors never reach this path
/// — the chrome tool's fail-fast guard bails with hand-close guidance first
/// (recovery cannot fix a Chrome-side orphan, so none is attempted).
pub(crate) fn note_unhealthy(error: &str) {
    // Same classification as the watchdog's health evaluation — the two
    // detection paths must agree on the cause.
    set_health(ProbeOutcome::Down(
        classify_failure_text(error).unwrap_or(ProbeFailure::DaemonWedge),
    ));
    wake().notify_one();
}

/// Actionable error shown when the daemon is down. Names the classified cause
/// with its concrete fix, and reflects whether auto-recovery is active or
/// frozen by thrash protection.
pub(crate) fn daemon_down_message() -> String {
    let h = health().lock().unwrap_poison();
    let cause = match h.last_failure {
        Some(ProbeFailure::NotInstalled) => {
            "The chrome-use extension or native host is not installed — the chrome daemon \
             cannot run. Enable the chrome-use extension at chrome://extensions (the CLI \
             re-installs itself in the background at startup); health recovers automatically \
             once it is installed."
        }
        Some(ProbeFailure::HostBroken) => {
            "The chrome-use native host launcher is broken — run `chrome-use doctor`; health \
             recovers automatically once it is fixed."
        }
        Some(ProbeFailure::ExtensionDisabled) => {
            "The chrome-use extension is disabled — enable it at chrome://extensions. Daemon \
             restarts cannot fix a Chrome-side disable; health recovers automatically once \
             it is enabled."
        }
        Some(ProbeFailure::ExtensionAbsent) => {
            "The chrome-use extension is not installed in Chrome — install/enable the ab-connect \
             extension from the Chrome Web Store. Daemon restarts and launches cannot fix an \
             absent extension; health recovers automatically once it is installed."
        }
        Some(ProbeFailure::RelayDown)
            if h.launch_outcome == Some(ChromeLaunchOutcome::Launched) =>
        {
            "The extension relay is down even after Chrome was auto-launched — Chrome is \
             running, but the ab-connect extension is not republishing. If the extension is \
             only installed in a non-default profile, install it in Chrome's default profile."
        }
        Some(ProbeFailure::RelayDown) => {
            "The chrome-use extension relay is down (the extension itself is enabled). \
             Auto-recovery restarts the session daemons and waits for the extension to \
             reconnect."
        }
        Some(ProbeFailure::ChromeNotRunning) => match h.launch_outcome {
            None | Some(ChromeLaunchOutcome::Launched) => "Chrome is not running.",
            Some(ChromeLaunchOutcome::Failed) => {
                "Chrome is not running and the auto-launch attempt failed (binary not found or \
                 could not start) — start Chrome manually."
            }
            Some(ChromeLaunchOutcome::NoDisplay) => {
                "Chrome is not running and this host has no display — start Chrome manually."
            }
        },
        Some(ProbeFailure::UnreachableTab) => {
            "A browser tab the session was driving is unreachable (the extension lost its \
             debugger attach; about:blank tabs are never re-attached) — close the leftover \
             tab in Chrome to unblock the session."
        }
        Some(ProbeFailure::DaemonWedge) | None => "The chrome daemon is down or unresponsive.",
    };
    let recovery = if matches!(h.last_failure, Some(ProbeFailure::ChromeNotRunning)) {
        // ChromeNotRunning has its own launch budget, so a halted RESTART state
        // must not produce restart-halt text here.
        match h.launch_outcome {
            Some(ChromeLaunchOutcome::NoDisplay) => {
                " Auto-recovery is paused for this cause — no launch will be attempted; it \
                 resumes automatically once a display is available."
            }
            _ if h.launch_budget.halted => {
                " Auto-recovery exhausted its launch attempts and is in a 30-minute cooldown \
                 (thrash protection); it will retry after the cooldown — start Chrome manually \
                 if Chrome stays down."
            }
            Some(ChromeLaunchOutcome::Failed) => {
                " Auto-recovery will retry the launch with backoff."
            }
            None | Some(ChromeLaunchOutcome::Launched) => {
                " Auto-recovery will launch Chrome, backing off between attempts — no manual \
                 action is needed."
            }
        }
    } else if h.restart_budget.halted {
        " Auto-recovery exhausted its restart attempts and is in a 30-minute cooldown (thrash \
         protection); it will retry after the cooldown."
    } else if h.last_failure.is_some_and(ProbeFailure::is_unfixable) {
        " Auto-recovery is paused for this cause — no restart will be attempted; it resumes \
         automatically once the underlying issue is resolved."
    } else {
        " Auto-recovery was triggered and will restart it automatically — no manual action is \
         needed (note: the restart resets chrome sessions)."
    };
    format!(
        "{cause}{recovery} While it's down, use web_search, or shell `curl` for page fetches, \
         instead of the chrome tool."
    )
}

/// Bounded post-timeout health evaluation, deciding what a timed-out chrome
/// call means. `status` is daemon-free and by design cannot see a wedged
/// session daemon (wedges are invisible to it), and the mahbot-side per-call
/// bound cuts the CLI off before its own ~152 s retry loop can surface the
/// daemon-unavailable signature — so after a healthy `status`, the session's
/// daemon itself is probed with a trivial bounded command. A second
/// consecutive hang is the wedge signature: mark the daemon unhealthy (wakes
/// the watchdog, whose recovery restarts the session daemon) and return the
/// down message. `None` = healthy — the timeout was a slow call, not the
/// daemon.
pub(crate) async fn health_after_call_timeout(session: &str) -> Option<String> {
    if !is_available().await {
        return Some(daemon_down_message());
    }
    if run_cli_bounded(&["get", "url"], Some(session))
        .await
        .is_none()
    {
        note_unhealthy("chrome-use CLI call timed out twice — daemon unresponsive");
        return Some(daemon_down_message());
    }
    None
}

/// Background watchdog: evaluate daemon health from the daemon-free status,
/// auto-restart with bounded backoff when down, and halt after repeated crashes
/// to avoid a restart loop. Stands down on hosts without the chrome-use CLI
/// (nothing to monitor or restart) — but only after [`CLI_MISSING_THRESHOLD`]
/// consecutive definitive-missing probes, so a transient spawn failure (EAGAIN
/// under process pressure) never takes the watchdog out of service.
///
/// Probe cadence: healthy hosts re-verify CLI presence every [`CLI_RECHECK`]
/// (5 min, no per-interval `--version` spawns); unknown hosts re-probe every
/// [`WATCHDOG_INTERVAL`] (30 s); stood-down hosts re-check at [`CLI_RECHECK`]
/// (5 min) in the steady state, and every [`WATCHDOG_INTERVAL`] while a
/// transient persists — the deliberate price of never standing down on a
/// single transient, bounded by the probe timeout. A transient verdict implies
/// the binary resolved, so it resets the missing streak and re-enables
/// recovery even on a stood-down host (the stand-down premise is stale). A
/// deterministically broken install (`--version` exits non-zero) classifies as
/// transient and thus never stands down, re-probing at the applicable cadence.
pub async fn run_watchdog() {
    let mut cli_present: Option<bool> = None;
    let mut last_cli_check = Instant::now();
    let mut cli_missing: u32 = 0;
    // Last transient probe cause — warn only on change so a persistent
    // transient leaves a trail without spamming the log.
    let mut last_transient: Option<CliProbeFailure> = None;
    // One-time sweep of leaked mahbot-owned session artifacts from crashed runs
    // or older versions (see cleanup_stale_sessions).
    let mut cleaned = false;
    // Whether the last wait ended in an early wake from the fail-fast path —
    // recovery then consumes the stored classification instead of re-evaluating
    // (the daemon-free status cannot see a wedged daemon and would clobber it).
    let mut woken = false;
    loop {
        // How long to wait before the next iteration, and whether the health
        // evaluation is skipped: a CLI-less host cannot run commands, and the
        // status-unavailable-is-healthy fallback would mark its daemon Healthy.
        let mut sleep = WATCHDOG_INTERVAL;
        let mut skip_health = false;
        let cli_due = last_cli_check.elapsed() >= CLI_RECHECK;
        if cli_present != Some(true) || cli_due {
            last_cli_check = Instant::now();
            match cli_probe().await {
                CliStatus::Available => {
                    cli_present = Some(true);
                    cli_missing = 0;
                    last_transient = None;
                }
                CliStatus::Transient(failure) => {
                    // Not definitive absence — the watchdog stays in service.
                    // Healthy hosts re-probe at the CLI_RECHECK gate; unknown
                    // and stood-down hosts re-probe next interval. Warn on
                    // each distinct cause so a persistently wedged-but-present
                    // CLI leaves a trail without spamming the log.
                    if last_transient.as_ref() != Some(&failure) {
                        warn!("chrome-use CLI probe transient: {failure}");
                        last_transient = Some(failure);
                    }
                    cli_missing = 0;
                }
                CliStatus::Missing => {
                    cli_missing += 1;
                    last_transient = None;
                    if cli_missing < CLI_MISSING_THRESHOLD {
                        // First miss — confirm on the next interval before
                        // standing down (and re-probe: the cached verdict is
                        // no longer trustworthy).
                        cli_present = None;
                        skip_health = true;
                    } else {
                        if cli_present != Some(false) {
                            cli_present = Some(false);
                            warn!(
                                "chrome-use CLI not found — chrome daemon watchdog standing down"
                            );
                        }
                        // Re-check rarely on CLI-less hosts so the watchdog
                        // doesn't spawn `--version` every interval; an early
                        // wake re-checks.
                        sleep = CLI_RECHECK;
                        skip_health = true;
                    }
                }
            }
        }
        if !skip_health {
            if !cleaned {
                cleaned = true;
                cleanup_stale_sessions().await;
            }
            // A fail-fast classification from a real call is the freshest signal —
            // recover from it directly (the daemon-free status cannot see a wedged
            // daemon and would clobber the cause). On interval ticks (or a wake
            // without a stored failure), run the daemon-free evaluation and recover
            // from a service-level failure it finds.
            let failure = if woken {
                health().lock().unwrap_poison().last_failure
            } else {
                None
            };
            if let Some(failure) = failure {
                attempt_recovery(failure).await;
            } else {
                let outcome = evaluate_health().await;
                set_health(outcome);
                if let ProbeOutcome::Down(failure) = outcome {
                    attempt_recovery(failure).await;
                }
            }
        }
        // Wait for the next interval or an early wake from the fail-fast path.
        // `woken` resets on every timeout, so a wake that is not consumed
        // before a CLI stand-down is dropped instead of replayed after
        // reinstall.
        let shutdown = crate::shutdown::shutdown_token();
        woken = tokio::select! {
            () = tokio::time::sleep(sleep) => false,
            () = wake().notified() => true,
            () = shutdown.cancelled() => break,
        };
    }
}

// ── Extension-skew advisory ───────────────────────────────────────────
/// Last (expected, live) extension-version pair that was advised on. Log the
/// extension-skew notice only on a transition (pair changed, or re-skewed
/// after an in-sync clear) — mirrors the sweep's anti-spam pattern.
static LAST_EXTENSION_SKEW: OnceLock<Mutex<Option<(String, String)>>> = OnceLock::new();

/// Extension-skew advisory from an already-fetched `status --json` snapshot:
/// the Chrome Web Store extension is NEVER force-updated — the Store
/// auto-updates it in the background — so a `liveVersion` behind the CLI's
/// `expectedVersion` only logs once per skew transition. Older CLIs without
/// these fields skip silently.
fn advise_extension_skew(status: &Value) {
    let ext = status.get("data").and_then(|d| d.get("extension"));
    let (Some(expected), Some(live)) = (
        ext.and_then(|e| e.get("expectedVersion"))
            .and_then(Value::as_str),
        ext.and_then(|e| e.get("liveVersion"))
            .and_then(Value::as_str),
    ) else {
        // Older CLIs without these fields — nothing to advise on.
        return;
    };
    if expected.is_empty() || live.is_empty() {
        return;
    }
    let mut last = LAST_EXTENSION_SKEW
        .get_or_init(|| Mutex::new(None))
        .lock()
        .unwrap_poison();
    if expected == live {
        // In sync — clear the stored skew so a later re-skew re-logs.
        *last = None;
        return;
    }
    if *last == Some((expected.to_string(), live.to_string())) {
        return;
    }
    *last = Some((expected.to_string(), live.to_string()));
    info!(
        "chrome-use browser extension version mismatch: installed {live}, CLI expects {expected} — \
         Chrome updates Web Store extensions automatically in the background; reloading the \
         extension at chrome://extensions (or waiting for the Store auto-update) clears this"
    );
}

/// Download the chrome-use release archive for `tag` for this platform,
/// verify it against the published `.sha256` sidecar (missing/unreadable/
/// mismatching sidecar is a HARD failure), and extract the single binary into
/// a temp dir. Returns `(temp dir, binary path)` — the caller must keep the
/// guard alive until the binary has been moved into place.
async fn download_chrome_use_binary(tag: &str) -> Result<(tempfile::TempDir, PathBuf), String> {
    use crate::util::http::{DownloadSizeCheck, build_download_client, download_verified};

    let platform = release_asset_name()?;
    let asset = format!("chrome-use-{platform}.tar.gz");
    let base = format!("https://github.com/{CHROME_USE_RELEASE_REPO}/releases/download/{tag}");
    let tgz_url = format!("{base}/{asset}");
    let sha_url = format!("{tgz_url}.sha256");

    let client = build_download_client(CHROME_USE_DOWNLOAD_TIMEOUT)
        .map_err(|e| format!("failed to build download client: {e}"))?;

    // Fetch the `.sha256` sidecar with the same client; a missing/unreadable/
    // mismatching sidecar is a hard failure so a tampered or partial release is
    // never installed.
    let sidecar = client
        .get(&sha_url)
        .send()
        .await
        .map_err(|e| format!("failed to fetch sha256 sidecar {sha_url}: {e}"))?;
    if !sidecar.status().is_success() {
        return Err(format!(
            "failed to fetch sha256 sidecar {sha_url}: HTTP {}",
            sidecar.status()
        ));
    }
    let body = sidecar
        .text()
        .await
        .map_err(|e| format!("failed to read sha256 sidecar {sha_url}: {e}"))?;
    let (hash, sidecar_name) =
        crate::util::managed_bin::parse_sha256_sidecar(&body).ok_or_else(|| {
            format!("sha256 sidecar {sha_url} is malformed (no `64-hex-hash  filename` pair)")
        })?;
    // The sidecar names the archive it was published for — a valid hash from a
    // cross-paired sidecar must not verify a different asset.
    if sidecar_name != asset {
        return Err(format!(
            "sha256 sidecar {sha_url} names '{sidecar_name}', expected '{asset}'"
        ));
    }

    let dir = tempfile::tempdir().map_err(|e| format!("failed to create temp dir: {e}"))?;
    let archive_path = dir.path().join("archive.tar.gz");
    download_verified(
        &client,
        &tgz_url,
        &archive_path,
        &hash,
        None,
        DownloadSizeCheck::None,
        |_, _| {},
    )
    .await
    .map_err(|e| format!("failed to download {tgz_url}: {e}"))?;

    let out_path = crate::util::managed_bin::extract_single_file_tar_gz(
        &archive_path,
        dir.path(),
        chrome_bin(),
    )?;
    Ok((dir, out_path))
}

/// First install of chrome-use: download the pinned chrome-use release directly
/// (SHA-256-verified against the published sidecar), place the single binary at
/// the stable managed dir that [`find_cli_binary`] always resolves, then do a
/// one-time native-host registration that never activates managed Chrome mode.
/// Called by [`run_chrome_use_management`] when the CLI is missing (first
/// install only — the updater swaps the binary in place and never re-registers;
/// the user accepted quiet-install risk, so there is no consent gate and no
/// user interaction). `Err` names the failing step and carries truncated
/// stdout/stderr for diagnosis.
pub(crate) async fn install_chrome_use() -> Result<(), String> {
    let tag = crate::util::managed_bin::fetch_latest_tag(
        CHROME_USE_RELEASE_REPO,
        CHROME_USE_RELEASE_TIMEOUT,
    )
    .await?;
    let (_temp, fresh) = download_chrome_use_binary(&tag).await?;

    let dest = crate::util::managed_bin::storage_bin_dir()
        .ok_or_else(|| "managed chrome-use bin dir unavailable (storage root not set)".to_string())?
        .join(chrome_bin());
    let parent = dest
        .parent()
        .ok_or_else(|| format!("invalid chrome-use install path {}", dest.display()))?;
    fs::create_dir_all(parent)
        .map_err(|e| format!("failed to create {}: {e}", parent.display()))?;
    let fresh_install = !dest.exists();
    crate::util::managed_bin::swap_binary_in_place(&fresh, &dest)?;
    // The swap preserves the old dest's mode, so a pre-existing install that
    // lost its executable bit would survive a reinstall unchanged — force the
    // bit back on (bun does the same).
    crate::util::managed_bin::set_executable(&dest)?;

    // The binary landed at the managed dir; clear any cached path so the next
    // probe re-resolves to the stable managed location.
    invalidate_cli_path();

    // User shells resolve the managed binary by bare name; non-fatal, idempotent.
    crate::util::managed_bin::ensure_rc_path_block();

    // Register the native-messaging host using the absolute freshly-downloaded
    // binary (never a stale PATH entry). `--no-profile` is REQUIRED on macOS to
    // avoid chrome-use's default of writing and queueing the
    // `ab-connect.mobileconfig` managed-configuration profile
    // (ExtensionInstallForcelist) that flips Chrome into "managed by your
    // organization" mode; mahbot never creates or re-queues that profile in any
    // flow. Supported since chrome-use v1.5.93; the binary is always freshly
    // downloaded so the flag is always available.
    let mut host = Command::new(&dest);
    host.args(["extension", "install", "--no-profile"]);
    match run_install_step("`chrome-use extension install --no-profile`", host).await {
        Ok(()) => Ok(()),
        Err(e) => {
            // A registration failure must not leave a half-installed state: a
            // freshly created binary is removed again (the next boot's quiet
            // auto-install re-downloads everything). When it replaced a
            // previously working install, the binary stays — the host
            // registration still points at the same absolute path, so the
            // existing setup keeps working.
            if fresh_install {
                let _ = fs::remove_file(&dest);
                invalidate_cli_path();
                Err(format!(
                    "{e}\nThe chrome-use binary was placed at {} but the native-host \
                     registration failed, so it was removed to leave no half-installed state.",
                    dest.display()
                ))
            } else {
                Err(format!(
                    "{e}\nThe chrome-use binary at {} was updated, but the native-host \
                     re-registration failed — the previous registration still references this \
                     path and keeps working.",
                    dest.display()
                ))
            }
        }
    }
}

/// Run one install subprocess bounded by [`CHROME_USE_INSTALL_TIMEOUT`].
async fn run_install_step(label: &str, mut cmd: Command) -> Result<(), String> {
    let out = tokio::time::timeout(CHROME_USE_INSTALL_TIMEOUT, cmd.kill_on_drop(true).output())
        .await
        .map_err(|_| format!("{label} timed out"))?
        .map_err(|e| format!("{label} failed to spawn: {e}"))?;
    if out.status.success() {
        return Ok(());
    }
    Err(format!(
        "{label} failed ({}).\nstdout: {}\nstderr: {}",
        out.status,
        crate::util::truncate(&String::from_utf8_lossy(&out.stdout), 2048),
        crate::util::truncate(&String::from_utf8_lossy(&out.stderr), 2048),
    ))
}

// ── Managed install + once-per-boot auto-update ───────────────────────
/// Spawned one-shot task: silent first install at startup (no consent flow —
/// the user accepted quiet-install risk), then a delayed once-per-boot
/// auto-update of an existing install. All failures are non-fatal (warn and
/// retry next boot); there is no intra-boot retry loop.
pub async fn run_chrome_use_management() {
    if cli_path().is_none() {
        match install_chrome_use().await {
            Ok(()) => {
                info!("chrome-use installed automatically at startup");
                // The fresh install IS the latest release — no update check.
                return;
            }
            Err(e) => {
                warn!(
                    "chrome-use auto-install failed (non-fatal, retried on next boot): {}",
                    crate::util::truncate(&e, 1024)
                );
                // Still no binary — the delayed update check would be a
                // guaranteed no-op (it never first-installs), so end here.
                return;
            }
        }
    }
    // Existing install: once-per-boot update check, delayed so it never
    // competes with service startup.
    tokio::time::sleep(Duration::from_mins(5)).await;
    run_update_check().await;
}

/// Once-per-boot auto-update of an existing chrome-use install. No retry loop
/// (a failed update retries next boot); never first-installs — only
/// [`run_chrome_use_management`] installs a missing CLI. Is skipped when
/// offline. On all platforms the update is a binary-only, checksum-verified
/// release swap in place: the native-messaging launcher and manifests reference
/// the binary by its fixed absolute path and keep working after the swap, so
/// there is no re-registration. After success there is no periodic re-check
/// (once per boot).
async fn run_update_check() {
    if cli_path().is_none() {
        debug!("chrome-use not installed — update check skipped (management only installs)");
        return;
    }
    // Pre-existing installs never went through `install_chrome_use`, so ensure
    // user-shell visibility on every update check (idempotent, non-fatal) —
    // not just on the boots where a swap actually happens.
    crate::util::managed_bin::ensure_rc_path_block();
    let local = cli_version().await;

    // Resolve the latest release tag (follow the releases/latest redirect — no
    // api.github.com rate limit). A single attempt per boot (any failure
    // retries next boot); a non-semver tag gives up immediately (cannot
    // compare). The raw tag string is captured so the later download uses the
    // SAME tag (no re-resolution race).
    let Ok(tag) = crate::util::managed_bin::fetch_latest_tag(
        CHROME_USE_RELEASE_REPO,
        CHROME_USE_RELEASE_TIMEOUT,
    )
    .await
    else {
        debug!("chrome-use auto-update skipped: release check failed (offline?)");
        return;
    };
    let Some(latest) = crate::util::managed_bin::parse_tag_version(&tag, "v") else {
        info!(
            "chrome-use auto-update: latest release tag '{tag}' is not a semver version; giving up"
        );
        return;
    };

    if let Some(local) = local.as_ref()
        && local >= &latest
    {
        debug!("chrome-use is up to date ({local})");
        return;
    }
    let local = local.map_or_else(|| "unknown version".to_string(), |v| v.to_string());
    debug!("chrome-use auto-update: updating {local} → {latest}");

    // The install path is the one the resolver found (the same path identity as
    // the first install — [`find_cli_binary`] always probes the managed dir
    // first). If it vanished, give up for this boot.
    let Some(dest) = cli_path() else {
        debug!("chrome-use auto-update skipped: CLI path vanished");
        return;
    };

    // Binary-only, checksum-verified release swap. The swap helper never leaves
    // a broken install, so on any error the previous binary stays untouched and
    // there is no same-boot retry. The native-messaging launcher/manifests
    // reference the binary by its fixed absolute path and keep working after
    // the swap — no `extension install`, no path invalidation. The failing step
    // is named in the error.
    // The temp-dir guard must be bound OUTSIDE the match: it owns the freshly
    // extracted binary, and dropping it at the end of a match arm would delete
    // the file before the swap runs.
    let (_temp, fresh) = match download_chrome_use_binary(&tag).await {
        Ok(pair) => pair,
        Err(e) => {
            info!(
                "chrome-use auto-update failed: {}",
                crate::util::truncate(&e, 1024)
            );
            return;
        }
    };
    if let Err(e) = crate::util::managed_bin::swap_binary_in_place(&fresh, &dest) {
        info!(
            "chrome-use auto-update failed: {}",
            crate::util::truncate(&e, 1024)
        );
        return;
    }
    // The swap preserves the old dest's mode, so a pre-existing install that
    // lost its executable bit would survive a reinstall unchanged — force the
    // bit back on after every swap (bun does the same).
    if let Err(e) = crate::util::managed_bin::set_executable(&dest) {
        info!(
            "chrome-use auto-update failed: {}",
            crate::util::truncate(&e, 1024)
        );
        return;
    }
    info!("chrome-use auto-updated to {latest} (binary in place)");
}

/// One-time cleanup of stale mahbot-owned chrome-session artifacts at watchdog
/// start: leftover link-enricher sessions get swept so their tab groups don't
/// accumulate. Each sweep is verified (round-over-round convergence) and only
/// ever closes the target session's own tabs — sessions owned by other agents
/// or the user (explicit tabs, `default`, any non-mahbot name) are never
/// touched, and neither are run-owned `agent-tab-*` ones, which are not mahbot
/// names at all (`chrome.rs`'s `AGENT_TAB_PREFIX`). Dead link-enricher orphans stay
/// until the tab is closed by hand — a documented residual limit.
async fn cleanup_stale_sessions() {
    let Some(sessions) = registered_sessions().await else {
        return;
    };
    for name in sessions {
        if is_mahbot_session_name(&name) {
            sweep_session(&name).await;
        }
    }
}

/// Names of currently registered session daemons (from the daemon-free
/// `status --json` snapshot).
async fn registered_sessions() -> Option<Vec<String>> {
    let status = run_cli_json(&["status"]).await?;
    Some(
        status
            .get("data")?
            .get("sessions")?
            .as_array()?
            .iter()
            .filter_map(|s| s.get("name").and_then(Value::as_str).map(String::from))
            .collect(),
    )
}

/// Poll `status --json` (daemon-free) until the extension relay republishes or
/// the budget elapses. The MV3 service worker revives on its keepalive (~30 s).
async fn wait_for_relay(budget: Duration) {
    let deadline = Instant::now() + budget;
    while Instant::now() < deadline {
        if relay_up().await == Some(true) {
            return;
        }
        tokio::time::sleep(Duration::from_secs(2)).await;
    }
}

pub(crate) async fn relay_up() -> Option<bool> {
    let status = run_cli_json(&["status"]).await?;
    status
        .get("data")?
        .get("extension")?
        .get("relayUp")
        .and_then(Value::as_bool)
}

/// Chrome launch flags applied on auto-launch. Deliberately minimal — no
/// daemon/profile/home overrides: the launch inherits the user's real
/// profile/environment, so only flags that suppress first-run friction belong.
const CHROME_LAUNCH_FLAGS: [&str; 3] = [
    "--no-first-run",
    "--no-default-browser-check",
    "--silent-debugger-extension-api",
];

/// Launch the user's real Chrome when [`ProbeFailure::ChromeNotRunning`], within
/// a bounded launch budget separate from daemon restarts. Display-less hosts
/// are unfixable here: paused, no budget consumed. The launch inherits mahbot's
/// real environment (NOT `ensure_chrome_env` — its HOME override and daemon
/// flags must never reach the user's browser) and waits for the relay.
async fn attempt_chrome_launch() {
    if !display_available() {
        record_launch_outcome(ChromeLaunchOutcome::NoDisplay);
        debug!("chrome daemon: headless host — Chrome launch skipped; start Chrome manually");
        return;
    }
    let gate = { health().lock().unwrap_poison().gate_launch(Instant::now()) };
    let RecoveryGate::Allowed(attempt) = gate else {
        log_gate_denied(gate, "chrome launch", MAX_LAUNCH_ATTEMPTS);
        return;
    };
    let Some(binary) = chrome_binary() else {
        record_launch_outcome(ChromeLaunchOutcome::Failed);
        warn!("no Chrome/Chromium binary found — start Chrome manually");
        return;
    };
    if let Err(e) = spawn_chrome_detached(&binary) {
        record_launch_outcome(ChromeLaunchOutcome::Failed);
        warn!(error = %e, "failed to launch Chrome — start Chrome manually");
        return;
    }
    info!(
        attempt,
        max = MAX_LAUNCH_ATTEMPTS,
        "launched the user's Chrome; waiting for the extension relay to come up"
    );
    wait_for_relay(RELAY_REVIVE_WAIT).await;
    let outcome = evaluate_health().await;
    // Verification must not seed the sustained-healthy window (same rationale as
    // the restart path) — the launch budget resets only on sustained health.
    set_health_after_recovery(outcome);
    if outcome.is_healthy() {
        info!("chrome daemon: relay recovered after Chrome launch");
    } else {
        record_launch_outcome(ChromeLaunchOutcome::Launched);
        warn!(
            "Chrome launched but the extension relay is still down — if the ab-connect \
             extension is only installed in a non-default profile, install it in Chrome's \
             default profile"
        );
    }
}

/// Whether a Chrome window can actually appear: Linux needs a display session;
/// macOS/Windows launch is attempted and degrades via the failure path (SSH/
/// service sessions surface there).
pub(crate) fn display_available() -> bool {
    #[cfg(target_os = "linux")]
    {
        std::env::var_os("DISPLAY").is_some() || std::env::var_os("WAYLAND_DISPLAY").is_some()
    }
    #[cfg(not(target_os = "linux"))]
    {
        true
    }
}

/// Resolve the user's real Chrome/Chromium-family binary (standard install
/// locations, mirroring chrome-use's own resolution in spirit). None → the
/// launch fails honestly.
fn chrome_binary() -> Option<PathBuf> {
    #[cfg(target_os = "macos")]
    {
        let home = directories::UserDirs::new().map(|d| d.home_dir().to_path_buf());
        let mut candidates = Vec::new();
        for app in ["Google Chrome", "Chromium", "Brave Browser"] {
            candidates.push(PathBuf::from(format!(
                "/Applications/{app}.app/Contents/MacOS/{app}"
            )));
            if let Some(home) = home.as_deref() {
                candidates.push(home.join(format!("Applications/{app}.app/Contents/MacOS/{app}")));
            }
        }
        candidates
            .into_iter()
            .find(|p| crate::util::is_executable(p))
    }
    #[cfg(target_os = "linux")]
    {
        let names = [
            "google-chrome",
            "google-chrome-stable",
            "chromium",
            "chromium-browser",
            "brave-browser",
            "brave",
        ];
        let mut dirs: Vec<PathBuf> = Vec::new();
        if let Some(paths) = std::env::var_os("PATH") {
            dirs.extend(std::env::split_paths(&paths));
        }
        dirs.extend([
            PathBuf::from("/usr/bin"),
            PathBuf::from("/usr/local/bin"),
            PathBuf::from("/snap/bin"),
        ]);
        for dir in dirs {
            for name in names {
                let candidate = dir.join(name);
                if crate::util::is_executable(&candidate) {
                    return Some(candidate);
                }
            }
        }
        None
    }
    #[cfg(target_os = "windows")]
    {
        let mut candidates = Vec::new();
        for base in ["ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA"] {
            let Some(base) = std::env::var_os(base) else {
                continue;
            };
            let base = PathBuf::from(base);
            for rel in [
                Path::new("Google/Chrome/Application/chrome.exe"),
                Path::new("Chromium/Application/chrome.exe"),
                Path::new("BraveSoftware/Brave-Browser/Application/brave.exe"),
            ] {
                candidates.push(base.join(rel));
            }
        }
        candidates
            .into_iter()
            .find(|p| crate::util::is_executable(p))
    }
    #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
    {
        None
    }
}

/// Spawn Chrome detached from mahbot: own process group on Unix (terminal
/// signals to mahbot's group must not kill the browser), detached/no-window
/// creation flags on Windows (mirrors self_update.rs:1428-1434). The child is
/// deliberately dropped without wait or kill_on_drop — Chrome must survive
/// mahbot restarts.
fn spawn_chrome_detached(binary: &Path) -> std::io::Result<()> {
    let mut cmd = std::process::Command::new(binary);
    cmd.args(CHROME_LAUNCH_FLAGS)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null());
    // Inherit the real env — do NOT touch HOME or add AGENT_BROWSER_*/CHROMIUM_FLAGS.
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        cmd.process_group(0);
    }
    #[cfg(windows)]
    {
        use std::os::windows::process::CommandExt;
        const DETACHED_PROCESS: u32 = 0x0000_0008;
        const CREATE_NO_WINDOW: u32 = 0x0800_0000;
        cmd.creation_flags(DETACHED_PROCESS | CREATE_NO_WINDOW);
    }
    cmd.spawn().map(|_| ())
}

/// Warn once per cause transition — an ongoing failure does not spam every
/// watchdog interval, but the same cause warns again after a healthy spell.
fn warn_transition(failure: ProbeFailure) {
    let mut h = health().lock().unwrap_poison();
    if h.last_cause_warned == Some(failure) {
        return;
    }
    h.last_cause_warned = Some(failure);
    match failure {
        ProbeFailure::NotInstalled => warn!(
            "chrome-use extension or native host is not installed — the browser \
             daemon cannot run. Enable the chrome-use extension at \
             chrome://extensions (the CLI re-installs itself in the background at \
             startup). Auto-recovery paused until it is installed."
        ),
        ProbeFailure::HostBroken => warn!(
            "chrome-use native host launcher is broken — run `chrome-use doctor`. \
             Auto-recovery paused until it is fixed."
        ),
        ProbeFailure::ExtensionDisabled => warn!(
            "chrome-use extension is disabled — enable it at chrome://extensions. \
             Daemon restarts cannot fix a Chrome-side disable; auto-recovery paused \
             until it is enabled."
        ),
        ProbeFailure::ExtensionAbsent => warn!(
            "chrome-use extension is not installed in Chrome — install/enable the \
             ab-connect extension from the Chrome Web Store. Auto-recovery paused \
             until it is installed."
        ),
        ProbeFailure::RelayDown => warn!(
            "chrome-use extension relay is down (the extension is enabled) — waiting \
             for the extension to reconnect and restarting session daemons to clear \
             stale relay bindings."
        ),
        ProbeFailure::ChromeNotRunning => {
            // Must match what attempt_recovery will actually do on this host — a
            // headless machine pauses recovery instead of launching.
            if !display_available() {
                warn!(
                    "Chrome is not running and no display is available (headless host) — \
                       start Chrome manually; auto-recovery paused."
                );
            } else if h.launch_budget.halted {
                warn!(
                    "Chrome is not running — launch attempts are paused in a thrash-protection \
                     cooldown; start Chrome manually."
                );
            } else {
                warn!(
                    "Chrome is not running — auto-recovery will launch it (bounded launch budget)."
                );
            }
        }
        ProbeFailure::UnreachableTab => warn!(
            "a browser tab the session was driving is unreachable (the extension lost its \
             debugger attach; about:blank tabs are never re-attached) — close the leftover \
             tab in Chrome to unblock the session"
        ),
        ProbeFailure::DaemonWedge => {
            warn!("chrome daemon is unresponsive — restarting it (bounded backoff).");
        }
    }
}

/// Log a blocked recovery-gate decision — the gated action does not run.
/// `noun` names the gated action ("restart" / "chrome launch").
fn log_gate_denied(gate: RecoveryGate, noun: &str, max: u32) {
    match gate {
        RecoveryGate::Halted => error!(
            attempts = max,
            "chrome daemon: {max} consecutive failed {noun} attempts; \
             auto-recovery halted for 30 min (thrash protection)"
        ),
        RecoveryGate::Backoff => {
            debug!("chrome daemon: still down; waiting out {noun} backoff");
        }
        RecoveryGate::Cooldown => {
            debug!("chrome daemon: still down; {noun} cooldown in progress (thrash protection)");
        }
        RecoveryGate::Allowed(_) => unreachable!(),
    }
}

/// Bounded auto-recovery. `ChromeNotRunning` funnels into a bounded Chrome
/// launch — never a daemon restart, never the restart budget (a closed browser
/// cannot be fixed by restarting the daemon). Restart causes restart session
/// daemons with backoff between attempts and a halt after MAX_RESTART_ATTEMPTS
/// failures. Causes that a restart cannot fix — extension absent/disabled, not
/// installed, broken host, unreachable tab — are reported with their concrete
/// fix and never consume restart attempts. A transient relay drop is waited out
/// first and consumes no attempt if it self-heals.
async fn attempt_recovery(mut failure: ProbeFailure) {
    warn_transition(failure);
    // Unfixable causes stop here — they never consume restart attempts.
    if failure.is_unfixable() {
        return;
    }
    // ChromeNotRunning is handled by a bounded launch, BEFORE the restart
    // throttle check: the launch budget is independent of restart backoff/halt,
    // so a halted restart state must not block launching the user's browser.
    if failure == ProbeFailure::ChromeNotRunning {
        attempt_chrome_launch().await;
        return;
    }
    // While a recovery timer is pending, the timer IS the wait — don't poll the
    // relay for up to RELAY_REVIVE_WAIT on top of it. The next watchdog cycle
    // re-evaluates and re-enters recovery.
    let now = Instant::now();
    let throttled = health()
        .lock()
        .unwrap_poison()
        .restart_budget
        .is_waiting(now);
    if throttled {
        return;
    }
    // A transient relay drop is waited out before any session-disrupting
    // restart: the MV3 worker republishes on its keepalive (~30 s). A drop
    // that self-heals consumes no restart attempt.
    if failure == ProbeFailure::RelayDown {
        wait_for_relay(RELAY_REVIVE_WAIT).await;
        let outcome = evaluate_health().await;
        set_health(outcome);
        match outcome {
            ProbeOutcome::Healthy => {
                info!("chrome daemon: relay recovered without a restart");
                return;
            }
            ProbeOutcome::Down(f) => {
                // Re-classified (e.g. now a wedge or a closed browser) — re-warn
                // and re-gate below.
                warn_transition(f);
                if f.is_unfixable() {
                    return;
                }
                if f == ProbeFailure::ChromeNotRunning {
                    attempt_chrome_launch().await;
                    return;
                }
                failure = f;
            }
        }
    }

    // Decide whether a restart is allowed, and update the attempt bookkeeping,
    // entirely within a scoped lock so the MutexGuard is never held across
    // an await point.
    let gate = {
        let mut h = health().lock().unwrap_poison();
        h.gate_restart(Instant::now())
    };
    let RecoveryGate::Allowed(attempt) = gate else {
        log_gate_denied(gate, "restart", MAX_RESTART_ATTEMPTS);
        return;
    };

    info!(
        attempt,
        max = MAX_RESTART_ATTEMPTS,
        "chrome daemon: attempting auto-recovery"
    );
    // Restart session daemons (session-less; closes their tabs, relay survives).
    // No `reconnect` — it can cold-restart the user's Chrome or open the Web
    // Store; a persistent relay drop self-heals on the extension's keepalive.
    let _ = run_cli(&["daemon", "restart"]).await;
    if failure == ProbeFailure::RelayDown {
        wait_for_relay(RELAY_REVIVE_WAIT).await;
    }

    let outcome = evaluate_health().await;
    // Post-restart verification must not seed the sustained-healthy window —
    // the restart budget resets only after consecutive watchdog intervals of
    // genuine health, so a run that keeps failing cannot reopen a fresh cycle.
    set_health_after_recovery(outcome);
    if outcome.is_healthy() {
        info!("chrome daemon: recovered after restart");
    } else {
        warn!(
            attempt,
            "chrome daemon: restart attempt did not restore health"
        );
    }
}

async fn run_cli(args: &[&str]) -> bool {
    let Some(path) = cli_path() else {
        return false;
    };
    let mut cmd = Command::new(path);
    ensure_chrome_env(&mut cmd);
    cmd.args(args)
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null());
    cmd.kill_on_drop(true);
    tokio::time::timeout(Duration::from_mins(1), cmd.status())
        .await
        .is_ok_and(|r| r.is_ok_and(|st| st.success()))
}

/// Test-only lock serializing tests that mutate the global daemon health
/// state (cargo runs tests in parallel threads).
#[cfg(test)]
pub(crate) async fn with_health_test_lock() -> tokio::sync::MutexGuard<'static, ()> {
    static LOCK: OnceLock<tokio::sync::Mutex<()>> = OnceLock::new();
    LOCK.get_or_init(|| tokio::sync::Mutex::new(()))
        .lock()
        .await
}

/// Test-only: restore the global health singleton to its pristine (unknown)
/// state so mutating tests don't leak state into later readers (e.g.
/// `Agent::new` filtering tools via `is_advertised`).
#[cfg(test)]
pub(crate) fn reset_health() {
    *health().lock().unwrap_poison() = DaemonHealth::default();
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::chrome::contract::is_daemon_unavailable_code;

    #[tokio::test]
    async fn advertisement_and_availability_reflect_daemon_state() {
        let _guard = with_health_test_lock().await;
        // Dead-daemon fixture: confirmed-down → not advertised, and the cached
        // result fails fast without re-probing.
        set_health(ProbeOutcome::Down(ProbeFailure::DaemonWedge));
        assert!(!is_advertised());
        assert!(!is_available().await);
        // Recovered: fresh healthy state → advertised and available.
        set_health(ProbeOutcome::Healthy);
        assert!(is_advertised());
        assert!(is_available().await);
        // Unknown (fresh boot) → advertised optimistically.
        reset_health();
        assert!(is_advertised());
    }

    #[tokio::test]
    async fn daemon_down_message_reflects_launch_state() {
        let _guard = with_health_test_lock().await;
        // Each sub-case starts from the pristine (unknown) state so the launch
        // outcome recorded in one case never leaks into the next.
        reset_health();

        // Plain relay drop — no launch was attempted, so the auto-launch caveat
        // must not leak into the message (it names the relay and the restart).
        set_health(ProbeOutcome::Down(ProbeFailure::RelayDown));
        let msg = daemon_down_message();
        assert!(msg.contains("relay is down"));
        assert!(!msg.contains("auto-launched"));

        // Relay still down after a successful auto-launch — the durable caveat
        // (non-default profile) surfaces instead of the plain relay-drop text.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::RelayDown));
        record_launch_outcome(ChromeLaunchOutcome::Launched);
        let msg = daemon_down_message();
        assert!(msg.contains("even after Chrome was auto-launched"));
        assert!(msg.contains("non-default profile"));

        // Chrome not running with no recorded launch — the tail promises a
        // launch, honest whether it fires this cycle or after backoff.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::ChromeNotRunning));
        let msg = daemon_down_message();
        assert!(msg.contains("Chrome is not running."));
        assert!(msg.contains("will launch Chrome"));

        // Chrome not running, last launch failed — the failed-attempt cause and
        // the backoff retry tail both appear (the launch budget is not halted).
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::ChromeNotRunning));
        record_launch_outcome(ChromeLaunchOutcome::Failed);
        let msg = daemon_down_message();
        assert!(msg.contains("auto-launch attempt failed"));
        assert!(msg.contains("start Chrome manually"));
        assert!(msg.contains("retry the launch with backoff"));

        // Same failed launch but the budget is halted (thrash protection) — the
        // cooldown text supersedes the backoff retry promise.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::ChromeNotRunning));
        record_launch_outcome(ChromeLaunchOutcome::Failed);
        health().lock().unwrap_poison().launch_budget.halted = true;
        let msg = daemon_down_message();
        assert!(msg.contains("exhausted its launch attempts"));
        assert!(!msg.contains("retry the launch with backoff"));

        // Chrome not running because there is no display — recovery is paused
        // for this cause instead of spending the launch budget.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::ChromeNotRunning));
        record_launch_outcome(ChromeLaunchOutcome::NoDisplay);
        let msg = daemon_down_message();
        assert!(msg.contains("no display"));
        assert!(msg.contains("paused for this cause"));

        // Absent extension — the Web Store fix and the paused recovery tail.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::ExtensionAbsent));
        let msg = daemon_down_message();
        assert!(msg.contains("Chrome Web Store"));
        assert!(msg.contains("no restart will be attempted"));

        // Wedged daemon — the generic down text plus the restart tail.
        reset_health();
        set_health(ProbeOutcome::Down(ProbeFailure::DaemonWedge));
        let msg = daemon_down_message();
        assert!(msg.contains("down or unresponsive"));
        assert!(msg.contains("restart it automatically"));
        // Leave the singleton pristine for sibling health tests.
        reset_health();
    }

    #[test]
    fn sustained_health_resets_restart_attempts() {
        let now = Instant::now();
        let mut h = DaemonHealth {
            restart_budget: AttemptBudget {
                attempts: 2,
                next_at: Some(now),
                halted: true,
                halted_until: Some(now),
            },
            ..DaemonHealth::default()
        };
        // A transient healthy result (e.g. the post-restart verification probe)
        // must not reset the budget — a runaway cycle would otherwise reopen a
        // fresh bounded cycle on every restart.
        h.apply_outcome(ProbeOutcome::Healthy, now, false);
        assert_eq!(h.restart_budget.attempts, 2);
        assert!(h.restart_budget.halted);
        // The first watchdog healthy seeds the sustained-healthy window…
        h.apply_outcome(ProbeOutcome::Healthy, now + WATCHDOG_INTERVAL, true);
        assert_eq!(h.restart_budget.attempts, 2);
        assert!(h.healthy_since.is_some());
        // …but a second healthy before the window elapses still does not reset.
        h.apply_outcome(ProbeOutcome::Healthy, now + WATCHDOG_INTERVAL * 2, true);
        assert_eq!(h.restart_budget.attempts, 2);
        assert!(h.restart_budget.halted);
        // Only sustained health across the window opens a fresh bounded cycle.
        h.apply_outcome(ProbeOutcome::Healthy, now + WATCHDOG_INTERVAL * 3, true);
        assert_eq!(h.restart_budget.attempts, 0);
        assert_eq!(h.restart_budget.next_at, None);
        assert!(!h.restart_budget.halted);
        assert!(h.restart_budget.halted_until.is_none());
        assert_eq!(h.last_failure, None);
    }

    #[test]
    fn cause_flapping_and_transient_health_do_not_reset_restart_budget() {
        let now = Instant::now();
        let mut h = DaemonHealth {
            restart_budget: AttemptBudget {
                attempts: 2,
                next_at: Some(now),
                ..AttemptBudget::default()
            },
            last_failure: Some(ProbeFailure::DaemonWedge),
            ..DaemonHealth::default()
        };
        // A cause flip (wedge → relay-down) must NOT reset the budget —
        // alternating causes must not evade the 3-attempt halt.
        h.apply_outcome(ProbeOutcome::Down(ProbeFailure::RelayDown), now, true);
        assert_eq!(h.last_failure, Some(ProbeFailure::RelayDown));
        assert_eq!(h.restart_budget.attempts, 2);
        assert!(h.restart_budget.next_at.is_some());
        // Flapping back and forth accumulates — never resets.
        h.apply_outcome(ProbeOutcome::Down(ProbeFailure::DaemonWedge), now, true);
        h.apply_outcome(ProbeOutcome::Down(ProbeFailure::RelayDown), now, true);
        assert_eq!(h.last_failure, Some(ProbeFailure::RelayDown));
        assert_eq!(h.restart_budget.attempts, 2);
        // A transient healthy result does not reset either — only sustained
        // health across the window opens a fresh bounded cycle.
        h.apply_outcome(ProbeOutcome::Healthy, now, true);
        assert_eq!(h.restart_budget.attempts, 2);
        assert!(h.restart_budget.next_at.is_some());
        h.apply_outcome(ProbeOutcome::Healthy, now + SUSTAINED_HEALTHY_WINDOW, true);
        assert_eq!(h.last_failure, None);
        assert_eq!(h.restart_budget.attempts, 0);
        assert_eq!(h.restart_budget.next_at, None);
        assert!(!h.restart_budget.halted);
    }

    #[test]
    fn gate_honors_backoff_before_halt() {
        let now = Instant::now();
        let mut h = DaemonHealth::default();
        assert_eq!(h.gate_restart(now), RecoveryGate::Allowed(1));
        // 30s backoff before attempt 2.
        assert_eq!(h.gate_restart(now), RecoveryGate::Backoff);
        assert_eq!(
            h.gate_restart(now + RESTART_BACKOFF[0]),
            RecoveryGate::Allowed(2)
        );
        // 2min backoff before attempt 3.
        let t2 = now + RESTART_BACKOFF[0] + RESTART_BACKOFF[1];
        assert_eq!(h.gate_restart(t2), RecoveryGate::Allowed(3));
        // The final 10-min grace is honored before the halt fires.
        assert_eq!(h.gate_restart(t2), RecoveryGate::Backoff);
        let t3 = t2 + RESTART_BACKOFF[2];
        assert_eq!(h.gate_restart(t3), RecoveryGate::Halted);
        assert!(h.restart_budget.halted);
        assert_eq!(h.gate_restart(t3), RecoveryGate::Cooldown);
        // After the cooldown a fresh bounded cycle starts.
        assert_eq!(h.gate_restart(t3 + HALT_COOLDOWN), RecoveryGate::Allowed(1));
        assert_eq!(h.restart_budget.attempts, 1);
        assert!(!h.restart_budget.halted);
    }

    #[test]
    fn relay_down_classification_precedence() {
        // Disabled wins regardless of whether Chrome is running.
        assert_eq!(
            classify_relay_down(ExtensionState::Disabled, Some(true)),
            ProbeFailure::ExtensionDisabled
        );
        assert_eq!(
            classify_relay_down(ExtensionState::Disabled, Some(false)),
            ProbeFailure::ExtensionDisabled
        );
        assert_eq!(
            classify_relay_down(ExtensionState::Disabled, None),
            ProbeFailure::ExtensionDisabled
        );
        // Absent beats ChromeNotRunning — launching can't fix an uninstalled extension.
        assert_eq!(
            classify_relay_down(ExtensionState::Absent, Some(false)),
            ProbeFailure::ExtensionAbsent
        );
        assert_eq!(
            classify_relay_down(ExtensionState::Absent, None),
            ProbeFailure::ExtensionAbsent
        );
        // Present + no Chrome running → ChromeNotRunning.
        assert_eq!(
            classify_relay_down(ExtensionState::Present, Some(false)),
            ProbeFailure::ChromeNotRunning
        );
        // Present + Chrome running (or an inconclusive probe) → transient relay drop.
        assert_eq!(
            classify_relay_down(ExtensionState::Present, Some(true)),
            ProbeFailure::RelayDown
        );
        assert_eq!(
            classify_relay_down(ExtensionState::Present, None),
            ProbeFailure::RelayDown
        );
        // Unknown fails open to the probe; only an explicit no-Chrome proves not running.
        assert_eq!(
            classify_relay_down(ExtensionState::Unknown, Some(false)),
            ProbeFailure::ChromeNotRunning
        );
        assert_eq!(
            classify_relay_down(ExtensionState::Unknown, None),
            ProbeFailure::RelayDown
        );
        // ChromeNotRunning is recoverable (launch), ExtensionAbsent is not.
        assert!(!ProbeFailure::ChromeNotRunning.is_unfixable());
        assert!(ProbeFailure::ExtensionAbsent.is_unfixable());
    }

    #[test]
    fn extension_state_parsing() {
        // No `data` at all, or no `chromeExtension` within it → shape-uncertain,
        // never the unfixable absent cause (fails open as unknown).
        assert_eq!(
            extension_state_from(&serde_json::json!({})),
            ExtensionState::Unknown
        );
        assert_eq!(
            extension_state_from(&serde_json::json!({ "data": {} })),
            ExtensionState::Unknown
        );
        // Explicit null → absent (the CLI reports the extension as not present).
        assert_eq!(
            extension_state_from(&serde_json::json!({ "data": { "chromeExtension": null } })),
            ExtensionState::Absent
        );
        // Present with an empty disableReasons, or with no disableReasons at all.
        assert_eq!(
            extension_state_from(&serde_json::json!({
                "data": { "chromeExtension": { "disableReasons": [] } }
            })),
            ExtensionState::Present
        );
        assert_eq!(
            extension_state_from(&serde_json::json!({
                "data": { "chromeExtension": { "enabled": true } }
            })),
            ExtensionState::Present
        );
        // Disabled when disableReasons is non-empty.
        assert_eq!(
            extension_state_from(&serde_json::json!({
                "data": { "chromeExtension": { "disableReasons": ["user"] } }
            })),
            ExtensionState::Disabled
        );
    }

    #[test]
    fn launch_budget_is_independent_of_restart_budget() {
        let now = Instant::now();
        // A halted/exhausted RESTART budget must NOT block a launch — the two
        // bounded cycles are independent.
        let mut h = DaemonHealth {
            restart_budget: AttemptBudget {
                attempts: MAX_RESTART_ATTEMPTS,
                halted: true,
                halted_until: Some(now),
                ..AttemptBudget::default()
            },
            ..DaemonHealth::default()
        };
        assert!(matches!(h.gate_launch(now), RecoveryGate::Allowed(_)));
        assert_eq!(h.launch_budget.attempts, 1);
        // An exhausted LAUNCH budget still leaves the restart gate open.
        let mut h2 = DaemonHealth {
            launch_budget: AttemptBudget {
                attempts: MAX_LAUNCH_ATTEMPTS,
                ..AttemptBudget::default()
            },
            ..DaemonHealth::default()
        };
        assert!(!matches!(h2.gate_launch(now), RecoveryGate::Allowed(_)));
        assert!(matches!(h2.gate_restart(now), RecoveryGate::Allowed(_)));
        // Sustained health resets both budgets and clears a recorded launch
        // outcome (a pending Failed launch must not survive recovery).
        let mut h3 = DaemonHealth {
            restart_budget: AttemptBudget {
                attempts: 2,
                next_at: Some(now),
                halted: true,
                halted_until: Some(now),
            },
            launch_budget: AttemptBudget {
                attempts: 2,
                next_at: Some(now),
                halted: true,
                halted_until: Some(now),
            },
            launch_outcome: Some(ChromeLaunchOutcome::Failed),
            ..DaemonHealth::default()
        };
        // The first healthy seeds the sustained-healthy window but does not yet
        // reset either budget; a healthy observation clears a stale launch record.
        h3.apply_outcome(ProbeOutcome::Healthy, now + WATCHDOG_INTERVAL, true);
        assert_eq!(h3.restart_budget.attempts, 2);
        assert_eq!(h3.launch_budget.attempts, 2);
        assert!(h3.restart_budget.halted);
        assert!(h3.launch_budget.halted);
        assert_eq!(h3.launch_outcome, None);
        // A healthy across the sustained window opens fresh bounded cycles.
        h3.apply_outcome(ProbeOutcome::Healthy, now + WATCHDOG_INTERVAL * 3, true);
        assert_eq!(h3.restart_budget.attempts, 0);
        assert_eq!(h3.launch_budget.attempts, 0);
        assert!(!h3.restart_budget.halted);
        assert!(!h3.launch_budget.halted);
    }

    #[test]
    fn daemon_unavailable_error_signature_detected() {
        for msg in [
            "Failed to read: Resource temporarily unavailable (os error 35) (after 5 retries - daemon may be busy or unresponsive)",
            "Failed to connect: No such file or directory (os error 2) (after 5 retries - daemon may be busy or unresponsive)",
            "session unresponsive: no response within 45s",
            "Daemon failed to start (socket: /tmp/x.sock)",
            // 1.5.8x-era texts.
            "session unresponsive: the stuck '__mahbot_probe' daemon was stopped automatically",
            "Failed to connect: the daemon endpoint for session '__mahbot_probe' disappeared (/tmp/x.sock).",
            "CDP session is unresponsive after attaching (Connection reset).",
            "Auto-launch failed: Could not drive your Chrome through the ab-connect extension.",
        ] {
            assert!(is_daemon_unavailable_error(msg), "should detect: {msg}");
        }
        for msg in [
            "chrome-use error: Element not found",
            "chrome-use error: Evaluation error: ReferenceError",
            "chrome-use error: Navigation failed",
            // Page-level navigation failure — not a daemon socket problem.
            "Failed to connect to example.com: Connection timed out",
        ] {
            assert!(
                !is_daemon_unavailable_error(msg),
                "should NOT detect: {msg}"
            );
        }
    }

    #[test]
    fn relay_unavailable_signature_detected() {
        for msg in [
            "The chrome-use extension is installed, but its relay isn't connected.",
            "Could not drive your Chrome through the ab-connect extension.",
            "Chrome relay dropped — reconnecting…",
        ] {
            assert!(is_relay_unavailable_error(msg), "should detect: {msg}");
        }
        for msg in [
            "chrome-use error: Element not found",
            "Failed to read: Resource temporarily unavailable (os error 35)",
        ] {
            assert!(!is_relay_unavailable_error(msg), "should NOT detect: {msg}");
        }
    }

    #[test]
    fn daemon_unavailable_code_detected() {
        assert!(is_daemon_unavailable_code(Some("browser_not_launched")));
        // Page-level failures share the coarse `connection_failed` code with
        // daemon-socket problems — the code alone must not fail-fast the
        // daemon path (the message-text matcher disambiguates).
        assert!(!is_daemon_unavailable_code(Some("connection_failed")));
        assert!(!is_daemon_unavailable_code(Some("timeout")));
        assert!(!is_daemon_unavailable_code(Some("element_not_found")));
        assert!(!is_daemon_unavailable_code(None));
    }

    #[test]
    fn failure_text_classification_is_shared_between_detection_paths() {
        // The captured combined error (stale tab wrapped in the auto-connect
        // envelope AND the daemon wrapper) classifies as unreachable-tab, NOT
        // relay-down or wedge — recovery must not fire for an orphaned tab on
        // an otherwise-healthy relay.
        assert_eq!(
            classify_failure_text(
                "Auto-launch failed: Could not drive your Chrome through the ab-connect \
                 extension. The tab this session was driving can no longer be resolved (it \
                 was closed, or a flaky relay dropped it)"
            ),
            Some(ProbeFailure::UnreachableTab)
        );
        // Auto-connect failure alone names the relay as the cause (its body
        // points at `chrome-use extension connect`) — the relay signature wins
        // over the daemon wrapper it is wrapped in, in both the watchdog and
        // fail-fast paths, so they never disagree on the cause.
        assert_eq!(
            classify_failure_text(
                "Auto-launch failed: Could not drive your Chrome through the ab-connect extension."
            ),
            Some(ProbeFailure::RelayDown)
        );
        assert_eq!(
            classify_failure_text(
                "Failed to connect: the daemon endpoint for session '__mahbot_probe' \
                 disappeared (/tmp/x.sock)."
            ),
            Some(ProbeFailure::DaemonWedge)
        );
        assert_eq!(
            classify_failure_text("chrome-use error: Element not found"),
            None
        );
    }

    #[test]
    fn spawn_error_classification_distinguishes_missing_from_transient() {
        // Only a genuinely missing binary (NotFound) is definitive absence;
        // every other spawn error is transient and must never be reported as
        // "not installed".
        let not_found = std::io::Error::from(std::io::ErrorKind::NotFound);
        assert_eq!(classify_spawn_error(&not_found), CliStatus::Missing);
        for kind in [
            std::io::ErrorKind::WouldBlock,  // EAGAIN — process-table exhaustion
            std::io::ErrorKind::OutOfMemory, // ENOMEM
            std::io::ErrorKind::PermissionDenied, // EACCES
            std::io::ErrorKind::StorageFull, // ENOSPC
            std::io::ErrorKind::TimedOut,
        ] {
            let err = std::io::Error::from(kind);
            assert!(
                matches!(
                    classify_spawn_error(&err),
                    CliStatus::Transient(CliProbeFailure::Spawn(_))
                ),
                "kind {kind:?} must classify as transient, not missing"
            );
        }
    }

    #[test]
    fn cli_version_parsing_scans_the_real_banner() {
        // The --version banner ends with a bug-report URL — the version must
        // be found by scanning, not by assuming the last token.
        let banner = "chrome-use 1.5.100\n\
             report bugs / rough edges: https://github.com/leeguooooo/chrome-use/issues";
        assert_eq!(
            parse_cli_version(banner),
            Some(semver::Version::new(1, 5, 100))
        );
        assert_eq!(
            parse_cli_version("chrome-use v1.5.99"),
            Some(semver::Version::new(1, 5, 99))
        );
        assert_eq!(parse_cli_version("chrome-use\nno version here"), None);
    }

    #[test]
    fn release_asset_platform_maps_supported_combos() {
        assert_eq!(
            release_asset_platform("macos", "x86_64", false).as_deref(),
            Some("darwin-x64")
        );
        assert_eq!(
            release_asset_platform("macos", "aarch64", false).as_deref(),
            Some("darwin-arm64")
        );
        assert_eq!(
            release_asset_platform("linux", "x86_64", false).as_deref(),
            Some("linux-x64")
        );
        assert_eq!(
            release_asset_platform("linux", "aarch64", false).as_deref(),
            Some("linux-arm64")
        );
        assert_eq!(
            release_asset_platform("linux", "x86_64", true).as_deref(),
            Some("linux-musl-x64")
        );
        assert_eq!(
            release_asset_platform("linux", "aarch64", true).as_deref(),
            Some("linux-musl-arm64")
        );
        // The musl flag is ignored for non-linux platforms.
        assert_eq!(
            release_asset_platform("windows", "x86_64", true).as_deref(),
            Some("win32-x64")
        );
        assert_eq!(
            release_asset_platform("macos", "aarch64", true).as_deref(),
            Some("darwin-arm64")
        );
        // Unsupported platform/arch combos return None.
        assert_eq!(release_asset_platform("windows", "aarch64", false), None);
        assert_eq!(release_asset_platform("freebsd", "x86_64", false), None);
    }
}