Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

295 KB
Raw Blame
use std::hash::{Hash, Hasher};
use std::io::{Read, Seek, SeekFrom};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use futures::{stream, StreamExt};
use sha2::{Digest, Sha256};

use crate::agent_catalog;
use crate::agent_manager::{
    AgentDriverInfo, AgentInstallCancellation, AgentManager, AgentRegistry, ArtifactFormat, ArtifactInfo,
    InstalledDriver, JavaRuntimeMode, OperationLockHandle, DEFAULT_JRE_KEY, SQLITE_WORKER_DRIVER_KEY,
    SQLITE_WORKER_NATIVE_PLATFORMS,
};
use crate::DownloadSource;

/// Error returned when a user cancels an agent driver install/upgrade. The
/// frontend recognizes this substring to treat the outcome as "cancelled"
/// rather than a genuine failure.
pub const AGENT_DOWNLOAD_CANCELED_ERROR: &str = "Agent download canceled by user.";

/// Number of attempts to delete a JRE directory before giving up (Windows
/// experiences transient `ERROR_ACCESS_DENIED` when java.exe is still mapped
/// or anti-virus is scanning the archive). POSIX returns 1 — `unlink` of an
/// in-use file always succeeds.
const JRE_REMOVE_ATTEMPTS: usize = if cfg!(windows) { 6 } else { 1 };

/// Exponential-ish backoff between retries. Total wait ≈ 1.55s on Windows.
const JRE_REMOVE_BACKOFF_MS: &[u64] = &[50, 100, 200, 400, 400, 400];

/// Attempts to unpack an archive before reporting a failure. On Windows an
/// anti-virus/EDR scanner briefly holds a file it has just seen created, which
/// surfaces as `Access is denied`/`sharing violation` while `tar` writes the
/// archive contents. POSIX returns 1 — a failure there is not transient.
const ARCHIVE_EXTRACT_ATTEMPTS: usize = if cfg!(windows) { 4 } else { 1 };

/// Exponential-ish backoff between archive extraction retries. Total wait
/// ≈ 0.85s on Windows: long enough to cover the AV scan window, short enough
/// not to stall the import.
const ARCHIVE_EXTRACT_BACKOFF_MS: &[u64] = &[100, 250, 500];

/// Keep batch updates concurrent without allowing a large registry to exhaust
/// the download server, local disk, or the application's file descriptors.
const MAX_CONCURRENT_AGENT_UPDATES: usize = 4;

#[derive(Debug, Clone)]
#[cfg_attr(not(windows), allow(dead_code))]
enum ManagedAgentProcessTarget {
    Driver { jar_path: PathBuf, native_path: PathBuf },
    JreDirectory(PathBuf),
}

impl ManagedAgentProcessTarget {
    #[cfg_attr(not(windows), allow(dead_code))]
    fn description(&self) -> String {
        match self {
            Self::Driver { jar_path, .. } => format!("driver artifact {}", jar_path.display()),
            Self::JreDirectory(path) => format!("JRE directory {}", path.display()),
        }
    }
}

/// Normalize a process path for Windows matching: unify slashes, strip the
/// `\\?\` prefix and quotes, lowercase. Shared by every "is this process
/// holding our files" check (agent drivers, JREs, the JDBC plugin directory).
#[cfg_attr(not(any(windows, test)), allow(dead_code))]
pub fn normalized_process_path(path: &Path) -> String {
    let normalized = path.to_string_lossy().trim_matches('"').replace('/', "\\");
    normalized.strip_prefix(r"\\?\").unwrap_or(&normalized).trim_end_matches('\\').to_ascii_lowercase()
}

/// Whether `candidate` equals `directory` or is a child path of it, on
/// normalized Windows form. Shared by the agent/JRE/JDBC process matcher.
#[cfg_attr(not(any(windows, test)), allow(dead_code))]
pub fn process_path_is_within(candidate: &str, directory: &str) -> bool {
    candidate == directory || candidate.strip_prefix(directory).is_some_and(|remainder| remainder.starts_with('\\'))
}

#[cfg_attr(not(any(windows, test)), allow(dead_code))]
fn process_matches_managed_agent(
    executable: Option<&Path>,
    command: &[std::ffi::OsString],
    target: &ManagedAgentProcessTarget,
) -> bool {
    let executable = executable.map(normalized_process_path);
    match target {
        ManagedAgentProcessTarget::Driver { jar_path, native_path } => {
            let jar_path = normalized_process_path(jar_path);
            let native_path = normalized_process_path(native_path);
            executable.as_deref() == Some(native_path.as_str())
                || command.iter().any(|argument| normalized_process_path(Path::new(argument)) == jar_path)
        }
        ManagedAgentProcessTarget::JreDirectory(directory) => {
            let directory = normalized_process_path(directory);
            executable.as_deref().is_some_and(|path| process_path_is_within(path, &directory))
        }
    }
}

#[cfg(windows)]
fn stop_external_managed_agent_processes_blocking(target: ManagedAgentProcessTarget) -> Result<(), String> {
    use sysinfo::{get_current_pid, ProcessRefreshKind, ProcessesToUpdate, RefreshKind, System, UpdateKind};

    let refresh = ProcessRefreshKind::new().with_cmd(UpdateKind::Always).with_exe(UpdateKind::Always);
    let mut system = System::new_with_specifics(RefreshKind::new().with_processes(refresh));
    system.refresh_processes_specifics(ProcessesToUpdate::All, true, refresh);
    let current_pid = get_current_pid().ok();
    let mut matched = Vec::new();

    for (pid, process) in system.processes() {
        if current_pid == Some(*pid) || !process_matches_managed_agent(process.exe(), process.cmd(), &target) {
            continue;
        }
        let name = process.name().to_string_lossy().into_owned();
        let sent = process.kill();
        log::info!(
            "Stopping external DBX agent process before replacing {}: pid={}, name={}, kill_sent={sent}",
            target.description(),
            pid.as_u32(),
            name
        );
        matched.push((*pid, name));
    }

    if matched.is_empty() {
        return Ok(());
    }

    for _ in 0..30 {
        std::thread::sleep(Duration::from_millis(100));
        system.refresh_processes_specifics(ProcessesToUpdate::All, true, refresh);
        matched.retain(|(pid, _)| system.process(*pid).is_some());
        if matched.is_empty() {
            return Ok(());
        }
    }

    let remaining =
        matched.into_iter().map(|(pid, name)| format!("{name} (PID {})", pid.as_u32())).collect::<Vec<_>>().join(", ");
    Err(format!("Failed to stop DBX agent process(es) holding {}: {remaining}", target.description()))
}

async fn stop_external_managed_agent_processes(target: ManagedAgentProcessTarget) -> Result<(), String> {
    #[cfg(windows)]
    {
        return tokio::task::spawn_blocking(move || stop_external_managed_agent_processes_blocking(target))
            .await
            .map_err(|error| format!("Failed to inspect DBX agent processes: {error}"))?;
    }
    #[cfg(not(windows))]
    {
        let _ = target;
        Ok(())
    }
}

async fn stop_driver_processes_before_replacement(am: &AgentManager, db_type: &str) -> Result<(), String> {
    am.stop_daemon_by_key(db_type).await;
    stop_external_managed_agent_processes(ManagedAgentProcessTarget::Driver {
        jar_path: am.driver_jar_path(db_type),
        native_path: am.driver_native_path(db_type),
    })
    .await
}

async fn stop_jre_processes_before_replacement(am: &AgentManager, jre_key: &str) -> Result<(), String> {
    stop_daemons_using_jre(am, jre_key).await;
    stop_external_managed_agent_processes(ManagedAgentProcessTarget::JreDirectory(am.jre_dir(jre_key))).await
}

/// Delete an old JRE directory, retrying on Windows to cover the daemon-exit
/// and AV-scan release window. Returns the original `std::io::Error` when all
/// retries fail so callers can decide whether to fall back to rename-stash.
fn remove_jre_dir_with_retry(path: &Path) -> std::io::Result<()> {
    if !path.exists() {
        return Ok(());
    }
    let mut last_err: Option<std::io::Error> = None;
    for i in 0..JRE_REMOVE_ATTEMPTS {
        match std::fs::remove_dir_all(path) {
            Ok(()) => return Ok(()),
            Err(err) => {
                log::warn!(
                    "remove_dir_all({}) attempt {}/{} failed: {err}",
                    path.display(),
                    i + 1,
                    JRE_REMOVE_ATTEMPTS
                );
                last_err = Some(err);
                if i + 1 < JRE_REMOVE_ATTEMPTS {
                    let delay_ms = JRE_REMOVE_BACKOFF_MS.get(i).copied().unwrap_or(400);
                    std::thread::sleep(Duration::from_millis(delay_ms));
                }
            }
        }
    }
    Err(last_err.unwrap_or_else(|| std::io::Error::other("remove_dir_all failed without an error")))
}

/// Render a friendly error message when the old JRE directory cannot be
/// replaced. On Windows, lists likely culprits (process holding java.exe,
/// AV scanning) and suggests restarting dbx; on POSIX returns a concise
/// message. The original OS error is appended in parentheses for support.
fn format_jre_dir_remove_error(path: &Path, os_err: &std::io::Error) -> String {
    if cfg!(windows) {
        format!(
            "Failed to remove the old JRE directory: {}\n\
             Possible causes:\n  \
             - a dbx Agent / java process still holds the directory\n  \
             - antivirus software is scanning it\n\
             Close any process that may hold the directory, or restart dbx and try again.\n\
             (original error: {os_err})",
            path.display()
        )
    } else {
        format!("Failed to remove the old JRE directory: {} (original error: {os_err})", path.display())
    }
}

/// Render an error together with the I/O failure it wrapped.
///
/// `tar` reports every failed entry as `failed to unpack \`<path>\`` and
/// `zip` reports archive-level failures as `invalid Zip archive: …`; neither
/// prints the OS error in `Display`. On Windows that hides whether the
/// extraction was blocked by anti-virus (`Access is denied. (os error 5)`),
/// by a scanner still holding the file (`The process cannot access the file …
/// (os error 32)`), or by a full/quota-limited disk (`There is not enough
/// space … (os error 112)`), which made offline-import failures impossible to
/// diagnose from the UI. Append the deepest I/O cause — preferring one that
/// carries an OS error code — so the OS error survives, without repeating the
/// wrapper text `tar` already printed.
fn describe_error(error: &dyn std::error::Error) -> String {
    let mut message = error.to_string();
    if let Some(io_error) = deepest_io_error(error) {
        let text = io_error.to_string();
        if !text.is_empty() && !message.contains(&text) {
            message.push_str(": ");
            message.push_str(&text);
        }
    }
    message
}

/// Deepest `std::io::Error` in an error chain, preferring one that carries an
/// OS error code over a generic wrapper.
fn deepest_io_error(error: &dyn std::error::Error) -> Option<&std::io::Error> {
    let mut detail: Option<&std::io::Error> = None;
    let mut cause = error.source();
    while let Some(current) = cause {
        if let Some(io_error) = current.downcast_ref::<std::io::Error>() {
            if io_error.raw_os_error().is_some() || detail.is_none() {
                detail = Some(io_error);
            }
        }
        cause = current.source();
    }
    detail
}

/// Windows-only: rename the old JRE dir to a unique sibling so the install
/// can continue even when files inside are still mapped. Returns the stash
/// path so the caller can record it for later cleanup. On POSIX this is
/// unreachable (callers gate on `cfg(windows)` after a failed remove).
#[cfg(windows)]
fn stash_old_jre_dir(path: &Path) -> std::io::Result<PathBuf> {
    use std::time::SystemTime;

    let file_name = path
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| std::io::Error::other("JRE directory has no file name"))?;
    let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).map(|d| d.as_secs()).unwrap_or(0);
    // uuid::Uuid::new_v4() is already a workspace dependency — use its short
    // form for a unique suffix without pulling in `rand`.
    let rand = uuid::Uuid::new_v4().simple().to_string();
    let stash = path.with_file_name(format!("{file_name}.old-{ts}-{rand}"));
    std::fs::rename(path, &stash)?;
    Ok(stash)
}

/// Replace an old JRE directory in-place: try retried `remove_dir_all` first;
/// on Windows fall back to rename-stash if removal fails. Returns the stash
/// path (Some) if the rename fallback was used so the caller can persist it
/// for startup cleanup, or None if the directory was deleted outright (or
/// did not exist).
fn replace_old_jre_dir(path: &Path) -> Result<Option<PathBuf>, String> {
    match remove_jre_dir_with_retry(path) {
        Ok(()) => Ok(None),
        Err(remove_err) => {
            #[cfg(windows)]
            {
                match stash_old_jre_dir(path) {
                    Ok(stash) => {
                        log::warn!("remove_dir_all failed, stashed old JRE at {} ({remove_err})", stash.display());
                        // The caller will persist this stash under
                        // state_lock after extraction succeeds.
                        Ok(Some(stash))
                    }
                    Err(rename_err) => {
                        log::warn!(
                            "remove_dir_all and rename both failed for {}: remove={remove_err}, rename={rename_err}",
                            path.display()
                        );
                        Err(format_jre_dir_remove_error(path, &remove_err))
                    }
                }
            }
            #[cfg(not(windows))]
            {
                Err(format_jre_dir_remove_error(path, &remove_err))
            }
        }
    }
}

const REGISTRY_PATH: &str = "https://github.com/t8y2/dbx/releases/download/agents-latest/agent-registry.json";
const REGISTRY_R2_PATH: &str = "agents/agent-registry.json";

static REGISTRY_CACHE: std::sync::LazyLock<
    tokio::sync::Mutex<std::collections::HashMap<DownloadSource, (std::time::Instant, AgentRegistry)>>,
> = std::sync::LazyLock::new(|| tokio::sync::Mutex::new(std::collections::HashMap::new()));

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
pub struct AgentProgressEvent {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub operation_id: Option<String>,
    pub step: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub downloaded: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub db_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub current: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total_drivers: Option<u32>,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
pub struct AgentDriverUpdateIssue {
    pub db_type: String,
    pub error: String,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, Default)]
pub struct UpgradeAllAgentDriversResult {
    pub upgraded: u32,
    /// Drivers whose install was aborted by a user cancel (either individually
    /// or via the batch-level cancel). These are reported separately from
    /// `failed` so the UI can show "cancelled" rather than "failed".
    pub cancelled: u32,
    pub failed: Vec<AgentDriverUpdateIssue>,
}

impl AgentProgressEvent {
    pub fn step(step: impl Into<String>) -> Self {
        Self {
            operation_id: None,
            step: step.into(),
            downloaded: None,
            total: None,
            db_type: None,
            current: None,
            total_drivers: None,
        }
    }

    pub fn transfer(step: impl Into<String>, downloaded: u64, total: u64) -> Self {
        Self { downloaded: Some(downloaded), total: Some(total), ..Self::step(step) }
    }

    pub fn with_batch(mut self, db_type: Option<&str>, current: Option<u32>, total_drivers: Option<u32>) -> Self {
        self.db_type = db_type.map(ToString::to_string);
        self.current = current;
        self.total_drivers = total_drivers;
        self
    }

    pub fn with_operation_id(mut self, operation_id: &str) -> Self {
        self.operation_id = Some(operation_id.to_string());
        self
    }
}

/// Rate limit for gated download transfer progress: on slow connections a
/// whole percent of a large artifact can take seconds, so the clock fallback
/// keeps the byte counter visibly moving.
const TRANSFER_PROGRESS_MIN_INTERVAL: std::time::Duration = std::time::Duration::from_millis(500);
/// Byte fallback when the total size is unknown (no manifest size and no
/// Content-Length), so unbounded streams still report roughly once per MiB.
const TRANSFER_PROGRESS_UNKNOWN_TOTAL_STEP: u64 = 1024 * 1024;

/// Decides when a download transfer progress event should be emitted. Drivers
/// and JRE archives are tens to hundreds of MB and arrive in 8-64KB HTTP
/// chunks; emitting per chunk floods the frontend event channel with thousands
/// of events whose progress the UI rounds to whole percent anyway. The gate
/// emits on the first observation, then at most once per whole percent of the
/// total, or once per [`TRANSFER_PROGRESS_MIN_INTERVAL`] on slow connections.
#[derive(Debug, Clone)]
pub struct TransferProgressGate {
    total: u64,
    last_bytes: u64,
    last_emit: Option<std::time::Instant>,
}

impl TransferProgressGate {
    pub fn new(total: u64) -> Self {
        Self { total, last_bytes: 0, last_emit: None }
    }

    /// Records `downloaded` bytes observed at `now`; returns `true` when a
    /// progress event should be emitted for this observation.
    pub fn record(&mut self, downloaded: u64, now: std::time::Instant) -> bool {
        if let Some(last_emit) = self.last_emit {
            let delta = downloaded.saturating_sub(self.last_bytes);
            let whole_percent = self.total > 0 && delta * 100 >= self.total;
            let slow_link = now.duration_since(last_emit) >= TRANSFER_PROGRESS_MIN_INTERVAL;
            let unknown_total_step = self.total == 0 && delta >= TRANSFER_PROGRESS_UNKNOWN_TOTAL_STEP;
            if !whole_percent && !slow_link && !unknown_total_step {
                return false;
            }
        }
        self.last_bytes = downloaded;
        self.last_emit = Some(now);
        true
    }
}

#[cfg(test)]
mod transfer_progress_gate_tests {
    use super::TransferProgressGate;
    use std::time::{Duration, Instant};

    #[test]
    fn emits_leading_then_whole_percent_steps() {
        let t0 = Instant::now();
        let mut gate = TransferProgressGate::new(1000);
        assert!(gate.record(10, t0), "first observation always emits");
        assert!(!gate.record(15, t0 + Duration::from_millis(10)), "0.5% within 500ms is suppressed");
        assert!(gate.record(25, t0 + Duration::from_millis(20)), ">= 1% emits immediately");
        assert!(!gate.record(26, t0 + Duration::from_millis(30)), "0.1% right after an emit is suppressed");
    }

    #[test]
    fn emits_on_slow_connections_without_percent_progress() {
        let t0 = Instant::now();
        let mut gate = TransferProgressGate::new(1000);
        assert!(gate.record(10, t0));
        assert!(!gate.record(11, t0 + Duration::from_millis(100)), "0.1% at 100ms is suppressed");
        assert!(gate.record(12, t0 + Duration::from_millis(600)), "500ms without a whole percent emits");
    }

    #[test]
    fn unknown_total_falls_back_to_mib_steps() {
        let t0 = Instant::now();
        let mut gate = TransferProgressGate::new(0);
        assert!(gate.record(1000, t0));
        assert!(!gate.record(600_000, t0 + Duration::from_millis(10)), "sub-MiB within 500ms is suppressed");
        assert!(gate.record(1_200_000, t0 + Duration::from_millis(20)), "1 MiB step emits without a total");
    }
}

pub fn build_agent_list(am: &AgentManager, registry: Option<&AgentRegistry>) -> Vec<AgentDriverInfo> {
    let local_state = am.load_state();
    let use_managed_jre = local_state.java_runtime.mode == JavaRuntimeMode::Managed;
    agent_catalog::driver_store_entries()
        .filter_map(|(key, label)| {
            let jar_valid = am.is_driver_jar_valid(key);
            let native_installed = am.driver_native_installed(key);
            let launch_config_installed = am.driver_launch_config_path(key).exists();
            let installed = jar_valid || native_installed || launch_config_installed;
            let local = local_state.installed_drivers.get(key);
            let remote = registry.and_then(|r| agent_registry_driver(r, key));
            // A driver the registry publishes nothing for on this platform (the
            // Windows-only Oracle OCI agent on macOS, for example) cannot be
            // installed here, and offering it would only produce a download or
            // JRE fetch that must fail. Already-installed entries stay listed so
            // they can still be upgraded or uninstalled.
            if !installed && remote.is_some_and(|driver| !driver_installable_on_current_platform(key, driver)) {
                return None;
            }
            let remote_requires_java_runtime = remote.is_some_and(remote_driver_requires_java_runtime);
            let requires_java_runtime = if installed {
                jar_valid && !native_installed && !launch_config_installed
            } else {
                remote_requires_java_runtime
            };
            let jre_key = remote
                .map(|r| r.jre.clone())
                .or_else(|| local.map(|l| l.jre.clone()))
                .unwrap_or_else(|| DEFAULT_JRE_KEY.to_string());
            let remote_jre_version = registry.and_then(|r| r.resolve_jre(&jre_key)).map(|j| &j.version);
            let local_jre_version = installed_jre_version(&local_state, &jre_key);
            let jre_update_available = installed
                && requires_java_runtime
                && use_managed_jre
                && (!am.is_jre_installed(&jre_key)
                    || remote_jre_version.is_some_and(|version| local_jre_version != Some(version)));
            Some(AgentDriverInfo {
                db_type: key.to_string(),
                label: label.to_string(),
                version: remote.map(|r| r.version.clone()).unwrap_or_default(),
                size: remote.map(|driver| driver_download_size(key, driver)).unwrap_or(0),
                installed,
                installed_version: local.map(|l| l.version.clone()),
                update_available: match (local, remote) {
                    (Some(l), Some(r)) => l.version != r.version || jre_update_available,
                    _ => false,
                },
                requires_java_runtime,
                jre: jre_key.clone(),
                jre_installed: !requires_java_runtime || am.is_jre_installed(&jre_key),
            })
        })
        .collect()
}

fn usable_driver_jar(driver: &crate::agent_manager::DriverInfo) -> Option<&crate::agent_manager::ArtifactInfo> {
    driver.jar.as_ref().filter(|artifact| artifact.size > 0)
}

/// Whether the registry publishes an artifact this platform can actually run:
/// a native agent binary built for it, or the Java JAR fallback.
///
/// The SQLite SSH worker is the one driver whose binaries execute on the remote
/// SSH host instead of the desktop, so a `native` set without an entry for this
/// platform is still installable here (#8987).
fn driver_installable_on_current_platform(db_type: &str, driver: &crate::agent_manager::DriverInfo) -> bool {
    if AgentManager::is_sqlite_worker_driver(db_type) {
        return true;
    }
    driver.native.contains_key(AgentManager::current_platform()) || usable_driver_jar(driver).is_some()
}

fn driver_download_artifact(driver: &crate::agent_manager::DriverInfo) -> Option<&crate::agent_manager::ArtifactInfo> {
    driver.native.get(AgentManager::current_platform()).or_else(|| usable_driver_jar(driver))
}

fn driver_download_size(db_type: &str, driver: &crate::agent_manager::DriverInfo) -> u64 {
    if AgentManager::is_sqlite_worker_driver(db_type) {
        return SQLITE_WORKER_NATIVE_PLATFORMS
            .iter()
            .filter_map(|platform| driver.native.get(*platform))
            .map(|artifact| artifact.size)
            .sum();
    }
    driver_download_artifact(driver).map(|artifact| artifact.size).unwrap_or(0)
}

fn remote_driver_requires_java_runtime(driver: &crate::agent_manager::DriverInfo) -> bool {
    usable_driver_jar(driver).is_some() && !driver.native.contains_key(AgentManager::current_platform())
}

fn installed_jre_version<'a>(state: &'a crate::agent_manager::AgentState, jre_key: &str) -> Option<&'a String> {
    state
        .jre_versions
        .get(jre_key)
        .or_else(|| (jre_key == DEFAULT_JRE_KEY).then_some(state.jre_version.as_ref()).flatten())
}

fn mark_executable(path: &Path) -> Result<(), String> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut permissions = std::fs::metadata(path).map_err(|err| err.to_string())?.permissions();
        permissions.set_mode(0o755);
        std::fs::set_permissions(path, permissions).map_err(|err| err.to_string())?;
    }
    #[cfg(not(unix))]
    {
        let _ = path;
    }
    Ok(())
}

pub fn jre_needs_install(am: &AgentManager, registry: &AgentRegistry, jre_key: &str) -> bool {
    let state = am.load_state();
    if state.java_runtime.mode != JavaRuntimeMode::Managed {
        return false;
    }
    if !am.is_jre_installed(jre_key) {
        return true;
    }
    registry.resolve_jre(jre_key).is_some_and(|jre| state.jre_versions.get(jre_key) != Some(&jre.version))
}

pub fn local_agent_jar_candidates(db_type: &str) -> Vec<PathBuf> {
    let jar_name = format!("dbx-agent-{db_type}.jar");
    let mut candidates = Vec::new();

    for agents_dir in local_agents_dir_candidates() {
        candidates.push(agent_driver_jar_path(&agents_dir, db_type, &jar_name));
        candidates.push(agent_legacy_jar_path(&agents_dir, db_type, &jar_name));
    }

    candidates
}

fn local_agents_dir_candidates() -> Vec<PathBuf> {
    let mut candidates = vec![PathBuf::from("agents"), PathBuf::from("..").join("agents")];
    if let Some(workspace_root) = PathBuf::from(env!("CARGO_MANIFEST_DIR")).parent().and_then(|path| path.parent()) {
        candidates.push(workspace_root.join("agents"));
    }
    candidates.push(PathBuf::from("..").join("dbx-agents"));
    candidates.push(PathBuf::from("dbx-agents"));
    candidates
}

fn agent_driver_jar_path(agents_dir: &Path, db_type: &str, jar_name: &str) -> PathBuf {
    agents_dir.join("drivers").join(db_type).join("build").join("libs").join(jar_name)
}

fn agent_legacy_jar_path(agents_dir: &Path, db_type: &str, jar_name: &str) -> PathBuf {
    agents_dir.join(db_type).join("build").join("libs").join(jar_name)
}

pub fn find_local_agent_jar(db_type: &str) -> Option<PathBuf> {
    local_agent_jar_candidates(db_type).into_iter().find(|path| path.exists())
}

pub fn install_local_agent(am: &AgentManager, db_type: &str, source: PathBuf) -> Result<(), String> {
    install_local_agent_file(am, db_type, &source)?;
    am.mutate_state(|state| record_local_agent_install(state, db_type, DEFAULT_JRE_KEY))
}

fn install_local_agent_file(am: &AgentManager, db_type: &str, source: &Path) -> Result<(), String> {
    let jar_path = am.driver_jar_path(db_type);
    let parent = jar_path.parent().ok_or_else(|| format!("Invalid driver path: {}", jar_path.display()))?;
    std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    let staging_path = parent.join(format!(".agent-jar-import-{}", uuid::Uuid::new_v4()));
    std::fs::copy(source, &staging_path).map_err(|e| format!("Failed to copy local agent jar: {e}"))?;
    if !is_valid_agent_jar(&staging_path) {
        std::fs::remove_file(&staging_path).ok();
        return Err(format!("Local agent jar is invalid or corrupt: {}", source.display()));
    }
    replace_imported_agent_file(&staging_path, &jar_path)
}

fn record_local_agent_install(state: &mut crate::agent_manager::AgentState, db_type: &str, jre_key: &str) {
    state.installed_drivers.insert(
        db_type.to_string(),
        InstalledDriver {
            version: "0.1.0-local".to_string(),
            installed_at: chrono::Utc::now().to_rfc3339(),
            jre: jre_key.to_string(),
        },
    );
}

fn is_valid_agent_jar(path: &Path) -> bool {
    let Ok(file) = std::fs::File::open(path) else {
        return false;
    };
    let Ok(mut archive) = zip::ZipArchive::new(file) else {
        return false;
    };
    let Ok(mut manifest) = archive.by_name("META-INF/MANIFEST.MF") else {
        return false;
    };
    let mut manifest_text = String::new();
    manifest.read_to_string(&mut manifest_text).is_ok() && manifest_text.contains("Main-Class:")
}

pub async fn fetch_registry() -> Result<AgentRegistry, String> {
    fetch_registry_from(DownloadSource::Official).await
}

pub async fn fetch_registry_from(source: DownloadSource) -> Result<AgentRegistry, String> {
    fetch_registry_from_claimed(source, &[]).await
}

/// Like `fetch_registry_from`, but the registry HTTP request AND the
/// response-body JSON parse are raced against the given cancellation tokens, so
/// a cancel fired during install/batch setup aborts promptly instead of waiting
/// for the 10s client timeout. Pass an empty slice to keep the non-cancellable
/// behavior.
pub async fn fetch_registry_from_claimed(
    source: DownloadSource,
    cancellations: &[&AgentInstallCancellation],
) -> Result<AgentRegistry, String> {
    let urls = source.download_candidate_urls(REGISTRY_PATH, REGISTRY_R2_PATH)?;
    fetch_registry_from_urls(source, &urls, cancellations).await
}

/// Core registry fetch over explicit candidate URLs (the URL seam lets tests
/// point at a localhost server). With a non-empty `cancellations` slice both the
/// HTTP request and the body parse are raced against cancellation.
async fn fetch_registry_from_urls(
    source: DownloadSource,
    urls: &[String],
    cancellations: &[&AgentInstallCancellation],
) -> Result<AgentRegistry, String> {
    // A pre-cancelled token must abort before any network attempt.
    if !cancellations.is_empty() && cancellations.iter().any(|token| token.is_cancelled()) {
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }
    {
        let cache = REGISTRY_CACHE.lock().await;
        if let Some((ts, registry)) = cache.get(&source) {
            if ts.elapsed() < std::time::Duration::from_secs(300) {
                return Ok(registry.clone());
            }
        }
    }
    let client = reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(10))
        .build()
        .map_err(|err| format!("Failed to create HTTP client: {err}"))?;
    let resp = open_download_response(&client, urls, "dbx-agent-manager", cancellations)
        .await
        .map_err(|err| format!("Failed to fetch agent registry: {err}"))?;
    // Race the body parse too: a stalled/partial body must not hold the
    // registry fetch hostage until the 10s client timeout.
    let registry: AgentRegistry = if cancellations.is_empty() {
        resp.json().await.map_err(|err| format!("Failed to parse registry: {err}"))?
    } else {
        tokio::select! {
            result = resp.json() => result.map_err(|err| format!("Failed to parse registry: {err}"))?,
            _ = first_cancellation(cancellations) => return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string()),
        }
    };
    REGISTRY_CACHE.lock().await.insert(source, (std::time::Instant::now(), registry.clone()));
    Ok(registry)
}

async fn open_download_response(
    client: &reqwest::Client,
    urls: &[String],
    user_agent: &str,
    cancellations: &[&AgentInstallCancellation],
) -> Result<reqwest::Response, String> {
    let mut errors = Vec::new();
    for url in urls {
        let request = client
            .get(url)
            .header(reqwest::header::USER_AGENT, user_agent)
            .header(reqwest::header::ACCEPT_ENCODING, "identity");
        // Race the request with cancellation: a stalled mirror that never
        // returns response headers must not hold the registry fetch hostage
        // until the 10s client timeout. Dropping the send future aborts it.
        let resp = if cancellations.is_empty() {
            match request.send().await {
                Ok(resp) => resp,
                Err(error) => {
                    errors.push(format!("{url}: {error}"));
                    continue;
                }
            }
        } else {
            tokio::select! {
                result = request.send() => match result {
                    Ok(resp) => resp,
                    Err(error) => {
                        errors.push(format!("{url}: {error}"));
                        continue;
                    }
                },
                _ = first_cancellation(cancellations) => return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string()),
            }
        };
        match resp.error_for_status() {
            Ok(resp) => return Ok(resp),
            Err(error) => errors.push(format!("{url}: {error}")),
        }
    }
    Err(errors.join("; "))
}

pub async fn invalidate_registry_cache() {
    REGISTRY_CACHE.lock().await.clear();
}

pub async fn install_agent_driver(
    am: &AgentManager,
    db_type: &str,
    progress: impl Fn(AgentProgressEvent),
) -> Result<(), String> {
    install_agent_driver_from(am, db_type, DownloadSource::Official, progress).await
}

/// Ensure both Linux worker binaries are available for remote SQLite over SSH.
///
/// Unlike a regular native Agent, this driver is selected by the remote SSH
/// host's architecture rather than by the desktop application's platform. The
/// online installer always fetches every platform, so this readiness check asks
/// for all of them; an offline import may legitimately provide just one (the
/// remote host's), which [`AgentManager::driver_native_installed`] accepts.
pub async fn ensure_sqlite_worker_driver_ready(am: &AgentManager) -> Result<(), String> {
    if am.sqlite_worker_all_platforms_installed() {
        return Ok(());
    }
    install_agent_driver(am, SQLITE_WORKER_DRIVER_KEY, |_| {}).await?;
    if am.sqlite_worker_all_platforms_installed() {
        Ok(())
    } else {
        Err("SQLite SSH worker installation completed without both Linux binaries".to_string())
    }
}

/// Like `install_agent_driver`, but using a command-scoped cancellation token
/// that was registered before any awaitable setup (blocker check, lock wait,
/// registry fetch) so a cancel fired during that window is observed.
pub async fn install_agent_driver_claimed(
    am: &AgentManager,
    db_type: &str,
    progress: impl Fn(AgentProgressEvent),
    cancellation: &Arc<AgentInstallCancellation>,
) -> Result<(), String> {
    install_agent_driver_from_claimed(am, db_type, DownloadSource::Official, progress, cancellation).await
}

pub async fn install_agent_driver_from(
    am: &AgentManager,
    db_type: &str,
    source: DownloadSource,
    progress: impl Fn(AgentProgressEvent),
) -> Result<(), String> {
    install_agent_driver_with_batch(am, db_type, source, &progress, None, None, None).await
}

/// Like `install_agent_driver_from`, but using a command-scoped cancellation
/// token registered before any awaitable setup. A cancel fired while waiting
/// on locks, blockers, or the registry fetch is observed instead of lost.
pub async fn install_agent_driver_from_claimed(
    am: &AgentManager,
    db_type: &str,
    source: DownloadSource,
    progress: impl Fn(AgentProgressEvent),
    cancellation: &Arc<AgentInstallCancellation>,
) -> Result<(), String> {
    install_agent_driver_with_batch(am, db_type, source, &progress, None, None, Some(cancellation)).await
}

/// Cancel an in-flight single driver install/update. `operation_id` targets the
/// exact install (a second same-db_type install registered under a different
/// operation id is unaffected). Also covers a driver inside a batch upgrade
/// when the batch's operation id is supplied. Missing keys are a no-op.
pub async fn cancel_agent_driver_install(
    am: &AgentManager,
    db_type: &str,
    operation_id: Option<&str>,
) -> Result<(), String> {
    if let Some(operation_id) = operation_id {
        am.cancel_install(&install_cancellation_key(operation_id)).await;
        am.cancel_install(&batch_driver_cancellation_key(operation_id, db_type)).await;
    }
    Ok(())
}

/// Cancel an in-flight batch upgrade, targeting the exact batch by its
/// operation id. Aborts every driver still downloading and stops scheduling
/// drivers that have not started yet.
pub async fn cancel_agent_batch_upgrade(am: &AgentManager, operation_id: Option<&str>) -> Result<(), String> {
    if let Some(operation_id) = operation_id {
        am.cancel_install(&batch_cancellation_key(operation_id)).await;
    }
    Ok(())
}

/// Cancellation-map key for a single install operation.
pub fn install_cancellation_key(operation_id: &str) -> String {
    format!("install:{operation_id}")
}

/// Cancellation-map key for a whole-batch upgrade operation.
pub fn batch_cancellation_key(operation_id: &str) -> String {
    format!("batch:{operation_id}")
}

/// Cancellation-map key for one driver inside a batch upgrade operation.
pub fn batch_driver_cancellation_key(operation_id: &str, db_type: &str) -> String {
    format!("batch:{operation_id}:{db_type}")
}

/// Ensure an already-selected fallback Agent can be launched, installing only
/// missing or invalid runtime artifacts. A usable installed driver is never
/// upgraded implicitly.
pub async fn ensure_agent_driver_ready(am: &AgentManager, db_type: &str) -> Result<(), String> {
    ensure_agent_driver_ready_from(am, db_type, DownloadSource::Official).await
}

async fn ensure_agent_driver_ready_from(
    am: &AgentManager,
    db_type: &str,
    source: DownloadSource,
) -> Result<(), String> {
    if agent_driver_runtime_readiness(am, db_type).is_ok() {
        return Ok(());
    }

    let _installation_guard = am.installation_operation_lock.read().await;
    let driver_lock = driver_operation_lock(am, db_type);
    let _driver_guard = driver_lock.lock().await;

    // Another fallback may have completed installation while this task waited.
    if agent_driver_runtime_readiness(am, db_type).is_ok() {
        return Ok(());
    }

    let registry = fetch_registry_from(source).await?;
    let progress = |_| {};
    if !am.is_driver_installed(db_type) {
        install_agent_driver_from_registry(am, &registry, source, db_type, &progress, None, None, &[]).await?;
    } else if am.driver_requires_java_runtime(db_type) {
        let state = am.load_state();
        let jre_key = state
            .installed_drivers
            .get(db_type)
            .map(|driver| driver.jre.as_str())
            .or_else(|| agent_registry_driver(&registry, db_type).map(|driver| driver.jre.as_str()))
            .unwrap_or(DEFAULT_JRE_KEY);
        ensure_jre_from_registry(am, &registry, source, jre_key, db_type, &progress, None, None, &[]).await?;
    }

    agent_driver_runtime_readiness(am, db_type)
}

fn agent_driver_runtime_readiness(am: &AgentManager, db_type: &str) -> Result<(), String> {
    let state = am.load_state();
    let jre_key = state.installed_drivers.get(db_type).map(|driver| driver.jre.as_str()).unwrap_or(DEFAULT_JRE_KEY);
    am.resolve_agent_launch_spec(&state, db_type, jre_key).map(|_| ())
}

pub async fn upgrade_all_agent_drivers(
    am: &AgentManager,
    progress: impl Fn(AgentProgressEvent),
) -> Result<UpgradeAllAgentDriversResult, String> {
    upgrade_all_agent_drivers_from(am, DownloadSource::Official, progress).await
}

pub async fn upgrade_all_agent_drivers_from(
    am: &AgentManager,
    source: DownloadSource,
    progress: impl Fn(AgentProgressEvent),
) -> Result<UpgradeAllAgentDriversResult, String> {
    let registry = fetch_registry_from(source).await?;
    upgrade_all_agent_drivers_with_registry(am, &registry, source, &progress, None, None).await
}

/// Like `upgrade_all_agent_drivers`, but using a command-scoped batch
/// cancellation token registered before the registry fetch + blocker check so a
/// cancel fired during that setup aborts the whole batch instead of being lost.
/// `operation_id` names the batch so per-driver cancellation targets the right
/// operation even when the same driver is installed concurrently elsewhere.
pub async fn upgrade_all_agent_drivers_claimed(
    am: &AgentManager,
    progress: impl Fn(AgentProgressEvent),
    batch_cancellation: &Arc<AgentInstallCancellation>,
    operation_id: &str,
) -> Result<UpgradeAllAgentDriversResult, String> {
    upgrade_all_agent_drivers_from_claimed(am, DownloadSource::Official, progress, batch_cancellation, operation_id)
        .await
}

pub async fn upgrade_all_agent_drivers_from_claimed(
    am: &AgentManager,
    source: DownloadSource,
    progress: impl Fn(AgentProgressEvent),
    batch_cancellation: &Arc<AgentInstallCancellation>,
    operation_id: &str,
) -> Result<UpgradeAllAgentDriversResult, String> {
    let registry = fetch_registry_from_claimed(source, &[batch_cancellation.as_ref()]).await?;
    upgrade_all_agent_drivers_with_registry(
        am,
        &registry,
        source,
        &progress,
        Some(batch_cancellation),
        Some(operation_id),
    )
    .await
}

async fn upgrade_all_agent_drivers_with_registry(
    am: &AgentManager,
    registry: &AgentRegistry,
    source: DownloadSource,
    progress: &impl Fn(AgentProgressEvent),
    batch_cancellation: Option<&Arc<AgentInstallCancellation>>,
    operation_id: Option<&str>,
) -> Result<UpgradeAllAgentDriversResult, String> {
    let agents = build_agent_list(am, Some(registry));
    let updatable: Vec<String> =
        agents.iter().filter(|agent| agent.update_available).map(|agent| agent.db_type.clone()).collect();
    let total = updatable.len() as u32;

    // Use the command-scoped batch token when one was registered before the
    // registry fetch + blocker check, so a cancel fired during that setup is
    // observed. Otherwise register a token owned by this call keyed by a fresh
    // operation id so it cannot collide with another in-flight operation.
    let owned_operation_id: Option<String> =
        if operation_id.is_some() { None } else { Some(uuid::Uuid::new_v4().to_string()) };
    let effective_operation_id: &str = owned_operation_id.as_deref().or(operation_id).unwrap_or_default();
    let owned_batch: Option<Arc<AgentInstallCancellation>> = if batch_cancellation.is_some() {
        None
    } else {
        Some(am.begin_install_cancellation(&batch_cancellation_key(effective_operation_id)).await)
    };
    let active_batch_arc: Arc<AgentInstallCancellation> = owned_batch
        .clone()
        .or_else(|| batch_cancellation.cloned())
        .expect("a batch cancellation token is always available");
    let active_batch: &AgentInstallCancellation = active_batch_arc.as_ref();
    if active_batch.is_cancelled() {
        if let Some(token) = owned_batch {
            am.finish_install_cancellation(&batch_cancellation_key(effective_operation_id), &token).await;
        }
        return Ok(UpgradeAllAgentDriversResult { cancelled: total, ..Default::default() });
    }

    // Register a per-driver token for every driver in the batch, keyed by the
    // batch operation id so per-driver cancels target this batch's driver even
    // when the same db_type is being installed concurrently elsewhere. The
    // batch token lets one click abort the whole upgrade; each driver token
    // lets the user cancel a single driver while the rest continue.
    let mut driver_cancellations = std::collections::HashMap::new();
    for db_type in &updatable {
        let key = batch_driver_cancellation_key(effective_operation_id, db_type);
        let token = am.begin_install_cancellation(&key).await;
        driver_cancellations.insert(db_type.clone(), token);
    }

    // Run independent driver installs concurrently, with a fixed upper bound
    // so a large registry cannot saturate download and file-system resources.
    let installs = updatable.into_iter().enumerate().map(|(index, db_type)| {
        let key = batch_driver_cancellation_key(effective_operation_id, &db_type);
        let token = driver_cancellations.remove(&db_type).expect("driver token registered");
        let batch_token = Arc::clone(&active_batch_arc);
        async move {
            let result = if batch_token.is_cancelled() {
                Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string())
            } else {
                install_agent_driver_from_registry_locked(
                    am,
                    registry,
                    source,
                    &db_type,
                    progress,
                    Some((index + 1) as u32),
                    Some(total),
                    // Observe BOTH the row token (per-driver cancel) and the
                    // batch token (cancel-all): a batch cancel must interrupt a
                    // driver whose download already started, not just one that
                    // is still waiting to begin.
                    &[&token, &batch_token],
                )
                .await
            };
            am.finish_install_cancellation(&key, &token).await;
            (db_type, result)
        }
    });

    let outcomes = stream::iter(installs).buffer_unordered(MAX_CONCURRENT_AGENT_UPDATES).collect::<Vec<_>>().await;
    if let Some(token) = owned_batch {
        am.finish_install_cancellation(&batch_cancellation_key(effective_operation_id), &token).await;
    }

    let mut result = UpgradeAllAgentDriversResult::default();
    for (db_type, outcome) in outcomes {
        match outcome {
            Ok(()) => result.upgraded += 1,
            Err(error) => {
                if is_cancelled_error(&error) {
                    result.cancelled += 1;
                } else {
                    log::warn!("Failed to update {} agent driver: {}", db_type, error);
                    result.failed.push(AgentDriverUpdateIssue { db_type, error });
                }
            }
        }
    }

    progress(AgentProgressEvent::step("all-done"));
    Ok(result)
}

fn is_cancelled_error(error: &str) -> bool {
    error.contains(AGENT_DOWNLOAD_CANCELED_ERROR)
}

async fn can_fallback_to_local_agent(
    _am: &AgentManager,
    _db_type: &str,
    cancellations: &[&AgentInstallCancellation],
) -> bool {
    !cancellations.iter().any(|token| token.is_cancelled())
}

fn driver_operation_lock<'a>(am: &'a AgentManager, db_type: &str) -> OperationLockHandle<'a> {
    let mut locks = am.driver_operation_locks.lock().expect("driver operation lock table poisoned");
    let lock = locks.entry(db_type.to_string()).or_insert_with(|| Arc::new(tokio::sync::Mutex::new(()))).clone();
    OperationLockHandle::new(&am.driver_operation_locks, db_type, lock)
}

fn jre_operation_lock<'a>(am: &'a AgentManager, jre_key: &str) -> OperationLockHandle<'a> {
    let mut locks = am.jre_install_locks.lock().expect("JRE install lock table poisoned");
    let lock = locks.entry(jre_key.to_string()).or_insert_with(|| Arc::new(tokio::sync::Mutex::new(()))).clone();
    OperationLockHandle::new(&am.jre_install_locks, jre_key, lock)
}

/// Future that resolves as soon as any cancellation token fires.
fn first_cancellation<'a>(
    cancellations: &'a [&'a AgentInstallCancellation],
) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + 'a>> {
    Box::pin(async move {
        let ((), _index, _rest) =
            futures::future::select_all(cancellations.iter().map(|token| Box::pin(token.cancelled()))).await;
    })
}

/// Acquire a per-driver/JRE operation lock, aborting promptly if any
/// cancellation token fires while the lock is held elsewhere. Without this
/// race a cancelled install would wait for the current lock holder to finish
/// before it could observe its token.
async fn lock_or_cancel<'a>(
    lock: &'a tokio::sync::Mutex<()>,
    cancellations: &'a [&'a AgentInstallCancellation],
) -> Result<tokio::sync::MutexGuard<'a, ()>, String> {
    if cancellations.is_empty() {
        return Ok(lock.lock().await);
    }
    tokio::select! {
        guard = lock.lock() => Ok(guard),
        _ = first_cancellation(cancellations) => Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string()),
    }
}

pub async fn uninstall_agent_driver(am: &AgentManager, db_type: &str) -> Result<(), String> {
    let _installation_guard = am.installation_operation_lock.read().await;
    {
        let driver_lock = driver_operation_lock(am, db_type);
        let _driver_guard = driver_lock.lock().await;
        stop_driver_processes_before_replacement(am, db_type).await?;
        prune_driver_download_cache(am, db_type)?;
        let jar_path = am.driver_jar_path(db_type);
        if jar_path.exists() {
            std::fs::remove_file(&jar_path).map_err(|err| err.to_string())?;
        }
        if let Some(driver_dir) = jar_path.parent() {
            if driver_dir.exists() {
                std::fs::remove_dir_all(driver_dir).map_err(|err| err.to_string())?;
            }
        }
        am.mutate_state(|state| state.installed_drivers.remove(db_type))?;
    }
    Ok(())
}

pub fn clear_agent_download_cache(am: &AgentManager) -> Result<(), String> {
    remove_download_cache_entries(am, |_| true, "download cache")
}

pub async fn uninstall_agent_jre(am: &AgentManager, jre_key: &str) -> Result<(), String> {
    // Keep the dependency check and removal atomic with respect to driver
    // installs/uninstalls that may add or remove a dependency on this JRE.
    let _installation_guard = am.installation_operation_lock.write().await;
    {
        let jre_lock = jre_operation_lock(am, jre_key);
        let _jre_guard = jre_lock.lock().await;
        let local_state = am.load_state();
        let dependents: Vec<&str> = local_state
            .installed_drivers
            .keys()
            .filter(|db_type| am.installed_driver_jre_dependency(&local_state, db_type) == Some(jre_key))
            .map(|k| k.as_str())
            .collect();
        if !dependents.is_empty() {
            return Err(format!(
                "JRE {jre_key} is in use by drivers: {}. Uninstall them first.",
                dependents.join(", ")
            ));
        }
        // Stop daemons first so any java.exe holding the JRE files exits before
        // we try to remove the directory (Windows ERROR_ACCESS_DENIED otherwise).
        am.stop_daemons().await;
        stop_external_managed_agent_processes(ManagedAgentProcessTarget::JreDirectory(am.jre_dir(jre_key))).await?;
        let jre_dir = am.jre_dir(jre_key);
        if let Err(err) = remove_jre_dir_with_retry(&jre_dir) {
            return Err(format_jre_dir_remove_error(&jre_dir, &err));
        }
        am.mutate_state(|state| state.jre_versions.remove(jre_key))?;
    }
    Ok(())
}

pub async fn reinstall_agent_jre(
    am: &AgentManager,
    jre_key: &str,
    progress: impl Fn(AgentProgressEvent),
) -> Result<(), String> {
    reinstall_agent_jre_from(am, jre_key, DownloadSource::Official, progress).await
}

pub async fn reinstall_agent_jre_from(
    am: &AgentManager,
    jre_key: &str,
    source: DownloadSource,
    progress: impl Fn(AgentProgressEvent),
) -> Result<(), String> {
    // Replacing a JRE must not race a driver operation that is using or about
    // to persist a dependency on the same runtime.
    let _installation_guard = am.installation_operation_lock.write().await;
    let jre_lock = jre_operation_lock(am, jre_key);
    let _jre_guard = jre_lock.lock().await;
    let registry = fetch_registry_from(source).await?;
    let jre_info = registry.resolve_jre(jre_key).ok_or_else(|| format!("No JRE definition for version: {jre_key}"))?;
    let platform = AgentManager::current_platform();
    let platform_jre = jre_info
        .platforms
        .get(platform)
        .ok_or_else(|| format!("No JRE {jre_key} available for platform: {platform}"))?;
    let jre_archive = jre_archive_download_path(am, jre_key, platform_jre.format);
    download_with_progress(
        am,
        &progress,
        "jre",
        source,
        &platform_jre.url,
        &r2_path_with_cache_buster(&github_url_to_r2_path(&platform_jre.url, "jre"), &jre_info.version),
        &jre_archive,
        platform_jre.size,
        platform_jre.sha256.as_deref(),
        Some(CacheIdentity::Jre { key: jre_key, version: &jre_info.version }),
        None,
        None,
        None,
        &[],
    )
    .await?;
    let jre_dir = am.jre_dir(jre_key);
    // Stop daemons before deleting so java.exe processes release file
    // handles on Windows (Issue #1100). Falls back to a rename-stash if the
    // directory still cannot be removed.
    am.stop_daemons().await;
    stop_external_managed_agent_processes(ManagedAgentProcessTarget::JreDirectory(jre_dir.clone())).await?;
    let stash = replace_old_jre_dir(&jre_dir)?;
    persist_pending_jre_cleanup(am, stash.as_ref()).await?;
    extract_jre_archive(&jre_archive, &jre_dir, platform_jre.format)?;
    std::fs::remove_file(&jre_archive).ok();
    am.mutate_state(|state| state.jre_versions.insert(jre_key.to_string(), jre_info.version.clone()))?;
    cleanup_jre_download_cache_after_success(am, jre_key);
    progress(AgentProgressEvent::step("done"));
    Ok(())
}

pub async fn import_agents_from_zip(
    am: &AgentManager,
    zip_path: &Path,
    progress: impl Fn(AgentProgressEvent),
) -> Result<OfflineImportResult, String> {
    import_offline_zip(am, zip_path, |p| {
        progress(AgentProgressEvent {
            operation_id: None,
            step: p.step,
            downloaded: Some(p.current as u64),
            total: Some(p.total as u64),
            db_type: p.db_type,
            current: Some(p.current),
            total_drivers: Some(p.total),
        });
    })
    .await
}

pub fn inspect_offline_package(package_path: &Path) -> Result<OfflineImportPlan, String> {
    if is_tar_zstd_package(package_path) {
        if let Some(info) = tar_zstd_jre_package_info(package_path)? {
            let staging = tempfile::tempdir().map_err(|error| error.to_string())?;
            extract_and_validate_standalone_jre(package_path, staging.path(), &info)?;
            return Ok(OfflineImportPlan { driver_keys: Vec::new(), includes_jre: true });
        }
        inspect_tar_zstd_driver_package(package_path)
    } else {
        inspect_offline_zip(package_path)
    }
}

pub async fn import_agents_from_package(
    am: &AgentManager,
    package_path: &Path,
    progress: impl Fn(AgentProgressEvent),
) -> Result<OfflineImportResult, String> {
    if is_tar_zstd_package(package_path) {
        if let Some(info) = tar_zstd_jre_package_info(package_path)? {
            return import_tar_zstd_jre_package(am, package_path, &info, &progress).await;
        }
        import_tar_zstd_driver_package(am, package_path, |event| {
            progress(AgentProgressEvent {
                operation_id: None,
                step: event.step,
                downloaded: Some(event.current as u64),
                total: Some(event.total as u64),
                db_type: event.db_type,
                current: Some(event.current),
                total_drivers: Some(event.total),
            });
        })
        .await
    } else {
        import_agents_from_zip(am, package_path, progress).await
    }
}

fn is_tar_zstd_package(path: &Path) -> bool {
    path.file_name().and_then(|name| name.to_str()).is_some_and(|name| name.to_ascii_lowercase().ends_with(".tar.zst"))
}

async fn install_agent_driver_with_batch(
    am: &AgentManager,
    db_type: &str,
    source: DownloadSource,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellation: Option<&Arc<AgentInstallCancellation>>,
) -> Result<(), String> {
    let _installation_guard = am.installation_operation_lock.read().await;
    let driver_lock = driver_operation_lock(am, db_type);
    // A cancel that fires while the driver lock is held elsewhere must abort
    // promptly instead of waiting for the lock holder to finish.
    let owned_tokens;
    let command_tokens: &[&AgentInstallCancellation] = match cancellation {
        Some(token) => {
            owned_tokens = [token.as_ref()];
            &owned_tokens
        }
        None => &[],
    };
    let _driver_guard = lock_or_cancel(&driver_lock, command_tokens).await?;
    // Use the command-scoped token when one was registered before any awaitable
    // setup (blocker check, lock wait, registry fetch) so a cancel fired during
    // that window is observed here instead of being lost. Otherwise register a
    // token owned by this call keyed by a fresh operation id so two concurrent
    // installs of the same driver cannot replace each other's token.
    let owned_operation_id: Option<String> =
        if cancellation.is_some() { None } else { Some(uuid::Uuid::new_v4().to_string()) };
    let owned_cancellation: Option<Arc<AgentInstallCancellation>> = match owned_operation_id.as_deref() {
        Some(operation_id) => Some(am.begin_install_cancellation(&install_cancellation_key(operation_id)).await),
        None => None,
    };
    let active_cancellation: &AgentInstallCancellation = owned_cancellation
        .as_deref()
        .or_else(|| cancellation.map(|token| token.as_ref()))
        .expect("a cancellation token is always available");
    if active_cancellation.is_cancelled() {
        if let (Some(operation_id), Some(token)) = (owned_operation_id.as_deref(), owned_cancellation.as_ref()) {
            am.finish_install_cancellation(&install_cancellation_key(operation_id), token).await;
        }
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }

    let result = install_agent_driver_with_batch_unlocked(
        am,
        db_type,
        source,
        progress,
        current,
        total_drivers,
        &[active_cancellation],
    )
    .await;

    if let (Some(operation_id), Some(token)) = (owned_operation_id.as_deref(), owned_cancellation.as_ref()) {
        am.finish_install_cancellation(&install_cancellation_key(operation_id), token).await;
    }
    result
}

async fn install_agent_driver_from_registry_locked(
    am: &AgentManager,
    registry: &AgentRegistry,
    source: DownloadSource,
    db_type: &str,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    let _installation_guard = am.installation_operation_lock.read().await;
    let driver_lock = driver_operation_lock(am, db_type);
    assert!(!cancellations.is_empty(), "batch driver cancellation token is always registered");
    // A cancelled batch row must not wait for the current lock holder to
    // finish before observing its cancellation tokens.
    let _driver_guard = lock_or_cancel(&driver_lock, cancellations).await?;
    install_agent_driver_from_registry(am, registry, source, db_type, progress, current, total_drivers, cancellations)
        .await
}

async fn install_agent_driver_with_batch_unlocked(
    am: &AgentManager,
    db_type: &str,
    source: DownloadSource,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    match fetch_registry_from_claimed(source, cancellations).await {
        Ok(registry) => {
            match install_agent_driver_from_registry(
                am,
                &registry,
                source,
                db_type,
                progress,
                current,
                total_drivers,
                cancellations,
            )
            .await
            {
                Ok(()) => Ok(()),
                Err(registry_err) => {
                    // Cancellation is terminal, not a registry failure. Falling
                    // back here would install a bundled JAR after the user
                    // explicitly aborted the download.
                    if can_fallback_to_local_agent(am, db_type, cancellations).await {
                        if let Some(local_jar) = find_local_agent_jar(db_type) {
                            install_local_agent_with_registry_jre(
                                am,
                                &registry,
                                source,
                                db_type,
                                local_jar,
                                progress,
                                current,
                                total_drivers,
                                cancellations,
                            )
                            .await?;
                            return Ok(());
                        }
                    }
                    Err(registry_err)
                }
            }
        }
        Err(registry_err) => {
            // The registry fetch observes cancellation, so the cancel error
            // must not start the local fallback (the fallback guard refuses it
            // anyway because the same tokens are cancelled).
            if can_fallback_to_local_agent(am, db_type, cancellations).await {
                if let Some(local_jar) = find_local_agent_jar(db_type) {
                    stop_driver_processes_before_replacement(am, db_type).await?;
                    install_local_agent(am, db_type, local_jar)?;
                    progress(AgentProgressEvent::step("done").with_batch(Some(db_type), current, total_drivers));
                    return Ok(());
                }
            }
            Err(registry_err)
        }
    }
}

async fn ensure_jre_from_registry(
    am: &AgentManager,
    registry: &AgentRegistry,
    source: DownloadSource,
    jre_key: &str,
    db_type: &str,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    // Fast path: already installed — return immediately without acquiring the
    // per-JRE lock.  The lock is only needed when a download + extract may be
    // required.
    if !jre_needs_install(am, registry, jre_key) {
        return Ok(());
    }

    // Acquire (or create) the per-JRE-key mutex so that concurrent driver
    // installs sharing the same JRE download it exactly once.
    let lock = jre_operation_lock(am, jre_key);
    // A cancel that fires while another install holds the JRE lock must abort
    // promptly instead of waiting for the lock holder to finish.
    let _jre_guard = lock_or_cancel(&lock, cancellations).await?;

    // Double-check: the previous lock holder may have already installed.
    if !jre_needs_install(am, registry, jre_key) {
        return Ok(());
    }

    let jre_info = registry.resolve_jre(jre_key).ok_or_else(|| format!("No JRE definition for version: {jre_key}"))?;
    let platform = AgentManager::current_platform();
    let platform_jre = jre_info
        .platforms
        .get(platform)
        .ok_or_else(|| format!("No JRE {jre_key} available for platform: {platform}"))?;
    let jre_archive = jre_archive_download_path(am, jre_key, platform_jre.format);
    progress(AgentProgressEvent::transfer("jre", 0, platform_jre.size).with_batch(
        Some(db_type),
        current,
        total_drivers,
    ));
    download_with_progress(
        am,
        progress,
        "jre",
        source,
        &platform_jre.url,
        &r2_path_with_cache_buster(&github_url_to_r2_path(&platform_jre.url, "jre"), &jre_info.version),
        &jre_archive,
        platform_jre.size,
        platform_jre.sha256.as_deref(),
        Some(CacheIdentity::Jre { key: jre_key, version: &jre_info.version }),
        Some(db_type),
        current,
        total_drivers,
        cancellations,
    )
    .await?;
    // A cancel may have fired right after the download completed but before we
    // replace the JRE directory — don't leave a half-extracted runtime.
    if cancellations.iter().any(|token| token.is_cancelled()) {
        std::fs::remove_file(&jre_archive).ok();
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }
    progress(AgentProgressEvent::transfer("jre-extract", 0, 0).with_batch(Some(db_type), current, total_drivers));
    let jre_dir = am.jre_dir(jre_key);
    // Stop only daemons that use this JRE before replacing its directory
    // (Windows ERROR_ACCESS_DENIED, Issue #1100).  In a concurrent
    // upgrade-all this avoids killing unrelated daemons mid-install.
    stop_jre_processes_before_replacement(am, jre_key).await?;
    let stash = replace_old_jre_dir(&jre_dir)?;

    // Persist the stash path *before* extraction so that a crash during
    // archive extraction (or a process kill) doesn't leave the renamed-stash
    // directory as an orphan that never gets cleaned up.
    persist_pending_jre_cleanup(am, stash.as_ref()).await?;

    extract_jre_archive(&jre_archive, &jre_dir, platform_jre.format)?;
    std::fs::remove_file(&jre_archive).ok();
    cleanup_jre_download_cache_after_success(am, jre_key);

    // Persist the JRE version after extraction succeeds, while still holding
    // the per-JRE lock.  This guarantees the DCL in another task's
    // jre_needs_install() sees the installed version and skips download.
    am.mutate_state(|state| state.jre_versions.insert(jre_key.to_string(), jre_info.version.clone()))?;

    Ok(())
}

/// Stop daemons whose installed driver actually runs on `jre_key`.
async fn stop_daemons_using_jre(am: &AgentManager, jre_key: &str) {
    let state = am.load_state();
    let keys: Vec<String> = state
        .installed_drivers
        .keys()
        .filter(|db_type| am.installed_driver_jre_dependency(&state, db_type) == Some(jre_key))
        .cloned()
        .collect();
    for db_type in keys {
        am.stop_daemon_by_key(&db_type).await;
    }
}

/// Record a rename-stashed JRE before extraction so startup can clean it up
/// even if the process exits mid-install.
async fn persist_pending_jre_cleanup(am: &AgentManager, stash: Option<&PathBuf>) -> Result<(), String> {
    let Some(stash_path) = stash else {
        return Ok(());
    };

    am.mutate_state(|state| {
        if !state.pending_jre_cleanup.contains(stash_path) {
            state.pending_jre_cleanup.push(stash_path.clone());
        }
    })
}

async fn persist_local_agent_install_state(
    am: &AgentManager,
    db_type: &str,
    jre_key: &str,
    jre_version: Option<&str>,
) -> Result<(), String> {
    am.mutate_state(|state| {
        if let Some(version) = jre_version {
            state.jre_versions.insert(jre_key.to_string(), version.to_string());
        }
        record_local_agent_install(state, db_type, jre_key);
    })
}

fn ensure_local_agent_commit_allowed(cancellations: &[&AgentInstallCancellation]) -> Result<(), String> {
    if cancellations.iter().any(|token| token.is_cancelled()) {
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }
    Ok(())
}

async fn commit_local_agent_install(
    am: &AgentManager,
    db_type: &str,
    local_jar: &Path,
    jre_key: &str,
    jre_version: Option<&str>,
) -> Result<(), String> {
    stop_driver_processes_before_replacement(am, db_type).await?;
    install_local_agent_file(am, db_type, local_jar)?;
    persist_local_agent_install_state(am, db_type, jre_key, jre_version).await
}

async fn install_local_agent_with_registry_jre(
    am: &AgentManager,
    registry: &AgentRegistry,
    source: DownloadSource,
    db_type: &str,
    local_jar: PathBuf,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    let jre_key = DEFAULT_JRE_KEY;
    if jre_needs_install(am, registry, jre_key) {
        ensure_jre_from_registry(
            am,
            registry,
            source,
            jre_key,
            db_type,
            progress,
            current,
            total_drivers,
            cancellations,
        )
        .await?;
    }
    ensure_local_agent_commit_allowed(cancellations)?;
    commit_local_agent_install(
        am,
        db_type,
        &local_jar,
        jre_key,
        registry.resolve_jre(jre_key).map(|jre| jre.version.as_str()),
    )
    .await?;
    progress(AgentProgressEvent::step("done").with_batch(Some(db_type), current, total_drivers));
    Ok(())
}

async fn install_sqlite_worker_from_registry(
    am: &AgentManager,
    source: DownloadSource,
    db_type: &str,
    driver: &crate::agent_manager::DriverInfo,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    let jre_key = &driver.jre;
    std::fs::create_dir_all(am.driver_dir(db_type))
        .map_err(|err| format!("Failed to create driver directory: {err}"))?;
    for platform in SQLITE_WORKER_NATIVE_PLATFORMS {
        let artifact = driver
            .native
            .get(*platform)
            .ok_or_else(|| format!("SQLite SSH worker registry is missing the {platform} native package"))?;
        let target_path = am.driver_native_platform_path(db_type, platform);
        let download_path = driver_artifact_download_path(&target_path, artifact.format);
        progress(AgentProgressEvent::transfer("driver", 0, artifact.size).with_batch(
            Some(db_type),
            current,
            total_drivers,
        ));
        obtain_driver_artifact(
            am,
            progress,
            source,
            artifact,
            db_type,
            &driver.version,
            &download_path,
            current,
            total_drivers,
            cancellations,
        )
        .await?;
        if cancellations.iter().any(|token| token.is_cancelled()) {
            std::fs::remove_file(&download_path).ok();
            return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
        }
        install_downloaded_driver_artifact(
            &download_path,
            &target_path,
            artifact.format,
            DriverArtifactKind::Native,
            db_type,
            &driver.version,
            Some(platform),
        )?;
        mark_executable(&target_path)?;
    }
    std::fs::remove_file(am.driver_jar_path(db_type)).ok();
    std::fs::remove_file(am.driver_native_path(db_type)).ok();
    am.mutate_state(|state| {
        state.installed_drivers.insert(
            db_type.to_string(),
            InstalledDriver {
                version: driver.version.clone(),
                installed_at: chrono::Utc::now().to_rfc3339(),
                jre: jre_key.clone(),
            },
        );
    })?;
    am.stop_daemon_by_key(db_type).await;
    cleanup_driver_download_cache_after_success(am, db_type);
    progress(AgentProgressEvent::step("done").with_batch(Some(db_type), current, total_drivers));
    Ok(())
}

async fn install_agent_driver_from_registry(
    am: &AgentManager,
    registry: &AgentRegistry,
    source: DownloadSource,
    db_type: &str,
    progress: &impl Fn(AgentProgressEvent),
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    let Some(driver) = agent_registry_driver(registry, db_type) else {
        if let Some(local_jar) = find_local_agent_jar(db_type) {
            install_local_agent_with_registry_jre(
                am,
                registry,
                source,
                db_type,
                local_jar,
                progress,
                current,
                total_drivers,
                cancellations,
            )
            .await?;
            return Ok(());
        }
        return Err(format!("Unknown driver type: {db_type}"));
    };
    if AgentManager::is_sqlite_worker_driver(db_type) {
        return install_sqlite_worker_from_registry(
            am,
            source,
            db_type,
            driver,
            progress,
            current,
            total_drivers,
            cancellations,
        )
        .await;
    }
    let jre_key = &driver.jre;
    let native_artifact = driver.native.get(AgentManager::current_platform());
    let jar_artifact = usable_driver_jar(driver);
    // Java is only required when the JAR fallback is what actually gets
    // installed. A driver that publishes no artifact for this platform at all
    // (the Windows-only Oracle OCI agent on macOS, for example) must fail
    // immediately instead of downloading and unpacking a JRE it cannot use.
    let requires_java_runtime = native_artifact.is_none() && jar_artifact.is_some();
    let needs_jre = requires_java_runtime && jre_needs_install(am, registry, jre_key);

    if needs_jre {
        ensure_jre_from_registry(
            am,
            registry,
            source,
            jre_key,
            db_type,
            progress,
            current,
            total_drivers,
            cancellations,
        )
        .await?;
    }

    let (artifact, target_path, is_native_artifact) = if let Some(native) = native_artifact {
        (native, am.driver_native_path(db_type), true)
    } else if let Some(jar) = jar_artifact {
        (jar, am.driver_jar_path(db_type), false)
    } else {
        return Err(format!("No driver artifact available for {db_type}"));
    };
    if let Some(parent) = target_path.parent() {
        std::fs::create_dir_all(parent).map_err(|err| format!("Failed to create driver directory: {err}"))?;
    }
    let artifact_kind = if is_native_artifact { DriverArtifactKind::Native } else { DriverArtifactKind::Jar };
    let download_path = driver_artifact_download_path(&target_path, artifact.format);
    progress(AgentProgressEvent::transfer("driver", 0, artifact.size).with_batch(
        Some(db_type),
        current,
        total_drivers,
    ));
    obtain_driver_artifact(
        am,
        progress,
        source,
        artifact,
        db_type,
        &driver.version,
        &download_path,
        current,
        total_drivers,
        cancellations,
    )
    .await?;
    // A cancel may have fired after the download completed but before the
    // artifact is moved into place — drop the partial artifact and bail.
    if cancellations.iter().any(|token| token.is_cancelled()) {
        std::fs::remove_file(&download_path).ok();
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }
    // Retain the artifact bytes for future incremental updates before the
    // install consumes (and deletes) the staged download.
    retain_driver_delta_base(am, db_type, &driver.version, &download_path);
    stop_driver_processes_before_replacement(am, db_type).await?;
    install_downloaded_driver_artifact(
        &download_path,
        &target_path,
        artifact.format,
        artifact_kind,
        db_type,
        &driver.version,
        is_native_artifact.then_some(AgentManager::current_platform()),
    )?;
    // Some drivers publish both a native agent and a legacy JAR fallback. Only
    // validate the artifact type that was actually installed.
    if is_native_artifact {
        mark_executable(&target_path)?;
        std::fs::remove_file(am.driver_jar_path(db_type)).ok();
    } else {
        if !am.is_driver_jar_valid(db_type) {
            std::fs::remove_file(&target_path).ok();
            return Err(format!("Downloaded driver jar is invalid or corrupt: {}", target_path.display()));
        }
        std::fs::remove_file(am.driver_native_path(db_type)).ok();
    }

    // The cancellation boundary is immediately before the staged artifact is
    // committed above. After that atomic replacement, treating a newly arrived
    // cancel as a rollback would delete a working driver and lose the prior
    // installation, so this completed install must persist normally.
    am.mutate_state(|state| {
        if requires_java_runtime {
            if let Some(jre_info) = registry.resolve_jre(jre_key) {
                state.jre_versions.insert(jre_key.clone(), jre_info.version.clone());
            }
        }
        state.installed_drivers.insert(
            db_type.to_string(),
            InstalledDriver {
                version: driver.version.clone(),
                installed_at: chrono::Utc::now().to_rfc3339(),
                jre: jre_key.clone(),
            },
        );
    })?;
    cleanup_driver_download_cache_after_success(am, db_type);
    progress(AgentProgressEvent::step("done").with_batch(Some(db_type), current, total_drivers));
    Ok(())
}

fn driver_artifact_download_path(target_path: &Path, format: Option<ArtifactFormat>) -> PathBuf {
    let parent = target_path.parent().unwrap_or_else(|| Path::new("."));
    let file_name = target_path.file_name().and_then(|name| name.to_str()).unwrap_or("agent");
    match format {
        Some(ArtifactFormat::TarZstd) => parent.join(format!(".{file_name}.tar.zst")),
        // Keep raw artifacts out of the live driver path until the caller has
        // made its final cancellation check. The filename stays stable so an
        // existing download-cache entry remains reusable.
        None => parent.join(".staging").join(file_name),
    }
}

fn install_downloaded_driver_artifact(
    download_path: &Path,
    target_path: &Path,
    format: Option<ArtifactFormat>,
    artifact_kind: DriverArtifactKind,
    db_type: &str,
    expected_version: &str,
    native_platform: Option<&str>,
) -> Result<(), String> {
    let result = match format {
        None => replace_download(download_path, target_path),
        Some(ArtifactFormat::TarZstd) => install_driver_from_tar_zstd_package(
            download_path,
            target_path,
            artifact_kind,
            db_type,
            expected_version,
            native_platform,
        ),
    };
    if result.is_ok() {
        std::fs::remove_file(download_path).ok();
    }
    result
}

fn install_driver_from_tar_zstd_package(
    package_path: &Path,
    target_path: &Path,
    expected_kind: DriverArtifactKind,
    db_type: &str,
    expected_version: &str,
    native_platform: Option<&str>,
) -> Result<(), String> {
    let info = tar_zstd_driver_package_info(package_path)?;
    if info.db_type != db_type {
        return Err(format!("Driver package contains {}, expected {db_type}", info.db_type));
    }
    if info.version != expected_version {
        return Err(format!(
            "Driver package version mismatch for {db_type}: expected {expected_version}, got {}",
            info.version
        ));
    }
    if info.kind != expected_kind {
        return Err(format!(
            "Driver package artifact type mismatch for {db_type}: expected {}, got {}",
            expected_kind.label(),
            info.kind.label()
        ));
    }
    let parent = target_path.parent().ok_or_else(|| format!("Invalid driver path: {}", target_path.display()))?;
    std::fs::create_dir_all(parent).map_err(|error| format!("Failed to create driver directory: {error}"))?;
    let staging_path = parent.join(format!(".agent-package-{}", uuid::Uuid::new_v4()));
    let result = extract_tar_zstd_file(package_path, &info.entry_name, &staging_path, info.size).and_then(|_| {
        match info.kind {
            DriverArtifactKind::Jar if !is_valid_agent_jar(&staging_path) => {
                return Err(format!("Packaged driver jar is invalid or corrupt: {}", info.entry_name));
            }
            DriverArtifactKind::Native => {
                let platform = native_platform
                    .or(info.native_platform.as_deref())
                    .unwrap_or_else(|| AgentManager::current_platform());
                validate_native_agent_binary_for_platform(&staging_path, platform)?;
                mark_executable(&staging_path)?;
            }
            DriverArtifactKind::Jar => {}
        }
        replace_download(&staging_path, target_path)
    });
    if result.is_err() {
        std::fs::remove_file(&staging_path).ok();
    }
    result
}

fn read_registry_from_tar_zstd(package_path: &Path) -> Result<AgentRegistry, String> {
    const MAX_REGISTRY_BYTES: u64 = 1024 * 1024;

    let file = std::fs::File::open(package_path).map_err(|error| format!("Failed to open driver package: {error}"))?;
    let decoder = zstd::stream::read::Decoder::new(file)
        .map_err(|error| format!("Failed to open zstd driver package: {error}"))?;
    let mut archive = tar::Archive::new(decoder);
    let entries = archive.entries().map_err(|error| format!("Invalid tar.zst driver package: {error}"))?;
    for entry in entries {
        let mut entry = entry.map_err(|error| format!("Invalid tar.zst driver package entry: {error}"))?;
        let path = entry.path().map_err(|error| format!("Invalid driver package path: {error}"))?;
        let name = safe_archive_entry_name(&path)?;
        if name != "agent-registry.json" {
            continue;
        }
        if !entry.header().entry_type().is_file() {
            return Err("Driver package registry is not a regular file".to_string());
        }
        if entry.size() > MAX_REGISTRY_BYTES {
            return Err("Driver package registry is too large".to_string());
        }
        let mut json = String::new();
        entry.read_to_string(&mut json).map_err(|error| format!("Failed to read driver package registry: {error}"))?;
        return serde_json::from_str(&json).map_err(|error| format!("Invalid driver package registry: {error}"));
    }
    Err("agent-registry.json not found in the driver package".to_string())
}

fn extract_tar_zstd_file(
    package_path: &Path,
    expected_entry: &str,
    destination: &Path,
    expected_size: u64,
) -> Result<(), String> {
    let file = std::fs::File::open(package_path).map_err(|error| format!("Failed to open driver package: {error}"))?;
    let decoder = zstd::stream::read::Decoder::new(file)
        .map_err(|error| format!("Failed to open zstd driver package: {error}"))?;
    let mut archive = tar::Archive::new(decoder);
    let entries = archive.entries().map_err(|error| format!("Invalid tar.zst driver package: {error}"))?;
    let mut extracted = false;
    for entry in entries {
        let mut entry = entry.map_err(|error| format!("Invalid tar.zst driver package entry: {error}"))?;
        let path = entry.path().map_err(|error| format!("Invalid driver package path: {error}"))?;
        let name = safe_archive_entry_name(&path)?;
        if name == "agent-registry.json" || entry.header().entry_type().is_dir() {
            continue;
        }
        if name != expected_entry {
            return Err(format!("Unexpected file in driver package: {name}"));
        }
        if extracted || !entry.header().entry_type().is_file() {
            return Err(format!("Invalid driver package entry: {name}"));
        }
        let mut output =
            std::fs::File::create(destination).map_err(|error| format!("Failed to create staged driver: {error}"))?;
        let copied = std::io::copy(&mut entry, &mut output)
            .map_err(|error| format!("Failed to extract driver package: {error}"))?;
        std::io::Write::flush(&mut output).map_err(|error| format!("Failed to flush staged driver: {error}"))?;
        if expected_size > 0 && copied != expected_size {
            return Err(format!("Packaged driver size mismatch: expected {expected_size} bytes, got {copied} bytes"));
        }
        extracted = true;
    }
    if extracted {
        Ok(())
    } else {
        Err(format!("Driver package entry not found: {expected_entry}"))
    }
}

fn safe_archive_entry_name(path: &Path) -> Result<String, String> {
    let mut parts = Vec::new();
    for component in path.components() {
        match component {
            std::path::Component::Normal(value) => parts.push(value.to_string_lossy().into_owned()),
            std::path::Component::CurDir => {}
            _ => return Err(format!("Unsafe driver package path: {}", path.display())),
        }
    }
    if parts.is_empty() {
        return Err("Driver package contains an empty path".to_string());
    }
    Ok(parts.join("/"))
}

fn agent_registry_driver<'a>(
    registry: &'a AgentRegistry,
    db_type: &str,
) -> Option<&'a crate::agent_manager::DriverInfo> {
    registry.drivers.get(db_type)
}

/// Downloads `artifact` for installation, preferring the registry's
/// incremental delta when a matching base artifact was retained by a previous
/// install of `db_type`. The staged full artifact lands at `dest` either way;
/// every delta failure falls back to a full download.
#[allow(clippy::too_many_arguments)]
async fn obtain_driver_artifact(
    am: &AgentManager,
    progress: &impl Fn(AgentProgressEvent),
    source: DownloadSource,
    artifact: &crate::agent_manager::ArtifactInfo,
    db_type: &str,
    driver_version: &str,
    dest: &Path,
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    if let Some(delta) = artifact.delta.as_ref() {
        let base = crate::driver_delta::find_delta_base(&am.download_cache_dir(), db_type, &delta.base_version);
        if let Some(base) = base {
            match try_delta_artifact(
                am,
                progress,
                source,
                artifact,
                delta,
                &base,
                db_type,
                driver_version,
                dest,
                current,
                total_drivers,
                cancellations,
            )
            .await
            {
                Ok(()) => {
                    log::info!(
                        "[driver-delta:{db_type}] applied incremental update {} -> {} (delta {} bytes of a {} byte artifact)",
                        delta.base_version,
                        driver_version,
                        delta.size,
                        artifact.size
                    );
                    return Ok(());
                }
                Err(err) => {
                    log::warn!(
                        "[driver-delta:{db_type}] incremental update failed, falling back to full download: {err}"
                    );
                    let _ = std::fs::remove_file(dest);
                }
            }
        }
    }
    download_with_progress(
        am,
        progress,
        "driver",
        source,
        &artifact.url,
        &r2_path_with_cache_buster(&github_url_to_r2_path(&artifact.url, "driver"), driver_version),
        dest,
        artifact.size,
        artifact.sha256.as_deref(),
        Some(CacheIdentity::Driver { db_type, version: driver_version }),
        Some(db_type),
        current,
        total_drivers,
        cancellations,
    )
    .await
}

/// Downloads the delta frame and reconstructs the full artifact onto `dest`.
/// The reconstructed bytes are verified against the full artifact's size and
/// SHA-256; a mismatching (e.g. corrupt) base is caught here and reported as a
/// plain error so the caller can fall back to a full download.
#[allow(clippy::too_many_arguments)]
async fn try_delta_artifact(
    am: &AgentManager,
    progress: &impl Fn(AgentProgressEvent),
    source: DownloadSource,
    artifact: &crate::agent_manager::ArtifactInfo,
    delta: &crate::agent_manager::DeltaInfo,
    base: &Path,
    db_type: &str,
    driver_version: &str,
    dest: &Path,
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    let file_name = dest
        .file_name()
        .and_then(|value| value.to_str())
        .ok_or_else(|| "Driver artifact has no file name".to_string())?;
    let delta_path = dest
        .parent()
        .ok_or_else(|| "Driver artifact has no parent directory".to_string())?
        .join(format!(".{file_name}.delta"));
    let cache_buster_version = format!("{driver_version}-from-{}", delta.base_version);
    download_with_progress(
        am,
        progress,
        "driver",
        source,
        &delta.url,
        &r2_path_with_cache_buster(&github_url_to_r2_path(&delta.url, "driver"), &cache_buster_version),
        &delta_path,
        delta.size,
        Some(delta.sha256.as_str()),
        Some(CacheIdentity::Driver { db_type, version: &cache_buster_version }),
        Some(db_type),
        current,
        total_drivers,
        cancellations,
    )
    .await?;
    let outcome = crate::driver_delta::apply_zstd_delta(base, &delta_path, dest)
        .and_then(|()| validate_artifact_integrity(dest, artifact.size, artifact.sha256.as_deref()));
    let _ = std::fs::remove_file(&delta_path);
    outcome
}

#[allow(clippy::too_many_arguments)]
async fn download_with_progress(
    am: &AgentManager,
    progress: &impl Fn(AgentProgressEvent),
    step: &str,
    source: DownloadSource,
    url: &str,
    r2_path: &str,
    dest: &std::path::Path,
    total_size: u64,
    expected_sha256: Option<&str>,
    cache_identity: Option<CacheIdentity<'_>>,
    db_type: Option<&str>,
    current: Option<u32>,
    total_drivers: Option<u32>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(), String> {
    const DOWNLOAD_ATTEMPTS: usize = 4;
    let expected_sha256 = normalized_sha256(expected_sha256)?;
    // Observe the exact operation tokens threaded from the command layer: a
    // single install passes its own token; a batch passes BOTH the row token
    // and the batch token so a batch cancel-all interrupts a driver whose
    // download already started. An empty slice means "no cancellation" for the
    // offline/auto paths.
    let any_cancelled = || cancellations.iter().any(|token| token.is_cancelled());
    if any_cancelled() {
        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
    }

    if let Some(parent) = dest.parent() {
        std::fs::create_dir_all(parent).map_err(|err| err.to_string())?;
    }
    let tmp = download_temp_path(dest);
    let tmp_source = download_source_path(&tmp);
    let cache_path = cached_download_path(am, url, total_size, expected_sha256, cache_identity, dest);
    prune_download_cache(am).ok();
    if cached_download_is_valid(am, &cache_path, total_size, expected_sha256) {
        if any_cancelled() {
            return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
        }
        std::fs::copy(&cache_path, &tmp).map_err(|err| format!("Failed to copy cached download: {err}"))?;
        progress(AgentProgressEvent::transfer(step, total_size, total_size).with_batch(
            db_type,
            current,
            total_drivers,
        ));
        return replace_download(&tmp, dest);
    }

    let client = reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(300))
        .build()
        .map_err(|err| format!("Failed to create HTTP client: {err}"))?;
    let mut last_err = None;
    let mut completed = false;
    let mut rejected_sources = std::collections::HashSet::new();
    for attempt in 1..=DOWNLOAD_ATTEMPTS {
        if any_cancelled() {
            std::fs::remove_file(&tmp).ok();
            std::fs::remove_file(&tmp_source).ok();
            return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
        }
        let mut resume_from = std::fs::metadata(&tmp).map(|meta| meta.len()).unwrap_or(0);
        let resume_source = std::fs::read_to_string(&tmp_source).ok().map(|value| value.trim().to_string());
        if resume_from > 0 && resume_source.is_none() {
            std::fs::remove_file(&tmp).ok();
            resume_from = 0;
        }
        if total_size > 0 && resume_from > total_size {
            std::fs::remove_file(&tmp).ok();
            std::fs::remove_file(&tmp_source).ok();
            resume_from = 0;
        }
        if total_size > 0 && resume_from == total_size {
            match validate_artifact_integrity(&tmp, total_size, expected_sha256) {
                Ok(()) => {
                    progress(AgentProgressEvent::transfer(step, total_size, total_size).with_batch(
                        db_type,
                        current,
                        total_drivers,
                    ));
                    completed = true;
                    break;
                }
                Err(err) => {
                    if let Some(source_url) = resume_source {
                        rejected_sources.insert(source_url);
                    }
                    std::fs::remove_file(&tmp).ok();
                    std::fs::remove_file(&tmp_source).ok();
                    last_err = Some(err);
                    continue;
                }
            }
        }

        let (mut resp, resumed, source_url) = match open_agent_download_response(
            &client,
            source,
            url,
            r2_path,
            "dbx-agent-manager",
            resume_from,
            total_size,
            resume_source.as_deref(),
            &rejected_sources,
            cancellations,
        )
        .await
        {
            Ok(value) => value,
            Err(err) => {
                if resume_from > 0 {
                    std::fs::remove_file(&tmp).ok();
                    std::fs::remove_file(&tmp_source).ok();
                }
                last_err = Some(err);
                continue;
            }
        };
        let starting_size = if resumed { resume_from } else { 0 };
        let content_length = total_size.max(starting_size + resp.content_length().unwrap_or(0));
        let mut file = if resumed {
            std::fs::OpenOptions::new()
                .append(true)
                .open(&tmp)
                .map_err(|err| format!("Failed to open temp file for resume: {err}"))?
        } else {
            std::fs::File::create(&tmp).map_err(|err| format!("Failed to create temp file: {err}"))?
        };
        std::fs::write(&tmp_source, &source_url).map_err(|err| format!("Failed to write download source: {err}"))?;
        let mut downloaded = starting_size;
        let mut transfer_gate = TransferProgressGate::new(content_length);
        let transfer_result = async {
            if cancellations.is_empty() {
                while let Some(chunk) = resp.chunk().await.map_err(|err| format!("Download stream error: {err}"))? {
                    std::io::Write::write_all(&mut file, &chunk)
                        .map_err(|err| format!("Failed to write chunk: {err}"))?;
                    downloaded += chunk.len() as u64;
                    if transfer_gate.record(downloaded, std::time::Instant::now()) {
                        progress(AgentProgressEvent::transfer(step, downloaded, content_length).with_batch(
                            db_type,
                            current,
                            total_drivers,
                        ));
                    }
                }
                return std::io::Write::flush(&mut file).map_err(|err| format!("Failed to flush temp file: {err}"));
            }
            // Cancellation tokens are registered: await the stream and every
            // cancel signal concurrently so any token (row-level or batch-level)
            // aborts mid-stream.
            loop {
                tokio::select! {
                    chunk = resp.chunk() => {
                        let chunk = chunk.map_err(|err| format!("Download stream error: {err}"))?;
                        match chunk {
                            Some(chunk) => {
                                std::io::Write::write_all(&mut file, &chunk)
                                    .map_err(|err| format!("Failed to write chunk: {err}"))?;
                                downloaded += chunk.len() as u64;
                                if transfer_gate.record(downloaded, std::time::Instant::now()) {
                                    progress(AgentProgressEvent::transfer(step, downloaded, content_length)
                                        .with_batch(db_type, current, total_drivers));
                                }
                            }
                            None => break,
                        }
                    }
                    _ = first_cancellation(cancellations) => {
                        return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
                    }
                }
            }
            std::io::Write::flush(&mut file).map_err(|err| format!("Failed to flush temp file: {err}"))
        }
        .await;
        drop(file);

        if let Err(err) = transfer_result {
            if any_cancelled() {
                std::fs::remove_file(&tmp).ok();
                std::fs::remove_file(&tmp_source).ok();
                return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
            }
            last_err = Some(format!("{err} (attempt {attempt}/{DOWNLOAD_ATTEMPTS}, source {source_url})"));
            continue;
        }

        // The gate may have suppressed the final chunk; always publish the
        // completed transfer so the UI reaches 100% before integrity validation.
        progress(AgentProgressEvent::transfer(step, downloaded, content_length).with_batch(
            db_type,
            current,
            total_drivers,
        ));

        let actual_size = std::fs::metadata(&tmp).map(|meta| meta.len()).unwrap_or(0);
        if total_size == 0 || actual_size == total_size {
            match validate_artifact_integrity(&tmp, total_size, expected_sha256) {
                Ok(()) => {
                    completed = true;
                    break;
                }
                Err(err) => {
                    rejected_sources.insert(source_url.clone());
                    std::fs::remove_file(&tmp).ok();
                    std::fs::remove_file(&tmp_source).ok();
                    last_err = Some(format!("{err} (attempt {attempt}/{DOWNLOAD_ATTEMPTS}, source {source_url})"));
                    continue;
                }
            }
        }
        if actual_size > total_size {
            std::fs::remove_file(&tmp).ok();
            std::fs::remove_file(&tmp_source).ok();
        }
        last_err = Some(format!(
            "Downloaded {step} is incomplete: expected {total_size} bytes, got {actual_size} bytes (attempt {attempt}/{DOWNLOAD_ATTEMPTS}, source {source_url})"
        ));
    }
    if !completed {
        if any_cancelled() {
            std::fs::remove_file(&tmp).ok();
            std::fs::remove_file(&tmp_source).ok();
            return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string());
        }
        let actual_size = std::fs::metadata(&tmp).map(|meta| meta.len()).unwrap_or(0);
        return Err(last_err.unwrap_or_else(|| {
            format!("Downloaded {step} is incomplete: expected {total_size} bytes, got {actual_size} bytes")
        }));
    }
    std::fs::remove_file(&tmp_source).ok();
    if let Some(parent) = cache_path.parent() {
        if let Err(err) = std::fs::create_dir_all(parent) {
            log::warn!("Failed to create agent download cache directory: {err}");
        } else if let Err(err) = std::fs::copy(&tmp, &cache_path) {
            log::warn!("Failed to cache agent download: {err}");
        }
    }
    replace_download(&tmp, dest)
}

async fn open_agent_download_response(
    client: &reqwest::Client,
    source: DownloadSource,
    github_url: &str,
    r2_path: &str,
    user_agent: &str,
    resume_from: u64,
    expected_size: u64,
    resume_source: Option<&str>,
    rejected_sources: &std::collections::HashSet<String>,
    cancellations: &[&AgentInstallCancellation],
) -> Result<(reqwest::Response, bool, String), String> {
    let mut errors = Vec::new();
    for candidate_url in source.download_candidate_urls(github_url, r2_path)? {
        if rejected_sources.contains(&candidate_url) {
            errors.push(format!("{candidate_url}: skipped after SHA-256 mismatch"));
            continue;
        }
        if resume_from > 0 && resume_source.is_some_and(|source| source != candidate_url) {
            continue;
        }
        let mut request = client
            .get(&candidate_url)
            .header(reqwest::header::USER_AGENT, user_agent)
            .header(reqwest::header::ACCEPT_ENCODING, "identity");
        if resume_from > 0 {
            request = request.header(reqwest::header::RANGE, format!("bytes={resume_from}-"));
        }
        // Race the request with cancellation: a stalled mirror that never
        // returns response headers must not hold the install hostage until
        // the 300s client timeout. Dropping the send future aborts it.
        let resp = if cancellations.is_empty() {
            match request.send().await {
                Ok(resp) => resp,
                Err(err) => {
                    errors.push(format!("{candidate_url}: {err}"));
                    continue;
                }
            }
        } else {
            tokio::select! {
                result = request.send() => match result {
                    Ok(resp) => resp,
                    Err(err) => {
                        errors.push(format!("{candidate_url}: {err}"));
                        continue;
                    }
                },
                _ = first_cancellation(cancellations) => return Err(AGENT_DOWNLOAD_CANCELED_ERROR.to_string()),
            }
        };
        let status = resp.status();
        if expected_size > 0 {
            let response_size = response_total_size(&resp, resume_from);
            if response_size != Some(expected_size) {
                let found = response_size.map_or_else(|| "unknown".to_string(), |size| size.to_string());
                errors.push(format!(
                    "{candidate_url}: artifact size mismatch, expected {expected_size} bytes, got {found} bytes"
                ));
                continue;
            }
        }
        if resume_from > 0 && status == reqwest::StatusCode::PARTIAL_CONTENT {
            return Ok((resp, true, candidate_url));
        }
        if status.is_success() {
            return match resp.error_for_status() {
                Ok(resp) => Ok((resp, false, candidate_url)),
                Err(err) => Err(format!("{candidate_url}: {err}")),
            };
        }
        errors.push(format!("{candidate_url}: HTTP {status}"));
    }
    Err(format!("Failed to download artifact: {}", errors.join("; ")))
}

fn response_total_size(resp: &reqwest::Response, resume_from: u64) -> Option<u64> {
    if resp.status() == reqwest::StatusCode::PARTIAL_CONTENT {
        return resp
            .headers()
            .get(reqwest::header::CONTENT_RANGE)
            .and_then(|value| value.to_str().ok())
            .and_then(content_range_total_size);
    }
    resp.content_length().map(|size| size + resume_from)
}

fn content_range_total_size(value: &str) -> Option<u64> {
    value.rsplit('/').next()?.parse().ok()
}

#[derive(Debug, Clone, Copy)]
enum CacheIdentity<'a> {
    Driver { db_type: &'a str, version: &'a str },
    Jre { key: &'a str, version: &'a str },
}

impl CacheIdentity<'_> {
    fn hash_key(self) -> String {
        match self {
            Self::Driver { db_type, version } => format!("driver:{db_type}:{version}"),
            Self::Jre { key, version } => format!("jre:{key}:{version}"),
        }
    }

    fn file_prefix(self) -> String {
        match self {
            Self::Driver { db_type, version } => {
                format!("driver-{}-{}", cache_file_token(db_type), cache_file_token(version))
            }
            Self::Jre { key, version } => format!("jre-{}-{}", cache_file_token(key), cache_file_token(version)),
        }
    }
}

fn cached_download_path(
    am: &AgentManager,
    url: &str,
    total_size: u64,
    expected_sha256: Option<&str>,
    cache_identity: Option<CacheIdentity<'_>>,
    dest: &std::path::Path,
) -> std::path::PathBuf {
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    url.hash(&mut hasher);
    total_size.hash(&mut hasher);
    expected_sha256.hash(&mut hasher);
    let identity_hash_key = cache_identity.map(CacheIdentity::hash_key);
    identity_hash_key.hash(&mut hasher);
    let hash = hasher.finish();
    let file_name = dest.file_name().and_then(|name| name.to_str()).unwrap_or("download");
    let prefix = cache_identity.map(CacheIdentity::file_prefix).unwrap_or_else(|| "download".to_string());
    am.download_cache_dir().join(format!("{prefix}-{hash:016x}-{file_name}"))
}

fn cached_download_is_valid(
    am: &AgentManager,
    path: &std::path::Path,
    expected_size: u64,
    expected_sha256: Option<&str>,
) -> bool {
    let Ok(meta) = std::fs::metadata(path) else {
        return false;
    };
    if !meta.is_file() {
        return false;
    }
    if expected_size > 0 && meta.len() != expected_size {
        let _ = std::fs::remove_file(path);
        return false;
    }
    let max_age = std::time::Duration::from_secs(am.download_cache_max_age_days() * 24 * 60 * 60);
    if meta.modified().ok().and_then(|modified| modified.elapsed().ok()).is_some_and(|age| age > max_age) {
        let _ = std::fs::remove_file(path);
        return false;
    }
    if validate_artifact_integrity(path, expected_size, expected_sha256).is_err() {
        let _ = std::fs::remove_file(path);
        return false;
    }
    true
}

fn normalized_sha256(expected_sha256: Option<&str>) -> Result<Option<&str>, String> {
    let Some(expected_sha256) = expected_sha256.map(str::trim).filter(|value| !value.is_empty()) else {
        return Ok(None);
    };
    if expected_sha256.len() != 64 || !expected_sha256.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        return Err("Invalid SHA-256 metadata for agent artifact".to_string());
    }
    Ok(Some(expected_sha256))
}

fn validate_artifact_integrity(path: &Path, expected_size: u64, expected_sha256: Option<&str>) -> Result<(), String> {
    let metadata = std::fs::metadata(path).map_err(|err| format!("Failed to inspect downloaded artifact: {err}"))?;
    if expected_size > 0 && metadata.len() != expected_size {
        return Err(format!(
            "Downloaded artifact size mismatch: expected {expected_size} bytes, got {} bytes",
            metadata.len()
        ));
    }
    let Some(expected_sha256) = expected_sha256 else {
        return Ok(());
    };
    let actual_sha256 = file_sha256(path)?;
    if actual_sha256.eq_ignore_ascii_case(expected_sha256) {
        return Ok(());
    }
    Err(format!("Downloaded artifact SHA-256 mismatch: expected {expected_sha256}, got {actual_sha256}"))
}

fn file_sha256(path: &Path) -> Result<String, String> {
    let mut file = std::fs::File::open(path).map_err(|err| format!("Failed to hash downloaded artifact: {err}"))?;
    let mut hasher = Sha256::new();
    let mut buffer = [0_u8; 64 * 1024];
    loop {
        let read = file.read(&mut buffer).map_err(|err| format!("Failed to hash downloaded artifact: {err}"))?;
        if read == 0 {
            break;
        }
        hasher.update(&buffer[..read]);
    }
    Ok(format!("{:x}", hasher.finalize()))
}

fn prune_download_cache(am: &AgentManager) -> Result<(), String> {
    let cache_dir = am.download_cache_dir();
    let max_age = std::time::Duration::from_secs(am.download_cache_max_age_days() * 24 * 60 * 60);
    let Ok(entries) = std::fs::read_dir(&cache_dir) else {
        return Ok(());
    };
    for entry in entries.flatten() {
        let path = entry.path();
        let Ok(meta) = entry.metadata() else {
            continue;
        };
        if meta.modified().ok().and_then(|modified| modified.elapsed().ok()).is_some_and(|age| age > max_age) {
            let _ = if meta.is_dir() { std::fs::remove_dir_all(path) } else { std::fs::remove_file(path) };
        }
    }
    Ok(())
}

fn prune_driver_download_cache(am: &AgentManager, db_type: &str) -> Result<(), String> {
    let prefix = format!("driver-{}-", cache_file_token(db_type));
    remove_download_cache_entries(am, |name| name.starts_with(&prefix), "cached driver download")
}

fn prune_jre_download_cache(am: &AgentManager, jre_key: &str) -> Result<(), String> {
    let prefix = format!("jre-{}-", cache_file_token(jre_key));
    remove_download_cache_entries(am, |name| name.starts_with(&prefix), "cached JRE download")
}

fn cleanup_driver_download_cache_after_success(am: &AgentManager, db_type: &str) {
    // Keep the retained delta base (future incremental updates read it back);
    // drop the transient download entries for this driver.
    let prefix = format!("driver-{}-", cache_file_token(db_type));
    let base_prefix = format!("driver-{}-base-", cache_file_token(db_type));
    if let Err(err) = remove_download_cache_entries(
        am,
        |name| name.starts_with(&prefix) && !name.starts_with(&base_prefix),
        "cached driver download",
    ) {
        log::warn!("Failed to clean cached download for {db_type}: {err}");
    }
}

/// Retains the just-installed artifact as the delta base for the next
/// incremental update of `db_type`. Best-effort: a missing base only costs a
/// full download later.
fn retain_driver_delta_base(am: &AgentManager, db_type: &str, version: &str, downloaded: &Path) {
    if let Err(err) = crate::driver_delta::retain_delta_base(&am.download_cache_dir(), db_type, version, downloaded) {
        log::warn!("Failed to retain delta base for {db_type} {version}: {err}");
    }
}

fn cleanup_jre_download_cache_after_success(am: &AgentManager, jre_key: &str) {
    if let Err(err) = prune_jre_download_cache(am, jre_key) {
        log::warn!("Failed to clean cached JRE download for {jre_key}: {err}");
    }
}

fn remove_download_cache_entries(
    am: &AgentManager,
    should_remove: impl Fn(&str) -> bool,
    context: &str,
) -> Result<(), String> {
    let cache_dir = am.download_cache_dir();
    let Ok(entries) = std::fs::read_dir(&cache_dir) else {
        return Ok(());
    };
    for entry in entries.flatten() {
        let path = entry.path();
        let Some(name) = path.file_name().and_then(|value| value.to_str()) else {
            continue;
        };
        if !should_remove(name) {
            continue;
        }
        let meta = match entry.metadata() {
            Ok(meta) => meta,
            Err(_) => continue,
        };
        if meta.is_dir() {
            std::fs::remove_dir_all(&path).map_err(|err| format!("Failed to remove {context}: {err}"))?;
        } else {
            std::fs::remove_file(&path).map_err(|err| format!("Failed to remove {context}: {err}"))?;
        }
    }
    Ok(())
}

fn cache_file_token(value: &str) -> String {
    let token = value
        .chars()
        .map(|ch| if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.' { ch } else { '-' })
        .collect::<String>()
        .trim_matches('-')
        .to_string();
    if token.is_empty() {
        "unknown".to_string()
    } else {
        token
    }
}

fn r2_path_with_cache_buster(r2_path: &str, version: &str) -> String {
    let separator = if r2_path.contains('?') { '&' } else { '?' };
    format!("{r2_path}{separator}v={}", cache_file_token(version))
}

pub fn github_url_to_r2_path(github_url: &str, category: &str) -> String {
    let filename = github_url.rsplit('/').next().unwrap_or(github_url);
    match category {
        "jre" => format!("agents/jre/{filename}"),
        "driver" => format!("agents/drivers/{filename}"),
        _ => format!("agents/{filename}"),
    }
}

pub fn ensure_driver_app_version(
    db_type: &str,
    driver: &crate::agent_manager::DriverInfo,
    current_version: &str,
) -> Result<(), String> {
    if is_app_version_compatible(&driver.min_app_version, current_version) {
        return Ok(());
    }
    Err(format!(
        "{db_type} driver {} requires DBX {} or newer. Current DBX version is {}.",
        driver.version, driver.min_app_version, current_version
    ))
}

pub fn is_app_version_compatible(min_app_version: &str, current_version: &str) -> bool {
    !dbx_platform::version::is_newer_version(min_app_version, current_version)
}

pub fn download_temp_path(dest: &std::path::Path) -> std::path::PathBuf {
    let file_name = dest.file_name().and_then(|name| name.to_str()).unwrap_or("download");
    dest.with_file_name(format!("{file_name}.download"))
}

fn download_source_path(tmp: &std::path::Path) -> std::path::PathBuf {
    tmp.with_extension(format!(
        "{}source",
        tmp.extension()
            .and_then(|extension| extension.to_str())
            .map(|extension| format!("{extension}."))
            .unwrap_or_default()
    ))
}

pub fn replace_download(tmp: &std::path::Path, dest: &std::path::Path) -> Result<(), String> {
    if let Some(parent) = dest.parent() {
        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    }
    if dest.exists() {
        let backup = backup_path(dest);
        std::fs::rename(dest, &backup).map_err(|e| format!("Failed to back up existing file: {e}"))?;
        match std::fs::rename(tmp, dest) {
            Ok(()) => {
                std::fs::remove_file(&backup).ok();
                Ok(())
            }
            Err(err) => {
                let _ = std::fs::rename(&backup, dest);
                Err(format!("Failed to replace downloaded file: {err}"))
            }
        }
    } else {
        std::fs::rename(tmp, dest).map_err(|e| format!("Failed to move downloaded file into place: {e}"))
    }
}

fn backup_path(dest: &std::path::Path) -> std::path::PathBuf {
    let file_name = dest.file_name().and_then(|name| name.to_str()).unwrap_or("download");
    dest.with_file_name(format!("{file_name}.backup-{}", uuid::Uuid::new_v4()))
}

// ──────────── Offline import ────────────

#[derive(Debug, Clone, serde::Serialize)]
pub struct OfflineImportProgress {
    pub step: String,
    pub current: u32,
    pub total: u32,
    /// Display label for the current item (e.g. "MySQL", "JRE 21.0.12").
    pub label: String,
    /// The real database-type key (e.g. "mysql"), used by the frontend for
    /// per-driver progress routing. `None` for JRE-only steps.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub db_type: Option<String>,
}

/// An offline-import item (managed JRE runtime or driver) that could not be
/// installed. The import continues past it so a single blocked or corrupt
/// item cannot abort the whole package.
#[derive(Debug, Clone, serde::Serialize)]
pub struct OfflineImportFailure {
    /// Managed JRE key (e.g. `21`) or driver key (e.g. `oracle`).
    pub key: String,
    /// True when the failed item is a managed JRE runtime rather than a driver.
    pub is_jre: bool,
    /// Failure text, including the underlying OS error when there is one.
    pub error: String,
}

#[derive(Debug, Clone)]
pub struct OfflineImportResult {
    pub jre_installed: Vec<String>,
    pub drivers_installed: Vec<String>,
    pub drivers_skipped: Vec<String>,
    /// Items that failed; reported to the user instead of failing the import.
    pub failures: Vec<OfflineImportFailure>,
}

#[derive(Debug)]
struct TarZstdJrePackageInfo {
    key: String,
    version: String,
}

fn tar_zstd_jre_package_info(package_path: &Path) -> Result<Option<TarZstdJrePackageInfo>, String> {
    let file = std::fs::File::open(package_path).map_err(|error| error.to_string())?;
    let decoder = zstd::stream::read::Decoder::new(file).map_err(|error| error.to_string())?;
    let mut archive = tar::Archive::new(decoder);
    let mut release = None;
    let mut has_registry = false;
    let mut invalid_jre_entry = false;
    for entry in archive.entries().map_err(|error| error.to_string())? {
        let mut entry = entry.map_err(|error| error.to_string())?;
        let name = safe_archive_entry_name(&entry.path().map_err(|error| error.to_string())?)?;
        has_registry |= name == "agent-registry.json";
        invalid_jre_entry |= !(name == "dbx-jre" || name.starts_with("dbx-jre/"))
            || !(entry.header().entry_type().is_file()
                || entry.header().entry_type().is_dir()
                || (entry.header().entry_type().is_symlink() && standalone_jre_link_is_safe(&entry, &name)?));
        if name == "dbx-jre/release" {
            if release.is_some() || !entry.header().entry_type().is_file() || entry.size() > 64 * 1024 {
                return Err("Invalid offline JRE release metadata".to_string());
            }
            let mut text = String::new();
            entry.read_to_string(&mut text).map_err(|error| error.to_string())?;
            release = Some(text);
        }
    }
    if has_registry {
        return Ok(None);
    }
    let Some(release) = release else { return Ok(None) };
    if invalid_jre_entry {
        return Err("Offline JRE package contains an unexpected or non-regular entry".to_string());
    }
    let version = release
        .lines()
        .find_map(|line| line.strip_prefix("JAVA_VERSION=").map(|value| value.trim().trim_matches('"')))
        .ok_or("Offline JRE package is missing JAVA_VERSION")?;
    let key = version.split('.').next().unwrap_or("");
    if key.is_empty() || !key.bytes().all(|byte| byte.is_ascii_digit()) || key == "0" {
        return Err("Invalid offline JRE JAVA_VERSION".to_string());
    }
    validate_offline_identifier(version, "JRE version")?;
    Ok(Some(TarZstdJrePackageInfo { key: key.to_string(), version: version.to_string() }))
}

fn standalone_jre_link_is_safe<R: Read>(entry: &tar::Entry<'_, R>, name: &str) -> Result<bool, String> {
    let Some(target) = entry.link_name().map_err(|error| error.to_string())? else { return Ok(false) };
    let mut parts: Vec<_> = name.split('/').collect();
    parts.pop();
    for component in target.components() {
        match component {
            std::path::Component::Normal(value) => {
                let Some(value) = value.to_str() else { return Ok(false) };
                parts.push(value);
            }
            std::path::Component::CurDir => {}
            std::path::Component::ParentDir if parts.len() > 1 => {
                parts.pop();
            }
            _ => return Ok(false),
        }
    }
    Ok(parts.first() == Some(&"dbx-jre"))
}

fn extract_and_validate_standalone_jre(
    package_path: &Path,
    staging: &Path,
    info: &TarZstdJrePackageInfo,
) -> Result<(), String> {
    extract_jre_archive(package_path, staging, Some(ArtifactFormat::TarZstd))?;
    let java = staging.join("bin").join(if cfg!(windows) { "java.exe" } else { "java" });
    if !java.is_file() {
        return Err(format!(
            "Offline JRE {} package does not contain a Java executable for {}",
            info.key,
            AgentManager::current_platform()
        ));
    }
    validate_native_agent_binary(&java).map_err(|_| {
        format!("Offline JRE {} package does not support platform: {}", info.key, AgentManager::current_platform())
    })?;
    mark_executable(&java)
}

async fn import_tar_zstd_jre_package(
    am: &AgentManager,
    package_path: &Path,
    info: &TarZstdJrePackageInfo,
    progress: &impl Fn(AgentProgressEvent),
) -> Result<OfflineImportResult, String> {
    let _installation_guard = am.installation_operation_lock.write().await;
    std::fs::create_dir_all(am.base_dir()).map_err(|error| error.to_string())?;
    let staging = tempfile::Builder::new()
        .prefix(".jre-offline-import-")
        .tempdir_in(am.base_dir())
        .map_err(|error| error.to_string())?;
    progress(AgentProgressEvent::step("jre-extract"));
    extract_and_validate_standalone_jre(package_path, staging.path(), info)?;
    // Validate before stopping active daemons or replacing a working runtime.
    am.stop_daemons().await;
    stop_external_managed_agent_processes(ManagedAgentProcessTarget::JreDirectory(am.jre_dir(&info.key))).await?;
    let pending_cleanup = replace_imported_jre_dir(staging.path(), &am.jre_dir(&info.key))?;
    am.mutate_state(|state| {
        state.jre_versions.insert(info.key.clone(), info.version.clone());
        if let Some(path) = pending_cleanup {
            state.pending_jre_cleanup.push(path);
        }
    })?;
    Ok(OfflineImportResult {
        jre_installed: vec![info.key.clone()],
        drivers_installed: Vec::new(),
        drivers_skipped: Vec::new(),
        failures: Vec::new(),
    })
}

#[derive(Debug, Clone)]
pub struct OfflineImportPlan {
    pub driver_keys: Vec<String>,
    pub includes_jre: bool,
}

type OfflineJreEntry = (String, String, Option<ArtifactFormat>);
type OfflineDriverEntry = (String, String, bool, Option<String>);
type OfflineArchiveEntries = (Vec<OfflineJreEntry>, Vec<OfflineDriverEntry>);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DriverArtifactKind {
    Jar,
    Native,
}

impl DriverArtifactKind {
    fn label(self) -> &'static str {
        match self {
            Self::Jar => "jar",
            Self::Native => "native",
        }
    }
}

#[derive(Debug, Clone)]
struct TarZstdDriverPackageInfo {
    db_type: String,
    version: String,
    jre: String,
    kind: DriverArtifactKind,
    native_platform: Option<String>,
    entry_name: String,
    size: u64,
}

fn inspect_tar_zstd_driver_package(package_path: &Path) -> Result<OfflineImportPlan, String> {
    let info = tar_zstd_driver_package_info(package_path)?;
    Ok(OfflineImportPlan { driver_keys: vec![info.db_type], includes_jre: false })
}

async fn import_tar_zstd_driver_package(
    am: &AgentManager,
    package_path: &Path,
    progress: impl Fn(OfflineImportProgress),
) -> Result<OfflineImportResult, String> {
    let _installation_guard = am.installation_operation_lock.write().await;
    let info = tar_zstd_driver_package_info(package_path)?;
    let mut result = OfflineImportResult {
        jre_installed: Vec::new(),
        drivers_installed: Vec::new(),
        drivers_skipped: Vec::new(),
        failures: Vec::new(),
    };
    if let Some(installed) = am.load_state().installed_drivers.get(&info.db_type) {
        if installed.version != "0.1.0-local"
            && installed.version != "local"
            && !dbx_platform::version::is_newer_version(&info.version, &installed.version)
        {
            result.drivers_skipped.push(info.db_type);
            return Ok(result);
        }
    }

    progress(OfflineImportProgress {
        step: "driver".to_string(),
        current: 1,
        total: 1,
        label: agent_catalog::label_for_key(&info.db_type).unwrap_or(&info.db_type).to_string(),
        db_type: Some(info.db_type.clone()),
    });
    let target_path = match info.kind {
        DriverArtifactKind::Jar => am.driver_jar_path(&info.db_type),
        DriverArtifactKind::Native if AgentManager::is_sqlite_worker_driver(&info.db_type) => {
            let platform = info
                .native_platform
                .as_deref()
                .ok_or_else(|| "SQLite SSH worker package is missing its Linux platform".to_string())?;
            am.driver_native_platform_path(&info.db_type, platform)
        }
        DriverArtifactKind::Native => am.driver_native_path(&info.db_type),
    };
    stop_driver_processes_before_replacement(am, &info.db_type).await?;
    install_driver_from_tar_zstd_package(
        package_path,
        &target_path,
        info.kind,
        &info.db_type,
        &info.version,
        info.native_platform.as_deref(),
    )?;
    match info.kind {
        DriverArtifactKind::Jar => {
            std::fs::remove_file(am.driver_native_path(&info.db_type)).ok();
        }
        DriverArtifactKind::Native => {
            std::fs::remove_file(am.driver_jar_path(&info.db_type)).ok();
        }
    }
    let record_install =
        !AgentManager::is_sqlite_worker_driver(&info.db_type) || am.driver_native_installed(&info.db_type);
    if record_install {
        am.mutate_state(|state| {
            state.installed_drivers.insert(
                info.db_type.clone(),
                InstalledDriver {
                    version: info.version.clone(),
                    installed_at: chrono::Utc::now().to_rfc3339(),
                    jre: info.jre.clone(),
                },
            );
        })?;
    }
    result.drivers_installed.push(info.db_type);
    Ok(result)
}

fn tar_zstd_driver_package_info(package_path: &Path) -> Result<TarZstdDriverPackageInfo, String> {
    let registry = read_registry_from_tar_zstd(package_path)?;
    if registry.drivers.len() != 1 {
        return Err("A tar.zst driver package must contain exactly one driver".to_string());
    }
    let (db_type, driver) = registry.drivers.iter().next().expect("checked one driver");
    validate_offline_driver_key(db_type)?;
    let current_platform = AgentManager::current_platform();
    let (native_platform, native_artifact) = if let Some(artifact) = driver.native.get(current_platform) {
        (Some(current_platform.to_string()), Some(artifact))
    } else if driver.native.len() == 1 {
        let (platform, artifact) = driver.native.iter().next().expect("checked one native platform");
        (Some(platform.clone()), Some(artifact))
    } else {
        (None, None)
    };
    let jar_artifact = usable_driver_jar(driver);
    let (kind, artifact) = match (native_artifact, jar_artifact) {
        (Some(_), Some(_)) => {
            return Err("A tar.zst driver package must contain exactly one driver artifact".to_string());
        }
        (Some(artifact), None) => (DriverArtifactKind::Native, artifact),
        (None, Some(artifact)) => (DriverArtifactKind::Jar, artifact),
        (None, None) if !driver.native.is_empty() => {
            return Err(format!("Driver package does not support platform: {current_platform}"));
        }
        (None, None) => return Err("A tar.zst driver package contains no driver artifact".to_string()),
    };
    if artifact.format.is_some() {
        return Err("Nested driver packages are not supported".to_string());
    }
    let artifact_filename = artifact
        .url
        .rsplit('/')
        .next()
        .filter(|name| !name.is_empty())
        .ok_or_else(|| format!("Invalid packaged driver URL: {}", artifact.url))?;
    let entry_name = format!("drivers/{artifact_filename}");
    validate_tar_zstd_package_entries(package_path, &entry_name, artifact.size)?;
    Ok(TarZstdDriverPackageInfo {
        db_type: db_type.clone(),
        version: driver.version.clone(),
        jre: driver.jre.clone(),
        kind,
        native_platform: native_platform.filter(|_| kind == DriverArtifactKind::Native),
        entry_name,
        size: artifact.size,
    })
}

fn validate_tar_zstd_package_entries(
    package_path: &Path,
    expected_entry: &str,
    expected_size: u64,
) -> Result<(), String> {
    let file = std::fs::File::open(package_path).map_err(|error| format!("Failed to open driver package: {error}"))?;
    let decoder = zstd::stream::read::Decoder::new(file)
        .map_err(|error| format!("Failed to open zstd driver package: {error}"))?;
    let mut archive = tar::Archive::new(decoder);
    let entries = archive.entries().map_err(|error| format!("Invalid tar.zst driver package: {error}"))?;
    let mut registry_seen = false;
    let mut driver_seen = false;
    for entry in entries {
        let entry = entry.map_err(|error| format!("Invalid tar.zst driver package entry: {error}"))?;
        let path = entry.path().map_err(|error| format!("Invalid driver package path: {error}"))?;
        let name = safe_archive_entry_name(&path)?;
        if entry.header().entry_type().is_dir() {
            continue;
        }
        if !entry.header().entry_type().is_file() {
            return Err(format!("Driver package contains a non-regular entry: {name}"));
        }
        match name.as_str() {
            "agent-registry.json" if !registry_seen => registry_seen = true,
            value if value == expected_entry && !driver_seen => {
                if expected_size > 0 && entry.size() != expected_size {
                    return Err(format!(
                        "Packaged driver size mismatch: expected {expected_size} bytes, got {} bytes",
                        entry.size()
                    ));
                }
                driver_seen = true;
            }
            _ => return Err(format!("Unexpected file in driver package: {name}")),
        }
    }
    if !registry_seen {
        return Err("agent-registry.json not found in the driver package".to_string());
    }
    if !driver_seen {
        return Err(format!("Driver package entry not found: {expected_entry}"));
    }
    Ok(())
}

pub fn inspect_offline_zip(zip_path: &Path) -> Result<OfflineImportPlan, String> {
    let file = std::fs::File::open(zip_path).map_err(|e| format!("Failed to open ZIP file: {e}"))?;
    let mut archive = zip::ZipArchive::new(file).map_err(|e| format!("Invalid ZIP file: {e}"))?;
    let registry = read_registry_from_zip(&mut archive)?;
    let (jre_entries, driver_entries) = collect_offline_entries(&mut archive, &registry)?;
    validate_offline_zip_preflight(&mut archive, &registry, &jre_entries, &driver_entries)?;
    Ok(OfflineImportPlan {
        driver_keys: driver_entries
            .into_iter()
            .map(|(db_type, _, _, _)| db_type)
            .collect::<std::collections::BTreeSet<_>>()
            .into_iter()
            .collect(),
        includes_jre: !jre_entries.is_empty(),
    })
}

pub async fn import_offline_zip(
    am: &AgentManager,
    zip_path: &Path,
    progress: impl Fn(OfflineImportProgress),
) -> Result<OfflineImportResult, String> {
    // Offline import can touch both JRE and driver directories — hold an
    // exclusive installation-operation lock so that concurrent driver installs,
    // JRE installs, Upgrade All, and uninstall operations are serialised.
    let _installation_guard = am.installation_operation_lock.write().await;

    let file = std::fs::File::open(zip_path).map_err(|e| format!("Failed to open ZIP file: {}", describe_error(&e)))?;
    let mut archive = zip::ZipArchive::new(file).map_err(|e| format!("Invalid ZIP file: {}", describe_error(&e)))?;

    let registry = read_registry_from_zip(&mut archive)?;

    let platform = AgentManager::current_platform();
    let (jre_entries, driver_entries) = collect_offline_entries(&mut archive, &registry)?;

    let total = (jre_entries.len() + driver_entries.len()) as u32;
    if total == 0 {
        return Err(format!("Offline package contains no drivers compatible with platform: {platform}"));
    }
    validate_offline_zip_preflight(&mut archive, &registry, &jre_entries, &driver_entries)?;
    std::fs::create_dir_all(am.base_dir())
        .map_err(|e| format!("Failed to create agent directory: {}", describe_error(&e)))?;
    let mut local_state = am.load_state();
    let mut result = OfflineImportResult {
        jre_installed: Vec::new(),
        drivers_installed: Vec::new(),
        drivers_skipped: Vec::new(),
        failures: Vec::new(),
    };
    let mut current: u32 = 0;

    for (jre_key, entry_name, format) in &jre_entries {
        current += 1;
        let jre_version = registry.resolve_jre(jre_key).map(|j| j.version.clone());
        let existing_version = local_state.jre_versions.get(jre_key);
        if am.is_jre_installed(jre_key) && existing_version == jre_version.as_ref() {
            continue;
        }

        progress(OfflineImportProgress {
            step: "jre-extract".into(),
            current,
            total,
            label: format!("JRE {jre_key}"),
            db_type: None,
        });

        // A blocked write (anti-virus, disk quota) or an invalid archive must
        // not abort the rest of the package: record the failure and continue so
        // the drivers still install.
        let jre_dir = am.jre_dir(jre_key);
        let staged = (|| -> Result<(PathBuf, PathBuf), String> {
            let mut entry = archive
                .by_name(entry_name)
                .map_err(|e| format!("Failed to read {entry_name}: {}", describe_error(&e)))?;
            let tmp_archive = am.base_dir().join(format!("jre-offline-{jre_key}{}", jre_archive_suffix(*format)));
            {
                let mut out = std::fs::File::create(&tmp_archive)
                    .map_err(|e| format!("Failed to create temp file: {}", describe_error(&e)))?;
                std::io::copy(&mut entry, &mut out)
                    .map_err(|e| format!("Failed to extract JRE archive: {}", describe_error(&e)))?;
            }

            let staging_dir = am.base_dir().join(format!(".jre-offline-import-{}", uuid::Uuid::new_v4()));
            if let Err(error) = extract_jre_archive(&tmp_archive, &staging_dir, *format) {
                std::fs::remove_dir_all(&staging_dir).ok();
                std::fs::remove_file(&tmp_archive).ok();
                return Err(error);
            }
            if !jre_dir_contains_java(&staging_dir) {
                std::fs::remove_dir_all(&staging_dir).ok();
                std::fs::remove_file(&tmp_archive).ok();
                return Err(format!("Offline JRE archive does not contain a Java executable: {entry_name}"));
            }
            Ok((tmp_archive, staging_dir))
        })();
        let outcome = match staged {
            Ok((tmp_archive, staging_dir)) => {
                let result = async {
                    stop_jre_processes_before_replacement(am, jre_key).await?;
                    let pending_cleanup = replace_imported_jre_dir(&staging_dir, &jre_dir)?;
                    if let Some(path) = pending_cleanup {
                        local_state.pending_jre_cleanup.push(path);
                    }
                    if let Some(ver) = jre_version {
                        local_state.jre_versions.insert(jre_key.clone(), ver);
                    }
                    Ok(())
                }
                .await;
                std::fs::remove_file(&tmp_archive).ok();
                if result.is_err() {
                    std::fs::remove_dir_all(&staging_dir).ok();
                }
                result
            }
            Err(error) => Err(error),
        };
        match outcome {
            Ok(()) => result.jre_installed.push(jre_key.clone()),
            Err(error) => {
                log::warn!("Offline JRE import failed for {jre_key}: {error}");
                result.failures.push(OfflineImportFailure { key: jre_key.clone(), is_jre: true, error });
            }
        }
    }

    // Decide up front which drivers are already up to date. A single driver can
    // contribute several entries (the SQLite worker ships one binary per remote
    // platform), and the check must not skip the second artifact just because
    // installing the first one updated the recorded version.
    let mut up_to_date_drivers = std::collections::BTreeSet::new();
    for (db_type, _, _, _) in &driver_entries {
        if up_to_date_drivers.contains(db_type) {
            continue;
        }
        let Some(remote_driver) = registry.drivers.get(db_type) else { continue };
        let Some(installed) = local_state.installed_drivers.get(db_type) else { continue };
        if installed.version != "0.1.0-local"
            && installed.version != "local"
            && !dbx_platform::version::is_newer_version(&remote_driver.version, &installed.version)
        {
            up_to_date_drivers.insert(db_type.clone());
        }
    }

    for (db_type, entry_name, is_native, worker_platform) in &driver_entries {
        current += 1;

        if up_to_date_drivers.contains(db_type) {
            if !result.drivers_skipped.contains(db_type) {
                result.drivers_skipped.push(db_type.clone());
            }
            continue;
        }

        progress(OfflineImportProgress {
            step: "driver".into(),
            current,
            total,
            label: agent_catalog::label_for_key(db_type).unwrap_or(db_type).to_string(),
            db_type: Some(db_type.clone()),
        });

        let driver_path = offline_driver_target_path(am, db_type, *is_native, worker_platform.as_deref());
        // Same per-item isolation as the JRE loop: one unreadable or blocked
        // driver must not stop the remaining drivers from installing.
        let staged = (|| -> Result<PathBuf, String> {
            if let Some(parent) = driver_path.parent() {
                std::fs::create_dir_all(parent)
                    .map_err(|e| format!("Failed to create driver directory: {}", describe_error(&e)))?;
            }
            let mut entry = archive
                .by_name(entry_name)
                .map_err(|e| format!("Failed to read {entry_name}: {}", describe_error(&e)))?;
            let parent =
                driver_path.parent().ok_or_else(|| format!("Invalid driver path: {}", driver_path.display()))?;
            let staging_path = parent.join(format!(".offline-agent-import-{}", uuid::Uuid::new_v4()));
            let mut out = std::fs::File::create(&staging_path)
                .map_err(|e| format!("Failed to write driver: {}", describe_error(&e)))?;
            match std::io::copy(&mut entry, &mut out) {
                Ok(_) => {}
                Err(e) => {
                    std::fs::remove_file(&staging_path).ok();
                    return Err(format!("Failed to copy driver: {}", describe_error(&e)));
                }
            }
            drop(out);
            if *is_native {
                // The SQLite SSH worker carries the remote host's architecture, so
                // validate against the packaged platform rather than this desktop.
                let native_platform = match worker_platform {
                    Some(packaged) => packaged.as_str(),
                    None => AgentManager::current_platform(),
                };
                if let Err(error) = validate_native_agent_binary_for_platform(&staging_path, native_platform) {
                    std::fs::remove_file(&staging_path).ok();
                    return Err(error);
                }
                mark_executable(&staging_path)?;
            } else {
                // Validate the staged JAR before replacing a working driver so a
                // corrupt offline package cannot destroy the previous installation.
                if !is_valid_agent_jar(&staging_path) {
                    std::fs::remove_file(&staging_path).ok();
                    return Err(format!("Offline agent jar is invalid or corrupt: {entry_name}"));
                }
            }
            Ok(staging_path)
        })();
        let outcome = match staged {
            Ok(staging_path) => {
                let result = async {
                    stop_driver_processes_before_replacement(am, db_type).await?;
                    replace_imported_agent_file(&staging_path, &driver_path)?;
                    if *is_native {
                        std::fs::remove_file(am.driver_jar_path(db_type)).ok();
                    } else {
                        std::fs::remove_file(am.driver_native_path(db_type)).ok();
                    }

                    let version =
                        registry.drivers.get(db_type).map(|d| d.version.clone()).unwrap_or_else(|| "local".to_string());
                    let jre_key = registry
                        .drivers
                        .get(db_type)
                        .map(|d| d.jre.clone())
                        .unwrap_or_else(|| DEFAULT_JRE_KEY.to_string());

                    local_state.installed_drivers.insert(
                        db_type.clone(),
                        InstalledDriver { version, installed_at: chrono::Utc::now().to_rfc3339(), jre: jre_key },
                    );
                    Ok(())
                }
                .await;
                if result.is_err() {
                    std::fs::remove_file(&staging_path).ok();
                }
                result
            }
            Err(error) => Err(error),
        };
        match outcome {
            Ok(()) => result.drivers_installed.push(db_type.clone()),
            Err(error) => {
                log::warn!("Offline driver import failed for {db_type}: {error}");
                result.failures.push(OfflineImportFailure { key: db_type.clone(), is_jre: false, error });
            }
        }
    }

    am.mutate_state(|state| {
        for jre_key in &result.jre_installed {
            if let Some(version) = local_state.jre_versions.get(jre_key) {
                state.jre_versions.insert(jre_key.clone(), version.clone());
            }
        }
        for path in &local_state.pending_jre_cleanup {
            if !state.pending_jre_cleanup.contains(path) {
                state.pending_jre_cleanup.push(path.clone());
            }
        }
        for db_type in &result.drivers_installed {
            if let Some(driver) = local_state.installed_drivers.get(db_type) {
                state.installed_drivers.insert(db_type.clone(), driver.clone());
            }
        }
    })?;
    Ok(result)
}

fn collect_offline_entries(
    archive: &mut zip::ZipArchive<std::fs::File>,
    registry: &AgentRegistry,
) -> Result<OfflineArchiveEntries, String> {
    let platform = AgentManager::current_platform();
    let mut jres = std::collections::BTreeMap::<String, (String, Option<ArtifactFormat>)>::new();
    // One driver can contribute more than one entry: the SQLite SSH worker ships
    // a binary per remote Linux platform, and a bundle may carry both a native
    // artifact and a Java fallback for the same key.
    let mut drivers = std::collections::BTreeMap::<String, Vec<(String, bool, Option<String>)>>::new();

    for index in 0..archive.len() {
        let entry = archive.by_index(index).map_err(|e| format!("Failed to inspect ZIP entry: {e}"))?;
        let Some(path) = entry.enclosed_name() else {
            return Err(format!("Offline package contains an unsafe path: {}", entry.name()));
        };
        let name = path.to_string_lossy().replace('\\', "/");
        if name.starts_with("jre/") {
            let jre_format = if name.ends_with(".tar.zst") {
                Some(ArtifactFormat::TarZstd)
            } else if name.ends_with(".tar.gz") {
                None
            } else {
                continue;
            };
            let Some(jre_key) = jre_key_for_offline_entry(registry, platform, &name)
                .or_else(|| name.contains(platform).then(|| extract_jre_key_from_filename(&name)).flatten())
            else {
                continue;
            };
            validate_offline_identifier(&jre_key, "JRE")?;
            let replace = !jres.contains_key(&jre_key) || jre_format == Some(ArtifactFormat::TarZstd);
            if replace {
                jres.insert(jre_key, (name, jre_format));
            }
        } else if name.starts_with("drivers/") && name.ends_with(".jar") {
            let db_type = db_type_for_jar_offline_entry(registry, &name)
                .or_else(|| extract_db_type_from_filename(&name))
                .ok_or_else(|| format!("Unable to identify offline driver: {name}"))?;
            validate_offline_driver_key(&db_type)?;
            drivers.entry(db_type).or_default().push((name, false, None));
        } else if name.starts_with("drivers/") {
            if let Some((db_type, worker_platform)) = native_offline_entry_target(registry, platform, &name) {
                validate_offline_driver_key(&db_type)?;
                drivers.entry(db_type).or_default().push((name, true, worker_platform));
            }
        }
    }

    let driver_entries = drivers
        .into_iter()
        .flat_map(|(db_type, mut entries)| {
            // Prefer native artifacts when a package contains both the platform
            // executable and a Java fallback for the same driver.
            if entries.iter().any(|(_, is_native, _)| *is_native) {
                entries.retain(|(_, is_native, _)| *is_native);
            } else {
                entries.truncate(1);
            }
            entries
                .into_iter()
                .map(move |(name, is_native, worker_platform)| (db_type.clone(), name, is_native, worker_platform))
        })
        .collect();

    Ok((jres.into_iter().map(|(jre_key, (name, format))| (jre_key, name, format)).collect(), driver_entries))
}

/// Where an offline native artifact must be installed.
///
/// Everything except the SQLite SSH worker installs under the desktop platform
/// path; the worker is chosen by the remote SSH host's architecture, so its
/// Linux packages are addressed by the platform baked into their filename.
fn offline_driver_target_path(
    am: &AgentManager,
    db_type: &str,
    is_native: bool,
    worker_platform: Option<&str>,
) -> PathBuf {
    match (is_native, worker_platform) {
        (true, Some(platform)) => am.driver_native_platform_path(db_type, platform),
        (true, None) => am.driver_native_path(db_type),
        (false, _) => am.driver_jar_path(db_type),
    }
}

/// Resolve a `drivers/` native entry to its driver key and, for the SQLite SSH
/// worker, to the remote Linux platform the binary belongs to.
fn native_offline_entry_target(
    registry: &AgentRegistry,
    platform: &str,
    name: &str,
) -> Option<(String, Option<String>)> {
    let filename = name.rsplit('/').next()?;
    // The SQLite SSH worker follows the remote SSH host, so resolve it against
    // its own platform list first: the generic lookup below would match the
    // desktop platform on a Linux machine and wrongly point at the flat native
    // path instead of the per-platform one the SSH launcher reads.
    for (db_type, driver) in &registry.drivers {
        if !AgentManager::is_sqlite_worker_driver(db_type) {
            continue;
        }
        for worker_platform in SQLITE_WORKER_NATIVE_PLATFORMS {
            let artifact_filename =
                driver.native.get(*worker_platform).and_then(|artifact| artifact.url.rsplit('/').next());
            if artifact_filename == Some(filename) {
                return Some((db_type.clone(), Some((*worker_platform).to_string())));
            }
        }
    }
    db_type_for_native_offline_entry(registry, platform, name).map(|db_type| (db_type, None))
}

fn validate_offline_zip_preflight(
    archive: &mut zip::ZipArchive<std::fs::File>,
    registry: &AgentRegistry,
    jre_entries: &[OfflineJreEntry],
    driver_entries: &[OfflineDriverEntry],
) -> Result<(), String> {
    let platform = AgentManager::current_platform();
    let has_jre_artifact_metadata =
        registry.jre.iter().chain(registry.jres.values()).any(|jre| !jre.platforms.is_empty());
    let packaged_jres = jre_entries.iter().map(|(key, _, _)| key.as_str()).collect::<std::collections::BTreeSet<_>>();

    for (jre_key, entry_name, format) in jre_entries {
        if let Some(artifact) = registry.resolve_jre(jre_key).and_then(|jre| jre.platforms.get(platform)) {
            if artifact.format != *format {
                return Err(format!("Offline JRE {jre_key} archive format does not match its registry metadata"));
            }
            validate_offline_zip_artifact(archive, entry_name, artifact, &format!("JRE {jre_key}"))?;
        }
    }

    for (db_type, entry_name, is_native, worker_platform) in driver_entries {
        let Some(driver) = registry.drivers.get(db_type) else {
            // Older locally assembled ZIPs can identify a JAR solely from its
            // canonical filename. Preserve that import path when no registry
            // artifact metadata exists to validate.
            continue;
        };
        let artifact = if *is_native {
            driver.native.get(worker_platform.as_deref().unwrap_or(platform))
        } else {
            let jre_key = driver.jre.trim();
            if !jre_key.is_empty() {
                if let Some(jre) = registry.resolve_jre(jre_key) {
                    if !jre.platforms.is_empty() && !jre.platforms.contains_key(platform) {
                        return Err(format!(
                            "Offline Java driver {db_type} requires JRE {jre_key}, which does not support the current platform: {platform}"
                        ));
                    }
                    if !jre.platforms.is_empty() && !packaged_jres.contains(jre_key) {
                        return Err(format!(
                            "Offline Java driver {db_type} requires JRE {jre_key}, but the current-platform JRE artifact is missing"
                        ));
                    }
                } else if has_jre_artifact_metadata {
                    return Err(format!(
                        "Offline Java driver {db_type} requires JRE {jre_key}, but that JRE is missing from the package registry"
                    ));
                }
            }
            driver.jar.as_ref()
        };
        if let Some(artifact) = artifact {
            validate_offline_zip_artifact(archive, entry_name, artifact, &format!("driver {db_type}"))?;
        }
    }
    Ok(())
}

fn validate_offline_zip_artifact(
    archive: &mut zip::ZipArchive<std::fs::File>,
    entry_name: &str,
    artifact: &ArtifactInfo,
    label: &str,
) -> Result<(), String> {
    let mut entry = archive
        .by_name(entry_name)
        .map_err(|error| format!("Failed to read offline {label} artifact {entry_name}: {error}"))?;
    if !entry.is_file() {
        return Err(format!("Offline {label} artifact is not a regular file: {entry_name}"));
    }
    if artifact.size > 0 && entry.size() != artifact.size {
        return Err(format!(
            "Offline {label} artifact size mismatch: expected {} bytes, got {} bytes",
            artifact.size,
            entry.size()
        ));
    }
    let Some(expected_sha256) = normalized_sha256(artifact.sha256.as_deref())? else {
        return Ok(());
    };
    let mut digest = Sha256::new();
    let mut buffer = [0u8; 64 * 1024];
    loop {
        let read = entry
            .read(&mut buffer)
            .map_err(|error| format!("Failed to hash offline {label} artifact {entry_name}: {error}"))?;
        if read == 0 {
            break;
        }
        digest.update(&buffer[..read]);
    }
    let actual_sha256 = format!("{:x}", digest.finalize());
    if actual_sha256.eq_ignore_ascii_case(expected_sha256) {
        Ok(())
    } else {
        Err(format!("Offline {label} artifact SHA-256 mismatch: expected {expected_sha256}, got {actual_sha256}"))
    }
}

fn validate_offline_driver_key(db_type: &str) -> Result<(), String> {
    validate_offline_identifier(db_type, "driver")?;
    if agent_catalog::label_for_key(db_type).is_none() {
        return Err(format!("Offline package contains an unknown driver type: {db_type}"));
    }
    Ok(())
}

fn validate_offline_identifier(value: &str, kind: &str) -> Result<(), String> {
    if value.is_empty()
        || matches!(value, "." | "..")
        || !value.chars().all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
    {
        return Err(format!("Offline package contains an invalid {kind} identifier: {value}"));
    }
    Ok(())
}

fn read_registry_from_zip(archive: &mut zip::ZipArchive<std::fs::File>) -> Result<AgentRegistry, String> {
    let mut entry = archive
        .by_name("agent-registry.json")
        .map_err(|_| "agent-registry.json not found in the ZIP; not a valid offline driver package.".to_string())?;
    let mut buf = String::new();
    entry.read_to_string(&mut buf).map_err(|e| format!("Failed to read agent-registry.json: {e}"))?;
    serde_json::from_str(&buf).map_err(|e| format!("Invalid agent-registry.json: {e}"))
}

fn extract_jre_key_from_filename(name: &str) -> Option<String> {
    let filename = name.rsplit('/').next()?;
    let rest = filename.strip_prefix("dbx-jre-").or_else(|| filename.strip_prefix("jre-"))?;
    let key = rest.split('-').next()?;
    if key.is_empty() {
        return None;
    }
    Some(key.to_string())
}

fn jre_key_for_offline_entry(registry: &AgentRegistry, platform: &str, name: &str) -> Option<String> {
    let filename = name.rsplit('/').next()?;
    let registry_match = registry.jres.iter().find_map(|(key, jre)| {
        let artifact = jre.platforms.get(platform)?;
        (artifact.url.rsplit('/').next()? == filename).then(|| key.clone())
    });
    if registry_match.is_some() {
        return registry_match;
    }
    if registry.jres.is_empty() {
        let artifact = registry.jre.as_ref()?.platforms.get(platform)?;
        if artifact.url.rsplit('/').next()? == filename {
            return Some(DEFAULT_JRE_KEY.to_string());
        }
    }
    None
}

fn extract_db_type_from_filename(name: &str) -> Option<String> {
    let filename = name.rsplit('/').next()?;
    let rest = filename.strip_prefix("dbx-agent-")?;
    let db_type = rest.strip_suffix(".jar")?;
    if db_type.is_empty() {
        return None;
    }
    Some(db_type.to_string())
}

fn db_type_for_native_offline_entry(registry: &AgentRegistry, platform: &str, name: &str) -> Option<String> {
    let filename = name.rsplit('/').next()?;
    registry.drivers.iter().find_map(|(db_type, driver)| {
        let artifact = driver.native.get(platform)?;
        let artifact_filename = artifact.url.rsplit('/').next()?;
        (artifact_filename == filename).then(|| db_type.clone())
    })
}

fn db_type_for_jar_offline_entry(registry: &AgentRegistry, name: &str) -> Option<String> {
    let filename = name.rsplit('/').next()?;
    registry.drivers.iter().find_map(|(db_type, driver)| {
        let artifact = driver.jar.as_ref()?;
        let artifact_filename = artifact.url.rsplit('/').next()?;
        (artifact_filename == filename).then(|| db_type.clone())
    })
}

fn jre_archive_suffix(format: Option<ArtifactFormat>) -> &'static str {
    match format {
        Some(ArtifactFormat::TarZstd) => ".tar.zst",
        None => ".tar.gz",
    }
}

fn jre_archive_download_path(am: &AgentManager, jre_key: &str, format: Option<ArtifactFormat>) -> PathBuf {
    am.base_dir().join(format!("jre-{jre_key}-download{}", jre_archive_suffix(format)))
}

fn extract_jre_archive(archive: &Path, dest: &Path, format: Option<ArtifactFormat>) -> Result<(), String> {
    let mut last_error: Option<String> = None;
    for attempt in 0..ARCHIVE_EXTRACT_ATTEMPTS {
        if attempt > 0 {
            // Windows rename cannot replace an existing directory, so a failed
            // attempt may leave partial entries in dest and every retry would
            // then fail forever. Clear dest first; errors are ignored because
            // a failed attempt may also leave no dest at all, and extract recreates it.
            let _ = std::fs::remove_dir_all(dest);
            let delay_ms = ARCHIVE_EXTRACT_BACKOFF_MS.get(attempt - 1).copied().unwrap_or(500);
            std::thread::sleep(Duration::from_millis(delay_ms));
        }
        match extract_jre_archive_once(archive, dest, format) {
            Ok(()) => return Ok(()),
            Err(error) => {
                log::warn!(
                    "JRE archive extraction ({}) attempt {}/{} failed: {error}",
                    archive.display(),
                    attempt + 1,
                    ARCHIVE_EXTRACT_ATTEMPTS
                );
                last_error = Some(error);
            }
        }
    }
    Err(last_error.unwrap_or_else(|| "Failed to extract JRE archive".to_string()))
}

fn extract_jre_archive_once(archive: &Path, dest: &Path, format: Option<ArtifactFormat>) -> Result<(), String> {
    match format {
        Some(ArtifactFormat::TarZstd) => {
            let source = JreArchiveSource::TarZstd(archive);
            extract_jre_tar(source.open()?, dest, source)
        }
        None => extract_tar_gz(archive, dest),
    }
}

fn extract_tar_gz(archive: &Path, dest: &Path) -> Result<(), String> {
    let source = JreArchiveSource::TarGzip(archive);
    extract_jre_tar(source.open()?, dest, source)
}

/// A JRE archive on disk and the codec needed to read it.
///
/// The path is kept next to the open stream because a failed extraction replays
/// the archive once to report the entries that never reached the disk; see
/// `diagnose_jre_extract_failure`.
#[derive(Clone, Copy)]
enum JreArchiveSource<'a> {
    TarZstd(&'a Path),
    TarGzip(&'a Path),
}

impl JreArchiveSource<'_> {
    fn open(&self) -> Result<tar::Archive<Box<dyn Read>>, String> {
        let path = match self {
            Self::TarZstd(path) | Self::TarGzip(path) => *path,
        };
        let file = std::fs::File::open(path)
            .map_err(|error| format!("Failed to open JRE archive: {}", describe_error(&error)))?;
        let reader: Box<dyn Read> = match self {
            Self::TarZstd(_) => Box::new(
                zstd::stream::read::Decoder::new(file)
                    .map_err(|error| format!("Failed to open zstd JRE archive: {}", describe_error(&error)))?,
            ),
            Self::TarGzip(_) => Box::new(flate2::read::GzDecoder::new(file)),
        };
        Ok(tar::Archive::new(reader))
    }
}

fn extract_jre_tar(
    mut archive: tar::Archive<Box<dyn Read>>,
    dest: &Path,
    source: JreArchiveSource<'_>,
) -> Result<(), String> {
    let parent = dest.parent().ok_or_else(|| format!("Invalid JRE destination: {}", dest.display()))?;
    std::fs::create_dir_all(parent).map_err(|e| format!("Failed to create JRE directory: {}", describe_error(&e)))?;

    let staging = tempfile::Builder::new()
        .prefix(".jre-extract-")
        .tempdir_in(parent)
        .map_err(|e| format!("Failed to create JRE extraction directory: {}", describe_error(&e)))?;

    // Restoring POSIX permissions and mtimes has no Windows equivalent: the
    // emulation cannot express a real ACL and only adds ways for the extraction
    // to fail (a file-system filter refusing attribute changes), while the
    // read-only attribute it sets for 0444 entries later blocks removing a JRE
    // that is being replaced. POSIX keeps the archive modes, which is what makes
    // `bin/java` executable there.
    if cfg!(windows) {
        archive.set_preserve_permissions(false);
        archive.set_preserve_mtime(false);
    }

    if let Err(error) = archive.unpack(staging.path()) {
        return Err(format!(
            "Failed to extract JRE archive: {}{}",
            describe_error(&error),
            diagnose_jre_extract_failure(source, staging.path(), &error)
        ));
    }

    let mut roots = std::fs::read_dir(staging.path())
        .map_err(|e| format!("Failed to inspect extracted JRE archive: {}", describe_error(&e)))?
        .collect::<Result<Vec<_>, _>>()
        .map_err(|e| format!("Failed to inspect extracted JRE archive: {}", describe_error(&e)))?;
    if roots.len() != 1 {
        return Err("Invalid JRE archive: expected a single top-level directory".to_string());
    }

    let root = roots.pop().expect("root count checked above");
    if !root
        .file_type()
        .map_err(|e| format!("Failed to inspect extracted JRE archive: {}", describe_error(&e)))?
        .is_dir()
    {
        return Err("Invalid JRE archive: expected a top-level directory".to_string());
    }

    std::fs::create_dir_all(dest).map_err(|e| format!("Failed to create JRE directory: {}", describe_error(&e)))?;
    for entry in std::fs::read_dir(root.path())
        .map_err(|e| format!("Failed to inspect extracted JRE archive: {}", describe_error(&e)))?
    {
        let entry = entry.map_err(|e| format!("Failed to inspect extracted JRE archive: {}", describe_error(&e)))?;
        std::fs::rename(entry.path(), dest.join(entry.file_name()))
            .map_err(|e| format!("Failed to install extracted JRE: {}", describe_error(&e)))?;
    }
    Ok(())
}

/// Bytes written by the extraction probe that classifies a failed entry:
/// large enough to fail on a full or quota-limited disk, small enough to be
/// harmless.
const JRE_EXTRACT_PROBE_BYTES: usize = 64 * 1024;

/// Explain a failed extraction in terms a support engineer can act on.
///
/// `tar` names the entry it failed on and nothing else, so the same message
/// covered a full disk, a permission problem and a security product refusing a
/// single file name. JRE archives ship ~30 `api-ms-win-*.dll` API-set stubs in
/// `bin/`; droppers plant exactly that name for DLL hijacking, so endpoint
/// security products are known to reject it — and closing the anti-virus UI does
/// not remove the file-system filter behind it. Replaying the archive locates
/// the entries that never reached the disk, and probing the failing folder
/// separates "this folder is not writable" from "this file name is not
/// writable".
fn diagnose_jre_extract_failure(source: JreArchiveSource<'_>, staging: &Path, error: &dyn std::error::Error) -> String {
    let mut diagnosis = String::new();
    if let Some(hint) = deepest_io_error(error).and_then(|error| describe_extract_os_error(error.raw_os_error())) {
        diagnosis.push_str(&format!("\nThe OS error means {hint}."));
    }

    let store_root = staging.parent().unwrap_or(staging);
    match locate_unwritten_entries(source, staging) {
        Err(replay_error) => {
            diagnosis.push_str(&format!(
                "\nExtraction check: the archive could not be replayed ({replay_error}), so the archive itself is \
                 damaged or incomplete rather than the destination folder."
            ));
        }
        Ok(scan) => match (scan.first_failed, scan.first_failed_path) {
            (Some(name), Some(path)) => {
                diagnosis.push_str(&format!(
                    "\nExtraction check: {} file(s) are missing or incomplete; the first is `{name}`. {}",
                    scan.failed_count,
                    describe_unwritten_entry(&path, store_root, scan.first_failed_incomplete)
                ));
            }
            _ if scan.entry_count > 0 => {
                diagnosis.push_str(
                    "\nExtraction check: every file entry of the archive is on disk, so the failure came from a \
                     directory or link entry, or from moving the extracted JRE into place.",
                );
            }
            _ => {}
        },
    }
    diagnosis
}

/// Which entries a failed extraction left behind, from replaying the archive.
#[derive(Default)]
struct JreArchiveScan {
    /// Archive-relative name of the first entry that is missing or incomplete.
    first_failed: Option<String>,
    /// Destination path of that entry.
    first_failed_path: Option<PathBuf>,
    /// Set when that entry exists but is shorter than the archive says.
    first_failed_incomplete: bool,
    failed_count: usize,
    entry_count: usize,
}

impl JreArchiveScan {
    fn record_failure(&mut self, relative: PathBuf, destination: PathBuf, incomplete: bool) {
        self.failed_count += 1;
        if self.first_failed.is_none() {
            self.first_failed = Some(relative.to_string_lossy().replace('\\', "/"));
            self.first_failed_path = Some(destination);
            self.first_failed_incomplete = incomplete;
        }
    }
}

/// Replay the archive and report the file entries whose destination is missing
/// or shorter than the archive says. Directories, links and metadata entries are
/// skipped: only regular files carry a size that can be compared.
fn locate_unwritten_entries(source: JreArchiveSource<'_>, staging: &Path) -> Result<JreArchiveScan, String> {
    let mut archive = source.open()?;
    let mut scan = JreArchiveScan::default();
    let mut entries = archive.entries().map_err(|error| describe_error(&error))?;
    for entry in &mut entries {
        let entry = entry.map_err(|error| describe_error(&error))?;
        if !entry.header().entry_type().is_file() {
            continue;
        }
        let mut relative = PathBuf::new();
        for component in entry.path().map_err(|error| describe_error(&error))?.components() {
            match component {
                std::path::Component::Normal(value) => relative.push(value),
                std::path::Component::CurDir => {}
                _ => return Err(format!("unsafe entry path: {}", relative.display())),
            }
        }
        if relative.as_os_str().is_empty() {
            continue;
        }
        scan.entry_count += 1;
        let destination = staging.join(&relative);
        match std::fs::metadata(&destination).map(|metadata| metadata.len()) {
            Ok(length) if length == entry.size() => {}
            Ok(_) => scan.record_failure(relative, destination, true),
            Err(_) => scan.record_failure(relative, destination, false),
        }
    }
    Ok(scan)
}

fn describe_unwritten_entry(path: &Path, store_root: &Path, incomplete: bool) -> String {
    let directory = path.parent().unwrap_or(store_root);
    if incomplete {
        return format!(
            "The entry was created but is shorter than the archive says, so the write itself was interrupted — check \
             the free disk space and any anti-virus, backup or quota filter for `{}`.",
            directory.display()
        );
    }
    classify_extract_blocker(directory, path.file_name(), store_root)
}

/// Tell apart the reasons a file cannot be created in the export directory by
/// creating probes there: one with a random name, one with the failed name.
fn classify_extract_blocker(directory: &Path, name: Option<&std::ffi::OsStr>, store_root: &Path) -> String {
    let random_probe = probe_destination_write(directory, None);
    let named_probe = name.map(|name| probe_destination_write(directory, Some(name)));
    describe_extract_blocker(directory, store_root, random_probe, named_probe)
}

fn describe_extract_blocker(
    directory: &Path,
    store_root: &Path,
    random_probe: std::io::Result<()>,
    named_probe: Option<std::io::Result<()>>,
) -> String {
    match (random_probe, named_probe) {
        (Err(error), _) => format!(
            "Creating a test file in `{}` failed the same way ({error}), so the folder is not writable — check its \
             permissions, the free disk space and any anti-virus, backup or quota filter.",
            directory.display()
        ),
        (Ok(()), Some(Err(error))) if error.kind() == std::io::ErrorKind::AlreadyExists => format!(
            "A test file can be created in `{}` and the entry exists now, so the failure looks transient — retry the \
             import.",
            directory.display()
        ),
        (Ok(()), Some(Err(_))) => format!(
            "A differently named test file could be created in `{}`, but creating that exact file name failed the \
             same way, so the file name itself is rejected on this machine — usually an endpoint-security file \
             filter or a group policy. Whitelist `{}` or the dbx process and retry; closing the anti-virus UI alone \
             does not remove such a filter.",
            directory.display(),
            store_root.display()
        ),
        _ => format!(
            "Test files can be created in `{}` now, so the failure looks transient (a scanner, indexer or backup agent \
             holding the file) — retry the import.",
            directory.display()
        ),
    }
}

fn probe_destination_write(directory: &Path, name: Option<&std::ffi::OsStr>) -> std::io::Result<()> {
    match name {
        Some(name) => {
            let probe = directory.join(name);
            let result = std::fs::OpenOptions::new().write(true).create_new(true).open(&probe).map(|_| ());
            if result.is_ok() {
                let _ = std::fs::remove_file(&probe);
            }
            result
        }
        None => {
            let probe = directory.join(format!(".dbx-extract-probe-{}", uuid::Uuid::new_v4()));
            let result = std::fs::File::create(&probe)
                .and_then(|mut file| std::io::Write::write_all(&mut file, &[0u8; JRE_EXTRACT_PROBE_BYTES]));
            let _ = std::fs::remove_file(&probe);
            result
        }
    }
}

/// Explain the well-known OS errors an extraction can hit, so support does not
/// have to translate `os error 5` by hand.
fn describe_extract_os_error(code: Option<i32>) -> Option<&'static str> {
    let code = code?;
    #[cfg(windows)]
    {
        match code {
            112 => Some("the destination disk is full or the quota is exhausted"),
            5 => Some("the file or folder is blocked by permissions, a security product or a group policy"),
            32 | 33 => Some("another process is holding the file (a virus scanner, indexer or backup agent)"),
            206 => Some("the path is longer than the file system allows"),
            225 => Some("a security product rejected the file while it was written"),
            226 => Some("a security product deleted the file right after it was written"),
            _ => None,
        }
    }
    #[cfg(not(windows))]
    {
        match code {
            28 => Some("the destination disk is full or the quota is exhausted"),
            13 => Some("the file or folder is blocked by permissions, a security product or a group policy"),
            11 | 16 => Some("another process is holding the file (a virus scanner, indexer or backup agent)"),
            63 => Some("the path is longer than the file system allows"),
            _ => None,
        }
    }
}

#[cfg(test)]
mod jre_archive_tests {
    use super::*;
    use std::io::Cursor;

    fn append_file(
        builder: &mut tar::Builder<flate2::write::GzEncoder<std::fs::File>>,
        path: &str,
        data: &[u8],
        mode: u32,
    ) {
        let mut header = tar::Header::new_gnu();
        header.set_size(data.len() as u64);
        header.set_mode(mode);
        header.set_cksum();
        builder.append_data(&mut header, path, Cursor::new(data)).unwrap();
    }

    #[test]
    fn extracts_jre_archive_without_system_tools_and_strips_top_level_directory() {
        let temp = tempfile::tempdir().unwrap();
        let archive_path = temp.path().join("jre.tar.gz");
        let encoder = flate2::write::GzEncoder::new(
            std::fs::File::create(&archive_path).unwrap(),
            flate2::Compression::default(),
        );
        let mut builder = tar::Builder::new(encoder);
        append_file(&mut builder, "jdk-21/bin/java", b"java", 0o755);
        append_file(&mut builder, "jdk-21/conf/release", b"JAVA_VERSION=21", 0o644);
        builder.into_inner().unwrap().finish().unwrap();

        let dest = temp.path().join("managed-jre");
        extract_tar_gz(&archive_path, &dest).unwrap();

        assert_eq!(std::fs::read(dest.join("bin/java")).unwrap(), b"java");
        assert_eq!(std::fs::read(dest.join("conf/release")).unwrap(), b"JAVA_VERSION=21");
        assert!(!dest.join("jdk-21").exists());

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            assert_eq!(std::fs::metadata(dest.join("bin/java")).unwrap().permissions().mode() & 0o777, 0o755);
        }
    }

    #[test]
    fn rejects_jre_archive_without_a_single_top_level_directory() {
        let temp = tempfile::tempdir().unwrap();
        let archive_path = temp.path().join("jre.tar.gz");
        let encoder = flate2::write::GzEncoder::new(
            std::fs::File::create(&archive_path).unwrap(),
            flate2::Compression::default(),
        );
        let mut builder = tar::Builder::new(encoder);
        append_file(&mut builder, "jdk-21/bin/java", b"java", 0o755);
        append_file(&mut builder, "unexpected/readme.txt", b"unexpected", 0o644);
        builder.into_inner().unwrap().finish().unwrap();

        let error = extract_tar_gz(&archive_path, &temp.path().join("managed-jre")).unwrap_err();
        assert!(error.contains("single top-level directory"), "unexpected error: {error}");
    }

    /// `tar` prints only its own description and keeps the OS error one level
    /// deeper in the source chain, which is the shape that hid Windows
    /// anti-virus and disk failures from the offline-import UI.
    #[derive(Debug)]
    struct ArchiveLikeError {
        description: String,
        io: std::io::Error,
    }

    impl std::fmt::Display for ArchiveLikeError {
        fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            formatter.write_str(&self.description)
        }
    }

    impl std::error::Error for ArchiveLikeError {
        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
            Some(&self.io)
        }
    }

    /// A failed extraction must name the entry that never reached the disk, not
    /// just the `tar` description that stopped at the first bad write.
    #[test]
    fn reports_the_entry_that_never_reached_the_disk() {
        let temp = tempfile::tempdir().unwrap();
        let archive_path = temp.path().join("jre.tar.gz");
        let encoder = flate2::write::GzEncoder::new(
            std::fs::File::create(&archive_path).unwrap(),
            flate2::Compression::default(),
        );
        let mut builder = tar::Builder::new(encoder);
        // The second entry cannot be created because its parent is a file.
        append_file(&mut builder, "jdk-21/bin", b"not a directory", 0o644);
        append_file(&mut builder, "jdk-21/bin/java", b"java", 0o755);
        builder.into_inner().unwrap().finish().unwrap();

        let error = extract_tar_gz(&archive_path, &temp.path().join("managed-jre")).unwrap_err();

        assert!(error.starts_with("Failed to extract JRE archive:"), "unexpected error: {error}");
        assert!(error.contains("`jdk-21/bin/java`"), "unexpected error: {error}");
        assert!(error.contains("1 file(s) are missing or incomplete"), "unexpected error: {error}");
        assert!(error.contains("Extraction check:"), "unexpected error: {error}");
    }

    #[test]
    fn reports_a_damaged_archive_instead_of_a_destination_problem() {
        let temp = tempfile::tempdir().unwrap();
        let archive_path = temp.path().join("jre.tar.gz");
        let encoder = flate2::write::GzEncoder::new(
            std::fs::File::create(&archive_path).unwrap(),
            flate2::Compression::default(),
        );
        let mut builder = tar::Builder::new(encoder);
        append_file(&mut builder, "jdk-21/lib/modules", &vec![b'x'; 512 * 1024], 0o644);
        builder.into_inner().unwrap().finish().unwrap();
        let full = std::fs::read(&archive_path).unwrap();
        std::fs::write(&archive_path, &full[..full.len() / 2]).unwrap();

        let error = extract_tar_gz(&archive_path, &temp.path().join("managed-jre")).unwrap_err();

        assert!(error.contains("could not be replayed"), "unexpected error: {error}");
        assert!(error.contains("damaged or incomplete"), "unexpected error: {error}");
    }

    #[test]
    fn classifies_a_rejected_file_name_as_a_security_filter() {
        let temp = tempfile::tempdir().unwrap();
        let denied = std::io::Error::from_raw_os_error(if cfg!(windows) { 5 } else { 13 });

        let message = describe_extract_blocker(&temp.path().join("bin"), temp.path(), Ok(()), Some(Err(denied)));

        assert!(message.contains("file name itself is rejected"), "unexpected message: {message}");
        assert!(message.contains(&temp.path().display().to_string()), "unexpected message: {message}");
    }

    #[test]
    fn classifies_an_existing_entry_as_transient() {
        let temp = tempfile::tempdir().unwrap();
        let existing = std::io::Error::from(std::io::ErrorKind::AlreadyExists);

        let message = describe_extract_blocker(&temp.path().join("bin"), temp.path(), Ok(()), Some(Err(existing)));

        assert!(message.contains("transient"), "unexpected message: {message}");
    }

    #[cfg(unix)]
    #[test]
    fn classifies_an_unwritable_folder() {
        use std::os::unix::fs::PermissionsExt;

        let temp = tempfile::tempdir().unwrap();
        let directory = temp.path().join("bin");
        std::fs::create_dir(&directory).unwrap();
        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o500)).unwrap();

        let message = classify_extract_blocker(&directory, Some(std::ffi::OsStr::new("java")), temp.path());

        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o755)).unwrap();
        assert!(message.contains("folder is not writable"), "unexpected message: {message}");
    }

    #[test]
    fn classifies_a_writable_folder_as_transient_and_cleans_up_the_probes() {
        let temp = tempfile::tempdir().unwrap();
        let directory = temp.path().join("bin");
        std::fs::create_dir(&directory).unwrap();

        let message = classify_extract_blocker(&directory, Some(std::ffi::OsStr::new("java")), temp.path());

        assert!(message.contains("transient"), "unexpected message: {message}");
        assert_eq!(std::fs::read_dir(&directory).unwrap().count(), 0, "probe files must not be left behind");
    }

    #[test]
    fn explains_well_known_os_errors() {
        let disk_full = if cfg!(windows) { 112 } else { 28 };
        let denied = if cfg!(windows) { 5 } else { 13 };

        assert!(describe_extract_os_error(Some(disk_full)).unwrap().contains("disk is full"));
        assert!(describe_extract_os_error(Some(denied)).unwrap().contains("permissions"));
        assert_eq!(describe_extract_os_error(Some(0)), None);
        assert_eq!(describe_extract_os_error(None), None);

        // A security product that blocks the write itself reports these
        // Windows codes; POSIX has no counterpart.
        if cfg!(windows) {
            assert!(describe_extract_os_error(Some(225)).unwrap().contains("rejected the file"));
            assert!(describe_extract_os_error(Some(226)).unwrap().contains("deleted the file"));
        } else {
            assert_eq!(describe_extract_os_error(Some(225)), None);
            assert_eq!(describe_extract_os_error(Some(226)), None);
        }
    }

    #[test]
    fn describes_the_os_error_behind_an_archive_message() {
        let error = std::io::Error::other(ArchiveLikeError {
            description: "failed to unpack `dbx-jre/bin/api-ms-win-core-string-l1-1-0.dll`".to_string(),
            io: std::io::Error::from_raw_os_error(5),
        });

        let message = describe_error(&error);

        assert!(
            message.starts_with("failed to unpack `dbx-jre/bin/api-ms-win-core-string-l1-1-0.dll`"),
            "unexpected message: {message}"
        );
        assert!(message.contains("os error 5"), "unexpected message: {message}");
    }

    #[test]
    fn describes_a_message_that_already_carries_the_os_error_unchanged() {
        let os_error = std::io::Error::from_raw_os_error(5);
        let expected = os_error.to_string();
        let error = std::io::Error::other(os_error);

        assert_eq!(describe_error(&error), expected);
    }
}

pub async fn import_agent_driver(am: &AgentManager, db_type: &str, source_path: &Path) -> Result<(), String> {
    // Manual imports replace the same artifact paths as downloads. Reuse the
    // install operation and per-driver locks so an import cannot race an
    // install, Upgrade All, or uninstall for this driver.
    let _installation_guard = am.installation_operation_lock.read().await;
    let driver_lock = driver_operation_lock(am, db_type);
    let _driver_guard = driver_lock.lock().await;

    if !source_path.is_file() {
        return Err(format!("File not found: {}", source_path.display()));
    }

    stop_driver_processes_before_replacement(am, db_type).await?;

    if source_path.extension().is_some_and(|extension| extension.eq_ignore_ascii_case("jar")) {
        install_local_agent(am, db_type, source_path.to_path_buf())?;
        std::fs::remove_file(am.driver_native_path(db_type)).ok();
        return Ok(());
    }

    validate_native_agent_binary(source_path)?;
    let native_path = am.driver_native_path(db_type);
    let parent = native_path.parent().ok_or_else(|| format!("Invalid driver path: {}", native_path.display()))?;
    std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    let staging_path = parent.join(format!(".agent-import-{}", uuid::Uuid::new_v4()));
    std::fs::copy(source_path, &staging_path).map_err(|e| format!("Failed to copy native agent: {e}"))?;
    mark_executable(&staging_path)?;
    replace_imported_agent_file(&staging_path, &native_path)?;
    std::fs::remove_file(am.driver_jar_path(db_type)).ok();

    am.mutate_state(|state| {
        state.installed_drivers.insert(
            db_type.to_string(),
            InstalledDriver {
                version: "0.1.0-local".to_string(),
                installed_at: chrono::Utc::now().to_rfc3339(),
                jre: DEFAULT_JRE_KEY.to_string(),
            },
        );
    })
}

pub async fn import_agent_jar(am: &AgentManager, db_type: &str, jar_path: &Path) -> Result<(), String> {
    import_agent_driver(am, db_type, jar_path).await
}

fn replace_imported_agent_file(staging_path: &Path, target_path: &Path) -> Result<(), String> {
    let backup_path = target_path.with_file_name(format!(
        ".{}-backup-{}",
        target_path.file_name().and_then(|name| name.to_str()).unwrap_or("agent"),
        uuid::Uuid::new_v4()
    ));
    let had_existing = target_path.exists();
    if had_existing {
        std::fs::rename(target_path, &backup_path).map_err(|e| format!("Failed to replace existing agent: {e}"))?;
    }
    if let Err(error) = std::fs::rename(staging_path, target_path) {
        if had_existing {
            let _ = std::fs::rename(&backup_path, target_path);
        }
        let _ = std::fs::remove_file(staging_path);
        return Err(format!("Failed to install agent: {error}"));
    }
    if had_existing {
        std::fs::remove_file(backup_path).ok();
    }
    Ok(())
}

fn replace_imported_jre_dir(staging_dir: &Path, target_dir: &Path) -> Result<Option<PathBuf>, String> {
    let backup_dir = target_dir.with_file_name(format!(
        ".{}-backup-{}",
        target_dir.file_name().and_then(|name| name.to_str()).unwrap_or("jre"),
        uuid::Uuid::new_v4()
    ));
    let had_existing = target_dir.exists();
    if had_existing {
        std::fs::rename(target_dir, &backup_dir).map_err(|error| {
            let _ = std::fs::remove_dir_all(staging_dir);
            format!("Failed to replace existing JRE: {error}")
        })?;
    }
    if let Err(error) = std::fs::rename(staging_dir, target_dir) {
        if had_existing {
            let _ = std::fs::rename(&backup_dir, target_dir);
        }
        let _ = std::fs::remove_dir_all(staging_dir);
        return Err(format!("Failed to install JRE: {error}"));
    }
    if had_existing && remove_jre_dir_with_retry(&backup_dir).is_err() {
        // The new runtime is already installed. Keep the old directory for
        // startup cleanup rather than turning a successful import into an error.
        return Ok(Some(backup_dir));
    }
    Ok(None)
}

fn jre_dir_contains_java(path: &Path) -> bool {
    let java_name = if cfg!(windows) { "java.exe" } else { "java" };
    path.join("bin").join(java_name).is_file()
        || path.join("Contents").join("Home").join("bin").join(java_name).is_file()
}

pub fn validate_native_agent_binary(path: &Path) -> Result<(), String> {
    validate_native_agent_binary_for_platform(path, AgentManager::current_platform())
}

pub fn validate_native_agent_binary_for_platform(path: &Path, platform: &str) -> Result<(), String> {
    let mut file = std::fs::File::open(path).map_err(|e| format!("Failed to read native agent: {e}"))?;
    let mut magic = [0_u8; 4];
    file.read_exact(&mut magic).map_err(|e| format!("Failed to read native agent header: {e}"))?;
    let valid = match platform {
        "linux-x64" => is_elf_binary_for_machine(&mut file, &magic, 62),
        "linux-aarch64" => is_elf_binary_for_machine(&mut file, &magic, 183),
        "macos-x64" => is_macho_binary_for_cpu(&mut file, &magic, 0x0100_0007),
        "macos-aarch64" => is_macho_binary_for_cpu(&mut file, &magic, 0x0100_000c),
        "windows-x64" => is_windows_binary_for_machine(&mut file, &magic, 0x8664),
        "windows-aarch64" => is_windows_binary_for_machine(&mut file, &magic, 0xaa64),
        _ => false,
    };
    if valid {
        Ok(())
    } else {
        Err(format!("The selected file is not a {platform} native agent"))
    }
}

fn is_elf_binary_for_machine(file: &mut std::fs::File, magic: &[u8; 4], expected_machine: u16) -> bool {
    if magic != b"\x7fELF" || file.seek(SeekFrom::Start(4)).is_err() {
        return false;
    }
    let mut header = [0_u8; 16];
    if file.read_exact(&mut header).is_err() || header[0] != 2 {
        return false;
    }
    let machine = match header[1] {
        1 => u16::from_le_bytes([header[14], header[15]]),
        2 => u16::from_be_bytes([header[14], header[15]]),
        _ => return false,
    };
    machine == expected_machine
}

fn is_macho_binary_for_cpu(file: &mut std::fs::File, magic: &[u8; 4], expected: u32) -> bool {
    let thin_endian = match magic {
        [0xce, 0xfa, 0xed, 0xfe] | [0xcf, 0xfa, 0xed, 0xfe] => Some(true),
        [0xfe, 0xed, 0xfa, 0xce] | [0xfe, 0xed, 0xfa, 0xcf] => Some(false),
        _ => None,
    };
    if let Some(little_endian) = thin_endian {
        if file.seek(SeekFrom::Start(4)).is_err() {
            return false;
        }
        let mut cpu_type = [0_u8; 4];
        if file.read_exact(&mut cpu_type).is_err() {
            return false;
        }
        let cpu_type = if little_endian { u32::from_le_bytes(cpu_type) } else { u32::from_be_bytes(cpu_type) };
        return cpu_type == expected;
    }

    let (little_endian, arch_size) = match magic {
        [0xca, 0xfe, 0xba, 0xbe] => (false, 20_u64),
        [0xbe, 0xba, 0xfe, 0xca] => (true, 20_u64),
        [0xca, 0xfe, 0xba, 0xbf] => (false, 32_u64),
        [0xbf, 0xba, 0xfe, 0xca] => (true, 32_u64),
        _ => return false,
    };
    if file.seek(SeekFrom::Start(4)).is_err() {
        return false;
    }
    let mut count = [0_u8; 4];
    if file.read_exact(&mut count).is_err() {
        return false;
    }
    let count = if little_endian { u32::from_le_bytes(count) } else { u32::from_be_bytes(count) };
    // A real universal binary has only a handful of slices; cap the count so
    // a malformed header cannot trigger unbounded seeks during import.
    if count == 0 || count > 64 {
        return false;
    }
    for index in 0..count {
        if file.seek(SeekFrom::Start(8 + u64::from(index) * arch_size)).is_err() {
            return false;
        }
        let mut cpu_type = [0_u8; 4];
        if file.read_exact(&mut cpu_type).is_err() {
            return false;
        }
        let cpu_type = if little_endian { u32::from_le_bytes(cpu_type) } else { u32::from_be_bytes(cpu_type) };
        if cpu_type == expected {
            return true;
        }
    }
    false
}

fn is_windows_binary_for_machine(file: &mut std::fs::File, magic: &[u8; 4], expected_machine: u16) -> bool {
    if &magic[..2] != b"MZ" || file.seek(SeekFrom::Start(0x3c)).is_err() {
        return false;
    }
    let mut pe_offset = [0_u8; 4];
    if file.read_exact(&mut pe_offset).is_err()
        || file.seek(SeekFrom::Start(u32::from_le_bytes(pe_offset) as u64)).is_err()
    {
        return false;
    }
    let mut pe_header = [0_u8; 6];
    if file.read_exact(&mut pe_header).is_err() || &pe_header[..4] != b"PE\0\0" {
        return false;
    }
    let machine = u16::from_le_bytes([pe_header[4], pe_header[5]]);
    machine == expected_machine
}

// ──────────── Tests ────────────

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

    #[test]
    fn managed_driver_process_matches_jar_argument_or_native_executable() {
        let target = ManagedAgentProcessTarget::Driver {
            jar_path: PathBuf::from(r"C:\Users\alice\.dbx\agents\drivers\dameng\agent.jar"),
            native_path: PathBuf::from(r"C:\Users\alice\.dbx\agents\drivers\dameng\agent.exe"),
        };
        let java_command = vec![
            std::ffi::OsString::from("-jar"),
            std::ffi::OsString::from(r"c:/users/ALICE/.dbx/agents/drivers/dameng/agent.jar"),
        ];

        assert!(process_matches_managed_agent(
            Some(Path::new(r"C:\Users\alice\.dbx\agents\jre-21\bin\java.exe")),
            &java_command,
            &target
        ));
        assert!(process_matches_managed_agent(
            Some(Path::new(r"\\?\C:\Users\alice\.dbx\agents\drivers\dameng\agent.exe")),
            &[],
            &target
        ));
        assert!(!process_matches_managed_agent(
            Some(Path::new(r"C:\Program Files\Java\bin\java.exe")),
            &[std::ffi::OsString::from(r"C:\tmp\agent.jar")],
            &target
        ));
    }

    #[test]
    fn managed_jre_process_requires_a_path_boundary() {
        let target = ManagedAgentProcessTarget::JreDirectory(PathBuf::from(r"C:\Users\alice\.dbx\agents\jre-21"));

        assert!(process_matches_managed_agent(
            Some(Path::new(r"c:/users/alice/.dbx/agents/jre-21/bin/java.exe")),
            &[],
            &target
        ));
        assert!(!process_matches_managed_agent(
            Some(Path::new(r"C:\Users\alice\.dbx\agents\jre-210\bin\java.exe")),
            &[],
            &target
        ));
    }

    #[test]
    fn r2_cache_buster_uses_version_query() {
        assert_eq!(
            r2_path_with_cache_buster("agents/jre/dbx-jre-21-macos-x64.tar.gz", "21.0.11+7"),
            "agents/jre/dbx-jre-21-macos-x64.tar.gz?v=21.0.11-7"
        );
    }

    #[test]
    fn r2_cache_buster_preserves_existing_query() {
        assert_eq!(
            r2_path_with_cache_buster("agents/drivers/dbx-agent-h2.jar?mirror=r2", "0.5.33"),
            "agents/drivers/dbx-agent-h2.jar?mirror=r2&v=0.5.33"
        );
    }

    #[test]
    fn offline_jre_filename_parser_accepts_release_and_legacy_names() {
        assert_eq!(extract_jre_key_from_filename("jre/dbx-jre-21-macos-aarch64.tar.gz").as_deref(), Some("21"));
        assert_eq!(extract_jre_key_from_filename("jre/jre-21-macos-aarch64.tar.gz").as_deref(), Some("21"));
    }

    #[test]
    fn windows_native_header_validator_checks_cpu_architecture() {
        let path = std::env::temp_dir().join(format!("dbx-agent-pe-test-{}", uuid::Uuid::new_v4()));
        let expected_machine = if cfg!(target_arch = "aarch64") { 0xaa64_u16 } else { 0x8664_u16 };
        let wrong_machine = if expected_machine == 0xaa64 { 0x8664_u16 } else { 0xaa64_u16 };

        std::fs::write(&path, test_pe_binary(expected_machine)).unwrap();
        let mut file = std::fs::File::open(&path).unwrap();
        assert!(is_windows_binary_for_machine(&mut file, b"MZ\0\0", expected_machine));

        std::fs::write(&path, test_pe_binary(wrong_machine)).unwrap();
        let mut file = std::fs::File::open(&path).unwrap();
        assert!(!is_windows_binary_for_machine(&mut file, b"MZ\0\0", expected_machine));
        std::fs::remove_file(path).ok();
    }

    fn test_pe_binary(machine: u16) -> Vec<u8> {
        let mut bytes = vec![0_u8; 0x48];
        bytes[..2].copy_from_slice(b"MZ");
        bytes[0x3c..0x40].copy_from_slice(&(0x40_u32).to_le_bytes());
        bytes[0x40..0x44].copy_from_slice(b"PE\0\0");
        bytes[0x44..0x46].copy_from_slice(&machine.to_le_bytes());
        bytes
    }
}

#[cfg(test)]
mod agent_registry_install_tests {
    use super::*;
    use crate::agent_manager::{ArtifactFormat, ArtifactInfo, DriverInfo, InstalledDriver, JavaRuntimeConfig, JreInfo};

    static ENSURE_AGENT_TEST_LOCK: std::sync::LazyLock<tokio::sync::Mutex<()>> =
        std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));

    fn test_manager(name: &str) -> AgentManager {
        let dir = std::env::temp_dir().join(format!("dbx-agent-registry-install-{name}-{}", uuid::Uuid::new_v4()));
        AgentManager::new_with_base_dir(dir)
    }

    #[test]
    fn driver_operation_lock_is_removed_after_last_handle_drops() {
        let manager = test_manager("driver-lock-cleanup");
        let lock = driver_operation_lock(&manager, "oracle");

        assert_eq!(manager.driver_operation_locks.lock().unwrap().len(), 1);
        drop(lock);
        assert!(manager.driver_operation_locks.lock().unwrap().is_empty());
    }

    #[test]
    fn jre_operation_lock_stays_until_all_handles_drop() {
        let manager = test_manager("jre-lock-cleanup");
        let first = jre_operation_lock(&manager, DEFAULT_JRE_KEY);
        let second = jre_operation_lock(&manager, DEFAULT_JRE_KEY);

        drop(first);
        assert_eq!(manager.jre_install_locks.lock().unwrap().len(), 1);
        drop(second);
        assert!(manager.jre_install_locks.lock().unwrap().is_empty());
    }

    fn write_test_agent_jar(path: &Path) {
        use std::io::Write;

        let file = std::fs::File::create(path).unwrap();
        let mut archive = zip::ZipWriter::new(file);
        archive.start_file("META-INF/MANIFEST.MF", zip::write::SimpleFileOptions::default()).unwrap();
        archive.write_all(b"Manifest-Version: 1.0\nMain-Class: com.dbx.Agent\n").unwrap();
        archive.finish().unwrap();
    }

    fn registry_with_native_and_legacy_jar(
        db_type: &str,
        version: &str,
        native_url: &str,
        native_size: u64,
    ) -> AgentRegistry {
        let mut drivers = std::collections::HashMap::new();
        drivers.insert(
            db_type.to_string(),
            DriverInfo {
                version: version.to_string(),
                label: db_type.to_string(),
                min_app_version: "0.1.0".to_string(),
                jre: DEFAULT_JRE_KEY.to_string(),
                jar: Some(ArtifactInfo {
                    url: format!("https://example.com/dbx-agent-{db_type}-legacy-placeholder.jar"),
                    sha256: None,
                    size: 0,
                    format: None,
                    delta: None,
                }),
                native: [(
                    AgentManager::current_platform().to_string(),
                    ArtifactInfo {
                        url: native_url.to_string(),
                        sha256: None,
                        size: native_size,
                        format: None,
                        delta: None,
                    },
                )]
                .into_iter()
                .collect(),
            },
        );
        AgentRegistry { jre: None, jres: std::collections::HashMap::new(), drivers }
    }

    fn registry_with_jar(db_type: &str, version: &str, url: &str, size: u64) -> AgentRegistry {
        let mut drivers = std::collections::HashMap::new();
        drivers.insert(
            db_type.to_string(),
            DriverInfo {
                version: version.to_string(),
                label: db_type.to_string(),
                min_app_version: "0.1.0".to_string(),
                jre: DEFAULT_JRE_KEY.to_string(),
                jar: Some(ArtifactInfo { url: url.to_string(), sha256: None, size, format: None, delta: None }),
                native: std::collections::HashMap::new(),
            },
        );
        AgentRegistry { jre: None, jres: std::collections::HashMap::new(), drivers }
    }

    fn registry_with_jre_version(version: &str) -> AgentRegistry {
        AgentRegistry {
            jre: None,
            jres: [(
                DEFAULT_JRE_KEY.to_string(),
                JreInfo { version: version.to_string(), platforms: std::collections::HashMap::new() },
            )]
            .into_iter()
            .collect(),
            drivers: std::collections::HashMap::new(),
        }
    }

    fn write_cached_driver_download(
        am: &AgentManager,
        db_type: &str,
        version: &str,
        url: &str,
        dest: &Path,
        bytes: &[u8],
    ) -> PathBuf {
        let cache_path = cached_download_path(
            am,
            url,
            bytes.len() as u64,
            None,
            Some(CacheIdentity::Driver { db_type, version }),
            dest,
        );
        std::fs::create_dir_all(cache_path.parent().unwrap()).unwrap();
        std::fs::write(&cache_path, bytes).unwrap();
        cache_path
    }

    fn current_platform_native_binary() -> Vec<u8> {
        if cfg!(windows) {
            let mut bytes = vec![0_u8; 0x48];
            bytes[..2].copy_from_slice(b"MZ");
            bytes[0x3c..0x40].copy_from_slice(&(0x40_u32).to_le_bytes());
            bytes[0x40..0x44].copy_from_slice(b"PE\0\0");
            let machine = if cfg!(target_arch = "aarch64") { 0xaa64_u16 } else { 0x8664_u16 };
            bytes[0x44..0x46].copy_from_slice(&machine.to_le_bytes());
            bytes
        } else if cfg!(target_os = "linux") {
            let mut bytes = vec![0_u8; 20];
            bytes[..4].copy_from_slice(b"\x7fELF");
            bytes[4] = 2;
            bytes[5] = 1;
            let machine = if cfg!(target_arch = "aarch64") { 183_u16 } else { 62_u16 };
            bytes[18..20].copy_from_slice(&machine.to_le_bytes());
            bytes
        } else if cfg!(target_os = "macos") {
            let mut bytes = vec![0xcf, 0xfa, 0xed, 0xfe];
            let cpu_type = if cfg!(target_arch = "aarch64") { 0x0100_000c_u32 } else { 0x0100_0007_u32 };
            bytes.extend_from_slice(&cpu_type.to_le_bytes());
            bytes
        } else {
            Vec::new()
        }
    }

    fn test_agent_jar() -> Vec<u8> {
        let mut bytes = std::io::Cursor::new(Vec::new());
        {
            use std::io::Write;
            let mut archive = zip::ZipWriter::new(&mut bytes);
            archive.start_file("META-INF/MANIFEST.MF", zip::write::SimpleFileOptions::default()).unwrap();
            archive.write_all(b"Manifest-Version: 1.0\nMain-Class: com.dbx.Agent\n").unwrap();
            archive.finish().unwrap();
        }
        bytes.into_inner()
    }

    fn sha256_bytes(bytes: &[u8]) -> String {
        format!("{:x}", Sha256::digest(bytes))
    }

    fn write_offline_zip(registry: &AgentRegistry, entries: &[(String, Vec<u8>)]) -> (tempfile::TempDir, PathBuf) {
        use std::io::Write;

        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("agents.zip");
        let file = std::fs::File::create(&path).unwrap();
        let mut archive = zip::ZipWriter::new(file);
        let options = zip::write::SimpleFileOptions::default();
        archive.start_file("agent-registry.json", options).unwrap();
        archive.write_all(&serde_json::to_vec(registry).unwrap()).unwrap();
        for (name, bytes) in entries {
            archive.start_file(name, options).unwrap();
            archive.write_all(bytes).unwrap();
        }
        archive.finish().unwrap();
        (temp, path)
    }

    fn build_tar_zstd_driver_package(
        db_type: &str,
        version: &str,
        kind: DriverArtifactKind,
        driver_bytes: &[u8],
    ) -> Vec<u8> {
        let platform = AgentManager::current_platform();
        let (filename, artifact) = match kind {
            DriverArtifactKind::Jar => (
                format!("dbx-agent-{db_type}-{version}.jar"),
                serde_json::json!({
                    "jar": {
                        "url": format!("dbx-agent-{db_type}-{version}.jar"),
                        "size": driver_bytes.len()
                    }
                }),
            ),
            DriverArtifactKind::Native => {
                let extension = if platform.starts_with("windows-") { ".exe" } else { "" };
                let filename = format!("dbx-agent-{db_type}-{version}-{platform}{extension}");
                (
                    filename.clone(),
                    serde_json::json!({
                        "native": {
                            platform: {
                                "url": filename,
                                "size": driver_bytes.len()
                            }
                        }
                    }),
                )
            }
        };
        let mut driver = serde_json::json!({
            "version": version,
            "label": db_type,
            "min_app_version": "0.6.0",
            "jre": DEFAULT_JRE_KEY
        });
        driver.as_object_mut().unwrap().extend(artifact.as_object().unwrap().clone());
        let registry = serde_json::json!({
            "jres": {},
            "drivers": {
                db_type: driver
            }
        });
        let registry_bytes = registry.to_string().into_bytes();
        let encoder = zstd::stream::write::Encoder::new(Vec::new(), 3).unwrap();
        let mut archive = tar::Builder::new(encoder);

        let mut registry_header = tar::Header::new_gnu();
        registry_header.set_size(registry_bytes.len() as u64);
        registry_header.set_mode(0o644);
        registry_header.set_cksum();
        archive.append_data(&mut registry_header, "agent-registry.json", registry_bytes.as_slice()).unwrap();

        let mut driver_header = tar::Header::new_gnu();
        driver_header.set_size(driver_bytes.len() as u64);
        driver_header.set_mode(if kind == DriverArtifactKind::Native { 0o755 } else { 0o644 });
        driver_header.set_cksum();
        archive.append_data(&mut driver_header, format!("drivers/{filename}"), driver_bytes).unwrap();

        archive.into_inner().unwrap().finish().unwrap()
    }

    #[test]
    fn managed_jre_content_revision_triggers_install() {
        let manager = test_manager("jre-content-revision");
        let java_path = manager.jre_java_path(DEFAULT_JRE_KEY);
        std::fs::create_dir_all(java_path.parent().unwrap()).unwrap();
        std::fs::write(&java_path, b"java").unwrap();

        let mut state = crate::agent_manager::AgentState::default();
        state.jre_versions.insert(DEFAULT_JRE_KEY.to_string(), "21.0.12+kerberos.1".to_string());
        manager.save_state(&state).unwrap();

        let registry = registry_with_jre_version("21.0.12+kerberos.ec.2");
        assert!(jre_needs_install(&manager, &registry, DEFAULT_JRE_KEY));

        state.jre_versions.insert(DEFAULT_JRE_KEY.to_string(), "21.0.12+kerberos.ec.2".to_string());
        manager.save_state(&state).unwrap();
        assert!(!jre_needs_install(&manager, &registry, DEFAULT_JRE_KEY));
    }

    fn install_jre(manager: &AgentManager) {
        let java_path = manager.jre_java_path(DEFAULT_JRE_KEY);
        std::fs::create_dir_all(java_path.parent().unwrap()).unwrap();
        std::fs::write(&java_path, b"java").unwrap();
        let mut state = manager.load_state();
        state.jre_versions.insert(DEFAULT_JRE_KEY.to_string(), "21.0.0".to_string());
        manager.save_state(&state).unwrap();
    }

    fn record_driver(manager: &AgentManager, db_type: &str) {
        let mut state = manager.load_state();
        state.installed_drivers.insert(
            db_type.to_string(),
            InstalledDriver {
                version: "1.0.0".to_string(),
                installed_at: "2026-01-01T00:00:00Z".to_string(),
                jre: DEFAULT_JRE_KEY.to_string(),
            },
        );
        manager.save_state(&state).unwrap();
    }

    #[tokio::test]
    async fn uninstall_jre_ignores_native_driver_dependents() {
        // A native (non-Java) driver still records the JRE key in its state
        // entry, but must not block uninstalling the JRE it never uses.
        let manager = test_manager("jre-uninstall-native-dependent");
        install_jre(&manager);
        std::fs::create_dir_all(manager.driver_dir("kafka")).unwrap();
        std::fs::write(manager.driver_native_path("kafka"), b"native-binary").unwrap();
        record_driver(&manager, "kafka");

        uninstall_agent_jre(&manager, DEFAULT_JRE_KEY).await.expect("native driver must not block JRE uninstall");
    }

    #[tokio::test]
    async fn uninstall_jre_blocked_by_jar_driver_dependent() {
        // A JAR (Java) driver genuinely depends on the JRE and must block the
        // uninstall so the driver keeps a runtime.
        let manager = test_manager("jre-uninstall-jar-dependent");
        install_jre(&manager);
        std::fs::create_dir_all(manager.driver_dir("mysql")).unwrap();
        std::fs::write(manager.driver_jar_path("mysql"), test_agent_jar()).unwrap();
        record_driver(&manager, "mysql");

        let err = uninstall_agent_jre(&manager, DEFAULT_JRE_KEY).await.expect_err("jar driver must block uninstall");
        assert!(err.contains("is in use by drivers"), "unexpected error: {err}");
        assert!(err.contains("mysql"), "expected dependent driver in error: {err}");
    }

    fn registry_with_jre(jre_key: &str, version: &str, url: &str, size: u64) -> AgentRegistry {
        AgentRegistry {
            jre: None,
            jres: [(
                jre_key.to_string(),
                JreInfo {
                    version: version.to_string(),
                    platforms: [(
                        AgentManager::current_platform().to_string(),
                        ArtifactInfo { url: url.to_string(), sha256: None, size, format: None, delta: None },
                    )]
                    .into_iter()
                    .collect(),
                },
            )]
            .into_iter()
            .collect(),
            drivers: std::collections::HashMap::new(),
        }
    }

    fn build_jre_archive(am: &AgentManager, jre_key: &str) -> Vec<u8> {
        let archive_root = am.base_dir().join("jre-test-archive");
        let payload = archive_root.join("payload");
        let java_path = am.jre_java_path(jre_key);
        let relative_java_path = java_path.strip_prefix(am.jre_dir(jre_key)).unwrap();
        let java_path = payload.join(relative_java_path);
        std::fs::create_dir_all(java_path.parent().unwrap()).unwrap();
        std::fs::write(java_path, b"java").unwrap();
        let encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
        let mut builder = tar::Builder::new(encoder);
        builder.append_dir_all("payload", &payload).unwrap();
        builder.into_inner().unwrap().finish().unwrap()
    }

    fn build_zstd_jre_archive(am: &AgentManager, jre_key: &str) -> Vec<u8> {
        let archive_root = am.base_dir().join("jre-zstd-test-archive");
        let payload = archive_root.join("payload");
        let java_path = am.jre_java_path(jre_key);
        let relative_java_path = java_path.strip_prefix(am.jre_dir(jre_key)).unwrap();
        let java_path = payload.join(relative_java_path);
        std::fs::create_dir_all(java_path.parent().unwrap()).unwrap();
        std::fs::write(java_path, b"java").unwrap();
        let encoder = zstd::stream::write::Encoder::new(Vec::new(), 3).unwrap();
        let mut builder = tar::Builder::new(encoder);
        builder.append_dir_all("payload", &payload).unwrap();
        builder.into_inner().unwrap().finish().unwrap()
    }

    fn write_cached_jre_download(
        am: &AgentManager,
        jre_key: &str,
        version: &str,
        url: &str,
        format: Option<ArtifactFormat>,
        expected_sha256: Option<&str>,
        archive: &[u8],
    ) {
        let dest = jre_archive_download_path(am, jre_key, format);
        let cache_path = cached_download_path(
            am,
            url,
            archive.len() as u64,
            expected_sha256,
            Some(CacheIdentity::Jre { key: jre_key, version }),
            &dest,
        );
        std::fs::create_dir_all(cache_path.parent().unwrap()).unwrap();
        std::fs::write(cache_path, archive).unwrap();
    }

    async fn cache_test_registry(registry: AgentRegistry) {
        REGISTRY_CACHE.lock().await.insert(DownloadSource::Cnb, (std::time::Instant::now(), registry));
    }

    fn mongodb_registry_with_jre(
        driver_version: &str,
        driver_url: &str,
        driver_size: u64,
        jre_version: &str,
        jre_url: &str,
        jre_size: u64,
    ) -> AgentRegistry {
        let mut registry = registry_with_jar("mongodb", driver_version, driver_url, driver_size);
        registry.jres = registry_with_jre(DEFAULT_JRE_KEY, jre_version, jre_url, jre_size).jres;
        registry
    }

    #[tokio::test]
    async fn ensure_agent_runtime_installs_missing_driver_and_jre() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = test_manager("ensure-missing-driver-and-jre");
        let driver_version = "0.1.47";
        let driver_url = "https://example.com/dbx-agent-mongodb.jar";
        let driver_bytes = test_agent_jar();
        let jre_version = "21.0.12";
        let jre_url = "https://example.com/dbx-jre.tar.gz";
        let jre_archive = build_jre_archive(&manager, DEFAULT_JRE_KEY);
        let registry = mongodb_registry_with_jre(
            driver_version,
            driver_url,
            driver_bytes.len() as u64,
            jre_version,
            jre_url,
            jre_archive.len() as u64,
        );
        write_cached_driver_download(
            &manager,
            "mongodb",
            driver_version,
            driver_url,
            &manager.driver_jar_path("mongodb"),
            &driver_bytes,
        );
        write_cached_jre_download(&manager, DEFAULT_JRE_KEY, jre_version, jre_url, None, None, &jre_archive);
        cache_test_registry(registry).await;

        ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb).await.unwrap();

        assert!(manager.is_driver_jar_valid("mongodb"));
        assert!(manager.is_jre_installed(DEFAULT_JRE_KEY));
        let state = manager.load_state();
        assert_eq!(state.installed_drivers["mongodb"].version, driver_version);
        assert_eq!(state.jre_versions[DEFAULT_JRE_KEY], jre_version);
    }

    /// The managed JRE is only needed for the JAR fallback. A driver the registry
    /// publishes for another platform only — the Windows-only Oracle OCI agent on
    /// macOS — must fail on the missing artifact instead of fetching and
    /// unpacking a JRE it can never use.
    #[tokio::test]
    async fn ensure_agent_runtime_fails_without_fetching_a_jre_when_no_local_artifact_exists() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = test_manager("ensure-no-local-artifact");
        let db_type = "oracle-oci";
        let foreign_platform =
            if AgentManager::current_platform() == "windows-x64" { "linux-x64" } else { "windows-x64" };
        let mut registry = registry_with_jar(
            db_type,
            "0.1.0",
            "https://example.invalid/dbx-agent-oracle-oci-legacy-placeholder.jar",
            0,
        );
        registry.jres = registry_with_jre(DEFAULT_JRE_KEY, "21.0.12", "https://example.invalid/dbx-jre.tar.gz", 8).jres;
        registry.drivers.get_mut(db_type).unwrap().native.insert(
            foreign_platform.to_string(),
            ArtifactInfo {
                url: format!("https://example.invalid/dbx-agent-oracle-oci-{foreign_platform}"),
                sha256: None,
                size: 8,
                format: None,
                delta: None,
            },
        );
        cache_test_registry(registry).await;

        let error = ensure_agent_driver_ready_from(&manager, db_type, DownloadSource::Cnb).await.unwrap_err();

        assert!(error.contains("No driver artifact available"), "{error}");
        assert!(
            !manager.is_jre_installed(DEFAULT_JRE_KEY),
            "the JRE must not be downloaded for an uninstallable driver"
        );
        assert!(!manager.is_driver_installed(db_type));
    }

    #[tokio::test]
    async fn ensure_agent_runtime_ready_fast_path_preserves_valid_old_driver() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = test_manager("ensure-ready-old-driver");
        let driver_path = manager.driver_jar_path("mongodb");
        std::fs::create_dir_all(driver_path.parent().unwrap()).unwrap();
        let old_driver_bytes = test_agent_jar();
        std::fs::write(&driver_path, &old_driver_bytes).unwrap();
        install_jre(&manager);
        record_driver(&manager, "mongodb");

        let latest_version = "9.9.9";
        let latest_url = "https://example.com/dbx-agent-mongodb-latest.jar";
        let latest_driver_bytes = test_agent_jar();
        let cache_path = write_cached_driver_download(
            &manager,
            "mongodb",
            latest_version,
            latest_url,
            &driver_path,
            &latest_driver_bytes,
        );
        let registry_guard = REGISTRY_CACHE.lock().await;

        tokio::time::timeout(
            std::time::Duration::from_millis(100),
            ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb),
        )
        .await
        .expect("ready Agent path must not wait for the registry cache")
        .unwrap();
        drop(registry_guard);

        assert_eq!(std::fs::read(&driver_path).unwrap(), old_driver_bytes);
        assert_eq!(manager.load_state().installed_drivers["mongodb"].version, "1.0.0");
        assert!(cache_path.exists(), "ready fast path must not consume a pending driver download");
    }

    #[tokio::test]
    async fn ensure_agent_runtime_repairs_damaged_jre_without_upgrading_valid_driver() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = test_manager("ensure-damaged-jre");
        let driver_path = manager.driver_jar_path("mongodb");
        std::fs::create_dir_all(driver_path.parent().unwrap()).unwrap();
        let old_driver_bytes = test_agent_jar();
        std::fs::write(&driver_path, &old_driver_bytes).unwrap();
        record_driver(&manager, "mongodb");
        let damaged_java = manager.jre_java_path(DEFAULT_JRE_KEY);
        std::fs::create_dir_all(&damaged_java).unwrap();

        let jre_version = "21.0.12";
        let jre_url = "https://example.com/dbx-jre.tar.gz";
        let jre_archive = build_jre_archive(&manager, DEFAULT_JRE_KEY);
        let registry = mongodb_registry_with_jre(
            "9.9.9",
            "https://example.com/dbx-agent-mongodb-latest.jar",
            test_agent_jar().len() as u64,
            jre_version,
            jre_url,
            jre_archive.len() as u64,
        );
        write_cached_jre_download(&manager, DEFAULT_JRE_KEY, jre_version, jre_url, None, None, &jre_archive);
        cache_test_registry(registry).await;

        ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb).await.unwrap();

        assert!(manager.is_jre_installed(DEFAULT_JRE_KEY));
        assert_eq!(std::fs::read(&driver_path).unwrap(), old_driver_bytes);
        assert_eq!(manager.load_state().installed_drivers["mongodb"].version, "1.0.0");
    }

    #[tokio::test]
    async fn concurrent_ensure_agent_runtime_installs_once() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = Arc::new(test_manager("ensure-concurrent-single-install"));
        let driver_version = "0.1.47";
        let driver_url = "https://example.com/dbx-agent-mongodb.jar";
        let driver_bytes = test_agent_jar();
        let jre_version = "21.0.12";
        let jre_url = "https://example.com/dbx-jre.tar.gz";
        let jre_archive = build_jre_archive(&manager, DEFAULT_JRE_KEY);
        let registry = mongodb_registry_with_jre(
            driver_version,
            driver_url,
            driver_bytes.len() as u64,
            jre_version,
            jre_url,
            jre_archive.len() as u64,
        );
        let driver_cache_path = write_cached_driver_download(
            &manager,
            "mongodb",
            driver_version,
            driver_url,
            &manager.driver_jar_path("mongodb"),
            &driver_bytes,
        );
        write_cached_jre_download(&manager, DEFAULT_JRE_KEY, jre_version, jre_url, None, None, &jre_archive);
        cache_test_registry(registry).await;

        let first = ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb);
        let second = ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb);
        let (first, second) = tokio::join!(first, second);

        first.unwrap();
        second.unwrap();
        assert!(manager.is_driver_jar_valid("mongodb"));
        assert!(manager.is_jre_installed(DEFAULT_JRE_KEY));
        assert!(!driver_cache_path.exists(), "the single successful install should consume the cached artifact");
    }

    #[tokio::test]
    async fn ensure_agent_runtime_propagates_corrupt_install_error() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = test_manager("ensure-corrupt-install-error");
        manager
            .mutate_state(|state| {
                state.java_runtime = JavaRuntimeConfig { mode: JavaRuntimeMode::System, custom_java_path: None };
            })
            .unwrap();
        let driver_version = "0.1.47";
        let driver_url = "https://example.com/dbx-agent-mongodb.jar";
        let corrupt_driver = b"not-a-jar";
        let registry = registry_with_jar("mongodb", driver_version, driver_url, corrupt_driver.len() as u64);
        write_cached_driver_download(
            &manager,
            "mongodb",
            driver_version,
            driver_url,
            &manager.driver_jar_path("mongodb"),
            corrupt_driver,
        );
        cache_test_registry(registry).await;

        let error = ensure_agent_driver_ready_from(&manager, "mongodb", DownloadSource::Cnb)
            .await
            .expect_err("corrupt driver install must fail");

        assert!(error.contains("invalid or corrupt"), "unexpected error: {error}");
        assert!(!manager.load_state().installed_drivers.contains_key("mongodb"));
    }

    #[test]
    fn artifact_info_deserializes_sha256_metadata() {
        let expected_sha256 = "a".repeat(64);
        let artifact: ArtifactInfo = serde_json::from_value(serde_json::json!({
            "url": "https://example.com/artifact.tar.zst",
            "sha256": expected_sha256,
            "size": 4,
            "format": "tar_zstd"
        }))
        .unwrap();

        assert_eq!(artifact.sha256.as_deref(), Some(expected_sha256.as_str()));
    }

    #[test]
    fn cached_download_rejects_same_size_sha256_mismatch() {
        let manager = test_manager("cache-sha256-mismatch");
        let cache_path = manager.download_cache_dir().join("artifact.bin");
        std::fs::create_dir_all(cache_path.parent().unwrap()).unwrap();
        std::fs::write(&cache_path, b"bad!").unwrap();
        let expected_sha256 = format!("{:x}", Sha256::digest(b"good"));

        assert!(!cached_download_is_valid(&manager, &cache_path, 4, Some(&expected_sha256)));
        assert!(!cache_path.exists());
    }

    #[test]
    fn cached_download_accepts_matching_sha256() {
        let manager = test_manager("cache-sha256-match");
        let cache_path = manager.download_cache_dir().join("artifact.bin");
        std::fs::create_dir_all(cache_path.parent().unwrap()).unwrap();
        std::fs::write(&cache_path, b"good").unwrap();
        let expected_sha256 = format!("{:x}", Sha256::digest(b"good"));

        assert!(cached_download_is_valid(&manager, &cache_path, 4, Some(&expected_sha256)));
        assert!(cache_path.exists());
    }

    #[tokio::test]
    async fn successful_delta_download_is_removed_by_driver_cache_cleanup() {
        let manager = test_manager("delta-cache-cleanup");
        let db_type = "demo";
        let base_version = "0.1.0";
        let driver_version = "0.2.0";
        let delta_url = "https://example.invalid/demo.delta";
        let rebuilt = b"reconstructed driver package";
        let delta_bytes = zstd::stream::encode_all(rebuilt.as_slice(), 3).unwrap();
        let delta_sha256 = format!("{:x}", Sha256::digest(&delta_bytes));
        let artifact_sha256 = format!("{:x}", Sha256::digest(rebuilt));

        let base_path = manager.download_cache_dir().join(crate::driver_delta::delta_base_file_name(
            db_type,
            base_version,
            "base.tar.zst",
        ));
        std::fs::create_dir_all(base_path.parent().unwrap()).unwrap();
        std::fs::write(&base_path, b"unused base for a standalone zstd frame").unwrap();

        let dest = manager.driver_dir(db_type).join(".agent.tar.zst");
        let delta_path = dest.parent().unwrap().join("..agent.tar.zst.delta");
        let cache_version = format!("{driver_version}-from-{base_version}");
        let cache_path = cached_download_path(
            &manager,
            delta_url,
            delta_bytes.len() as u64,
            Some(&delta_sha256),
            Some(CacheIdentity::Driver { db_type, version: &cache_version }),
            &delta_path,
        );
        std::fs::write(&cache_path, &delta_bytes).unwrap();

        let artifact = ArtifactInfo {
            url: "https://example.invalid/demo.tar.zst".to_string(),
            sha256: Some(artifact_sha256),
            size: rebuilt.len() as u64,
            format: Some(ArtifactFormat::TarZstd),
            delta: None,
        };
        let delta = crate::agent_manager::DeltaInfo {
            base_version: base_version.to_string(),
            url: delta_url.to_string(),
            sha256: delta_sha256,
            size: delta_bytes.len() as u64,
        };

        try_delta_artifact(
            &manager,
            &|_| {},
            DownloadSource::Cnb,
            &artifact,
            &delta,
            &base_path,
            db_type,
            driver_version,
            &dest,
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert_eq!(std::fs::read(&dest).unwrap(), rebuilt);
        assert!(cache_path.exists());
        cleanup_driver_download_cache_after_success(&manager, db_type);
        assert!(!cache_path.exists());
        assert!(base_path.exists());
    }

    #[tokio::test]
    async fn registry_install_replaces_hive_legacy_jar_with_native_driver() {
        let manager = test_manager("hive-native-replaces-legacy-jar");
        let db_type = "hive";
        let version = "0.1.31";
        let native_url = "https://example.com/dbx-agent-hive";
        let native_bytes = b"native-agent";
        let registry = registry_with_native_and_legacy_jar(db_type, version, native_url, native_bytes.len() as u64);
        let native_path = manager.driver_native_path(db_type);
        std::fs::create_dir_all(manager.driver_dir(db_type)).unwrap();
        write_test_agent_jar(&manager.driver_jar_path(db_type));
        let cache_path =
            write_cached_driver_download(&manager, db_type, version, native_url, &native_path, native_bytes);
        let events = std::sync::Mutex::new(Vec::new());
        let progress = |event| events.lock().unwrap().push(event);

        install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert_eq!(std::fs::read(&native_path).unwrap(), native_bytes);
        assert!(!cache_path.exists());
        assert!(!manager.driver_jar_path(db_type).exists());
        assert_eq!(manager.load_state().installed_drivers.get(db_type).unwrap().version, version);
        assert!(events
            .lock()
            .unwrap()
            .iter()
            .any(|event| event.step == "done" && event.db_type.as_deref() == Some(db_type)));
    }

    #[tokio::test]
    async fn registry_install_sqlite_worker_downloads_both_linux_platforms() {
        let manager = test_manager("sqlite-worker-both-linux-platforms");
        let db_type = "sqlite-worker";
        let version = "0.1.0";
        let x64_url = "https://example.com/dbx-agent-sqlite-worker-linux-x64";
        let arm_url = "https://example.com/dbx-agent-sqlite-worker-linux-aarch64";
        let x64_bytes = b"sqlite-worker-linux-x64";
        let arm_bytes = b"sqlite-worker-linux-aarch64";
        let mut native = std::collections::HashMap::new();
        native.insert(
            "linux-x64".to_string(),
            ArtifactInfo {
                url: x64_url.to_string(),
                sha256: None,
                size: x64_bytes.len() as u64,
                format: None,
                delta: None,
            },
        );
        native.insert(
            "linux-aarch64".to_string(),
            ArtifactInfo {
                url: arm_url.to_string(),
                sha256: None,
                size: arm_bytes.len() as u64,
                format: None,
                delta: None,
            },
        );
        let mut drivers = std::collections::HashMap::new();
        drivers.insert(
            db_type.to_string(),
            DriverInfo {
                version: version.to_string(),
                label: "SQLite SSH Worker".to_string(),
                min_app_version: "0.1.0".to_string(),
                jre: DEFAULT_JRE_KEY.to_string(),
                jar: Some(ArtifactInfo {
                    url: "https://example.com/dbx-agent-sqlite-worker-legacy-placeholder.jar".to_string(),
                    sha256: None,
                    size: 0,
                    format: None,
                    delta: None,
                }),
                native,
            },
        );
        let registry = AgentRegistry { jre: None, jres: std::collections::HashMap::new(), drivers };
        let x64_path = manager.driver_native_platform_path(db_type, "linux-x64");
        let arm_path = manager.driver_native_platform_path(db_type, "linux-aarch64");
        std::fs::create_dir_all(manager.driver_dir(db_type)).unwrap();
        write_cached_driver_download(&manager, db_type, version, x64_url, &x64_path, x64_bytes);
        write_cached_driver_download(&manager, db_type, version, arm_url, &arm_path, arm_bytes);
        let events = std::sync::Mutex::new(Vec::new());
        let progress = |event| events.lock().unwrap().push(event);

        install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert_eq!(std::fs::read(&x64_path).unwrap(), x64_bytes);
        assert_eq!(std::fs::read(&arm_path).unwrap(), arm_bytes);
        assert!(manager.driver_native_installed(db_type));
        assert!(!manager.driver_native_path(db_type).exists());
        assert!(!manager.driver_jar_path(db_type).exists());
        assert!(!remote_driver_requires_java_runtime(registry.drivers.get(db_type).unwrap()));
        assert_eq!(
            driver_download_size(db_type, registry.drivers.get(db_type).unwrap()),
            (x64_bytes.len() + arm_bytes.len()) as u64
        );
        assert_eq!(manager.load_state().installed_drivers.get(db_type).unwrap().version, version);
        assert!(events
            .lock()
            .unwrap()
            .iter()
            .any(|event| event.step == "done" && event.db_type.as_deref() == Some(db_type)));
    }

    #[tokio::test]
    async fn registry_install_cancel_after_cached_download_preserves_existing_driver() {
        let manager = test_manager("cancel-after-cached-driver-download");
        let db_type = "mongodb";
        let old_version = "1.0.0";
        let new_version = "2.0.0";
        let url = "https://example.com/dbx-agent-mongodb.jar";
        // The old driver only needs to exist for this regression: use distinct
        // bytes so the assertion proves cancellation did not replace it.
        let old_bytes = b"previously-installed-driver".to_vec();
        let new_bytes = test_agent_jar();
        let target_path = manager.driver_jar_path(db_type);
        std::fs::create_dir_all(target_path.parent().unwrap()).unwrap();
        std::fs::write(&target_path, &old_bytes).unwrap();
        install_jre(&manager);
        record_driver(&manager, db_type);
        write_cached_driver_download(&manager, db_type, new_version, url, &target_path, &new_bytes);
        let registry = registry_with_jar(db_type, new_version, url, new_bytes.len() as u64);
        let cancellation = manager.begin_install_cancellation("cancel-after-cached-download").await;
        let progress_cancellation = Arc::clone(&cancellation);
        let progress = move |event: AgentProgressEvent| {
            if event.step == "driver" && event.downloaded == Some(new_bytes.len() as u64) {
                progress_cancellation.cancel();
            }
        };

        let error = install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[&cancellation],
        )
        .await
        .expect_err("cancellation after download completion must abort installation");

        assert!(error.contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        assert_eq!(std::fs::read(&target_path).unwrap(), old_bytes);
        assert_eq!(manager.load_state().installed_drivers[db_type].version, old_version);
        assert!(!driver_artifact_download_path(&target_path, None).exists());
    }

    #[tokio::test]
    async fn registry_install_extracts_tar_zstd_native_driver_package() {
        let manager = test_manager("tar-zstd-native-package");
        let db_type = "duckdb";
        let version = "0.1.0";
        let package_url = "https://example.com/dbx-agent-duckdb.tar.zst";
        let native_bytes = current_platform_native_binary();
        let package_bytes = build_tar_zstd_driver_package(db_type, version, DriverArtifactKind::Native, &native_bytes);
        let mut registry =
            registry_with_native_and_legacy_jar(db_type, version, package_url, package_bytes.len() as u64);
        registry.drivers.get_mut(db_type).unwrap().native.get_mut(AgentManager::current_platform()).unwrap().format =
            Some(ArtifactFormat::TarZstd);
        let native_path = manager.driver_native_path(db_type);
        let package_path = driver_artifact_download_path(&native_path, Some(ArtifactFormat::TarZstd));
        let cache_path =
            write_cached_driver_download(&manager, db_type, version, package_url, &package_path, &package_bytes);
        let progress = |_| {};

        install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert_eq!(std::fs::read(&native_path).unwrap(), native_bytes);
        assert!(!package_path.exists());
        assert!(!cache_path.exists());
        assert_eq!(manager.load_state().installed_drivers[db_type].version, version);
    }

    #[tokio::test]
    async fn registry_install_extracts_tar_zstd_java_driver_package() {
        let manager = test_manager("tar-zstd-java-package");
        let db_type = "dameng";
        let version = "0.2.0";
        let package_url = "https://example.com/dbx-agent-dameng.tar.zst";
        let jar_bytes = test_agent_jar();
        let package_bytes = build_tar_zstd_driver_package(db_type, version, DriverArtifactKind::Jar, &jar_bytes);
        let mut registry = registry_with_jar(db_type, version, package_url, package_bytes.len() as u64);
        registry.drivers.get_mut(db_type).unwrap().jar.as_mut().unwrap().format = Some(ArtifactFormat::TarZstd);
        manager
            .mutate_state(|state| {
                state.java_runtime = JavaRuntimeConfig { mode: JavaRuntimeMode::System, custom_java_path: None };
            })
            .unwrap();
        let jar_path = manager.driver_jar_path(db_type);
        let package_path = driver_artifact_download_path(&jar_path, Some(ArtifactFormat::TarZstd));
        let cache_path =
            write_cached_driver_download(&manager, db_type, version, package_url, &package_path, &package_bytes);
        let progress = |_| {};

        install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert_eq!(std::fs::read(&jar_path).unwrap(), jar_bytes);
        assert!(!package_path.exists());
        assert!(!cache_path.exists());
        assert_eq!(manager.load_state().installed_drivers[db_type].version, version);
    }

    #[tokio::test]
    async fn batch_upgrade_preserves_successful_state_and_reports_independent_failure() {
        let manager = test_manager("batch-upgrade");
        let oracle_url = "https://example.com/dbx-agent-oracle";
        let dameng_url = "https://example.com/dbx-agent-dameng";
        let kingbase_url = "https://example.com/dbx-agent-kingbase.jar";
        let oracle_bytes = b"oracle-native-agent";
        let dameng_bytes = b"dameng-native-agent";
        let corrupt_jar = b"not-a-jar";

        let mut registry =
            registry_with_native_and_legacy_jar("oracle", "2.0.0", oracle_url, oracle_bytes.len() as u64);
        registry.drivers.extend(
            registry_with_native_and_legacy_jar("dameng", "2.0.0", dameng_url, dameng_bytes.len() as u64).drivers,
        );
        registry.drivers.extend(registry_with_jar("kingbase", "2.0.0", kingbase_url, corrupt_jar.len() as u64).drivers);

        let mut state = manager.load_state();
        state.java_runtime = JavaRuntimeConfig { mode: JavaRuntimeMode::System, custom_java_path: None };
        for (db_type, version) in [("oracle", "1.0.0"), ("dameng", "1.0.0"), ("kingbase", "1.0.0")] {
            state.installed_drivers.insert(
                db_type.to_string(),
                InstalledDriver {
                    version: version.to_string(),
                    installed_at: "2026-01-01T00:00:00Z".to_string(),
                    jre: DEFAULT_JRE_KEY.to_string(),
                },
            );
        }
        manager.save_state(&state).unwrap();

        write_cached_driver_download(
            &manager,
            "oracle",
            "2.0.0",
            oracle_url,
            &manager.driver_native_path("oracle"),
            oracle_bytes,
        );
        write_cached_driver_download(
            &manager,
            "dameng",
            "2.0.0",
            dameng_url,
            &manager.driver_native_path("dameng"),
            dameng_bytes,
        );
        write_cached_driver_download(
            &manager,
            "kingbase",
            "2.0.0",
            kingbase_url,
            &manager.driver_jar_path("kingbase"),
            corrupt_jar,
        );
        let events = std::sync::Mutex::new(Vec::new());
        let progress = |event| events.lock().unwrap().push(event);

        let result = upgrade_all_agent_drivers_with_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            &progress,
            None,
            None,
        )
        .await
        .unwrap();

        assert_eq!(result.upgraded, 2);
        assert_eq!(result.failed.len(), 1);
        assert_eq!(result.failed[0].db_type, "kingbase");
        let state = manager.load_state();
        assert_eq!(state.installed_drivers["oracle"].version, "2.0.0");
        assert_eq!(state.installed_drivers["dameng"].version, "2.0.0");
        assert_eq!(state.installed_drivers["kingbase"].version, "1.0.0");
        assert_eq!(events.lock().unwrap().iter().filter(|event| event.step == "done").count(), 2);
    }

    #[tokio::test]
    async fn batch_cancel_all_aborts_in_flight_downloads_without_persisting() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = std::sync::Arc::new(test_manager("batch-cancel-in-flight"));
        let db_type = "oracle";
        let version = "2.0.0";
        // Pad the native binary to a sizeable payload so the server can stream
        // it slowly and the download stays in-flight when cancel-all fires.
        let body_size = 256 * 1024usize;
        let mut native_bytes = current_platform_native_binary();
        native_bytes.resize(body_size, 0xAA);
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let native_url = format!("http://{addr}/dbx-agent-oracle");
        let registry = registry_with_native_and_legacy_jar(db_type, version, &native_url, native_bytes.len() as u64);

        // Mark the driver installed at an older version so the batch considers
        // it updatable.
        let mut state = manager.load_state();
        state.java_runtime = JavaRuntimeConfig { mode: JavaRuntimeMode::System, custom_java_path: None };
        state.installed_drivers.insert(
            db_type.to_string(),
            InstalledDriver {
                version: "1.0.0".to_string(),
                installed_at: "2026-01-01T00:00:00Z".to_string(),
                jre: DEFAULT_JRE_KEY.to_string(),
            },
        );
        manager.save_state(&state).unwrap();

        // Slow server: serve the exact payload size slowly so the download is
        // still transferring when the batch cancel-all fires.
        let server = tokio::spawn(async move {
            let (mut socket, _) = listener.accept().await.expect("accept");
            let mut buf = [0u8; 1024];
            let _ = socket.read(&mut buf).await;
            let header = format!(
                "HTTP/1.1 200 OK\r\nContent-Length: {body_size}\r\nContent-Type: application/octet-stream\r\nConnection: close\r\n\r\n"
            );
            socket.write_all(header.as_bytes()).await.expect("write header");
            let chunk = vec![0xAAu8; 4096];
            for _ in 0..(body_size / 4096) {
                socket.write_all(&chunk).await.expect("write chunk");
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        });

        // Register the batch operation + shared batch token (as the command
        // layer does) and start the upgrade.
        let operation_id = "batch-op";
        let batch_token = manager.begin_install_cancellation(&batch_cancellation_key(operation_id)).await;
        let batch_token_task = Arc::clone(&batch_token);
        let started = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
        let started_progress = started.clone();
        let task_manager = Arc::clone(&manager);
        let mut batch_task = tokio::spawn(async move {
            upgrade_all_agent_drivers_with_registry(
                &task_manager,
                &registry,
                DownloadSource::Official,
                &|event| {
                    if event.step == "driver" && event.downloaded.unwrap_or(0) > 0 {
                        started_progress.store(true, std::sync::atomic::Ordering::SeqCst);
                    }
                },
                Some(&batch_token_task),
                Some(operation_id),
            )
            .await
        });

        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(30);
        while !started.load(std::sync::atomic::Ordering::SeqCst) {
            if tokio::time::Instant::now() >= deadline {
                server.abort();
                if let Ok(joined) = tokio::time::timeout(std::time::Duration::from_secs(1), &mut batch_task).await {
                    panic!("batch download never started; batch finished with: {joined:?}");
                }
                batch_task.abort();
                panic!("batch download never started");
            }
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }

        // Cancel-all must abort the already-transferring driver.
        cancel_agent_batch_upgrade(&manager, Some(operation_id)).await.unwrap();

        let result = tokio::time::timeout(std::time::Duration::from_secs(30), batch_task)
            .await
            .expect("batch did not finish after cancel-all")
            .expect("batch panicked")
            .expect("batch returned an unexpected error");
        server.abort();
        manager.finish_install_cancellation(&batch_cancellation_key(operation_id), &batch_token).await;

        assert_eq!(result.upgraded, 0);
        assert!(result.failed.is_empty(), "cancelled drivers must not be reported as failed: {:?}", result.failed);
        assert!(result.cancelled >= 1, "the in-flight driver must be reported cancelled, got {result:?}");
        // The pre-existing install is untouched: cancel-all must not persist the
        // new (in-flight) download as the installed version.
        assert_eq!(
            manager.load_state().installed_drivers.get(db_type).map(|driver| driver.version.as_str()),
            Some("1.0.0"),
            "batch cancel-all must not persist the cancelled download as installed"
        );
        assert!(
            !manager.driver_native_path(db_type).exists(),
            "cancelled download must not leave the driver artifact behind"
        );
        assert!(
            !download_temp_path(&manager.driver_native_path(db_type)).exists(),
            "cancelled download must clean up its temp file"
        );
    }

    #[tokio::test]
    async fn shared_jre_is_not_downloaded_again_after_the_first_install_persists_its_version() {
        let manager = test_manager("shared-jre-deduplication");
        let jre_key = DEFAULT_JRE_KEY;
        let version = "21.0.12";
        let url = "https://example.com/dbx-jre.tar.gz";
        let archive = build_jre_archive(&manager, jre_key);
        let registry = registry_with_jre(jre_key, version, url, archive.len() as u64);
        let events = std::sync::Mutex::new(Vec::new());
        let progress = |event| events.lock().unwrap().push(event);

        write_cached_jre_download(&manager, jre_key, version, url, None, None, &archive);
        ensure_jre_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            jre_key,
            "oracle",
            &progress,
            Some(1),
            Some(2),
            &[],
        )
        .await
        .unwrap();

        // The successful install cleans its cache. Re-add it so the old
        // implementation fails deterministically by consuming it again.
        write_cached_jre_download(&manager, jre_key, version, url, None, None, &archive);
        ensure_jre_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            jre_key,
            "dameng",
            &progress,
            Some(2),
            Some(2),
            &[],
        )
        .await
        .unwrap();

        assert_eq!(manager.load_state().jre_versions[jre_key], version);
        assert!(events
            .lock()
            .unwrap()
            .iter()
            .any(|event| event.step == "jre" && event.db_type.as_deref() == Some("oracle")));
        assert!(!events
            .lock()
            .unwrap()
            .iter()
            .any(|event| event.step == "jre" && event.db_type.as_deref() == Some("dameng")));
    }

    #[tokio::test]
    async fn managed_jre_install_extracts_tar_zstd_archive() {
        let manager = test_manager("managed-zstd-jre");
        let jre_key = DEFAULT_JRE_KEY;
        let version = "21.0.12";
        let url = "https://example.com/dbx-jre.tar.zst";
        let archive = build_zstd_jre_archive(&manager, jre_key);
        let expected_sha256 = format!("{:x}", Sha256::digest(&archive));
        let mut registry = registry_with_jre(jre_key, version, url, archive.len() as u64);
        let artifact =
            registry.jres.get_mut(jre_key).unwrap().platforms.get_mut(AgentManager::current_platform()).unwrap();
        artifact.format = Some(ArtifactFormat::TarZstd);
        artifact.sha256 = Some(expected_sha256.clone());
        write_cached_jre_download(
            &manager,
            jre_key,
            version,
            url,
            Some(ArtifactFormat::TarZstd),
            Some(&expected_sha256),
            &archive,
        );

        ensure_jre_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            jre_key,
            "dameng",
            &|_| {},
            None,
            None,
            &[],
        )
        .await
        .unwrap();

        assert!(manager.is_jre_installed(jre_key));
        assert_eq!(manager.load_state().jre_versions[jre_key], version);
    }

    #[tokio::test]
    async fn stash_is_recorded_before_jre_extraction() {
        let manager = test_manager("stash-before-extract");
        let stash = manager.base_dir().join("jre-21.old-test");

        persist_pending_jre_cleanup(&manager, Some(&stash)).await.unwrap();

        assert_eq!(manager.load_state().pending_jre_cleanup, vec![stash]);
    }

    #[tokio::test]
    async fn local_fallback_cancel_before_commit_preserves_existing_driver() {
        let manager = test_manager("local-cancel-before-commit");
        let db_type = "oracle";
        let jar_path = manager.driver_jar_path(db_type);
        std::fs::create_dir_all(jar_path.parent().unwrap()).unwrap();
        std::fs::write(&jar_path, b"existing-driver").unwrap();
        manager.mutate_state(|state| record_local_agent_install(state, db_type, DEFAULT_JRE_KEY)).unwrap();
        let token = manager.begin_install_cancellation("local-cancel-before-commit").await;
        token.cancel();

        let error = ensure_local_agent_commit_allowed(&[&token]).expect_err("a pre-commit cancel must abort");

        assert!(error.contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        assert_eq!(std::fs::read(&jar_path).unwrap(), b"existing-driver");
        assert!(manager.load_state().installed_drivers.contains_key(db_type));
    }

    #[tokio::test]
    async fn local_fallback_cancel_after_commit_boundary_persists_replacement() {
        let manager = test_manager("local-cancel-after-boundary");
        let db_type = "oracle";
        let jar_path = manager.driver_jar_path(db_type);
        std::fs::create_dir_all(jar_path.parent().unwrap()).unwrap();
        std::fs::write(&jar_path, b"existing-driver").unwrap();
        manager.mutate_state(|state| record_local_agent_install(state, db_type, DEFAULT_JRE_KEY)).unwrap();
        let source = manager.base_dir().join("replacement.jar");
        write_test_agent_jar(&source);
        let expected = std::fs::read(&source).unwrap();
        let token = manager.begin_install_cancellation("local-cancel-after-boundary").await;

        ensure_local_agent_commit_allowed(&[&token]).unwrap();
        token.cancel();
        commit_local_agent_install(&manager, db_type, &source, DEFAULT_JRE_KEY, Some("21.0.12")).await.unwrap();

        assert_eq!(std::fs::read(&jar_path).unwrap(), expected);
        let state = manager.load_state();
        assert_eq!(state.installed_drivers[db_type].version, "0.1.0-local");
        assert_eq!(state.jre_versions[DEFAULT_JRE_KEY], "21.0.12");
    }

    #[test]
    fn concurrent_local_agent_state_updates_preserve_each_driver() {
        let manager = test_manager("concurrent-local-agent-state");
        let start = std::sync::Arc::new(std::sync::Barrier::new(3));
        std::thread::scope(|scope| {
            for db_type in ["oracle", "dameng"] {
                let start = start.clone();
                let manager = &manager;
                scope.spawn(move || {
                    start.wait();
                    manager
                        .mutate_state(|state| {
                            state.jre_versions.insert(DEFAULT_JRE_KEY.to_string(), "21.0.12".to_string());
                            record_local_agent_install(state, db_type, DEFAULT_JRE_KEY);
                        })
                        .unwrap();
                });
            }
            start.wait();
        });

        let state = manager.load_state();
        assert!(state.installed_drivers.contains_key("oracle"));
        assert!(state.installed_drivers.contains_key("dameng"));
        assert_eq!(state.jre_versions[DEFAULT_JRE_KEY], "21.0.12");
    }

    #[tokio::test]
    async fn batch_registry_install_waits_for_an_existing_driver_operation() {
        let manager = test_manager("batch-driver-operation-lock");
        let db_type = "oracle";
        let version = "0.1.31";
        let native_url = "https://example.com/dbx-agent-oracle";
        let native_bytes = b"native-agent";
        let registry = registry_with_native_and_legacy_jar(db_type, version, native_url, native_bytes.len() as u64);
        write_cached_driver_download(
            &manager,
            db_type,
            version,
            native_url,
            &manager.driver_native_path(db_type),
            native_bytes,
        );
        let first_lock = driver_operation_lock(&manager, "oracle");
        let first_guard = first_lock.lock().await;
        let token = manager.begin_install_cancellation(&install_cancellation_key("batch-test")).await;
        let progress = |_| {};

        let blocked = tokio::time::timeout(std::time::Duration::from_millis(50), async {
            install_agent_driver_from_registry_locked(
                &manager,
                &registry,
                DownloadSource::Official,
                db_type,
                &progress,
                Some(1),
                Some(1),
                &[&token],
            )
            .await
        })
        .await;
        assert!(blocked.is_err(), "batch install entered while another operation owned the driver files");

        drop(first_guard);
        tokio::time::timeout(
            std::time::Duration::from_secs(1),
            install_agent_driver_from_registry_locked(
                &manager,
                &registry,
                DownloadSource::Official,
                db_type,
                &progress,
                Some(1),
                Some(1),
                &[&token],
            ),
        )
        .await
        .expect("batch install did not resume after the driver lock was released")
        .unwrap();
        assert_eq!(std::fs::read(manager.driver_native_path(db_type)).unwrap(), native_bytes);
    }

    #[tokio::test]
    async fn manual_import_waits_for_an_existing_driver_operation() {
        let manager = test_manager("manual-import-driver-operation-lock");
        let db_type = "h2";
        let source = manager.base_dir().join("dbx-agent-h2.jar");
        std::fs::create_dir_all(source.parent().unwrap()).unwrap();
        write_test_agent_jar(&source);
        let lock = driver_operation_lock(&manager, db_type);
        let first_guard = lock.lock().await;

        let blocked =
            tokio::time::timeout(std::time::Duration::from_millis(50), import_agent_driver(&manager, db_type, &source))
                .await;
        assert!(blocked.is_err(), "manual import entered while another operation owned the driver files");

        drop(first_guard);
        tokio::time::timeout(std::time::Duration::from_secs(1), import_agent_driver(&manager, db_type, &source))
            .await
            .expect("manual import did not resume after the driver lock was released")
            .unwrap();
        assert_eq!(std::fs::read(manager.driver_jar_path(db_type)).unwrap(), std::fs::read(source).unwrap());
    }

    #[tokio::test]
    async fn jre_exclusive_operation_waits_for_in_flight_driver_operation() {
        let manager = test_manager("jre-exclusive-operation-lock");
        let driver_guard = manager.installation_operation_lock.read().await;

        let blocked =
            tokio::time::timeout(std::time::Duration::from_millis(50), manager.installation_operation_lock.write())
                .await;
        assert!(blocked.is_err(), "JRE replacement entered before an in-flight driver operation completed");

        drop(driver_guard);
        let _jre_guard =
            tokio::time::timeout(std::time::Duration::from_secs(1), manager.installation_operation_lock.write())
                .await
                .expect("JRE replacement did not resume after driver operations completed");
    }

    #[tokio::test]
    async fn cancellation_token_lifecycle_is_scoped_and_removable() {
        let manager = test_manager("cancel-token-lifecycle");
        let token = manager.begin_install_cancellation("oracle").await;
        assert!(!token.is_cancelled());
        assert!(!manager.is_install_cancelled("oracle").await);

        manager.cancel_install("oracle").await;
        assert!(token.is_cancelled());
        assert!(manager.is_install_cancelled("oracle").await);

        manager.finish_install_cancellation("oracle", &token).await;
        assert!(!manager.is_install_cancelled("oracle").await);
    }

    #[tokio::test]
    async fn cancelled_install_never_enters_local_fallback() {
        let manager = test_manager("cancel-local-fallback");
        let token = manager.begin_install_cancellation("oracle").await;
        assert!(can_fallback_to_local_agent(&manager, "oracle", &[&token]).await);

        token.cancel();

        assert!(!can_fallback_to_local_agent(&manager, "oracle", &[&token]).await);
    }

    #[tokio::test]
    async fn finish_install_cancellation_keeps_a_fresh_token() {
        let manager = test_manager("cancel-token-fresh");
        let old_token = manager.begin_install_cancellation("oracle").await;
        old_token.cancel();
        // A new install replaces the cancelled token; finishing the OLD token
        // must not remove the fresh one (Arc::ptr_eq guard).
        let new_token = manager.begin_install_cancellation("oracle").await;
        assert!(!new_token.is_cancelled());
        manager.finish_install_cancellation("oracle", &old_token).await;
        assert!(!manager.is_install_cancelled("oracle").await);

        manager.cancel_install("oracle").await;
        assert!(new_token.is_cancelled());
        manager.finish_install_cancellation("oracle", &new_token).await;
        assert!(!manager.is_install_cancelled("oracle").await);
    }

    #[tokio::test]
    async fn download_with_progress_returns_cancelled_when_token_prefired() {
        let manager = test_manager("cancel-download-entry");
        let db_type = "oracle";
        let token = manager.begin_install_cancellation(db_type).await;
        token.cancel();
        let dest = manager.base_dir().join("downloads").join("oracle-agent");
        let error = download_with_progress(
            &manager,
            &|_| {},
            "driver",
            DownloadSource::Official,
            "https://example.com/dbx-agent-oracle",
            "agents/drivers/dbx-agent-oracle",
            &dest,
            100,
            None,
            None,
            Some(db_type),
            None,
            None,
            &[&token],
        )
        .await
        .expect_err("a pre-cancelled token must abort the download before any transfer");
        assert!(error.contains(AGENT_DOWNLOAD_CANCELED_ERROR), "unexpected error: {error}");
        assert!(!download_temp_path(&dest).exists());
        assert!(!dest.exists());
    }

    #[tokio::test]
    async fn download_with_progress_aborts_mid_stream_when_cancelled() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let manager = test_manager("cancel-mid-stream");
        let db_type = "oracle";
        let token = manager.begin_install_cancellation(db_type).await;
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let url = format!("http://{addr}/slow-agent");

        let server = tokio::spawn(async move {
            let (mut socket, _) = listener.accept().await.expect("accept");
            let mut buf = [0u8; 1024];
            let _ = socket.read(&mut buf).await;
            let body_size = 256 * 1024usize;
            let header = format!(
                "HTTP/1.1 200 OK\r\nContent-Length: {body_size}\r\nContent-Type: application/octet-stream\r\nConnection: close\r\n\r\n"
            );
            socket.write_all(header.as_bytes()).await.expect("write header");
            let chunk = vec![0xAAu8; 4096];
            for _ in 0..64 {
                socket.write_all(&chunk).await.expect("write chunk");
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        });

        let dest = manager.base_dir().join("downloads").join("oracle-agent");
        let dest_assert = dest.clone();
        let started = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
        let started_progress = started.clone();
        let token_for_task = Arc::clone(&token);
        let task = tokio::spawn(async move {
            download_with_progress(
                &manager,
                &|event| {
                    if event.step == "driver" && event.downloaded.unwrap_or(0) > 0 {
                        started_progress.store(true, std::sync::atomic::Ordering::SeqCst);
                    }
                },
                "driver",
                DownloadSource::Official,
                &url,
                "agents/drivers/dbx-agent-oracle",
                &dest,
                256 * 1024,
                None,
                None,
                Some(db_type),
                None,
                None,
                &[&token_for_task],
            )
            .await
        });

        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(15);
        while !started.load(std::sync::atomic::Ordering::SeqCst) {
            if tokio::time::Instant::now() >= deadline {
                server.abort();
                panic!("download never started (external mirror probe may have stalled)");
            }
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
        token.cancel();

        let result = tokio::time::timeout(std::time::Duration::from_secs(15), task)
            .await
            .expect("download task did not finish after cancel")
            .expect("download task panicked");
        server.abort();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        assert!(!download_temp_path(&dest_assert).exists());
        assert!(!dest_assert.exists());
    }

    #[test]
    fn cancelled_error_classification_distinguishes_user_cancel() {
        assert!(is_cancelled_error(AGENT_DOWNLOAD_CANCELED_ERROR));
        assert!(is_cancelled_error(&format!("prefix {AGENT_DOWNLOAD_CANCELED_ERROR} suffix")));
        assert!(!is_cancelled_error("Download failed: 404 Not Found"));
    }

    #[tokio::test]
    async fn cancel_during_driver_lock_wait_aborts_install_before_persist() {
        let manager = std::sync::Arc::new(test_manager("cancel-lock-wait"));
        let db_type = "oracle";
        // Command scope: the token is registered before any awaitable setup.
        let cancellation = manager.begin_install_cancellation(db_type).await;
        let cancel_handle = Arc::clone(&cancellation);
        // Hold the driver lock so the install blocks on it.
        let lock = driver_operation_lock(&manager, db_type);
        let _guard = lock.lock().await;

        let install_manager = Arc::clone(&manager);
        let install = tokio::spawn(async move {
            install_agent_driver_from_claimed(
                &install_manager,
                db_type,
                DownloadSource::Official,
                |_| {},
                &cancellation,
            )
            .await
        });
        // Let the install reach the lock wait, then cancel.
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        cancel_handle.cancel();

        // The guard is still held: the install must observe its token and
        // return promptly instead of waiting for the lock holder to finish.
        let result = tokio::time::timeout(std::time::Duration::from_secs(5), install)
            .await
            .expect("install task did not finish after cancel while the driver lock was still held")
            .expect("install task panicked");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        // Cancellation observed while waiting on the lock must never persist state.
        assert!(!manager.load_state().installed_drivers.contains_key(db_type));
        drop(_guard);
        drop(lock);
        assert!(manager.driver_operation_locks.lock().unwrap().is_empty());
        manager.finish_install_cancellation(db_type, &cancel_handle).await;
    }

    #[tokio::test]
    async fn cancelled_install_aborts_while_waiting_for_jre_lock() {
        let manager = std::sync::Arc::new(test_manager("cancel-jre-lock-wait"));
        let db_type = "oracle";
        let registry = registry_with_jre_version("21.0.12");
        let cancellation = manager.begin_install_cancellation(&install_cancellation_key("jre-lock-wait")).await;
        let cancel_handle = Arc::clone(&cancellation);
        // Hold the JRE lock so the install blocks on it before downloading.
        let lock = jre_operation_lock(&manager, DEFAULT_JRE_KEY);
        let _guard = lock.lock().await;

        let install_manager = Arc::clone(&manager);
        let install = tokio::spawn(async move {
            ensure_jre_from_registry(
                &install_manager,
                &registry,
                DownloadSource::Official,
                DEFAULT_JRE_KEY,
                db_type,
                &|_| {},
                None,
                None,
                &[&cancellation],
            )
            .await
        });
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        cancel_handle.cancel();

        // The guard is still held: the JRE wait must abort on the token
        // instead of waiting for the lock holder to finish.
        let result = tokio::time::timeout(std::time::Duration::from_secs(5), install)
            .await
            .expect("JRE wait did not finish after cancel while the JRE lock was still held")
            .expect("JRE wait panicked");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        // Nothing must have been downloaded or persisted.
        assert!(!manager.jre_dir(DEFAULT_JRE_KEY).exists());
        assert!(manager.load_state().jre_versions.is_empty());
        drop(_guard);
        drop(lock);
        assert!(manager.jre_install_locks.lock().unwrap().is_empty());
        manager.finish_install_cancellation(&install_cancellation_key("jre-lock-wait"), &cancel_handle).await;
    }

    #[tokio::test]
    async fn download_with_progress_aborts_before_response_headers_when_cancelled() {
        use tokio::io::AsyncReadExt;
        let manager = test_manager("cancel-stalled-headers");
        let db_type = "oracle";
        let token = manager.begin_install_cancellation(db_type).await;
        // A mirror that accepts connections but never sends response headers -
        // without racing `request.send()` against cancellation the install
        // would hang here until the 300s client timeout.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let url = format!("http://{addr}/stalled-agent");
        let server = tokio::spawn(async move {
            loop {
                let Ok((mut socket, _)) = listener.accept().await else { break };
                // Read the request, then never respond.
                let mut buf = [0u8; 1024];
                let _ = socket.read(&mut buf).await;
                let _ = socket.read(&mut buf).await;
            }
        });

        let dest = manager.base_dir().join("downloads").join("oracle-agent");
        let dest_assert = dest.clone();
        let token_for_task = Arc::clone(&token);
        let task = tokio::spawn(async move {
            download_with_progress(
                &manager,
                &|_| {},
                "driver",
                DownloadSource::Official,
                &url,
                "agents/drivers/dbx-agent-oracle",
                &dest,
                256 * 1024,
                None,
                None,
                Some(db_type),
                None,
                None,
                &[&token_for_task],
            )
            .await
        });
        // The request is now pending on the stalled mirror; cancel must abort
        // it long before the 300s timeout.
        tokio::time::sleep(std::time::Duration::from_millis(300)).await;
        token.cancel();

        let result = tokio::time::timeout(std::time::Duration::from_secs(5), task)
            .await
            .expect("download did not abort after cancel while response headers were stalled")
            .expect("download task panicked");
        server.abort();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
        assert!(!download_temp_path(&dest_assert).exists());
        assert!(!dest_assert.exists());
    }

    #[tokio::test]
    async fn fetch_registry_aborts_when_cancelled_while_request_stalled() {
        use tokio::io::AsyncReadExt;
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        invalidate_registry_cache().await;
        let manager = test_manager("cancel-registry-stalled-headers");
        let token = manager.begin_install_cancellation("registry-fetch").await;
        // A registry mirror that accepts connections but never sends response
        // headers - without racing `request.send()` against cancellation the
        // registry fetch would hang until the 10s client timeout.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let url = format!("http://{addr}/stalled-registry.json");
        let server = tokio::spawn(async move {
            let Ok((mut socket, _)) = listener.accept().await else { return };
            // Read the request, then never respond.
            let mut buf = [0u8; 1024];
            let _ = socket.read(&mut buf).await;
            let _ = socket.read(&mut buf).await;
        });

        let token_for_task = Arc::clone(&token);
        let task = tokio::spawn(async move {
            let urls = vec![url];
            fetch_registry_from_urls(DownloadSource::Official, &urls, &[token_for_task.as_ref()]).await
        });
        // The request is now pending on the stalled mirror; cancel must abort
        // it long before the 10s client timeout.
        tokio::time::sleep(std::time::Duration::from_millis(300)).await;
        token.cancel();

        let result = tokio::time::timeout(std::time::Duration::from_secs(5), task)
            .await
            .expect("registry fetch did not abort after cancel while response headers were stalled")
            .expect("registry fetch task panicked");
        server.abort();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
    }

    #[tokio::test]
    async fn fetch_registry_aborts_when_cancelled_while_body_stalled() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        invalidate_registry_cache().await;
        let manager = test_manager("cancel-registry-stalled-body");
        let token = manager.begin_install_cancellation("registry-fetch").await;
        // A registry mirror that sends response headers plus a small partial
        // body, then stalls before satisfying Content-Length - without racing
        // `resp.json()` against cancellation the registry fetch would hang
        // until the 10s client timeout.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let url = format!("http://{addr}/partial-registry.json");
        let server = tokio::spawn(async move {
            let (mut socket, _) = listener.accept().await.expect("accept");
            let mut buf = [0u8; 1024];
            let _ = socket.read(&mut buf).await;
            let header = "HTTP/1.1 200 OK\r\nContent-Length: 65536\r\nContent-Type: application/json\r\nConnection: close\r\n\r\n";
            socket.write_all(header.as_bytes()).await.expect("write header");
            // A truncated JSON body: the client keeps waiting for the remaining
            // bytes to satisfy Content-Length.
            socket.write_all(b"{\"drivers\": {}}").await.expect("write partial body");
            let mut drain = [0u8; 1024];
            let _ = socket.read(&mut drain).await;
        });

        let token_for_task = Arc::clone(&token);
        let task = tokio::spawn(async move {
            let urls = vec![url];
            fetch_registry_from_urls(DownloadSource::Official, &urls, &[token_for_task.as_ref()]).await
        });
        // The body parse is now waiting on the stalled mirror; cancel must
        // abort it during parsing, not after the 10s client timeout.
        tokio::time::sleep(std::time::Duration::from_millis(300)).await;
        token.cancel();

        let result = tokio::time::timeout(std::time::Duration::from_secs(5), task)
            .await
            .expect("registry fetch did not abort after cancel while the response body was stalled")
            .expect("registry fetch task panicked");
        server.abort();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));
    }

    #[tokio::test]
    async fn fetch_registry_precancelled_token_aborts_before_any_network_attempt() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        invalidate_registry_cache().await;
        let manager = test_manager("cancel-registry-prefired");
        let token = manager.begin_install_cancellation("registry-fetch").await;
        token.cancel();

        // Point at a port that would refuse/never answer: the entry check must
        // abort before any network attempt, so the result is the cancel error,
        // not a connection/timeout error.
        let urls = vec!["http://127.0.0.1:1/stalled-registry.json".to_string()];
        let result = tokio::time::timeout(
            std::time::Duration::from_secs(5),
            fetch_registry_from_urls(DownloadSource::Official, &urls, &[token.as_ref()]),
        )
        .await
        .expect("pre-cancelled registry fetch must return immediately")
        .expect_err("pre-cancelled token must abort the registry fetch");
        assert!(result.contains(AGENT_DOWNLOAD_CANCELED_ERROR));
    }

    #[tokio::test]
    async fn concurrent_same_driver_installs_cancel_only_the_targeted_operation() {
        let _test_guard = ENSURE_AGENT_TEST_LOCK.lock().await;
        let manager = std::sync::Arc::new(test_manager("concurrent-same-driver-cancel"));
        let db_type = "oracle";
        let version = "0.1.31";
        let native_url = "https://example.com/dbx-agent-oracle";
        let native_bytes = b"native-agent";
        let registry = registry_with_native_and_legacy_jar(db_type, version, native_url, native_bytes.len() as u64);
        write_cached_driver_download(
            &manager,
            db_type,
            version,
            native_url,
            &manager.driver_native_path(db_type),
            native_bytes,
        );
        cache_test_registry(registry).await;

        // Two independent operations for the SAME driver, each with its own
        // operation id and therefore its own cancellation token.
        let op_a = "operation-a";
        let op_b = "operation-b";
        let token_a = manager.begin_install_cancellation(&install_cancellation_key(op_a)).await;
        let token_b = manager.begin_install_cancellation(&install_cancellation_key(op_b)).await;

        // Hold the driver lock so both installs block on it.
        let lock = driver_operation_lock(&manager, db_type);
        let _guard = lock.lock().await;

        let manager_a = Arc::clone(&manager);
        let manager_b = Arc::clone(&manager);
        let token_a_task = Arc::clone(&token_a);
        let token_b_task = Arc::clone(&token_b);
        let install_a = tokio::spawn(async move {
            install_agent_driver_from_claimed(&manager_a, db_type, DownloadSource::Cnb, |_| {}, &token_a_task).await
        });
        let install_b = tokio::spawn(async move {
            install_agent_driver_from_claimed(&manager_b, db_type, DownloadSource::Cnb, |_| {}, &token_b_task).await
        });
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

        // Cancel operation A only; operation B must be unaffected.
        cancel_agent_driver_install(&manager, db_type, Some(op_a)).await.unwrap();
        assert!(!token_b.is_cancelled(), "cancelling operation A must not cancel operation B");
        drop(_guard);

        let result_a = tokio::time::timeout(std::time::Duration::from_secs(5), install_a)
            .await
            .expect("install A did not finish after cancel")
            .expect("install A panicked");
        assert!(result_a.is_err());
        assert!(result_a.unwrap_err().contains(AGENT_DOWNLOAD_CANCELED_ERROR));

        let result_b = tokio::time::timeout(std::time::Duration::from_secs(5), install_b)
            .await
            .expect("install B did not finish")
            .expect("install B panicked");
        assert!(result_b.is_ok(), "operation A's cancel must not abort operation B: {:?}", result_b.err());

        // Only the completed operation B persists installed state.
        assert_eq!(manager.load_state().installed_drivers[db_type].version, version);
        manager.finish_install_cancellation(&install_cancellation_key(op_a), &token_a).await;
        manager.finish_install_cancellation(&install_cancellation_key(op_b), &token_b).await;
    }

    #[tokio::test]
    async fn registry_install_rejects_corrupt_downloaded_jar() {
        let manager = test_manager("corrupt-jar");
        let db_type = "h2";
        let version = "0.2.0";
        let jar_url = "https://example.com/dbx-agent-h2.jar";
        let jar_bytes = b"jar";
        let registry = registry_with_jar(db_type, version, jar_url, jar_bytes.len() as u64);
        let jar_path = manager.driver_jar_path(db_type);
        let cache_path = write_cached_driver_download(&manager, db_type, version, jar_url, &jar_path, jar_bytes);
        manager
            .save_state(&crate::agent_manager::AgentState {
                java_runtime: JavaRuntimeConfig { mode: JavaRuntimeMode::System, custom_java_path: None },
                ..Default::default()
            })
            .unwrap();
        let progress = |_| {};

        let err = install_agent_driver_from_registry(
            &manager,
            &registry,
            DownloadSource::Official,
            db_type,
            &progress,
            None,
            None,
            &[],
        )
        .await
        .unwrap_err();

        assert!(err.contains("invalid or corrupt"));
        assert!(cache_path.exists());
        assert!(!jar_path.exists());
        assert!(!manager.load_state().installed_drivers.contains_key(db_type));
    }

    #[tokio::test]
    async fn offline_zip_rejects_a_cross_platform_java_dependency_before_install_changes() {
        let platform = AgentManager::current_platform();
        let foreign_platform = if platform == "linux-x64" { "macos-x64" } else { "linux-x64" };
        let jre_key = "temurin-21";
        let jar_name = "dbx-agent-h2.jar";
        let jre_name = format!("dbx-jre-{jre_key}-{foreign_platform}.tar.gz");
        let jar_bytes = test_agent_jar();
        let jre_bytes = b"foreign-jre".to_vec();
        let registry = AgentRegistry {
            jre: None,
            jres: [(
                jre_key.to_string(),
                JreInfo {
                    version: "21.0.7".to_string(),
                    platforms: [(
                        foreign_platform.to_string(),
                        ArtifactInfo {
                            url: format!("offline://{jre_name}"),
                            sha256: Some(sha256_bytes(&jre_bytes)),
                            size: jre_bytes.len() as u64,
                            format: None,
                            delta: None,
                        },
                    )]
                    .into_iter()
                    .collect(),
                },
            )]
            .into_iter()
            .collect(),
            drivers: [(
                "h2".to_string(),
                DriverInfo {
                    version: "1.0.0".to_string(),
                    label: "H2".to_string(),
                    min_app_version: "0.1.0".to_string(),
                    jar: Some(ArtifactInfo {
                        url: format!("offline://{jar_name}"),
                        sha256: Some(sha256_bytes(&jar_bytes)),
                        size: jar_bytes.len() as u64,
                        format: None,
                        delta: None,
                    }),
                    native: std::collections::HashMap::new(),
                    jre: jre_key.to_string(),
                },
            )]
            .into_iter()
            .collect(),
        };
        let (_package_dir, package) = write_offline_zip(
            &registry,
            &[(format!("drivers/{jar_name}"), jar_bytes), (format!("jre/{jre_name}"), jre_bytes)],
        );

        let inspect_error = inspect_offline_zip(&package).unwrap_err();
        assert!(inspect_error.contains("does not support the current platform"), "unexpected error: {inspect_error}");

        let manager = test_manager("offline-cross-platform-java");
        let existing_jar = manager.driver_jar_path("h2");
        std::fs::create_dir_all(existing_jar.parent().unwrap()).unwrap();
        std::fs::write(&existing_jar, b"existing-driver").unwrap();
        manager
            .mutate_state(|state| {
                state.installed_drivers.insert(
                    "h2".to_string(),
                    InstalledDriver {
                        version: "9.9.9".to_string(),
                        installed_at: "before".to_string(),
                        jre: jre_key.to_string(),
                    },
                );
            })
            .unwrap();

        let import_error = import_offline_zip(&manager, &package, |_| {}).await.unwrap_err();
        assert!(import_error.contains("does not support the current platform"), "unexpected error: {import_error}");
        assert_eq!(std::fs::read(existing_jar).unwrap(), b"existing-driver");
        assert_eq!(manager.load_state().installed_drivers["h2"].version, "9.9.9");
        assert!(!manager.jre_dir(jre_key).exists());
    }

    #[test]
    fn offline_zip_rejects_a_java_dependency_missing_from_a_registry_with_jre_metadata() {
        let platform = AgentManager::current_platform();
        let jar_name = "dbx-agent-h2.jar";
        let jar_bytes = test_agent_jar();
        let unrelated_jre_name = format!("dbx-jre-temurin-17-{platform}.tar.gz");
        let unrelated_jre_bytes = b"unrelated-jre".to_vec();
        let registry = AgentRegistry {
            jre: None,
            jres: [(
                "temurin-17".to_string(),
                JreInfo {
                    version: "17.0.15".to_string(),
                    platforms: [(
                        platform.to_string(),
                        ArtifactInfo {
                            url: format!("offline://{unrelated_jre_name}"),
                            sha256: Some(sha256_bytes(&unrelated_jre_bytes)),
                            size: unrelated_jre_bytes.len() as u64,
                            format: None,
                            delta: None,
                        },
                    )]
                    .into_iter()
                    .collect(),
                },
            )]
            .into_iter()
            .collect(),
            drivers: [(
                "h2".to_string(),
                DriverInfo {
                    version: "1.0.0".to_string(),
                    label: "H2".to_string(),
                    min_app_version: "0.1.0".to_string(),
                    jar: Some(ArtifactInfo {
                        url: format!("offline://{jar_name}"),
                        sha256: Some(sha256_bytes(&jar_bytes)),
                        size: jar_bytes.len() as u64,
                        format: None,
                        delta: None,
                    }),
                    native: std::collections::HashMap::new(),
                    jre: "temurin-21".to_string(),
                },
            )]
            .into_iter()
            .collect(),
        };
        let (_package_dir, package) = write_offline_zip(
            &registry,
            &[(format!("drivers/{jar_name}"), jar_bytes), (format!("jre/{unrelated_jre_name}"), unrelated_jre_bytes)],
        );

        let error = inspect_offline_zip(&package).unwrap_err();
        assert!(error.contains("missing from the package registry"), "unexpected error: {error}");
    }

    #[test]
    fn offline_zip_rejects_registry_size_and_sha256_tampering() {
        let platform = AgentManager::current_platform();
        let entry_name = format!("dbx-agent-h2-{platform}");
        let original = b"native-bytes".to_vec();
        let tampered = b"native-byteS".to_vec();
        assert_eq!(original.len(), tampered.len());

        let registry_with = |size, sha256: String| AgentRegistry {
            jre: None,
            jres: std::collections::HashMap::new(),
            drivers: [(
                "h2".to_string(),
                DriverInfo {
                    version: "1.0.0".to_string(),
                    label: "H2".to_string(),
                    min_app_version: "0.1.0".to_string(),
                    jar: None,
                    native: [(
                        platform.to_string(),
                        ArtifactInfo {
                            url: format!("offline://{entry_name}"),
                            sha256: Some(sha256),
                            size,
                            format: None,
                            delta: None,
                        },
                    )]
                    .into_iter()
                    .collect(),
                    jre: DEFAULT_JRE_KEY.to_string(),
                },
            )]
            .into_iter()
            .collect(),
        };

        let size_registry = registry_with((original.len() + 1) as u64, sha256_bytes(&original));
        let (_size_dir, size_package) =
            write_offline_zip(&size_registry, &[(format!("drivers/{entry_name}"), original.clone())]);
        let size_error = inspect_offline_zip(&size_package).unwrap_err();
        assert!(size_error.contains("size mismatch"), "unexpected error: {size_error}");

        let sha_registry = registry_with(original.len() as u64, sha256_bytes(&original));
        let (_sha_dir, sha_package) = write_offline_zip(&sha_registry, &[(format!("drivers/{entry_name}"), tampered)]);
        let sha_error = inspect_offline_zip(&sha_package).unwrap_err();
        assert!(sha_error.contains("SHA-256 mismatch"), "unexpected error: {sha_error}");
    }

    #[test]
    fn offline_zip_resolves_a_hyphenated_jre_key_from_the_registry_basename() {
        let platform = AgentManager::current_platform();
        let jre_key = "temurin-21";
        let jar_name = "dbx-agent-h2.jar";
        let jre_name = format!("dbx-jre-{jre_key}-21.0.7-{platform}.tar.gz");
        let jar_bytes = test_agent_jar();
        let jre_bytes = b"current-jre".to_vec();
        let registry = AgentRegistry {
            jre: None,
            jres: [(
                jre_key.to_string(),
                JreInfo {
                    version: "21.0.7".to_string(),
                    platforms: [(
                        platform.to_string(),
                        ArtifactInfo {
                            url: format!("offline://{jre_name}"),
                            sha256: Some(sha256_bytes(&jre_bytes)),
                            size: jre_bytes.len() as u64,
                            format: None,
                            delta: None,
                        },
                    )]
                    .into_iter()
                    .collect(),
                },
            )]
            .into_iter()
            .collect(),
            drivers: [(
                "h2".to_string(),
                DriverInfo {
                    version: "1.0.0".to_string(),
                    label: "H2".to_string(),
                    min_app_version: "0.1.0".to_string(),
                    jar: Some(ArtifactInfo {
                        url: format!("offline://{jar_name}"),
                        sha256: Some(sha256_bytes(&jar_bytes)),
                        size: jar_bytes.len() as u64,
                        format: None,
                        delta: None,
                    }),
                    native: std::collections::HashMap::new(),
                    jre: jre_key.to_string(),
                },
            )]
            .into_iter()
            .collect(),
        };
        let (_package_dir, package) = write_offline_zip(
            &registry,
            &[(format!("drivers/{jar_name}"), jar_bytes), (format!("jre/{jre_name}"), jre_bytes)],
        );

        let plan = inspect_offline_zip(&package).unwrap();
        assert_eq!(plan.driver_keys, vec!["h2"]);
        assert!(plan.includes_jre);
    }

    #[test]
    fn offline_zip_keeps_legacy_jar_and_jre_entries_compatible_without_integrity_metadata() {
        let platform = AgentManager::current_platform();
        let jar_name = "dbx-agent-h2.jar";
        let jre_name = format!("jre-21-{platform}.tar.gz");
        let jar_bytes = test_agent_jar();
        let registry = registry_with_jar("h2", "1.0.0", &format!("offline://{jar_name}"), jar_bytes.len() as u64);
        let (_package_dir, package) = write_offline_zip(
            &registry,
            &[(format!("drivers/{jar_name}"), jar_bytes), (format!("jre/{jre_name}"), b"legacy-jre".to_vec())],
        );

        let plan = inspect_offline_zip(&package).unwrap();
        assert_eq!(plan.driver_keys, vec!["h2"]);
        assert!(plan.includes_jre);
    }

    #[tokio::test]
    async fn offline_import_exclusive_lock_waits_for_in_flight_driver_operation() {
        let manager = test_manager("offline-import-lock");
        // Simulate an in-flight driver operation holding a read lock.
        let driver_guard = manager.installation_operation_lock.read().await;
        // import_offline_zip acquires the write lock — it must wait.
        let blocked =
            tokio::time::timeout(std::time::Duration::from_millis(50), manager.installation_operation_lock.write())
                .await;
        assert!(blocked.is_err(), "offline import entered before an in-flight driver operation completed");

        drop(driver_guard);
        let _offline_guard =
            tokio::time::timeout(std::time::Duration::from_secs(1), manager.installation_operation_lock.write())
                .await
                .expect("offline import did not resume after driver operations completed");
    }

    /// A minimal ELF header that passes the native-agent platform check.
    fn linux_native_binary(machine: u16) -> Vec<u8> {
        let mut bytes = vec![0_u8; 20];
        bytes[..4].copy_from_slice(b"\x7fELF");
        bytes[4] = 2;
        bytes[5] = 1;
        bytes[18..20].copy_from_slice(&machine.to_le_bytes());
        bytes
    }

    /// A registry entry for the SSH worker carrying both Linux binaries, the way
    /// a release bundle does.
    fn registry_with_sqlite_worker(version: &str) -> AgentRegistry {
        let native = SQLITE_WORKER_NATIVE_PLATFORMS
            .iter()
            .map(|platform| {
                (
                    (*platform).to_string(),
                    ArtifactInfo {
                        url: format!("https://example.com/dbx-agent-sqlite-worker-{version}-{platform}"),
                        sha256: None,
                        size: 0,
                        format: None,
                        delta: None,
                    },
                )
            })
            .collect();
        AgentRegistry {
            jre: None,
            jres: std::collections::HashMap::new(),
            drivers: [(
                SQLITE_WORKER_DRIVER_KEY.to_string(),
                DriverInfo {
                    version: version.to_string(),
                    label: "SQLite SSH Worker".to_string(),
                    min_app_version: "0.1.0".to_string(),
                    jar: None,
                    native,
                    jre: DEFAULT_JRE_KEY.to_string(),
                },
            )]
            .into_iter()
            .collect(),
        }
    }

    fn sqlite_worker_entry(manager: &AgentManager, registry: &AgentRegistry) -> AgentDriverInfo {
        build_agent_list(manager, Some(registry))
            .into_iter()
            .find(|driver| driver.db_type == SQLITE_WORKER_DRIVER_KEY)
            .expect("sqlite-worker is part of the driver catalog")
    }

    #[tokio::test]
    async fn offline_zip_installs_the_single_sqlite_worker_platform_it_ships() {
        let version = "0.1.3";
        let x64_name = format!("dbx-agent-sqlite-worker-{version}-linux-x64");
        let registry = registry_with_sqlite_worker(version);
        let (_dir, package) = write_offline_zip(&registry, &[(format!("drivers/{x64_name}"), linux_native_binary(62))]);

        let plan = inspect_offline_zip(&package).unwrap();
        assert_eq!(plan.driver_keys, vec![SQLITE_WORKER_DRIVER_KEY.to_string()]);

        let manager = test_manager("offline-sqlite-worker-single-platform");
        assert!(!manager.driver_native_installed(SQLITE_WORKER_DRIVER_KEY));
        assert!(!sqlite_worker_entry(&manager, &registry).installed);

        let result = import_offline_zip(&manager, &package, |_| {}).await.unwrap();
        assert!(result.failures.is_empty(), "unexpected failures: {:?}", result.failures);
        assert_eq!(result.drivers_installed, vec![SQLITE_WORKER_DRIVER_KEY.to_string()]);

        // Only the packaged platform lands on disk, and that alone must count as
        // installed so the SSH connection stops trying to download it (#8987).
        assert!(manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-x64").is_file());
        assert!(!manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-aarch64").exists());
        assert!(manager.driver_native_installed(SQLITE_WORKER_DRIVER_KEY));
        assert!(sqlite_worker_entry(&manager, &registry).installed, "Driver Manager must report the worker installed");

        // Re-importing the same package is a no-op instead of a bogus reinstall.
        let again = import_offline_zip(&manager, &package, |_| {}).await.unwrap();
        assert_eq!(again.drivers_skipped, vec![SQLITE_WORKER_DRIVER_KEY.to_string()]);
        assert!(again.drivers_installed.is_empty());
    }

    #[tokio::test]
    async fn offline_zip_installs_both_sqlite_worker_platforms_when_packaged() {
        let version = "0.1.4";
        let x64_name = format!("dbx-agent-sqlite-worker-{version}-linux-x64");
        let arm_name = format!("dbx-agent-sqlite-worker-{version}-linux-aarch64");
        let registry = registry_with_sqlite_worker(version);
        let (_dir, package) = write_offline_zip(
            &registry,
            &[
                (format!("drivers/{x64_name}"), linux_native_binary(62)),
                (format!("drivers/{arm_name}"), linux_native_binary(183)),
            ],
        );

        let manager = test_manager("offline-sqlite-worker-both-platforms");
        let result = import_offline_zip(&manager, &package, |_| {}).await.unwrap();
        assert!(result.failures.is_empty(), "unexpected failures: {:?}", result.failures);
        // Installing the first artifact updates the recorded version; the second
        // must still be written instead of being treated as already up to date.
        assert!(manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-x64").is_file());
        assert!(manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-aarch64").is_file());
        assert!(manager.sqlite_worker_all_platforms_installed());
    }

    #[tokio::test]
    async fn offline_zip_rejects_a_sqlite_worker_binary_for_the_wrong_architecture() {
        let version = "0.1.5";
        let name = format!("dbx-agent-sqlite-worker-{version}-linux-x64");
        let registry = registry_with_sqlite_worker(version);
        // An aarch64 ELF packaged as the x64 artifact must not be installed.
        let (_dir, package) = write_offline_zip(&registry, &[(format!("drivers/{name}"), linux_native_binary(183))]);

        let manager = test_manager("offline-sqlite-worker-wrong-arch");
        let result = import_offline_zip(&manager, &package, |_| {}).await.unwrap();
        assert!(!result.failures.is_empty(), "a mismatched binary must be reported as a failure");
        assert!(!manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-x64").exists());
        assert!(!manager.driver_native_installed(SQLITE_WORKER_DRIVER_KEY));
    }

    /// The website drivers page assembles custom offline bundles in the
    /// browser: raw artifacts under `drivers/`, the JRE tarball under `jre/`,
    /// and a synthesized registry whose artifact URLs are `offline://` file
    /// names. This test feeds exactly that JSON shape (including the extra
    /// `external_driver_required` field the package registries carry) through
    /// the real inspect + import pipeline.
    #[tokio::test]
    async fn offline_zip_imports_a_web_assembled_custom_bundle() {
        let platform = AgentManager::current_platform();
        let jar_name = "dbx-agent-h2-1.0.0.jar";
        let worker_x64 = "dbx-agent-sqlite-worker-0.1.6-linux-x64";
        let worker_arm = "dbx-agent-sqlite-worker-0.1.6-linux-aarch64";
        let jre_name = format!("dbx-jre-21-{platform}.tar.zst");
        let jar_bytes = test_agent_jar();
        let jre_bytes = b"fake-jre-archive".to_vec();
        let worker_x64_bytes = linux_native_binary(62);
        let worker_arm_bytes = linux_native_binary(183);

        let registry_json = serde_json::json!({
            "jres": {
                "21": {
                    "version": "21",
                    "platforms": {
                        platform: {
                            "url": format!("offline://{jre_name}"),
                            "sha256": sha256_bytes(&jre_bytes),
                            "size": jre_bytes.len(),
                            "format": "tar_zstd"
                        }
                    }
                }
            },
            "drivers": {
                "h2": {
                    "version": "1.0.0",
                    "label": "H2",
                    "min_app_version": "0.6.33",
                    "jre": "21",
                    "external_driver_required": false,
                    "jar": {
                        "url": format!("offline://{jar_name}"),
                        "sha256": sha256_bytes(&jar_bytes),
                        "size": jar_bytes.len()
                    }
                },
                "sqlite-worker": {
                    "version": "0.1.6",
                    "label": "SQLite SSH Worker",
                    "min_app_version": "0.6.30",
                    "jre": "21",
                    "external_driver_required": false,
                    "native": {
                        "linux-x64": {
                            "url": format!("offline://{worker_x64}"),
                            "sha256": sha256_bytes(&worker_x64_bytes),
                            "size": worker_x64_bytes.len()
                        },
                        "linux-aarch64": {
                            "url": format!("offline://{worker_arm}"),
                            "sha256": sha256_bytes(&worker_arm_bytes),
                            "size": worker_arm_bytes.len()
                        }
                    }
                }
            }
        });
        let registry: AgentRegistry =
            serde_json::from_value(registry_json).expect("web-synthesized registry JSON must deserialize");

        let (_dir, package) = write_offline_zip(
            &registry,
            &[
                (format!("drivers/{jar_name}"), jar_bytes),
                (format!("drivers/{worker_x64}"), worker_x64_bytes),
                (format!("drivers/{worker_arm}"), worker_arm_bytes),
                (format!("jre/{jre_name}"), jre_bytes),
            ],
        );

        let plan = inspect_offline_zip(&package).expect("web-synthesized bundle must pass inspection");
        assert_eq!(plan.driver_keys, vec!["h2".to_string(), SQLITE_WORKER_DRIVER_KEY.to_string()]);
        assert!(plan.includes_jre);

        let manager = test_manager("offline-web-custom-bundle");
        let result = import_offline_zip(&manager, &package, |_| {}).await.unwrap();
        // The fake JRE archive cannot extract (no java executable inside), but
        // that must only surface as an isolated JRE failure — never block the
        // drivers, exactly like a corrupt real-world package.
        assert!(result.failures.iter().all(|failure| failure.is_jre), "unexpected failures: {:?}", result.failures);
        // The worker contributes one entry per remote platform, so it appears twice.
        assert_eq!(
            result.drivers_installed,
            vec!["h2".to_string(), SQLITE_WORKER_DRIVER_KEY.to_string(), SQLITE_WORKER_DRIVER_KEY.to_string()]
        );
        assert!(manager.driver_jar_path("h2").is_file());
        assert!(manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-x64").is_file());
        assert!(manager.driver_native_platform_path(SQLITE_WORKER_DRIVER_KEY, "linux-aarch64").is_file());
        assert_eq!(manager.load_state().installed_drivers.get("h2").map(|d| d.version.as_str()), Some("1.0.0"));
    }
}

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

    fn unique_tmp(name: &str) -> PathBuf {
        std::env::temp_dir().join(format!("dbx-jre-remove-{name}-{}", uuid::Uuid::new_v4()))
    }

    #[test]
    fn remove_returns_ok_when_path_missing() {
        let path = unique_tmp("missing");
        assert!(!path.exists());
        assert!(remove_jre_dir_with_retry(&path).is_ok());
    }

    #[test]
    fn remove_deletes_existing_dir() {
        let dir = unique_tmp("happy");
        std::fs::create_dir_all(dir.join("bin")).unwrap();
        std::fs::write(dir.join("bin").join("java"), b"x").unwrap();
        assert!(dir.exists());
        remove_jre_dir_with_retry(&dir).expect("happy path delete");
        assert!(!dir.exists());
    }

    #[test]
    fn windows_error_message_lists_root_causes_and_path() {
        let path = PathBuf::from("/tmp/dbx-jre-test");
        let err = std::io::Error::new(std::io::ErrorKind::PermissionDenied, "拒绝访问。 (os error 5)");
        let rendered = format_jre_dir_remove_error(&path, &err);
        assert!(rendered.contains(&path.display().to_string()), "missing path: {rendered}");
        assert!(rendered.contains("(original error:"), "missing original error wrapper: {rendered}");
        assert!(rendered.contains("拒绝访问"), "missing original error text: {rendered}");
        if cfg!(windows) {
            assert!(rendered.starts_with("Failed to remove the old JRE directory:"), "wrong prefix: {rendered}");
            assert!(rendered.contains("java process still holds the directory"), "missing process advice: {rendered}");
            assert!(rendered.contains("restart dbx and try again"), "missing restart advice: {rendered}");
        } else {
            // POSIX path: short form, no Windows-specific advice.
            assert!(rendered.contains("Failed to remove the old JRE directory"));
            assert!(!rendered.contains("antivirus"));
        }
    }

    #[test]
    #[cfg(windows)]
    fn stash_old_jre_dir_renames_and_is_unique() {
        let base = unique_tmp("stash-unique");
        std::fs::create_dir_all(&base).unwrap();
        let jre_a = base.join("jre-21");
        std::fs::create_dir_all(&jre_a).unwrap();
        let stash_a = stash_old_jre_dir(&jre_a).expect("first stash");
        assert!(stash_a.exists(), "stash dir should exist after rename");
        assert!(!jre_a.exists(), "original dir should be gone after rename");

        // Recreate original and stash again — name must differ.
        std::fs::create_dir_all(&jre_a).unwrap();
        let stash_b = stash_old_jre_dir(&jre_a).expect("second stash");
        assert_ne!(stash_a, stash_b, "stash names must be unique across calls");

        // Cleanup.
        let _ = std::fs::remove_dir_all(&base);
    }
}